MAN page from Other perl-PodParser-1.26-8.noarch.rpm

Pod::ParseUtils

Section: User Contributed Perl Documentation (3)
Updated: perl v5.6.1
Index

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 forPOD 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 hashreference 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 musthave 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 thenew() method or by calling the start() method with a scalarargument.

$list->indent()

Without argument, retrieves the indent level of the list as specifiedin "=over n". This must have been set before by either specifying-indent in the new() method or by calling the indent() methodwith 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() methodwith 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 inan 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() methodwith 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 thislist, 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() methodwith a scalar argument.

$list->tag()

Without argument, retrieves information about the list tag, which can beany scalar.This must have been set before by either specifying-tag in the new() method or by calling the tag() methodwith 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 thedifferent parts of a POD hyperlink for further processing. It can also beused to construct hyperlinks.

Pod::Hyperlink->new()

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

$link->parse($string)

This method can be used to (re)parse a (new) hyperlink, i.e. the contentsof 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 pointto Perl documents. "L<DBI::foo(3p)>" is wrong as well, the manpagesection can simply be dropped.

$link->markup($string)

Set/retrieve the textual value of the link. This string contains specialmarkers "P<>" and "Q<>" that should be expanded by thetranslator's interior sequence expansion engine to theformatter-specific code to highlight/activate the hyperlink. The detailshave 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 ofthe following alternatives (the + and * denote the portions of the textthat 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 theparsing process.

$link->file()

$link->line()

Just simple slots for storing information about the line and the filethe 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 ofPOD documents of class Pod::Cache::Item.
$cache->item(): Add a new item to the cache. Without arguments, this method returns alist of all cache elements.
$cache->find_page($name): Look for a POD document named "$name" in the cache. Returns thereference to the corresponding Pod::Cache::Item object or undef ifnot 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 PODdocuments.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 thatthe 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 thesame order the nodes have been added.A node can be any scalar, but usually is a pair of node string andunique 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 arraystored 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 thatthe 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 thesame order the entries have been added.An index entry can be any scalar, but usually is a pair of string andunique id.

AUTHOR

Please report bugs using http://rt.cpan.org.

Marek Rouchal <marekrAATTcpan.org>, borrowinga lot of things from the pod2man manpage and the pod2roff manpage as well as other PODprocessing tools by Tom Christiansen, Brad Appleton and Russ Allbery.

This document was created byman2html,using the manual pages.