FlatFile::DataStore::DBM - Perl module that implements a flatfile datastore with a DBM file key access.
use Fctnl; use FlatFile::DataStore::DBM; $FlatFile::DataStore::DBM::dbm_package = "SDBM_File"; # the defaults $FlatFile::DataStore::DBM::dbm_parms = [ O_CREAT|O_RDWR, 0666 ]; $FlatFile::DataStore::DBM::dbm_lock_ext = ".dir"; # new object my $obj = tie my %dshash, 'FlatFile::DataStore::DBM', { name => "dsname", dir => "/my/datastore/directory", }; # create a record and retrieve it my $id = "testrec1"; my $record = $dshash{ $id } = { data => "Test record", user => "Test user data" }; # update it $record->data( "Updating the test record." ); $dshash{ $id } = $record; # delete it delete $dshash{ $id }; # get its history my @records = $obj->history( $id );
FlatFile::DataStore::DBM implements a tied hash interface to a flatfile datastore. The hash keys are strings that you provide. These keys do not necessarily have to exist as data in the record.
In the case of delete, you're limited in the tied interface -- you can't supply a "delete record" (one that has information about the delete operation). Instead, it will simply retrieve the existing record and store that as the delete record.
Record data may be created or updated (i.e., STORE'd) three ways:
As a data string (or scalar reference), e.g.,
$record = $dshash{ $id } = $record_data;
As a hash reference, e.g.
$record = $dshash{ $id } = { data => $record_data, user => $user_data };
As a record object (record data and user data gotten from object), e.g.,
$record->data( $record_data ); $record->user( $user_data ); $record = $dshash{ $id } = $record;
In the last line above, the object fetched is not the same as the one given to be stored (it has a different preamble).
FWIW, this module is not a subclass of FlatFile::DataStore. Instead, it is a wrapper, so it's a "has a" relationship rather than an "is a" one. But many of the public flatfile methods are available via the tied object, as illustrated by the history() call in the synopsis.
These methods include
name dir retrieve retrieve_preamble locate_record_data history userdata howmany lastkeynum nextkeynum
Note that create(), update(), and delete() are not included in this list. If a datastore is set up using this module, all updates to its data should use this module. This will keep the keys in sync with the data.
FlatFile::DataStore::DBM version 1.03
Accepts hash ref giving values for dir and name.
dir
name
tie my %dshash, 'FlatFile::DataStore::DBM', { name => $name, dir => $dir, };
To initialize a new datastore, pass the URI as the value of the uri parameter, e.g.,
uri
tie my %dshash, 'FlatFile::DataStore::DBM', { dir => $dir, name => $name, uri => join( ";" => "http://example.com?name=$name", "desc=My%20Data%20Store", "defaults=medium", "user=8-%20-%7E", "recsep=%0A", ), };
(See URI Configuration in FlatFile::DataStore.) Also accepts a userdata parameter, which sets the default user data for this instance.
userdata
Returns a reference to the FlatFile::DataStore::DBM object.
#---------------------------------------------------------------------
Gets the key associated with a record sequence number (keynum). This could be handy if you have a record, but don't have its key in the DBM file, e.g.,
# have a record to update, but forgot its key # (the key isn't necessarily in the record) my $id = tied(%dshash)->get_key( $record->keynum ); $dshash{ $id } = $record;
Gets the record sequence number (keynum) associated with a key. Don't have a good use case yet -- included this method as a complement to get_key().
To install FlatFile::DataStore, copy and paste the appropriate command in to your terminal.
cpanm
cpanm FlatFile::DataStore
CPAN shell
perl -MCPAN -e shell install FlatFile::DataStore
For more information on module installation, please visit the detailed CPAN module installation guide.