NAME

VOTABLE - VOTABLE XML manipulation package

SYNOPSIS

use VOTABLE;

DESCRIPTION

The VOTABLE:: class hierarchy forms a set of wrappers around the class hierarchy. When using the VOTABLE classes, the user does not need to worry about the implementation details of the underlying XML technology (currently XML::DOM, but subject to change).

In general, the code consists of a VOTABLE module/class for each VOTABLE element defined in the VOTABLE DTD (version 1.0). This is VERY alpha code. It provides a crude but essentially complete capability to read, modify, and write VOTABLE documents. The code does its best to maintain the internal integrity of the document so that adherence to the DTD (or schema) is maintained.

The overall design of the VOTABLE objects is straightforward. Each XML element in the VOTABLE DTD is represented by a class. Each element class is a subclass of VOTABLE::Element (this class). Within each element class, there are attributes and child elements, along with implementation-specific data, such as references to the underlying XML::DOM objects.

Attributes are manipulated using get_ATTNAME and set_ATTNAME methods (accessors), where ATTNAME is replaced by the name of the attribute in question. The set methods take a single argument (the value to set the attribute to), and the get methods take no arguments. Since attributes can only take single values, all set_ATTNAME methods take single scalars as arguments, and get_ATTNAME methods return single scalars. All set_ATTNAME methods return the newly-set value on success, or undef if an error occurs.

Child elements have similar accessors, of the form get_ELNAME and set_ELNAME, where ELNAME is replaced by the name of the element (more precisely, the name of the element tag, such as TABLEDATA for a TABLEDATA element). Note that these names, and the methods, are case-sensitive. The type of arguments passed to and returned from the element accessors is determined by the multiplicity of the child elements (as defined by the VOTABLE DTD). Elements which can occur 0 or 1 times (those which are unquantified, or quantified with a '?' in the DTD) are passed and returned as scalars, while elements which can occur 1 or more times (those quantified with a '+' or '*' in the DTD) are passed and returned as lists. Like set_ATTNAME accessors, set_ELNAME accessors return the new value(s) on success. On failure, scalar-returning methods return undef, while list-returning methods return an empty list.

The VOTABLE class hierarchy is simple. The VOTABLE::Document class is used for objects representing entire XML documents, which are composed of VOTABLE::ELEMENT_NAME objects, where ELEMENT_NAME is replaced by the name of a valid VOTABLE element tag. There is a class for each valid VOTABLE element. Classes are arranged in tiers, where an element in a higher tier is composed exclusively of elements in lower tiers. The current list of valid elements is:

Tier 0: COOSYS, DESCRIPTION, INFO, LINK, MAX, MIN, STREAM, TD
Tier 1: BINARY, FITS, OPTION, TR
Tier 2: TABLEDATA, VALUES
Tier 3: DATA, FIELD, PARAM
Tier 4: DEFINITIONS, TABLE
Tier 5: RESOURCE
Tier 6: Document

WARNINGS

Alpha code. Caveat programmor.
This code (perhaps unwisely) assumes that object internal structure is always maintained. For example, this code assumes that every VOTABLE::Element always has an underlying XML::DOM::Element object. When aberrant cases are encountered, an exception is raised (using the Carp::croak subroutine).
Similarly, this code assumes that XML::DOM methods always succeed. When aberrant cases are encountered, an exception is raised (using the Carp::croak subroutine).
Attribute and element names containing embedded hyphens ('-') use accessors where the hyphen is mapped to an underscore ('_') in the name of the accessor method. This is a necessity, since the hyphen is not a valid name character in Perl.
External data is not yet supported, although the infrastructure has been started (BINARY and FITS elements, and STREAMs).
No testing has been done with Perl prior to version 5.6.1.

AUTHOR

Eric Winter, NASA GSFC (elwinter@milkyway.gsfc.nasa.gov)

VERSION