Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Pod::ParseUtils.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Pod::ParseUtils 3"
.TH Pod::ParseUtils 3 "2002-06-01" "perl v5.8.0" "Perl Programmers Reference Guide"
.SH "NAME"
Pod::ParseUtils \- helpers for POD parsing and conversion
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Pod::ParseUtils;
.Ve
.PP
.Vb 2
\&  my $list = new Pod::List;
\&  my $link = Pod::Hyperlink->new('Pod::Parser');
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBPod::ParseUtils\fR contains a few object-oriented helper packages for
\&\s-1POD\s0 parsing and processing (i.e. in \s-1POD\s0 formatters and translators).
.Sh "Pod::List"
.IX Subsection "Pod::List"
\&\fBPod::List\fR can be used to hold information about \s-1POD\s0 lists
(written as =over ... =item ... =back) for further processing.
The following methods are available:
.IP "Pod::List\->\fInew()\fR" 4
.IX Item "Pod::List->new()"
Create a new list object. Properties may be specified through a hash
reference like this:
.Sp
.Vb 1
\&  my $list = Pod::List->new({ -start => $., -indent => 4 });
.Ve
.Sp
See the individual methods/properties for details.
.IP "$list\->\fIfile()\fR" 4
.IX Item "$list->file()"
Without argument, retrieves the file name the list is in. This must
have been set before by either specifying \fB\-file\fR in the \fB\f(BInew()\fB\fR
method or by calling the \fB\f(BIfile()\fB\fR method with a scalar argument.
.IP "$list\->\fIstart()\fR" 4
.IX Item "$list->start()"
Without argument, retrieves the line number where the list started.
This must have been set before by either specifying \fB\-start\fR in the
\&\fB\f(BInew()\fB\fR method or by calling the \fB\f(BIstart()\fB\fR method with a scalar
argument.
.IP "$list\->\fIindent()\fR" 4
.IX Item "$list->indent()"
Without argument, retrieves the indent level of the list as specified
in \f(CW\*(C`=over n\*(C'\fR. This must have been set before by either specifying
\&\fB\-indent\fR in the \fB\f(BInew()\fB\fR method or by calling the \fB\f(BIindent()\fB\fR method
with a scalar argument.
.IP "$list\->\fItype()\fR" 4
.IX Item "$list->type()"
Without argument, retrieves the list type, which can be an arbitrary value,
e.g. \f(CW\*(C`OL\*(C'\fR, \f(CW\*(C`UL\*(C'\fR, ... when thinking the \s-1HTML\s0 way.
This must have been set before by either specifying
\&\fB\-type\fR in the \fB\f(BInew()\fB\fR method or by calling the \fB\f(BItype()\fB\fR method
with a scalar argument.
.IP "$list\->\fIrx()\fR" 4
.IX Item "$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 \s-1HTML\s0, one might strip the leading number in
an ordered list as \f(CW\*(C`<OL>\*(C'\fR already prints numbers itself.
This must have been set before by either specifying
\&\fB\-rx\fR in the \fB\f(BInew()\fB\fR method or by calling the \fB\f(BIrx()\fB\fR method
with a scalar argument.
.IP "$list\->\fIitem()\fR" 4
.IX Item "$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.
.IP "$list\->\fIparent()\fR" 4
.IX Item "$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 specifying
\&\fB\-parent\fR in the \fB\f(BInew()\fB\fR method or by calling the \fB\f(BIparent()\fB\fR method
with a scalar argument.
.IP "$list\->\fItag()\fR" 4
.IX Item "$list->tag()"
Without argument, retrieves information about the list tag, which can be
any scalar.
This must have been set before by either specifying
\&\fB\-tag\fR in the \fB\f(BInew()\fB\fR method or by calling the \fB\f(BItag()\fB\fR method
with a scalar argument.
.Sh "Pod::Hyperlink"
.IX Subsection "Pod::Hyperlink"
\&\fBPod::Hyperlink\fR is a class for manipulation of \s-1POD\s0 hyperlinks. Usage:
.PP
.Vb 1
\&  my $link = Pod::Hyperlink->new('alternative text|page/"section in page"');
.Ve
.PP
The \fBPod::Hyperlink\fR class is mainly designed to parse the contents of the
\&\f(CW\*(C`L<...>\*(C'\fR sequence, providing a simple interface for accessing the
different parts of a \s-1POD\s0 hyperlink for further processing. It can also be
used to construct hyperlinks.
.IP "Pod::Hyperlink\->\fInew()\fR" 4
.IX Item "Pod::Hyperlink->new()"
The \fB\f(BInew()\fB\fR method can either be passed a set of key/value pairs or a single
scalar value, namely the contents of a \f(CW\*(C`L<...>\*(C'\fR sequence. An object
of the class \f(CW\*(C`Pod::Hyperlink\*(C'\fR is returned. The value \f(CW\*(C`undef\*(C'\fR indicates a
failure, the error message is stored in \f(CW$@\fR.
.IP "$link\->parse($string)" 4
.IX Item "$link->parse($string)"
This method can be used to (re)parse a (new) hyperlink, i.e. the contents
of a \f(CW\*(C`L<...>\*(C'\fR sequence. The result is stored in the current object.
Warnings are stored in the \fBwarnings\fR property.
E.g. sections like \f(CW\*(C`L<open(2)>\*(C'\fR are deprecated, as they do not point
to Perl documents. \f(CW\*(C`L<DBI::foo(3p)>\*(C'\fR is wrong as well, the manpage
section can simply be dropped.
.IP "$link\->markup($string)" 4
.IX Item "$link->markup($string)"
Set/retrieve the textual value of the link. This string contains special
markers \f(CW\*(C`P<>\*(C'\fR and \f(CW\*(C`Q<>\*(C'\fR 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.
.IP "$link\->\fItext()\fR" 4
.IX Item "$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):
.Sp
.Vb 4
\&  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
.Ve
.IP "$link\->\fIwarning()\fR" 4
.IX Item "$link->warning()"
After parsing, this method returns any warnings encountered during the
parsing process.
.IP "$link\->\fIfile()\fR" 4
.IX Item "$link->file()"
.PD 0
.IP "$link\->\fIline()\fR" 4
.IX Item "$link->line()"
.PD
Just simple slots for storing information about the line and the file
the link was encountered in. Has to be filled in manually.
.IP "$link\->\fIpage()\fR" 4
.IX Item "$link->page()"
This method sets or returns the \s-1POD\s0 page this link points to.
.IP "$link\->\fInode()\fR" 4
.IX Item "$link->node()"
As above, but the destination node text of the link.
.IP "$link\->\fIalttext()\fR" 4
.IX Item "$link->alttext()"
Sets or returns an alternative text specified in the link.
.IP "$link\->\fItype()\fR" 4
.IX Item "$link->type()"
The node type, either \f(CW\*(C`section\*(C'\fR or \f(CW\*(C`item\*(C'\fR. As an unofficial type,
there is also \f(CW\*(C`hyperlink\*(C'\fR, derived from e.g. \f(CW\*(C`L<http://perl.com>\*(C'\fR
.IP "$link\->\fIlink()\fR" 4
.IX Item "$link->link()"
Returns the link as contents of \f(CW\*(C`L<>\*(C'\fR. Reciprocal to \fB\f(BIparse()\fB\fR.
.Sh "Pod::Cache"
.IX Subsection "Pod::Cache"
\&\fBPod::Cache\fR holds information about a set of \s-1POD\s0 documents,
especially the nodes for hyperlinks.
The following methods are available:
.IP "Pod::Cache\->\fInew()\fR" 4
.IX Item "Pod::Cache->new()"
Create a new cache object. This object can hold an arbitrary number of
\&\s-1POD\s0 documents of class Pod::Cache::Item.
.IP "$cache\->\fIitem()\fR" 4
.IX Item "$cache->item()"
Add a new item to the cache. Without arguments, this method returns a
list of all cache elements.
.IP "$cache\->find_page($name)" 4
.IX Item "$cache->find_page($name)"
Look for a \s-1POD\s0 document named \f(CW$name\fR in the cache. Returns the
reference to the corresponding Pod::Cache::Item object or undef if
not found.
.Sh "Pod::Cache::Item"
.IX Subsection "Pod::Cache::Item"
\&\fBPod::Cache::Item\fR holds information about individual \s-1POD\s0 documents,
that can be grouped in a Pod::Cache object.
It is intended to hold information about the hyperlink nodes of \s-1POD\s0
documents.
The following methods are available:
.IP "Pod::Cache::Item\->\fInew()\fR" 4
.IX Item "Pod::Cache::Item->new()"
Create a new object.
.IP "$cacheitem\->\fIpage()\fR" 4
.IX Item "$cacheitem->page()"
Set/retrieve the \s-1POD\s0 document name (e.g. \*(L"Pod::Parser\*(R").
.IP "$cacheitem\->\fIdescription()\fR" 4
.IX Item "$cacheitem->description()"
Set/retrieve the \s-1POD\s0 short description as found in the \f(CW\*(C`=head1 NAME\*(C'\fR
section.
.IP "$cacheitem\->\fIpath()\fR" 4
.IX Item "$cacheitem->path()"
Set/retrieve the \s-1POD\s0 file storage path.
.IP "$cacheitem\->\fIfile()\fR" 4
.IX Item "$cacheitem->file()"
Set/retrieve the \s-1POD\s0 file name.
.IP "$cacheitem\->\fInodes()\fR" 4
.IX Item "$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 \f(CW\*(C`find_node\*(C'\fR method to work correctly.
.IP "$cacheitem\->find_node($name)" 4
.IX Item "$cacheitem->find_node($name)"
Look for a node or index entry named \f(CW$name\fR 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.
.IP "$cacheitem\->\fIidx()\fR" 4
.IX Item "$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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Marek Rouchal <marek@saftsack.fs.uni\-bayreuth.de>, borrowing
a lot of things from pod2man and pod2roff as well as other \s-1POD\s0
processing tools by Tom Christiansen, Brad Appleton and Russ Allbery.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
pod2man, pod2roff, Pod::Parser, Pod::Checker,
pod2html