VOTABLE::DESCRIPTION - VOTABLE DESCRIPTION XML element class
use VOTABLE::DESCRIPTION;
This class implements the DESCRIPTION
element from the VOTABLE
DTD. This element is used to store a textual description of its parent
element.
The DESCRIPTION
element is a Tier 0 element, and is described by
the following excerpt from the VOTABLE
1.0 DTD:
<!ELEMENT DESCRIPTION (#PCDATA)>
=head2 Methods
new($str_or_ref, %options)
Create a new VOTABLE::DESCRIPTION
object, and return a reference to
it. If the first argument ($str_or_ref
) is a string, it is used as
the initial #PCDATA
content of the DESCRIPTION
element. If the
first argument is a reference to a XML::DOM::Element
object, that
object is used to initialize the new DESCRIPTION
element
(implicitly assuming that the XML::DOM::Element
object contains a
valid DESCRIPTION
element). The %options
hash is used to set the
attributes of the new element. If the first argument is missing or
undefined, or an empty string, create and return an empty
VOTABLE::DESCRIPTION
object. Return undef
if an error occurs.
get
Return a string containing the #PCDATA
content of the
DESCRIPTION
element. Return undef
if the element has no
#PCDATA
content, or an error occurs.
set($str)
Set the #PCDATA
content of the DESCRIPTION
element to the
specified string. Use undef
as the argument to clear any existing
value of the text. Return the string on success, or undef
if an
error occurs.
_
') are for
internal use only, and should not be used outside of the VOTABLE
class hierarchy.
get_XXX
and set_XXX
accessors for attributes
and elements are derived directly from the names of the attributes or
elements, with the attribute or element name replacing
XXX
. 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.
VOTABLE
object always has an underlying XML::DOM::Element
object. As long as the internal structure is manipulated only by the
publicly-available methods, this should be an adequate assumption. If
a method detects an aberrant case, a warning message is printed (using
the Carp::carp
subroutine), and the method fails.
XML::DOM
methods always
succeed. If a method detects an aberrant case, a warning message is
printed (using the Carp::carp
subroutine), and the method fails.
set_XXX
accessors do not perform validation of the
new attribute values. The exceptions are the accessors for attributes
with enumerated values; the new value is checked against the list of
acceptable values, as defined in the DTD.
VOTABLE
, VOTABLE::Document
, VOTABLE::FIELD
,
VOTABLE::PARAM
, VOTABLE::RESOURCE
, VOTABLE::TABLE
Eric Winter, NASA GSFC (elwinter@milkyway.gsfc.nasa.gov)
$Id: DESCRIPTION.pm,v 1.1.1.11 2002/06/09 21:13:08 elwinter Exp $