1NAME
2 Pod::Usage - extracts POD documentation and shows usage information
3
4SYNOPSIS
5 use Pod::Usage;
6
7 my $message_text = "This text precedes the usage message.";
8 my $exit_status = 2; ## The exit status to use
9 my $verbose_level = 0; ## The verbose level to use
10 my $filehandle = \*STDERR; ## The filehandle to write to
11
12 pod2usage($message_text);
13
14 pod2usage($exit_status);
15
16 pod2usage( { -message => $message_text ,
17 -exitval => $exit_status ,
18 -verbose => $verbose_level,
19 -output => $filehandle } );
20
21 pod2usage( -msg => $message_text ,
22 -exitval => $exit_status ,
23 -verbose => $verbose_level,
24 -output => $filehandle );
25
26 pod2usage( -verbose => 2,
27 -noperldoc => 1 );
28
29 pod2usage( -verbose => 2,
30 -perlcmd => $path_to_perl,
31 -perldoc => $path_to_perldoc,
32 -perldocopt => $perldoc_options );
33
34ARGUMENTS
35 pod2usage should be given either a single argument, or a list of
36 arguments corresponding to an associative array (a "hash"). When a
37 single argument is given, it should correspond to exactly one of the
38 following:
39
40 * A string containing the text of a message to print *before* printing
41 the usage message
42
43 * A numeric value corresponding to the desired exit status
44
45 * A reference to a hash
46
47 If more than one argument is given then the entire argument list is
48 assumed to be a hash. If a hash is supplied (either as a reference or as
49 a list) it should contain one or more elements with the following keys:
50
51 "-message" *string*
52 "-msg" *string*
53 The text of a message to print immediately prior to printing the
54 program's usage message.
55
56 "-exitval" *value*
57 The desired exit status to pass to the exit() function. This should
58 be an integer, or else the string "NOEXIT" to indicate that control
59 should simply be returned without terminating the invoking process.
60
61 "-verbose" *value*
62 The desired level of "verboseness" to use when printing the usage
63 message. If the value is 0, then only the "SYNOPSIS" and/or "USAGE"
64 sections of the pod documentation are printed. If the value is 1,
65 then the "SYNOPSIS" and/or "USAGE" sections, along with any section
66 entitled "OPTIONS", "ARGUMENTS", or "OPTIONS AND ARGUMENTS" is
67 printed. If the corresponding value is 2 or more then the entire
68 manpage is printed, using perldoc if available; otherwise Pod::Text
69 is used for the formatting. For better readability, the all-capital
70 headings are downcased, e.g. "SYNOPSIS" => "Synopsis".
71
72 The special verbosity level 99 requires to also specify the
73 -sections parameter; then these sections are extracted and printed.
74
75 "-sections" *spec*
76 There are two ways to specify the selection. Either a string
77 (scalar) representing a selection regexp for sections to be printed
78 when -verbose is set to 99, e.g.
79
80 "NAME|SYNOPSIS|DESCRIPTION|VERSION"
81
82 With the above regexp all content following (and including) any of
83 the given "=head1" headings will be shown. It is possible to
84 restrict the output to particular subsections only, e.g.:
85
86 "DESCRIPTION/Algorithm"
87
88 This will output only the "=head2 Algorithm" heading and content
89 within the "=head1 DESCRIPTION" section. The regexp binding is
90 stronger than the section separator, such that e.g.:
91
92 "DESCRIPTION|OPTIONS|ENVIRONMENT/Caveats"
93
94 will print any "=head2 Caveats" section (only) within any of the
95 three "=head1" sections.
96
97 Alternatively, an array reference of section specifications can be
98 used:
99
100 pod2usage(-verbose => 99, -sections => [
101 qw(DESCRIPTION DESCRIPTION/Introduction) ] );
102
103 This will print only the content of "=head1 DESCRIPTION" and the
104 "=head2 Introduction" sections, but no other "=head2", and no other
105 "=head1" either.
106
107 "-output" *handle*
108 A reference to a filehandle, or the pathname of a file to which the
109 usage message should be written. The default is "\*STDERR" unless
110 the exit value is less than 2 (in which case the default is
111 "\*STDOUT").
112
113 "-input" *handle*
114 A reference to a filehandle, or the pathname of a file from which
115 the invoking script's pod documentation should be read. It defaults
116 to the file indicated by $0 ($PROGRAM_NAME for users of English.pm).
117
118 If you are calling pod2usage() from a module and want to display
119 that module's POD, you can use this:
120
121 use Pod::Find qw(pod_where);
122 pod2usage( -input => pod_where({-inc => 1}, __PACKAGE__) );
123
124 "-pathlist" *string*
125 A list of directory paths. If the input file does not exist, then it
126 will be searched for in the given directory list (in the order the
127 directories appear in the list). It defaults to the list of
128 directories implied by $ENV{PATH}. The list may be specified either
129 by a reference to an array, or by a string of directory paths which
130 use the same path separator as $ENV{PATH} on your system (e.g., ":"
131 for Unix, ";" for MSWin32 and DOS).
132
133 "-noperldoc"
134 By default, Pod::Usage will call perldoc when -verbose >= 2 is
135 specified. This does not work well e.g. if the script was packed
136 with PAR. This option suppresses the external call to perldoc and
137 uses the simple text formatter (Pod::Text) to output the POD.
138
139 "-perlcmd"
140 By default, Pod::Usage will call perldoc when -verbose >= 2 is
141 specified. In case of special or unusual Perl installations, this
142 option may be used to supply the path to a perl executable which
143 should run perldoc.
144
145 "-perldoc" *path-to-perldoc*
146 By default, Pod::Usage will call perldoc when -verbose >= 2 is
147 specified. In case perldoc is not installed where the perl
148 interpreter thinks it is (see Config), the -perldoc option may be
149 used to supply the correct path to perldoc.
150
151 "-perldocopt" *string*
152 By default, Pod::Usage will call perldoc when -verbose >= 2 is
153 specified. This option may be used to supply options to perldoc. The
154 string may contain several, space-separated options.
155
156 Formatting base class
157 The default text formatter is Pod::Text. The base class for Pod::Usage
158 can be defined by pre-setting $Pod::Usage::Formatter *before* loading
159 Pod::Usage, e.g.:
160
161 BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
162 use Pod::Usage qw(pod2usage);
163
164 Pod::Usage uses Pod::Simple's _handle_element_end() method to implement
165 the section selection, and in case of verbosity < 2 it down-cases the
166 all-caps headings to first capital letter and rest lowercase, and adds a
167 colon/newline at the end of the headings, for better readability. Same
168 for verbosity = 99.
169
170 Pass-through options
171 The following options are passed through to the underlying text
172 formatter. See the manual pages of these modules for more information.
173
174 alt code indent loose margin quotes sentence stderr utf8 width
175
176DESCRIPTION
177 pod2usage will print a usage message for the invoking script (using its
178 embedded pod documentation) and then exit the script with the desired
179 exit status. The usage message printed may have any one of three levels
180 of "verboseness": If the verbose level is 0, then only a synopsis is
181 printed. If the verbose level is 1, then the synopsis is printed along
182 with a description (if present) of the command line options and
183 arguments. If the verbose level is 2, then the entire manual page is
184 printed.
185
186 Unless they are explicitly specified, the default values for the exit
187 status, verbose level, and output stream to use are determined as
188 follows:
189
190 * If neither the exit status nor the verbose level is specified, then
191 the default is to use an exit status of 2 with a verbose level of 0.
192
193 * If an exit status *is* specified but the verbose level is *not*,
194 then the verbose level will default to 1 if the exit status is less
195 than 2 and will default to 0 otherwise.
196
197 * If an exit status is *not* specified but verbose level *is* given,
198 then the exit status will default to 2 if the verbose level is 0 and
199 will default to 1 otherwise.
200
201 * If the exit status used is less than 2, then output is printed on
202 "STDOUT". Otherwise output is printed on "STDERR".
203
204 Although the above may seem a bit confusing at first, it generally does
205 "the right thing" in most situations. This determination of the default
206 values to use is based upon the following typical Unix conventions:
207
208 * An exit status of 0 implies "success". For example, diff(1) exits
209 with a status of 0 if the two files have the same contents.
210
211 * An exit status of 1 implies possibly abnormal, but non-defective,
212 program termination. For example, grep(1) exits with a status of 1
213 if it did *not* find a matching line for the given regular
214 expression.
215
216 * An exit status of 2 or more implies a fatal error. For example,
217 ls(1) exits with a status of 2 if you specify an illegal (unknown)
218 option on the command line.
219
220 * Usage messages issued as a result of bad command-line syntax should
221 go to "STDERR". However, usage messages issued due to an explicit
222 request to print usage (like specifying -help on the command line)
223 should go to "STDOUT", just in case the user wants to pipe the
224 output to a pager (such as more(1)).
225
226 * If program usage has been explicitly requested by the user, it is
227 often desirable to exit with a status of 1 (as opposed to 0) after
228 issuing the user-requested usage message. It is also desirable to
229 give a more verbose description of program usage in this case.
230
231 pod2usage does not force the above conventions upon you, but it will use
232 them by default if you don't expressly tell it to do otherwise. The
233 ability of pod2usage() to accept a single number or a string makes it
234 convenient to use as an innocent looking error message handling
235 function:
236
237 use strict;
238 use Pod::Usage;
239 use Getopt::Long;
240
241 ## Parse options
242 my %opt;
243 GetOptions(\%opt, "help|?", "man", "flag1") || pod2usage(2);
244 pod2usage(1) if ($opt{help});
245 pod2usage(-exitval => 0, -verbose => 2) if ($opt{man});
246
247 ## Check for too many filenames
248 pod2usage("$0: Too many files given.\n") if (@ARGV > 1);
249
250 Some user's however may feel that the above "economy of expression" is
251 not particularly readable nor consistent and may instead choose to do
252 something more like the following:
253
254 use strict;
255 use Pod::Usage qw(pod2usage);
256 use Getopt::Long qw(GetOptions);
257
258 ## Parse options
259 my %opt;
260 GetOptions(\%opt, "help|?", "man", "flag1") ||
261 pod2usage(-verbose => 0);
262
263 pod2usage(-verbose => 1) if ($opt{help});
264 pod2usage(-verbose => 2) if ($opt{man});
265
266 ## Check for too many filenames
267 pod2usage(-verbose => 2, -message => "$0: Too many files given.\n")
268 if (@ARGV > 1);
269
270 As with all things in Perl, *there's more than one way to do it*, and
271 pod2usage() adheres to this philosophy. If you are interested in seeing
272 a number of different ways to invoke pod2usage (although by no means
273 exhaustive), please refer to "EXAMPLES".
274
275 Scripts
276 The Pod::Usage distribution comes with a script pod2usage which offers a
277 command line interface to the functionality of Pod::Usage. See
278 pod2usage.
279
280EXAMPLES
281 Each of the following invocations of "pod2usage()" will print just the
282 "SYNOPSIS" section to "STDERR" and will exit with a status of 2:
283
284 pod2usage();
285
286 pod2usage(2);
287
288 pod2usage(-verbose => 0);
289
290 pod2usage(-exitval => 2);
291
292 pod2usage({-exitval => 2, -output => \*STDERR});
293
294 pod2usage({-verbose => 0, -output => \*STDERR});
295
296 pod2usage(-exitval => 2, -verbose => 0);
297
298 pod2usage(-exitval => 2, -verbose => 0, -output => \*STDERR);
299
300 Each of the following invocations of "pod2usage()" will print a message
301 of "Syntax error." (followed by a newline) to "STDERR", immediately
302 followed by just the "SYNOPSIS" section (also printed to "STDERR") and
303 will exit with a status of 2:
304
305 pod2usage("Syntax error.");
306
307 pod2usage(-message => "Syntax error.", -verbose => 0);
308
309 pod2usage(-msg => "Syntax error.", -exitval => 2);
310
311 pod2usage({-msg => "Syntax error.", -exitval => 2, -output => \*STDERR});
312
313 pod2usage({-msg => "Syntax error.", -verbose => 0, -output => \*STDERR});
314
315 pod2usage(-msg => "Syntax error.", -exitval => 2, -verbose => 0);
316
317 pod2usage(-message => "Syntax error.",
318 -exitval => 2,
319 -verbose => 0,
320 -output => \*STDERR);
321
322 Each of the following invocations of "pod2usage()" will print the
323 "SYNOPSIS" section and any "OPTIONS" and/or "ARGUMENTS" sections to
324 "STDOUT" and will exit with a status of 1:
325
326 pod2usage(1);
327
328 pod2usage(-verbose => 1);
329
330 pod2usage(-exitval => 1);
331
332 pod2usage({-exitval => 1, -output => \*STDOUT});
333
334 pod2usage({-verbose => 1, -output => \*STDOUT});
335
336 pod2usage(-exitval => 1, -verbose => 1);
337
338 pod2usage(-exitval => 1, -verbose => 1, -output => \*STDOUT});
339
340 Each of the following invocations of "pod2usage()" will print the entire
341 manual page to "STDOUT" and will exit with a status of 1:
342
343 pod2usage(-verbose => 2);
344
345 pod2usage({-verbose => 2, -output => \*STDOUT});
346
347 pod2usage(-exitval => 1, -verbose => 2);
348
349 pod2usage({-exitval => 1, -verbose => 2, -output => \*STDOUT});
350
351 Recommended Use
352 Most scripts should print some type of usage message to "STDERR" when a
353 command line syntax error is detected. They should also provide an
354 option (usually "-H" or "-help") to print a (possibly more verbose)
355 usage message to "STDOUT". Some scripts may even wish to go so far as to
356 provide a means of printing their complete documentation to "STDOUT"
357 (perhaps by allowing a "-man" option). The following complete example
358 uses Pod::Usage in combination with Getopt::Long to do all of these
359 things:
360
361 use strict;
362 use Getopt::Long qw(GetOptions);
363 use Pod::Usage qw(pod2usage);
364
365 my $man = 0;
366 my $help = 0;
367 ## Parse options and print usage if there is a syntax error,
368 ## or if usage was explicitly requested.
369 GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
370 pod2usage(1) if $help;
371 pod2usage(-verbose => 2) if $man;
372
373 ## If no arguments were given, then allow STDIN to be used only
374 ## if it's not connected to a terminal (otherwise print usage)
375 pod2usage("$0: No files given.") if ((@ARGV == 0) && (-t STDIN));
376
377 __END__
378
379 =head1 NAME
380
381 sample - Using GetOpt::Long and Pod::Usage
382
383 =head1 SYNOPSIS
384
385 sample [options] [file ...]
386
387 Options:
388 -help brief help message
389 -man full documentation
390
391 =head1 OPTIONS
392
393 =over 4
394
395 =item B<-help>
396
397 Print a brief help message and exits.
398
399 =item B<-man>
400
401 Prints the manual page and exits.
402
403 =back
404
405 =head1 DESCRIPTION
406
407 B<This program> will read the given input file(s) and do something
408 useful with the contents thereof.
409
410 =cut
411
412CAVEATS
413 By default, pod2usage() will use $0 as the path to the pod input file.
414 Unfortunately, not all systems on which Perl runs will set $0 properly
415 (although if $0 is not found, pod2usage() will search $ENV{PATH} or else
416 the list specified by the "-pathlist" option). If this is the case for
417 your system, you may need to explicitly specify the path to the pod docs
418 for the invoking script using something similar to the following:
419
420 pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs");
421
422 In the pathological case that a script is called via a relative path
423 *and* the script itself changes the current working directory (see
424 "chdir" in perlfunc) *before* calling pod2usage, Pod::Usage will fail
425 even on robust platforms. Don't do that. Or use FindBin to locate the
426 script:
427
428 use FindBin;
429 pod2usage(-input => $FindBin::Bin . "/" . $FindBin::Script);
430
431SUPPORT
432 This module is managed in a GitHub repository,
433 <https://github.com/Dual-Life/Pod-Usage> Feel free to fork and
434 contribute, or to clone and send patches!
435
436 Please use <https://github.com/Dual-Life/Pod-Usage/issues/new> to file a
437 bug report. The previous ticketing system,
438 <https://rt.cpan.org/Dist/Display.html?Queue=Pod-Usage>, is deprecated
439 for this package.
440
441 More general questions or discussion about POD should be sent to the
442 "pod-people@perl.org" mail list. Send an empty email to
443 "pod-people-subscribe@perl.org" to subscribe.
444
445AUTHOR
446 Marek Rouchal <marekr@cpan.org>
447
448 Nicolas R <nicolas@atoomic.org>
449
450 Brad Appleton <bradapp@enteract.com>
451
452 Based on code for Pod::Text::pod2text() written by Tom Christiansen
453 <tchrist@mox.perl.com>
454
455LICENSE
456 Pod::Usage (the distribution) is licensed under the same terms as Perl.
457
458ACKNOWLEDGMENTS
459 Nicolas R (ATOOMIC) for setting up the Github repo and modernizing this
460 package.
461
462 rjbs for refactoring Pod::Usage to not use Pod::Parser any more.
463
464 Steven McDougall <swmcd@world.std.com> for his help and patience with
465 re-writing this manpage.
466
467SEE ALSO
468 Pod::Usage is now a standalone distribution, depending on Pod::Text
469 which in turn depends on Pod::Simple.
470
471 Pod::Perldoc, Getopt::Long, Pod::Find, FindBin, Pod::Text,
472 Pod::Text::Termcap, Pod::Simple
473
474