Tie::PureDB - Perl extension for pure-db

  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;
  }

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 ;)

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.

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 $!.

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 $!.

Don't try to use the following functions, they are not defined (for example: keys %db. See perltie (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(){}

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.

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 $!.

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

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

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.

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

Don't try to use the following functions, they are not defined (for example: keys %db. See perltie (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(){}

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

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

The untie Gotcha (The untie Gotcha in perltie) in perltie (perltie).

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

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/ ).

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