1 2=head1 NAME 3 4Pod::Simple - framework for parsing Pod 5 6=head1 SYNOPSIS 7 8 TODO 9 10=head1 DESCRIPTION 11 12Pod::Simple is a Perl library for parsing text in the Pod ("plain old 13documentation") markup language that is typically used for writing 14documentation for Perl and for Perl modules. The Pod format is explained 15L<perlpod>; the most common formatter is called C<perldoc>. 16 17Pod formatters can use Pod::Simple to parse Pod documents and render them into 18plain text, HTML, or any number of other formats. Typically, such formatters 19will be subclasses of Pod::Simple, and so they will inherit its methods, like 20C<parse_file>. 21 22If you're reading this document just because you have a Pod-processing 23subclass that you want to use, this document (plus the documentation for the 24subclass) is probably all you need to read. 25 26If you're reading this document because you want to write a formatter 27subclass, continue reading it and then read L<Pod::Simple::Subclassing>, and 28then possibly even read L<perlpodspec> (some of which is for parser-writers, 29but 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 37This returns a new parser object, where I<C<SomeClass>> is a subclass 38of Pod::Simple. 39 40=item C<< $parser->output_fh( *OUT ); >> 41 42This sets the filehandle that C<$parser>'s output will be written to. 43You can pass C<*STDOUT>, otherwise you should probably do something 44like 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 54This sets the string that C<$parser>'s output will be sent to, 55instead of any filehandle. 56 57 58=item C<< $parser->parse_file( I<$some_filename> ); >> 59 60=item C<< $parser->parse_file( *INPUT_FH ); >> 61 62This reads the Pod content of the file (or filehandle) that you specify, 63and processes it with that C<$parser> object, according to however 64C<$parser>'s class works, and according to whatever parser options you 65have set up for this C<$parser> object. 66 67=item C<< $parser->parse_string_document( I<$all_content> ); >> 68 69This works just like C<parse_file> except that it reads the Pod 70content not from a file, but from a string that you have already 71in memory. 72 73=item C<< $parser->parse_lines( I<...@lines...>, undef ); >> 74 75This processes the lines in C<@lines> (where each list item must be a 76defined value, and must contain exactly one line of content -- so no 77items like C<"foo\nbar"> are allowed). The final C<undef> is used to 78indicate the end of document being parsed. 79 80The other C<parser_I<whatever>> methods are meant to be called only once 81per C<$parser> object; but C<parse_lines> can be called as many times per 82C<$parser> object as you want, as long as the last call (and only 83the last call) ends with an C<undef> value. 84 85 86=item C<< $parser->content_seen >> 87 88This returns true only if there has been any real content seen 89for this document. 90 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 98This is a shortcut method for creating a new parser object, setting the 99output handle to STDOUT, and then processing the specified file (or 100filehandle, or in-memory document). This is handy for one-liners like 101this: 102 103 perl -MPod::Simple::Text -e "Pod::Simple::Text->filter('thingy.pod')" 104 105=back 106 107 108 109=head1 SECONDARY METHODS 110 111Some of these methods might be of interest to general users, as 112well as of interest to formatter-writers. 113 114Note that the general pattern here is that the accessor-methods 115read the attribute's value with C<< $value = $parser->I<attribute> >> 116and set the attribute's value with 117C<< $parser->I<attribute>(I<newvalue>) >>. For each accessor, I typically 118only mention one syntax or another, based on which I think you are actually 119most likely to use. 120 121 122=over 123 124=item C<< $parser->no_whining( I<SOMEVALUE> ) >> 125 126If you set this attribute to a true value, you will suppress the 127parser's complaints about irregularities in the Pod coding. By default, 128this attribute's value is false, meaning that irregularities will 129be reported. 130 131Note that turning this attribute to true won't suppress one or two kinds 132of complaints about rarely occurring unrecoverable errors. 133 134 135=item C<< $parser->no_errata_section( I<SOMEVALUE> ) >> 136 137If you set this attribute to a true value, you will stop the parser from 138generating a "POD ERRORS" section at the end of the document. By 139default, this attribute's value is false, meaning that an errata section 140will be generated, as necessary. 141 142 143=item C<< $parser->complain_stderr( I<SOMEVALUE> ) >> 144 145If you set this attribute to a true value, it will send reports of 146parsing errors to STDERR. By default, this attribute's value is false, 147meaning that no output is sent to STDERR. 148 149Setting C<complain_stderr> also sets C<no_errata_section>. 150 151 152=item C<< $parser->source_filename >> 153 154This returns the filename that this parser object was set to read from. 155 156 157=item C<< $parser->doc_has_started >> 158 159This returns true if C<$parser> has read from a source, and has seen 160Pod content in it. 161 162 163=item C<< $parser->source_dead >> 164 165This returns true if C<$parser> has read from a source, and come to the 166end of that source. 167 168=item C<< $parser->strip_verbatim_indent( I<SOMEVALUE> ) >> 169 170The perlpod spec for a Verbatim paragraph is "It should be reproduced 171exactly...", which means that the whitespace you've used to indent your 172verbatim blocks will be preserved in the output. This can be annoying for 173outputs such as HTML, where that whitespace will remain in front of every 174line. It's an unfortunate case where syntax is turned into semantics. 175 176If the POD your parsing adheres to a consistent indentation policy, you can 177have such indentation stripped from the beginning of every line of your 178verbatim blocks. This method tells Pod::Simple what to strip. For two-space 179indents, you'd use: 180 181 $parser->strip_verbatim_indent(' '); 182 183For tab indents, you'd use a tab character: 184 185 $parser->strip_verbatim_indent("\t"); 186 187If the POD is inconsistent about the indentation of verbatim blocks, but you 188have figured out a heuristic to determine how much a particular verbatim block 189is indented, you can pass a code reference instead. The code reference will be 190executed with one argument, an array reference of all the lines in the 191verbatim block, and should return the value to be stripped from each line. For 192example, if you decide that you're fine to use the first line of the verbatim 193block to set the standard for indentation of the rest of the block, you can 194look 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 202If you'd rather treat each line individually, you can do that, too, by just 203transforming them in-place in the code reference and returning C<undef>. Say 204that 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 CAVEATS 215 216This is just a beta release -- there are a good number of things still 217left to do. Notably, support for EBCDIC platforms is still half-done, 218an untested. 219 220 221=head1 SEE ALSO 222 223L<Pod::Simple::Subclassing> 224 225L<perlpod|perlpod> 226 227L<perlpodspec|perlpodspec> 228 229L<Pod::Escapes|Pod::Escapes> 230 231L<perldoc> 232 233=head1 SUPPORT 234 235Questions or discussion about POD and Pod::Simple should be sent to the 236pod-people@perl.org mail list. Send an empty email to 237pod-people-subscribe@perl.org to subscribe. 238 239This module is managed in an open GitHub repository, 240L<http://github.com/theory/pod-simple/>. Feel free to fork and contribute, or 241to clone L<git://github.com/theory/pod-simple.git> and send patches! 242 243Patches against Pod::Simple are welcome. Please send bug reports to 244<bug-pod-simple@rt.cpan.org>. 245 246=head1 COPYRIGHT AND DISCLAIMERS 247 248Copyright (c) 2002 Sean M. Burke. 249 250This library is free software; you can redistribute it and/or modify it 251under the same terms as Perl itself. 252 253This program is distributed in the hope that it will be useful, but 254without any warranty; without even the implied warranty of 255merchantability or fitness for a particular purpose. 256 257=head1 AUTHOR 258 259Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. 260But don't bother him, he's retired. 261 262Pod::Simple is maintained by: 263 264=over 265 266=item * Allison Randal C<allison@perl.org> 267 268=item * Hans Dieter Pearcey C<hdp@cpan.org> 269 270=item * David E. Wheeler C<dwheeler@cpan.org> 271 272=back 273 274=cut 275