perldoc > Pod::Simple::PullParser

man perldoc info pydoc3 ri search

📛 NAME

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

🚀 Quick Reference

Use Case	Command	Description
🔧 Create a parser	my $parser = SomePodProcessor->new;	Instantiate a subclass of Pod::Simple::PullParser
📂 Set source (file)	$parser->set_source( "filename.pod" );	Parse from a file
📂 Set source (handle)	$parser->set_source( $filehandle );	Parse from a filehandle
📂 Set source (string)	$parser->set_source( \$document );	Parse from a scalar reference
📂 Set source (array)	$parser->set_source( \@lines );	Parse from an array of lines
🎯 Pull next token	my $token = $parser->get_token;	Get the next token object (returns undef at end)
↩️ Push back tokens	$parser->unget_token( $token1, $token2, ... );	Restore tokens to the front of the stream
🏷️ Get document title	$parser->get_title;	Extract title from =head1 NAME section
🔖 Get short title	$parser->get_short_title;	Extract module name if title is "Module -- description"
👤 Get author	$parser->get_author;	Extract content from =head1 AUTHOR section
📖 Get description	$parser->get_description;	Extract content from =head1 DESCRIPTION section
🔢 Get version block	$parser->get_version;	Extract content from =head1 VERSION section
▶️ Run parser	$parser->parse_file(...); etc.	Convenience methods that call a run method

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

🔧 Setting the Source

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);

📝 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 AT perl.org mail list. Send an empty email to pod-people-subscribe AT 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 AT rt.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 AT cpan.org>. But don't bother him, he's retired.

Pod::Simple is maintained by:

• Allison Randal <allison AT perl.org>
• Hans Dieter Pearcey <hdp AT cpan.org>
• David E. Wheeler <dwheeler AT cpan.org>

📛 NAME 🚀 Quick Reference 📋 SYNOPSIS 📖 DESCRIPTION 🛠️ METHODS 📝 NOTE 👀 SEE ALSO 🤝 SUPPORT ©️ COPYRIGHT AND DISCLAIMERS ✍️ AUTHOR