I can't see any particular distinguishing feature so DBM::DBass
is fine by me.
Tim.
On Fri, Jan 14, 2000 at 04:11:56PM -0500, N. Hao Ching wrote:
> > 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
