GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

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

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 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.

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" 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.

Pod::Simple

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

HTML::TokeParser, 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:

  • Allison Randal "allison@perl.org"
  • Hans Dieter Pearcey "hdp@cpan.org"
  • David E. Wheeler "dwheeler@cpan.org"
2021-06-16 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.