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
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 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
85 subsections:
86 "NAME|SYNOPSIS"
88 · Match only the "Question" and "Answer" subsections of the
90 "DESCRIPTION" 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
103 subsections:
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
152 subsections of POD documentation that are to be printed and/or
153 processed. See <select()> for replacing the currently selected
154 sections.
155 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 This method should not normally be overridden by subclasses.
162
164 $parser->clear_selections();
165 This method takes no arguments, it has the exact same effect as
167 invoking <select()> with no arguments.
168
170 $boolean = $parser->match_section($heading1,$heading2,...);
171 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 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 This method should not normally be overridden by subclasses.
183
185 $boolean = $parser->is_selected($paragraph);
186 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 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
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
204 podselect(\%options,@filelist);
205 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 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 -output
215 A string corresponding to the desired output file (or ">&STDOUT" or
216 ">&STDERR"). The default is to use standard output.
217 -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 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
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 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
242 Pod::Parser
243
245 Please report bugs using <http://rt.cpan.org>.
246 Brad Appleton <bradapp@enteract.com>
248 Based on code for pod2text written by Tom Christiansen
250 <tchrist@mox.perl.com>
251perl v5.12.4 2011-06-01 Pod::Select(3pm)