ndk/prebuilt/linux-x86_64/lib/perl5/5.16.2/Pod/Simple.pod

   1
   2 =head1 NAME
   3
   4 Pod::Simple - framework for parsing Pod
   5
   6 =head1 SYNOPSIS
   7
   8  TODO
   9
  10 =head1 DESCRIPTION
  11
  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 explained
  15 L<perlpod>; the most common formatter is called C<perldoc>.
  16
  17 Pod formatters can use Pod::Simple to parse Pod documents and render them into
  18 plain text, HTML, or any number of other formats. Typically, such formatters
  19 will be subclasses of Pod::Simple, and so they will inherit its methods, like
  20 C<parse_file>.
  21
  22 If you're reading this document just because you have a Pod-processing
  23 subclass that you want to use, this document (plus the documentation for the
  24 subclass) is probably all you need to read.
  25
  26 If you're reading this document because you want to write a formatter
  27 subclass, continue reading it and then read L<Pod::Simple::Subclassing>, and
  28 then possibly even read L<perlpodspec> (some of which is for parser-writers,
  29 but much of which is notes to formatter-writers).
  30
  31 =head1 MAIN METHODS
  32
  33 =over
  34
  35 =item C<< $parser = I<SomeClass>->new(); >>
  36
  37 This returns a new parser object, where I<C<SomeClass>> is a subclass
  38 of Pod::Simple.
  39
  40 =item C<< $parser->output_fh( *OUT ); >>
  41
  42 This sets the filehandle that C<$parser>'s output will be written to.
  43 You can pass C<*STDOUT>, otherwise you should probably do something
  44 like this:
  45
  46     my $outfile = "output.txt";
  47     open TXTOUT, ">$outfile" or die "Can't write to $outfile: $!";
  48     $parser->output_fh(*TXTOUT);
  49
  50 ...before you call one of the C<< $parser->parse_I<whatever> >> methods.
  51
  52 =item C<< $parser->output_string( \$somestring ); >>
  53
  54 This sets the string that C<$parser>'s output will be sent to,
  55 instead of any filehandle.
  56
  57
  58 =item C<< $parser->parse_file( I<$some_filename> ); >>
  59
  60 =item C<< $parser->parse_file( *INPUT_FH ); >>
  61
  62 This reads the Pod content of the file (or filehandle) that you specify,
  63 and processes it with that C<$parser> object, according to however
  64 C<$parser>'s class works, and according to whatever parser options you
  65 have set up for this C<$parser> object.
  66
  67 =item C<< $parser->parse_string_document( I<$all_content> ); >>
  68
  69 This works just like C<parse_file> except that it reads the Pod
  70 content not from a file, but from a string that you have already
  71 in memory.
  72
  73 =item C<< $parser->parse_lines( I<...@lines...>, undef ); >>
  74
  75 This processes the lines in C<@lines> (where each list item must be a
  76 defined value, and must contain exactly one line of content -- so no
  77 items like C<"foo\nbar"> are allowed).  The final C<undef> is used to
  78 indicate the end of document being parsed.
  79
  80 The other C<parser_I<whatever>> methods are meant to be called only once
  81 per C<$parser> object; but C<parse_lines> can be called as many times per
  82 C<$parser> object as you want, as long as the last call (and only
  83 the last call) ends with an C<undef> value.
  84
  85
  86 =item C<< $parser->content_seen >>
  87
  88 This returns true only if there has been any real content seen for this
  89 document. Returns false in cases where the document contains content,
  90 but does not make use of any Pod markup.
  91
  92 =item C<< I<SomeClass>->filter( I<$filename> ); >>
  93
  94 =item C<< I<SomeClass>->filter( I<*INPUT_FH> ); >>
  95
  96 =item C<< I<SomeClass>->filter( I<\$document_content> ); >>
  97
  98 This is a shortcut method for creating a new parser object, setting the
  99 output handle to STDOUT, and then processing the specified file (or
 100 filehandle, or in-memory document). This is handy for one-liners like
 101 this:
 102
 103   perl -MPod::Simple::Text -e "Pod::Simple::Text->filter('thingy.pod')"
 104
 105 =back
 106
 107
 108
 109 =head1 SECONDARY METHODS
 110
 111 Some of these methods might be of interest to general users, as
 112 well as of interest to formatter-writers.
 113
 114 Note that the general pattern here is that the accessor-methods
 115 read the attribute's value with C<< $value = $parser->I<attribute> >>
 116 and set the attribute's value with
 117 C<< $parser->I<attribute>(I<newvalue>) >>.  For each accessor, I typically
 118 only mention one syntax or another, based on which I think you are actually
 119 most likely to use.
 120
 121
 122 =over
 123
 124 =item C<< $parser->no_whining( I<SOMEVALUE> ) >>
 125
 126 If you set this attribute to a true value, you will suppress the
 127 parser's complaints about irregularities in the Pod coding. By default,
 128 this attribute's value is false, meaning that irregularities will
 129 be reported.
 130
 131 Note that turning this attribute to true won't suppress one or two kinds
 132 of complaints about rarely occurring unrecoverable errors.
 133
 134
 135 =item C<< $parser->no_errata_section( I<SOMEVALUE> ) >>
 136
 137 If you set this attribute to a true value, you will stop the parser from
 138 generating a "POD ERRORS" section at the end of the document. By
 139 default, this attribute's value is false, meaning that an errata section
 140 will be generated, as necessary.
 141
 142
 143 =item C<< $parser->complain_stderr( I<SOMEVALUE> ) >>
 144
 145 If you set this attribute to a true value, it will send reports of
 146 parsing errors to STDERR. By default, this attribute's value is false,
 147 meaning that no output is sent to STDERR.
 148
 149 Setting C<complain_stderr> also sets C<no_errata_section>.
 150
 151
 152 =item C<< $parser->source_filename >>
 153
 154 This returns the filename that this parser object was set to read from.
 155
 156
 157 =item C<< $parser->doc_has_started >>
 158
 159 This returns true if C<$parser> has read from a source, and has seen
 160 Pod content in it.
 161
 162
 163 =item C<< $parser->source_dead >>
 164
 165 This returns true if C<$parser> has read from a source, and come to the
 166 end of that source.
 167
 168 =item C<< $parser->strip_verbatim_indent( I<SOMEVALUE> ) >>
 169
 170 The perlpod spec for a Verbatim paragraph is "It should be reproduced
 171 exactly...", which means that the whitespace you've used to indent your
 172 verbatim blocks will be preserved in the output. This can be annoying for
 173 outputs such as HTML, where that whitespace will remain in front of every
 174 line. It's an unfortunate case where syntax is turned into semantics.
 175
 176 If the POD your parsing adheres to a consistent indentation policy, you can
 177 have such indentation stripped from the beginning of every line of your
 178 verbatim blocks. This method tells Pod::Simple what to strip. For two-space
 179 indents, you'd use:
 180
 181   $parser->strip_verbatim_indent('  ');
 182
 183 For tab indents, you'd use a tab character:
 184
 185   $parser->strip_verbatim_indent("\t");
 186
 187 If the POD is inconsistent about the indentation of verbatim blocks, but you
 188 have figured out a heuristic to determine how much a particular verbatim block
 189 is indented, you can pass a code reference instead. The code reference will be
 190 executed with one argument, an array reference of all the lines in the
 191 verbatim block, and should return the value to be stripped from each line. For
 192 example, if you decide that you're fine to use the first line of the verbatim
 193 block to set the standard for indentation of the rest of the block, you can
 194 look at the first line and return the appropriate value, like so:
 195
 196   $new->strip_verbatim_indent(sub {
 197       my $lines = shift;
 198       (my $indent = $lines->[0]) =~ s/\S.*//;
 199       return $indent;
 200   });
 201
 202 If you'd rather treat each line individually, you can do that, too, by just
 203 transforming them in-place in the code reference and returning C<undef>. Say
 204 that you don't want I<any> lines indented. You can do something like this:
 205
 206   $new->strip_verbatim_indent(sub {
 207       my $lines = shift;
 208       sub { s/^\s+// for @{ $lines },
 209       return undef;
 210   });
 211
 212 =back
 213
 214 =head1 TERTIARY METHODS
 215
 216 =over
 217
 218 =item C<< $parser->abandon_output_fh() >>X<abandon_output_fh>
 219
 220 Cancel output to the file handle. Any POD read by the C<$parser> is not
 221 effected.
 222
 223 =item C<< $parser->abandon_output_string() >>X<abandon_output_string>
 224
 225 Cancel output to the output string. Any POD read by the C<$parser> is not
 226 effected.
 227
 228 =item C<< $parser->accept_code( @codes ) >>X<accept_code>
 229
 230 Alias for L<< accept_codes >>.
 231
 232 =item C<< $parser->accept_codes( @codes ) >>X<accept_codes>
 233
 234 Allows C<$parser> to accept a list of L<perlpod/Formatting Codes>. This can be
 235 used to implement user-defined codes.
 236
 237 =item C<< $parser->accept_directive_as_data( @directives ) >>X<accept_directive_as_data>
 238
 239 Allows C<$parser> to accept a list of directives for data paragraphs. A
 240 directive is the label of a L<perlpod/Command Paragraph>. A data paragraph is
 241 one delimited by C<< =begin/=for/=end >> directives. This can be used to
 242 implement user-defined directives.
 243
 244 =item C<< $parser->accept_directive_as_processed( @directives ) >>X<accept_directive_as_processed>
 245
 246 Allows C<$parser> to accept a list of directives for processed paragraphs. A
 247 directive is the label of a L<perlpod/Command Paragraph>. A processed
 248 paragraph is also known as L<perlpod/Ordinary Paragraph>. This can be used to
 249 implement user-defined directives.
 250
 251 =item C<< $parser->accept_directive_as_verbatim( @directives ) >>X<accept_directive_as_verbatim>
 252
 253 Allows C<$parser> to accept a list of directives for L<perlpod/Verbatim
 254 Paragraph>. A directive is the label of a L<perlpod/Command Paragraph>. This
 255 can be used to implement user-defined directives.
 256
 257 =item C<< $parser->accept_target( @targets ) >>X<accept_target>
 258
 259 Alias for L<< accept_targets >>.
 260
 261 =item C<< $parser->accept_target_as_text( @targets ) >>X<accept_target_as_text>
 262
 263 Alias for L<< accept_targets_as_text >>.
 264
 265 =item C<< $parser->accept_targets( @targets ) >>X<accept_targets>
 266
 267 Accepts targets for C<< =begin/=for/=end >> sections of the POD.
 268
 269 =item C<< $parser->accept_targets_as_text( @targets ) >>X<accept_targets_as_text>
 270
 271 Accepts targets for C<< =begin/=for/=end >> sections that should be parsed as
 272 POD. For details, see L<< perlpodspec/About Data Paragraphs >>.
 273
 274 =item C<< $parser->any_errata_seen() >>X<any_errata_seen>
 275
 276 Used to check if any errata was seen.
 277
 278 I<Example:>
 279
 280   die "too many errors\n" if $parser->any_errata_seen();
 281
 282 =item C<< $parser->parse_from_file( $source, $to ) >>X<parse_from_file>
 283
 284 Parses from C<$source> file to C<$to> file. Similar to L<<
 285 Pod::Parser/parse_from_file >>.
 286
 287 =item C<< $parser->scream( @error_messages ) >>X<scream>
 288
 289 Log an error that can't be ignored.
 290
 291 =item C<< $parser->unaccept_code( @codes ) >>X<unaccept_code>
 292
 293 Alias for L<< unaccept_codes >>.
 294
 295 =item C<< $parser->unaccept_codes( @codes ) >>X<unaccept_codes>
 296
 297 Removes C<< @codes >> as valid codes for the parse.
 298
 299 =item C<< $parser->unaccept_directive( @directives ) >>X<unaccept_directive>
 300
 301 Alias for L<< unaccept_directives >>.
 302
 303 =item C<< $parser->unaccept_directives( @directives ) >>X<unaccept_directives>
 304
 305 Removes C<< @directives >> as valid directives for the parse.
 306
 307 =item C<< $parser->unaccept_target( @targets ) >>X<unaccept_target>
 308
 309 Alias for L<< unaccept_targets >>.
 310
 311 =item C<< $parser->unaccept_targets( @targets ) >>X<unaccept_targets>
 312
 313 Removes C<< @targets >> as valid targets for the parse.
 314
 315 =item C<< $parser->version_report() >>X<version_report>
 316
 317 Returns a string describing the version.
 318
 319 =item C<< $parser->whine( @error_messages ) >>X<whine>
 320
 321 Log an error unless C<< $parser->no_whining( TRUE ); >>.
 322
 323 =back
 324
 325 =head1 CAVEATS
 326
 327 This is just a beta release -- there are a good number of things still
 328 left to do.  Notably, support for EBCDIC platforms is still half-done,
 329 an untested.
 330
 331
 332 =head1 SEE ALSO
 333
 334 L<Pod::Simple::Subclassing>
 335
 336 L<perlpod|perlpod>
 337
 338 L<perlpodspec|perlpodspec>
 339
 340 L<Pod::Escapes|Pod::Escapes>
 341
 342 L<perldoc>
 343
 344 =head1 SUPPORT
 345
 346 Questions or discussion about POD and Pod::Simple should be sent to the
 347 pod-people@perl.org mail list. Send an empty email to
 348 pod-people-subscribe@perl.org to subscribe.
 349
 350 This module is managed in an open GitHub repository,
 351 L<http://github.com/theory/pod-simple/>. Feel free to fork and contribute, or
 352 to clone L<git://github.com/theory/pod-simple.git> and send patches!
 353
 354 Patches against Pod::Simple are welcome. Please send bug reports to
 355 <bug-pod-simple@rt.cpan.org>.
 356
 357 =head1 COPYRIGHT AND DISCLAIMERS
 358
 359 Copyright (c) 2002 Sean M. Burke.
 360
 361 This library is free software; you can redistribute it and/or modify it
 362 under the same terms as Perl itself.
 363
 364 This program is distributed in the hope that it will be useful, but
 365 without any warranty; without even the implied warranty of
 366 merchantability or fitness for a particular purpose.
 367
 368 =head1 AUTHOR
 369
 370 Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.
 371 But don't bother him, he's retired.
 372
 373 Pod::Simple is maintained by:
 374
 375 =over
 376
 377 =item * Allison Randal C<allison@perl.org>
 378
 379 =item * Hans Dieter Pearcey C<hdp@cpan.org>
 380
 381 =item * David E. Wheeler C<dwheeler@cpan.org>
 382
 383 =back
 384
 385 Documentation has been contributed by:
 386
 387 =over
 388
 389 =item * Gabor Szabo C<szabgab@gmail.com>
 390
 391 =item * Shawn H Corey  C<SHCOREY at cpan.org>
 392
 393 =back
 394
 395 =cut