Data::Stag::BaseGenerator man page on Pidora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Pidora logo
[printable version]

Data::Stag::BaseGeneraUser3Contributed Perl DocumeData::Stag::BaseGenerator(3)

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.14.1			  2008-06-03	  Data::Stag::BaseGenerator(3)
[top]

List of man pages available for Pidora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net