Initial commit of OpenSPARC T2 architecture model.

[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / man / man3 / Pod::Select.3

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" 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::Select 3"
.TH Pod::Select 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide"
.SH "NAME"
Pod::Select, podselect() \- extract selected sections of POD from input
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Pod::Select;
.Ve
.PP
.Vb 3
\&    ## Select all the POD sections for each file in @filelist
\&    ## and print the result on standard output.
\&    podselect(@filelist);
.Ve
.PP
.Vb 2
\&    ## Same as above, but write to tmp.out
\&    podselect({-output => "tmp.out"}, @filelist):
.Ve
.PP
.Vb 3
\&    ## Select from the given filelist, only those POD sections that are
\&    ## within a 1st level section named any of: NAME, SYNOPSIS, OPTIONS.
\&    podselect({-sections => ["NAME|SYNOPSIS", "OPTIONS"]}, @filelist):
.Ve
.PP
.Vb 3
\&    ## Select the "DESCRIPTION" section of the PODs from STDIN and write
\&    ## the result to STDERR.
\&    podselect({-output => ">&STDERR", -sections => ["DESCRIPTION"]}, \e*STDIN);
.Ve
.PP
or
.PP
.Vb 1
\&    use Pod::Select;
.Ve
.PP
.Vb 2
\&    ## Create a parser object for selecting POD sections from the input
\&    $parser = new Pod::Select();
.Ve
.PP
.Vb 3
\&    ## Select all the POD sections for each file in @filelist
\&    ## and print the result to tmp.out.
\&    $parser->parse_from_file("<&STDIN", "tmp.out");
.Ve
.PP
.Vb 4
\&    ## Select from the given filelist, only those POD sections that are
\&    ## within a 1st level section named any of: NAME, SYNOPSIS, OPTIONS.
\&    $parser->select("NAME|SYNOPSIS", "OPTIONS");
\&    for (@filelist) { $parser->parse_from_file($_); }
.Ve
.PP
.Vb 5
\&    ## Select the "DESCRIPTION" and "SEE ALSO" sections of the PODs from
\&    ## STDIN and write the result to STDERR.
\&    $parser->select("DESCRIPTION");
\&    $parser->add_selection("SEE ALSO");
\&    $parser->parse_from_filehandle(\e*STDIN, \e*STDERR);
.Ve
.SH "REQUIRES"
.IX Header "REQUIRES"
perl5.005, Pod::Parser, Exporter, Carp
.SH "EXPORTS"
.IX Header "EXPORTS"
\&\fIpodselect()\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\f(BIpodselect()\fB\fR is a function which will extract specified sections of
pod documentation from an input stream. This ability is provided by the
\&\fBPod::Select\fR module which is a subclass of \fBPod::Parser\fR.
\&\fBPod::Select\fR provides a method named \fB\f(BIselect()\fB\fR to specify the set of
\&\s-1POD\s0 sections to select for processing/printing. \fB\f(BIpodselect()\fB\fR merely
creates a \fBPod::Select\fR object and then invokes the \fB\f(BIpodselect()\fB\fR
followed by \fB\f(BIparse_from_file()\fB\fR.
.SH "SECTION SPECIFICATIONS"
.IX Header "SECTION SPECIFICATIONS"
\&\fB\f(BIpodselect()\fB\fR and \fB\f(BIPod::Select::select()\fB\fR may be given one or more
\&\*(L"section specifications\*(R" to restrict the text processed to only the
desired set of sections and their corresponding subsections.  A section
specification is a string containing one or more Perl-style regular
expressions separated by forward slashes (\*(L"/\*(R").  If you need to use a
forward slash literally within a section title you can escape it with a
backslash (\*(L"\e/\*(R").
.PP
The formal syntax of a section specification is:
.IP "\(bu" 4
\&\fIhead1\-title\-regex\fR/\fIhead2\-title\-regex\fR/...
.PP
Any omitted or empty regular expressions will default to \*(L".*\*(R".
Please note that each regular expression given is implicitly
anchored by adding \*(L"^\*(R" and \*(L"$\*(R" to the beginning and end.  Also, if a
given regular expression starts with a \*(L"!\*(R" character, then the
expression is \fInegated\fR (so \f(CW\*(C`!foo\*(C'\fR would match anything \fIexcept\fR
\&\f(CW\*(C`foo\*(C'\fR).
.PP
Some example section specifications follow.
.IP "\(bu" 4
Match the \f(CW\*(C`NAME\*(C'\fR and \f(CW\*(C`SYNOPSIS\*(C'\fR sections and all of their subsections:
.Sp
\&\f(CW\*(C`NAME|SYNOPSIS\*(C'\fR
.IP "\(bu" 4
Match only the \f(CW\*(C`Question\*(C'\fR and \f(CW\*(C`Answer\*(C'\fR subsections of the \f(CW\*(C`DESCRIPTION\*(C'\fR
section:
.Sp
\&\f(CW\*(C`DESCRIPTION/Question|Answer\*(C'\fR
.IP "\(bu" 4
Match the \f(CW\*(C`Comments\*(C'\fR subsection of \fIall\fR sections:
.Sp
\&\f(CW\*(C`/Comments\*(C'\fR
.IP "\(bu" 4
Match all subsections of \f(CW\*(C`DESCRIPTION\*(C'\fR \fIexcept\fR for \f(CW\*(C`Comments\*(C'\fR:
.Sp
\&\f(CW\*(C`DESCRIPTION/!Comments\*(C'\fR
.IP "\(bu" 4
Match the \f(CW\*(C`DESCRIPTION\*(C'\fR section but do \fInot\fR match any of its subsections:
.Sp
\&\f(CW\*(C`DESCRIPTION/!.+\*(C'\fR
.IP "\(bu" 4
Match all top level sections but none of their subsections:
.Sp
\&\f(CW\*(C`/!.+\*(C'\fR
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
The following methods are provided in this module. Each one takes a
reference to the object itself as an implicit first parameter.
.SH "\fB\fP\f(BIcurr_headings()\fP\fB\fP"
.IX Header "curr_headings()"
.Vb 2
\&            ($head1, $head2, $head3, ...) = $parser->curr_headings();
\&            $head1 = $parser->curr_headings(1);
.Ve
.PP
This method returns a list of the currently active section headings and
subheadings in the document being parsed. The list of headings returned
corresponds to the most recently parsed paragraph of the input.
.PP
If an argument is given, it must correspond to the desired section
heading number, in which case only the specified section heading is
returned. If there is no current section heading at the specified
level, then \f(CW\*(C`undef\*(C'\fR is returned.
.SH "\fB\fP\f(BIselect()\fP\fB\fP"
.IX Header "select()"
.Vb 1
\&            $parser->select($section_spec1,$section_spec2,...);
.Ve
.PP
This method is used to select the particular sections and subsections of
\&\s-1POD\s0 documentation that are to be printed and/or processed. The existing
set of selected sections is \fIreplaced\fR with the given set of sections.
See \fB\f(BIadd_selection()\fB\fR for adding to the current set of selected
sections.
.PP
Each of the \f(CW$section_spec\fR arguments should be a section specification
as described in \*(L"\s-1SECTION\s0 \s-1SPECIFICATIONS\s0\*(R".  The section specifications
are parsed by this method and the resulting regular expressions are
stored in the invoking object.
.PP
If no \f(CW$section_spec\fR arguments are given, then the existing set of
selected sections is cleared out (which means \f(CW\*(C`all\*(C'\fR sections will be
processed).
.PP
This method should \fInot\fR normally be overridden by subclasses.
.SH "\fB\fP\f(BIadd_selection()\fP\fB\fP"
.IX Header "add_selection()"
.Vb 1
\&            $parser->add_selection($section_spec1,$section_spec2,...);
.Ve
.PP
This method is used to add to the currently selected sections and
subsections of \s-1POD\s0 documentation that are to be printed and/or
processed. See <\fIselect()\fR> for replacing the currently selected sections.
.PP
Each of the \f(CW$section_spec\fR arguments should be a section specification
as described in \*(L"\s-1SECTION\s0 \s-1SPECIFICATIONS\s0\*(R". The section specifications
are parsed by this method and the resulting regular expressions are
stored in the invoking object.
.PP
This method should \fInot\fR normally be overridden by subclasses.
.SH "\fB\fP\f(BIclear_selections()\fP\fB\fP"
.IX Header "clear_selections()"
.Vb 1
\&            $parser->clear_selections();
.Ve
.PP
This method takes no arguments, it has the exact same effect as invoking
<\fIselect()\fR> with no arguments.
.SH "\fB\fP\f(BImatch_section()\fP\fB\fP"
.IX Header "match_section()"
.Vb 1
\&            $boolean = $parser->match_section($heading1,$heading2,...);
.Ve
.PP
Returns a value of true if the given section and subsection heading
titles match any of the currently selected section specifications in
effect from prior calls to \fB\f(BIselect()\fB\fR and \fB\f(BIadd_selection()\fB\fR (or if
there are no explictly selected/deselected sections).
.PP
The arguments \f(CW$heading1\fR, \f(CW$heading2\fR, etc. are the heading titles of
the corresponding sections, subsections, etc. to try and match.  If
\&\f(CW$headingN\fR is omitted then it defaults to the current corresponding
section heading title in the input.
.PP
This method should \fInot\fR normally be overridden by subclasses.
.SH "\fB\fP\f(BIis_selected()\fP\fB\fP"
.IX Header "is_selected()"
.Vb 1
\&            $boolean = $parser->is_selected($paragraph);
.Ve
.PP
This method is used to determine if the block of text given in
\&\f(CW$paragraph\fR falls within the currently selected set of \s-1POD\s0 sections
and subsections to be printed or processed. This method is also
responsible for keeping track of the current input section and
subsections. It is assumed that \f(CW$paragraph\fR is the most recently read
(but not yet processed) input paragraph.
.PP
The value returned will be true if the \f(CW$paragraph\fR and the rest of the
text in the same section as \f(CW$paragraph\fR should be selected (included)
for processing; otherwise a false value is returned.
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
The following functions are exported by this module. Please note that
these are functions (not methods) and therefore \f(CW\*(C`do not\*(C'\fR take an
implicit first argument.
.SH "\fB\fP\f(BIpodselect()\fP\fB\fP"
.IX Header "podselect()"
.Vb 1
\&            podselect(\e%options,@filelist);
.Ve
.PP
\&\fBpodselect\fR will print the raw (untranslated) \s-1POD\s0 paragraphs of all
\&\s-1POD\s0 sections in the given input files specified by \f(CW@filelist\fR
according to the given options.
.PP
If any argument to \fBpodselect\fR is a reference to a hash
(associative array) then the values with the following keys are
processed as follows:
.IP "\fB\-output\fR" 4
.IX Item "-output"
A string corresponding to the desired output file (or \*(L">&STDOUT\*(R"
or \*(L">&STDERR\*(R"). The default is to use standard output.
.IP "\fB\-sections\fR" 4
.IX Item "-sections"
A reference to an array of sections specifications (as described in
\&\*(L"\s-1SECTION\s0 \s-1SPECIFICATIONS\s0\*(R") which indicate the desired set of \s-1POD\s0
sections and subsections to be selected from input. If no section
specifications are given, then all sections of the PODs are used.
.PP
All other arguments should correspond to the names of input files
containing \s-1POD\s0 sections. A file name of \*(L"\-\*(R" or \*(L"<&STDIN\*(R" will
be interpeted to mean standard input (which is the default if no
filenames are given).
.SH "PRIVATE METHODS AND DATA"
.IX Header "PRIVATE METHODS AND DATA"
\&\fBPod::Select\fR makes uses a number of internal methods and data fields
which clients should not need to see or use. For the sake of avoiding
name collisions with client data and methods, these methods and fields
are briefly discussed here. Determined hackers may obtain further
information about them by reading the \fBPod::Select\fR source code.
.PP
Private data fields are stored in the hash-object whose reference is
returned by the \fB\f(BInew()\fB\fR constructor for this class. The names of all
private methods and data-fields used by \fBPod::Select\fR begin with a
prefix of \*(L"_\*(R" and match the regular expression \f(CW\*(C`/^_\ew+$/\*(C'\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Pod::Parser
.SH "AUTHOR"
.IX Header "AUTHOR"
Please report bugs using <http://rt.cpan.org>.
.PP
Brad Appleton <bradapp@enteract.com>
.PP
Based on code for \fBpod2text\fR written by
Tom Christiansen <tchrist@mox.perl.com>