


Pod::ParseUtils(3Perl Programmers Reference GuPod::ParseUtils(3p)


NAME
       Pod::ParseUtils - helpers for POD parsing and conversion

SYNOPSIS
         use Pod::ParseUtils;

         my $list = new Pod::List;
         my $link = Pod::Hyperlink->new('Pod::Parser');

DESCRIPTION
       Pod::ParseUtils contains a few object-oriented helper
       packages for POD parsing and processing (i.e. in POD
       formatters and translators).

   Pod::List
       Pod::List can be used to hold information about POD lists
       (written as =over ... =item ... =back) for further
       processing.  The following methods are available:

       Pod::List->new()
           Create a new list object. Properties may be specified
           through a hash reference like this:

             my $list = Pod::List->new({ -start => $., -indent => 4 });

           See the individual methods/properties for details.

       $list->file()
           Without argument, retrieves the file name the list is
           in. This must have been set before by either
           specifying -file in the new() method or by calling the
           file() method with a scalar argument.

       $list->start()
           Without argument, retrieves the line number where the
           list started.  This must have been set before by
           either specifying -start in the new() method or by
           calling the start() method with a scalar argument.

       $list->indent()
           Without argument, retrieves the indent level of the
           list as specified in "=over n". This must have been
           set before by either specifying -indent in the new()
           method or by calling the indent() method with a scalar
           argument.

       $list->type()
           Without argument, retrieves the list type, which can
           be an arbitrary value, e.g. "OL", "UL", ... when
           thinking the HTML way.  This must have been set before
           by either specifying -type in the new() method or by
           calling the type() method with a scalar argument.





perl v5.10.1                2009-10-12                          1





Pod::ParseUtils(3Perl Programmers Reference GuPod::ParseUtils(3p)


       $list->rx()
           Without argument, retrieves a regular expression for
           simplifying the individual item strings once the list
           type has been determined. Usage: E.g. when converting
           to HTML, one might strip the leading number in an
           ordered list as "<OL>" already prints numbers itself.
           This must have been set before by either specifying
           -rx in the new() method or by calling the rx() method
           with a scalar argument.

       $list->item()
           Without argument, retrieves the array of the items in
           this list.  The items may be represented by any
           scalar.  If an argument has been given, it is pushed
           on the list of items.

       $list->parent()
           Without argument, retrieves information about the
           parent holding this list, which is represented as an
           arbitrary scalar.  This must have been set before by
           either specifying -parent in the new() method or by
           calling the parent() method with a scalar argument.

       $list->tag()
           Without argument, retrieves information about the list
           tag, which can be any scalar.  This must have been set
           before by either specifying -tag in the new() method
           or by calling the tag() method with a scalar argument.

   Pod::Hyperlink
       Pod::Hyperlink is a class for manipulation of POD
       hyperlinks. Usage:

         my $link = Pod::Hyperlink->new('alternative text|page/"section in page"');

       The Pod::Hyperlink class is mainly designed to parse the
       contents of the "L<...>" sequence, providing a simple
       interface for accessing the different parts of a POD
       hyperlink for further processing. It can also be used to
       construct hyperlinks.

       Pod::Hyperlink->new()
           The new() method can either be passed a set of
           key/value pairs or a single scalar value, namely the
           contents of a "L<...>" sequence. An object of the
           class "Pod::Hyperlink" is returned. The value "undef"
           indicates a failure, the error message is stored in
           $@.

       $link->parse($string)
           This method can be used to (re)parse a (new)
           hyperlink, i.e. the contents of a "L<...>" sequence.
           The result is stored in the current object.  Warnings
           are stored in the warnings property.  E.g. sections



perl v5.10.1                2009-10-12                          2





Pod::ParseUtils(3Perl Programmers Reference GuPod::ParseUtils(3p)


           like "L<open(2)>" are deprecated, as they do not point
           to Perl documents. "L<DBI::foo(3p)>" is wrong as well,
           the manpage section can simply be dropped.

       $link->markup($string)
           Set/retrieve the textual value of the link. This
           string contains special markers "P<>" and "Q<>" that
           should be expanded by the translator's interior
           sequence expansion engine to the formatter-specific
           code to highlight/activate the hyperlink. The details
           have to be implemented in the translator.

       $link->text()
           This method returns the textual representation of the
           hyperlink as above, but without markers (read only).
           Depending on the link type this is one of the
           following alternatives (the + and * denote the
           portions of the text that are marked up):

             +perl+                    L<perl>
             *$|* in +perlvar+         L<perlvar/$|>
             *OPTIONS* in +perldoc+    L<perldoc/"OPTIONS">
             *DESCRIPTION*             L<"DESCRIPTION">

       $link->warning()
           After parsing, this method returns any warnings
           encountered during the parsing process.

       $link->file()
       $link->line()
           Just simple slots for storing information about the
           line and the file the link was encountered in. Has to
           be filled in manually.

       $link->page()
           This method sets or returns the POD page this link
           points to.

       $link->node()
           As above, but the destination node text of the link.

       $link->alttext()
           Sets or returns an alternative text specified in the
           link.

       $link->type()
           The node type, either "section" or "item". As an
           unofficial type, there is also "hyperlink", derived
           from e.g. "L<http://perl.com>"

       $link->link()
           Returns the link as contents of "L<>". Reciprocal to
           parse().




perl v5.10.1                2009-10-12                          3





Pod::ParseUtils(3Perl Programmers Reference GuPod::ParseUtils(3p)


   Pod::Cache
       Pod::Cache holds information about a set of POD documents,
       especially the nodes for hyperlinks.  The following
       methods are available:

       Pod::Cache->new()
           Create a new cache object. This object can hold an
           arbitrary number of POD documents of class
           Pod::Cache::Item.

       $cache->item()
           Add a new item to the cache. Without arguments, this
           method returns a list of all cache elements.

       $cache->find_page($name)
           Look for a POD document named $name in the cache.
           Returns the reference to the corresponding
           Pod::Cache::Item object or undef if not found.

   Pod::Cache::Item
       Pod::Cache::Item holds information about individual POD
       documents, that can be grouped in a Pod::Cache object.  It
       is intended to hold information about the hyperlink nodes
       of POD documents.  The following methods are available:

       Pod::Cache::Item->new()
           Create a new object.

       $cacheitem->page()
           Set/retrieve the POD document name (e.g.
           "Pod::Parser").

       $cacheitem->description()
           Set/retrieve the POD short description as found in the
           "=head1 NAME" section.

       $cacheitem->path()
           Set/retrieve the POD file storage path.

       $cacheitem->file()
           Set/retrieve the POD file name.

       $cacheitem->nodes()
           Add a node (or a list of nodes) to the document's node
           list. Note that the order is kept, i.e. start with the
           first node and end with the last.  If no argument is
           given, the current list of nodes is returned in the
           same order the nodes have been added.  A node can be
           any scalar, but usually is a pair of node string and
           unique id for the "find_node" method to work
           correctly.

       $cacheitem->find_node($name)
           Look for a node or index entry named $name in the



perl v5.10.1                2009-10-12                          4





Pod::ParseUtils(3Perl Programmers Reference GuPod::ParseUtils(3p)


           object.  Returns the unique id of the node (i.e. the
           second element of the array stored in the node array)
           or undef if not found.

       $cacheitem->idx()
           Add an index entry (or a list of them) to the
           document's index list. Note that the order is kept,
           i.e. start with the first node and end with the last.
           If no argument is given, the current list of index
           entries is returned in the same order the entries have
           been added.  An index entry can be any scalar, but
           usually is a pair of string and unique id.

AUTHOR
       Please report bugs using <http://rt.cpan.org>.

       Marek Rouchal <marekr@cpan.org>, borrowing a lot of things
       from pod2man and pod2roff as well as other POD processing
       tools by Tom Christiansen, Brad Appleton and Russ Allbery.

SEE ALSO
       pod2man, pod2roff, Pod::Parser, Pod::Checker, pod2html



































perl v5.10.1                2009-10-12                          5


