.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "POE::Filter::XML::Node 3pm"
.TH POE::Filter::XML::Node 3pm "2009-04-25" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
POE::Filter::XML::Node \- An enhanced XML::LibXML::Element subclass.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use 5.010;
.PP
use POE::Filter::XML::Node;
.PP
my \f(CW$node\fR = POE::Filter::XML::Node\->new('iq');
.PP
\&\f(CW$node\fR\->setAttributes(
    ['to', 'foo@other', 
    'from', 'bar@other',
    'type', 'get']
);
.PP
my \f(CW$query\fR = \f(CW$node\fR\->addNewChild('jabber:iq:foo', 'query');
.PP
\&\f(CW$query\fR\->appendTextChild('foo_tag', 'bar');
.PP
say \f(CW$node\fR\->\fItoString()\fR;
.PP
\&\-\-
.PP
(newlines and tabs for example only)
.PP
.Vb 5
\& <iq to=\*(Aqfoo@other\*(Aq from=\*(Aqbar@other\*(Aq type=\*(Aqget\*(Aq>
\&   <query xmlns=\*(Aqjabber:iq:foo\*(Aq>
\&     <foo_tag>bar</foo_tag>
\&   </query>
\& </iq>
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.SH "METHODS"
.IX Header "METHODS"
.IP "stream_start($bool) [public]" 4
.IX Item "stream_start($bool) [public]"
\&\fIstream_start()\fR 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
\&\s-1XMPP\s0 this is the <stream:stream> tag. Called with a single argument (a bool)
sets whether this tag should be considered a stream starter.
.Sp
This method is significant because it determines the behavior of the \fItoString()\fR
method. If \fIstream_start()\fR returns bool true, the tag will not be terminated.
(ie. <iq to='test' from='test'> instead of <iq to='test' from='test'\fB/\fR>)
.IP "stream_end($bool) [public]" 4
.IX Item "stream_end($bool) [public]"
\&\fIstream_end()\fR 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 \s-1XMPP\s0, this is the </stream:stream>. Called with a single argument (a 
bool) sets whether this tag should be considered a stream ender.
.Sp
This method is significant because it determines the behavior of the \fItoString()\fR
method. If \fIstream_end()\fR returns bool true, then any data or attributes or
children of the node is ignored and an ending tag is constructed.
.Sp
(ie. </iq> instead of <iq to='test' from='test'><child/></iq>)
.IP "setAttributes($array_ref) [public]" 4
.IX Item "setAttributes($array_ref) [public]"
\&\fIsetAttributes()\fR 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 \fIsetAttribute()\fR. This is just a 
convenience method.
.Sp
If one of the attributes is 'xmlns', \fIsetNamespace()\fR will be called with the 
value used as the \f(CW$nsURI\fR argument, with no prefix, and not activated.
.Sp
.Vb 8
\& eg. 
\& [\*(Aqxmlns\*(Aq, \*(Aqhttp://foo\*(Aq]
\&        |
\&        V
\& setNamespace($value, \*(Aq\*(Aq, 0)
\&        |
\&        V
\& <node xmlns="http://foo"/>
.Ve
.IP "\fIgetAttributes()\fR [public]" 4
.IX Item "getAttributes() [public]"
This method returns all of the attribute nodes on the Element (filtering out 
namespace declarations).
.IP "\fIgetChildrenHash()\fR [public]" 4
.IX Item "getChildrenHash() [public]"
\&\fIgetChildrenHash()\fR 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.
.IP "getSingleChildByTagName($name) [public]" 4
.IX Item "getSingleChildByTagName($name) [public]"
This is a convenience method that basically does:
 (getChildrenByTagName($name))[0]
.Sp
The returned object will be a POE::Filter::XML::Node object.
.IP "new($name,[$array_ref]) [overriden]" 4
.IX Item "new($name,[$array_ref]) [overriden]"
The default XML::LibXML::Element constructor is overridden to provide some
extra functionality with regards to attributes. If the \f(CW$array_ref\fR argument is
defined, it will be passed to \fIsetAttributes()\fR.
.Sp
Returns a newly constructed POE::Filter::XML::Node.
.IP "cloneNode($deep) [overridden]" 4
.IX Item "cloneNode($deep) [overridden]"
This method overrides the base \fIcloneNode()\fR to propogate the stream_[start|end]
bits on the node being cloned. The \f(CW$deep\fR argument is passed unchanged to the 
base class.
.Sp
This returns a POE::Filter::XML::Node object.
.IP "appendChild($name|$node,[$array_ref]) [overridden]" 4
.IX Item "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 \fIsetAttributes()\fR.
.IP "toString($formatted) [overridden]" 4
.IX Item "toString($formatted) [overridden]"
\&\fItoString()\fR was overridden to provide special stringification semantics for when
stream_start and stream_end are boolean true.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "ordain($element) [exported by default]" 4
.IX Item "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.
.SH "NOTES"
.IX Header "NOTES"
This Node module is 100% incompatible with previous versions. Do \s-1NOT\s0 assume
this will upgrade cleanly.
.PP
When using XML::LibXML::Element methods, the objects returned will \s-1NOT\s0 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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (c) 2003 \- 2009 Nicholas Perez. 
Released and distributed under the \s-1GPL\s0.