.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Data::Stag::BaseHandler 3pm" .TH Data::Stag::BaseHandler 3pm "2022-06-12" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" .Vb 1 \& Data::Stag::BaseHandler \- Base class for writing tag stream handlers .Ve .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& # EXAMPLE 1 \& package MyPersonHandler; \& use base qw(Data::Stag::BaseHandler); \& \& # handler that prints nodes as they are parsed; \& # after each 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\en", \& $node\->sget(\*(Aqname\*(Aq), $node\->sget(\*(Aqaddress\*(Aq); \& return; # prune this from tree \& } \& 1; \& \& # EXAMPLE 2 \& package MyStatsHandler; \& use base qw(Data::Stag::BaseHandler); \& \& # handler that modifies tree as it goes \& # changes inch10 \& # to cm25 \& sub e_measurement { \& my $self = shift; \& my $node = shift; \& if ($node\->sget(\*(Aqunit\*(Aq) eq \*(Aqinch\*(Aq) { \& $node\->set(\*(Aqunit\*(Aq, \*(Aqcm\*(Aq); \& $node\->set(\*(Aqquantity\*(Aq, $node\->get(\*(Aqquantity\*(Aq) * 2.5); \& } \& return $node; # replace 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 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Default Simple Event Handler, other handlers inherit from this class .PP See also Data::Stag and Data::Stag::BaseGenerator .PP Stag has an event-handling architecture; parsers or generators \&\fBgenerate\fR or \fBfire\fR 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. .PP 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 .PP 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. .PP If you wish to write your own handler that writes out to another format, you may wish to inherit from Data::Stag::Writer .SS "\s-1CATCHING EVENTS\s0" .IX Subsection "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 \fBparse()\fR call .PP This class can take \s-1SAX\s0 events and turn them into simple Data::Stag events .PP the events recognised are .PP .Vb 3 \& start_event(node\-name) \& evbody(node\-data) \& end_event(node\-name) .Ve .PP and also .PP .Vb 1 \& event(node\-name, node\-data|[nodes]) .Ve .PP which is just a wrapper for the other events .PP you can either intercept these methods; or you can define methods .PP .Vb 2 \& s_ \& e_ .Ve .PP 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. .PP .Vb 10 \& # the follow handler prunes nodes from the tree, and writes \& # out data from the 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\en", \& $node\->sget(\*(Aqname\*(Aq), $node\->sget(\*(Aqaddress\*(Aq); \& return; \& }); \& my $parser = MyParser\->new; \& $parser\->handler($h); \& $parser\->parse(\-fh=>$fh); \& my $result_tree = $h\->stag; .Ve .SH "PUBLIC METHODS \-" .IX Header "PUBLIC METHODS -" \fInew\fR .IX Subsection "new" .PP .Vb 1 \& Title: new \& \& Args: \& Return: L \& Example: .Ve .PP returns the tree that was built from all uncaught events .PP \fItree (stag)\fR .IX Subsection "tree (stag)" .PP .Vb 2 \& Title: tree \& Synonym: stag \& \& Args: \& Return: L \& Example: print $parser\->handler\->tree\->xml; .Ve .PP returns the tree that was built from all uncaught events .SH "CAUGHT EVENTS" .IX Header "CAUGHT EVENTS" A Data::Stag::BaseGenerator class will generate events by calling the following methods on this class: .IP "start_event \s-1NODENAME\s0" 4 .IX Item "start_event NODENAME" .PD 0 .IP "evbody \s-1DATA\s0" 4 .IX Item "evbody DATA" .IP "end_event \s-1NODENAME\s0 {optional}" 4 .IX Item "end_event NODENAME {optional}" .IP "event \s-1NODENAME DATA\s0" 4 .IX Item "event NODENAME DATA" .PD .PP These events can be nested/hierarchical .PP If uncaught, these events are stacked into a stag tree, which can be written as xml or one of the other stag formats .SH "PROTECTED METHODS \-" .IX Header "PROTECTED METHODS -" \fIs_*\fR .IX Subsection "s_*" .PP .Vb 3 \& Args: handler L \& Return: \& Example: .Ve .PP autogenerated method \- called by the parser when ever it starts a node; * matches the node name .PP override this class providing the name of the node you wish to intercept .PP \fIe_*\fR .IX Subsection "e_*" .PP .Vb 3 \& Args: handler L, node L \& Return: node L \& Example: .Ve .PP autogenerated method \- called by the parser when ever it ends a node; * matches the node name .PP override this class providing the name of the node you wish to intercept .PP \fI\s-1CONSUMES\s0\fR .IX Subsection "CONSUMES" .PP 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 .PP .Vb 5 \& package MyHandler; \& use base qw(Data::Stag::BaseHandler); \& sub CONSUMES {qw(person city)} \& sub e_person {....} \& sub e_city {....} .Ve .PP \fIdepth\fR .IX Subsection "depth" .PP .Vb 1 \& Title: depth \& \& Args: \& Return: depth int \& Example: .Ve .PP depth of the nested event tree .PP \fIup\fR .IX Subsection "up" .PP .Vb 1 \& Title: up \& \& Args: dist int \& Return: node stag \& Example: $stag\->up(\-2); .Ve .PP when called when intercepting a node , this will look \fBdist\fR up the tree to find the container node .PP For example, if our data contains the node below: .PP .Vb 8 \& \& \& 1 \& \& \& 2 \& \& \& \& # and we have the following code: \& $h = Data::Stag\->makehandler(foo=>sub { \& my ($self, $foo) = @_; \& print $foo\->up(1)\->xml; \& return}); .Ve .PP The handler will be called twice; it will print the structure of the containing node, but the first time round, the node will not be complete .PP \fIup_to\fR .IX Subsection "up_to" .PP .Vb 1 \& Title: up_to \& \& Args: nodename str \& Return: node stag \& Example: $stag\->up_to(\*(Aqblah\*(Aq); .Ve .PP Similar to \fBup()\fR, but it will go up the container event nodes until it finds one with the matching name