NAME

       POE::Filter::XML::Handler - Default SAX Handler for POE::Filter::XML

VERSION

       version 1.140700

DESCRIPTION

       POE::Filter::XML::Handler is the default SAX handler for POE::Filter::XML. It extends
       XML::SAX::Base to provide different semantics for streaming vs.  non-streaming contexts.
       This handle by default builds POE::Filter::XML::Nodes.

PUBLIC_ATTRIBUTES

   not_streaming
           is: ro, isa: Bool, default: false

       not_streaming determines the behavior for the opening tag parsed. If what is being parsed
       is not a stream, the document will be parsed in full then placed into the finished_nodes
       attribute. Otherwise, the opening tag will be placed immediately into the finished_nodes
       bucket.

PRIVATE_ATTRIBUTES

   current_node
           is: rw, isa: POE::Filter::XML::Node

       current_node holds the node being immediately parsed.

   finished_nodes
           is: ro, isa: ArrayRef, traits: Array

       finished_nodes holds the nodes that have been completely parsed. Access to this attribute
       is provided through the following methods:

           handles =>
           {
               all_finished_nodes => 'elements',
               has_finished_nodes => 'count',
               add_finished_node => 'push',
               get_finished_node => 'shift',
           }

   depth_stack
           is: ro, isa: ArrayRef, traits: Array

       depth_stack holds the operating stack for the parsed nodes. As nodes are processed,
       ancendants of the current node are stored in the stack. When done they are popped off the
       stack. Access to this attribute is provided through the following methods:

           handles =>
           {
               push_depth_stack => 'push',
               pop_depth_stack => 'pop',
               depth => 'count',
           }

PUBLIC_METHODS

   reset
       reset will clear the current node, the finished nodes, and the depth stack.

PROTECTED_METHODS

   override start_element
           (HashRef $data)

       start_element is overridden from the XML::SAX::Base class to provide our custom behavior
       for dealing with streaming vs. non-streaming data. It builds Nodes then attaches them to
       either the root node (non-streaming) or as stand-alone top level fragments (streaming)
       sets them to the current node. Children nodes are appended to their parents before getting
       set as the current node. Then the base class method is called via super()

   override end_element
           (HashRef $data)

       end_element is overridden from the XML::SAX::Base class to provide our custom behavior for
       dealing with streaming vs. non-streaming data. Mostly this method is in charge of stack
       management when the depth of the stack reaches certain points. In streaming documents,
       this means that top level fragments (not root) are popped off the stack and added to the
       finished_nodes collection. Otherwise a Node is created with stream_end set and added to
       the finished nodes.

       Then the base class method is called via super()

   override characters
           (HashRef $data)

       characters merely applies the character data as text to the current node being processed.
       It then calls the base class method via super().

AUTHOR

       Nicholas R. Perez <nperez@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2014 by Nicholas R. Perez <nperez@cpan.org>.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.