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 ($!)"
;
"This database was created on $db{createtime}\n"
;
" 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 ($!)"
;
"This database was created on "
,
$db
->
read
(
$db
->puredb_find(
'createtime'
) ), \n";
" 1 => "
,
$db
->FETCH(1) ||
"EEEK!($!)"
,
"\n"
;
" 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 ;)
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{
Memoize::memoize(
'puredb_read'
,
'puredb_find'
,
'FETCH'
);
no
strict
'refs'
;
*read
=
*puredb_read
;
*find
=
*puredb_find
;
*EXISTS
=
*puredb_find
;
}
## ... 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/ ).