NAME

Metadata::Base - base class for metadata

SYNOPSIS

package Metadata::FOO

use vars(@ISA);
...
@ISA=qw(Metadata::Base);
...

DESCRIPTION

Metadata:Base class - the core functionality for handling metadata.

CONSTRUCTOR

new [OPTIONS]

Create a new Metadata object with an optional hash of options to describe the metadata characteristics. Currently only the following can be set:

DEBUG

Set if debugging should be enabled from creation. This can also be set and read by the debug method below. If this is not defined, it is set to the current class debugging state which can be read from the class method debug described below.

ORDERED

Set if the metadata elements are ordered

COPY CONSTRUCTOR

clone

Create a new identical Metadata object from this one.

CLASS METHODS

debug [VALUE]

If VALUE is given, sets the debugging state of this class and returns the old state. Otherwise returns the current debugging state.

seconds_to_iso8601 SECONDS

Convert the SECONDS value to (subset of) ISO-8601 format YYYY-MM-DDThh:mm:SSZ representing the GMT/UTC value.

iso8601_to_seconds VALUE

Convert 6 ISO-8601 subset formats to a seconds value. The 6 formats are those proposed for the Dublin Core date use:

YYYY
YYYY-MM
YYYY-MM-DD
YYYY-MM-DDThh:mm
YYYY-MM-DDThh:mm:ssTZ
YYYY-MM-DDThh:mm:ss.ssTZ

where TZ can be 'Z', +hh:mm or -hh:mm

NOTE: This method rounds towards the start of the period (it should really return two values for start and end).

METHODS

debug [VALUE]

If VALUE is given, sets the debugging state of this object and returns the old state. Otherwise returns the current debugging state. The default debugging state is determined by the class debug state.

set ELEMENT, VALUE, [INDEX]

Set element ELEMENT to VALUE. If VALUE is an array reference, the existing array is used to as all the existing sub-values. Otherwise if INDEX is given, sets the particular sub-value of ELEMENT, otherwise appends to the end of the existing list of sub-values for ELEMENT.

get ELEMENT, [INDEX]

Return the contents of the given ELEMENT. In an array context returns the sub-values as an array, in a scalar context they are all returned separated by spaces. If INDEX is given, returns the value of the given sub-value.

delete ELEMENT, [INDEX}

Delete the given ELEMENT. If an INDEX is given, remove just that sub-value.

exists ELEMENT, [INDEX]

Returns a defined value if the given ELEMENT and/or sub-value INDEX exists.

size [ELEMENT]

Returns number of elements with no argument or the number of subvalues for the given ELEMENT or undef if ELEMENT does not exist.

elements

Return a list of the elements (in the correct order if there is one).

order [ORDER]

If ORDER is given, sets that as the order of the elements and returns the old order list. Otherwise, returns the current order of the elements. If the elements are not ordered, returns undef.

validate ELEMENT, VALUE, [INDEX]

This method is intended to be overriden by subclasses. It is called when a element value is being set. The method should return either a list of ELEMENT, VALUE and INDEX values to use or an undefined value in which case no element will be set.

validate_elements ELEMENT, [INDEX]

This method is intended to be overriden by subclasses. It is called when a element and/or index is being read. The method should return a list of ELEMENT and INDEX values to use.

as_string =item format

Returns a string representing the metadata, suitable for storing (in a text file). This is different from the pack method because this value is meant to be the native encoding format of the metadata, usually human readable, wheras pack uses the minimum space.

pack

Return a packed string representing the metadata format. This can be used with unpack to restore the values.

unpack VALUE

Initialise the metadata from the packed VALUE which must be the value made by the pack method.

read HANDLE

Reads from the given file handle and initialises the metadata elements. Returns undef if end of file is seen.

write HANDLE

Write to the given file handle a formatted version of this metadata format. Likely to use format in most implementations.

reset

Reset the metadata object to the default ones (including any passed with the constructor) and then do a clear.

clear

Remove any stored elements in this metadata object. This can be used in conjuction with read to prevent the overhead of many new operations when reading metadata objects from files.

get_date_as_seconds ELEMENT

Assuming ELEMENT is stored in a date format, returns the number of seconds since 1st January 1970.

set_date_as_seconds ELEMENT, VALUE

Set ELEMENT encoded as a date corresponding to VALUE which is the number of seconds since 1st January 1970.

AUTHOR

By Dave Beckett - http://purl.org/net/dajobe/

COPYRIGHT

Copyright (C) 1997-2001 Dave Beckett - http://purl.org/net/dajobe/ All rights reserved.

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