Pod::ParseUtils(3Perl Programmers Reference GuPod::ParseUtils(3p)NAMEPod::ParseUtils - helpers for POD parsing and conversion
SYNOPSIS
use Pod::ParseUtils;
my $list = new Pod::List;
my $link = Pod::Hyperlink->new('Pod::Parser');
DESCRIPTIONPod::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
