DBM::DBass - DBM with associative arrays, file locking and XML records
DBM::DBass
use DBM::DBass; die unless DBM::DBass::gestalt (-api => 'neo'); my $db = DBM::DBass->new ( -api => 'neo', -file => '+<file.dbm', -lock => 'file.lock', -mode => 0644 );
This module provides methods to read, write and delete associative arrays in DBM files, with file locking and XML records.
It uses a named argument -api for class methods new and gestalt to try to prevent later versions of the module from breaking preexisting APIs.
-api
new
gestalt
This method checks for the existence of an API:
die 'no API neo' unless DBM::DBass::gestalt (-api => 'neo');
-api is the calling API to check for. One should use this method only for development or testing, and not in frequently used applications.
This method creates a new DBass object, and should be the first one called:
my $db = DBM::DBass->new ( '-api' => 'neo', '-file' => '+<file.dbm', '-lock' => 'file.lock', '-mode' => 0644 );
-api is the calling API to use. -file is the read/write mode (default is read-only) and DBM filename. -lock is the lock filename. -mode is the file permissions mode of the DBM file.
-file
-lock
-mode
If the DBM file is opened for read-only access, the lock file must preexist, but can be empty. In MacOS, one can create an empty file with SimpleText. In *nix, one can create an empty file with touch:
touch
touch file.lock
This version of the module has APIs xeen and . The xeen API is deprecated and provided for backward compatibility only, and the neo API should be used when possible.
xeen
neo
close
This method releases various resources in the DBass object, to allow other processes to access the DBM file:
$db->close;
Normally this method should not be used, as it renders the object useless for the remainder of the program execution (and is automatically called when the object is destroyed).
delete
This method deletes records from the DBM file:
$db->delete ('-keys' => \@keys); $db->delete ('-keys' => \%keys); $db->delete ('-keys' => $key );
Be careful. It can also delete all records:
$db->delete;
keys
This method returns record keys:
my @keys = $db->keys;
read
This method returns a hash reference pointing to records in the DBM file:
my $smallerhashref = $db->read ('-keys' => \@keys, '-root' => $root); my $smallerhashref = $db->read ('-keys' => \%keys, '-root' => $root); my $smallhashref = $db->read ('-keys' => $keys, '-root' => $root); my $entirehashref = $db->read ('-root' => $root);
-keys are the keys to match against. -root is the XML root tag name used in storing the records.
-keys
-root
write
This method writes key-value pairs to the DBM file:
$db->write (-hash => \%hash, -root => $root);
-hash is the hash reference pointing to the key-value pairs (records). -root is the XML root tag name to use in storing the records.
-hash
The xeen API is deprecated and provided for backward compatibility only, and the neo API should be used when possible. The main reason for the API name change is that the neo record format is significantly different from that of xeen.
On platforms other than MacOS, *nix or Windows NT, flock will probably cause the module to crash and burn.
flock
The module should be pronounced /di'bas/.
/di'bas/
The xeen API is not named after the IBM alphaWorks Xeena XML editor.
Xeena
0.54 2000.01.19 renamed package to DBM::DBass, as per Tim Bunce 0.53 2000.01.11 fixed Makefile.PL (oops!) 0.52 1999.10.30 added check for _OBJ added check for _HASHREF fixed neo_read handling of _UNTAGGED fixed neo_read to check for _HASHREF fixed neo_write to check for _OBJ fixed xeen_delete to check for _OBJ fixed xeen_destroy to check for _OBJ fixed xeen_new die preparation fixed xeen_new to include _UNTAGGED fixed xeen_read handling of _UNTAGGED fixed xeen_read to check for _HASHREF fixed xeen_write to check for _OBJ 0.51 1999.10.26 fixed gestalt for wantarray fixed neo_read to accept hash references as -keys fixed xeen_delete to accept hash references as -keys fixed xeen_read to accept hash references as -keys 0.50 1999.10.06 added neo API (valid XML tags and lists of lists) 0.40 1999.09.20 fixed DBM file locking bug in xeen_destroy fixed DBM file locking bug in xeen_new fixed xeen_delete to accept scalars as -keys fixed xeen_read to accept scalars as -keys
Copyright 1999, 2000 Nguon Hao Ching (spiderboy@spiderboy.net).
spiderboy@spiderboy.net
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Thanks to Tom Christiansen for Perl Cookbook recipe 14.5.
Thanks to Mark-Jason Dominus for the Perl Monger tutorial on file locking.
Thanks to David Harris and Paul Marquess for the recipe bug report.
Thanks to Chris Nandor for perlport.
perlport
Thanks to James Wismer for feedback on the initial, unreleased version.
Thanks to Jay Trolley for her patience and understanding.
Thanks to xeenie for everything else.
To install DBM::DBass, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DBM::DBass
CPAN shell
perl -MCPAN -e shell install DBM::DBass
For more information on module installation, please visit the detailed CPAN module installation guide.