.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "POE::Filter::XML 3pm"
.TH POE::Filter::XML 3pm "2022-06-17" "perl v5.34.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 \- XML parsing for the POE framework
.SH "VERSION"
.IX Header "VERSION"
version 1.140700
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.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
.SH "PUBLIC_ATTRIBUTES"
.IX Header "PUBLIC_ATTRIBUTES"
.SS "not_streaming"
.IX Subsection "not_streaming"
.Vb 1
\&    is: ro, isa: Bool, default: false
.Ve
.PP
Setting the not_streaming attribute to true via \fBnew()\fR will put this filter into
non-streaming mode, meaning that whole documents are parsed before nodes are
returned. This is handy for \s-1XMLRPC\s0 or other short documents.
.SH "PRIVATE_ATTRIBUTES"
.IX Header "PRIVATE_ATTRIBUTES"
.SS "buffer"
.IX Subsection "buffer"
.Vb 1
\&    is: ro, isa: ArrayRef, traits: Array
.Ve
.PP
buffer holds the raw data to be parsed. Raw data should be split on network
new lines before being added to the buffer. Access to this attribute is
provided by the following methods:
.PP
.Vb 8
\&    handles =>
\&    {
\&        has_buffer => \*(Aqcount\*(Aq,
\&        all_buffer => \*(Aqelements\*(Aq,
\&        push_buffer => \*(Aqpush\*(Aq,
\&        shift_buffer => \*(Aqshift\*(Aq,
\&        join_buffer => \*(Aqjoin\*(Aq,
\&    }
.Ve
.SS "callback"
.IX Subsection "callback"
.Vb 1
\&    is: ro, isa: CodeRef
.Ve
.PP
callback holds the CodeRef to be call in the event that there is an exception
generated while parsing content. By default it holds a CodeRef that simply
calls Carp::confess.
.SS "handler"
.IX Subsection "handler"
.Vb 1
\&    is: ro, isa: POE::Filter::XML::Handler
.Ve
.PP
handler holds the \s-1SAX\s0 handler to be used for processing events from the parser.
By default POE::Filter::XML::Handler is instantiated and used.
.PP
The \*(L"not_streaming\*(R" attribute is passed to the constructor of Handler.
.SS "parser"
.IX Subsection "parser"
.Vb 1
\&    is: ro, isa: XML::LibXML
.Ve
.PP
parser holds an instance of the XML::LibXML parser. The \*(L"handler\*(R" attribute
is passed to the constructor of XML::LibXML.
.SH "PUBLIC_METHODS"
.IX Header "PUBLIC_METHODS"
.SS "get_one_start"
.IX Subsection "get_one_start"
.Vb 1
\&    (ArrayRef $raw?)
.Ve
.PP
This method is part of the POE::Filter \s-1API.\s0 See \*(L"get_one_start\*(R" in POE::Filter
for an explanation of its usage.
.SS "get_one"
.IX Subsection "get_one"
.Vb 1
\&    returns (ArrayRef)
.Ve
.PP
This method is part of the POE::Filter \s-1API.\s0 See \*(L"get_one\*(R" in POE::Filter for an
explanation of its usage.
.SS "put"
.IX Subsection "put"
.Vb 1
\&    (ArrayRef $nodes) returns (ArrayRef)
.Ve
.PP
This method is part of the POE::Filter \s-1API.\s0 See \*(L"put\*(R" in POE::Filter for an
explanation of its usage.
.SH "PROTECTED_METHODS"
.IX Header "PROTECTED_METHODS"
.SS "reset"
.IX Subsection "reset"
\&\fBreset()\fR is an internal method that gets called when either a \fBstream_start\fR\|(1)
POE::Filter::XML::Node gets placed into the filter via \*(L"put\*(R", or when a
\&\fBstream_end\fR\|(1) POE::Filter::XML::Node is pulled out of the queue of finished
Nodes via \*(L"get_one\*(R". 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.
.PP
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.
.SH "PRIVATE_METHODS"
.IX Header "PRIVATE_METHODS"
.SS "\s-1BUILD\s0"
.IX Subsection "BUILD"
A \s-1BUILD\s0 method is provided to parse the initial buffer (if any was included
when constructing the filter).
.SH "AUTHOR"
.IX Header "AUTHOR"
Nicholas R. Perez <nperez@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2014 by Nicholas R. Perez <nperez@cpan.org>.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.