NAME
XMLNews::Meta - A module for reading and writing XMLNews metadata files.
SYNOPSIS
use
XMLNews::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:
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:
# Use getValue only for
# singleton values!!!
$title
=
$meta
->getValue(
$xn_ns
,
"title"
);
$creator
=
$meta
->getValue(
$xn_ns
,
"creator"
);
The same property can have more than one value, which the getValues method will deliver as an array:
@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
@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: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).
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 579:
=cut found outside a pod block. Skipping to next block.