Marek Rouchal > Pod-Compiler > Pod::Compiler

Download:
Pod-Compiler-0.21.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.21   Source  

NAME ^

Pod::Compiler - compile POD into an object tree

SYNOPSIS ^

  use Pod::Compiler;

DESCRIPTION ^

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 ); # don't 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: $message\n";
$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.

NOTES ^

Building POD converters

The Pod::Compiler module is designed to serve as a basis for complex POD converters, e.g. to HTML, FrameMaker or LaTeX that can handle multiple POD documents with a table of contents, an index and most imporant hyperlinks/crossreferences.

The following flow outlines how such a converter may work:

SEE ALSO ^

Pod::Checker, Pod::Parser, Pod::Find, pod2man, pod2text, Pod::Man

AUTHOR ^

Marek Rouchal <marekr@cpan.org>

HISTORY ^

A big deal of this code has been recycled from a variety of existing Pod converters, e.g. by Tom Christiansen and Russ Allbery. A lot of ideas came from Nick Ing-Simmons' PodToHtml.

syntax highlighting: