Debian Codegraph @

upstream/debian-unstable/man3/Pod::Simple::PullParser.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Pod::Simple::PullParser 3perl"
58 .TH Pod::Simple::PullParser 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Pod::Simple::PullParser \-\- a pull\-parser interface to parsing Pod
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 3
68 \& my $parser = SomePodProcessor\->new;
69 \& $parser\->set_source( "whatever.pod" );
70 \& $parser\->run;
71 .Ve
72 .PP
73 Or:
74 .PP
75 .Vb 3
76 \& my $parser = SomePodProcessor\->new;
77 \& $parser\->set_source( $some_filehandle_object );
78 \& $parser\->run;
79 .Ve
80 .PP
81 Or:
82 .PP
83 .Vb 3
84 \& my $parser = SomePodProcessor\->new;
85 \& $parser\->set_source( \e$document_source );
86 \& $parser\->run;
87 .Ve
88 .PP
89 Or:
90 .PP
91 .Vb 3
92 \& my $parser = SomePodProcessor\->new;
93 \& $parser\->set_source( \e@document_lines );
94 \& $parser\->run;
95 .Ve
96 .PP
97 And elsewhere:
98 .PP
99 .Vb 4
100 \& require 5;
101 \& package SomePodProcessor;
102 \& use strict;
103 \& use base qw(Pod::Simple::PullParser);
104 \&
105 \& sub run {
106 \& my $self = shift;
107 \& Token:
108 \& while(my $token = $self\->get_token) {
109 \& ...process each token...
110 \& }
111 \& }
112 .Ve
113 .SH DESCRIPTION
114 .IX Header "DESCRIPTION"
115 This class is for using Pod::Simple to build a Pod processor \-\- but
116 one that uses an interface based on a stream of token objects,
117 instead of based on events.
118 .PP
119 This is a subclass of Pod::Simple and inherits all its methods.
120 .PP
121 A subclass of Pod::Simple::PullParser should define a \f(CW\*(C`run\*(C'\fR method
122 that calls \f(CW\*(C`$token = $parser\->get_token\*(C'\fR to pull tokens.
123 .PP
124 See the source for Pod::Simple::RTF for an example of a formatter
125 that uses Pod::Simple::PullParser.
126 .SH METHODS
127 .IX Header "METHODS"
128 .ie n .IP "my $token = $parser\->get_token" 4
129 .el .IP "my \f(CW$token\fR = \f(CW$parser\fR\->get_token" 4
130 .IX Item "my $token = $parser->get_token"
131 This returns the next token object (which will be of a subclass of
132 Pod::Simple::PullParserToken), or undef if the parser-stream has hit
133 the end of the document.
134 .ie n .IP "$parser\->unget_token( $token )" 4
135 .el .IP "\f(CW$parser\fR\->unget_token( \f(CW$token\fR )" 4
136 .IX Item "$parser->unget_token( $token )"
137 .PD 0
138 .ie n .IP "$parser\->unget_token( $token1, $token2, ... )" 4
139 .el .IP "\f(CW$parser\fR\->unget_token( \f(CW$token1\fR, \f(CW$token2\fR, ... )" 4
140 .IX Item "$parser->unget_token( $token1, $token2, ... )"
141 .PD
142 This restores the token object(s) to the front of the parser stream.
143 .PP
144 The source has to be set before you can parse anything. The lowest-level
145 way is to call \f(CW\*(C`set_source\*(C'\fR:
146 .ie n .IP "$parser\->set_source( $filename )" 4
147 .el .IP "\f(CW$parser\fR\->set_source( \f(CW$filename\fR )" 4
148 .IX Item "$parser->set_source( $filename )"
149 .PD 0
150 .ie n .IP "$parser\->set_source( $filehandle_object )" 4
151 .el .IP "\f(CW$parser\fR\->set_source( \f(CW$filehandle_object\fR )" 4
152 .IX Item "$parser->set_source( $filehandle_object )"
153 .ie n .IP "$parser\->set_source( \e$document_source )" 4
154 .el .IP "\f(CW$parser\fR\->set_source( \e$document_source )" 4
155 .IX Item "$parser->set_source( $document_source )"
156 .ie n .IP "$parser\->set_source( \e@document_lines )" 4
157 .el .IP "\f(CW$parser\fR\->set_source( \e@document_lines )" 4
158 .IX Item "$parser->set_source( @document_lines )"
159 .PD
160 .PP
161 Or you can call these methods, which Pod::Simple::PullParser has defined
162 to work just like Pod::Simple's same-named methods:
163 .ie n .IP $parser\->parse_file(...) 4
164 .el .IP \f(CW$parser\fR\->parse_file(...) 4
165 .IX Item "$parser->parse_file(...)"
166 .PD 0
167 .ie n .IP $parser\->parse_string_document(...) 4
168 .el .IP \f(CW$parser\fR\->parse_string_document(...) 4
169 .IX Item "$parser->parse_string_document(...)"
170 .ie n .IP $parser\->filter(...) 4
171 .el .IP \f(CW$parser\fR\->filter(...) 4
172 .IX Item "$parser->filter(...)"
173 .ie n .IP $parser\->parse_from_file(...) 4
174 .el .IP \f(CW$parser\fR\->parse_from_file(...) 4
175 .IX Item "$parser->parse_from_file(...)"
176 .PD
177 .PP
178 For those to work, the Pod-processing subclass of
179 Pod::Simple::PullParser has to have defined a \f(CW$parser\fR\->run method \-\-
180 so it is advised that all Pod::Simple::PullParser subclasses do so.
181 See the Synopsis above, or the source for Pod::Simple::RTF.
182 .PP
183 Authors of formatter subclasses might find these methods useful to
184 call on a parser object that you haven't started pulling tokens
185 from yet:
186 .ie n .IP "my $title_string = $parser\->get_title" 4
187 .el .IP "my \f(CW$title_string\fR = \f(CW$parser\fR\->get_title" 4
188 .IX Item "my $title_string = $parser->get_title"
189 This tries to get the title string out of \f(CW$parser\fR, by getting some tokens,
190 and scanning them for the title, and then ungetting them so that you can
191 process the token-stream from the beginning.
192 .Sp
193 For example, suppose you have a document that starts out:
194 .Sp
195 .Vb 1
196 \& =head1 NAME
197 \&
198 \& Hoo::Boy::Wowza \-\- Stuff B<wow> yeah!
199 .Ve
200 .Sp
201 \&\f(CW$parser\fR\->get_title on that document will return "Hoo::Boy::Wowza \-\-
202 Stuff wow yeah!". If the document starts with:
203 .Sp
204 .Vb 1
205 \& =head1 Name
206 \&
207 \& Hoo::Boy::W00t \-\- Stuff B<w00t> yeah!
208 .Ve
209 .Sp
210 Then you'll need to pass the \f(CW\*(C`nocase\*(C'\fR option in order to recognize "Name":
211 .Sp
212 .Vb 1
213 \& $parser\->get_title(nocase => 1);
214 .Ve
215 .Sp
216 In cases where get_title can't find the title, it will return empty-string
217 ("").
218 .ie n .IP "my $title_string = $parser\->get_short_title" 4
219 .el .IP "my \f(CW$title_string\fR = \f(CW$parser\fR\->get_short_title" 4
220 .IX Item "my $title_string = $parser->get_short_title"
221 This is just like get_title, except that it returns just the modulename, if
222 the title seems to be of the form "SomeModuleName \-\- description".
223 .Sp
224 For example, suppose you have a document that starts out:
225 .Sp
226 .Vb 1
227 \& =head1 NAME
228 \&
229 \& Hoo::Boy::Wowza \-\- Stuff B<wow> yeah!
230 .Ve
231 .Sp
232 then \f(CW$parser\fR\->get_short_title on that document will return
233 "Hoo::Boy::Wowza".
234 .Sp
235 But if the document starts out:
236 .Sp
237 .Vb 1
238 \& =head1 NAME
239 \&
240 \& Hooboy, stuff B<wow> yeah!
241 .Ve
242 .Sp
243 then \f(CW$parser\fR\->get_short_title on that document will return "Hooboy,
244 stuff wow yeah!". If the document starts with:
245 .Sp
246 .Vb 1
247 \& =head1 Name
248 \&
249 \& Hoo::Boy::W00t \-\- Stuff B<w00t> yeah!
250 .Ve
251 .Sp
252 Then you'll need to pass the \f(CW\*(C`nocase\*(C'\fR option in order to recognize "Name":
253 .Sp
254 .Vb 1
255 \& $parser\->get_short_title(nocase => 1);
256 .Ve
257 .Sp
258 If the title can't be found, then get_short_title returns empty-string
259 ("").
260 .ie n .IP "$author_name = $parser\->get_author" 4
261 .el .IP "\f(CW$author_name\fR = \f(CW$parser\fR\->get_author" 4
262 .IX Item "$author_name = $parser->get_author"
263 This works like get_title except that it returns the contents of the
264 "=head1 AUTHOR\en\enParagraph...\en" section, assuming that that section
265 isn't terribly long. To recognize a "=head1 Author\en\enParagraph\en"
266 section, pass the \f(CW\*(C`nocase\*(C'\fR option:
267 .Sp
268 .Vb 1
269 \& $parser\->get_author(nocase => 1);
270 .Ve
271 .Sp
272 (This method tolerates "AUTHORS" instead of "AUTHOR" too.)
273 .ie n .IP "$description_name = $parser\->get_description" 4
274 .el .IP "\f(CW$description_name\fR = \f(CW$parser\fR\->get_description" 4
275 .IX Item "$description_name = $parser->get_description"
276 This works like get_title except that it returns the contents of the
277 "=head1 DESCRIPTION\en\enParagraph...\en" section, assuming that that section
278 isn't terribly long. To recognize a "=head1 Description\en\enParagraph\en"
279 section, pass the \f(CW\*(C`nocase\*(C'\fR option:
280 .Sp
281 .Vb 1
282 \& $parser\->get_description(nocase => 1);
283 .Ve
284 .ie n .IP "$version_block = $parser\->get_version" 4
285 .el .IP "\f(CW$version_block\fR = \f(CW$parser\fR\->get_version" 4
286 .IX Item "$version_block = $parser->get_version"
287 This works like get_title except that it returns the contents of
288 the "=head1 VERSION\en\en[BIG BLOCK]\en" block. Note that this does NOT
289 return the module's \f(CW$VERSION\fR!! To recognize a
290 "=head1 Version\en\en[BIG BLOCK]\en" section, pass the \f(CW\*(C`nocase\*(C'\fR option:
291 .Sp
292 .Vb 1
293 \& $parser\->get_version(nocase => 1);
294 .Ve
295 .SH NOTE
296 .IX Header "NOTE"
297 You don't actually \fIhave\fR to define a \f(CW\*(C`run\*(C'\fR method. If you're
298 writing a Pod-formatter class, you should define a \f(CW\*(C`run\*(C'\fR just so
299 that users can call \f(CW\*(C`parse_file\*(C'\fR etc, but you don't \fIhave\fR to.
300 .PP
301 And if you're not writing a formatter class, but are instead just
302 writing a program that does something simple with a Pod::PullParser
303 object (and not an object of a subclass), then there's no reason to
304 bother subclassing to add a \f(CW\*(C`run\*(C'\fR method.
305 .SH "SEE ALSO"
306 .IX Header "SEE ALSO"
307 Pod::Simple
308 .PP
309 Pod::Simple::PullParserToken \-\- and its subclasses
310 Pod::Simple::PullParserStartToken,
311 Pod::Simple::PullParserTextToken, and
312 Pod::Simple::PullParserEndToken.
313 .PP
314 HTML::TokeParser, which inspired this.
315 .SH SUPPORT
316 .IX Header "SUPPORT"
317 Questions or discussion about POD and Pod::Simple should be sent to the
318 pod\[email protected] mail list. Send an empty email to
319 pod\-people\[email protected] to subscribe.
320 .PP
321 This module is managed in an open GitHub repository,
322 <https://github.com/perl\-pod/pod\-simple/>. Feel free to fork and contribute, or
323 to clone <https://github.com/perl\-pod/pod\-simple.git> and send patches!
324 .PP
325 Patches against Pod::Simple are welcome. Please send bug reports to
326 <bug\-pod\[email protected]>.
327 .SH "COPYRIGHT AND DISCLAIMERS"
328 .IX Header "COPYRIGHT AND DISCLAIMERS"
329 Copyright (c) 2002 Sean M. Burke.
330 .PP
331 This library is free software; you can redistribute it and/or modify it
332 under the same terms as Perl itself.
333 .PP
334 This program is distributed in the hope that it will be useful, but
335 without any warranty; without even the implied warranty of
336 merchantability or fitness for a particular purpose.
337 .SH AUTHOR
338 .IX Header "AUTHOR"
339 Pod::Simple was created by Sean M. Burke <[email protected]>.
340 But don't bother him, he's retired.
341 .PP
342 Pod::Simple is maintained by:
343 .IP \(bu 4
344 Allison Randal \f(CW\*(C`[email protected]\*(C'\fR
345 .IP \(bu 4
346 Hans Dieter Pearcey \f(CW\*(C`[email protected]\*(C'\fR
347 .IP \(bu 4
348 David E. Wheeler \f(CW\*(C`[email protected]\*(C'\fR