Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "Pod::Parser 3" | |
132 | .TH Pod::Parser 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | Pod::Parser \- base class for creating POD filters and translators | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | .Vb 1 | |
138 | \& use Pod::Parser; | |
139 | .Ve | |
140 | .PP | |
141 | .Vb 2 | |
142 | \& package MyParser; | |
143 | \& @ISA = qw(Pod::Parser); | |
144 | .Ve | |
145 | .PP | |
146 | .Vb 10 | |
147 | \& sub command { | |
148 | \& my ($parser, $command, $paragraph, $line_num) = @_; | |
149 | \& ## Interpret the command and its text; sample actions might be: | |
150 | \& if ($command eq 'head1') { ... } | |
151 | \& elsif ($command eq 'head2') { ... } | |
152 | \& ## ... other commands and their actions | |
153 | \& my $out_fh = $parser->output_handle(); | |
154 | \& my $expansion = $parser->interpolate($paragraph, $line_num); | |
155 | \& print $out_fh $expansion; | |
156 | \& } | |
157 | .Ve | |
158 | .PP | |
159 | .Vb 6 | |
160 | \& sub verbatim { | |
161 | \& my ($parser, $paragraph, $line_num) = @_; | |
162 | \& ## Format verbatim paragraph; sample actions might be: | |
163 | \& my $out_fh = $parser->output_handle(); | |
164 | \& print $out_fh $paragraph; | |
165 | \& } | |
166 | .Ve | |
167 | .PP | |
168 | .Vb 7 | |
169 | \& sub textblock { | |
170 | \& my ($parser, $paragraph, $line_num) = @_; | |
171 | \& ## Translate/Format this block of text; sample actions might be: | |
172 | \& my $out_fh = $parser->output_handle(); | |
173 | \& my $expansion = $parser->interpolate($paragraph, $line_num); | |
174 | \& print $out_fh $expansion; | |
175 | \& } | |
176 | .Ve | |
177 | .PP | |
178 | .Vb 8 | |
179 | \& sub interior_sequence { | |
180 | \& my ($parser, $seq_command, $seq_argument) = @_; | |
181 | \& ## Expand an interior sequence; sample actions might be: | |
182 | \& return "*$seq_argument*" if ($seq_command eq 'B'); | |
183 | \& return "`$seq_argument'" if ($seq_command eq 'C'); | |
184 | \& return "_${seq_argument}_'" if ($seq_command eq 'I'); | |
185 | \& ## ... other sequence commands and their resulting text | |
186 | \& } | |
187 | .Ve | |
188 | .PP | |
189 | .Vb 1 | |
190 | \& package main; | |
191 | .Ve | |
192 | .PP | |
193 | .Vb 5 | |
194 | \& ## Create a parser object and have it parse file whose name was | |
195 | \& ## given on the command-line (use STDIN if no files were given). | |
196 | \& $parser = new MyParser(); | |
197 | \& $parser->parse_from_filehandle(\e*STDIN) if (@ARGV == 0); | |
198 | \& for (@ARGV) { $parser->parse_from_file($_); } | |
199 | .Ve | |
200 | .SH "REQUIRES" | |
201 | .IX Header "REQUIRES" | |
202 | perl5.005, Pod::InputObjects, Exporter, Symbol, Carp | |
203 | .SH "EXPORTS" | |
204 | .IX Header "EXPORTS" | |
205 | Nothing. | |
206 | .SH "DESCRIPTION" | |
207 | .IX Header "DESCRIPTION" | |
208 | \&\fBPod::Parser\fR is a base class for creating \s-1POD\s0 filters and translators. | |
209 | It handles most of the effort involved with parsing the \s-1POD\s0 sections | |
210 | from an input stream, leaving subclasses free to be concerned only with | |
211 | performing the actual translation of text. | |
212 | .PP | |
213 | \&\fBPod::Parser\fR parses PODs, and makes method calls to handle the various | |
214 | components of the \s-1POD\s0. Subclasses of \fBPod::Parser\fR override these methods | |
215 | to translate the \s-1POD\s0 into whatever output format they desire. | |
216 | .SH "QUICK OVERVIEW" | |
217 | .IX Header "QUICK OVERVIEW" | |
218 | To create a \s-1POD\s0 filter for translating \s-1POD\s0 documentation into some other | |
219 | format, you create a subclass of \fBPod::Parser\fR which typically overrides | |
220 | just the base class implementation for the following methods: | |
221 | .IP "\(bu" 2 | |
222 | \&\fB\f(BIcommand()\fB\fR | |
223 | .IP "\(bu" 2 | |
224 | \&\fB\f(BIverbatim()\fB\fR | |
225 | .IP "\(bu" 2 | |
226 | \&\fB\f(BItextblock()\fB\fR | |
227 | .IP "\(bu" 2 | |
228 | \&\fB\f(BIinterior_sequence()\fB\fR | |
229 | .PP | |
230 | You may also want to override the \fB\f(BIbegin_input()\fB\fR and \fB\f(BIend_input()\fB\fR | |
231 | methods for your subclass (to perform any needed per-file and/or | |
232 | per-document initialization or cleanup). | |
233 | .PP | |
234 | If you need to perform any preprocesssing of input before it is parsed | |
235 | you may want to override one or more of \fB\f(BIpreprocess_line()\fB\fR and/or | |
236 | \&\fB\f(BIpreprocess_paragraph()\fB\fR. | |
237 | .PP | |
238 | Sometimes it may be necessary to make more than one pass over the input | |
239 | files. If this is the case you have several options. You can make the | |
240 | first pass using \fBPod::Parser\fR and override your methods to store the | |
241 | intermediate results in memory somewhere for the \fB\f(BIend_pod()\fB\fR method to | |
242 | process. You could use \fBPod::Parser\fR for several passes with an | |
243 | appropriate state variable to control the operation for each pass. If | |
244 | your input source can't be reset to start at the beginning, you can | |
245 | store it in some other structure as a string or an array and have that | |
246 | structure implement a \fB\f(BIgetline()\fB\fR method (which is all that | |
247 | \&\fB\f(BIparse_from_filehandle()\fB\fR uses to read input). | |
248 | .PP | |
249 | Feel free to add any member data fields you need to keep track of things | |
250 | like current font, indentation, horizontal or vertical position, or | |
251 | whatever else you like. Be sure to read \*(L"\s-1PRIVATE\s0 \s-1METHODS\s0 \s-1AND\s0 \s-1DATA\s0\*(R" | |
252 | to avoid name collisions. | |
253 | .PP | |
254 | For the most part, the \fBPod::Parser\fR base class should be able to | |
255 | do most of the input parsing for you and leave you free to worry about | |
256 | how to intepret the commands and translate the result. | |
257 | .PP | |
258 | Note that all we have described here in this quick overview is the | |
259 | simplest most straightforward use of \fBPod::Parser\fR to do stream-based | |
260 | parsing. It is also possible to use the \fBPod::Parser::parse_text\fR function | |
261 | to do more sophisticated tree-based parsing. See \*(L"\s-1TREE\-BASED\s0 \s-1PARSING\s0\*(R". | |
262 | .SH "PARSING OPTIONS" | |
263 | .IX Header "PARSING OPTIONS" | |
264 | A \fIparse-option\fR is simply a named option of \fBPod::Parser\fR with a | |
265 | value that corresponds to a certain specified behavior. These various | |
266 | behaviors of \fBPod::Parser\fR may be enabled/disabled by setting | |
267 | or unsetting one or more \fIparse-options\fR using the \fB\f(BIparseopts()\fB\fR method. | |
268 | The set of currently accepted parse-options is as follows: | |
269 | .IP "\fB\-want_nonPODs\fR (default: unset)" 3 | |
270 | .IX Item "-want_nonPODs (default: unset)" | |
271 | Normally (by default) \fBPod::Parser\fR will only provide access to | |
272 | the \s-1POD\s0 sections of the input. Input paragraphs that are not part | |
273 | of the POD-format documentation are not made available to the caller | |
274 | (not even using \fB\f(BIpreprocess_paragraph()\fB\fR). Setting this option to a | |
275 | non\-empty, non-zero value will allow \fB\f(BIpreprocess_paragraph()\fB\fR to see | |
276 | non-POD sections of the input as well as \s-1POD\s0 sections. The \fB\f(BIcutting()\fB\fR | |
277 | method can be used to determine if the corresponding paragraph is a \s-1POD\s0 | |
278 | paragraph, or some other input paragraph. | |
279 | .IP "\fB\-process_cut_cmd\fR (default: unset)" 3 | |
280 | .IX Item "-process_cut_cmd (default: unset)" | |
281 | Normally (by default) \fBPod::Parser\fR handles the \f(CW\*(C`=cut\*(C'\fR \s-1POD\s0 directive | |
282 | by itself and does not pass it on to the caller for processing. Setting | |
283 | this option to a non\-empty, non-zero value will cause \fBPod::Parser\fR to | |
284 | pass the \f(CW\*(C`=cut\*(C'\fR directive to the caller just like any other \s-1POD\s0 command | |
285 | (and hence it may be processed by the \fB\f(BIcommand()\fB\fR method). | |
286 | .Sp | |
287 | \&\fBPod::Parser\fR will still interpret the \f(CW\*(C`=cut\*(C'\fR directive to mean that | |
288 | \&\*(L"cutting mode\*(R" has been (re)entered, but the caller will get a chance | |
289 | to capture the actual \f(CW\*(C`=cut\*(C'\fR paragraph itself for whatever purpose | |
290 | it desires. | |
291 | .IP "\fB\-warnings\fR (default: unset)" 3 | |
292 | .IX Item "-warnings (default: unset)" | |
293 | Normally (by default) \fBPod::Parser\fR recognizes a bare minimum of | |
294 | pod syntax errors and warnings and issues diagnostic messages | |
295 | for errors, but not for warnings. (Use \fBPod::Checker\fR to do more | |
296 | thorough checking of \s-1POD\s0 syntax.) Setting this option to a non\-empty, | |
297 | non-zero value will cause \fBPod::Parser\fR to issue diagnostics for | |
298 | the few warnings it recognizes as well as the errors. | |
299 | .PP | |
300 | Please see \*(L"\fIparseopts()\fR\*(R" for a complete description of the interface | |
301 | for the setting and unsetting of parse\-options. | |
302 | .SH "RECOMMENDED SUBROUTINE/METHOD OVERRIDES" | |
303 | .IX Header "RECOMMENDED SUBROUTINE/METHOD OVERRIDES" | |
304 | \&\fBPod::Parser\fR provides several methods which most subclasses will probably | |
305 | want to override. These methods are as follows: | |
306 | .SH "\fB\fP\f(BIcommand()\fP\fB\fP" | |
307 | .IX Header "command()" | |
308 | .Vb 1 | |
309 | \& $parser->command($cmd,$text,$line_num,$pod_para); | |
310 | .Ve | |
311 | .PP | |
312 | This method should be overridden by subclasses to take the appropriate | |
313 | action when a \s-1POD\s0 command paragraph (denoted by a line beginning with | |
314 | \&\*(L"=\*(R") is encountered. When such a \s-1POD\s0 directive is seen in the input, | |
315 | this method is called and is passed: | |
316 | .ie n .IP "$cmd" 3 | |
317 | .el .IP "\f(CW$cmd\fR" 3 | |
318 | .IX Item "$cmd" | |
319 | the name of the command for this \s-1POD\s0 paragraph | |
320 | .ie n .IP "$text" 3 | |
321 | .el .IP "\f(CW$text\fR" 3 | |
322 | .IX Item "$text" | |
323 | the paragraph text for the given \s-1POD\s0 paragraph command. | |
324 | .ie n .IP "$line_num" 3 | |
325 | .el .IP "\f(CW$line_num\fR" 3 | |
326 | .IX Item "$line_num" | |
327 | the line-number of the beginning of the paragraph | |
328 | .ie n .IP "$pod_para" 3 | |
329 | .el .IP "\f(CW$pod_para\fR" 3 | |
330 | .IX Item "$pod_para" | |
331 | a reference to a \f(CW\*(C`Pod::Paragraph\*(C'\fR object which contains further | |
332 | information about the paragraph command (see Pod::InputObjects | |
333 | for details). | |
334 | .PP | |
335 | \&\fBNote\fR that this method \fIis\fR called for \f(CW\*(C`=pod\*(C'\fR paragraphs. | |
336 | .PP | |
337 | The base class implementation of this method simply treats the raw \s-1POD\s0 | |
338 | command as normal block of paragraph text (invoking the \fB\f(BItextblock()\fB\fR | |
339 | method with the command paragraph). | |
340 | .SH "\fB\fP\f(BIverbatim()\fP\fB\fP" | |
341 | .IX Header "verbatim()" | |
342 | .Vb 1 | |
343 | \& $parser->verbatim($text,$line_num,$pod_para); | |
344 | .Ve | |
345 | .PP | |
346 | This method may be overridden by subclasses to take the appropriate | |
347 | action when a block of verbatim text is encountered. It is passed the | |
348 | following parameters: | |
349 | .ie n .IP "$text" 3 | |
350 | .el .IP "\f(CW$text\fR" 3 | |
351 | .IX Item "$text" | |
352 | the block of text for the verbatim paragraph | |
353 | .ie n .IP "$line_num" 3 | |
354 | .el .IP "\f(CW$line_num\fR" 3 | |
355 | .IX Item "$line_num" | |
356 | the line-number of the beginning of the paragraph | |
357 | .ie n .IP "$pod_para" 3 | |
358 | .el .IP "\f(CW$pod_para\fR" 3 | |
359 | .IX Item "$pod_para" | |
360 | a reference to a \f(CW\*(C`Pod::Paragraph\*(C'\fR object which contains further | |
361 | information about the paragraph (see Pod::InputObjects | |
362 | for details). | |
363 | .PP | |
364 | The base class implementation of this method simply prints the textblock | |
365 | (unmodified) to the output filehandle. | |
366 | .SH "\fB\fP\f(BItextblock()\fP\fB\fP" | |
367 | .IX Header "textblock()" | |
368 | .Vb 1 | |
369 | \& $parser->textblock($text,$line_num,$pod_para); | |
370 | .Ve | |
371 | .PP | |
372 | This method may be overridden by subclasses to take the appropriate | |
373 | action when a normal block of \s-1POD\s0 text is encountered (although the base | |
374 | class method will usually do what you want). It is passed the following | |
375 | parameters: | |
376 | .ie n .IP "$text" 3 | |
377 | .el .IP "\f(CW$text\fR" 3 | |
378 | .IX Item "$text" | |
379 | the block of text for the a \s-1POD\s0 paragraph | |
380 | .ie n .IP "$line_num" 3 | |
381 | .el .IP "\f(CW$line_num\fR" 3 | |
382 | .IX Item "$line_num" | |
383 | the line-number of the beginning of the paragraph | |
384 | .ie n .IP "$pod_para" 3 | |
385 | .el .IP "\f(CW$pod_para\fR" 3 | |
386 | .IX Item "$pod_para" | |
387 | a reference to a \f(CW\*(C`Pod::Paragraph\*(C'\fR object which contains further | |
388 | information about the paragraph (see Pod::InputObjects | |
389 | for details). | |
390 | .PP | |
391 | In order to process interior sequences, subclasses implementations of | |
392 | this method will probably want to invoke either \fB\f(BIinterpolate()\fB\fR or | |
393 | \&\fB\f(BIparse_text()\fB\fR, passing it the text block \f(CW$text\fR, and the corresponding | |
394 | line number in \f(CW$line_num\fR, and then perform any desired processing upon | |
395 | the returned result. | |
396 | .PP | |
397 | The base class implementation of this method simply prints the text block | |
398 | as it occurred in the input stream). | |
399 | .SH "\fB\fP\f(BIinterior_sequence()\fP\fB\fP" | |
400 | .IX Header "interior_sequence()" | |
401 | .Vb 1 | |
402 | \& $parser->interior_sequence($seq_cmd,$seq_arg,$pod_seq); | |
403 | .Ve | |
404 | .PP | |
405 | This method should be overridden by subclasses to take the appropriate | |
406 | action when an interior sequence is encountered. An interior sequence is | |
407 | an embedded command within a block of text which appears as a command | |
408 | name (usually a single uppercase character) followed immediately by a | |
409 | string of text which is enclosed in angle brackets. This method is | |
410 | passed the sequence command \f(CW$seq_cmd\fR and the corresponding text | |
411 | \&\f(CW$seq_arg\fR. It is invoked by the \fB\f(BIinterpolate()\fB\fR method for each interior | |
412 | sequence that occurs in the string that it is passed. It should return | |
413 | the desired text string to be used in place of the interior sequence. | |
414 | The \f(CW$pod_seq\fR argument is a reference to a \f(CW\*(C`Pod::InteriorSequence\*(C'\fR | |
415 | object which contains further information about the interior sequence. | |
416 | Please see Pod::InputObjects for details if you need to access this | |
417 | additional information. | |
418 | .PP | |
419 | Subclass implementations of this method may wish to invoke the | |
420 | \&\fB\f(BInested()\fB\fR method of \f(CW$pod_seq\fR to see if it is nested inside | |
421 | some other interior-sequence (and if so, which kind). | |
422 | .PP | |
423 | The base class implementation of the \fB\f(BIinterior_sequence()\fB\fR method | |
424 | simply returns the raw text of the interior sequence (as it occurred | |
425 | in the input) to the caller. | |
426 | .SH "OPTIONAL SUBROUTINE/METHOD OVERRIDES" | |
427 | .IX Header "OPTIONAL SUBROUTINE/METHOD OVERRIDES" | |
428 | \&\fBPod::Parser\fR provides several methods which subclasses may want to override | |
429 | to perform any special pre/post\-processing. These methods do \fInot\fR have to | |
430 | be overridden, but it may be useful for subclasses to take advantage of them. | |
431 | .SH "\fB\fP\f(BInew()\fP\fB\fP" | |
432 | .IX Header "new()" | |
433 | .Vb 1 | |
434 | \& my $parser = Pod::Parser->new(); | |
435 | .Ve | |
436 | .PP | |
437 | This is the constructor for \fBPod::Parser\fR and its subclasses. You | |
438 | \&\fIdo not\fR need to override this method! It is capable of constructing | |
439 | subclass objects as well as base class objects, provided you use | |
440 | any of the following constructor invocation styles: | |
441 | .PP | |
442 | .Vb 3 | |
443 | \& my $parser1 = MyParser->new(); | |
444 | \& my $parser2 = new MyParser(); | |
445 | \& my $parser3 = $parser2->new(); | |
446 | .Ve | |
447 | .PP | |
448 | where \f(CW\*(C`MyParser\*(C'\fR is some subclass of \fBPod::Parser\fR. | |
449 | .PP | |
450 | Using the syntax \f(CW\*(C`MyParser::new()\*(C'\fR to invoke the constructor is \fInot\fR | |
451 | recommended, but if you insist on being able to do this, then the | |
452 | subclass \fIwill\fR need to override the \fB\f(BInew()\fB\fR constructor method. If | |
453 | you do override the constructor, you \fImust\fR be sure to invoke the | |
454 | \&\fB\f(BIinitialize()\fB\fR method of the newly blessed object. | |
455 | .PP | |
456 | Using any of the above invocations, the first argument to the | |
457 | constructor is always the corresponding package name (or object | |
458 | reference). No other arguments are required, but if desired, an | |
459 | associative array (or hash\-table) my be passed to the \fB\f(BInew()\fB\fR | |
460 | constructor, as in: | |
461 | .PP | |
462 | .Vb 2 | |
463 | \& my $parser1 = MyParser->new( MYDATA => $value1, MOREDATA => $value2 ); | |
464 | \& my $parser2 = new MyParser( -myflag => 1 ); | |
465 | .Ve | |
466 | .PP | |
467 | All arguments passed to the \fB\f(BInew()\fB\fR constructor will be treated as | |
468 | key/value pairs in a hash\-table. The newly constructed object will be | |
469 | initialized by copying the contents of the given hash-table (which may | |
470 | have been empty). The \fB\f(BInew()\fB\fR constructor for this class and all of its | |
471 | subclasses returns a blessed reference to the initialized object (hash\-table). | |
472 | .SH "\fB\fP\f(BIinitialize()\fP\fB\fP" | |
473 | .IX Header "initialize()" | |
474 | .Vb 1 | |
475 | \& $parser->initialize(); | |
476 | .Ve | |
477 | .PP | |
478 | This method performs any necessary object initialization. It takes no | |
479 | arguments (other than the object instance of course, which is typically | |
480 | copied to a local variable named \f(CW$self\fR). If subclasses override this | |
481 | method then they \fImust\fR be sure to invoke \f(CW\*(C`$self\->SUPER::initialize()\*(C'\fR. | |
482 | .SH "\fB\fP\f(BIbegin_pod()\fP\fB\fP" | |
483 | .IX Header "begin_pod()" | |
484 | .Vb 1 | |
485 | \& $parser->begin_pod(); | |
486 | .Ve | |
487 | .PP | |
488 | This method is invoked at the beginning of processing for each \s-1POD\s0 | |
489 | document that is encountered in the input. Subclasses should override | |
490 | this method to perform any per-document initialization. | |
491 | .SH "\fB\fP\f(BIbegin_input()\fP\fB\fP" | |
492 | .IX Header "begin_input()" | |
493 | .Vb 1 | |
494 | \& $parser->begin_input(); | |
495 | .Ve | |
496 | .PP | |
497 | This method is invoked by \fB\f(BIparse_from_filehandle()\fB\fR immediately \fIbefore\fR | |
498 | processing input from a filehandle. The base class implementation does | |
499 | nothing, however, subclasses may override it to perform any per-file | |
500 | initializations. | |
501 | .PP | |
502 | Note that if multiple files are parsed for a single \s-1POD\s0 document | |
503 | (perhaps the result of some future \f(CW\*(C`=include\*(C'\fR directive) this method | |
504 | is invoked for every file that is parsed. If you wish to perform certain | |
505 | initializations once per document, then you should use \fB\f(BIbegin_pod()\fB\fR. | |
506 | .SH "\fB\fP\f(BIend_input()\fP\fB\fP" | |
507 | .IX Header "end_input()" | |
508 | .Vb 1 | |
509 | \& $parser->end_input(); | |
510 | .Ve | |
511 | .PP | |
512 | This method is invoked by \fB\f(BIparse_from_filehandle()\fB\fR immediately \fIafter\fR | |
513 | processing input from a filehandle. The base class implementation does | |
514 | nothing, however, subclasses may override it to perform any per-file | |
515 | cleanup actions. | |
516 | .PP | |
517 | Please note that if multiple files are parsed for a single \s-1POD\s0 document | |
518 | (perhaps the result of some kind of \f(CW\*(C`=include\*(C'\fR directive) this method | |
519 | is invoked for every file that is parsed. If you wish to perform certain | |
520 | cleanup actions once per document, then you should use \fB\f(BIend_pod()\fB\fR. | |
521 | .SH "\fB\fP\f(BIend_pod()\fP\fB\fP" | |
522 | .IX Header "end_pod()" | |
523 | .Vb 1 | |
524 | \& $parser->end_pod(); | |
525 | .Ve | |
526 | .PP | |
527 | This method is invoked at the end of processing for each \s-1POD\s0 document | |
528 | that is encountered in the input. Subclasses should override this method | |
529 | to perform any per-document finalization. | |
530 | .SH "\fB\fP\f(BIpreprocess_line()\fP\fB\fP" | |
531 | .IX Header "preprocess_line()" | |
532 | .Vb 1 | |
533 | \& $textline = $parser->preprocess_line($text, $line_num); | |
534 | .Ve | |
535 | .PP | |
536 | This method should be overridden by subclasses that wish to perform | |
537 | any kind of preprocessing for each \fIline\fR of input (\fIbefore\fR it has | |
538 | been determined whether or not it is part of a \s-1POD\s0 paragraph). The | |
539 | parameter \f(CW$text\fR is the input line; and the parameter \f(CW$line_num\fR is | |
540 | the line number of the corresponding text line. | |
541 | .PP | |
542 | The value returned should correspond to the new text to use in its | |
543 | place. If the empty string or an undefined value is returned then no | |
544 | further processing will be performed for this line. | |
545 | .PP | |
546 | Please note that the \fB\f(BIpreprocess_line()\fB\fR method is invoked \fIbefore\fR | |
547 | the \fB\f(BIpreprocess_paragraph()\fB\fR method. After all (possibly preprocessed) | |
548 | lines in a paragraph have been assembled together and it has been | |
549 | determined that the paragraph is part of the \s-1POD\s0 documentation from one | |
550 | of the selected sections, then \fB\f(BIpreprocess_paragraph()\fB\fR is invoked. | |
551 | .PP | |
552 | The base class implementation of this method returns the given text. | |
553 | .SH "\fB\fP\f(BIpreprocess_paragraph()\fP\fB\fP" | |
554 | .IX Header "preprocess_paragraph()" | |
555 | .Vb 1 | |
556 | \& $textblock = $parser->preprocess_paragraph($text, $line_num); | |
557 | .Ve | |
558 | .PP | |
559 | This method should be overridden by subclasses that wish to perform any | |
560 | kind of preprocessing for each block (paragraph) of \s-1POD\s0 documentation | |
561 | that appears in the input stream. The parameter \f(CW$text\fR is the \s-1POD\s0 | |
562 | paragraph from the input file; and the parameter \f(CW$line_num\fR is the | |
563 | line number for the beginning of the corresponding paragraph. | |
564 | .PP | |
565 | The value returned should correspond to the new text to use in its | |
566 | place If the empty string is returned or an undefined value is | |
567 | returned, then the given \f(CW$text\fR is ignored (not processed). | |
568 | .PP | |
569 | This method is invoked after gathering up all the lines in a paragraph | |
570 | and after determining the cutting state of the paragraph, | |
571 | but before trying to further parse or interpret them. After | |
572 | \&\fB\f(BIpreprocess_paragraph()\fB\fR returns, the current cutting state (which | |
573 | is returned by \f(CW\*(C`$self\->cutting()\*(C'\fR) is examined. If it evaluates | |
574 | to true then input text (including the given \f(CW$text\fR) is cut (not | |
575 | processed) until the next \s-1POD\s0 directive is encountered. | |
576 | .PP | |
577 | Please note that the \fB\f(BIpreprocess_line()\fB\fR method is invoked \fIbefore\fR | |
578 | the \fB\f(BIpreprocess_paragraph()\fB\fR method. After all (possibly preprocessed) | |
579 | lines in a paragraph have been assembled together and either it has been | |
580 | determined that the paragraph is part of the \s-1POD\s0 documentation from one | |
581 | of the selected sections or the \f(CW\*(C`\-want_nonPODs\*(C'\fR option is true, | |
582 | then \fB\f(BIpreprocess_paragraph()\fB\fR is invoked. | |
583 | .PP | |
584 | The base class implementation of this method returns the given text. | |
585 | .SH "METHODS FOR PARSING AND PROCESSING" | |
586 | .IX Header "METHODS FOR PARSING AND PROCESSING" | |
587 | \&\fBPod::Parser\fR provides several methods to process input text. These | |
588 | methods typically won't need to be overridden (and in some cases they | |
589 | can't be overridden), but subclasses may want to invoke them to exploit | |
590 | their functionality. | |
591 | .SH "\fB\fP\f(BIparse_text()\fP\fB\fP" | |
592 | .IX Header "parse_text()" | |
593 | .Vb 3 | |
594 | \& $ptree1 = $parser->parse_text($text, $line_num); | |
595 | \& $ptree2 = $parser->parse_text({%opts}, $text, $line_num); | |
596 | \& $ptree3 = $parser->parse_text(\e%opts, $text, $line_num); | |
597 | .Ve | |
598 | .PP | |
599 | This method is useful if you need to perform your own interpolation | |
600 | of interior sequences and can't rely upon \fBinterpolate\fR to expand | |
601 | them in simple bottom-up order. | |
602 | .PP | |
603 | The parameter \f(CW$text\fR is a string or block of text to be parsed | |
604 | for interior sequences; and the parameter \f(CW$line_num\fR is the | |
605 | line number curresponding to the beginning of \f(CW$text\fR. | |
606 | .PP | |
607 | \&\fB\f(BIparse_text()\fB\fR will parse the given text into a parse-tree of \*(L"nodes.\*(R" | |
608 | and interior\-sequences. Each \*(L"node\*(R" in the parse tree is either a | |
609 | text\-string, or a \fBPod::InteriorSequence\fR. The result returned is a | |
610 | parse-tree of type \fBPod::ParseTree\fR. Please see Pod::InputObjects | |
611 | for more information about \fBPod::InteriorSequence\fR and \fBPod::ParseTree\fR. | |
612 | .PP | |
613 | If desired, an optional hash-ref may be specified as the first argument | |
614 | to customize certain aspects of the parse-tree that is created and | |
615 | returned. The set of recognized option keywords are: | |
616 | .IP "\fB\-expand_seq\fR => \fIcode-ref\fR|\fImethod-name\fR" 3 | |
617 | .IX Item "-expand_seq => code-ref|method-name" | |
618 | Normally, the parse-tree returned by \fB\f(BIparse_text()\fB\fR will contain an | |
619 | unexpanded \f(CW\*(C`Pod::InteriorSequence\*(C'\fR object for each interior-sequence | |
620 | encountered. Specifying \fB\-expand_seq\fR tells \fB\f(BIparse_text()\fB\fR to \*(L"expand\*(R" | |
621 | every interior-sequence it sees by invoking the referenced function | |
622 | (or named method of the parser object) and using the return value as the | |
623 | expanded result. | |
624 | .Sp | |
625 | If a subroutine reference was given, it is invoked as: | |
626 | .Sp | |
627 | .Vb 1 | |
628 | \& &$code_ref( $parser, $sequence ) | |
629 | .Ve | |
630 | .Sp | |
631 | and if a method-name was given, it is invoked as: | |
632 | .Sp | |
633 | .Vb 1 | |
634 | \& $parser->method_name( $sequence ) | |
635 | .Ve | |
636 | .Sp | |
637 | where \f(CW$parser\fR is a reference to the parser object, and \f(CW$sequence\fR | |
638 | is a reference to the interior-sequence object. | |
639 | [\fI\s-1NOTE\s0\fR: If the \fB\f(BIinterior_sequence()\fB\fR method is specified, then it is | |
640 | invoked according to the interface specified in \*(L"\fIinterior_sequence()\fR\*(R"]. | |
641 | .IP "\fB\-expand_text\fR => \fIcode-ref\fR|\fImethod-name\fR" 3 | |
642 | .IX Item "-expand_text => code-ref|method-name" | |
643 | Normally, the parse-tree returned by \fB\f(BIparse_text()\fB\fR will contain a | |
644 | text-string for each contiguous sequence of characters outside of an | |
645 | interior\-sequence. Specifying \fB\-expand_text\fR tells \fB\f(BIparse_text()\fB\fR to | |
646 | \&\*(L"preprocess\*(R" every such text-string it sees by invoking the referenced | |
647 | function (or named method of the parser object) and using the return value | |
648 | as the preprocessed (or \*(L"expanded\*(R") result. [Note that if the result is | |
649 | an interior\-sequence, then it will \fInot\fR be expanded as specified by the | |
650 | \&\fB\-expand_seq\fR option; Any such recursive expansion needs to be handled by | |
651 | the specified callback routine.] | |
652 | .Sp | |
653 | If a subroutine reference was given, it is invoked as: | |
654 | .Sp | |
655 | .Vb 1 | |
656 | \& &$code_ref( $parser, $text, $ptree_node ) | |
657 | .Ve | |
658 | .Sp | |
659 | and if a method-name was given, it is invoked as: | |
660 | .Sp | |
661 | .Vb 1 | |
662 | \& $parser->method_name( $text, $ptree_node ) | |
663 | .Ve | |
664 | .Sp | |
665 | where \f(CW$parser\fR is a reference to the parser object, \f(CW$text\fR is the | |
666 | text-string encountered, and \f(CW$ptree_node\fR is a reference to the current | |
667 | node in the parse-tree (usually an interior-sequence object or else the | |
668 | top-level node of the parse\-tree). | |
669 | .IP "\fB\-expand_ptree\fR => \fIcode-ref\fR|\fImethod-name\fR" 3 | |
670 | .IX Item "-expand_ptree => code-ref|method-name" | |
671 | Rather than returning a \f(CW\*(C`Pod::ParseTree\*(C'\fR, pass the parse-tree as an | |
672 | argument to the referenced subroutine (or named method of the parser | |
673 | object) and return the result instead of the parse-tree object. | |
674 | .Sp | |
675 | If a subroutine reference was given, it is invoked as: | |
676 | .Sp | |
677 | .Vb 1 | |
678 | \& &$code_ref( $parser, $ptree ) | |
679 | .Ve | |
680 | .Sp | |
681 | and if a method-name was given, it is invoked as: | |
682 | .Sp | |
683 | .Vb 1 | |
684 | \& $parser->method_name( $ptree ) | |
685 | .Ve | |
686 | .Sp | |
687 | where \f(CW$parser\fR is a reference to the parser object, and \f(CW$ptree\fR | |
688 | is a reference to the parse-tree object. | |
689 | .SH "\fB\fP\f(BIinterpolate()\fP\fB\fP" | |
690 | .IX Header "interpolate()" | |
691 | .Vb 1 | |
692 | \& $textblock = $parser->interpolate($text, $line_num); | |
693 | .Ve | |
694 | .PP | |
695 | This method translates all text (including any embedded interior sequences) | |
696 | in the given text string \f(CW$text\fR and returns the interpolated result. The | |
697 | parameter \f(CW$line_num\fR is the line number corresponding to the beginning | |
698 | of \f(CW$text\fR. | |
699 | .PP | |
700 | \&\fB\f(BIinterpolate()\fB\fR merely invokes a private method to recursively expand | |
701 | nested interior sequences in bottom-up order (innermost sequences are | |
702 | expanded first). If there is a need to expand nested sequences in | |
703 | some alternate order, use \fBparse_text\fR instead. | |
704 | .SH "\fB\fP\f(BIparse_from_filehandle()\fP\fB\fP" | |
705 | .IX Header "parse_from_filehandle()" | |
706 | .Vb 1 | |
707 | \& $parser->parse_from_filehandle($in_fh,$out_fh); | |
708 | .Ve | |
709 | .PP | |
710 | This method takes an input filehandle (which is assumed to already be | |
711 | opened for reading) and reads the entire input stream looking for blocks | |
712 | (paragraphs) of \s-1POD\s0 documentation to be processed. If no first argument | |
713 | is given the default input filehandle \f(CW\*(C`STDIN\*(C'\fR is used. | |
714 | .PP | |
715 | The \f(CW$in_fh\fR parameter may be any object that provides a \fB\f(BIgetline()\fB\fR | |
716 | method to retrieve a single line of input text (hence, an appropriate | |
717 | wrapper object could be used to parse PODs from a single string or an | |
718 | array of strings). | |
719 | .PP | |
720 | Using \f(CW\*(C`$in_fh\->getline()\*(C'\fR, input is read line-by-line and assembled | |
721 | into paragraphs or \*(L"blocks\*(R" (which are separated by lines containing | |
722 | nothing but whitespace). For each block of \s-1POD\s0 documentation | |
723 | encountered it will invoke a method to parse the given paragraph. | |
724 | .PP | |
725 | If a second argument is given then it should correspond to a filehandle where | |
726 | output should be sent (otherwise the default output filehandle is | |
727 | \&\f(CW\*(C`STDOUT\*(C'\fR if no output filehandle is currently in use). | |
728 | .PP | |
729 | \&\fB\s-1NOTE:\s0\fR For performance reasons, this method caches the input stream at | |
730 | the top of the stack in a local variable. Any attempts by clients to | |
731 | change the stack contents during processing when in the midst executing | |
732 | of this method \fIwill not affect\fR the input stream used by the current | |
733 | invocation of this method. | |
734 | .PP | |
735 | This method does \fInot\fR usually need to be overridden by subclasses. | |
736 | .SH "\fB\fP\f(BIparse_from_file()\fP\fB\fP" | |
737 | .IX Header "parse_from_file()" | |
738 | .Vb 1 | |
739 | \& $parser->parse_from_file($filename,$outfile); | |
740 | .Ve | |
741 | .PP | |
742 | This method takes a filename and does the following: | |
743 | .IP "\(bu" 2 | |
744 | opens the input and output files for reading | |
745 | (creating the appropriate filehandles) | |
746 | .IP "\(bu" 2 | |
747 | invokes the \fB\f(BIparse_from_filehandle()\fB\fR method passing it the | |
748 | corresponding input and output filehandles. | |
749 | .IP "\(bu" 2 | |
750 | closes the input and output files. | |
751 | .PP | |
752 | If the special input filename \*(L"\-\*(R" or \*(L"<&STDIN\*(R" is given then the \s-1STDIN\s0 | |
753 | filehandle is used for input (and no open or close is performed). If no | |
754 | input filename is specified then \*(L"\-\*(R" is implied. | |
755 | .PP | |
756 | If a second argument is given then it should be the name of the desired | |
757 | output file. If the special output filename \*(L"\-\*(R" or \*(L">&STDOUT\*(R" is given | |
758 | then the \s-1STDOUT\s0 filehandle is used for output (and no open or close is | |
759 | performed). If the special output filename \*(L">&STDERR\*(R" is given then the | |
760 | \&\s-1STDERR\s0 filehandle is used for output (and no open or close is | |
761 | performed). If no output filehandle is currently in use and no output | |
762 | filename is specified, then \*(L"\-\*(R" is implied. | |
763 | Alternatively, an IO::String object is also accepted as an output | |
764 | file handle. | |
765 | .PP | |
766 | This method does \fInot\fR usually need to be overridden by subclasses. | |
767 | .SH "ACCESSOR METHODS" | |
768 | .IX Header "ACCESSOR METHODS" | |
769 | Clients of \fBPod::Parser\fR should use the following methods to access | |
770 | instance data fields: | |
771 | .SH "\fB\fP\f(BIerrorsub()\fP\fB\fP" | |
772 | .IX Header "errorsub()" | |
773 | .Vb 3 | |
774 | \& $parser->errorsub("method_name"); | |
775 | \& $parser->errorsub(\e&warn_user); | |
776 | \& $parser->errorsub(sub { print STDERR, @_ }); | |
777 | .Ve | |
778 | .PP | |
779 | Specifies the method or subroutine to use when printing error messages | |
780 | about \s-1POD\s0 syntax. The supplied method/subroutine \fImust\fR return \s-1TRUE\s0 upon | |
781 | successful printing of the message. If \f(CW\*(C`undef\*(C'\fR is given, then the \fBwarn\fR | |
782 | builtin is used to issue error messages (this is the default behavior). | |
783 | .PP | |
784 | .Vb 5 | |
785 | \& my $errorsub = $parser->errorsub() | |
786 | \& my $errmsg = "This is an error message!\en" | |
787 | \& (ref $errorsub) and &{$errorsub}($errmsg) | |
788 | \& or (defined $errorsub) and $parser->$errorsub($errmsg) | |
789 | \& or warn($errmsg); | |
790 | .Ve | |
791 | .PP | |
792 | Returns a method name, or else a reference to the user-supplied subroutine | |
793 | used to print error messages. Returns \f(CW\*(C`undef\*(C'\fR if the \fBwarn\fR builtin | |
794 | is used to issue error messages (this is the default behavior). | |
795 | .SH "\fB\fP\f(BIcutting()\fP\fB\fP" | |
796 | .IX Header "cutting()" | |
797 | .Vb 1 | |
798 | \& $boolean = $parser->cutting(); | |
799 | .Ve | |
800 | .PP | |
801 | Returns the current \f(CW\*(C`cutting\*(C'\fR state: a boolean-valued scalar which | |
802 | evaluates to true if text from the input file is currently being \*(L"cut\*(R" | |
803 | (meaning it is \fInot\fR considered part of the \s-1POD\s0 document). | |
804 | .PP | |
805 | .Vb 1 | |
806 | \& $parser->cutting($boolean); | |
807 | .Ve | |
808 | .PP | |
809 | Sets the current \f(CW\*(C`cutting\*(C'\fR state to the given value and returns the | |
810 | result. | |
811 | .SH "\fB\fP\f(BIparseopts()\fP\fB\fP" | |
812 | .IX Header "parseopts()" | |
813 | When invoked with no additional arguments, \fBparseopts\fR returns a hashtable | |
814 | of all the current parsing options. | |
815 | .PP | |
816 | .Vb 3 | |
817 | \& ## See if we are parsing non-POD sections as well as POD ones | |
818 | \& my %opts = $parser->parseopts(); | |
819 | \& $opts{'-want_nonPODs}' and print "-want_nonPODs\en"; | |
820 | .Ve | |
821 | .PP | |
822 | When invoked using a single string, \fBparseopts\fR treats the string as the | |
823 | name of a parse-option and returns its corresponding value if it exists | |
824 | (returns \f(CW\*(C`undef\*(C'\fR if it doesn't). | |
825 | .PP | |
826 | .Vb 3 | |
827 | \& ## Did we ask to see '=cut' paragraphs? | |
828 | \& my $want_cut = $parser->parseopts('-process_cut_cmd'); | |
829 | \& $want_cut and print "-process_cut_cmd\en"; | |
830 | .Ve | |
831 | .PP | |
832 | When invoked with multiple arguments, \fBparseopts\fR treats them as | |
833 | key/value pairs and the specified parse-option names are set to the | |
834 | given values. Any unspecified parse-options are unaffected. | |
835 | .PP | |
836 | .Vb 2 | |
837 | \& ## Set them back to the default | |
838 | \& $parser->parseopts(-warnings => 0); | |
839 | .Ve | |
840 | .PP | |
841 | When passed a single hash\-ref, \fBparseopts\fR uses that hash to completely | |
842 | reset the existing parse\-options, all previous parse-option values | |
843 | are lost. | |
844 | .PP | |
845 | .Vb 2 | |
846 | \& ## Reset all options to default | |
847 | \& $parser->parseopts( { } ); | |
848 | .Ve | |
849 | .PP | |
850 | See \*(L"\s-1PARSING\s0 \s-1OPTIONS\s0\*(R" for more information on the name and meaning of each | |
851 | parse-option currently recognized. | |
852 | .SH "\fB\fP\f(BIoutput_file()\fP\fB\fP" | |
853 | .IX Header "output_file()" | |
854 | .Vb 1 | |
855 | \& $fname = $parser->output_file(); | |
856 | .Ve | |
857 | .PP | |
858 | Returns the name of the output file being written. | |
859 | .SH "\fB\fP\f(BIoutput_handle()\fP\fB\fP" | |
860 | .IX Header "output_handle()" | |
861 | .Vb 1 | |
862 | \& $fhandle = $parser->output_handle(); | |
863 | .Ve | |
864 | .PP | |
865 | Returns the output filehandle object. | |
866 | .SH "\fB\fP\f(BIinput_file()\fP\fB\fP" | |
867 | .IX Header "input_file()" | |
868 | .Vb 1 | |
869 | \& $fname = $parser->input_file(); | |
870 | .Ve | |
871 | .PP | |
872 | Returns the name of the input file being read. | |
873 | .SH "\fB\fP\f(BIinput_handle()\fP\fB\fP" | |
874 | .IX Header "input_handle()" | |
875 | .Vb 1 | |
876 | \& $fhandle = $parser->input_handle(); | |
877 | .Ve | |
878 | .PP | |
879 | Returns the current input filehandle object. | |
880 | .SH "PRIVATE METHODS AND DATA" | |
881 | .IX Header "PRIVATE METHODS AND DATA" | |
882 | \&\fBPod::Parser\fR makes use of several internal methods and data fields | |
883 | which clients should not need to see or use. For the sake of avoiding | |
884 | name collisions for client data and methods, these methods and fields | |
885 | are briefly discussed here. Determined hackers may obtain further | |
886 | information about them by reading the \fBPod::Parser\fR source code. | |
887 | .PP | |
888 | Private data fields are stored in the hash-object whose reference is | |
889 | returned by the \fB\f(BInew()\fB\fR constructor for this class. The names of all | |
890 | private methods and data-fields used by \fBPod::Parser\fR begin with a | |
891 | prefix of \*(L"_\*(R" and match the regular expression \f(CW\*(C`/^_\ew+$/\*(C'\fR. | |
892 | .SH "TREE-BASED PARSING" | |
893 | .IX Header "TREE-BASED PARSING" | |
894 | If straightforward stream-based parsing wont meet your needs (as is | |
895 | likely the case for tasks such as translating PODs into structured | |
896 | markup languages like \s-1HTML\s0 and \s-1XML\s0) then you may need to take the | |
897 | tree-based approach. Rather than doing everything in one pass and | |
898 | calling the \fB\f(BIinterpolate()\fB\fR method to expand sequences into text, it | |
899 | may be desirable to instead create a parse-tree using the \fB\f(BIparse_text()\fB\fR | |
900 | method to return a tree-like structure which may contain an ordered | |
901 | list of children (each of which may be a text\-string, or a similar | |
902 | tree-like structure). | |
903 | .PP | |
904 | Pay special attention to \*(L"\s-1METHODS\s0 \s-1FOR\s0 \s-1PARSING\s0 \s-1AND\s0 \s-1PROCESSING\s0\*(R" and | |
905 | to the objects described in Pod::InputObjects. The former describes | |
906 | the gory details and parameters for how to customize and extend the | |
907 | parsing behavior of \fBPod::Parser\fR. \fBPod::InputObjects\fR provides | |
908 | several objects that may all be used interchangeably as parse\-trees. The | |
909 | most obvious one is the \fBPod::ParseTree\fR object. It defines the basic | |
910 | interface and functionality that all things trying to be a \s-1POD\s0 parse-tree | |
911 | should do. A \fBPod::ParseTree\fR is defined such that each \*(L"node\*(R" may be a | |
912 | text\-string, or a reference to another parse\-tree. Each \fBPod::Paragraph\fR | |
913 | object and each \fBPod::InteriorSequence\fR object also supports the basic | |
914 | parse-tree interface. | |
915 | .PP | |
916 | The \fB\f(BIparse_text()\fB\fR method takes a given paragraph of text, and | |
917 | returns a parse-tree that contains one or more children, each of which | |
918 | may be a text\-string, or an InteriorSequence object. There are also | |
919 | callback-options that may be passed to \fB\f(BIparse_text()\fB\fR to customize | |
920 | the way it expands or transforms interior\-sequences, as well as the | |
921 | returned result. These callbacks can be used to create a parse-tree | |
922 | with custom-made objects (which may or may not support the parse-tree | |
923 | interface, depending on how you choose to do it). | |
924 | .PP | |
925 | If you wish to turn an entire \s-1POD\s0 document into a parse\-tree, that process | |
926 | is fairly straightforward. The \fB\f(BIparse_text()\fB\fR method is the key to doing | |
927 | this successfully. Every paragraph-callback (i.e. the polymorphic methods | |
928 | for \fB\f(BIcommand()\fB\fR, \fB\f(BIverbatim()\fB\fR, and \fB\f(BItextblock()\fB\fR paragraphs) takes | |
929 | a \fBPod::Paragraph\fR object as an argument. Each paragraph object has a | |
930 | \&\fB\f(BIparse_tree()\fB\fR method that can be used to get or set a corresponding | |
931 | parse\-tree. So for each of those paragraph-callback methods, simply call | |
932 | \&\fB\f(BIparse_text()\fB\fR with the options you desire, and then use the returned | |
933 | parse-tree to assign to the given paragraph object. | |
934 | .PP | |
935 | That gives you a parse-tree for each paragraph \- so now all you need is | |
936 | an ordered list of paragraphs. You can maintain that yourself as a data | |
937 | element in the object/hash. The most straightforward way would be simply | |
938 | to use an array\-ref, with the desired set of custom \*(L"options\*(R" for each | |
939 | invocation of \fBparse_text\fR. Let's assume the desired option-set is | |
940 | given by the hash \f(CW%options\fR. Then we might do something like the | |
941 | following: | |
942 | .PP | |
943 | .Vb 1 | |
944 | \& package MyPodParserTree; | |
945 | .Ve | |
946 | .PP | |
947 | .Vb 1 | |
948 | \& @ISA = qw( Pod::Parser ); | |
949 | .Ve | |
950 | .PP | |
951 | .Vb 1 | |
952 | \& ... | |
953 | .Ve | |
954 | .PP | |
955 | .Vb 4 | |
956 | \& sub begin_pod { | |
957 | \& my $self = shift; | |
958 | \& $self->{'-paragraphs'} = []; ## initialize paragraph list | |
959 | \& } | |
960 | .Ve | |
961 | .PP | |
962 | .Vb 6 | |
963 | \& sub command { | |
964 | \& my ($parser, $command, $paragraph, $line_num, $pod_para) = @_; | |
965 | \& my $ptree = $parser->parse_text({%options}, $paragraph, ...); | |
966 | \& $pod_para->parse_tree( $ptree ); | |
967 | \& push @{ $self->{'-paragraphs'} }, $pod_para; | |
968 | \& } | |
969 | .Ve | |
970 | .PP | |
971 | .Vb 4 | |
972 | \& sub verbatim { | |
973 | \& my ($parser, $paragraph, $line_num, $pod_para) = @_; | |
974 | \& push @{ $self->{'-paragraphs'} }, $pod_para; | |
975 | \& } | |
976 | .Ve | |
977 | .PP | |
978 | .Vb 6 | |
979 | \& sub textblock { | |
980 | \& my ($parser, $paragraph, $line_num, $pod_para) = @_; | |
981 | \& my $ptree = $parser->parse_text({%options}, $paragraph, ...); | |
982 | \& $pod_para->parse_tree( $ptree ); | |
983 | \& push @{ $self->{'-paragraphs'} }, $pod_para; | |
984 | \& } | |
985 | .Ve | |
986 | .PP | |
987 | .Vb 1 | |
988 | \& ... | |
989 | .Ve | |
990 | .PP | |
991 | .Vb 5 | |
992 | \& package main; | |
993 | \& ... | |
994 | \& my $parser = new MyPodParserTree(...); | |
995 | \& $parser->parse_from_file(...); | |
996 | \& my $paragraphs_ref = $parser->{'-paragraphs'}; | |
997 | .Ve | |
998 | .PP | |
999 | Of course, in this module\-author's humble opinion, I'd be more inclined to | |
1000 | use the existing \fBPod::ParseTree\fR object than a simple array. That way | |
1001 | everything in it, paragraphs and sequences, all respond to the same core | |
1002 | interface for all parse-tree nodes. The result would look something like: | |
1003 | .PP | |
1004 | .Vb 1 | |
1005 | \& package MyPodParserTree2; | |
1006 | .Ve | |
1007 | .PP | |
1008 | .Vb 1 | |
1009 | \& ... | |
1010 | .Ve | |
1011 | .PP | |
1012 | .Vb 4 | |
1013 | \& sub begin_pod { | |
1014 | \& my $self = shift; | |
1015 | \& $self->{'-ptree'} = new Pod::ParseTree; ## initialize parse-tree | |
1016 | \& } | |
1017 | .Ve | |
1018 | .PP | |
1019 | .Vb 5 | |
1020 | \& sub parse_tree { | |
1021 | \& ## convenience method to get/set the parse-tree for the entire POD | |
1022 | \& (@_ > 1) and $_[0]->{'-ptree'} = $_[1]; | |
1023 | \& return $_[0]->{'-ptree'}; | |
1024 | \& } | |
1025 | .Ve | |
1026 | .PP | |
1027 | .Vb 6 | |
1028 | \& sub command { | |
1029 | \& my ($parser, $command, $paragraph, $line_num, $pod_para) = @_; | |
1030 | \& my $ptree = $parser->parse_text({<<options>>}, $paragraph, ...); | |
1031 | \& $pod_para->parse_tree( $ptree ); | |
1032 | \& $parser->parse_tree()->append( $pod_para ); | |
1033 | \& } | |
1034 | .Ve | |
1035 | .PP | |
1036 | .Vb 4 | |
1037 | \& sub verbatim { | |
1038 | \& my ($parser, $paragraph, $line_num, $pod_para) = @_; | |
1039 | \& $parser->parse_tree()->append( $pod_para ); | |
1040 | \& } | |
1041 | .Ve | |
1042 | .PP | |
1043 | .Vb 6 | |
1044 | \& sub textblock { | |
1045 | \& my ($parser, $paragraph, $line_num, $pod_para) = @_; | |
1046 | \& my $ptree = $parser->parse_text({<<options>>}, $paragraph, ...); | |
1047 | \& $pod_para->parse_tree( $ptree ); | |
1048 | \& $parser->parse_tree()->append( $pod_para ); | |
1049 | \& } | |
1050 | .Ve | |
1051 | .PP | |
1052 | .Vb 1 | |
1053 | \& ... | |
1054 | .Ve | |
1055 | .PP | |
1056 | .Vb 6 | |
1057 | \& package main; | |
1058 | \& ... | |
1059 | \& my $parser = new MyPodParserTree2(...); | |
1060 | \& $parser->parse_from_file(...); | |
1061 | \& my $ptree = $parser->parse_tree; | |
1062 | \& ... | |
1063 | .Ve | |
1064 | .PP | |
1065 | Now you have the entire \s-1POD\s0 document as one great big parse\-tree. You | |
1066 | can even use the \fB\-expand_seq\fR option to \fBparse_text\fR to insert | |
1067 | whole different kinds of objects. Just don't expect \fBPod::Parser\fR | |
1068 | to know what to do with them after that. That will need to be in your | |
1069 | code. Or, alternatively, you can insert any object you like so long as | |
1070 | it conforms to the \fBPod::ParseTree\fR interface. | |
1071 | .PP | |
1072 | One could use this to create subclasses of \fBPod::Paragraphs\fR and | |
1073 | \&\fBPod::InteriorSequences\fR for specific commands (or to create your own | |
1074 | custom node-types in the parse\-tree) and add some kind of \fB\f(BIemit()\fB\fR | |
1075 | method to each custom node/subclass object in the tree. Then all you'd | |
1076 | need to do is recursively walk the tree in the desired order, processing | |
1077 | the children (most likely from left to right) by formatting them if | |
1078 | they are text\-strings, or by calling their \fB\f(BIemit()\fB\fR method if they | |
1079 | are objects/references. | |
1080 | .SH "SEE ALSO" | |
1081 | .IX Header "SEE ALSO" | |
1082 | Pod::InputObjects, Pod::Select | |
1083 | .PP | |
1084 | \&\fBPod::InputObjects\fR defines \s-1POD\s0 input objects corresponding to | |
1085 | command paragraphs, parse\-trees, and interior\-sequences. | |
1086 | .PP | |
1087 | \&\fBPod::Select\fR is a subclass of \fBPod::Parser\fR which provides the ability | |
1088 | to selectively include and/or exclude sections of a \s-1POD\s0 document from being | |
1089 | translated based upon the current heading, subheading, subsubheading, etc. | |
1090 | .SH "AUTHOR" | |
1091 | .IX Header "AUTHOR" | |
1092 | Please report bugs using <http://rt.cpan.org>. | |
1093 | .PP | |
1094 | Brad Appleton <bradapp@enteract.com> | |
1095 | .PP | |
1096 | Based on code for \fBPod::Text\fR written by | |
1097 | Tom Christiansen <tchrist@mox.perl.com> |