Manual

- Overview
- Tutorials
- FAQs
- History / Changes
- License

Reference

- Language
- Functions
- Operators
- Special Variables
- Pragmas
- Utilities
- Internals
- Platform Specific

Modules

- A • B • C • D • E
- F • G • H • I • L
- M • N • O • P • S
- T • U • X

News / Blogs

- Perl Buzz
- Perl Iron Man
- Perlsphere
- Planet Perl
- TPF news
- Use Perl

See also

- CPAN
- Perl.org
- Perl.com
- Perl 5 Wiki
- Perl Jobs
- Perl Mongers
- Perl Monks

Contact

- Site designed and maintained by Jon Allen (JJ)
- http://perl.jonallen.info

- View the project page and FAQs

# Pod::Simple::PullParser

Perl 5 version 10.1 documentation
Go to top • Show page index • Download PDF

# Pod::Simple::PullParser

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
- NOTE
- SEE ALSO
- COPYRIGHT AND DISCLAIMERS
- AUTHOR

# NAME

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

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

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

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

  (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 PARAGRAPH\n\nParagraph...\n" section, assuming that that section isn't terribly long.

- $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` !!

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

# COPYRIGHT AND DISCLAIMERS

Copyright (c) 2002 Sean M. Burke. All rights reserved.

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

Sean M. Burke `sburke@cpan.org`

Page index

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
- NOTE
- SEE ALSO
- COPYRIGHT AND DISCLAIMERS
- AUTHOR

Recently read

Tools

- Preferences