1Data::Stag::BaseHandlerU(s3e)r Contributed Perl DocumentaDtaitoan::Stag::BaseHandler(3)
2
3
4

NAME

6         Data::Stag::BaseHandler     - Base class for writing tag stream handlers
7

SYNOPSIS

9         # EXAMPLE 1
10         package MyPersonHandler;
11         use base qw(Data::Stag::BaseHandler);
12
13         # 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
25         # EXAMPLE 2
26         package MyStatsHandler;
27         use base qw(Data::Stag::BaseHandler);
28
29         # 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
43         # Using the handlers
44         my $handler = MyHandler->new;
45         my $stag = Data::Stag->parse(-fh=>$fh, -handler=>$handler);
46
47         # Using a handler from the command line:
48         unix> stag-handle.pl -m MyHandler input.xml > post-processed.xml
49

DESCRIPTION

51       Default Simple Event Handler, other handlers inherit from this class
52
53       See also Data::Stag and Data::Stag::BaseGenerator
54
55       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
60       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
64       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
68       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
71   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
77       This class can take SAX events and turn them into simple Data::Stag
78       events
79
80       the events recognised are
81
82         start_event(node-name)
83         evbody(node-data)
84         end_event(node-name)
85
86       and also
87
88         event(node-name, node-data|[nodes])
89
90       which is just a wrapper for the other events
91
92       you can either intercept these methods; or you can define methods
93
94         s_<element_name>
95         e_<element_name>
96
97       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
100         # 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

PUBLIC METHODS -

118       new
119
120              Title: new
121
122               Args:
123             Return: L<Data::Stag::BaseHandler>
124            Example:
125
126       returns the tree that was built from all uncaught events
127
128       tree (stag)
129
130              Title: tree
131            Synonym: stag
132
133               Args:
134             Return: L<Data::Stag>
135            Example: print $parser->handler->tree->xml;
136
137       returns the tree that was built from all uncaught events
138

CAUGHT EVENTS

140       A Data::Stag::BaseGenerator class will generate events by calling the
141       following methods on this class:
142
143       start_event NODENAME
144       evbody DATA
145       end_event NODENAME {optional}
146       event NODENAME DATA
147
148       These events can be nested/hierarchical
149
150       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

PROTECTED METHODS -

154       s_*
155
156               Args: handler L<Data::Stag::BaseHandler>
157             Return:
158            Example:
159
160       autogenerated method - called by the parser when ever it starts a node;
161       * matches the node name
162
163       override this class providing the name of the node you wish to
164       intercept
165
166       e_*
167
168               Args: handler L<Data::Stag::BaseHandler>, node L<Data::Stag>
169             Return: node L<Data::Stag>
170            Example:
171
172       autogenerated method - called by the parser when ever it ends a node; *
173       matches the node name
174
175       override this class providing the name of the node you wish to
176       intercept
177
178       CONSUMES
179
180       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
184         package MyHandler;
185         use base qw(Data::Stag::BaseHandler);
186         sub CONSUMES {qw(person city)}
187         sub e_person {....}
188         sub e_city   {....}
189
190       depth
191
192              Title: depth
193
194               Args:
195             Return: depth int
196            Example:
197
198       depth of the nested event tree
199
200       up
201
202              Title: up
203
204               Args: dist int
205             Return: node stag
206            Example: $stag->up(-2);
207
208       when called when intercepting a node <foo>, this will look dist up the
209       tree to find the container node
210
211       For example, if our data contains the node <blah> below:
212
213         <blah>
214           <foo>
215             <a>1</b>
216           </foo>
217           <foo>
218             <a>2</b>
219           </foo>
220         </blah>
221
222           # 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
228       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
232       up_to
233
234              Title: up_to
235
236               Args: nodename str
237             Return: node stag
238            Example: $stag->up_to('blah');
239
240       Similar to up(), but it will go up the container event nodes until it
241       finds one with the matching name
242
243
244
245perl v5.38.0                      2023-07-20        Data::Stag::BaseHandler(3)
Impressum