[ Index ] |
PHP Cross Reference of Unnamed Project |
[Summary view] [Print] [Text view]
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 in the L<perlpod|perlpod> man page; the most common formatter is called 16 "perldoc". 17 18 Pod formatters can use Pod::Simple to parse Pod documents into produce 19 renderings of them in plain ASCII, in HTML, or in any number of other 20 formats. Typically, such formatters will be subclasses of Pod::Simple, 21 and so they will inherit its methods, like C<parse_file>. 22 23 If you're reading this document just because you have a Pod-processing 24 subclass that you want to use, this document (plus the documentation for 25 the subclass) is probably all you'll need to read. 26 27 If you're reading this document because you want to write a formatter 28 subclass, continue reading this document, and then read 29 L<Pod::Simple::Subclassing>, and then possibly even read L<perlpodspec> 30 (some of which is for parser-writers, but much of which is notes to 31 formatter-writers). 32 33 34 =head1 MAIN METHODS 35 36 37 38 =over 39 40 =item C<< $parser = I<SomeClass>->new(); >> 41 42 This returns a new parser object, where I<C<SomeClass>> is a subclass 43 of Pod::Simple. 44 45 =item C<< $parser->output_fh( *OUT ); >> 46 47 This sets the filehandle that C<$parser>'s output will be written to. 48 You can pass C<*STDOUT>, otherwise you should probably do something 49 like this: 50 51 my $outfile = "output.txt"; 52 open TXTOUT, ">$outfile" or die "Can't write to $outfile: $!"; 53 $parser->output_fh(*TXTOUT); 54 55 ...before you call one of the C<< $parser->parse_I<whatever> >> methods. 56 57 =item C<< $parser->output_string( \$somestring ); >> 58 59 This sets the string that C<$parser>'s output will be sent to, 60 instead of any filehandle. 61 62 63 =item C<< $parser->parse_file( I<$some_filename> ); >> 64 65 =item C<< $parser->parse_file( *INPUT_FH ); >> 66 67 This reads the Pod content of the file (or filehandle) that you specify, 68 and processes it with that C<$parser> object, according to however 69 C<$parser>'s class works, and according to whatever parser options you 70 have set up for this C<$parser> object. 71 72 =item C<< $parser->parse_string_document( I<$all_content> ); >> 73 74 This works just like C<parse_file> except that it reads the Pod 75 content not from a file, but from a string that you have already 76 in memory. 77 78 =item C<< $parser->parse_lines( I<...@lines...>, undef ); >> 79 80 This processes the lines in C<@lines> (where each list item must be a 81 defined value, and must contain exactly one line of content -- so no 82 items like C<"foo\nbar"> are allowed). The final C<undef> is used to 83 indicate the end of document being parsed. 84 85 The other C<parser_I<whatever>> methods are meant to be called only once 86 per C<$parser> object; but C<parse_lines> can be called as many times per 87 C<$parser> object as you want, as long as the last call (and only 88 the last call) ends with an C<undef> value. 89 90 91 =item C<< $parser->content_seen >> 92 93 This returns true only if there has been any real content seen 94 for this document. 95 96 97 =item C<< I<SomeClass>->filter( I<$filename> ); >> 98 99 =item C<< I<SomeClass>->filter( I<*INPUT_FH> ); >> 100 101 =item C<< I<SomeClass>->filter( I<\$document_content> ); >> 102 103 This is a shortcut method for creating a new parser object, setting the 104 output handle to STDOUT, and then processing the specified file (or 105 filehandle, or in-memory document). This is handy for one-liners like 106 this: 107 108 perl -MPod::Simple::Text -e "Pod::Simple::Text->filter('thingy.pod')" 109 110 =back 111 112 113 114 =head1 SECONDARY METHODS 115 116 Some of these methods might be of interest to general users, as 117 well as of interest to formatter-writers. 118 119 Note that the general pattern here is that the accessor-methods 120 read the attribute's value with C<< $value = $parser->I<attribute> >> 121 and set the attribute's value with 122 C<< $parser->I<attribute>(I<newvalue>) >>. For each accessor, I typically 123 only mention one syntax or another, based on which I think you are actually 124 most likely to use. 125 126 127 =over 128 129 =item C<< $parser->no_whining( I<SOMEVALUE> ) >> 130 131 If you set this attribute to a true value, you will suppress the 132 parser's complaints about irregularities in the Pod coding. By default, 133 this attribute's value is false, meaning that irregularities will 134 be reported. 135 136 Note that turning this attribute to true won't suppress one or two kinds 137 of complaints about rarely occurring unrecoverable errors. 138 139 140 =item C<< $parser->no_errata_section( I<SOMEVALUE> ) >> 141 142 If you set this attribute to a true value, you will stop the parser from 143 generating a "POD ERRORS" section at the end of the document. By 144 default, this attribute's value is false, meaning that an errata section 145 will be generated, as necessary. 146 147 148 =item C<< $parser->complain_stderr( I<SOMEVALUE> ) >> 149 150 If you set this attribute to a true value, it will send reports of 151 parsing errors to STDERR. By default, this attribute's value is false, 152 meaning that no output is sent to STDERR. 153 154 Note that errors can be noted in an errata section, or sent to STDERR, 155 or both, or neither. So don't think that turning on C<complain_stderr> 156 will turn off C<no_errata_section> or vice versa -- these are 157 independent attributes. 158 159 160 =item C<< $parser->source_filename >> 161 162 This returns the filename that this parser object was set to read from. 163 164 165 =item C<< $parser->doc_has_started >> 166 167 This returns true if C<$parser> has read from a source, and has seen 168 Pod content in it. 169 170 171 =item C<< $parser->source_dead >> 172 173 This returns true if C<$parser> has read from a source, and come to the 174 end of that source. 175 176 =back 177 178 179 =head1 CAVEATS 180 181 This is just a beta release -- there are a good number of things still 182 left to do. Notably, support for EBCDIC platforms is still half-done, 183 an untested. 184 185 186 =head1 SEE ALSO 187 188 L<Pod::Simple::Subclassing> 189 190 L<perlpod|perlpod> 191 192 L<perlpodspec|perlpodspec> 193 194 L<Pod::Escapes|Pod::Escapes> 195 196 L<perldoc> 197 198 199 =head1 COPYRIGHT AND DISCLAIMERS 200 201 Copyright (c) 2002 Sean M. Burke. All rights reserved. 202 203 This library is free software; you can redistribute it and/or modify it 204 under the same terms as Perl itself. 205 206 This program is distributed in the hope that it will be useful, but 207 without any warranty; without even the implied warranty of 208 merchantability or fitness for a particular purpose. 209 210 =head1 AUTHOR 211 212 Original author: Sean M. Burke C<sburke@cpan.org> 213 214 Maintained by: Allison Randal C<allison@perl.org> 215 216 =cut 217 218
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated: Tue Mar 17 22:47:18 2015 | Cross-referenced by PHPXref 0.7.1 |