NAME

XMLNews::Meta - A module for reading and writing XMLNews metadata files.

SYNOPSIS

  use XMLNews::Meta;

  my $namespace = "http://www.xmlnews.org/namespaces/meta#";

				# Create a Meta object.
  my $meta = new XMLNews::Meta();

				# Read in the metadata file.
  $meta->importRDF("data.rdf");

				# Look up a singleton value.
  my $expireTime = $meta->getValue($namespace, "expireTime");

				# Add a new value to a property.
  $meta->addValue($namespace, "companyCode", "WAVO");

				# Write the metadata back out.
  $meta->exportRDF("data.rdf");

DESCRIPTION

NOTE: This module requires the XML::Parser module, version 2.19 or higher.

WARNING: This module is not re-entrant or thread-safe due to the use of static variables while importing XML.

The XMLNews::Meta module handles the import, export, and programmatic manipulation of metadata for XMLNews resources. You can read or write a metadata file using a single method call, and can easily add or remove values.

Traditionally, resource files consist of simple pairs of the form

NAME = VALUE

XMLNews metadata, which is based on the W3C's Resource Description Format (RDF), allows richer metadata in two ways:

1. Property names are partitioned into namespaces, so that two different providers can use the same property name without fear of collision (a namespaces is simply a URI (URL or URN); following RDF practice, the URI should end with the fragment separator "#". To look up a property, you always need to use both the namespace and the property name:

     $xn_ns = "http://www.xmlnews.org/namespaces/meta#";
   
   				# Use getValue only for 
   				# singleton values!!!
     $title = $meta->getValue($xn_ns, "title");
     $creator = $meta->getValue($xn_ns, "creator");

2. The same property can have more than one value, which the getValues method will deliver as an array:

   $xn_ns = "http://www.xmlnews.org/namespaces/meta#";
   @companyCodes = $meta->getValues($xn_ns, 'companyCodes');

METHODS

new()

Create a new (empty) metadata collection:

use XMLNews::Meta;
my $meta = new XMLNews::Meta();

Once you have created the collection, you can add values manually using the addValue() method, or import one or more files into the collection using the importRDF() method.

importRDF(INPUT)

Read an RDF file from the IO::Handle input stream provided, and add its properties to this metadata collection:

$meta->importRDF($handle);

If INPUT is a string, it will be treated as a file name; otherwise, it will be treated as an instance of IO::Handle.

Note that duplicate properties will not be filtered out, so it is possible to have the same property with the same value more than once. Importing a file does not remove any properties already in the collection.

exportRDF(OUTPUT)

Export all of the properties in the collection to an IO::Handle output stream of some sort:

$meta->exportRDF($output);

If OUTPUT is a string, it will be treated as a file name; otherwise, it will be treated as an instance of IO::Handle.

The XML::Meta module will create its own namespace prefixes for the different namespaces in the document, but the namespaces themselves will not be changed.

getValues(NAMESPACE, PROPERTY)

Return all of the values for a property in a namespace as an array. If the property does not exist, return an empty array:

my $namespace = "http://www.xmlnews.org/namespaces/meta#";
my @people = $meta->getValues($namespace, 'personName');
foreach $person (@people) {
  print "This resource mentions $person\n";
}

Note that it is always necessary to provide a namespace as well as a property name; the property 'personName' might have a different meaning in another namespace.

(When you know for certain that a property will never have more than one value, you can use the getValue() method instead to avoid dealing with an array.)

getValue(NAMESPACE, PROPERTY)

Return a single value (or undef) for a property in a namespace:

my $resourceId = $meta->getValue($namespace, 'resourceId');

This method is convenient for properties (like XMLNews's 'resourceId') which should never have more than one value.

NOTE: If there is more than one value present for the resource, the getValue() method will croak().

hasValue(NAMESPACE, PROPERTY)

Return true if the specified property has one or more values, and false otherwise:

unless ($meta->hasValue($namespace, 'provider')) {
  print "No provider information available\n";
}

getNamespaces()

Return an array containing all of the namespaces used in the metadata collection:

my @namespaces = $meta->getNamespaces();

Each namespace is a URI (URL or URN) represented as a string.

getProperties(NAMESPACE)

Return an array containing all of the properties defined for a specific namespace in the metadata collection:

my @properties = $meta->getProperties($namespace);

If the namespace does not exist, this method will croak().

addValue(NAMESPACE, PROPERTY, VALUE)

Add a value for a property in a namespace:

$meta->addValue($namespace, "locationName", "Salt Lake City");

removeValue(NAMESPACE, PROPERTY, VALUE)

Remove a value for a property in a namespace:

$meta->removeValue($namespace, "locationName", "Dallas");

If the namespace, property, or value does not exist, this method will croak().

CONFORMANCE NOTE

The XMLNews metadata format is based on RDF, but this tool is not a general RDF processor; instead, it relies on a particular usage profile and a particular abbreviated syntax, like the following:

<?xml version="1.0"?>
<xn:Resource xmlns:xn="http://www.xmlnews.org/namespaces/meta#">
 <xn:resourceId>12345</xn:resourceId>
 <xn:title>Sample</xn:title>
 <xn:description>Sample resource.</xn:description>
 <xn:rendition>12345.xml</xn:rendition>
 <xn:rendition>12345.html</xn:rendition>
</xn:Resource>

AUTHOR

This module was originally written for WavePhore by David Megginson (david@megginson.com).