VOTABLE::Element - VOTABLE XML element class
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, ...
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.
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
.
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).
perl, XML::DOM
Eric Winter, NASA GSFC (elwinter@milkyway.gsfc.nasa.gov)
$Id: Element.pm,v 1.1.1.4 2002/06/09 21:13:08 elwinter Exp $