1Pod::Simple(3)        User Contributed Perl Documentation       Pod::Simple(3)
2
3
4

NAME

6       Pod::Simple - framework for parsing Pod
7

SYNOPSIS

9        TODO
10

DESCRIPTION

12       Pod::Simple is a Perl library for parsing text in the Pod ("plain old
13       documentation") markup language that is typically used for writing
14       documentation for Perl and for Perl modules. The Pod format is
15       explained in perlpod; the most common formatter is called "perldoc".
16
17       Be sure to read "ENCODING" if your Pod contains non-ASCII characters.
18
19       Pod formatters can use Pod::Simple to parse Pod documents and render
20       them into plain text, HTML, or any number of other formats. Typically,
21       such formatters will be subclasses of Pod::Simple, and so they will
22       inherit its methods, like "parse_file".
23
24       If you're reading this document just because you have a Pod-processing
25       subclass that you want to use, this document (plus the documentation
26       for the subclass) is probably all you need to read.
27
28       If you're reading this document because you want to write a formatter
29       subclass, continue reading it and then read Pod::Simple::Subclassing,
30       and then possibly even read perlpodspec (some of which is for parser-
31       writers, but much of which is notes to formatter-writers).
32

MAIN METHODS

34       "$parser = SomeClass->new();"
35           This returns a new parser object, where "SomeClass" is a subclass
36           of Pod::Simple.
37
38       "$parser->output_fh( *OUT );"
39           This sets the filehandle that $parser's output will be written to.
40           You can pass *STDOUT or *STDERR, otherwise you should probably do
41           something like this:
42
43               my $outfile = "output.txt";
44               open TXTOUT, ">$outfile" or die "Can't write to $outfile: $!";
45               $parser->output_fh(*TXTOUT);
46
47           ...before you call one of the "$parser->parse_whatever" methods.
48
49       "$parser->output_string( \$somestring );"
50           This sets the string that $parser's output will be sent to, instead
51           of any filehandle.
52
53       "$parser->parse_file( $some_filename );"
54       "$parser->parse_file( *INPUT_FH );"
55           This reads the Pod content of the file (or filehandle) that you
56           specify, and processes it with that $parser object, according to
57           however $parser's class works, and according to whatever parser
58           options you have set up for this $parser object.
59
60       "$parser->parse_string_document( $all_content );"
61           This works just like "parse_file" except that it reads the Pod
62           content not from a file, but from a string that you have already in
63           memory.
64
65       "$parser->parse_lines( ...@lines..., undef );"
66           This processes the lines in @lines (where each list item must be a
67           defined value, and must contain exactly one line of content -- so
68           no items like "foo\nbar" are allowed).  The final "undef" is used
69           to indicate the end of document being parsed.
70
71           The other "parser_whatever" methods are meant to be called only
72           once per $parser object; but "parse_lines" can be called as many
73           times per $parser object as you want, as long as the last call (and
74           only the last call) ends with an "undef" value.
75
76       "$parser->content_seen"
77           This returns true only if there has been any real content seen for
78           this document. Returns false in cases where the document contains
79           content, but does not make use of any Pod markup.
80
81       "SomeClass->filter( $filename );"
82       "SomeClass->filter( *INPUT_FH );"
83       "SomeClass->filter( \$document_content );"
84           This is a shortcut method for creating a new parser object, setting
85           the output handle to STDOUT, and then processing the specified file
86           (or filehandle, or in-memory document). This is handy for one-
87           liners like this:
88
89             perl -MPod::Simple::Text -e "Pod::Simple::Text->filter('thingy.pod')"
90

SECONDARY METHODS

92       Some of these methods might be of interest to general users, as well as
93       of interest to formatter-writers.
94
95       Note that the general pattern here is that the accessor-methods read
96       the attribute's value with "$value = $parser->attribute" and set the
97       attribute's value with "$parser->attribute(newvalue)".  For each
98       accessor, I typically only mention one syntax or another, based on
99       which I think you are actually most likely to use.
100
101       "$parser->parse_characters( SOMEVALUE )"
102           The Pod parser normally expects to read octets and to convert those
103           octets to characters based on the "=encoding" declaration in the
104           Pod source.  Set this option to a true value to indicate that the
105           Pod source is already a Perl character stream.  This tells the
106           parser to ignore any "=encoding" command and to skip all the code
107           paths involving decoding octets.
108
109       "$parser->no_whining( SOMEVALUE )"
110           If you set this attribute to a true value, you will suppress the
111           parser's complaints about irregularities in the Pod coding. By
112           default, this attribute's value is false, meaning that
113           irregularities will be reported.
114
115           Note that turning this attribute to true won't suppress one or two
116           kinds of complaints about rarely occurring unrecoverable errors.
117
118       "$parser->no_errata_section( SOMEVALUE )"
119           If you set this attribute to a true value, you will stop the parser
120           from generating a "POD ERRORS" section at the end of the document.
121           By default, this attribute's value is false, meaning that an errata
122           section will be generated, as necessary.
123
124       "$parser->complain_stderr( SOMEVALUE )"
125           If you set this attribute to a true value, it will send reports of
126           parsing errors to STDERR. By default, this attribute's value is
127           false, meaning that no output is sent to STDERR.
128
129           Setting "complain_stderr" also sets "no_errata_section".
130
131       "$parser->source_filename"
132           This returns the filename that this parser object was set to read
133           from.
134
135       "$parser->doc_has_started"
136           This returns true if $parser has read from a source, and has seen
137           Pod content in it.
138
139       "$parser->source_dead"
140           This returns true if $parser has read from a source, and come to
141           the end of that source.
142
143       "$parser->strip_verbatim_indent( SOMEVALUE )"
144           The perlpod spec for a Verbatim paragraph is "It should be
145           reproduced exactly...", which means that the whitespace you've used
146           to indent your verbatim blocks will be preserved in the output.
147           This can be annoying for outputs such as HTML, where that
148           whitespace will remain in front of every line. It's an unfortunate
149           case where syntax is turned into semantics.
150
151           If the POD you're parsing adheres to a consistent indentation
152           policy, you can have such indentation stripped from the beginning
153           of every line of your verbatim blocks. This method tells
154           Pod::Simple what to strip. For two-space indents, you'd use:
155
156             $parser->strip_verbatim_indent('  ');
157
158           For tab indents, you'd use a tab character:
159
160             $parser->strip_verbatim_indent("\t");
161
162           If the POD is inconsistent about the indentation of verbatim
163           blocks, but you have figured out a heuristic to determine how much
164           a particular verbatim block is indented, you can pass a code
165           reference instead. The code reference will be executed with one
166           argument, an array reference of all the lines in the verbatim
167           block, and should return the value to be stripped from each line.
168           For example, if you decide that you're fine to use the first line
169           of the verbatim block to set the standard for indentation of the
170           rest of the block, you can look at the first line and return the
171           appropriate value, like so:
172
173             $new->strip_verbatim_indent(sub {
174                 my $lines = shift;
175                 (my $indent = $lines->[0]) =~ s/\S.*//;
176                 return $indent;
177             });
178
179           If you'd rather treat each line individually, you can do that, too,
180           by just transforming them in-place in the code reference and
181           returning "undef". Say that you don't want any lines indented. You
182           can do something like this:
183
184             $new->strip_verbatim_indent(sub {
185                 my $lines = shift;
186                 sub { s/^\s+// for @{ $lines },
187                 return undef;
188             });
189

TERTIARY METHODS

191       "$parser->abandon_output_fh()"
192           Cancel output to the file handle. Any POD read by the $parser is
193           not effected.
194
195       "$parser->abandon_output_string()"
196           Cancel output to the output string. Any POD read by the $parser is
197           not effected.
198
199       "$parser->accept_code( @codes )"
200           Alias for accept_codes.
201
202       "$parser->accept_codes( @codes )"
203           Allows $parser to accept a list of "Formatting Codes" in perlpod.
204           This can be used to implement user-defined codes.
205
206       "$parser->accept_directive_as_data( @directives )"
207           Allows $parser to accept a list of directives for data paragraphs.
208           A directive is the label of a "Command Paragraph" in perlpod. A
209           data paragraph is one delimited by "=begin/=for/=end" directives.
210           This can be used to implement user-defined directives.
211
212       "$parser->accept_directive_as_processed( @directives )"
213           Allows $parser to accept a list of directives for processed
214           paragraphs. A directive is the label of a "Command Paragraph" in
215           perlpod. A processed paragraph is also known as "Ordinary
216           Paragraph" in perlpod. This can be used to implement user-defined
217           directives.
218
219       "$parser->accept_directive_as_verbatim( @directives )"
220           Allows $parser to accept a list of directives for "Verbatim
221           Paragraph" in perlpod. A directive is the label of a "Command
222           Paragraph" in perlpod. This can be used to implement user-defined
223           directives.
224
225       "$parser->accept_target( @targets )"
226           Alias for accept_targets.
227
228       "$parser->accept_target_as_text( @targets )"
229           Alias for accept_targets_as_text.
230
231       "$parser->accept_targets( @targets )"
232           Accepts targets for "=begin/=for/=end" sections of the POD.
233
234       "$parser->accept_targets_as_text( @targets )"
235           Accepts targets for "=begin/=for/=end" sections that should be
236           parsed as POD. For details, see "About Data Paragraphs" in
237           perlpodspec.
238
239       "$parser->any_errata_seen()"
240           Used to check if any errata was seen.
241
242           Example:
243
244             die "too many errors\n" if $parser->any_errata_seen();
245
246       "$parser->errata_seen()"
247           Returns a hash reference of all errata seen, both whines and
248           screams. The hash reference's keys are the line number and the
249           value is an array reference of the errors for that line.
250
251           Example:
252
253             if ( $parser->any_errata_seen() ) {
254                $logger->log( $parser->errata_seen() );
255             }
256
257       "$parser->detected_encoding()"
258           Return the encoding corresponding to "=encoding", but only if the
259           encoding was recognized and handled.
260
261       "$parser->encoding()"
262           Return encoding of the document, even if the encoding is not
263           correctly handled.
264
265       "$parser->parse_from_file( $source, $to )"
266           Parses from $source file to $to file. Similar to "parse_from_file"
267           in Pod::Parser.
268
269       "$parser->scream( @error_messages )"
270           Log an error that can't be ignored.
271
272       "$parser->unaccept_code( @codes )"
273           Alias for unaccept_codes.
274
275       "$parser->unaccept_codes( @codes )"
276           Removes @codes as valid codes for the parse.
277
278       "$parser->unaccept_directive( @directives )"
279           Alias for unaccept_directives.
280
281       "$parser->unaccept_directives( @directives )"
282           Removes @directives as valid directives for the parse.
283
284       "$parser->unaccept_target( @targets )"
285           Alias for unaccept_targets.
286
287       "$parser->unaccept_targets( @targets )"
288           Removes @targets as valid targets for the parse.
289
290       "$parser->version_report()"
291           Returns a string describing the version.
292
293       "$parser->whine( @error_messages )"
294           Log an error unless "$parser->no_whining( TRUE );".
295

ENCODING

297       The Pod::Simple parser expects to read octets.  The parser will decode
298       the octets into Perl's internal character string representation using
299       the value of the "=encoding" declaration in the POD source.
300
301       If the POD source does not include an "=encoding" declaration, the
302       parser will attempt to guess the encoding (selecting one of UTF-8 or CP
303       1252) by examining the first non-ASCII bytes and applying the heuristic
304       described in perlpodspec.  (If the POD source contains only ASCII
305       bytes, the encoding is assumed to be ASCII.)
306
307       If you set the "parse_characters" option to a true value the parser
308       will expect characters rather than octets; will ignore any "=encoding";
309       and will make no attempt to decode the input.
310

SEE ALSO

312       Pod::Simple::Subclassing
313
314       perlpod
315
316       perlpodspec
317
318       Pod::Escapes
319
320       perldoc
321

SUPPORT

323       Questions or discussion about POD and Pod::Simple should be sent to the
324       pod-people@perl.org mail list. Send an empty email to
325       pod-people-subscribe@perl.org to subscribe.
326
327       This module is managed in an open GitHub repository,
328       <https://github.com/perl-pod/pod-simple/>. Feel free to fork and
329       contribute, or to clone <git://github.com/perl-pod/pod-simple.git> and
330       send patches!
331
332       Patches against Pod::Simple are welcome. Please send bug reports to
333       <bug-pod-simple@rt.cpan.org>.
334
336       Copyright (c) 2002 Sean M. Burke.
337
338       This library is free software; you can redistribute it and/or modify it
339       under the same terms as Perl itself.
340
341       This program is distributed in the hope that it will be useful, but
342       without any warranty; without even the implied warranty of
343       merchantability or fitness for a particular purpose.
344

AUTHOR

346       Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.  But don't
347       bother him, he's retired.
348
349       Pod::Simple is maintained by:
350
351       ·   Allison Randal "allison@perl.org"
352
353       ·   Hans Dieter Pearcey "hdp@cpan.org"
354
355       ·   David E. Wheeler "dwheeler@cpan.org"
356
357       Documentation has been contributed by:
358
359       ·   Gabor Szabo "szabgab@gmail.com"
360
361       ·   Shawn H Corey  "SHCOREY at cpan.org"
362
363
364
365perl v5.26.3                      2016-11-29                    Pod::Simple(3)
Impressum