Pod::Checker, podchecker() - check pod documents for syntax errors
use Pod::Checker; $syntax_okay = podchecker($filepath, $outputpath, %options); my $checker = new Pod::Checker %options; $checker->parse_from_file($filepath, \*STDERR);
$filepath is the input POD to read and $outputpath is where to write POD syntax error messages. Either argument may be a scalar indicating a file-path, or else a reference to an open filehandle. If unspecified, the input-file it defaults to \*STDIN, and the output-file defaults to \*STDERR.
$filepath
$outputpath
\*STDIN
\*STDERR
This function can take a hash of options:
Turn warnings on/off. See "Warnings".
podchecker will perform syntax checking of Perl5 POD format documentation.
NOTE THAT THIS MODULE IS CURRENTLY IN THE BETA STAGE!
It is hoped that curious/ambitious user will help flesh out and add the additional features they wish to see in Pod::Checker and podchecker and verify that the checks are consistent with perlpod.
The following checks are currently preformed:
Unknown '=xxxx' commands, unknown 'X<...>' interior-sequences, and unterminated interior sequences.
Check for proper balancing of =begin and =end. The contents of such a block are generally ignored, i.e. no syntax checks are performed.
=begin
=end
Check for proper nesting and balancing of =over, =item and =back.
=over
=item
=back
Check for same nested interior-sequences (e.g. L<...L<...>...>).
L<...L<...>...>
Check for malformed or nonexisting entities E<...>.
E<...>
Check for correct syntax of hyperlinks L<...>. See perlpod for details.
L<...>
Check for unresolved document-internal links. This check may also reveal misspelled links that seem to be internal links but should be links to something else.
empty =headn
A heading (=head1 or =head2) without any text? That ain't no heading!
=head1
=head2
=over on line N without closing =back
The =over command does not have a corresponding =back before the next heading (=head1 or =head2) or the end of the file.
=item without previous =over
=back without previous =over
An =item or =back command has been found outside a =over/=back block.
No argument for =begin
A =begin command was found that is not followed by the formatter specification.
=end without =begin
A standalone =end command was found.
Nested =begin's
There were at least two consecutive =begin commands without the corresponding =end. Only one =begin may be active at a time.
=for without formatter specification
There is no specification of the formatter after the =for command.
=for
unresolved internal link NAME
The given link to NAME does not have a matching node in the current POD. This also happend when a single word node name is not enclosed in "".
""
Unknown command "CMD"
An invalid POD command has been found. Valid are =head1, =head2, =over, =item, =back, =begin, =end, =for, =pod, =cut
=pod
=cut
Unknown interior-sequence "SEQ"
An invalid markup command has been encountered. Valid are: B<>, C<>, E<>, F<>, I<>, L<>, S<>, X<>, Z<>
B<>
C<>
E<>
F<>
I<>
L<>
S<>
X<>
Z<>
nested commands CMD<...CMD<...>...>
Two nested identical markup commands have been found. Generally this does not make sense.
garbled entity STRING
The STRING found cannot be interpreted as a character entity.
Entity number out of range
An entity specified by number (dec, hex, oct) is out of range (1-255).
malformed link L<>
The link found cannot be parsed because it does not conform to the syntax described in perlpod.
nonempty Z<>
The Z<> sequence is supposed to be empty.
empty X<>
The index entry specified contains nothing but whitespace.
Spurious text after =pod / =cut
The commands =pod and =cut do not take any arguments.
Spurious character(s) after =back
The =back command does not take any arguments.
These may not necessarily cause trouble, but indicate mediocre style.
multiple occurence of link target name
The POD file has some =item and/or =head commands that have the same text. Potential hyperlinks to such a text cannot be unique then.
=head
line containing nothing but whitespace in paragraph
There is some whitespace on a seemingly empty line. POD is very sensitive to such things, so this is flagged. vi users switch on the list option to avoid this problem.
file does not start with =head
The file starts with a different POD directive than head. This is most probably something you do not want.
No numeric argument for =over
The =over command is supposed to have a numeric argument (the indentation).
previous =item has no contents
There is a list =item right above the flagged line that has no text contents. You probably want to delete empty items.
preceding non-item paragraph(s)
A list introduced by =over starts with a text or verbatim paragraph, but continues with =items. Move the non-item paragraph out of the =over/=back block.
=item type mismatch (one vs. two)
A list started with e.g. a bulletted =item and continued with a numbered one. This is obviously inconsistent. For most translators the type of the first =item determines the type of the list.
N unescaped <> in paragraph
<>
Angle brackets not written as <lt> and <gt> can potentially cause errors as they could be misinterpreted as markup commands.
<lt>
<gt>
Unknown entity
A character entity was found that does not belong to the standard ISO set or the POD specials verbar and sol.
verbar
sol
No items in =over
The list opened with =over does not contain any items.
No argument for =item
=item without any parameters is deprecated. It should either be followed by * to indicate an unordered list, by a number (optionally followed by a dot) to indicate an ordered (numbered) list or simple text for a definition list.
*
empty section in previous paragraph
The previous section (introduced by a =head command) does not contain any text. This usually indicates that something is missing. Note: A =head1 followed immediately by =head2 does not trigger this warning.
Verbatim paragraph in NAME section
The NAME section (=head1 NAME) should consist of a single paragraph with the script/module name, followed by a dash `-' and a very short description of what the thing is good for.
=head1 NAME
Hyperlinks
There are some warnings wrt. hyperlinks: Leading/trailing whitespace, newlines in hyperlinks, brackets ().
()
podchecker returns the number of POD syntax errors found or -1 if there were no POD commands at all found in the file.
[T.B.D.]
While checking, this module collects document properties, e.g. the nodes for hyperlinks (=headX, =item) and index entries (X<>). POD translators can use this feature to syntax-check and get the nodes in a first pass before actually starting to convert. This is expensive in terms of execution time, but allows for very robust conversions.
=headX
$checker->poderror( @args )
$checker->poderror( {%opts}, @args )
Internal method for printing errors and warnings. If no options are given, simply prints "@_". The following options are recognized and used to form the output:
-msg
A message to print prior to @args.
@args
-line
The line number the error occurred in.
-file
The file (name) the error occurred in.
-severity
The error level, should be 'WARNING' or 'ERROR'.
$checker->num_errors()
Set (if argument specified) and retrieve the number of errors found.
$checker->name()
Set (if argument specified) and retrieve the canonical name of POD as found in the =head1 NAME section.
$checker->node()
Add (if argument specified) and retrieve the nodes (as defined by =headX and =item) of the current POD. The nodes are returned in the order of their occurence. They consist of plain text, each piece of whitespace is collapsed to a single blank.
$checker->idx()
Add (if argument specified) and retrieve the index entries (as defined by X<>) of the current POD. They consist of plain text, each piece of whitespace is collapsed to a single blank.
$checker->hyperlink()
Add (if argument specified) and retrieve the hyperlinks (as defined by L<>) of the current POD. They consist of an 2-item array: line number and Pod::Hyperlink object.
Pod::Hyperlink
Brad Appleton <bradapp@enteract.com> (initial version), Marek Rouchal <marek@saftsack.fs.uni-bayreuth.de>
Based on code for Pod::Text::pod2text() written by Tom Christiansen <tchrist@mox.perl.com>
To install lib, copy and paste the appropriate command in to your terminal.
cpanm
cpanm lib
CPAN shell
perl -MCPAN -e shell install lib
For more information on module installation, please visit the detailed CPAN module installation guide.