/ 
File-Sticker-4.00
River stage zero No dependents
/ File::Sticker::Scribe

NAME

File::Sticker::Scribe - read, write and standardize meta-data from files

VERSION

version 4.00

SYNOPSIS

use File::Sticker::Scribe;

my $scribe = File::Sticker::Scribe->new(%args);

my $meta = $scribe->read_meta($filename);

$scribe->write_meta(%args);

DESCRIPTION

This will read and write meta-data from files in various formats, and standardize it to a common nomenclature, such as "tags" for things called tags, or Keywords or Subject etc.

The standard nomenclature is:

url

The source URL of this file (ref 'dublincore.source')

creator

The author or artist who created this. (ref 'dublincore.creator')

title

The title of the item. (ref 'dublincore.title')

description

The description of the item. (ref 'dublincore.description')

tags

The item's tags. (ref 'Keywords').

Other fields will be called whatever the user has pre-configured.

DEBUGGING

whoami

Used for debugging info

METHODS

new

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

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

init

Initialize the object. Check if all the required parameters are there.

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

name

The name of the scribe; 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::Scribe::name($class);

priority

The priority of this scribe. Scribes 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 scribe class.

$priority = $self->priority();

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

allow

If this scribe can be used for the given file and the wanted_fields, then this returns true.

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

allowed_file

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

    if ($scribe->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 scribe knows about.

This must be overridden by the specific scribe class.

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

readonly_fields

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

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

writable_fields

Returns the fields which this scribe knows about, which can be written into.

my $writable_fields = $scribe->writable_fields();

read_meta

Read the meta-data from the given file.

This must be overridden by the specific scribe class.

my $meta = $scribe->read_meta($filename);

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.

$scribe->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 scribe class.

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

replace_all_meta

Overwrite the existing meta-data with that given.

$scribe->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.

$scribe->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.

$scribe->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.

$scribe->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 scribe class.

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

BUGS

Please report any bugs or feature requests to the author.