NAME

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

METHODS

Class->new(%params);

Constructor. A HASH 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 retrieved 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->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.

ATOM COMMON ATTRIBUTES

This class supplies accessors to the Atom common attributes that every Atom element is to support.

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 supporting more then a simple string value require a more sophisticated means for adding or replacing nodes in an Atom document. These setters share a common method signature that is detailed here.

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

This class supplies several get and set accessors for accessing any element in the parse tree regardless of namespace. These accessors are also used in constructing the accessors for the elements defined in the Atom Syndication Format specification.

$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

XML::Atom::Syndication::Object dynamically generates the appropriate accessors for all defined elements in the Atom namespace. This is a more convenient and less verbose then using generic methods such as get_element or set_attribute.

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

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.

cpanm XML::Atom::Syndication

perl -MCPAN -e shell
install XML::Atom::Syndication