NAME
Tie::PureDB - Perl extension for pure-db
SYNOPSIS
use Tie::PureDB;
my $file = 'foo.db';
{
my %db;
tie %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), "\n";
print " 1 => ", $db->FETCH(9), "\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); ).
If you use the function interface, you'll wanna use
new
Also known as open, or puredbw_open. 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'); ).
If you use the function interface, you'll wanna use
new
Also known as open, or puredb_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 $!.
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 ;)
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/ ).