> Does "DBass" mean anything?
Not really, but:
1. It could be mispronounced as DBase.
2. It provides flattening and unflattening of some Perl data
structures to and from XML records - including associative
arrays (hashes).
3. I originally wrote it to support a module I call Halibut.
4. Some of my colleagues might think I'm calling a certain
manager an ass (which I'm not, actually). :)
> Posting the docs would help.
Okey, here they are, verbatim from the POD:
=pod
=head1 NAME
C<DBass> - DBM with associative arrays, file locking and XML records
=head1 SYNOPSIS
use DBass;
die unless DBass::gestalt (-api => 'xeen');
my $db = DBass->new (
-api => 'neo',
-file => '+<file.dbm',
-lock => 'file.lock',
-mode => 0644
);
=head1 DESCRIPTION
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 C<-api> for class methods C<new> and C<gestalt> to
try to prevent later versions of the module from breaking preexisting APIs.
=head1 METHODS
=over 4
=item C<gestalt>
This method checks for the existence of an API:
die 'no API neo' unless DBass::gestalt (-api => 'neo');
C<-api> is the calling API to check for. One should use this method only
for development or testing, and not in frequently used applications.
=item C<new>
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
);
C<-api> is the calling API to use. C<-file> is the read/write mode (default
is read-only) and DBM filename. C<-lock> is the lock filename. C<-mode> is
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 C<touch>:
touch file.lock
This version of the module has APIs C<xeen> and X<neo>. The C<xeen> API is
deprecated and provided for backward compatibility only, and the C<neo> API
should be used when possible.
=item C<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).
=item C<delete>
This method deletes records from the DBM file:
$db->delete ('-keys' => \@keys);
$db->delete ('-keys' => \%keys);
$db->delete ('-keys' => $key );
B<Be careful.> It can also delete all records:
$db->delete;
=item C<keys>
This method returns record keys:
my @keys = $db->keys;
=item C<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);
C<-keys> are the keys to match against. C<-root> is the XML root tag name
used in storing the records.
=item C<write>
This method writes key-value pairs to the DBM file:
$db->write (-hash => \%hash, -root => $root);
C<-hash> is the hash reference pointing to the key-value pairs (records).
C<-root> is the XML root tag name to use in storing the records.
=back
=head1 KNOWN ISSUES
The C<xeen> API is deprecated and provided for backward compatibility only,
and the C<neo> API should be used when possible. The main reason for the
API name change is that the C<neo> record format is significantly different
from that of C<xeen>.
On platforms other than MacOS, *nix or Windows NT, C<flock> will probably
cause the module to crash and burn.
The module should be pronounced C</di'bas/>.
The C<xeen> API is not named after the IBM alphaWorks C<Xeena> XML editor.
=head1 CHANGES
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
=head1 AUTHOR
Copyright 1999, 2000 Nguon Hao Ching (C<[EMAIL PROTECTED]>).
=head1 CREDITS
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 C<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.
=cut
