/ 
FlatFile-DataStore-1.00
River stage zero No dependents
/ FlatFile::DataStore::DBM

NAME

FlatFile::DataStore::DBM - Perl module that implements a flat file data store with a DBM file key access.

SYNOPSYS

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 datastore object

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 (must have a record to update it)

$record->data( "Updating the test record." );
$dshash{ $id } = $record;

# delete it

delete $dshash{ $id };

# -or-

tied(%dshash)->delete({ id => $id, record => $record });

# get its history

my @records = tied(%dshash)->history( $id );

DESCRIPTION

FlatFile::DataStore::DBM implements a tied hash interface to a flat file data store. 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.

Note that record data may be created or updated (i.e., STORE'd) two ways:

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 );
$recore->user( $user_data );
$record = $dshash{ $id } = $record;

Note that 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 in general, all of the public flat file methods are available via the tied object, as illustrated by the history() call in the synopsis.

VERSION

FlatFile::DataStore::DBM version 1.00

Tieing the hash

Accepts hash ref giving values for dir and name.

use Fctnl;
tie my %dshash, 'FlatFile::DataStore::DBM', {
    name        => $name,
    dir         => $dir,
};

To initialize a new data store, pass the URI as the value of the uri parameter, e.g.,

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, e.g.,

Returns a reference to the FlatFile::DataStore::DBM object.