MirOS Manual: Pod::ParseUtils(3p)


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 pack-
     ages 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 process-
     ing. 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 argu-
         ment.

     $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

perl v5.8.8                2005-02-05                           1

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

         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 speci-
         fying -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 hyper-
     links. 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 inter-
     face 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" indi-
         cates a failure, the error message is stored in $@.

     $link->parse($string)

perl v5.8.8                2005-02-05                           2

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

         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 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 encoun-
         tered 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 unoffi-
         cial type, there is also "hyperlink", derived from e.g.

perl v5.8.8                2005-02-05                           3

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

         "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 arbi-
         trary 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

perl v5.8.8                2005-02-05                           4

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

         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.8                2005-02-05                           5

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.