NAME

Tie::PureDB - Perl extension for pure-db

SYNOPSIS

  use Tie::PureDB;
  my $file = 'foo.db';
  {
      tie my %db, 'Tie::PureDB::Write', "$file.index", "$file.data", $file
          or die "Couldn't create database ($!)";

      $db{createtime} = scalar gmtime;
      $db{$_} = rand($_) for 1..100;

      untie %db;

      tie %db, 'Tie::PureDB::Read', $file
          or die "Couldn't read database ($!)";

      print "This database was created on $db{createtime}\n";
      print " 1 => $db{1}\n 6 => $db{6}\n\n";

      untie %db;
  }
  {
      my $db = Tie::PureDB::Write->new( "$file.index", "$file.data", $file )
          or die "Couldn't create database ($!)";

      $db->puredbw_add( createtime => scalar gmtime );
      $db->add( $_ => rand($_)) for 1..100;

      undef $db;

      $db = Tie::PureDB::Read->($file)
          or die "Couldn't read database ($!)";

      print "This database was created on ",
          $db->read( $db->puredb_find('createtime') ), \n";

      print " 1 => ", $db->FETCH(1) || "EEEK!($!)", "\n";
      print " 1 => ", $db->FETCH(9) || "EEEK!($!)", "\n";

      undef $db;
  }

DESCRIPTION

This is the perl interface to PureDB. If you wanna know what PureDB is, visit the PureDB home page at http://www.pureftpd.org/puredb/ .

Now go read the examples ;)

Tie::PureDB::Write

This is the interface to libpuredb_write.

If you use the tie interface, you can only use it to store values ($db{foo}=1; aka (tied %db)->STORE(foo => 1); ). It is highly reccomended that you use the tie interface.

If you use the function interface, you'll wanna use the following functions.

puredbw_open

Also known as open, or new. It takes 3 arguments: file_index, file_data, file_final.

On success, returns a Tie::PureDB::Write object. On failure, returns nothing while setting $!.

add

Also known as open, or puredbw_add. It takes 2 arguments: key,value.

On success, returns a true value. On failure, returns nothing while setting $!.

CAVEATS(undefined functions)

Don't try to use the following functions, they are not defined (for example: keys %db. See perltie for more info details.).

    # these would require an extension to libpuredb_write, which I ain't ready for
    sub FIRSTKEY(){}
    sub NEXTKEY(){}

    # these are NO-NOs (libpuredb_write don't know this)
    sub FETCH(){}
    sub EXISTS(){}
    sub DELETE(){}
    sub CLEAR(){}

Tie::PureDB::Read

This is the interface to libpuredb_read.

If you use the tie interface, you can only use it to read values (print $db{foo}; aka print (tied %db)->FETCH('foo'); ). It is highly reccomended that you use the tie interface.

If you use the function interface, you'll wanna use the following functions.

puredb_open

Also known as new, or open. It takes 1 arguments: file_final.

On success, returns a Tie::PureDB::Read object. On failure, returns nothing while setting $!.

getsize

Also known as puredb_getsize. Takes 0 arguments. Returns the size of the database in bytes (same number as -s $file).

find

Also known as puredb_find. Takes 1 argument (the key to find), On success, returns offset,length. On failure, returns nothing while setting $!.

read

Also known as puredb_read. Takes 2 arguments (offset,length). On success, returns the value. On failure, returns nothing while setting $!.

**WARNING -- It is highly discouraged that you use read with invalid offsets. Always use those returned by find, or simply use FETCH or the tie interface.

FETCH

A utiliy method. use $db->FETCH('foo') instead of $db->read( $db->find('foo') ); Returns undef on failure.

CAVEATS (undefined functions)

Don't try to use the following functions, they are not defined (for example: keys %db. See perltie for more info details.).

    # these would require an extension to libpuredb_read, which I ain't ready for
    sub FIRSTKEY(){}
    sub NEXTKEY(){}

    # these are NO-NOs (libpuredb_read don't know this)
    sub STORE(){}
    sub DELETE(){}
    sub CLEAR(){}

THREAD SAFETY

AFAIK, this module and the underlying c library do not use globally shared data, and as such, they are "thread-safe".

CAVEATS (The untie() Gotcha)

If you aren't aware of the Gotcha, read about it before even attempting to use this module ;)

The untie Gotcha in perltie.

Memoize

You could use Memoize with this module. All you have to do is add the following lines to your program:

    use Tie::PureDB;
    BEGIN{
        package Tie::PureDB::Read;
        use Memoize();
        Memoize::memoize('puredb_read','puredb_find','FETCH');
        no strict 'refs';
        *read = *puredb_read;
        *find = *puredb_find;
        *EXISTS = *puredb_find;
        package main;
    }
    ## ... rest of your code follows

AUTHOR

D. H. <PodMaster@cpan.org> who is very thankful to tye and the perlmonks, as well as Tim Jenness and Simon Cozens (authors of Extending and Embedding Perl -- http://www.manning.com/jenness/ ).

SEE ALSO

perl, perltie, perldata, AnyDBM_File, DB_File, BerkeleyDB.

cpanm Tie::PureDB

perl -MCPAN -e shell
install Tie::PureDB