Linux Certif

Toute la documentation sur la certification Linux LPI

Data::Stag::BaseGenerator.3pm

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