NAME

FlatFile::DataStore - Perl module that implements a flat file data store.

SYNOPSYS

use FlatFile::DataStore;

# new datastore object

my $dir  = "/my/datastore/area";
my $name = "dsname";
my $ds   = FlatFile::DataStore->new( { dir => $dir, name => $name } );

# create a record

my $record_data = "This is a test record.";
my $user_data   = "Test1";
my $record = $ds->create( $record_data, $user_data );
my $record_number = $record->keynum;

# retrieve it

$record = $ds->retrieve( $record_number );

# update it

$record->data( "Updating the test record." );
$record = $ds->update( $record );

# delete it

$record = $ds->delete( $record );

# get its history

my @records = $ds->history( $record_number );

DESCRIPTION

FlatFile::DataStore implements a simple flat file data store. When you create (store) a new record, it is appended to the flat file. When you update an existing record, the existing entry in the flat file is flagged as updated, and the updated record is appended to the flat file. When you delete a record, the existing entry is flagged as deleted, and a deleted record is appended to the flat file.

The result is that all versions of a record are retained in the data store, and running a history will return all of them. Another result is that each record in the data store represents a transaction: create, update, or delete.

Methods support the following actions:

- create
- retrieve
- update
- delete
- history
- iterate (over all transactions in the data files) (TODO)

Scripts supplied in the distribution perform:

- validation of a data store
- migration of data store records to newly configured data store
- comparison of pre-migration and post-migration data stores

There is more general discussion and tutorials about this module in FlatFile::DataStore::Tutorial.

VERSION

FlatFile::DataStore version 0.05

CLASS METHODS

FlatFile::DataStore->new();

Constructs a new FlatFile::DataStore object.

Accepts hash ref giving values for dir and name.

my $ds = FlatFile::DataStore->new( { dir => $dir, name => $name } );

Returns a reference to the FlatFile::DataStore object.

OBJECT METHODS, Record Processing (CRUD)

create( $record_data[, $user_data] )

Creates a record. The parm $record_data may be one of

- data string
- scalar reference (to the data string)
- FlatFile::DataStore::Record object

The parm $user_data may be omitted if $record_data is an object, in which case the user data will be gotten from it.

Returns a Flatfile::DataStore::Record object.

Note: the record data (but not user data) is stored in the FF::DS::Record object as a scalar reference. This is done for efficiency in the cases where the record data may be very large. Likewise, the first parm to create() is allowed to be a scalar reference for the same reason.

retrieve( $num[, $pos] )

Retrieves a record. The parm $num may be one of

- a key number, i.e., record sequence number
- a file number

The parm $pos is required if $num is a file number.

Returns a Flatfile::DataStore::Record object.

update( $object_or_string[, $record_data][, $user_data] )

Updates a record. The parm $object_or_string may be one of:

- FlatFile::DataStore::Record object
- FlatFile::DataStore::Preamble object
- Preamble string

The parms $record_data and $user_data may be omitted only if $object_or_string is a FF::DS::Record object, in which case the record and user data will be gotten from it.

Returns a Flatfile::DataStore::Record object.

delete( $object_or_string[, $record_data][, $user_data] )

Deletes a record. The parm $object_or_string may be one of:

- FlatFile::DataStore::Record object
- FlatFile::DataStore::Preamble object
- Preamble string

The parms $record_data and $user_data may be omitted only if $object_or_string is a FF::DS::Record object, in which case the record and user data will be gotten from it.

Returns a Flatfile::DataStore::Record object.

history( $keynum )

Retrieves a record's history. The parm $keynum is always a key number, i.e., a record sequence number.

Returns an array of FlatFile::DataStore::Record objects.

The first element of this array is the current record. The last element is the original record. That is, the array is in reverse chronological order.

OBJECT METHODS, Accessors

$ds->specs( [$omap] )

Sets and returns the specs attribute value if $omap is given, otherwise just returns the value.

An 'omap' is an ordered hash as defined in

http://yaml.org/type/omap.html

That is, it's an array of single-key hashes. This ordered hash contains the specifications for constructing and parsing a record preamble as defined in the name.uri file.

$ds->dir( [$dir] )

Sets and returns the dir attribute value if $dir is given, otherwise just returns the value.

If $dir is given, the directory must already exist.

Preamble accessors

The following methods set and return their respective attribute values if $value is given. Otherwise, they just return the value.

$ds->indicator( [$value] ); # from uri (length-characters)
$ds->date(      [$value] ); # from uri (length-format)
$ds->transnum(  [$value] ); # from uri (length-base)
$ds->keynum(    [$value] ); # from uri (length-base)
$ds->reclen(    [$value] ); # from uri (length-base)
$ds->thisfnum(  [$value] ); # from uri (length-base)
$ds->thisseek(  [$value] ); # from uri (length-base)
$ds->prevfnum(  [$value] ); # from uri (length-base)
$ds->prevseek(  [$value] ); # from uri (length-base)
$ds->nextfnum(  [$value] ); # from uri (length-base)
$ds->nextseek(  [$value] ); # from uri (length-base)
$ds->user(      [$value] ); # from uri (length-characters)

Other accessors

$ds->name(        [$value] ); # from uri, name of data store
$ds->desc(        [$value] ); # from uri, description of data store
$ds->recsep(      [$value] ); # from uri (character(s))
$ds->uri(         [$value] ); # full uri as is
$ds->preamblelen( [$value] ); # length of full preamble string
$ds->toclen(      [$value] ); # length of toc entry
$ds->keylen(      [$value] ); # length of stored keynum
$ds->keybase(     [$value] ); # base of stored keynum
$ds->translen(    [$value] ); # length of stored transaction number
$ds->transbase(   [$value] ); # base of stored trancation number
$ds->fnumlen(     [$value] ); # length of stored file number
$ds->fnumbase(    [$value] ); # base of stored file number
$ds->dateformat(  [$value] ); # format from uri
$ds->regx(        [$value] ); # capturing regx for preamble string
$ds->crud(        [$value] ); # hash ref, e.g.,

    {
       create => '+',
       oldupd => '#',
       update => '=',
       olddel => '*',
       delete => '-'
    }

(translates logical actions into their symbolic indicators)

Optional accessors

$ds->dirmax(  [$value] ); # maximum files in a directory
$ds->dirlev(  [$value] ); # number of directory levels
$ds->tocmax(  [$value] ); # maximum toc entries
$ds->keymax(  [$value] ); # maximum key entries
$ds->datamax( [$value] ); # maximum bytes in a data file

If no dirmax, directories will keep being added to.

If no dirlev, toc, key, and data files will reside in top-level directory. If dirmax given, dirlev defaults to 1.

If no tocmax, there will be only one toc file, which will grow indefinitely.

If no keymax, there will be only one key file, which will grow indefinitely.

If no datamax, the length and number base of the seek position numbers will determine the maximum size for the data files.

OBJECT METHODS, UTILITARIAN

TODO: more pod here ...

howmany( [$regx] )

Returns count of records whose indicators match regx, e.g.,

$self->howmany( qr/create|update/ );
$self->howmany( qr/delete/ );
$self->howmany( qr/oldupd|olddel/ );

If no regx, howmany() counts creates minus deletes (which should be the number of undeleted records in the datastore).

CAVEATS

This module is still in an experimental state. The tests and pod are sparse. When I start using it in production, I'll up the version to 1.00.

Until then (afterwards, too) please use with care.

TODO

- iteration function
- cgi to analyze data store configuation (for uri to point to)
- more tests
- more pod
- split Tutorial.pm into Tutorial.pm and FMTEYEWTK.pm
- make Tutorial.pm a real tutorial

AUTHOR

Brad Baxter, <bbaxter@cpan.org>

COPYRIGHT AND LICENSE

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.

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSYS

DESCRIPTION

VERSION

CLASS METHODS

FlatFile::DataStore->new();

OBJECT METHODS, Record Processing (CRUD)

create( $record_data[, $user_data] )

retrieve( $num[, $pos] )

update( $object_or_string[, $record_data][, $user_data] )

delete( $object_or_string[, $record_data][, $user_data] )

history( $keynum )

OBJECT METHODS, Accessors

$ds->specs( [$omap] )

$ds->dir( [$dir] )

Preamble accessors

Other accessors

Optional accessors

OBJECT METHODS, UTILITARIAN

howmany( [$regx] )

CAVEATS

TODO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions