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

NAME

       POE::Filter::XML - A POE Filter for parsing XML

SYSNOPSIS

        use POE::Filter::XML;
        my $filter = POE::Filter::XML->new();

        my $wheel = POE::Wheel:ReadWrite->new(
               Filter          => $filter,
               InputEvent      => 'input_event',
        );

DESCRIPTION

       POE::Filter::XML provides POE with a completely encapsulated XML parsing strategy for
       POE::Wheels that will be dealing with XML streams.

       The parser is XML::LibXML

       Default, the Filter will spit out POE::Filter::XML::Nodes because that is what the default
       XML::SAX 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.

       Also, Filter requires POE::Filter::XML::Nodes for put(). If you are wanting to send raw
       XML, it is recommened that you subclass the Filter and override put()

PUBLIC METHODS

       Since POE::Filter::XML follows the POE::Filter API look to POE::Filter for documentation.
       Deviations from Filter API will be covered here.

       new()
           new() accepts a total of four(4) named arguments that are all optional: (1) 'BUFFER':
           a string that is XML waiting to be parsed (i.e. xml received from the wheel before the
           Filter was instantiated), (2) 'CALLBACK': a coderef to be executed upon a parsing
           error, (3) 'HANDLER': a XML::SAX compliant Handler, or (4) 'NOTSTREAMING': boolean
           telling the filter to not process incoming XML as a stream but as single documents.

           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.

       reset()
           reset() is an internal method that gets called when either a stream_start(1)
           POE::Filter::XML::Node gets placed into the filter via put(), or when a stream_end(1)
           POE::Filter::XML::Node is pulled out of the queue of finished Nodes via get_one().
           This facilitates automagical behavior when using the Filter within the XMPP protocol
           that requires many new stream initiations.  This method is also called after every
           document when not in streaming mode.  Useful for handling XMLRPC processing.

           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 POE context.

           Internally reset() gets another parser, calls reset() on the stored handler and then
           deletes any data in the buffer.

       callback()
           callback() 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.

BUGS AND NOTES

       The underlying parser was switched to XML::LibXML.

       Also note that the PXF::Nodes returned are now subclassed from LibXML::Element and that
       the underlying API for Nodes has changed completely with out ANY compatibility at all.
       This was done for performance reasons, and also to gain XPath capabilities on the nodes
       returned.

       Meta filtering was removed. No one was using it and the increased level of indirection was
       a posible source of performance issues.

       put() now requires POE::Filter::XML::Nodes. Raw XML text can no longer be put() into the
       stream without subclassing the Filter and overriding put().

       reset() semantics were properly worked out to now be automagical and consistent. Thanks
       Eric Waters (ewaters@uarc.com).

       A new argument was added to the constructor to allow for multiple single document
       processing instead of one coherent stream. This allows for inbound XMLRPC requests to be
       properly parsed automagically without manually touching the reset() method on the Filter.

       Arguments passed to new() must be in name/value pairs (ie. 'BUFFER' => "stuff")

AUTHOR

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