Data::Stag::BaseGenerator(3pm)				User Contributed Perl Documentation			    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

perl v5.10.0							    2008-06-03					    Data::Stag::BaseGenerator(3pm)