Pod::Simple::PullParser -- a pull-parser interface to parsing Pod
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...
}
}
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 the Pod::Simple manpage 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.
- my $token = $parser->get_token
-
This returns the next token object (which will be of a subclass of
the Pod::Simple::PullParserToken manpage), or undef if the parser-stream has hit
the end of the document.
- $parser->unget_token( $token )
-
- $parser->unget_token( $token1, $token2, ... )$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( $filehandle_object )
-
- $parser->set_source( \$document_source )$parser->set_source( \$document_source )
-
- $parser->set_source( \@document_lines )$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 option:
$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 option:
$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 option:
$parser->get_version(nocase => 1);
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.
the Pod::Simple manpage
the Pod::Simple::PullParserToken manpage -- and its subclasses
the Pod::Simple::PullParserStartToken manpage,
the Pod::Simple::PullParserTextToken manpage, and
the Pod::Simple::PullParserEndToken manpage.
the HTML::TokeParser manpage, which inspired this.
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/perl-pod/pod-simple/. Feel free to fork and contribute, or
to clone git://github.com/perl-pod/pod-simple.git and send patches!
Patches against Pod::Simple are welcome. Please send bug reports to
<bug-pod-simple@rt.cpan.org>.
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.
Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.
But don't bother him, he's retired.
Pod::Simple is maintained by:
|