Pod::Compiler 0.20

Pod::Compiler can compile POD into an object tree.

This package, based on Pod::Parser, compiles a given POD document into an object tree (based on Tree::DAG_Node). It prints errors and warnings about the POD it reads. The result can be used to conveniently convert the POD into any other format.

The resulting objects have a variety of methods to ease the subsequent conversion.

There are two script based on this package, namely podchecker2, an enhanced POD syntax checker and podlint, which beautifies the POD of a given file.

This package is object-oriented, which means that you can quite easily build a derived package and override some methods in case the given behaviour does not exactly suit your needs.

Package Functions

The following functions can be imported and called from a script, e.g. like this:

use Pod::Compiler qw(pod_compile);
my $root = pod_compile(myfile.pod);

pod_compile( { %options } , $file )
pod_compile( $file )

Compile the given $file using some %options and return the root of the object tree representing the POD in $file. The return value is either undef if some fatal error occured or an object of type Pod::root. See below for methods applicable to this class and for the options.

The special option -compiler => class lets you specify an alternate (derived) compiler class rather than Pod::Compiler.

Compiler Object Interface

The following section describes the OO interface of Pod::Compiler.

$c = Pod::Compiler->new( %options )

Set up a new compiler object. Options (see below) can be passed as a hash, e.g.

$c = Pod::Compiler->new( -warnings => 0 ); # dont be silly

Pod::Compiler inherits from Pod::Parser. See Pod::Parser for additional methods.

$c->initialize()

Initalize, set defaults. The following options are set to the given defaults unless they have been defined at object creation:

-errors => 1

Print POD syntax errors (using messagehandler) if option value is true.

-warnings => 1

Print POD syntax warnings (using messagehandler) if option value is true.

-idlength => 20

Pod::Compiler creates a unique node id for each =head, =item and X<>, consisting only of w characters. The option value specifies how many characters from the original node text are used for the node id by the built-in make_unique_node_id method. See below for more information.

-ignore => BCFS

This option specifies which interior sequences (e.g. B< ... >) are ignored when nested in itself, e.g. B< ...B< ... >... >. The inner B is simply discarded if the corresponding letter appears in the option value string.

-unwrap => I

This option specifies which interior sequences (e.g. I< ... >) are unwrapped when nested in itself, e.g. I< ...I< ... >... > is turned into I< ... >...I< ... >. While some destination formats may handle such nestings appropriately, other might have problems. This option solves it right away. By the way, from a typographical point of view, italics are often used for emphasis. In order to emphasize something within an emphasis, one reverts to the non-italic font.

name =>

This is used to store the (logical) name of the POD, i.e. for example the module name as it appears in use module;. It is used internally only to detect internal links pointing to the explicit page name. Example: You compile the file Compiler.pm which contains the package Pod::Compiler. You set name to Pod::Compiler (there is no safe automatic way to do so). Thus if the file includes a link like L< Pod::Compiler/messagehandler > it is recognized as an internal link and it is checked whether it resolves. Of course you should have written the link as L< /messagehandler >...

-perlcode => 0

If set to true, the compiler will also return the Perl code blocks as objects Pod::perlcode, rather than only the POD embedded in the file. This is used e.g. by podlint.

$c->option( $name , $value )

Get or set the compile option (see above) given by $name. If $value is defined, the option is set to this value. The resulting (or unchanged) value is returned.

$c->messagehandler( $severity , $message )

This method is called every time a warning or error occurs. $severity is one of ERROR or WARNING, $message is a one-line string. The built-in method simply does

warn "$severity: $messagen";
$c->name( [ $name ] )

Set/retrieve the name property, i.e. the canonical Pod name (e.g. Pod::HTML). See above for more details.

$c->root()

Return the root element (instance of class Pod::root) representing the compiled POD document. See below for more info about its methods.

$c->make_unique_node_id($string)

Turn given text string into a document unique node id. Can be overridden to adapt this to specific formatter needs. Basically this method takes a string and must return something (more or less dependent on the string) that is unique for this POD document. The built-in method maps all consecutive non-word characters and underlines to a single underline and truncates the result to -idlength (see options above). If the result already exists, a suffix _n is appended, where n is a number starting with 1. A different method could e.g. just return ascending numbers, but if you think of HTML output, a node id that resembles the text and has a fair chance to remain constant over subsequent compiles of the same document gives the opportunity to link to such anchors from external documents.