Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Pod::Simple::PullParser.3pm

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