NAME

POE::Filter::XML::Node - An enhanced XML::LibXML::Element subclass.

SYNOPSIS

use 5.010;

use POE::Filter::XML::Node;

my $node = POE::Filter::XML::Node->new('iq');

$node->setAttributes( ['to', 'foo@other', 'from', 'bar@other', 'type', 'get'] );

my $query = $node->addNewChild('jabber:iq:foo', 'query');

$query->appendTextChild('foo_tag', 'bar');

say $node->toString();

--

(newlines and tabs for example only)

 <iq to='foo@other' from='bar@other' type='get'>
   <query xmlns='jabber:iq:foo'>
     <foo_tag>bar</foo_tag>
   </query>
 </iq>

DESCRIPTION

POE::Filter::XML::Node is a XML::LibXML::Element subclass that aims to provide a few extra convenience methods and light integration into a streaming context.

METHODS

stream_start($bool) [public]

stream_start() called without arguments returns a bool on whether or not the node in question is the top level document tag. In an xml stream such as XMPP this is the <stream:stream> tag. Called with a single argument (a bool) sets whether this tag should be considered a stream starter.

This method is significant because it determines the behavior of the toString() method. If stream_start() returns bool true, the tag will not be terminated. (ie. <iq to='test' from='test'> instead of <iq to='test' from='test'/>)

stream_end($bool) [public]

stream_end() called without arguments returns a bool on whether or not the node in question is the closing document tag in a stream. In an xml stream such as XMPP, this is the </stream:stream>. Called with a single argument (a bool) sets whether this tag should be considered a stream ender.

This method is significant because it determines the behavior of the toString() method. If stream_end() returns bool true, then any data or attributes or children of the node is ignored and an ending tag is constructed.

(ie. </iq> instead of <iq to='test' from='test'><child/></iq>)

setAttributes($array_ref) [public]

setAttributes() accepts a single arguement: an array reference. Basically you pair up all the attributes you want to be into the node (ie. [attrib, value]) and this method will process them using setAttribute(). This is just a convenience method.

If one of the attributes is 'xmlns', setNamespace() will be called with the value used as the $nsURI argument, with no prefix, and not activated.

 eg. 
 ['xmlns', 'http://foo']
        |
        V
 setNamespace($value, '', 0)
        |
        V
 <node xmlns="http://foo"/>

getAttributes() [public]

This method returns all of the attribute nodes on the Element (filtering out namespace declarations).

getChildrenHash() [public]

getChildrenHash() returns a hash reference to all the children of that node. Each key in the hash will be node name, and each value will be an array reference with all of the children with that name. Each child will be blessed into POE::Filter::XML::Node.

getSingleChildByTagName($name) [public]

This is a convenience method that basically does: (getChildrenByTagName($name))[0]

The returned object will be a POE::Filter::XML::Node object.

new($name,[$array_ref]) [overriden]

The default XML::LibXML::Element constructor is overridden to provide some extra functionality with regards to attributes. If the $array_ref argument is defined, it will be passed to setAttributes().

Returns a newly constructed POE::Filter::XML::Node.

cloneNode($deep) [overridden]

This method overrides the base cloneNode() to propogate the stream_[start|end] bits on the node being cloned. The $deep argument is passed unchanged to the base class.

This returns a POE::Filter::XML::Node object.

appendChild($name|$node,[$array_ref]) [overridden]

Depending on the arguments provided, this method either 1) instantiates a new Node and appends to the subject or 2) appends the provided Node object. An array reference of attributes may also be provided in either case, and if defined, will be passed to setAttributes().

toString($formatted) [overridden]

toString() was overridden to provide special stringification semantics for when stream_start and stream_end are boolean true.

FUNCTIONS

ordain($element) [exported by default]

Use this exported function to get PFX::Nodes from XML::LibXML::Elements. This is useful for inherited methods that by default return Elements instead of Nodes.

NOTES

This Node module is 100% incompatible with previous versions. Do NOT assume this will upgrade cleanly.

When using XML::LibXML::Element methods, the objects returned will NOT be blessed into POE::Filter::XML::Node objects unless those methods are explictly overriden in this module. Use POE::Filter::XML::Node::ordain to overcome this.

AUTHOR

Copyright (c) 2003 - 2009 Nicholas Perez. Released and distributed under the GPL.