<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/Pod/Simple/PullParser.md. Do not edit. -->

```{index} single: Pod::Simple::PullParser
```

# Pod::Simple::PullParser

a pull-parser interface to parsing Pod

## SYNOPSIS

```perl
my $parser = SomePodProcessor->new;
$parser->set_source( "whatever.pod" );
$parser->run;
```

Or:

```perl
my $parser = SomePodProcessor->new;
$parser->set_source( $some_filehandle_object );
$parser->run;
```

Or:

```perl
my $parser = SomePodProcessor->new;
$parser->set_source( \$document_source );
$parser->run;
```

Or:

```perl
my $parser = SomePodProcessor->new;
$parser->set_source( \@document_lines );
$parser->run;
```

And elsewhere:

```perl
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](../Simple.md) 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](PullParserToken.md)), 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:

    ```text
    =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:

    ```text
    =head1 Name

    Hoo::Boy::W00t -- Stuff B<w00t> yeah!
    ```

    Then you'll need to pass the `nocase` option in order to recognize "Name":

    ```perl
    $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:

    ```text
    =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:

    ```text
    =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:

    ```text
    =head1 Name

    Hoo::Boy::W00t -- Stuff B<w00t> yeah!
    ```

    Then you'll need to pass the `nocase` option in order to recognize "Name":

    ```perl
    $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:

    ```perl
    $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:

    ```perl
    $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:

    ```perl
    $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](../Simple.md)

[Pod::Simple::PullParserToken](PullParserToken.md) -- and its subclasses
[Pod::Simple::PullParserStartToken](PullParserStartToken.md),
[Pod::Simple::PullParserTextToken](PullParserTextToken.md), and
[Pod::Simple::PullParserEndToken](PullParserEndToken.md).

[HTML::TokeParser](../../HTML/TokeParser.md), 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,
[https://github.com/perl-pod/pod-simple/](https://github.com/perl-pod/pod-simple/). Feel free to fork and contribute, or
to clone [https://github.com/perl-pod/pod-simple.git](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.

## 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`