NAME

Keystone::Resolver::Descriptor - a Descriptor in an OpenURL v1.0 ContextObject

SYNOPSIS

 $des = new Keystone::Resolver::Descriptor("rft");
 $des->superdata(ref => "http://some.host/path/entity.kev");
 $des->metadata(aulast => [ "Wedel" ]);
 $ids = $des->superdata("id");
 @authors = $des->metadata("aulast");

DESCRIPTION

A Descriptor is a small data structure containing information describing one of the six OpenURL v1.0 entities (referent, referer, etc.) Each Descriptor has a name, and contains both metadata (author, title, etc.) and what we will call superdata (identifier, descriptor format and suchlike), which are held in two different spaces.

Although this module neither knows nor cares what kind of information is stored in the metadata and superdata hashes, it's worth knowing that the way Keystone Resolver uses this is by storing references to arrays of scalars. In other words, instead of storing author = "taylor", we store author = [ "taylor", "wedel" ].

Three utility methods are provided for application such as Keystone Resolver that use Descriptor objects in this way: metadata1(), superdata1() and push_metadata()

METHODS

new()

 $des = new Keystone::Resolver::Descriptor($name);

Constructs a new Descriptor with the specified name, and with (initially) no metadata or superdata.

name()

Returns the name with which the descriptor was created.

metadata(), superdata()

 $oldfoo = $des->metadata("foo");
 $des->metadata(foo => $newfoo);
 # ...
 $des->metadata(foo => $oldfoo);

These two methods behave the same way, but operate on different data-spaces. Each one returns the value associated with the key whose name is specified in by the first parameter. If a second parameter is also specified, then it becomes the new value associated with that key (although the old value is still returned).

metadata1(), superdata1()

 $des->metadata(foo => [ "bar" ]);
 $res = $des->metadata("foo");
 die if ref($ref) ne "ARRAY";
 $scalar = $des->metadata1("foo");
 die if ref($ref);

metadata1() returns the first element of the array whose reference is stored in a descriptor's metadata space under the specified key. It is a fatal error if the array has zero elements, and a warning is issued if it has more than one.

superdata1() behaves the same but operates on the descriptor's superdata space instead of its metadata space.

metadata_keys(), superdata_keys()

 foreach my $name ($des->metadata_keys()) {
     print $name, " -> ", $des->metadata($name), "\n";
 }

metadata_keys() returns a list of all the keys for which the descriptor has a metadata value. superdata_keys() returns a list of all the keys for which the descriptor has a superdata value.

delete_superdata()

 $des->delete_superdata("ref");
 $oldval = $des->delete_superdata("ref_fmt");

Deletes the named superdata element from the descriptor, returning its old value if any.

There is at present no corresponding delete_metadata().

push_metadata()

 $des->push_metadata(foo => $extraFoo1, $extraFoo2, ...);

To be used only when the metadata keys are list-references. Appends the specified values to the list associated with the specified name. The following two code-fragments are equivalent:

 $des->metadata(foo => []);
 $des->push_metadata(foo => 1);
 $des->push_metadata(foo => 2, 3);

and

 $des->metadata(foo => [ 1 2 ]);
 $des->push_metadata(foo => 3);

There is at present no corresponding push_superdata().

cpanm Keystone::Resolver

perl -MCPAN -e shell
install Keystone::Resolver