Tie::PerlFiles - interface to directory of eval-able datafiles
use Tie::PerlFiles;
# tie hash to files in /data/dir, using read/write mode, # with common lockfile /my/lockfile tie (%hash, 'Tie::PerlFiles', '/data/dir', 'rw', '/my/lockfile');
# create /data/dir/scale containing a scalar variable with the
# data 'one two three'
$hash{'scale'} = 'one two three';
# create a blessed, complex data item
$ref = [ 'one', 'two', { 'a' => 10, 'b' => 20 } ];
bless $ref, "Goober";
# save the complex data item using locking
tied(%hash)->lock();
$hash{'complex'} = $ref;
tied(%hash)->unlock();
# finished untie %hash;
This module provides the ability to tie a directory of eval-able text files to a hash variable. The module uses Data::Dumper to create the datafiles, which allows you to store almost any complex data
structure as a hash value while preserving the structure.
Tie::PerlFiles includes a simple caching mechanism. By default, the last 25 key-value pairs are stored in memory. The cache automatically removes the oldest key-value pairs when the space is needed for new data.
Tie::PerlFiles also supports a simple file locking mechanism. If you provide the name of a
lockfile, you can call a lock() functions on the tied hash before making modifications, to ensure exclusive
access.
This ties the %hash variable to the files contained in the directory data-dir. mode should be 'rw' for read/write access, or anything else for read-only
access. lockfile should be the name of a scratch file to be used for locking, if you plan to
use the included lock() and unlock() functions.
Use this function to set the DEBUG parameter to value. Debugging messages are reported for any non-zero value. If called with no parameters, this function returns the current DEBUG value.
Use this function to set the STACKSIZE parameter to value. This parameter is the number of key-value pairs that are stored in the memory cache by this module. If you set this value below the current usage of the cache, the oldest entries will be cleared from the cache. If called with no parameters, this function returns the current STACKSIZE value.
Use this function to set the CLOBBER parameter to value. The parameter sets the access mode to read-only (CLOBBER=0) or read-write (CLOBBER=1). If called with no parameters, this function returns the current CLOBBER value.
Use this function to wait for and create an exclusive lock on the provided lockfile. The module will open the given lockfile for writing and then wait to
establish a lock using flock(). The lockfile
must be provided when the has is tied, and the file must be writable by the
process, or the lock() will fail.
Use this function to remove the lock created by the lock()
function, and to close the lockfile.
Use this function to remove key-value pairs from the memory cache. If a key is provided, then that key-value pair will be removed from the cache. If no key is provided, then entire cache will be cleared.
Keys can have any non-null values. All keys are HTML-encoded before used as filenames to avoid dangerous misinterpretation of the key as a directory path. (i.e. the key '../../etc/passwd' could not be used to try to access etc/passwd from a directory above the data directory.) Null key values are not supported.
Multiple hashes can be tied to this module at the same time. The DEBUG and STACKSIZE values are global to this module, so any changes will affect each of the tied hashes, not just the one calling the change.
Be aware of the fact that this module calls eval() on the datafiles that it reads. You must take the necessary precautions to
ensure the datafiles cannot be compromised, lest someone leave you code
that could damage your program.
Charles Brabec (brabec@ncsu.edu / brabec@aitcom.net)
Version 1.0 22-June-1999
Copyright (c) 1999 Charles Brabec. All rights reserved.
This library is free software; you can redistibute it and/or modify it under the same terms as Perl itself.
perl(1), Data::Dumper