1Pod::Select(3pm) Perl Programmers Reference Guide Pod::Select(3pm)
2
6 Pod::Select, podselect() - extract selected sections of POD from input
7
9 use Pod::Select;
10 ## Select all the POD sections for each file in @filelist
12 ## and print the result on standard output.
13 podselect(@filelist);
14 ## Same as above, but write to tmp.out
16 podselect({-output => "tmp.out"}, @filelist):
17 ## 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 ## Select the "DESCRIPTION" section of the PODs from STDIN and write
23 ## the result to STDERR.
24 podselect({-output => ">&STDERR", -sections => ["DESCRIPTION"]}, \*STDIN);
25 or
27 use Pod::Select;
29 ## Create a parser object for selecting POD sections from the input
31 $parser = new Pod::Select();
32 ## 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 ## 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 ## 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
49 perl5.005, Pod::Parser, Exporter, Carp
50
52 podselect()
53
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
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 specifica‐
67 tion is a string containing one or more Perl-style regular expressions
68 separated by forward slashes ("/"). If you need to use a forward slash
69 literally within a section title you can escape it with a backslash
70 ("\/").
71 The formal syntax of a section specification is:
73 · head1-title-regex/head2-title-regex/...
75 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 Some example section specifications follow.
83 · Match the "NAME" and "SYNOPSIS" sections and all of their subsec‐
85 tions:
86 "NAME⎪SYNOPSIS"
88 · Match only the "Question" and "Answer" subsections of the "DESCRIP‐
90 TION" section:
91 "DESCRIPTION/Question⎪Answer"
93 · Match the "Comments" subsection of all sections:
95 "/Comments"
97 · Match all subsections of "DESCRIPTION" except for "Comments":
99 "DESCRIPTION/!Comments"
101 · Match the "DESCRIPTION" section but do not match any of its subsec‐
103 tions:
104 "DESCRIPTION/!.+"
106 · Match all top level sections but none of their subsections:
108 "/!.+"
110
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
116 ($head1, $head2, $head3, ...) = $parser->curr_headings();
117 $head1 = $parser->curr_headings(1);
118 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 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
129 $parser->select($section_spec1,$section_spec2,...);
130 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 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 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 This method should not normally be overridden by subclasses.
147
149 $parser->add_selection($section_spec1,$section_spec2,...);
150 This method is used to add to the currently selected sections and sub‐
152 sections of POD documentation that are to be printed and/or processed.
153 See <select()> for replacing the currently selected sections.
154 Each of the $section_spec arguments should be a section specification
156 as described in "SECTION SPECIFICATIONS". The section specifications
157 are parsed by this method and the resulting regular expressions are
158 stored in the invoking object.
159 This method should not normally be overridden by subclasses.
161
163 $parser->clear_selections();
164 This method takes no arguments, it has the exact same effect as invok‐
166 ing <select()> with no arguments.
167
169 $boolean = $parser->match_section($heading1,$heading2,...);
170 Returns a value of true if the given section and subsection heading
172 titles match any of the currently selected section specifications in
173 effect from prior calls to select() and add_selection() (or if there
174 are no explictly selected/deselected sections).
175 The arguments $heading1, $heading2, etc. are the heading titles of the
177 corresponding sections, subsections, etc. to try and match. If $head‐
178 ingN is omitted then it defaults to the current corresponding section
179 heading title in the input.
180 This method should not normally be overridden by subclasses.
182
184 $boolean = $parser->is_selected($paragraph);
185 This method is used to determine if the block of text given in $para‐
187 graph falls within the currently selected set of POD sections and sub‐
188 sections to be printed or processed. This method is also responsible
189 for keeping track of the current input section and subsections. It is
190 assumed that $paragraph is the most recently read (but not yet pro‐
191 cessed) input paragraph.
192 The value returned will be true if the $paragraph and the rest of the
194 text in the same section as $paragraph should be selected (included)
195 for processing; otherwise a false value is returned.
196
198 The following functions are exported by this module. Please note that
199 these are functions (not methods) and therefore "do not" take an
200 implicit first argument.
201
203 podselect(\%options,@filelist);
204 podselect will print the raw (untranslated) POD paragraphs of all POD
206 sections in the given input files specified by @filelist according to
207 the given options.
208 If any argument to podselect is a reference to a hash (associative
210 array) then the values with the following keys are processed as fol‐
211 lows:
212 -output
214 A string corresponding to the desired output file (or ">&STDOUT" or
215 ">&STDERR"). The default is to use standard output.
216 -sections
218 A reference to an array of sections specifications (as described in
219 "SECTION SPECIFICATIONS") which indicate the desired set of POD
220 sections and subsections to be selected from input. If no section
221 specifications are given, then all sections of the PODs are used.
222 All other arguments should correspond to the names of input files con‐
224 taining POD sections. A file name of "-" or "<&STDIN" will be inter‐
225 peted to mean standard input (which is the default if no filenames are
226 given).
227
229 Pod::Select makes uses a number of internal methods and data fields
230 which clients should not need to see or use. For the sake of avoiding
231 name collisions with client data and methods, these methods and fields
232 are briefly discussed here. Determined hackers may obtain further
233 information about them by reading the Pod::Select source code.
234 Private data fields are stored in the hash-object whose reference is
236 returned by the new() constructor for this class. The names of all pri‐
237 vate methods and data-fields used by Pod::Select begin with a prefix of
238 "_" and match the regular expression "/^_\w+$/".
239
241 Pod::Parser
242
244 Please report bugs using <http://rt.cpan.org>.
245 Brad Appleton <bradapp@enteract.com>
247 Based on code for pod2text written by Tom Christiansen
249 <tchrist@mox.perl.com>
250perl v5.8.8 2001-09-21 Pod::Select(3pm)