VOTABLE - VOTABLE XML manipulation package
use VOTABLE
;
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:
COOSYS
, DESCRIPTION
, INFO
, LINK
, MAX
, MIN
,
STREAM
, TD
BINARY
, FITS
, OPTION
, TR
TABLEDATA
, VALUES
DATA
, FIELD
, PARAM
DEFINITIONS
, TABLE
RESOURCE
Document
VOTABLE::Element
always has an underlying XML::DOM::Element
object. When aberrant cases are encountered, an exception is raised
(using the Carp::croak
subroutine).
XML::DOM
methods always
succeed. When aberrant cases are encountered, an exception is raised
(using the Carp::croak
subroutine).
Eric Winter, NASA GSFC (elwinter@milkyway.gsfc.nasa.gov)
$Id: VOTABLE.pm,v 1.1.1.4 2002/05/21 14:07:09 elwinter Exp $