NAME¶
Data::Stag::BaseGenerator - base class for parsers and other event generators
SYNOPSIS¶
# writing the parser
package MyParser;
use base qw(Data::Stag::BaseGenerator);
sub parse_fh {
my ($self, $fh) = shift;
my $lnum = 0;
$self->start_event('data');
while (<$fh>) {
++$lnum;
$self->line_no($lnum);
# do stuff
$self->start_event('foo');
# ...
$self->event(blah=>5);
#
if (/incorrect_line/) {
$self->parse_err('line not in correct format');
}
# ...
$self->end_event('foo');
}
$self->pop_stack_to_depth(0);
}
1;
# using the parser
my $p = MyParser->new;
my $h = MyHandler->new; # see Data::Stag::BaseHandler
my $eh = Data::Stag->makehandler;
$p->handler($h);
$p->errhandler($eh);
$p->parse($file);
# result tree
print $h->stag->xml;
# write parse errs on standard err
printf \*STDERR $p->errhandler->stag->xml;
# using the parser from the command line
unix> stag-parse.pl -p MyParser -w xml -e err.xml > out.xml
# using the parser from the command line via intermediate handler
unix> stag-handle.pl -p MyParser -m MyHandler -w xml -e err.xml > out.xml
DESCRIPTION¶
This is the base class for all parsers and event generators
parsers/generators take some input (usually a filehandle, but a generator could
be a socket listener, for example) and fire stag events
stag events are
- start_event NODENAME
- evbody DATA
- end_event NODENAME {optional}
- event NODENAME DATA
These events can be nested/hierarchical
If uncaught, these events are stacked into a stag tree, which can be written as
xml or one of the other stag formats
specialised handlers can be written to catch the events your parser throws
For example, you may wish to write a pod parser that generates nested events
like this:
<pod>
<section>
<type>head1</type>
<name>NAME</name>
<text>Data::Stag - Structured Tags datastructures</text>
</section>
...
</pod>
(see the source for Data::Stag::PodParser for details)
You can write handlers that take the pod-xml and generate something - for
example HTML
parsers may encounter unexpected things along the way - they may throw an
exception, and fall over - or they may choose to fire an error event. by
default, error event streams are diverted to STDERR. You can create your own
error handlers
PUBLIC METHODS¶
new
Title: new
Args:
Return: L<Data::Stag::BaseGenerator>
Example:
CONSTRUCTOR
handler
Title: handler
Function: GET/SET ACCESSOR METHOD
Args: handler L<Data::Stag::BaseHandler> optional
Return: L<Data::Stag::BaseHandler>
Example: $p->handler(MyHandler->new);
each parser has a handler - all events generated are passed onto the handler;
the default handler simply sits there collecting events
errhandler
Title: errhandler
Function: GET/SET ACCESSOR METHOD
Args: handler L<Data::Stag::BaseHandler> optional
Return: L<Data::Stag::BaseHandler>
Example: $p->errhandler(Data::Stag->makehandler);
each parser has an error handler - if the parser encounters things it does not
expect, it can pass errors to the errorhandler
if no errorhandler is set, an XML event handler that writes to STDERR is used
cache_errors
Title: cache_errors
Args:
Return:
Example: $p->cache_errors
If this is called, all errors will be cached rather than written to STDERR
The error list can be accessed like this
$p->parse($fn);
@errs = $p->errhandler->stag->get_error;
parse¶
Example - $parser->parse($file1, $file2);
Returns -
Args - filenames str-LIST
parses a file
parse¶
Example - $parser->parse_fh($fh)
Returns -
Args - fh FILEHANDLE
parses an open filehandle
PROTECTED METHODS¶
These methods are only of interest if you are making your own parser/generator
class
- start_event NODENAME
- evbody DATA
- end_event NODENAME {optional}
- event NODENAME DATA
SEE ALSO¶
Data::Stag Data::Stag::BaseHandler