plucky (3) Data::Stag::BaseHandler.3pm.gz

Provided by: libdata-stag-perl_0.14-3_all bug

NAME

         Data::Stag::BaseHandler     - Base class for writing tag stream handlers

SYNOPSIS

         # EXAMPLE 1
         package MyPersonHandler;
         use base qw(Data::Stag::BaseHandler);

         # handler that prints <person> nodes as they are parsed;
         # after each <person> node is intercepted, it is discarded
         # (it does not go to form the final tree)
         sub e_person {
             my $self = shift;
             my $node = shift;
             printf "Person name:%s address:%s\n",
               $node->sget('name'), $node->sget('address');
             return;               # prune this from tree
         }
         1;

         # EXAMPLE 2
         package MyStatsHandler;
         use base qw(Data::Stag::BaseHandler);

         # handler that modifies tree as it goes
         # changes <measurement><unit>inch</unit><quantity>10</quantity></measurement>
         # to      <measurement><unit>cm</unit><quantity>25</quantity></measurement>
         sub e_measurement {
             my $self = shift;
             my $node = shift;
             if ($node->sget('unit') eq 'inch') {
                 $node->set('unit', 'cm');
                 $node->set('quantity', $node->get('quantity') * 2.5);
             }
             return $node;     # replace <measurement> with new data in result tree
         }
         1;

         # Using the handlers
         my $handler = MyHandler->new;
         my $stag = Data::Stag->parse(-fh=>$fh, -handler=>$handler);

         # Using a handler from the command line:
         unix> stag-handle.pl -m MyHandler input.xml > post-processed.xml

DESCRIPTION

       Default Simple Event Handler, other handlers inherit from this class

       See also Data::Stag and Data::Stag::BaseGenerator

       Stag has an event-handling architecture; parsers or generators generate or fire events. Events can be
       hierarchical/nested, just like stag nodes. These events are caught by handlers. By default, uncaught
       events stack to form stag trees.

       Stag has built in parsers for parsing xml, sxpr and itext data. You can construct your own parsers for
       dealing with your own formats specific to your own data; these should inherit from
       Data::Stag::BaseGenerator

       Stag also has built in handlers for these formats. You can construct your own - either as modules that
       inherit from this one, or as hashes of anonymous subroutines.

       If you wish to write your own handler that writes out to another format, you may wish to inherit from
       Data::Stag::Writer

   CATCHING EVENTS
       This class catches Data::Stag node events  (start, end and body) and allows the subclassing module to
       intercept these. Unintercepted events get pushed into a tree. The final tree is returned at the end of a
       parse() call

       This class can take SAX events and turn them into simple Data::Stag events

       the events recognised are

         start_event(node-name)
         evbody(node-data)
         end_event(node-name)

       and also

         event(node-name, node-data|[nodes])

       which is just a wrapper for the other events

       you can either intercept these methods; or you can define methods

         s_<element_name>
         e_<element_name>

       that get called on the start/end of an event; you can dynamically change the structure of the tree by
       returning nodes from these methods.

         # the follow handler prunes <foo> nodes from the tree, and writes
         # out data from the <person> node
         # when parsing large datasets, it can be a good idea to prune nodes
         # from the tree, so the result tree of the parse is not too big
         my $h = Data::Stag->makehandler( foo => 0,
                                          person => sub {
                                              my $self = shift;
                                              my $node = shift;
                                              printf "Person name:%s address:%s\n",
                                                $node->sget('name'), $node->sget('address');
                                              return;
                                          });
         my $parser = MyParser->new;
         $parser->handler($h);
         $parser->parse(-fh=>$fh);
         my $result_tree = $h->stag;

PUBLIC METHODS -

       new

              Title: new

               Args:
             Return: L<Data::Stag::BaseHandler>
            Example:

       returns the tree that was built from all uncaught events

       tree (stag)

              Title: tree
            Synonym: stag

               Args:
             Return: L<Data::Stag>
            Example: print $parser->handler->tree->xml;

       returns the tree that was built from all uncaught events

CAUGHT EVENTS

       A Data::Stag::BaseGenerator class will generate events by calling the following methods on this class:

       start_event NODENAME
       evbody DATA
       end_event NODENAME {optional}
       event NODENAME DATA

       These events can be nested/hierarchical

       If uncaught, these events are stacked into a stag tree, which can be written as xml or one of the other
       stag formats

PROTECTED METHODS -

       s_*

               Args: handler L<Data::Stag::BaseHandler>
             Return:
            Example:

       autogenerated method - called by the parser when ever it starts a node; * matches the node name

       override this class providing the name of the node you wish to intercept

       e_*

               Args: handler L<Data::Stag::BaseHandler>, node L<Data::Stag>
             Return: node L<Data::Stag>
            Example:

       autogenerated method - called by the parser when ever it ends a node; * matches the node name

       override this class providing the name of the node you wish to intercept

       CONSUMES

       define this in your handler class to make explicit the list of node names that your parser consumes; this
       is then used if your handler is placed in a chain

         package MyHandler;
         use base qw(Data::Stag::BaseHandler);
         sub CONSUMES {qw(person city)}
         sub e_person {....}
         sub e_city   {....}

       depth

              Title: depth

               Args:
             Return: depth int
            Example:

       depth of the nested event tree

       up

              Title: up

               Args: dist int
             Return: node stag
            Example: $stag->up(-2);

       when called when intercepting a node <foo>, this will look dist up the tree to find the container node

       For example, if our data contains the node <blah> below:

         <blah>
           <foo>
             <a>1</b>
           </foo>
           <foo>
             <a>2</b>
           </foo>
         </blah>

           # and we have the following code:
           $h = Data::Stag->makehandler(foo=>sub {
                                                  my ($self, $foo) = @_;
                                                  print $foo->up(1)->xml;
                                                  return});

       The <foo> handler will be called twice; it will print the structure of the containing <blah> node, but
       the first time round, the <blah> node will not be complete

       up_to

              Title: up_to

               Args: nodename str
             Return: node stag
            Example: $stag->up_to('blah');

       Similar to up(), but it will go up the container event nodes until it finds one with the matching name