DBass - DBM with associative arrays, file locking and XML records
use DBass; die unless DBass::gestalt (-api => 'xeen'); my $db = 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
try to prevent later versions of the module from breaking preexisting APIs.
This method checks for the existence of an API:
die 'no API neo' unless 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 = 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.
the file permissions mode of the DBM file.
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
This method releases various resources in the DBass object, to allow other processes to access the DBM file:
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).
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:
This method returns record keys:
my @keys = $db->keys;
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.
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.
xeen API is deprecated and provided for backward compatibility only,
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
On platforms other than MacOS, *nix or Windows NT,
flock will probably
cause the module to crash and burn.
The module should be pronounced
xeen API is not named after the IBM alphaWorks
Xeena XML editor.
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 (
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
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.