/ 
Tie-PureDB-0.04
River stage zero No dependents
/ Tie::PureDB

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.