Gurusamy Sarathy > perl-5.6.0 > Pod::Checker

Download:
perl-5.6.0.tar.gz

Dependencies

Annotate this POD

Related Modules

Test::More
Test::Pod
Getopt::Long
Pod::Usage
Test::Harness
IO::Socket
Text::Tabs
Tie::SubstrHash
IO::Pipe
OS2::REXX
more...
By perlmonks.org
Module Version: 1.098   Source   Latest Release: perl-5.6.2

NAME ^

Pod::Checker, podchecker() - check pod documents for syntax errors

SYNOPSIS ^

  use Pod::Checker;

  $syntax_okay = podchecker($filepath, $outputpath, %options);

  my $checker = new Pod::Checker %options;
  $checker->parse_from_file($filepath, \*STDERR);

OPTIONS/ARGUMENTS ^

$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.

podchecker()

This function can take a hash of options:

-warnings => val

Turn warnings on/off. See "Warnings".

DESCRIPTION ^

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:

DIAGNOSTICS ^

Errors

Warnings

These may not necessarily cause trouble, but indicate mediocre style.

RETURN VALUE ^

podchecker returns the number of POD syntax errors found or -1 if there were no POD commands at all found in the file.

EXAMPLES ^

[T.B.D.]

INTERFACE ^

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.

$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.

  -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.

AUTHOR ^

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>

syntax highlighting: