/ 
PXR-0.1.5
/ PXR::Node

NAME

PXR::Node - Fully featured XML node representation.

SYNOPSIS

use PXR::Node;

my $node = PXR::Node->new('iq');

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

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

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

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

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

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

$query->insert_tag($foo2);

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

$node->free();

--

(newlines and tabs for example only)

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

DESCRIPTION

PXR::Node aims to be a very simple yet powerful, memory/speed conscious module that allows PXR or 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.

METHODS

new()

new() accepts as arguments the (1) name of the actual tag (ie. 'iq'), (2) an XML namespace, and the PXR::Node parent of the node being created. All of the arguments are optional and can be specified through other methods at a later time.

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 and references to the node cloned.

free()

free() breaks circular references between parent and node children. It is necessary to free() a node after its use to prevent memory leaks. Note that free() is a deep recursive effort. All children will be free()ed.

name()

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

parent()

parent() returns the PXR::Node parent reference.

attr()

attr() with one argument returns the value of that attrib (ie. my $attrib = $node->attr('x') ). With another argument it sets that attribute to the value supplie (ie. $node->attr('x', 'value')).

get_attrs()

get_attrs() returns an array 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 PXR::Node reference to add to the parents children, and (2) if (1) is a string then you pass along an optional xmlns to build built into the new child. insert_tag() returns either newly created node, or the reference passed in originally, respectively.

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.

get_tag()

get_tag() takes two arguments, (1) the name of the tag wanted, and (2) an optional namespace to filter against. 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 PXR::Node reference that matches, respectively.

detach_from_parent()

detach_from_parent() takes the current node and all of its children and separates from its parent node. Returns 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.

BUGS AND NOTES

Currently nodes are not ordered because they are stored in a hash. For sufficiently large node structures the hash O(1) access times will outweigh memory and speed of arrays, especially for linear searches. Each node is tagged with an internal ID number that will of course cause conflicts around integer limit on your specific platforms. These IDs are to provide ordering upon stringifying, but current to_str() does not take that into account. Order is preserved for multiple tags of the same name since they are stored in an array. Implementation may one day move to a pseudohash (ordered associative array usually by index being in the first element of the array) to preserve order intrinsicly instead of by some unreliable ID method (And also if there is a strong enough implementation that doesn't slow down regular hashes/arrays).

AUTHOR

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