Unix/Linux Go Back    


CentOS 7.0 - man page for pod::simple::pullparser (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Pod::Simple::PullParser(3)     User Contributed Perl Documentation     Pod::Simple::PullParser(3)

NAME
       Pod::Simple::PullParser -- a pull-parser interface to parsing Pod

SYNOPSIS
	my $parser = SomePodProcessor->new;
	$parser->set_source( "whatever.pod" );
	$parser->run;

       Or:

	my $parser = SomePodProcessor->new;
	$parser->set_source( $some_filehandle_object );
	$parser->run;

       Or:

	my $parser = SomePodProcessor->new;
	$parser->set_source( \$document_source );
	$parser->run;

       Or:

	my $parser = SomePodProcessor->new;
	$parser->set_source( \@document_lines );
	$parser->run;

       And elsewhere:

	require 5;
	package SomePodProcessor;
	use strict;
	use base qw(Pod::Simple::PullParser);

	sub run {
	  my $self = shift;
	 Token:
	  while(my $token = $self->get_token) {
	    ...process each token...
	  }
	}

DESCRIPTION
       This class is for using Pod::Simple to build a Pod processor -- but one that uses an
       interface based on a stream of token objects, instead of based on events.

       This is a subclass of Pod::Simple and inherits all its methods.

       A subclass of Pod::Simple::PullParser should define a "run" method that calls "$token =
       $parser->get_token" to pull tokens.

       See the source for Pod::Simple::RTF for an example of a formatter that uses
       Pod::Simple::PullParser.

METHODS
       my $token = $parser->get_token
	   This returns the next token object (which will be of a subclass of
	   Pod::Simple::PullParserToken), or undef if the parser-stream has hit the end of the
	   document.

       $parser->unget_token( $token )
       $parser->unget_token( $token1, $token2, ... )
	   This restores the token object(s) to the front of the parser stream.

       The source has to be set before you can parse anything.	The lowest-level way is to call
       "set_source":

       $parser->set_source( $filename )
       $parser->set_source( $filehandle_object )
       $parser->set_source( \$document_source )
       $parser->set_source( \@document_lines )

       Or you can call these methods, which Pod::Simple::PullParser has defined to work just like
       Pod::Simple's same-named methods:

       $parser->parse_file(...)
       $parser->parse_string_document(...)
       $parser->filter(...)
       $parser->parse_from_file(...)

       For those to work, the Pod-processing subclass of Pod::Simple::PullParser has to have
       defined a $parser->run method -- so it is advised that all Pod::Simple::PullParser
       subclasses do so.  See the Synopsis above, or the source for Pod::Simple::RTF.

       Authors of formatter subclasses might find these methods useful to call on a parser object
       that you haven't started pulling tokens from yet:

       my $title_string = $parser->get_title
	   This tries to get the title string out of $parser, by getting some tokens, and
	   scanning them for the title, and then ungetting them so that you can process the
	   token-stream from the beginning.

	   For example, suppose you have a document that starts out:

	     =head1 NAME

	     Hoo::Boy::Wowza -- Stuff B<wow> yeah!

	   $parser->get_title on that document will return "Hoo::Boy::Wowza -- Stuff wow yeah!".
	   If the document starts with:

	     =head1 Name

	     Hoo::Boy::W00t -- Stuff B<w00t> yeah!

	   Then you'll need to pass the "nocase" option in order to recognize "Name":

	     $parser->get_title(nocase => 1);

	   In cases where get_title can't find the title, it will return empty-string ("").

       my $title_string = $parser->get_short_title
	   This is just like get_title, except that it returns just the modulename, if the title
	   seems to be of the form "SomeModuleName -- description".

	   For example, suppose you have a document that starts out:

	     =head1 NAME

	     Hoo::Boy::Wowza -- Stuff B<wow> yeah!

	   then $parser->get_short_title on that document will return "Hoo::Boy::Wowza".

	   But if the document starts out:

	     =head1 NAME

	     Hooboy, stuff B<wow> yeah!

	   then $parser->get_short_title on that document will return "Hooboy, stuff wow yeah!".
	   If the document starts with:

	     =head1 Name

	     Hoo::Boy::W00t -- Stuff B<w00t> yeah!

	   Then you'll need to pass the "nocase" option in order to recognize "Name":

	     $parser->get_short_title(nocase => 1);

	   If the title can't be found, then get_short_title returns empty-string ("").

       $author_name   = $parser->get_author
	   This works like get_title except that it returns the contents of the "=head1
	   AUTHOR\n\nParagraph...\n" section, assuming that that section isn't terribly long. To
	   recognize a "=head1 Author\n\nParagraph\n" section, pass the "nocase" otpion:

	     $parser->get_author(nocase => 1);

	   (This method tolerates "AUTHORS" instead of "AUTHOR" too.)

       $description_name = $parser->get_description
	   This works like get_title except that it returns the contents of the "=head1
	   DESCRIPTION\n\nParagraph...\n" section, assuming that that section isn't terribly
	   long. To recognize a "=head1 Description\n\nParagraph\n" section, pass the "nocase"
	   otpion:

	     $parser->get_description(nocase => 1);

       $version_block = $parser->get_version
	   This works like get_title except that it returns the contents of the "=head1
	   VERSION\n\n[BIG BLOCK]\n" block.  Note that this does NOT return the module's
	   $VERSION!! To recognize a "=head1 Version\n\n[BIG BLOCK]\n" section, pass the "nocase"
	   otpion:

	     $parser->get_version(nocase => 1);

NOTE
       You don't actually have to define a "run" method.  If you're writing a Pod-formatter
       class, you should define a "run" just so that users can call "parse_file" etc, but you
       don't have to.

       And if you're not writing a formatter class, but are instead just writing a program that
       does something simple with a Pod::PullParser object (and not an object of a subclass),
       then there's no reason to bother subclassing to add a "run" method.

SEE ALSO
       Pod::Simple

       Pod::Simple::PullParserToken -- and its subclasses Pod::Simple::PullParserStartToken,
       Pod::Simple::PullParserTextToken, and Pod::Simple::PullParserEndToken.

       HTML::TokeParser, which inspired this.

SUPPORT
       Questions or discussion about POD and Pod::Simple should be sent to the
       pod-people@perl.org mail list. Send an empty email to pod-people-subscribe@perl.org to
       subscribe.

       This module is managed in an open GitHub repository,
       <https://github.com/theory/pod-simple/>. Feel free to fork and contribute, or to clone
       <git://github.com/theory/pod-simple.git> and send patches!

       Patches against Pod::Simple are welcome. Please send bug reports to
       <bug-pod-simple@rt.cpan.org>.

COPYRIGHT AND DISCLAIMERS
       Copyright (c) 2002 Sean M. Burke.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

       This program is distributed in the hope that it will be useful, but without any warranty;
       without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR
       Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.  But don't bother him, he's
       retired.

       Pod::Simple is maintained by:

       o   Allison Randal "allison@perl.org"

       o   Hans Dieter Pearcey "hdp@cpan.org"

       o   David E. Wheeler "dwheeler@cpan.org"

perl v5.16.3				    2013-05-03		       Pod::Simple::PullParser(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:25 PM.