Manual Pages for UNIX Darwin command on man Pod::Simple::PullParser

Pod::Simple::PullParserU(s3e)r Contributed Perl DocumentaPtoido:n:Simple::PullParser(3)

NAME

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

SYNOPSIS

my $parser = SomePodProcessor->new;

$parser->setsource( "whatever.pod" );

$parser->run;

Or:

my $parser = SomePodProcessor->new;

$parser->setsource( $somefilehandleobject );

$parser->run;

Or:

my $parser = SomePodProcessor->new;

$parser->setsource( \$documentsource );

$parser->run;

Or:

my $parser = SomePodProcessor->new;

$parser->setsource( \@documentlines );

$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->gettoken) {

...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->gettoken" to pull tokens.

See the source for Pod::Simple::RTF for an example of a formatter that

uses Pod::Simple::PullParser.

MMEETTHHOODDSS

my $token = $parser->gettoken

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->ungettoken( $token )

$parser->ungettoken( $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 "setsource":

$parser->setsource( $filename )

$parser->setsource( $filehandleobject )

$parser->setsource( \$documentsource )

$parser->setsource( \@documentlines )

Or you can call these methods, which Pod::Simple::PullParser has

defined to work just like Pod::Simple's same-named methods:

$parser->parsefile(...)

$parser->parsestringdocument(...)

$parser->filter(...)

$parser->parsefromfile(...)

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 $titlestring = $parser->gettitle

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 yeah!

$parser->gettitle on that document will return "Hoo::Boy::Wowza -

Stuff wow yeah!". In cases where gettitle can't find the title, it will return

empty-string ("").

my $titlestring = $parser->getshorttitle

This is just like gettitle, 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 yeah!

then $parser->getshorttitle on that document will return

"Hoo::Boy::Wowza". But if the document starts out:

=head1 NAME

Hooboy, stuff B yeah!

then $parser->getshorttitle on that document will return "Hooboy,

stuff wow yeah!".

If the title can't be found, then getshorttitle returns empty-

string ("").

$authorname = $parser->getauthor

This works like gettitle 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.)

$descriptionname = $parser->getdescription

This works like gettitle except that it returns the contents of the "=head1 PARAGRAPH\n\nParagraph...\n" section, assuming that that section isn't terribly long.

$versionblock = $parser->getversion

This works like gettitle 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!!

NNOOTTEE 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 "parsefile" 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::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"