Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Data::Stag::BaseHandleUser Contributed Perl DocumentData::Stag::BaseHandler(3)

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

perl v5.24.1			  2013-09-18	    Data::Stag::BaseHandler(3)

NAME | SYNOPSIS | DESCRIPTION | PUBLIC METHODS - | CAUGHT EVENTS | PROTECTED METHODS -

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::Stag::BaseHandler&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help