1Pod::Select(3)        User Contributed Perl Documentation       Pod::Select(3)
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       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
59       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

SECTION SPECIFICATIONS

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
76       The formal syntax of a section specification is:
77
78head1-title-regex/head2-title-regex/...
79
80       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
86       Some example section specifications follow.
87
88       •   Match the "NAME" and "SYNOPSIS" sections and all of their
89           subsections:
90
91           "NAME|SYNOPSIS"
92
93       •   Match only the "Question" and "Answer" subsections of the
94           "DESCRIPTION" section:
95
96           "DESCRIPTION/Question|Answer"
97
98       •   Match the "Comments" subsection of all sections:
99
100           "/Comments"
101
102       •   Match all subsections of "DESCRIPTION" except for "Comments":
103
104           "DESCRIPTION/!Comments"
105
106       •   Match the "DESCRIPTION" section but do not match any of its
107           subsections:
108
109           "DESCRIPTION/!.+"
110
111       •   Match all top level sections but none of their subsections:
112
113           "/!.+"
114

OBJECT METHODS

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

curr_headings()

120                   ($head1, $head2, $head3, ...) = $parser->curr_headings();
121                   $head1 = $parser->curr_headings(1);
122
123       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
127       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

select()

133                   $parser->select($section_spec1,$section_spec2,...);
134
135       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
141       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
146       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
150       This method should not normally be overridden by subclasses.
151

add_selection()

153                   $parser->add_selection($section_spec1,$section_spec2,...);
154
155       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
160       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
165       This method should not normally be overridden by subclasses.
166

clear_selections()

168                   $parser->clear_selections();
169
170       This method takes no arguments, it has the exact same effect as
171       invoking <select()> with no arguments.
172

match_section()

174                   $boolean = $parser->match_section($heading1,$heading2,...);
175
176       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
181       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
186       This method should not normally be overridden by subclasses.
187

is_selected()

189                   $boolean = $parser->is_selected($paragraph);
190
191       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
198       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

EXPORTED FUNCTIONS

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

podselect()

208                   podselect(\%options,@filelist);
209
210       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
214       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
218       -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
223       -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
229       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

PRIVATE METHODS AND DATA

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
241       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

SEE ALSO

247       Pod::Parser
248

AUTHOR

250       Please report bugs using <http://rt.cpan.org>.
251
252       Brad Appleton <bradapp@enteract.com>
253
254       Based on code for pod2text written by Tom Christiansen
255       <tchrist@mox.perl.com>
256
257       Pod::Select is part of the Pod::Parser distribution.
258
259
260
261perl v5.34.1                      2022-05-23                    Pod::Select(3)
Impressum