Provided by: libdata-stag-perl_0.14-1ubuntu2_all 
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