Provided by: libpoe-filter-xml-perl_0.38-1_all bug

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.