FlatFile::DataStore::Tiehash - Provides routines that are used only when tie'ing a hash to a datastore.
require FlatFile::DataStore::Tiehash;
(But this is done only in FlatFile/DataStore.pm)
FlatFile::DataStore::Tiehash provides the routines that are used only when tie'ing a hash to a datastore. It isn't a "true" module; it's intended for loading more methods into the FlatFile::DataStore class.
use FlatFile::DataStore; # not FlatFile::DataStore::Tiehash
tie my %dshash, 'FlatFile::DataStore', {
name => "dsname",
dir => "/my/datastore/directory",
};
# create a record (null string key says, "new record")
my $record = $dshash{''} = { data => "Test record", user => "Test user data" };
my $record_number = $record->keynum;
# update it (have to "have" a record to update it)
$record->data( "Updating the test record." );
$dshash{ $record_number } = $record;
# retrieve it
$record = $dshash{ $record_number };
# delete it
delete $dshash{ $record_number };
# -or-
tied(%dshash)->delete( $record );
# test it ... exists is true after a delete
if( $preamble = exists $dshash{ $record_number } ) {
print "Deleted." if $preamble->is_deleted;
}
This module provides the methods that allow you to tie a hash to a data store. The hash keys are integers that range from 0 to $datastore_object->lastkeynum.
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". If you want the "delete record" to contain different information (such as who is deleting it), you must call the non-tied delete() method with the datastore object.
Note that record data may be created or updated (i.e., STORE'd) three ways:
As data string (or scalar reference), e.g.,
$record = $dshash{''} = $record_data;
As a hash reference (so you can supply some user data), e.g.
$record = $dshash{''} = { 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{''} = $record;
Note that in the last example, the object fetched is not the same as the one given to be stored (it has a different preamble).
The above examples use a "null key" convention. When you assign to the null key entry, it creates a new record in the datastore, which adds a new record key sequence number. When you read the null key entry, it retrieves the last record. Thus when you do this:
$record = $dshash{''} = $record_data;
You are creating a new record ($dshash{''} = $record_data), and you are then retrieving the last record ($record = $dshash{''}), which happens to be the record you just created. This null key convention saves you from having to do something like this equivalent code:
my $ds = tied %dshash;
$dshash{ $ds->nextkeynum } = $record_data;
$record = $dshash{ $ds->lastkeynum };
FlatFile::DataStore::Tiehash version 1.03
This module is still in an experimental state. The tests are sparse. When I start using it in production, I'll bump the version to 1.00.
Until then (afterwards, too) please use with care.
Brad Baxter, <bbaxter@cpan.org>
Copyright (C) 2011 by Brad Baxter
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.
