Data::Stag::BaseGenerator(3pm)

1Data::Stag::BaseGeneratUosre(r3)Contributed Perl DocumenDtaattai:o:nStag::BaseGenerator(3)
2
3
4

NAME

6         Data::Stag::BaseGenerator     - base class for parsers and other event generators
7

SYNOPSIS

9         # writing the parser
10         package MyParser;
11         use base qw(Data::Stag::BaseGenerator);
12
13         sub parse_fh {
14           my ($self, $fh) = shift;
15
16           my $lnum = 0;
17           $self->start_event('data');
18           while (<$fh>) {
19             ++$lnum;
20             $self->line_no($lnum);
21             # do stuff
22             $self->start_event('foo');
23
24             # ...
25             $self->event(blah=>5);
26
27             #
28             if (/incorrect_line/) {
29                $self->parse_err('line not in correct format');
30             }
31
32             # ...
33             $self->end_event('foo');
34           }
35           $self->pop_stack_to_depth(0);
36         }
37         1;
38
39         # using the parser
40         my $p = MyParser->new;
41         my $h = MyHandler->new; # see Data::Stag::BaseHandler
42         my $eh = Data::Stag->makehandler;
43         $p->handler($h);
44         $p->errhandler($eh);
45         $p->parse($file);
46
47         # result tree
48         print $h->stag->xml;
49
50         # write parse errs on standard err
51         printf \*STDERR $p->errhandler->stag->xml;
52
53         # using the parser from the command line
54         unix> stag-parse.pl -p MyParser -w xml -e err.xml > out.xml
55
56         # using the parser from the command line via intermediate handler
57         unix> stag-handle.pl -p MyParser -m MyHandler -w xml -e err.xml > out.xml
58

DESCRIPTION

60       This is the base class for all parsers and event generators
61
62       parsers/generators take some input (usually a filehandle, but a
63       generator could be a socket listener, for example) and fire stag events
64
65       stag events are
66
67       start_event NODENAME
68       evbody DATA
69       end_event NODENAME {optional}
70       event NODENAME DATA
71
72       These events can be nested/hierarchical
73
74       If uncaught, these events are stacked into a stag tree, which can be
75       written as xml or one of the other stag formats
76
77       specialised handlers can be written to catch the events your parser
78       throws
79
80       For example, you may wish to write a pod parser that generates nested
81       events like this:
82
83         <pod>
84          <section>
85            <type>head1</type>
86            <name>NAME</name>
87            <text>Data::Stag - Structured Tags datastructures</text>
88          </section>
89          ...
90         </pod>
91
92       (see the source for Data::Stag::PodParser for details)
93
94       You can write handlers that take the pod-xml and generate something -
95       for example HTML
96
97       parsers may encounter unexpected things along the way - they may throw
98       an exception, and fall over - or they may choose to fire an error
99       event. by default, error event streams are diverted to STDERR. You can
100       create your own error handlers
101

PUBLIC METHODS

103       new
104
105              Title: new
106
107               Args:
108             Return: L<Data::Stag::BaseGenerator>
109            Example:
110
111       CONSTRUCTOR
112
113       handler
114
115              Title: handler
116           Function: GET/SET ACCESSOR METHOD
117               Args: handler L<Data::Stag::BaseHandler> optional
118             Return: L<Data::Stag::BaseHandler>
119            Example: $p->handler(MyHandler->new);
120
121       each parser has a handler - all events generated are passed onto the
122       handler; the default handler simply sits there collecting events
123
124       errhandler
125
126              Title: errhandler
127           Function: GET/SET ACCESSOR METHOD
128               Args: handler L<Data::Stag::BaseHandler> optional
129             Return: L<Data::Stag::BaseHandler>
130            Example: $p->errhandler(Data::Stag->makehandler);
131
132       each parser has an error handler - if the parser encounters things it
133       does not expect, it can pass errors to the errorhandler
134
135       if no errorhandler is set, an XML event handler that writes to STDERR
136       is used
137
138       cache_errors
139
140              Title: cache_errors
141               Args:
142             Return:
143            Example: $p->cache_errors
144
145       If this is called, all errors will be cached rather than written to
146       STDERR
147
148       The error list can be accessed like this
149
150         $p->parse($fn);
151         @errs = $p->errhandler->stag->get_error;
152
153   parse
154         Example - $parser->parse($file1, $file2);
155         Returns -
156         Args    - filenames str-LIST
157
158       parses a file
159
160   parse
161         Example - $parser->parse_fh($fh)
162         Returns -
163         Args    - fh FILEHANDLE
164
165       parses an open filehandle
166

PROTECTED METHODS

168       These methods are only of interest if you are making your own
169       parser/generator class
170
171       start_event NODENAME
172       evbody DATA
173       end_event NODENAME {optional}
174       event NODENAME DATA
175

NAME

SYNOPSIS

DESCRIPTION

PUBLIC METHODS

PROTECTED METHODS

SEE ALSO