NAME
File::Attribute - read and write file attributes
VERSION
Version 0.01
SYNOPSIS
File::Attribute lets you assign attributes to files. This means that you can easily set metadata for files. Even better, the module looks for attributes recursively. It first checks for an attribute applied to a certain file, then the directory, then the parent directory, etc. This lets you set information for many files in a very efficient way.
An example should clarify this.
use File::Attribute;
my $lang = read_attribute({path=>"/path/to/a/file",
attribute=>"language",
top=>"/path"});Here, we read the "language" attribute for the file /path/to/a/file. This is accomplished by reading a file called /path/to/a/.file.language. If that file doesn't exist, the module tries /path/to/a/.language, and then /path/to/a/.language, then /path/to/.language, and finally, /path/.language. /.language is not tried because the search will not ascend above the (optional) top argument.
If read_attribute encounters a blank file at any stage in the serach, it will terminate the search and return nothing (even if a non-blank file exists below the blank file that was found).
Writing is just as easy:
use File::Attribute;
write_attribute({path=>"/path/to/a/file",
attribute=>"language"},
"en_JP", "engrish");In this example, we create an attribute called "language" that applies to /path/to/a/file. The attribute has two lines; one "en_JP" and the next "engrish". (My apologies to the Japanese.) If path is a directory, the attribute will be a directory-scoped attribute (i.e. applies to files in that directory, and files in all subdirectories).
EXPORT
Both functions are exported by default.
read_attribute
write_attribute
FUNCTIONS
read_attribute
Reads an attribute, as per the decription in SYNOPSIS.
ARGUMENTS
Accepts a single hash reference. Required in the hash are path, the path to the file, and attribute, the name of the attribute to read.
Optionally, you may include top, which limits the scope of the search to all subdirectories of top. read_attribute will die if path is not below top. Creative symlinking is not accounted for here -- if /a is a symlink to /b/a, then /b is not "above" /a. I would be very interested in hearing how this is a problem for you :)
RETURN VALUE
In scalar context, returns the first non-blank line of the attribute file (if one exists). In list context, returns all non-blank lines.
write_attribute
Writes an attribute file that can be read by read_attribute.
ARGUMENTS
Accepts a hash reference followed by one or more lines to save in the attribute file.
The hash must contain two elements, path, and attribute. If path is a file, a file-scoped attribute is written. If path is a directory, a directory-scoped attribute is written.
The remaining arguments are taken to be lines to be written to the attribute file.
RETURN VALUE
Returns the filename of the attribute file. Throws an exception on error.
DIAGNOSTICS
Required argument foo not specified.
The function required an argument named foo, but you didn't supply it.
path does not exist.
The path path passed to the function does not exist.
path is not a valid UNIX path.
You passed a path to the function that isn't valid. (Probably a bug in my code.)
top does not contain path
You passed read_attribute a path that's not contained in top. That makes the specification of top meaningless, which probably isn't what you wanted.
BUGS
Please report any bugs or feature requests to bug-file-attribute@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Attribute. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
AUTHOR
Jonathan T. Rockway, <jon-cpan@jrock.us>
COPYRIGHT & LICENSE
Copyright 2005 Jonathan T. Rockway, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.