NAME

XML::Atom::Syndication::Object - base class for all complex Atom elements.

METHODS

Class->new( $HASHREF );

Constructor. A HASH reference can be passed to initialize the object. Recognized keys are:

Elem

A XML::Elemental::Element that will be used as the source for this object. This object can be retreived or set using the elem method.

Namespace

A string containing the namespace URI for the element.

Version

A SCALAR contain the Atom format version. This hash key can optionally be used instead of setting the element official Atom Namespace URIs using the Namespace key. Recognized values are 1.0 and 0.3. 1.0 is used as the default if Namespace and Version are not defined.

$object->ns

A read-only accessor to the element's namespace URI.

$object->elem([$element])

An accessor that returns its underlying XML::Elemental::Element object. If $object is provided the element is set.

$object->element_name

Returns the Atom element name the object represents. This MUST be overwritten by all subclasses.

$object->get_element($ns,$name)

Retrieves the values of a direct descendent of the object. $ns is a SCALAR contain a namespace URI or a XML::Atom::Syndication::Namespace object. $name is the local name of the element to retrieve.

When called in a SCALAR context returns the first elements values. In an ARRAY context it returns all values for the element.

$object->set_element($ns,$name,$val[,$attr,$add])

Sets the value of an element as a direct descendent of the object. $ns is a SCALAR contain a namespace URI or a XML::Atom::Syndication::Namespace object. $name is the local name of the element to retrieve. $val can either be a string, XML::Elemental::Element object, or some appropriate XML::Atom::Syndication object. $attr is an optional HASH reference used to specify attributes when $val is a string value. It is ignored otherwise. $add is an optional boolean that will create a new node and append it to any existing values as opposed to overwriting them which is the default behavior.

Returns $val if successful and undef otherwise. The error message can be retrieved through the object's errstr method.

$object->get_attribute($ns,$attr)

$object->get_attribute($attr)

Retrieves the value of an attribute. If one parameter is passed the sole attribute is assumed to be the attribute name in the same namespace as the object. If two are passed in it is assumed the first is either a XML::Atom::Syndication::Namespace object or SCALAR containing the namespace URI and the second the local name.

$object->set_attribute($ns,$attr,$val)

$object->set_attribute($attr,$val)

Sets the value of an attribute. If two parameters are passed the first is assumed to be the attribute name and the second its value. If three parameters are passed the first is considered to be either a XML::Atom::Syndication::Namespace object or SCALAR containing the namespace URI followed by the attribute name and new value.

$object->add($ns,$name,$val[,$attr])

An alias for set_element with add boolean flag always set to true.

$object->remove

"Disowns" the object from its parent.

$object->as_xml

Output the element and all of its descendants are a full XML document using XML::Atom::Syndication::Writer. The object will be the root element of the document with its namespace URI set as the default.

ELEMENT ACCESSORS

XML::Atom::Syndication::Object has the means to dynamically create generic accessors that can get and set known elements in the Atom namespace. This is a more convienant and less verbose then using generic methods such as get_element or set_attribute.

For instance if you wanted the title of an entry you could get it with either of these lines:

$entry->set_element('http://www.w3.org/2005/Atom','title','My Title');
$entry->get_element('http://www.w3.org/2005/Atom','title');

$entry->title('My Title');
$entry->title;

The second set of methods are the element accessors that we are talking about.

These accessors set and get text values. Other accessors will exist in the object sublclasses to handle more complex data such as a link where you have a value AND attributes per element.

See the Atom Syndication Format specification or the documentation for the specific classes for which elements you can expect from each.

Like its generic counterparts, if a "get" is made in an array context and multiple values exist all will be returned, otherwise only the first value is returned.

XML::Atom::Syndication does not enforce valid Atom Syndication Format (ASF) document structure though its really really encouraged. For validating an Atom document use one of the Atom-enabled feed validators such as the one found at http://www.feedvalidator.org/

Put another way, if you were to call $object-foo>, the object would essentially go the equivalent of $object-get_element($object->ns,'foo')>, It wouldn't throw an error for calling an undefined method. Instead it would simply return nothing -- or at least it should. (If it does you have some bigger issues.) This was by design in order for the module to be flexible as the format and knowledge of its use settles. It is subject to change in the future once support for version 0.3 of the format is completely phased out.

ERROR HANDLING

All subclasses of XML::Atom::Syndication::Object inherit two methods from Class::ErrorHandler.

Class->error($message)

$object->error($message)

Sets the error message for either the class Class or the object $object to the message $message. Returns undef.

Class->errstr

$object->errstr

Accesses the last error message set in the class Class or the object $object, respectively, and returns that error message.

AUTHOR & COPYRIGHT

Please see the XML::Atom::Syndication manpage for author, copyright, and license information.