POE::Filter::XML::Node - Fully featured XML node representation.

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

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

$node->attr('to', 'nickperez@jabber.org');

$node->attr('from', 'POE::Filter::XML::Node@jabber.org');

$node->attr('type', 'get');

my CW$query = CW$node->insert_tag('query', 'jabber:iq:foo'); CW$query->insert_tag('foo_tag')->data('bar');

my CW$foo = CW$query->get_tag('foo_tag');

my CW$foo2 = CW$foo->clone(); CW$foo2->data('new_data');

$query->insert_tag($foo2);

print CW$node->to_str() . \n;

$node->free();

--

(newlines and tabs for example only)

 <iq to='nickperez@jabber.org' 
  from='POE::Filter::XML::Node@jabber.org' type='get'>
   <query xmlns='jabber:iq:foo'>
     <foo_tag>bar</foo_tag>
     <foo_tag>new_data</foo_tag>
   </query>
 </iq>

POE::Filter::XML::Node aims to be a very simple yet powerful, memory/speed conscious module that allows JABBER(tm) developers to have the flexibility they need to build custom nodes, use it as the basis of their higher level libraries, or manipulating XML and then putting it out to a file.

Note that this is not a parser. This is merely the node representation that can be used to build XML objects that will give stringified versions of themselves.

new()

new() accepts as arguments the (1) name of the actual tag (ie. 'iq'), (2) an arrayref of attribute pairs for insert_attrs(). All of the arguments are optional and can be specified through other methods at a later time.

stream_start()

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 to_str() 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()

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 to_str() 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>)

clone()

clone() does a deep copy of the node and returns it. This includes all of its children, data, attributes, etc. The returned node stands on its own and does not hold any references to the node cloned. Also note that it has its own unique creation ID. Note: This method works but is expensive with self-referential nodes.

get_id()

get_id() returns the creation ID of the node. Useful for sorting. Creation IDs are unique to each Node.

parent()

parent() returns the nodes parent reference

name()

name() with no arguments returns the name of the node. With an argument, the name of the node is changed.

insert_attrs()

insert_attrs() 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 attr(). This is just a convenience method.

attr()

attr() with one argument returns the value of that attrib (ie. my CW$attrib = CW$node->attr('x') ). With another argument it sets that attribute to the value supplie (ie. CW$node->attr('x', 'value')). If the second argument is an empty string, then that attribute will be deleted and returned.

get_attrs()

get_attrs() returns a hash reference to the stored attribute/value pairs within the node.

data()

data() with no arguments returns the data stored in the node decoded. With one argument, data is stored into the node encoded. To access raw data with out going through the encoding mechanism, see rawdata().

rawdata()

rawdata() is similar to data() but without the encoding/decocing implictly occuring. Be cautious with this, because you may inadvertently send malformed xml over the wire if you are not careful to encode your data for transport.

insert_tag()

insert_tag() accepts two arguments, with (1) being either the name as a string of a new tag to build and then insert into the parent node, or (1) being a POE::Filter::XML::Node reference to add to the parents children, and (2) if (1) is a string then you pass along an optional arrayref of attribute pairs for insert_attrs() to be built into the new child. insert_tag() returns either newly created node, or the reference passed in originally, respectively. Note: You may safely insert yourself or any of your ascendants including your direct parent.

to_str()

to_str() returns a string representation of the entire node structure. Note there is no caching of stringifying nodes, so each operation is expensive. It really should wait until it's time to serialized to be sent over the wire. Note: Any self-referential or circular-referential links in your Node will only output the tag of the referent. ie. <parent><child><parent/></child></parent> Otherwise there is the problem with infinite recursion and we can't have that.

get_tag()

get_tag() takes one argument, (1) the name of the tag wanted. Depending on the context of the return value (array or scalar), get_tag() either returns an array of nodes match the name of the tag/filter supplied, or a single POE::Filter::XML::Node reference that matches, respectively. If there is no tag matching the specified argument, undef is returned.

detach_child() DEPRECATED: PLEASE SEE DETACH

detach_child() takes one argument: a POE::Filter::XML::Node reference that is a child of the node. It then removes that child from its children and returns it as a stand alone node on its own.

detach()

detach() takes no arguments and will sever itself from the tree to be a stand alone Node. In the case of self-referential Nodes, the internal counter is decremented by one and its position is removed. If multiple references exist (ie. you store yourself as several children), one of those children is removed. The invoking object will return itself.

get_children()

get_children() returns an array reference to all the children of that node.

get_children_hash()

get_children_hash() returns a hash reference to all the children of that node. Note: for more than one child with the same name, the entry in the hash will be an array reference.

get_sort_children()

get_sort_children() returns an array reference to all children of that node in sorted order according to their creation ID.

By request, parent and parent related functions are returned and safely implemented using Scalar::Util::weaken. The performance penalty has not been fully assessed, so proper testing should be utilized to ascertain the full extent of the added (mis)features.

Also note that ancesants are carefully tracked to avoid infinite recursion for methods such as to_str() and clone(). Although the functionality has been been tested, managing self-referential decendants is highly discouraged and may introduce weird behaviors because weakened references must be tracked by hand. You have been warned.

Copyright (c) 2003, 2004 Nicholas Perez. Released and distributed under the GPL.