.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Data::Stag::BaseGenerator 3pm"
.TH Data::Stag::BaseGenerator 3pm "2016-05-29" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\&  Data::Stag::BaseGenerator     \- base class for parsers and other event generators
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  # writing the parser
\&  package MyParser;
\&  use base qw(Data::Stag::BaseGenerator);
\&  
\&  sub parse_fh {
\&    my ($self, $fh) = shift;
\&
\&    my $lnum = 0;
\&    $self\->start_event(\*(Aqdata\*(Aq);
\&    while (<$fh>) {
\&      ++$lnum;
\&      $self\->line_no($lnum);
\&      # do stuff
\&      $self\->start_event(\*(Aqfoo\*(Aq);
\&
\&      # ...
\&      $self\->event(blah=>5);
\&
\&      #
\&      if (/incorrect_line/) {
\&         $self\->parse_err(\*(Aqline not in correct format\*(Aq);
\&      }
\&
\&      # ...
\&      $self\->end_event(\*(Aqfoo\*(Aq);
\&    }
\&    $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 \e*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
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the base class for all parsers and event generators
.PP
parsers/generators take some input (usually a filehandle, but a
generator could be a socket listener, for example) and fire stag
events
.PP
stag events are
.IP "start_event \s-1NODENAME\s0" 4
.IX Item "start_event NODENAME"
.PD 0
.IP "evbody \s-1DATA\s0" 4
.IX Item "evbody DATA"
.IP "end_event \s-1NODENAME\s0 {optional}" 4
.IX Item "end_event NODENAME {optional}"
.IP "event \s-1NODENAME DATA\s0" 4
.IX Item "event NODENAME DATA"
.PD
.PP
These events can be nested/hierarchical
.PP
If uncaught, these events are stacked into a stag tree, which can be
written as xml or one of the other stag formats
.PP
specialised handlers can be written to catch the events your parser
throws
.PP
For example, you may wish to write a pod parser that generates nested
events like this:
.PP
.Vb 8
\&  <pod>
\&   <section>
\&     <type>head1</type>
\&     <name>NAME</name>
\&     <text>Data::Stag \- Structured Tags datastructures</text>
\&   </section>
\&   ...
\&  </pod>
.Ve
.PP
(see the source for Data::Stag::PodParser for details)
.PP
You can write handlers that take the pod-xml and generate something \-
for example \s-1HTML\s0
.PP
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 \s-1STDERR.\s0 You can
create your own error handlers
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
\fInew\fR
.IX Subsection "new"
.PP
.Vb 1
\&       Title: new
\&
\&        Args: 
\&      Return: L<Data::Stag::BaseGenerator>
\&     Example:
.Ve
.PP
\&\s-1CONSTRUCTOR\s0
.PP
\fIhandler\fR
.IX Subsection "handler"
.PP
.Vb 5
\&       Title: handler
\&    Function: GET/SET ACCESSOR METHOD
\&        Args: handler L<Data::Stag::BaseHandler> optional
\&      Return: L<Data::Stag::BaseHandler>
\&     Example: $p\->handler(MyHandler\->new);
.Ve
.PP
each parser has a handler \- all events generated are passed onto the
handler; the default handler simply sits there collecting events
.PP
\fIerrhandler\fR
.IX Subsection "errhandler"
.PP
.Vb 5
\&       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);
.Ve
.PP
each parser has an error handler \- if the parser encounters things it
does not expect, it can pass errors to the errorhandler
.PP
if no errorhandler is set, an \s-1XML\s0 event handler that writes to \s-1STDERR\s0 is used
.PP
\fIcache_errors\fR
.IX Subsection "cache_errors"
.PP
.Vb 4
\&       Title: cache_errors
\&        Args: 
\&      Return: 
\&     Example: $p\->cache_errors
.Ve
.PP
If this is called, all errors will be cached rather than written to \s-1STDERR\s0
.PP
The error list can be accessed like this
.PP
.Vb 2
\&  $p\->parse($fn);
\&  @errs = $p\->errhandler\->stag\->get_error;
.Ve
.SS "parse"
.IX Subsection "parse"
.Vb 3
\&  Example \- $parser\->parse($file1, $file2);
\&  Returns \- 
\&  Args    \- filenames str\-LIST
.Ve
.PP
parses a file
.SS "parse"
.IX Subsection "parse"
.Vb 3
\&  Example \- $parser\->parse_fh($fh)
\&  Returns \- 
\&  Args    \- fh FILEHANDLE
.Ve
.PP
parses an open filehandle
.SH "PROTECTED METHODS"
.IX Header "PROTECTED METHODS"
These methods are only of interest if you are making your own
parser/generator class
.IP "start_event \s-1NODENAME\s0" 4
.IX Item "start_event NODENAME"
.PD 0
.IP "evbody \s-1DATA\s0" 4
.IX Item "evbody DATA"
.IP "end_event \s-1NODENAME\s0 {optional}" 4
.IX Item "end_event NODENAME {optional}"
.IP "event \s-1NODENAME DATA\s0" 4
.IX Item "event NODENAME DATA"
.PD
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Data::Stag
Data::Stag::BaseHandler