NAME

VOTABLE::Element - VOTABLE XML element class


SYNOPSIS

use VOTABLE::Element

$votable_element = new VOTABLE::Element

$votable_element = new VOTABLE::Element undef, a1 => v1, a2 => v2, ...

$votable_element = new VOTABLE::Element $xml_string

$votable_element = new VOTABLE::Element $xml_string, a1 => v1, a2 => v2, ...

$votable_element = new VOTABLE::Element $xmldom_element

$votable_element = new VOTABLE::Element $xmldom_element, a1 => v1, a2 => v2, ...


DESCRIPTION

This class is a VOTABLE-specific wrapper around the XML::DOM::Element class. It provides the base functionality for all VOTABLE element classes, and allows access to implementation-specific details, such as the XML::DOM::Element objects embedded within the VOTABLE objects. The typical user should never need access to the implementation-specific details, so these base methods are for use primarily by other VOTABLE objects. This approach was taken to allow modification of the underlying XML technology (currently XML::DOM, but we may use something else later) without changing the user API.

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.

Methods

new($str_or_ref, %options)

This is the class constructor. $str_or_ref, if defined, contains a string of XML to use to initialize the new object, or a reference to an existing XML::DOM::Element object to use to initialize the new object. If $str_or_ref is undefined, a new, empty XML::DOM::Element object is created for the new object. The %options argument contains 0 or more key => value pairs to use when setting the initial values of the element attributes. On success, this method returns the blessed refrence for the new object. On failure, this method returns undef.


WARNINGS


SEE ALSO

perl, XML::DOM


AUTHOR

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


VERSION

$Id: Element.pm,v 1.1.1.4 2002/06/09 21:13:08 elwinter Exp $