NAME

File::Sticker::Writer - write and standardize meta-data from files

VERSION

version 3.0101

SYNOPSIS

    use File::Sticker::Writer;

    my $writer = File::Sticker::Writer->new(%args);

    $writer->write_meta(%args);

DESCRIPTION

This will write meta-data from files in various formats, and standardize it to a common nomenclature.

DEBUGGING

whoami

Used for debugging info

METHODS

new

Create a new object, setting global values for the object.

    my $obj = File::Sticker::Writer->new();

init

Initialize the object. Set which fields you are interested in ('wanted_fields').

    $writer->init(wanted_fields=>{title=>'TEXT',count=>'NUMBER',tags=>'MULTI'});

name

The name of the writer; this is basically the last component of the module name. This works as either a class function or a method.

$name = $self->name();

$name = File::Sticker::Writer::name($class);

priority

The priority of this writer. Writers with higher priority get tried first. This is useful where there may be more than one possible meta-data format for a file, such as EXIF versus XATTR.

This works as either a class function or a method.

This must be overridden by the specific writer class.

$priority = $self->priority();

$priority = File::Sticker::Writer::priority($class);

allow

If this writer can be used for the given file, and the wanted_fields then this returns true. Returns false if there are no 'wanted_fields'!

    if ($writer->allow($file))
    {
        ....
    }

allowed_file

If this writer can be used for the given file, then this returns true. This must be overridden by the specific writer class.

    if ($writer->allowed_file($file))
    {
        ....
    }

allowed_fields

If this writer can be used for the known and wanted fields, then this returns true. By default, if there are no wanted_fields, this returns false. (But this may be overridden by subclasses)

    if ($writer->allowed_fields())
    {
        ....
    }

known_fields

Returns the fields which this writer knows about.

This must be overridden by the specific writer class.

    my $known_fields = $writer->known_fields();

readonly_fields

Returns the fields which this writer knows about, which can't be overwritten, but are allowed to be "wanted" fields. Things like file-size etc.

This must be overridden by the specific writer class.

    my $readonly_fields = $writer->readonly_fields();

add_field_to_file

Adds a field to a file, taking account of whether it is a multi-value field or not. This requires the old meta-data for the file to be passed in.

    $writer->add_field_to_file(filename=>$filename,
        field=>$field,
        value=>$value,
        old_meta=>\%meta);

delete_field_from_file

Completely remove the given field. For multi-value fields, it removes ALL the values.

This must be overridden by the specific writer class.

    $writer->delete_field_from_file(filename=>$filename,field=>$field);

replace_all_meta

Overwrite the existing meta-data with that given.

    $writer->replace_all_meta(filename=>$filename,meta=>\%meta);

Helper Functions

Private interface.

update_multival_field

A multi-valued field could have individual values added or removed from it. This expects a comma-separated list of individual values, prefixed with an operation: '+' or nothing -- add the values '-' -- remove the values '=' -- replace the values

This also needs to know the existing values of the multi-valued field. The old values are either a reference to an array, or a string with comma-separated values.

    $writer->update_multival_field(filename=>$filename,
        field=>$field_name,
        value=>$value,
        old_vals=>$old_vals);

add_multival_to_file

Add a multi-valued field to the file. Needs to know the existing values of the multi-valued field. The old values are either a reference to an array, or a string with comma-separated values.

    $writer->add_multival_to_file(filename=>$filename,
        field=>$field_name,
        value=>$value,
        old_vals=>$old_vals);

delete_multival_from_file

Remove one value of a multi-valued field. Needs to know the existing values of the multi-valued field. The old values are either a reference to an array, or a string with comma-separated values.

    $writer->delete_multival_from_file(filename=>$filename,
        value=>$value,
        field=>$field_name,
        old_vals=>$old_vals);

replace_one_field

Overwrite the given field. This does no checking.

This must be overridden by the specific writer class.

    $writer->replace_one_field(filename=>$filename,field=>$field,value=>$value);

BUGS

Please report any bugs or feature requests to the author.

cpanm File::Sticker

perl -MCPAN -e shell
install File::Sticker