TextDir(3) User Contributed Perl Documentation TextDir(3)NAMETie::TextDir - interface to directory of files
SYNOPSIS
use Tie::TextDir;
tie %hash, 'Tie::TextDir', '/some_directory', 'rw'; # Open in read/write mode
$hash{'one'} = "some text"; # Creates file /some_directory/one
# with contents "some text"
untie %hash;
tie %hash, 'Tie::TextDir', '/etc'; # Defaults to read-only mode
print $hash{'passwd'}; # Prints contents of /etc/passwd
# Specify directory permissions explicitly
tie %hash, 'Tie::TextDir', '/some_directory', 'rw', 0775;
DESCRIPTION
The Tie::TextDir module is a TIEHASH interface which lets you tie a
Perl hash to a directory on the filesystem. Each entry in the hash
represents a file in the directory.
To use it, tie a hash to a directory:
tie %hash, "/some_directory", 'rw'; # Open in read/write mode
If you pass 'rw' as the third parameter, you'll be in read/write mode,
and any changes you make to the hash will create, modify, or delete
files in the given directory. If you pass 'ro' (or nothing) as the
third parameter, you'll be in read-only mode, and any changes you make
to the hash won't have any effect in the given directory.
The 'rw' and 'ro' modes are actually just shorthand for
"O_RDWR|O_CREAT" and "O_RDONLY", respectively, as defined by the
"Fcntl" module. You may pass "Fcntl" bitmasks instead of their stringy
names if you like that better. The "O_RDWR" flag means that you may
create or delete files in the directory, and the "O_CREAT" flag means
that if the directory itself doesn't exist "Tie::TextDir" will create
it (or die trying).
An optional fourth parameter specifies the permissions setting that
should be used when creating the tied directory. It doesn't have any
effect at this point on the permissions of the files inside the direc-
tory, though. If the directory already exists, the permissions setting
will have no effect. The default permissions setting is 0775.
ERROR CONDITIONS
If you try to create or delete a file (by storing or deleting an entry
in the tied hash) and the operation fails, a fatal error will be trig-
gered. If you try to read a file and the operation fails, a warning
message will be issued if you have Perl's warning switch turned on.
If these policies don't suit you, let me know and I can probably make
the behavior configurable.
LIMITATIONS
You may not use the empty string, '.', or '..' as a key in a hash,
because they would all cause integrity problems in the directory.
Other than that, "Tie::TextDir" won't try to check for problematic key
names, so exercise some caution (see CAUTIONS). This is to be con-
strued as a feature - it's possible that you might want read-only
access to an entire multi-level tree of files (though this module would
be a pretty weird way to go about it), so I don't prevent it.
If you store a key like "brown/puppies" and the "brown/" directory
doesn't exist, "Tie::TextDir" won't create it for you. On most plat-
form this means the operation will fail.
This module has only been tested on the UNIX platform, and although it
should work just fine on other platforms there may be some issues I
haven't thought of.
CAUTIONS
Strange characters can cause problems when used as the keys in a hash.
For instance, if you accidentally store "../../f" as a key, you'll
probably mess something up. If you knew what you were doing, you're
probably okay. I'd like to add an optional (by default on) "safe" mode
that URL-encodes keys or something similar (I've lost the name of the
person who suggested this, but thanks!), but I haven't done it yet.
AUTHOR
Ken Williams (ken@mathforum.org)
COPYRIGHT
Copyright (c) 1998-2001 Ken Williams. All rights reserved.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSOperl(1).
perl v5.8.8 2003-09-09 TextDir(3)
