NAME

FlatFile::DataStore::DBM - Perl module that implements a flatfile datastore 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 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 );

DESCRIPTION

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.

VERSION

FlatFile::DataStore::DBM version 1.03

DESCRIPTION

Tieing the hash

Accepts hash ref giving values for dir and 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.,

    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.

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

Object Methods

#---------------------------------------------------------------------

get_key( $keynum );

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;

get_keynum( $key );

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().

cpanm FlatFile::DataStore

perl -MCPAN -e shell
install FlatFile::DataStore