XML::Atom::Syndication::Object - base class for all complex Atom elements.
Constructor. A HASH can be passed to initialize the object. Recognized keys are:
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.
elem
A string containing the namespace URI for the element.
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.
A read-only accessor to the element's namespace URI.
An accessor that returns its underlying XML::Elemental::Element object. If $object is provided the element is set.
$object
Returns the Atom element name the object represents. This MUST be overwritten by all subclasses.
"Disowns" the object from its parent.
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.
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.
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.
xml:base
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.
xml:lang
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.
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.
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.
$ns
$name
When called in a SCALAR context returns the first element's value. In an ARRAY context it returns all values for the element.
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.
$class
When called in a SCALAR context returns the first element. In an ARRAY context it returns all objects for the element.
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.
$val
$attr
$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.
$add
Returns $val if successful and undef otherwise. The error message can be retrieved through the object's errstr method.
undef
errstr
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.
XML::Atom::Syndication::Namespace
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.
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.
get_element
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.
mk_accessors
$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.
$type
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
All subclasses of XML::Atom::Syndication::Object inherit two methods from Class::ErrorHandler.
Sets the error message for either the class Class or the object $object to the message $message. Returns undef.
$message
Accesses the last error message set in the class Class or the object $object, respectively, and returns that error message.
Please see the XML::Atom::Syndication manpage for author, copyright, and license information.
3 POD Errors
The following errors were encountered while parsing the POD:
=begin without a target?
You forgot a '=back' before '=head2'
'=end' without a target?
To install XML::Atom::Syndication, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XML::Atom::Syndication
CPAN shell
perl -MCPAN -e shell install XML::Atom::Syndication
For more information on module installation, please visit the detailed CPAN module installation guide.