NAME

XML::RSS::Parser::Element -- a node in the XML::RSS::Parser parse tree.

METHODS

XML::RSS::Parser::Element->new( [\%init] )

Constructor for XML::RSS::Parser::Element. Optionally the name, value, attributes, root, and parent can be set with a HASH reference using keys of the same name. See their associated functions below for more.

$element->root

Returns a reference to the root element of class XML::RSS::Parser::Feed from the parse tree.

$element->parent( [$element] )

Returns a reference to the parent element. A XML::RSS::Parser::Element object or one of its subclasses can be passed to optionally set the parent.

$element->name( [$extended_name] )

Returns the name of the element as a SCALAR. This should by the fully namespace qualified (extended) name of the element and not the QName or local part.

$element->attributes( [\%attributes] )

Returns a HASH reference contain attributes and their values as key value pairs. An optional parameter of a HASH reference can be passed in to set multiple attributes. Returns undef if no attributes exist. NOTE: When setting attributes with this method, all existing attributes are overwritten irregardless of whether they are present in the hash being passed in.

$element->contents([\@children])

Returns an ordered ARRAY reference of direct sibling objects. Returns a reference to an empty array if the element does not have any siblings. If a parameter is passed all the direct siblings are (re)set.

$element->text_content

A method that returns the character data of all siblings.

$element->as_xml

Creates XML output markup for the element object including its siblings.

This has its limitations, but should suffice in re-implementing the pass-thru function and maintain backwards compatability. i.e. missing namespace prefix mappings. perhaps more.

Use with caution. Feedback and enhancements are appreciated.

XPath-esque Methods

$element->query($xpath)

Finds matching nodes using an XPath-esque query from anywhere in the tree. Like the param method found in CGI, calling query in a SCALAR context will return only the first matching node. In an ARRAY context all matching elements are returned.

$element->match($xpath)

match is inherited from Class::XPath and always returns an array regardless of context. While query is generally preferred, using match in a scalar context is a good quick way of getting a count of matching nodes. See the Class::XPath documentation for more information.

$element->xpath

Returns a unique XPath string to the current node which can be used as an identifier.

These methods were implemented for internal use with Class::XPath and have now been exposed for general use.

$elemenet->qname

Returns the QName of the element based on the internal namespace prefix mapping.

$element->attribute_qnames

Returns an array of attribute names in namespace qualified (QName) form based on the internal prefix mapping.

$element->attribute_by_qname($qname)

Returns an array of attribute names in namespace qualified (QName) form.

2x API Methods

These were easily re-implemented though implementing them with only the methods provided by XML::Elemental are trivial. They are still available for backwards compatability reasons.

$element->attribute($name [, $value] )

Returns the value of an attribute specified by $name as a SCALAR. If an optional second text parameter $value is passed in the attribute is set. Returns undef if the attribute does not exist.

Using the attributes method you could replicate this method like so:

$element->attributes->{$name};          #get
$element->attributes->{$name} = $value; #set

$element->child( [$extended_name] )

Constructs and returns a new element object making the current object as its parent. An optional parameter representing the name of the new element object can be passed. This should be the fully namespace qualified (extended) name and not the QName or local part.

$element->children( [$extended_name] )

Returns any array of child elements to the object. An optional parameter can be passed in to return element(s) with a specific name. If called in a SCALAR context it will return only the first element with this name. If called in an ARRAY context the function returns all elements with this name. If no elements exist as a child of the object, and undefined value is returned.

NOTE: In keeping with the original behaviour of the 2x API, this method only returns XML::RSS::Parser::Elements. XML::RSS::Parser::Characters are stripped out. Use the contents method for the full list of child objects.

$element->children_names

Returns an array containing the names of the objects children. Empty if no children are present.

NOTE: In keeping with the original behaviour of the 2x API, this method only returns the names of XML::RSS::Parser::Elements. XML::RSS::Parser::Characters are not present.

Deprecated Methods

With the refactoring of XML::RSS::Parser 3.0 to a true tree structure, the purpose of some methods are no useful or problematic.the operation of some methods has changed. Ever attempt has been made to maintain backwards compatability, but some differences in behavior are unavoidable.

$element->value( [$value] )

Returns a reference to the value (text contents) of the element. If an optional SCALAR parameter is passed in the value (text contents) is set, removes all character objects and creates a new one as the first child of its parent with the passed using the passed value. The 2x API pass-thru functionality is still maintained. If parsing complex feed with extensive embedded markup like FOAF or XHTML, use of this method is likely to misbehave. Its highly recommended that you switch to the 3x API and use the text_content method or the contents method along with the XML::RSS::Parser::Character objects.

$element->append_value( $value )

Appends the value of the SCALAR parameter to the object's current value.

Instead of appending the $value to a the immediate character data for the element (See the notes on the value method), this method will create a new XML::RSS::Parser::Characters and set its value with $value if the last child is not character data. If the last child of the element is a characters object, $value is appended to that objects data value.

SEE ALSO

XML::RAI, XML::RSS::Parser, XML::SimpleObject, Class::XPath

AUTHOR & COPYRIGHT

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