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

Pod::Compiler Ranking & Summary

Pod::Compiler Tags

Perl module object compiler POD compile POD object tree

Pod::Compiler Description

Pod::Compiler can compile POD into an object tree. 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 FunctionsThe 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 InterfaceThe 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 sillyPod::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 => 1Print POD syntax errors (using messagehandler) if option value is true. -warnings => 1Print POD syntax warnings (using messagehandler) if option value is true. -idlength => 20Pod::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 => 0If 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( )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. Requirements: · Perl

Pod::Compiler Related Software