Pod::ParseUtils(3Perl Programmers Reference GuiPod::ParseUtils(3)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
packages for POD parsing and processing (i.e. in POD for
matters and translators).
Pod::List
Pod::List can be used to hold information about POD lists
(written as =over ... =item ... =back) for further pro
cessing. 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 specify
ing -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.
$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 par
ent 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 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
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) hyper
link, 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 deprected, 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 follow
ing alternatives (the + and * denote the portions of
the text that are marked up):
the +perl+ manpage
the *$|* entry in the +perlvar+ manpage
the section on *OPTIONS* in the +perldoc+ manpage
the section on *DESCRIPTION* elsewhere in this document
$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 unof
ficial 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 meth
ods 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 cor
rectly.
$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 docu
ment'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
Marek Rouchal <marek@saftsack.fs.uni-bayreuth.de>, borrow
ing a lot of things from the pod2man manpage and the
pod2roff manpage as well as other POD processing tools by
Tom Christiansen, Brad Appleton and Russ Allbery.
SEE ALSO
the pod2man manpage, the pod2roff manpage, the Pod::Parser
manpage, the Pod::Checker manpage, the pod2html manpage
2001-02-22 perl v5.6.1 Pod::ParseUtils(3)
