1Data::Stag::BaseHandlerU(s3e)r Contributed Perl DocumentaDtaitoan::Stag::BaseHandler(3)
2
6 Data::Stag::BaseHandler - Base class for writing tag stream handlers
7
9 # EXAMPLE 1
10 package MyPersonHandler;
11 use base qw(Data::Stag::BaseHandler);
12 # handler that prints <person> nodes as they are parsed;
14 # after each <person> node is intercepted, it is discarded
15 # (it does not go to form the final tree)
16 sub e_person {
17 my $self = shift;
18 my $node = shift;
19 printf "Person name:%s address:%s\n",
20 $node->sget('name'), $node->sget('address');
21 return; # prune this from tree
22 }
23 1;
24 # EXAMPLE 2
26 package MyStatsHandler;
27 use base qw(Data::Stag::BaseHandler);
28 # handler that modifies tree as it goes
30 # changes <measurement><unit>inch</unit><quantity>10</quantity></measurement>
31 # to <measurement><unit>cm</unit><quantity>25</quantity></measurement>
32 sub e_measurement {
33 my $self = shift;
34 my $node = shift;
35 if ($node->sget('unit') eq 'inch') {
36 $node->set('unit', 'cm');
37 $node->set('quantity', $node->get('quantity') * 2.5);
38 }
39 return $node; # replace <measurement> with new data in result tree
40 }
41 1;
42 # Using the handlers
44 my $handler = MyHandler->new;
45 my $stag = Data::Stag->parse(-fh=>$fh, -handler=>$handler);
46 # Using a handler from the command line:
48 unix> stag-handle.pl -m MyHandler input.xml > post-processed.xml
49
51 Default Simple Event Handler, other handlers inherit from this class
52 See also Data::Stag and Data::Stag::BaseGenerator
54 Stag has an event-handling architecture; parsers or generators generate
56 or fire events. Events can be hierarchical/nested, just like stag
57 nodes. These events are caught by handlers. By default, uncaught events
58 stack to form stag trees.
59 Stag has built in parsers for parsing xml, sxpr and itext data. You can
61 construct your own parsers for dealing with your own formats specific
62 to your own data; these should inherit from Data::Stag::BaseGenerator
63 Stag also has built in handlers for these formats. You can construct
65 your own - either as modules that inherit from this one, or as hashes
66 of anonymous subroutines.
67 If you wish to write your own handler that writes out to another
69 format, you may wish to inherit from Data::Stag::Writer
70 CATCHING EVENTS
72 This class catches Data::Stag node events (start, end and body) and
73 allows the subclassing module to intercept these. Unintercepted events
74 get pushed into a tree. The final tree is returned at the end of a
75 parse() call
76 This class can take SAX events and turn them into simple Data::Stag
78 events
79 the events recognised are
81 start_event(node-name)
83 evbody(node-data)
84 end_event(node-name)
85 and also
87 event(node-name, node-data|[nodes])
89 which is just a wrapper for the other events
91 you can either intercept these methods; or you can define methods
93 s_<element_name>
95 e_<element_name>
96 that get called on the start/end of an event; you can dynamically
98 change the structure of the tree by returning nodes from these methods.
99 # the follow handler prunes <foo> nodes from the tree, and writes
101 # out data from the <person> node
102 # when parsing large datasets, it can be a good idea to prune nodes
103 # from the tree, so the result tree of the parse is not too big
104 my $h = Data::Stag->makehandler( foo => 0,
105 person => sub {
106 my $self = shift;
107 my $node = shift;
108 printf "Person name:%s address:%s\n",
109 $node->sget('name'), $node->sget('address');
110 return;
111 });
112 my $parser = MyParser->new;
113 $parser->handler($h);
114 $parser->parse(-fh=>$fh);
115 my $result_tree = $h->stag;
116
118 new
119 Title: new
121 Args:
123 Return: L<Data::Stag::BaseHandler>
124 Example:
125 returns the tree that was built from all uncaught events
127 tree (stag)
129 Title: tree
131 Synonym: stag
132 Args:
134 Return: L<Data::Stag>
135 Example: print $parser->handler->tree->xml;
136 returns the tree that was built from all uncaught events
138
140 A Data::Stag::BaseGenerator class will generate events by calling the
141 following methods on this class:
142 start_event NODENAME
144 evbody DATA
145 end_event NODENAME {optional}
146 event NODENAME DATA
147 These events can be nested/hierarchical
149 If uncaught, these events are stacked into a stag tree, which can be
151 written as xml or one of the other stag formats
152
154 s_*
155 Args: handler L<Data::Stag::BaseHandler>
157 Return:
158 Example:
159 autogenerated method - called by the parser when ever it starts a node;
161 * matches the node name
162 override this class providing the name of the node you wish to
164 intercept
165 e_*
167 Args: handler L<Data::Stag::BaseHandler>, node L<Data::Stag>
169 Return: node L<Data::Stag>
170 Example:
171 autogenerated method - called by the parser when ever it ends a node; *
173 matches the node name
174 override this class providing the name of the node you wish to
176 intercept
177 CONSUMES
179 define this in your handler class to make explicit the list of node
181 names that your parser consumes; this is then used if your handler is
182 placed in a chain
183 package MyHandler;
185 use base qw(Data::Stag::BaseHandler);
186 sub CONSUMES {qw(person city)}
187 sub e_person {....}
188 sub e_city {....}
189 depth
191 Title: depth
193 Args:
195 Return: depth int
196 Example:
197 depth of the nested event tree
199 up
201 Title: up
203 Args: dist int
205 Return: node stag
206 Example: $stag->up(-2);
207 when called when intercepting a node <foo>, this will look dist up the
209 tree to find the container node
210 For example, if our data contains the node <blah> below:
212 <blah>
214 <foo>
215 <a>1</b>
216 </foo>
217 <foo>
218 <a>2</b>
219 </foo>
220 </blah>
221 # and we have the following code:
223 $h = Data::Stag->makehandler(foo=>sub {
224 my ($self, $foo) = @_;
225 print $foo->up(1)->xml;
226 return});
227 The <foo> handler will be called twice; it will print the structure of
229 the containing <blah> node, but the first time round, the <blah> node
230 will not be complete
231 up_to
233 Title: up_to
235 Args: nodename str
237 Return: node stag
238 Example: $stag->up_to('blah');
239 Similar to up(), but it will go up the container event nodes until it
241 finds one with the matching name
242perl v5.34.0 2021-07-22 Data::Stag::BaseHandler(3)