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

Pod::Select

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

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);

or

    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->parse_from_file("<&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->parse_from_file($_); }

    ## 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(\*STDIN, \*STDERR);

 

REQUIRES

perl5.005, Pod::Parser, Exporter, Carp 

EXPORTS

podselect() 

DESCRIPTION

podselect() is a function which will extract specified sections ofpod documentation from an input stream. This ability is provided by thePod::Select module which is a subclass of Pod::Parser.Pod::Select provides a method named select() to specify the set ofPOD sections to select for processing/printing. podselect() merelycreates a Pod::Select object and then invokes the podselect()followed by parse_from_file(). 

SECTION SPECIFICATIONS

podselect() and Pod::Select::select() may be given one or more``section specifications'' to restrict the text processed to only thedesired set of sections and their corresponding subsections. A sectionspecification is a string containing one or more Perl-style regularexpressions separated by forward slashes (``/''). If you need to use aforward slash literally within a section title you can escape it with abackslash (``\/'').

The formal syntax of a section specification is:

*

head1-title-regex/head2-title-regex/...

Any omitted or empty regular expressions will default to ``.*''.Please note that each regular expression given is implicitlyanchored by adding ``^'' and ``$'' to the beginning and end. Also, if agiven regular expression starts with a ``!'' character, then theexpression is negated (so "!foo" would match anything except"foo").

Some example section specifications follow.

*

Match the "NAME" and "SYNOPSIS" sections and all of their subsections:

"NAME|SYNOPSIS"

*

Match only the "Question" and "Answer" subsections of the "DESCRIPTION"section:

"DESCRIPTION/Question|Answer"

*

Match the "Comments" subsection of all sections:

"/Comments"

*

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

"DESCRIPTION/!Comments"

*

Match the "DESCRIPTION" section but do not match any of its subsections:

"DESCRIPTION/!.+"

*

Match all top level sections but none of their subsections:

"/!.+"

 

OBJECT METHODS

The following methods are provided in this module. Each one takes areference to the object itself as an implicit first parameter. 

curr_headings()

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

This method returns a list of the currently active section headings andsubheadings in the document being parsed. The list of headings returnedcorresponds to the most recently parsed paragraph of the input.

If an argument is given, it must correspond to the desired sectionheading number, in which case only the specified section heading isreturned. If there is no current section heading at the specifiedlevel, then "undef" is returned. 

select()

            $parser->select($section_spec1,$section_spec2,...);

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

Each of the "$section_spec" arguments should be a section specificationas described in the section on "SECTION SPECIFICATIONS". The section specificationsare parsed by this method and the resulting regular expressions arestored in the invoking object.

If no "$section_spec" arguments are given, then the existing set ofselected sections is cleared out (which means "all" sections will beprocessed).

This method should not normally be overridden by subclasses. 

add_selection()

            $parser->add_selection($section_spec1,$section_spec2,...);

This method is used to add to the currently selected sections andsubsections of POD documentation that are to be printed and/orprocessed. See <select()> for replacing the currently selected sections.

Each of the "$section_spec" arguments should be a section specificationas described in the section on "SECTION SPECIFICATIONS". The section specificationsare parsed by this method and the resulting regular expressions arestored in the invoking object.

This method should not normally be overridden by subclasses. 

clear_selections()

            $parser->clear_selections();

This method takes no arguments, it has the exact same effect as invoking<select()> with no arguments. 

match_section()

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

Returns a value of true if the given section and subsection headingtitles match any of the currently selected section specifications ineffect from prior calls to select() and add_selection() (or ifthere are no explictly selected/deselected sections).

The arguments "$heading1", "$heading2", etc. are the heading titles ofthe corresponding sections, subsections, etc. to try and match. If"$headingN" is omitted then it defaults to the current correspondingsection heading title in the input.

This method should not normally be overridden by subclasses. 

is_selected()

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

This method is used to determine if the block of text given in"$paragraph" falls within the currently selected set of POD sectionsand subsections to be printed or processed. This method is alsoresponsible for keeping track of the current input section andsubsections. It is assumed that "$paragraph" is the most recently read(but not yet processed) input paragraph.

The value returned will be true if the "$paragraph" and the rest of thetext in the same section as "$paragraph" should be selected (included)for processing; otherwise a false value is returned. 

EXPORTED FUNCTIONS

The following functions are exported by this module. Please note thatthese are functions (not methods) and therefore "do not" take animplicit first argument. 

podselect()

            podselect(\%options,@filelist);

podselect will print the raw (untranslated) POD paragraphs of allPOD sections in the given input files specified by "@filelist"according to the given options.

If any argument to podselect is a reference to a hash(associative array) then the values with the following keys areprocessed as follows:

-output

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

-sections

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

All other arguments should correspond to the names of input filescontaining POD sections. A file name of ``-'' or ``<&STDIN'' willbe interpeted to mean standard input (which is the default if nofilenames are given). 

PRIVATE METHODS AND DATA

Pod::Select makes uses a number of internal methods and data fieldswhich clients should not need to see or use. For the sake of avoidingname collisions with client data and methods, these methods and fieldsare briefly discussed here. Determined hackers may obtain furtherinformation about them by reading the Pod::Select source code.

Private data fields are stored in the hash-object whose reference isreturned by the new() constructor for this class. The names of allprivate methods and data-fields used by Pod::Select begin with aprefix of ``_'' and match the regular expression "/^_\w+$/". 

SEE ALSO

the Pod::Parser manpage 

AUTHOR

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

Brad Appleton <bradappAATTenteract.com>

Based on code for pod2text written byTom Christiansen <tchristAATTmox.perl.com>

---

 

Index

NAME

SYNOPSIS

REQUIRES

EXPORTS

DESCRIPTION

SECTION SPECIFICATIONS

OBJECT METHODS

curr_headings()

select()

add_selection()

clear_selections()

match_section()

is_selected()

EXPORTED FUNCTIONS

podselect()

PRIVATE METHODS AND DATA

SEE ALSO

AUTHOR

---

This document was created byman2html,using the manual pages.