POD::SIMPLE::PULLPARSER(3perl)

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

okay bestie sit DOWN because we're about to talk about Pod::Simple::PullParser, which lives in the Perl Programmers Reference Guide, and it's genuinely such a vibe. it's a pull-parser interface to parsing Pod. that's the whole name. slay. 🦋

---

✨ SYNOPSIS ✨

the four ways to start, bestie, let's go:

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 — and this part is the actual main character move, the subclass with the run method:

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

notice the Token: label?? yes. labeled loops. we love a labeled while. 👑

---

🌸 DESCRIPTION 🌸

so this class exists so you can use Pod::Simple to build a Pod processor — except instead of the usual event-based interface, you get an interface built on a stream of token objects. it's giving "i pull, i don't get pushed." 💅

this is a subclass of Pod::Simple and it inherits all its methods. all of them. no cap.

a subclass of Pod::Simple::PullParser should define a "run" method that calls "$token = $parser->get_token" to pull tokens.

and if you want a real-life example of a formatter that uses Pod::Simple::PullParser? go look at the source for Pod::Simple::RTF. iconic behavior honestly.

---

🎀 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. that's it. that's the pull. 🫶

$parser->unget_token( $token )

$parser->unget_token( $token1, $token2, ... )

this restores the token object(s) to the front of the parser stream. like a rewind but for tokens. so useful. 💖

---

The source has to be set before you can parse anything. no source, no parsing, periodt. 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 — so like, pre-pull. before the vibe check. 🌈

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. (yes, it ungets them back. no crumbs left behind. 🎀)

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 (""). sad but honest. 😭

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.) accepting both?? inclusivity queen. 🌸

$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!! like seriously, do not come for me, it does not do that. 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. like, nobody's forcing you, bestie, live your life. 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. skip it. go touch grass. 🌱 (jk, go write perl.)

---

🔥 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. the origin story. the blueprint. ⭐

---

💜 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. (empty email, that's the whole trick, iykyk 💌)

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 <https://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 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.

okay that last one is the legal equivalent of "no refunds" — highkey important, don't skip it. 💀

---

🦋 AUTHOR 🦋

Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. But don't bother him, he's retired. (respect the retirement fr fr 🙏)

Pod::Simple is maintained by:

• Allison Randal "allison@perl.org"
• Hans Dieter Pearcey "hdp@cpan.org"
• David E. Wheeler "dwheeler@cpan.org"

---

and that's the whole page, bestie!! 🎀✨ this was Pod::S...lParser(3perl) from perl v5.44.0, dated 2026-10-17, out of the Perl Programmers Reference Guide. go forth and pull those tokens, you absolute icon. mwah. 💖💅🫶