NAME

VOTABLE::VALUES - VOTABLE VALUES XML element class

SYNOPSIS

use VOTABLE::VALUES;

DESCRIPTION

This class implements the VALUES element from the VOTABLE DTD. This element is used to store descriptive values about other data items, such as minimum and maximum allowed values, and options for enumerated values.

The VALUES element is a Tier 2 element, and is described by the following excerpt from the VOTABLE 1.0 DTD:

 <!ELEMENT VALUES (MIN?, MAX?, OPTION*)>
 <!ATTLIST VALUES
         ID ID #IMPLIED
         type (legal | actual) "legal"
         null CDATA #IMPLIED
         invalid (yes | no) "no"
 >

Methods

`new($xmldom_element, %options)`

Create and return a new VOTABLE::VALUES object, based on the supplied XML::DOM::Element object, using %options to set the attributes of the new object. If no XML::DOM::Element object is specified, or is undefined, create and return an empty VOTABLE::VALUES object. 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 if an error occurs.

`get_invalid`

Return the value of the invalid attribute. Return undef if the attribute has not been set, or an error occurs.

`set_invalid($invalid)`

Set the value of the invalid attribute to the specified value. Return the new value of the attribute on success, or undef if an error occurs.

`get_null`

Return the value of the null attribute. Return undef if the attribute has not been set, or an error occurs.

`set_null($null)`

Set the value of the null attribute to the specified value. Return the new value of the attribute on success, or undef if an error occurs.

`get_type`

Return the value of the type attribute. Return undef if the attribute has not been set, or an error occurs.

`set_type($type)`

Set the value of the type attribute to the specified value. Return the new value of the attribute on success, or undef if an error occurs.

`get_max`

Return the VOTABLE::MAX object for the MAX element child of this VALUES object. Return undef if no MAX element is found, or if an error occurs.

`set_max($votable_max)`

Set the VOTABLE::MAX object for the MAX child element of this VALUES element to the specified object. Any existing MAX child element is first removed. Return the new MAX object on success, or undef if an error occurs.

`get_min`

Return the VOTABLE::MIN object for the MIN element child of this VALUES object. Return undef if no MIN element is found, or if an error occurs.

`set_min($votable_min)`

Set the VOTABLE::MIN object for the MIN child element of this VALUES element to the specified objects. Any existing MIN child element is first removed. Return the new MIN object on success, or undef if an error occurs.

`get_option`

Return a list of the VOTABLE::OPTION objects for the OPTION element children of this VALUES object. Return an empty list if no OPTION elements are found, or if an error occurs.

`set_option(@votable_option)`

Set the VOTABLE::OPTION objects for the OPTION child elements of this VALUES element to the specified objects. Any existing OPTION child elements are first removed. Return the new OPTION objects on success, or an empty list if an error occurs.

Notes on class internals

Method names that begin with a leading underscore ('_') are for internal use only, and should not be used outside of the VOTABLE class hierarchy.
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 (perhaps unwisely) assumes that object internal structure is always maintained. For example, this code assumes that every VOTABLE::TABLEDATA 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.
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.

AUTHOR

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

VERSION

$Id: VALUES.pm,v 1.1.1.11 2002/05/21 14:14:37 elwinter Exp $