Manual Pages for UNIX Darwin command on man Pod::Select

Pod::Select(3pm) Perl Programmers Reference Guide Pod::Select(3pm)

NAME

Pod::Select, podselect() - extract selected sections of POD from input

SYNOPSIS

use Pod::Select;

## Select all the POD sections for each file in @filelist

## and print the result on standard output.

podselect(@filelist);

## Same as above, but write to tmp.out

podselect({-output => "tmp.out"}, @filelist):

## 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):

## Select the "DESCRIPTION" section of the PODs from STDIN and write

## the result to STDERR.

podselect({-output => ">&STDERR", -sections => ["DESCRIPTION"]}, \*STDIN);

use Pod::Select;

## Create a parser object for selecting POD sections from the input

$parser = new Pod::Select();

## Select all the POD sections for each file in @filelist

## and print the result to tmp.out.

$parser->parsefromfile("<&STDIN", "tmp.out");

## 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->parsefromfile($); }

## Select the "DESCRIPTION" and "SEE ALSO" sections of the PODs from

## STDIN and write the result to STDERR.

$parser->select("DESCRIPTION");

$parser->addselection("SEE ALSO");

$parser->parsefromfilehandle(\*STDIN, \*STDERR);

RREEQQUUIIRREESS perl5.005, Pod::Parser, Exporter, Carp EEXXPPOORRTTSS podselect()

DESCRIPTION

ppooddsseelleecctt(()) is a function which will extract specified sections of pod documentation from an input stream. This ability is provided by the PPoodd::::SSeelleecctt module which is a subclass of PPoodd::::PPaarrsseerr. PPoodd::::SSeelleecctt provides a method named sseelleecctt(()) to specify the set of POD sections to select for processing/printing. ppooddsseelleecctt(()) merely creates a PPoodd::::SSeelleecctt object and then invokes the ppooddsseelleecctt(()) followed by ppaarrsseeffrroommffiillee(()). SSEECCTTIIOONN SSPPEECCIIFFIICCAATTIIOONNSS ppooddsseelleecctt(()) and PPoodd::::SSeelleecctt::::sseelleecctt(()) may be given one or more "section specifications" to restrict the text processed to only the desired set

of sections and their corresponding subsections. A section specifica-

tion is a string containing one or more Perl-style regular expressions

separated by forward slashes ("/"). If you need to use a forward slash literally within a section title you can escape it with a backslash ("\/"). The formal syntax of a section specification is:

+o head1-title-regex/head2-title-regex/...

Any omitted or empty regular expressions will default to ".*". Please note that each regular expression given is implicitly anchored by

adding "^" and "$" to the beginning and end. Also, if a given regular

expression starts with a "!" character, then the expression is negated (so "!foo" would match anything except "foo"). Some example section specifications follow.

+o Match the "NAME" and "SYNOPSIS" sections and all of their subsec-

tions:

"NAME|SYNOPSIS"

+o Match only the "Question" and "Answer" subsections of the "DESCRIP-

TION" section:

"DESCRIPTION/Question|Answer"

+o Match the "Comments" subsection of all sections: "/Comments"

+o Match all subsections of "DESCRIPTION" except for "Comments":

"DESCRIPTION/!Comments"

+o Match the "DESCRIPTION" section but do not match any of its subsec-

tions:

"DESCRIPTION/!.+"

+o Match all top level sections but none of their subsections: "/!.+" OOBBJJEECCTT MMEETTHHOODDSS The following methods are provided in this module. Each one takes a reference to the object itself as an implicit first parameter. ccuurrrrhheeaaddiinnggss(())

($head1, $head2, $head3, ...) = $parser->currheadings();

$head1 = $parser->currheadings(1);

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. 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 "undef" is returned. sseelleecctt(())

$parser->select($sectionspec1,$sectionspec2,...);

This method is used to select the particular sections and subsections of POD documentation that are to be printed and/or processed. The existing set of selected sections is replaced with the given set of sections. See aaddddsseelleeccttiioonn(()) for adding to the current set of selected sections.

Each of the $sectionspec arguments should be a section specification

as described in "SECTION SPECIFICATIONS". The section specifications are parsed by this method and the resulting regular expressions are stored in the invoking object.

If no $sectionspec arguments are given, then the existing set of

selected sections is cleared out (which means "all" sections will be processed). This method should not normally be overridden by subclasses. aaddddsseelleeccttiioonn(())

$parser->addselection($sectionspec1,$sectionspec2,...);

This method is used to add to the currently selected sections and sub-

sections of POD documentation that are to be printed and/or processed. See for replacing the currently selected sections.

Each of the $sectionspec arguments should be a section specification

as described in "SECTION SPECIFICATIONS". The section specifications are parsed by this method and the resulting regular expressions are stored in the invoking object. This method should not normally be overridden by subclasses. cclleeaarrsseelleeccttiioonnss(())

$parser->clearselections();

This method takes no arguments, it has the exact same effect as invok-

ing with no arguments. mmaattcchhsseeccttiioonn(())

$boolean = $parser->matchsection($heading1,$heading2,...);

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 sseelleecctt(()) and aaddddsseelleeccttiioonn(()) (or if there are no explictly selected/deselected sections).

The arguments $heading1, $heading2, etc. are the heading titles of the

corresponding sections, subsections, etc. to try and match. If $head-

ingN is omitted then it defaults to the current corresponding section heading title in the input. This method should not normally be overridden by subclasses. iisssseelleecctteedd(())

$boolean = $parser->isselected($paragraph);

This method is used to determine if the block of text given in $para-

graph falls within the currently selected set of POD sections and sub-

sections to be printed or processed. This method is also responsible for keeping track of the current input section and subsections. It is

assumed that $paragraph is the most recently read (but not yet pro-

cessed) input paragraph.

The value returned will be true if the $paragraph and the rest of the

text in the same section as $paragraph should be selected (included)

for processing; otherwise a false value is returned. EEXXPPOORRTTEEDD FFUUNNCCTTIIOONNSS The following functions are exported by this module. Please note that these are functions (not methods) and therefore "do not" take an implicit first argument. ppooddsseelleecctt(())

podselect(\%options,@filelist);

ppooddsseelleecctt will print the raw (untranslated) POD paragraphs of all POD sections in the given input files specified by @filelist according to the given options. If any argument to ppooddsseelleecctt is a reference to a hash (associative

array) then the values with the following keys are processed as fol-

lows:

-oouuttppuutt

A string corresponding to the desired output file (or ">&STDOUT" or ">&STDERR"). The default is to use standard output.

-sseeccttiioonnss

A reference to an array of sections specifications (as described in "SECTION SPECIFICATIONS") which indicate the desired set of POD sections and subsections to be selected from input. If no section specifications are given, then all sections of the PODs are used.

All other arguments should correspond to the names of input files con-

taining POD sections. A file name of "-" or "<&STDIN" will be inter-

peted to mean standard input (which is the default if no filenames are given). PPRRIIVVAATTEE MMEETTHHOODDSS AANNDD DDAATTAA PPoodd::::SSeelleecctt 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 PPoodd::::SSeelleecctt source code.

Private data fields are stored in the hash-object whose reference is

returned by the nneeww(()) constructor for this class. The names of all pri-

vate methods and data-fields used by PPoodd::::SSeelleecctt begin with a prefix of

"" and match the regular expression "/^\w+$/".