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 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, otherwise you should probably do something
41           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 your parsing adheres to a consistent indentation policy,
152           you can have such indentation stripped from the beginning of every
153           line of your verbatim blocks. This method tells Pod::Simple what to
154           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->detected_encoding()"
247           Return the encoding corresponding to "=encoding", but only if the
248           encoding was recognized and handled.
249
250       "$parser->encoding()"
251           Return encoding of the document, even if the encoding is not
252           correctly handled.
253
254       "$parser->parse_from_file( $source, $to )"
255           Parses from $source file to $to file. Similar to "parse_from_file"
256           in Pod::Parser.
257
258       "$parser->scream( @error_messages )"
259           Log an error that can't be ignored.
260
261       "$parser->unaccept_code( @codes )"
262           Alias for unaccept_codes.
263
264       "$parser->unaccept_codes( @codes )"
265           Removes @codes as valid codes for the parse.
266
267       "$parser->unaccept_directive( @directives )"
268           Alias for unaccept_directives.
269
270       "$parser->unaccept_directives( @directives )"
271           Removes @directives as valid directives for the parse.
272
273       "$parser->unaccept_target( @targets )"
274           Alias for unaccept_targets.
275
276       "$parser->unaccept_targets( @targets )"
277           Removes @targets as valid targets for the parse.
278
279       "$parser->version_report()"
280           Returns a string describing the version.
281
282       "$parser->whine( @error_messages )"
283           Log an error unless "$parser->no_whining( TRUE );".
284

ENCODING

286       The Pod::Simple parser expects to read octets.  The parser will decode
287       the octets into Perl's internal character string representation using
288       the value of the "=encoding" declaration in the POD source.
289
290       If the POD source does not include an "=encoding" declaration, the
291       parser will attempt to guess the encoding (selecting one of UTF-8 or
292       Latin-1) by examining the first non-ASCII bytes and applying the
293       heuristic described in perlpodspec.
294
295       If you set the "parse_characters" option to a true value the parser
296       will expect characters rather than octets; will ignore any "=encoding";
297       and will make no attempt to decode the input.
298

CAVEATS

300       This is just a beta release -- there are a good number of things still
301       left to do.  Notably, support for EBCDIC platforms is still half-done,
302       an untested.
303

SEE ALSO

305       Pod::Simple::Subclassing
306
307       perlpod
308
309       perlpodspec
310
311       Pod::Escapes
312
313       perldoc
314

SUPPORT

316       Questions or discussion about POD and Pod::Simple should be sent to the
317       pod-people@perl.org mail list. Send an empty email to
318       pod-people-subscribe@perl.org to subscribe.
319
320       This module is managed in an open GitHub repository,
321       <https://github.com/theory/pod-simple/>. Feel free to fork and
322       contribute, or to clone <git://github.com/theory/pod-simple.git> and
323       send patches!
324
325       Patches against Pod::Simple are welcome. Please send bug reports to
326       <bug-pod-simple@rt.cpan.org>.
327
329       Copyright (c) 2002 Sean M. Burke.
330
331       This library is free software; you can redistribute it and/or modify it
332       under the same terms as Perl itself.
333
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

AUTHOR

339       Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.  But don't
340       bother him, he's retired.
341
342       Pod::Simple is maintained by:
343
344       ·   Allison Randal "allison@perl.org"
345
346       ·   Hans Dieter Pearcey "hdp@cpan.org"
347
348       ·   David E. Wheeler "dwheeler@cpan.org"
349
350       Documentation has been contributed by:
351
352       ·   Gabor Szabo "szabgab@gmail.com"
353
354       ·   Shawn H Corey  "SHCOREY at cpan.org"
355
356
357
358perl v5.16.3                      2013-05-02                    Pod::Simple(3)
Impressum