• NAME
• SYNOPSIS
• DESCRIPTION
• Methods
• 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)
• Notes on class internals
• WARNINGS
• SEE ALSO
• AUTHOR
• VERSION

NAME

VOTABLE::Document - VOTABLE XML document class

SYNOPSIS

use VOTABLE::Document;

DESCRIPTION

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 >

Methods

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.

Notes on class internals

• WARNING: The information in this section is for code maintainers only.

• This class (along with the other VOTABLE classes) makes extensive use of internal methods. The internal method names always start with a leading underscore (_), and should only be used by other methods in the class, or subclasses.

• To further delineate the 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.

• A general design principle for this software is that the user should not be aware of the use of the underlying representation (XML::DOM in this case), so that it can be changed in the future.

• The names of the 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.

WARNINGS

• This code assumes (perhaps unwisely) that 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.

• Similarly, this code assumes that 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.

• Most attribute 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.

SEE ALSO

VOTABLE, VOTABLE::DEFINITIONS, VOTABLE::DESCRIPTION, VOTABLE::INFO, VOTABLE::RESOURCE

AUTHOR

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

VERSION

$Id: Document.pm,v 1.1.1.19 2002/05/21 14:09:55 elwinter Exp $