/ 
Tie-Persistent-0.901
River stage zero No dependents
/ Tie::Persistent

NAME

Tie::Persistent - persistent data structures via tie

SYNOPSIS

use Tie::Persistent;

tie %DB, 'Tie::Persistent', 'file', 'rw'; # read data from 'file'

# now create/add/modify database
...

untie %DB;			# stores data back into 'file'

tie %ReadOnly, 'Tie::Persistent', 'file';
foreach (keys %ReadOnly) {
  print "$_ => $ReadOnly{$_}\n";
}

DESCRIPTION

The Persistent package makes working with persistent data real easy by using the tie interface.

It works by storing data contained in a variable into a file (not unlike a database). The primary advantage is speed, as the whole datastructure is kept in memory (which is also a limitation), and, of course, that you can use arbitrary data structures inside the variable (unlike DB_File).

If you want to make an arbitrary object persistent, just store its ref in a scalar tied to 'Tie::Persistent'.

Beware: not every data structure or object can be made persistent. For example, it may not contain GLOB or CODE refs, as these are not really dumpable (yet?).

Also, it works only for variables, you cannot use it for file handles. [A persistent file handle? Hmmm... Hmmm! Let me think about it. I have a vague idea, I'll have to do some unconscious work on...]

PARAMETERS

tie %Hash, 'Tie::Persistent', file, mode, other...;

tie @Array, 'Tie::Persistent', file, mode, other...;

tie $Scalar, 'Tie::Persistent', file, mode, other...;

file

Filename to store the data in. No naming convention is enforced, but I personally use the suffix 'pdb' for "Perl Data Base" (or "Persistent Data Base"?). No file locking is done; see the section on locking below.

mode (optional)

Same as mode for POSIX fopen() or IO::File::open. Basically a combination of 'r', 'w', 'a' and '+'. Semantics:

'r' .... read only. Modifications in the data are not stored back
         into the file. A non-existing file gives an error. This is
         the default if no mode is given.

'rw' ... read/write. Modifications are stored back, if the file does
         not exist, it is created.

'w' .... write only. The file is not read, the variable starts out empty.

'a', '+' ... append. Same as 'w', but creates numbered backup files.

'ra', 'r+' ... Same as 'rw', but creates numbered backup files.

When some kind of write access is specified, a backup file of the old dataset is always created. [You'll thank me for that, believe me.] The reason is simple: when you tie a variable read-write (the contents get restored from the file), and your program isn't fully debugged yet, it may die in the middle of some modifications, but the data will still be written back to the file, possibly leaving them inconsistent. Then you always have at least the previous version that you can restore from.

The default backup filenames follow the Emacs notation, i.e. a '~' is appended; for numbered backup files (specified as 'a' or '+'), an additional number and a '~' is appended.

For a file 'data.pdb', the normal backup file would be 'data.pdb~' and the numbered backup files would be 'data.pdb~1~', 'data.pdb~2~' and so on. The latest backup file is the one with the highest number. The backup filename format can be overridden, see below.

other (optional, experimental)

This can be a reference to another (possibly tied) variable or a name of another tieable package.

If a ref is given, it is used internally to store the variable data instead of an anonymous variable ref. This allows to make other tied datastructures persistent, e.g. you could first tie a hash to Tie::IxHash to make it order-preserving and then give it to Tie::Persistent to make it persistent.

A plain name is used to create this tied variable internally. Trailing arguments are passed to the other tieable package.

Example:

tie %h, 'Tie::Persistent', 'file', 'rw', 'Tie::IxHash';

or

tie %ixh, 'Tie::IxHash';
tie %ph,  'Tie::Persistent', 'file', 'w', \%ixh;
# you can now use %ixh as an alias for %ph

NOTE: This is an experimental feature. It may or may not work with other Tie:: packages. I have only tested it with 'Tie::IxHash'. Please report success or failure.

LOCKING

The data file is not automatically locked. Locking has to be done outside of the package. I recommend using a module like 'Lockfile::Simple' for that.

There are typical two scenarios for locking: you either lock just the 'tie' and/or 'untie' calls, but not the data manipulation, or you lock the whole 'tie' - modify data - 'untie' sequence.

CONFIGURATION VARIABLES

$Tie::Persistent::Readable controls which format to use to store the data inside the file. 'false' means to use 'Storable', which is faster (and the default), 'true' means to use 'Data::Dumper', which is slower but much more readable and thus meant for debugging. This only influences the way the datastructure is written, format detection on read is automatic.

$Tie::Persistent::BackupFile points to a sub that determines the backup filename format. It gets the filename as $_[0] and returns the backup filename. The default is

sub { "$_[0]~"; }

which is the Emacs backup format. For NT, you might want to change this to

sub { "$_[0].bak"; }

or something.

$Tie::Persistent::NumberedBackupFile points to a sub that determines the numbered backup filename format. It gets the filename and a number as $_[0] and $_[1] respectively and returns the backup filename. The default is

sub { "$_[0]~$_[1]~"; }

which is the extended Emacs backup format.

NOTES

There is a module called 'Class::Eroot' that intends to do the same thing but uses a more difficult interface (and also is rather old, not that this is a bad thing per se), so I think my module could be of some use.

'Tie::Persistent' uses 'Storable' and 'Data::Dumper' internally, so these must be installed.

For testing, I use 'Tie::IxHash', but 'make test' still does some tests if it is not installed.

BUGS

Numbered backupfile creation might have problems if the filename contains the first six digits of the speed of light (in m/s).

All other bugs, please tell me!

AUTHOR

Roland Giersig <Roland.Giersig@bigfoot.com>

COPYRIGHT

Copyright (c) 1999 Roland Giersig. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Storable, Data::Dumper.