new($str_or_ref, %options)
new_from_filename($filename, %options)
get_ID
set_ID($id)
get_version
set_version($version)
get_description
set_description($votable_description)
get_definitions
set_definitions($votable_definitions)
get_info
set_info(@votable_info)
get_resource
set_resource(@votable_resource)
VOTABLE::Document - VOTABLE XML document class
use VOTABLE::Document
;
This class implements the VOTABLE
element from the VOTABLE
DTD. This element is the document element for VOTABLE
documents.
The VOTABLE
element is a Tier 6 element, and is described by the
following excerpt from the VOTABLE
1.0 DTD:
<
!ELEMENT VOTABLE (DESCRIPTION?, DEFINITIONS?, INFO*, RESOURCE*)>
<!ATTLIST VOTABLE
ID ID #IMPLIED
version CDATA #IMPLIED
>
new($str_or_ref, %options)
Create a new VOTABLE::Document
object, and return a reference to
it. If the first argument ($str_or_ref
) is a string, it is used as
the XML content of the document. If the first argument is a reference
to an open FileHandle object, it is used as the source of the XML
stream used to create the document. If the first argument is a
reference to a XML::DOM::Document
object, that object is used to
initialize the new VOTABLE
element (implicitly assuming that the
XML::DOM::Document
object contains a valid VOTABLE
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::Document
object. Return undef
if an
error occurs.
new_from_filename($filename, %options)
This is the alternate class constructor. The first argument is
interpreted as the name of a file from which to read the
XML. %options
is used to set the attributes of the new
element. Return undef
if an error occurs.
get_ID
Return the value of the ID
attribute. Return undef
if the
attribute has not been set, or an error occurs.
set_ID($id)
Set the value of the ID
attribute to the specified value. Return
the new value of the attribute on success, or undef
on error.
get_version
Return the value of the version
attribute. Return undef
if the
attribute has not been set, or an error occurs.
set_version($version)
Set the value of the version
attribute to the specified
value. Return the new value of the attribute on success, or undef
on error.
get_description
Return the VOTABLE::DESCRIPTION
object for this
VOTABLE::Document
. If no description is found, or an error occurs,
return undef
.
set_description($votable_description)
Set the DESCRIPTION
element for this object to the supplied
VOTABLE::DESCRIPTION
object. Return the VOTABLE::DESCRIPTION
object on success, or undef
if an error occurs.
get_definitions
Return a the VOTABLE::DEFINITIONS
object for this
VOTABLE::Document
. If no DEFINITIONS
element is found, or an
error occurs, return undef
.
set_definitions($votable_definitions)
Set the DEFINITIONS
element for this object to the supplied
VOTABLE::DEFINITIONS
object. Return the VOTABLE::DEFINITIONS
object on success, or undef
if an error occurs.
get_info
Return a list of the VOTABLE::INFO
objects representing the INFO
elements for this object. If no INFO
elements are found, or an
error occurs, return an empty list.
set_info(@votable_info)
Set the INFO
elements for this object to the supplied list of
VOTABLE::INFO
objects. Return the input list on success, or an
empty list on error.
get_resource
Return a list of the VOTABLE::RESOURCE
objects representing the
RESOURCE
elements for this object. If no RESOURCE
elements are
found, or an error occurs, return an empty list.
set_resource(@votable_resource)
Set the RESOURCE
elements for this object to the supplied list of
VOTABLE::RESOURCE
objects. Return the input list on success, or an
empty list on error.
_
), and should only be used by other methods in
the class, or subclasses.
VOTABLE
and XML::DOM
class hierarchies,
any variable (other than the traditional $this
) that refers to a
XML::DOM
object has the xmldom_
prefix, while variables that
refer to VOTABLE
objects use the votable_
prefix. Again, this is
probably verbosity overkill, but I'd rather be safe than sorry right
now.
XML::DOM
in this case), so that it can be changed in the future.
get_XXX
and set_XXX
accessors for attributes
and elements are derived directly from the names of the attributes or
elements. 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.
XML::DOM
methods and
subroutines never fail, and that the internal structure of VOTABLE
and XML::DOM
objects is always consistent. This decision was made
to speed initial development.
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::DEFINITIONS
, VOTABLE::DESCRIPTION
,
VOTABLE::INFO
, VOTABLE::RESOURCE
Eric Winter, NASA GSFC (elwinter@milkyway.gsfc.nasa.gov)
$Id: Document.pm,v 1.1.1.19 2002/05/21 14:09:55 elwinter Exp $