table of contents
other versions
- wheezy 5.14.2-21+deb7u3
- jessie 5.20.2-3+deb8u6
- testing 5.24.1-3
- unstable 5.24.1-3
- experimental 5.26.0-1
other sections
Pod::Simple::PullParser(3perl) | Perl Programmers Reference Guide | Pod::Simple::PullParser(3perl) |
NAME¶
Pod::Simple::PullParser -- a pull-parser interface to parsing PodSYNOPSIS¶
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.
- $parser->set_source( $filename )
- $parser->set_source( $filehandle_object )
- $parser->set_source( \$document_source )
- $parser->set_source( \@document_lines )
- $parser->parse_file(...)
- $parser->parse_string_document(...)
- $parser->filter(...)
- $parser->parse_from_file(...)
- 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.
=head1 NAME Hoo::Boy::Wowza -- Stuff B<wow> yeah!
=head1 Name Hoo::Boy::W00t -- Stuff B<w00t> yeah!
$parser->get_title(nocase => 1);
- 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".
=head1 NAME Hoo::Boy::Wowza -- Stuff B<wow> yeah!
=head1 NAME Hooboy, stuff B<wow> yeah!
=head1 Name Hoo::Boy::W00t -- Stuff B<w00t> yeah!
$parser->get_short_title(nocase => 1);
- $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);
- $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, http://github.com/theory/pod-simple/ <http://github.com/theory/pod-simple/>. Feel free to fork and contribute, or to clone git://github.com/theory/pod-simple.git <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:- •
- Allison Randal "allison@perl.org"
- •
- Hans Dieter Pearcey "hdp@cpan.org"
- •
- David E. Wheeler "dwheeler@cpan.org"
2011-09-26 | perl v5.14.2 |