Pod::Simple::PullParser(3pm)

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

NAME

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

SYNOPSIS

9        my $parser = SomePodProcessor->new;
10        $parser->set_source( "whatever.pod" );
11        $parser->run;
12
13       Or:
14
15        my $parser = SomePodProcessor->new;
16        $parser->set_source( $some_filehandle_object );
17        $parser->run;
18
19       Or:
20
21        my $parser = SomePodProcessor->new;
22        $parser->set_source( \$document_source );
23        $parser->run;
24
25       Or:
26
27        my $parser = SomePodProcessor->new;
28        $parser->set_source( \@document_lines );
29        $parser->run;
30
31       And elsewhere:
32
33        require 5;
34        package SomePodProcessor;
35        use strict;
36        use base qw(Pod::Simple::PullParser);
37
38        sub run {
39          my $self = shift;
40         Token:
41          while(my $token = $self->get_token) {
42            ...process each token...
43          }
44        }
45

DESCRIPTION

47       This class is for using Pod::Simple to build a Pod processor -- but one
48       that uses an interface based on a stream of token objects, instead of
49       based on events.
50
51       This is a subclass of Pod::Simple and inherits all its methods.
52
53       A subclass of Pod::Simple::PullParser should define a "run" method that
54       calls "$token = $parser->get_token" to pull tokens.
55
56       See the source for Pod::Simple::RTF for an example of a formatter that
57       uses Pod::Simple::PullParser.
58

METHODS

60       my $token = $parser->get_token
61           This returns the next token object (which will be of a subclass of
62           Pod::Simple::PullParserToken), or undef if the parser-stream has
63           hit the end of the document.
64
65       $parser->unget_token( $token )
66       $parser->unget_token( $token1, $token2, ... )
67           This restores the token object(s) to the front of the parser
68           stream.
69
70       The source has to be set before you can parse anything.  The lowest-
71       level way is to call "set_source":
72
73       $parser->set_source( $filename )
74       $parser->set_source( $filehandle_object )
75       $parser->set_source( \$document_source )
76       $parser->set_source( \@document_lines )
77
78       Or you can call these methods, which Pod::Simple::PullParser has
79       defined to work just like Pod::Simple's same-named methods:
80
81       $parser->parse_file(...)
82       $parser->parse_string_document(...)
83       $parser->filter(...)
84       $parser->parse_from_file(...)
85
86       For those to work, the Pod-processing subclass of
87       Pod::Simple::PullParser has to have defined a $parser->run method -- so
88       it is advised that all Pod::Simple::PullParser subclasses do so.  See
89       the Synopsis above, or the source for Pod::Simple::RTF.
90
91       Authors of formatter subclasses might find these methods useful to call
92       on a parser object that you haven't started pulling tokens from yet:
93
94       my $title_string = $parser->get_title
95           This tries to get the title string out of $parser, by getting some
96           tokens, and scanning them for the title, and then ungetting them so
97           that you can process the token-stream from the beginning.
98
99           For example, suppose you have a document that starts out:
100
101             =head1 NAME
102
103             Hoo::Boy::Wowza -- Stuff B<wow> yeah!
104
105           $parser->get_title on that document will return "Hoo::Boy::Wowza --
106           Stuff wow yeah!". If the document starts with:
107
108             =head1 Name
109
110             Hoo::Boy::W00t -- Stuff B<w00t> yeah!
111
112           Then you'll need to pass the "nocase" option in order to recognize
113           "Name":
114
115             $parser->get_title(nocase => 1);
116
117           In cases where get_title can't find the title, it will return
118           empty-string ("").
119
120       my $title_string = $parser->get_short_title
121           This is just like get_title, except that it returns just the
122           modulename, if the title seems to be of the form "SomeModuleName --
123           description".
124
125           For example, suppose you have a document that starts out:
126
127             =head1 NAME
128
129             Hoo::Boy::Wowza -- Stuff B<wow> yeah!
130
131           then $parser->get_short_title on that document will return
132           "Hoo::Boy::Wowza".
133
134           But if the document starts out:
135
136             =head1 NAME
137
138             Hooboy, stuff B<wow> yeah!
139
140           then $parser->get_short_title on that document will return "Hooboy,
141           stuff wow yeah!". If the document starts with:
142
143             =head1 Name
144
145             Hoo::Boy::W00t -- Stuff B<w00t> yeah!
146
147           Then you'll need to pass the "nocase" option in order to recognize
148           "Name":
149
150             $parser->get_short_title(nocase => 1);
151
152           If the title can't be found, then get_short_title returns empty-
153           string ("").
154
155       $author_name   = $parser->get_author
156           This works like get_title except that it returns the contents of
157           the "=head1 AUTHOR\n\nParagraph...\n" section, assuming that that
158           section isn't terribly long. To recognize a "=head1
159           Author\n\nParagraph\n" section, pass the "nocase" option:
160
161             $parser->get_author(nocase => 1);
162
163           (This method tolerates "AUTHORS" instead of "AUTHOR" too.)
164
165       $description_name = $parser->get_description
166           This works like get_title except that it returns the contents of
167           the "=head1 DESCRIPTION\n\nParagraph...\n" section, assuming that
168           that section isn't terribly long. To recognize a "=head1
169           Description\n\nParagraph\n" section, pass the "nocase" option:
170
171             $parser->get_description(nocase => 1);
172
173       $version_block = $parser->get_version
174           This works like get_title except that it returns the contents of
175           the "=head1 VERSION\n\n[BIG BLOCK]\n" block.  Note that this does
176           NOT return the module's $VERSION!! To recognize a "=head1
177           Version\n\n[BIG BLOCK]\n" section, pass the "nocase" option:
178
179             $parser->get_version(nocase => 1);
180

NOTE

182       You don't actually have to define a "run" method.  If you're writing a
183       Pod-formatter class, you should define a "run" just so that users can
184       call "parse_file" etc, but you don't have to.
185
186       And if you're not writing a formatter class, but are instead just
187       writing a program that does something simple with a Pod::PullParser
188       object (and not an object of a subclass), then there's no reason to
189       bother subclassing to add a "run" method.
190

SUPPORT

201       Questions or discussion about POD and Pod::Simple should be sent to the
202       pod-people@perl.org mail list. Send an empty email to
203       pod-people-subscribe@perl.org to subscribe.
204
205       This module is managed in an open GitHub repository,
206       <https://github.com/perl-pod/pod-simple/>. Feel free to fork and
207       contribute, or to clone <git://github.com/perl-pod/pod-simple.git> and
208       send patches!
209
210       Patches against Pod::Simple are welcome. Please send bug reports to
211       <bug-pod-simple@rt.cpan.org>.
212

COPYRIGHT AND DISCLAIMERS

214       Copyright (c) 2002 Sean M. Burke.
215
216       This library is free software; you can redistribute it and/or modify it
217       under the same terms as Perl itself.
218
219       This program is distributed in the hope that it will be useful, but
220       without any warranty; without even the implied warranty of
221       merchantability or fitness for a particular purpose.
222

AUTHOR

224       Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.  But don't
225       bother him, he's retired.
226
227       Pod::Simple is maintained by:
228
229       •   Allison Randal "allison@perl.org"
230
231       •   Hans Dieter Pearcey "hdp@cpan.org"
232
233       •   David E. Wheeler "dwheeler@cpan.org"
234
235
236
237perl v5.32.1                      2021-01-27        Pod::Simple::PullParser(3)