The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Tie::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;

 # Specify how many levels of subdirectories should be created
 tie %hash, 'Tie::TextDir', '/some_directory', 'rw', 0775, 2;

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 directory, though. If the directory already exists, the permissions setting will have no effect. The default permissions setting is 0775.

The optional fifth parameter specifies how many levels of subdirectories should be created. For instance, if you specify two levels of subdirectories the key key will be placed under k/ke/key, and the key module under m/mo/module.

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 triggered. 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 construed 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 platform 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.

When working with levels keep in mind that you should be aware of the system case sensitiveness (if you use the keys Foo and foo on a case sensitive system, the files will be placed on two different directories). Also, keep in mind that if you use a key whose length is smaller than the number of levels you might have conflicts. For instance, using two levels, and keys b and bar will result on a file b on the root directory that will prevent b/ba/bar from being created.

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 ALSO

perl(1).