ABCDEFGHIJKLMNOPQRSTUVWXYZ

Pod::ParseUtils

Pod::ParseUtils(3)     Perl Programmers Reference Guide     Pod::ParseUtils(3)



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 meth-
       ods 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 argu-
           ment.

       $list->indent()
           Without argument, retrieves the indent level of the list as speci-
           fied in "=over n". This must have been set before by either speci-
           fying -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 arbi-
           trary 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.

       $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 speci-
           fying -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 cur-
           rent object.  Warnings are stored in the warnings property.  E.g.
           sections 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().

       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 ref-
           erence 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 informa-
       tion 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 object.  Returns
           the unique id of the node (i.e. the second element of the array
           stored in the node arry) 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.8.6                       2001-09-21                Pod::ParseUtils(3)