ATOM COMMON ATTRIBUTES

All of these accessors return a string. You can set these attributes by passing in an optional string.

base

An attribute that when used serves the function described in section 5.1.1. of RFC3986 establishing the base URI/IRI for resolving any relative references found within its effective scope.

This attribute is represented as "xml:base" in markup.

lang

An attribute whose content indicates the natural language for the element and its descendants. See the XML 1.0 specification, Section 2.12 for more detail.

This attribute is represented as "xml:lang" in markup.

WORKING WITH OBJECT SETTERS

Elements can be set in one of two ways -- with a string HASH reference combination or with an appropriate object.

  $atom->element($var,$attr,$add);
  $atom->element($object,$add);

In the first example, a string ($var) is passed with an optional HASH reference ($attr) representing the attributes of the node. The keys of the hash referenced by $attr MUST be in Clarkian notation, in which the element's URI is wrapped in curly braces { } and prepended to the element's local name.

The accessor with create a node from these parameters that will be attached to the parent element.

Following the attribute hash with a true value ($add) will append the resulting node to any existing nodes of the same type. The default behavior is to remove any existing nodes of the same type before the new node is created.

In the second example the element is set with a XML::Elemental::Element object or XML::Atom::Syndication::Object subclass ($object). You can follow the object with an optional parameter ($add) to signify if the node is to be appended or to replace any similar elements.

GENERIC ACCESSORS

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

Retrieves the string values of any direct descendent of the object with the same namespace URI and name. $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 element's value. In an ARRAY context it returns all values for the element.

$object->get_class($class,$ns,$name)

Retrieves any direct descendants of the object with the same namespace and name as an object of the class defined by $class.

$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. $class is a package name that is assumed to be a superclass of this base class.

When called in a SCALAR context returns the first element. In an ARRAY context it returns all objects 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. he keys of the hash referenced by $attr MUST be in Clarkian notation, in which the element's URI is wrapped in curly braces { } and prepended to the element's local name.

$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.

ATOM ELEMENT ACCESSORS

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

 $entry->set_element('http://www.w3.org/2005/Atom','issued','2005-04-22T20:16:00Z');
 $entry->get_element('http://www.w3.org/2005/Atom','issued');

 $entry->issued('2005-04-22T20:16:00Z');
 $entry->issued;

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

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

These Atom element accessors are generated in each class using the "mk_accessors" method.

Class->mk_accessors($type,@names)

$type defines what type of set and get methods will be used to create an element accessor for each name defined by the @names array. Recognized values are either 'element', 'attribute' or a class name that is a superclass of this one.

The following chart defines which of the generic accessor methods will be used in constructing the element accessors.

 type           set             get
 -------------- --------------- ---------------
 element        set_element     get_element
 attribute      set_attribute   set_attribute
 $class         set_element     get_class
    

ERROR HANDLING

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.