1Pod::Select(3) User Contributed Perl Documentation Pod::Select(3)
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 NOTE: This module is considered legacy; modern Perl releases (5.31.1
56 and higher) are going to remove Pod-Parser from core and use
57 Pod::Simple for all things POD.
58 podselect() is a function which will extract specified sections of pod
60 documentation from an input stream. This ability is provided by the
61 Pod::Select module which is a subclass of Pod::Parser. Pod::Select
62 provides a method named select() to specify the set of POD sections to
63 select for processing/printing. podselect() merely creates a
64 Pod::Select object and then invokes the podselect() followed by
65 parse_from_file().
66
68 podselect() and Pod::Select::select() may be given one or more "section
69 specifications" to restrict the text processed to only the desired set
70 of sections and their corresponding subsections. A section
71 specification is a string containing one or more Perl-style regular
72 expressions separated by forward slashes ("/"). If you need to use a
73 forward slash literally within a section title you can escape it with a
74 backslash ("\/").
75 The formal syntax of a section specification is:
77 • head1-title-regex/head2-title-regex/...
79 Any omitted or empty regular expressions will default to ".*". Please
81 note that each regular expression given is implicitly anchored by
82 adding "^" and "$" to the beginning and end. Also, if a given regular
83 expression starts with a "!" character, then the expression is negated
84 (so "!foo" would match anything except "foo").
85 Some example section specifications follow.
87 • Match the "NAME" and "SYNOPSIS" sections and all of their
89 subsections:
90 "NAME|SYNOPSIS"
92 • Match only the "Question" and "Answer" subsections of the
94 "DESCRIPTION" section:
95 "DESCRIPTION/Question|Answer"
97 • Match the "Comments" subsection of all sections:
99 "/Comments"
101 • Match all subsections of "DESCRIPTION" except for "Comments":
103 "DESCRIPTION/!Comments"
105 • Match the "DESCRIPTION" section but do not match any of its
107 subsections:
108 "DESCRIPTION/!.+"
110 • Match all top level sections but none of their subsections:
112 "/!.+"
114
116 The following methods are provided in this module. Each one takes a
117 reference to the object itself as an implicit first parameter.
118
120 ($head1, $head2, $head3, ...) = $parser->curr_headings();
121 $head1 = $parser->curr_headings(1);
122 This method returns a list of the currently active section headings and
124 subheadings in the document being parsed. The list of headings returned
125 corresponds to the most recently parsed paragraph of the input.
126 If an argument is given, it must correspond to the desired section
128 heading number, in which case only the specified section heading is
129 returned. If there is no current section heading at the specified
130 level, then "undef" is returned.
131
133 $parser->select($section_spec1,$section_spec2,...);
134 This method is used to select the particular sections and subsections
136 of POD documentation that are to be printed and/or processed. The
137 existing set of selected sections is replaced with the given set of
138 sections. See add_selection() for adding to the current set of
139 selected sections.
140 Each of the $section_spec arguments should be a section specification
142 as described in "SECTION SPECIFICATIONS". The section specifications
143 are parsed by this method and the resulting regular expressions are
144 stored in the invoking object.
145 If no $section_spec arguments are given, then the existing set of
147 selected sections is cleared out (which means "all" sections will be
148 processed).
149 This method should not normally be overridden by subclasses.
151
153 $parser->add_selection($section_spec1,$section_spec2,...);
154 This method is used to add to the currently selected sections and
156 subsections of POD documentation that are to be printed and/or
157 processed. See <select()> for replacing the currently selected
158 sections.
159 Each of the $section_spec arguments should be a section specification
161 as described in "SECTION SPECIFICATIONS". The section specifications
162 are parsed by this method and the resulting regular expressions are
163 stored in the invoking object.
164 This method should not normally be overridden by subclasses.
166
168 $parser->clear_selections();
169 This method takes no arguments, it has the exact same effect as
171 invoking <select()> with no arguments.
172
174 $boolean = $parser->match_section($heading1,$heading2,...);
175 Returns a value of true if the given section and subsection heading
177 titles match any of the currently selected section specifications in
178 effect from prior calls to select() and add_selection() (or if there
179 are no explicitly selected/deselected sections).
180 The arguments $heading1, $heading2, etc. are the heading titles of the
182 corresponding sections, subsections, etc. to try and match. If
183 $headingN is omitted then it defaults to the current corresponding
184 section heading title in the input.
185 This method should not normally be overridden by subclasses.
187
189 $boolean = $parser->is_selected($paragraph);
190 This method is used to determine if the block of text given in
192 $paragraph falls within the currently selected set of POD sections and
193 subsections to be printed or processed. This method is also responsible
194 for keeping track of the current input section and subsections. It is
195 assumed that $paragraph is the most recently read (but not yet
196 processed) input paragraph.
197 The value returned will be true if the $paragraph and the rest of the
199 text in the same section as $paragraph should be selected (included)
200 for processing; otherwise a false value is returned.
201
203 The following functions are exported by this module. Please note that
204 these are functions (not methods) and therefore "do not" take an
205 implicit first argument.
206
208 podselect(\%options,@filelist);
209 podselect will print the raw (untranslated) POD paragraphs of all POD
211 sections in the given input files specified by @filelist according to
212 the options given in "\%options".
213 If any argument to podselect is a reference to a hash (associative
215 array) then the values with the following keys are processed as
216 follows:
217 -output
219 A string corresponding to the desired output file (or ">&STDOUT" or
220 ">&STDERR"), or a filehandle to write on. The default is to use
221 standard output.
222 -sections
224 A reference to an array of sections specifications (as described in
225 "SECTION SPECIFICATIONS") which indicate the desired set of POD
226 sections and subsections to be selected from input. If no section
227 specifications are given, then all sections of the PODs are used.
228 All other arguments are optional and should correspond to filehandles
230 to read from or the names of input files containing POD sections. A
231 file name of "", "-" or "<&STDIN" will be interpreted to mean standard
232 input (which is the default if no arguments are given).
233
235 Pod::Select makes uses a number of internal methods and data fields
236 which clients should not need to see or use. For the sake of avoiding
237 name collisions with client data and methods, these methods and fields
238 are briefly discussed here. Determined hackers may obtain further
239 information about them by reading the Pod::Select source code.
240 Private data fields are stored in the hash-object whose reference is
242 returned by the new() constructor for this class. The names of all
243 private methods and data-fields used by Pod::Select begin with a prefix
244 of "_" and match the regular expression "/^_\w+$/".
245
247 Pod::Parser
248
250 Please report bugs using <http://rt.cpan.org>.
251 Brad Appleton <bradapp@enteract.com>
253 Based on code for pod2text written by Tom Christiansen
255 <tchrist@mox.perl.com>
256 Pod::Select is part of the Pod::Parser distribution.
258perl v5.36.0 2023-04-24 Pod::Select(3)