#############################################################################
# Pod/ParseUtils.pm -- helpers for POD parsing and conversion
# Copyright (C) 1999-2000 by Marek Rouchal. All rights reserved.
# This file is part of "PodParser". PodParser is free software;
# you can redistribute it and/or modify it under the same terms
#############################################################################
$VERSION = 0.22; ## Current version of this package
require 5.005; ## requires this Perl version or later
Pod::ParseUtils - helpers for POD parsing and conversion
my $list = new Pod::List;
my $link = Pod::Hyperlink->new('Pod::Parser');
B<Pod::ParseUtils> contains a few object-oriented helper packages for
POD parsing and processing (i.e. in POD formatters and translators).
#-----------------------------------------------------------------------------
# class to hold POD list info (=over, =item, =back)
#-----------------------------------------------------------------------------
B<Pod::List> can be used to hold information about POD lists
(written as =over ... =item ... =back) for further processing.
The following methods are available:
=item Pod::List-E<gt>new()
Create a new list object. Properties may be specified through a hash
my $list = Pod::List->new({ -start => $., -indent => 4 });
See the individual methods/properties for details.
my $class = ref($this) || $this;
$self->{-file} ||= 'unknown';
$self->{-start} ||= 'unknown';
$self->{-indent} ||= 4; # perlpod: "should be the default"
Without argument, retrieves the file name the list is in. This must
have been set before by either specifying B<-file> in the B<new()>
method or by calling the B<file()> method with a scalar argument.
# The POD file name the list appears in
return (@_ > 1) ? ($_[0]->{-file} = $_[1]) : $_[0]->{-file};
Without argument, retrieves the line number where the list started.
This must have been set before by either specifying B<-start> in the
B<new()> method or by calling the B<start()> method with a scalar
# The line in the file the node appears
return (@_ > 1) ? ($_[0]->{-start} = $_[1]) : $_[0]->{-start};
=item $list-E<gt>indent()
Without argument, retrieves the indent level of the list as specified
in C<=over n>. This must have been set before by either specifying
B<-indent> in the B<new()> method or by calling the B<indent()> method
return (@_ > 1) ? ($_[0]->{-indent} = $_[1]) : $_[0]->{-indent};
Without argument, retrieves the list type, which can be an arbitrary value,
e.g. C<OL>, C<UL>, ... when thinking the HTML way.
This must have been set before by either specifying
B<-type> in the B<new()> method or by calling the B<type()> method
# The type of the list (UL, OL, ...)
return (@_ > 1) ? ($_[0]->{-type} = $_[1]) : $_[0]->{-type};
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 C<E<lt>OLE<gt>> already prints numbers itself.
This must have been set before by either specifying
B<-rx> in the B<new()> method or by calling the B<rx()> method
# The regular expression to simplify the items
return (@_ > 1) ? ($_[0]->{-rx} = $_[1]) : $_[0]->{-rx};
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.
# The individual =items of this list
push(@{$self->{_items}}, $item);
return @{$self->{_items}};
=item $list-E<gt>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
B<-parent> in the B<new()> method or by calling the B<parent()> method
# possibility for parsers/translators to store information about the
return (@_ > 1) ? ($_[0]->{-parent} = $_[1]) : $_[0]->{-parent};
Without argument, retrieves information about the list tag, which can be
This must have been set before by either specifying
B<-tag> in the B<new()> method or by calling the B<tag()> method
# possibility for parsers/translators to store information about the
return (@_ > 1) ? ($_[0]->{-tag} = $_[1]) : $_[0]->{-tag};
#-----------------------------------------------------------------------------
# class to manipulate POD hyperlinks (L<>)
#-----------------------------------------------------------------------------
B<Pod::Hyperlink> is a class for manipulation of POD hyperlinks. Usage:
my $link = Pod::Hyperlink->new('alternative text|page/"section in page"');
The B<Pod::Hyperlink> class is mainly designed to parse the contents of the
C<LE<lt>...E<gt>> 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.
=item Pod::Hyperlink-E<gt>new()
The B<new()> method can either be passed a set of key/value pairs or a single
scalar value, namely the contents of a C<LE<lt>...E<gt>> sequence. An object
of the class C<Pod::Hyperlink> is returned. The value C<undef> indicates a
failure, the error message is stored in C<$@>.
my $class = ref($this) || $this;
# called with a list of parameters
$self->_construct_text();
# called with L<> contents
return undef unless($self->parse($_[0]));
$self->{-line} ||= 'undef';
$self->{-file} ||= 'undef';
$self->{-alttext} ||= '';
$self->{-type} ||= 'undef';
=item $link-E<gt>parse($string)
This method can be used to (re)parse a (new) hyperlink, i.e. the contents
of a C<LE<lt>...E<gt>> sequence. The result is stored in the current object.
Warnings are stored in the B<warnings> property.
E.g. sections like C<LE<lt>open(2)E<gt>> are deprecated, as they do not point
to Perl documents. C<LE<lt>DBI::foo(3p)E<gt>> is wrong as well, the manpage
section can simply be dropped.
# syntax check the link and extract destination
my ($alttext,$page,$node,$type) = (undef,'','','');
# collapse newlines with whitespace
# strip leading/trailing whitespace
$self->warning("ignoring leading whitespace in link");
$self->warning("ignoring trailing whitespace in link");
_invalid_link("empty link");
## Check for different possibilities. This is tedious and error-prone
# we match all possibilities (alttext, page, section/item)
#warn "DEBUG: link=$_\n";
# problem: a lot of people use (), or (1) or the like to indicate
# man page sections. But this collides with L<func()> that is supposed
# to point to an internal funtion...
my $page_rx = '[\w.]+(?:::[\w.]+)*(?:[(](?:\d\w*|)[)]|)';
# alttext, page and "section"
elsif(m!^(.*?)\s*[|]\s*($page_rx)\s*/\s*"(.+)"$!o) {
($alttext, $page, $node) = ($1, $2, $3);
elsif(m!^(.*?)\s*[|]\s*($page_rx)$!o) {
($alttext, $page) = ($1, $2);
elsif(m!^(.*?)\s*[|]\s*(?:/\s*|)"(.+)"$!) {
($alttext, $node) = ($1,$2);
elsif(m!^($page_rx)\s*/\s*"(.+)"$!o) {
($page, $node) = ($1, $2);
elsif(m!^($page_rx)\s*/\s*(.+)$!o) {
($page, $node) = ($1, $2);
# non-standard: Hyperlink
elsif(m!^((?:http|ftp|mailto|news):.+)$!i) {
elsif(m!^(.*?)\s*[|]\s*($page_rx)\s*/\s*(.+)$!o) {
($alttext, $page, $node) = ($1, $2, $3);
elsif(m!^(.*?)\s*[|]\s*/(.+)$!) {
($alttext, $node) = ($1,$2);
# nonstandard: alttext and hyperlink
elsif(m!^(.*?)\s*[|]\s*((?:http|ftp|mailto|news):.+)$!) {
($alttext, $node) = ($1,$2);
# must be an item or a "malformed" section (without "")
# collapse whitespace in nodes
# empty alternative text expands to node name
$alttext = $node | $page;
if($page =~ /[(]\w*[)]$/) {
$self->warning("(section) in '$page' deprecated");
$self->warning("node '$node' contains non-escaped | or /");
if($alttext =~ m:[|/]:) {
$self->warning("alternative text '$node' contains non-escaped | or /");
$self->{-alttext} = $alttext;
#warn "DEBUG: page=$page section=$section item=$item alttext=$alttext\n";
$self->_construct_text();
my $alttext = $self->alttext();
my $type = $self->type();
my $section = $self->node();
my $page = $self->page();
$page =~ s/([(]\w*[)])$// && ($page_ext = $1);
$self->{_text} = $alttext;
elsif($type eq 'hyperlink') {
$self->{_text} = $section;
$self->{_text} = (!$section ? '' :
$type eq 'item' ? "the $section entry" :
"the section on $section" ) .
($page ? ($section ? ' in ':'') . "the $page$page_ext manpage" :
' elsewhere in this document');
# for being marked up later
# use the non-standard markers P<> and Q<>, so that the resulting
# text can be parsed by the translators. It's their job to put
# the correct hypertext around the linktext
$self->{_markup} = "Q<$alttext>";
elsif($type eq 'hyperlink') {
$self->{_markup} = "Q<$section>";
$self->{_markup} = (!$section ? '' :
$type eq 'item' ? "the Q<$section> entry" :
"the section on Q<$section>" ) .
($page ? ($section ? ' in ':'') . "the P<$page>$page_ext manpage" :
' elsewhere in this document');
=item $link-E<gt>markup($string)
Set/retrieve the textual value of the link. This string contains special
markers C<PE<lt>E<gt>> and C<QE<lt>E<gt>> 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.
#' retrieve/set markuped text
return (@_ > 1) ? ($_[0]->{_markup} = $_[1]) : $_[0]->{_markup};
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
the *$|* entry in the +perlvar+ manpage
the section on *OPTIONS* in the +perldoc+ manpage
the section on *DESCRIPTION* elsewhere in this document
# The complete link's text
=item $link-E<gt>warning()
After parsing, this method returns any warnings encountered during the
push(@{$self->{_warnings}}, @_);
return @{$self->{_warnings}};
Just simple slots for storing information about the line and the file
the link was encountered in. Has to be filled in manually.
# The line in the file the link appears
return (@_ > 1) ? ($_[0]->{-line} = $_[1]) : $_[0]->{-line};
# The POD file name the link appears in
return (@_ > 1) ? ($_[0]->{-file} = $_[1]) : $_[0]->{-file};
This method sets or returns the POD page this link points to.
# The POD page the link appears on
$_[0]->_construct_text();
As above, but the destination node text of the link.
$_[0]->_construct_text();
=item $link-E<gt>alttext()
Sets or returns an alternative text specified in the link.
# Potential alternative text
$_[0]->{-alttext} = $_[1];
$_[0]->_construct_text();
The node type, either C<section> or C<item>. As an unofficial type,
there is also C<hyperlink>, derived from e.g. C<LE<lt>http://perl.comE<gt>>
# The type: item or headn
return (@_ > 1) ? ($_[0]->{-type} = $_[1]) : $_[0]->{-type};
Returns the link as contents of C<LE<lt>E<gt>>. Reciprocal to B<parse()>.
my $link = $self->page() || '';
my $node = $self->node();
$text =~ s/\|/E<verbar>/g;
if($self->type() eq 'section') {
$link .= ($link ? '/' : '') . '"' . $node . '"';
elsif($self->type() eq 'hyperlink') {
my $text = $self->alttext();
$text =~ s/\|/E<verbar>/g;
$@ = $msg; # this seems to work, too!
#-----------------------------------------------------------------------------
# class to hold POD page details
#-----------------------------------------------------------------------------
B<Pod::Cache> holds information about a set of POD documents,
especially the nodes for hyperlinks.
The following methods are available:
=item Pod::Cache-E<gt>new()
Create a new cache object. This object can hold an arbitrary number of
POD documents of class Pod::Cache::Item.
my $class = ref($this) || $this;
Add a new item to the cache. Without arguments, this method returns a
list of all cache elements.
my $item = Pod::Cache::Item->new(%param);
=item $cache-E<gt>find_page($name)
Look for a POD document named C<$name> in the cache. Returns the
reference to the corresponding Pod::Cache::Item object or undef if
if($_->page() eq $page) {
package Pod::Cache::Item;
B<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
The following methods are available:
=item Pod::Cache::Item-E<gt>new()
my $class = ref($this) || $this;
$self->{-nodes} = [] unless(defined $self->{-nodes});
=item $cacheitem-E<gt>page()
Set/retrieve the POD document name (e.g. "Pod::Parser").
return (@_ > 1) ? ($_[0]->{-page} = $_[1]) : $_[0]->{-page};
=item $cacheitem-E<gt>description()
Set/retrieve the POD short description as found in the C<=head1 NAME>
# The POD description, taken out of NAME if present
return (@_ > 1) ? ($_[0]->{-description} = $_[1]) : $_[0]->{-description};
=item $cacheitem-E<gt>path()
Set/retrieve the POD file storage path.
return (@_ > 1) ? ($_[0]->{-path} = $_[1]) : $_[0]->{-path};
=item $cacheitem-E<gt>file()
Set/retrieve the POD file name.
return (@_ > 1) ? ($_[0]->{-file} = $_[1]) : $_[0]->{-file};
=item $cacheitem-E<gt>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 C<find_node> method to work correctly.
push(@{$self->{-nodes}}, @nodes);
return @{$self->{-nodes}};
=item $cacheitem-E<gt>find_node($name)
Look for a node or index entry named C<$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.
push(@search, @{$self->{-nodes}}) if($self->{-nodes});
push(@search, @{$self->{-idx}}) if($self->{-idx});
=item $cacheitem-E<gt>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
push(@{$self->{-idx}}, @idx);
Marek Rouchal E<lt>marek@saftsack.fs.uni-bayreuth.deE<gt>, borrowing
a lot of things from L<pod2man> and L<pod2roff> as well as other POD
processing tools by Tom Christiansen, Brad Appleton and Russ Allbery.
L<pod2man>, L<pod2roff>, L<Pod::Parser>, L<Pod::Checker>,