1Pod::Select(3pm)       Perl Programmers Reference Guide       Pod::Select(3pm)
2
3
4

NAME

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

SYNOPSIS

9           use Pod::Select;
10
11           ## Select all the POD sections for each file in @filelist
12           ## and print the result on standard output.
13           podselect(@filelist);
14
15           ## Same as above, but write to tmp.out
16           podselect({-output => "tmp.out"}, @filelist):
17
18           ## Select from the given filelist, only those POD sections that are
19           ## within a 1st level section named any of: NAME, SYNOPSIS, OPTIONS.
20           podselect({-sections => ["NAME|SYNOPSIS", "OPTIONS"]}, @filelist):
21
22           ## Select the "DESCRIPTION" section of the PODs from STDIN and write
23           ## the result to STDERR.
24           podselect({-output => ">&STDERR", -sections => ["DESCRIPTION"]}, \*STDIN);
25
26       or
27
28           use Pod::Select;
29
30           ## Create a parser object for selecting POD sections from the input
31           $parser = new Pod::Select();
32
33           ## Select all the POD sections for each file in @filelist
34           ## and print the result to tmp.out.
35           $parser->parse_from_file("<&STDIN", "tmp.out");
36
37           ## Select from the given filelist, only those POD sections that are
38           ## within a 1st level section named any of: NAME, SYNOPSIS, OPTIONS.
39           $parser->select("NAME|SYNOPSIS", "OPTIONS");
40           for (@filelist) { $parser->parse_from_file($_); }
41
42           ## Select the "DESCRIPTION" and "SEE ALSO" sections of the PODs from
43           ## STDIN and write the result to STDERR.
44           $parser->select("DESCRIPTION");
45           $parser->add_selection("SEE ALSO");
46           $parser->parse_from_filehandle(\*STDIN, \*STDERR);
47

REQUIRES

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

EXPORTS

52       podselect()
53

DESCRIPTION

55       podselect() is a function which will extract specified sections of pod
56       documentation from an input stream. This ability is provided by the
57       Pod::Select module which is a subclass of Pod::Parser.  Pod::Select
58       provides a method named select() to specify the set of POD sections to
59       select for processing/printing. podselect() merely creates a
60       Pod::Select object and then invokes the podselect() followed by
61       parse_from_file().
62

SECTION SPECIFICATIONS

64       podselect() and Pod::Select::select() may be given one or more "section
65       specifications" to restrict the text processed to only the desired set
66       of sections and their corresponding subsections.  A section
67       specification is a string containing one or more Perl-style regular
68       expressions separated by forward slashes ("/").  If you need to use a
69       forward slash literally within a section title you can escape it with a
70       backslash ("\/").
71
72       The formal syntax of a section specification is:
73
74       ·   head1-title-regex/head2-title-regex/...
75
76       Any omitted or empty regular expressions will default to ".*".  Please
77       note that each regular expression given is implicitly anchored by
78       adding "^" and "$" to the beginning and end.  Also, if a given regular
79       expression starts with a "!" character, then the expression is negated
80       (so "!foo" would match anything except "foo").
81
82       Some example section specifications follow.
83
84       ·   Match the "NAME" and "SYNOPSIS" sections and all of their
85           subsections:
86
87           "NAME|SYNOPSIS"
88
89       ·   Match only the "Question" and "Answer" subsections of the
90           "DESCRIPTION" section:
91
92           "DESCRIPTION/Question|Answer"
93
94       ·   Match the "Comments" subsection of all sections:
95
96           "/Comments"
97
98       ·   Match all subsections of "DESCRIPTION" except for "Comments":
99
100           "DESCRIPTION/!Comments"
101
102       ·   Match the "DESCRIPTION" section but do not match any of its
103           subsections:
104
105           "DESCRIPTION/!.+"
106
107       ·   Match all top level sections but none of their subsections:
108
109           "/!.+"
110

OBJECT METHODS

112       The following methods are provided in this module. Each one takes a
113       reference to the object itself as an implicit first parameter.
114

curr_headings()

116                   ($head1, $head2, $head3, ...) = $parser->curr_headings();
117                   $head1 = $parser->curr_headings(1);
118
119       This method returns a list of the currently active section headings and
120       subheadings in the document being parsed. The list of headings returned
121       corresponds to the most recently parsed paragraph of the input.
122
123       If an argument is given, it must correspond to the desired section
124       heading number, in which case only the specified section heading is
125       returned. If there is no current section heading at the specified
126       level, then "undef" is returned.
127

select()

129                   $parser->select($section_spec1,$section_spec2,...);
130
131       This method is used to select the particular sections and subsections
132       of POD documentation that are to be printed and/or processed. The
133       existing set of selected sections is replaced with the given set of
134       sections.  See add_selection() for adding to the current set of
135       selected sections.
136
137       Each of the $section_spec arguments should be a section specification
138       as described in "SECTION SPECIFICATIONS".  The section specifications
139       are parsed by this method and the resulting regular expressions are
140       stored in the invoking object.
141
142       If no $section_spec arguments are given, then the existing set of
143       selected sections is cleared out (which means "all" sections will be
144       processed).
145
146       This method should not normally be overridden by subclasses.
147

add_selection()

149                   $parser->add_selection($section_spec1,$section_spec2,...);
150
151       This method is used to add to the currently selected sections and
152       subsections of POD documentation that are to be printed and/or
153       processed. See <select()> for replacing the currently selected
154       sections.
155
156       Each of the $section_spec arguments should be a section specification
157       as described in "SECTION SPECIFICATIONS". The section specifications
158       are parsed by this method and the resulting regular expressions are
159       stored in the invoking object.
160
161       This method should not normally be overridden by subclasses.
162

clear_selections()

164                   $parser->clear_selections();
165
166       This method takes no arguments, it has the exact same effect as
167       invoking <select()> with no arguments.
168

match_section()

170                   $boolean = $parser->match_section($heading1,$heading2,...);
171
172       Returns a value of true if the given section and subsection heading
173       titles match any of the currently selected section specifications in
174       effect from prior calls to select() and add_selection() (or if there
175       are no explicitly selected/deselected sections).
176
177       The arguments $heading1, $heading2, etc. are the heading titles of the
178       corresponding sections, subsections, etc. to try and match.  If
179       $headingN is omitted then it defaults to the current corresponding
180       section heading title in the input.
181
182       This method should not normally be overridden by subclasses.
183

is_selected()

185                   $boolean = $parser->is_selected($paragraph);
186
187       This method is used to determine if the block of text given in
188       $paragraph falls within the currently selected set of POD sections and
189       subsections to be printed or processed. This method is also responsible
190       for keeping track of the current input section and subsections. It is
191       assumed that $paragraph is the most recently read (but not yet
192       processed) input paragraph.
193
194       The value returned will be true if the $paragraph and the rest of the
195       text in the same section as $paragraph should be selected (included)
196       for processing; otherwise a false value is returned.
197

EXPORTED FUNCTIONS

199       The following functions are exported by this module. Please note that
200       these are functions (not methods) and therefore "do not" take an
201       implicit first argument.
202

podselect()

204                   podselect(\%options,@filelist);
205
206       podselect will print the raw (untranslated) POD paragraphs of all POD
207       sections in the given input files specified by @filelist according to
208       the given options.
209
210       If any argument to podselect is a reference to a hash (associative
211       array) then the values with the following keys are processed as
212       follows:
213
214       -output
215           A string corresponding to the desired output file (or ">&STDOUT" or
216           ">&STDERR"). The default is to use standard output.
217
218       -sections
219           A reference to an array of sections specifications (as described in
220           "SECTION SPECIFICATIONS") which indicate the desired set of POD
221           sections and subsections to be selected from input. If no section
222           specifications are given, then all sections of the PODs are used.
223
224       All other arguments should correspond to the names of input files
225       containing POD sections. A file name of "-" or "<&STDIN" will be
226       interpreted to mean standard input (which is the default if no
227       filenames are given).
228

PRIVATE METHODS AND DATA

230       Pod::Select makes uses a number of internal methods and data fields
231       which clients should not need to see or use. For the sake of avoiding
232       name collisions with client data and methods, these methods and fields
233       are briefly discussed here. Determined hackers may obtain further
234       information about them by reading the Pod::Select source code.
235
236       Private data fields are stored in the hash-object whose reference is
237       returned by the new() constructor for this class. The names of all
238       private methods and data-fields used by Pod::Select begin with a prefix
239       of "_" and match the regular expression "/^_\w+$/".
240

SEE ALSO

242       Pod::Parser
243

AUTHOR

245       Please report bugs using <http://rt.cpan.org>.
246
247       Brad Appleton <bradapp@enteract.com>
248
249       Based on code for pod2text written by Tom Christiansen
250       <tchrist@mox.perl.com>
251
252
253
254perl v5.12.4                      2011-06-01                  Pod::Select(3pm)
Impressum