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 for‐
69 mat, 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
74 allows the subclassing module to intercept these. Unintercepted events
75 get pushed into a tree. The final tree is returned at the end of a
76 parse() call
77 This class can take SAX events and turn them into simple Data::Stag
79 events
80 the events recognised are
82 start_event(node-name)
84 evbody(node-data)
85 end_event(node-name)
86 and also
88 event(node-name, node-data⎪[nodes])
90 which is just a wrapper for the other events
92 you can either intercept these methods; or you can define methods
94 s_<element_name>
96 e_<element_name>
97 that get called on the start/end of an event; you can dynamically
99 change the structure of the tree by returning nodes from these methods.
100 # the follow handler prunes <foo> nodes from the tree, and writes
102 # out data from the <person> node
103 # when parsing large datasets, it can be a good idea to prune nodes
104 # from the tree, so the result tree of the parse is not too big
105 my $h = Data::Stag->makehandler( foo => 0,
106 person => sub {
107 my $self = shift;
108 my $node = shift;
109 printf "Person name:%s address:%s\n",
110 $node->sget('name'), $node->sget('address');
111 return;
112 });
113 my $parser = MyParser->new;
114 $parser->handler($h);
115 $parser->parse(-fh=>$fh);
116 my $result_tree = $h->stag;
117
119 new
120 Title: new
122 Args:
124 Return: L<Data::Stag::BaseHandler>
125 Example:
126 returns the tree that was built from all uncaught events
128 tree (stag)
130 Title: tree
132 Synonym: stag
133 Args:
135 Return: L<Data::Stag>
136 Example: print $parser->handler->tree->xml;
137 returns the tree that was built from all uncaught events
139
141 A Data::Stag::BaseGenerator class will generate events by calling the
142 following methods on this class:
143 start_event NODENAME
145 evbody DATA
146 end_event NODENAME {optional}
147 event NODENAME DATA
148 These events can be nested/hierarchical
150 If uncaught, these events are stacked into a stag tree, which can be
152 written as xml or one of the other stag formats
153
155 s_*
156 Args: handler L<Data::Stag::BaseHandler>
158 Return:
159 Example:
160 autogenerated method - called by the parser when ever it starts a node;
162 * matches the node name
163 override this class providing the name of the node you wish to inter‐
165 cept
166 e_*
168 Args: handler L<Data::Stag::BaseHandler>, node L<Data::Stag>
170 Return: node L<Data::Stag>
171 Example:
172 autogenerated method - called by the parser when ever it ends a node; *
174 matches the node name
175 override this class providing the name of the node you wish to inter‐
177 cept
178 CONSUMES
180 define this in your handler class to make explicit the list of node
182 names that your parser consumes; this is then used if your handler is
183 placed in a chain
184 package MyHandler;
186 use base qw(Data::Stag::BaseHandler);
187 sub CONSUMES {qw(person city)}
188 sub e_person {....}
189 sub e_city {....}
190 depth
192 Title: depth
194 Args:
196 Return: depth int
197 Example:
198 depth of the nested event tree
200 up
202 Title: up
204 Args: dist int
206 Return: node stag
207 Example: $stag->up(-2);
208 when called when intercepting a node <foo>, this will look dist up the
210 tree to find the container node
211 For example, if our data contains the node <blah> below:
213 <blah>
215 <foo>
216 <a>1</b>
217 </foo>
218 <foo>
219 <a>2</b>
220 </foo>
221 </blah>
222 # and we have the following code:
224 $h = Data::Stag->makehandler(foo=>sub {
225 my ($self, $foo) = @_;
226 print $foo->up(1)->xml;
227 return});
228 The <foo> handler will be called twice; it will print the structure of
230 the containing <blah> node, but the first time round, the <blah> node
231 will not be complete
232 up_to
234 Title: up_to
236 Args: nodename str
238 Return: node stag
239 Example: $stag->up_to('blah');
240 Similar to up(), but it will go up the container event nodes until it
242 finds one with the matching name
243perl v5.8.8 2005-12-16 Data::Stag::BaseHandler(3)