.\" 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 3pm"
.TH POE::Filter::XML 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 \- A POE Filter for parsing XML
.SH "SYSNOPSIS"
.IX Header "SYSNOPSIS"
.Vb 2
\& use POE::Filter::XML;
\& my $filter = POE::Filter::XML\->new();
\&
\& my $wheel = POE::Wheel:ReadWrite\->new(
\&        Filter          => $filter,
\&        InputEvent      => \*(Aqinput_event\*(Aq,
\& );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
POE::Filter::XML provides \s-1POE\s0 with a completely encapsulated \s-1XML\s0 parsing 
strategy for POE::Wheels that will be dealing with \s-1XML\s0 streams.
.PP
The parser is XML::LibXML
.PP
Default, the Filter will spit out POE::Filter::XML::Nodes because that is 
what the default \s-1XML::SAX\s0 compliant Handler produces from the stream it is 
given. You are of course encouraged to override the default Handler for your 
own purposes if you feel POE::Filter::XML::Node to be inadequate.
.PP
Also, Filter requires POE::Filter::XML::Nodes for \fIput()\fR. If you are wanting to
send raw \s-1XML\s0, it is recommened that you subclass the Filter and override \fIput()\fR
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
Since POE::Filter::XML follows the POE::Filter \s-1API\s0 look to POE::Filter for 
documentation. Deviations from Filter \s-1API\s0 will be covered here.
.IP "\fInew()\fR" 4
.IX Item "new()"
\&\fInew()\fR accepts a total of \fIfour\fR\|(4) named arguments that are all optional: 
(1) '\s-1BUFFER\s0': a string that is \s-1XML\s0 waiting to be parsed (i.e. xml received from
the wheel before the Filter was instantiated), (2) '\s-1CALLBACK\s0': a coderef to be
executed upon a parsing error, (3) '\s-1HANDLER\s0': a \s-1XML::SAX\s0 compliant Handler, or
(4) '\s-1NOTSTREAMING\s0': boolean telling the filter to not process incoming \s-1XML\s0 as
a stream but as single documents.
.Sp
If no options are specified, then a default coderef containing a simple
Carp::confess is generated, a new instance of POE::Filter::XML::Handler is 
used, and activated in streaming mode.
.IP "\fIreset()\fR" 4
.IX Item "reset()"
\&\fIreset()\fR is an internal method that gets called when either a \fIstream_start\fR\|(1)
POE::Filter::XML::Node gets placed into the filter via \fIput()\fR, or when a
\&\fIstream_end\fR\|(1) POE::Filter::XML::Node is pulled out of the queue of finished
Nodes via \fIget_one()\fR. This facilitates automagical behavior when using the 
Filter within the \s-1XMPP\s0 protocol that requires many new stream initiations.
This method is also called after every document when not in streaming mode.
Useful for handling \s-1XMLRPC\s0 processing.
.Sp
This method really should never be called outside of the Filter, but it is 
documented here in case the Filter is used outside of the \s-1POE\s0 context.
.Sp
Internally \fIreset()\fR gets another parser, calls \fIreset()\fR on the stored handler
and then deletes any data in the buffer.
.IP "\fIcallback()\fR" 4
.IX Item "callback()"
\&\fIcallback()\fR is an internal accessor to the coderef used when a parsing error 
occurs. If you want to place stateful nformation into a closure that gets 
executed when a parsering error happens, this is the method to use.
.SH "BUGS AND NOTES"
.IX Header "BUGS AND NOTES"
The underlying parser was switched to XML::LibXML.
.PP
Also note that the PXF::Nodes returned are now subclassed from LibXML::Element
and that the underlying \s-1API\s0 for Nodes has changed completely with out \s-1ANY\s0 
compatibility at all. This was done for performance reasons, and also to gain
XPath capabilities on the nodes returned.
.PP
Meta filtering was removed. No one was using it and the increased level of
indirection was a posible source of performance issues.
.PP
\&\fIput()\fR now requires POE::Filter::XML::Nodes. Raw \s-1XML\s0 text can no longer be
\&\fIput()\fR into the stream without subclassing the Filter and overriding \fIput()\fR.
.PP
\&\fIreset()\fR semantics were properly worked out to now be automagical and
consistent. Thanks Eric Waters (ewaters@uarc.com).
.PP
A new argument was added to the constructor to allow for multiple single 
document processing instead of one coherent stream. This allows for inbound 
\&\s-1XMLRPC\s0 requests to be properly parsed automagically without manually touching 
the \fIreset()\fR method on the Filter.
.PP
Arguments passed to \fInew()\fR must be in name/value pairs (ie. '\s-1BUFFER\s0' => \*(L"stuff\*(R")
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (c) 2003 \- 2009 Nicholas Perez. 
Released and distributed under the \s-1GPL\s0.