NAME
Pod::Simple::PullParser a pull-parser interface to parsing Pod
SYNOPSIS
my $parser = SomePodProcessor->new;
$parser->setsource( "whatever.pod" );
$parser->run;
Or:
my $parser = SomePodProcessor->new;
$parser->setsource( $somefilehandleobject );
$parser->run;
Or:
my $parser = SomePodProcessor->new;
$parser->setsource( \$documentsource );
$parser->run;
Or:
my $parser = SomePodProcessor->new;
$parser->setsource( \@documentlines );
$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->gettoken) {
...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->gettoken" 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->gettoken
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->ungettoken( $token )
$parser->ungettoken( $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 "setsource":
$parser->setsource( $filename )
$parser->setsource( $filehandleobject )
$parser->setsource( \$documentsource )
$parser->setsource( \@documentlines )
Or you can call these methods, which Pod::Simple::PullParser has
defined to work just like Pod::Simple's same-named methods:
$parser->parsefile(...)
$parser->parsestringdocument(...)
$parser->filter(...)
$parser->parsefromfile(...)
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 $titlestring = $parser->gettitle
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 yeah!
$parser->gettitle on that document will return "Hoo::Boy::Wowza
Stuff wow yeah!". If the document starts with:
=head1 Name
Hoo::Boy::W00t Stuff B yeah!
Then you'll need to pass the "nocase" option in order to recognize
"Name":
$parser->gettitle(nocase => 1);
In cases where gettitle can't find the title, it will return
empty-string ("").
my $titlestring = $parser->getshorttitle
This is just like gettitle, 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 yeah!
then $parser->getshorttitle on that document will return
"Hoo::Boy::Wowza".
But if the document starts out:
=head1 NAME
Hooboy, stuff B yeah!
then $parser->getshorttitle on that document will return "Hooboy,
stuff wow yeah!". If the document starts with:
=head1 Name
Hoo::Boy::W00t Stuff B yeah!
Then you'll need to pass the "nocase" option in order to recognize
"Name":
$parser->getshorttitle(nocase => 1);
If the title can't be found, then getshorttitle returns empty-
string ("").
$authorname = $parser->getauthor
This works like gettitle 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->getauthor(nocase => 1);
(This method tolerates "AUTHORS" instead of "AUTHOR" too.)
$descriptionname = $parser->getdescription
This works like gettitle 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->getdescription(nocase => 1);
$versionblock = $parser->getversion
This works like gettitle 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->getversion(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 "parsefile" 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,
. Feel free to fork and
contribute, or to clone and
send patches!
Patches against Pod::Simple are welcome. Please send bug reports to
.
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 . But don't
bother him, he's retired.
Pod::Simple is maintained by:
· Allison Randal "allison@perl.org"
· Hans Dieter Pearcey "hdp@cpan.org"
· David E. Wheeler "dwheeler@cpan.org"
perl v5.16.3 2013-05-03 Pod::Simple::PullParser(3)