NAME

File::Attributes - Manipulate file metadata

VERSION

Version 0.04

SYNOPSIS

    use File::Attributes qw(set_attribute list_attributes get_all_attributes);

    my $file = 'foo.txt';
    set_attribute($file, type     => 'text/plain');
    set_attribute($file, encoding => 'utf8');
    
    my @attributes = list_attributes($file);
    #  @attributes = qw(type encoding)
 
    %attributes = get_attributes($file);
    #  $attributes{type} will be 'text/plain'
    #  $attributes{foo}  will be undefined.

DETAILS

"File::Attributes" is a wrapper around modules in the File::Attributes <http://search.cpan.org/search?query=File%3A%3AAttributes> hierarchy. If you use this module directly (instead of one of the aforementioned decendants), then your attribute manipulations will Just Work, regardless of the underlying filesystem.

Module::Pluggable is used to find all "File::Attributes::" modules that inherit from "File::Attributes::Base" and that are applicable on your system. If it finds one, it uses that. If not, it uses "File::Attributes::Simple", which is bundled with this module and works everywhere.

As of version 0.04, plugins are now set up per-file, not per-system. This means that if you have "File::Attributes::Extended" installed, extended attributes will be used where available, but Simple attributes will be used on files where extended attributes don't work (a FAT filesytem on a Linux machine, for example). Existing simple attributes will be read even if extended attributes are available, but writes will affect only the extended attributes.

This means that you can switch to a better attribute plugin at any time, without losing any old data!

EXPORT

None, by default. Specify the functions that you'd like to use as arguments to the module. If you want everything, specify ":all".

FUNCTIONS

All functions throw an exception on error.

get_attribute($file, $attribute)

Returns the value of attribute $attribute on file $file. If $attribute doesn't exist, returns undefined.

set_attribute($file, $attribute => $value)

Sets attribute $<attribute> on file $file to $value.

get_attributes($file)

Returns a hash of all attributes on $file.

set_attributes($file, %hash)

Sets the attributes named by the keys of %hash to the value contained in %hash. Note that this operation is not atomic -- if setting an individual attribute fails, the attributes on $file may not be the same as before "set_attributes" was called!

unset_attribute($file, $attribute)

Removes the attribute $attribute from $file.

unset_attributes($file, $attribute0, [$attribute1, ...])

Removes each attribute ($attribute0, $attribute1, "...") from $file.

list_attributes($file)

Returns a list of the attributes on $file. Equivalent to (but faster than) "keys get_attributes($file)".

AUTHOR

Jonathan Rockway, "<jrockway at cpan.org>"

BUGS

Please report any bugs or feature requests to RT at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Attributes>.

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.