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