1Pod::Usage(3)         User Contributed Perl Documentation        Pod::Usage(3)
2
3
4

NAME

6       Pod::Usage - extracts POD documentation and shows usage information
7

SYNOPSIS

9         use Pod::Usage;
10
11         my $message_text  = "This text precedes the usage message.";
12         my $exit_status   = 2;          ## The exit status to use
13         my $verbose_level = 0;          ## The verbose level to use
14         my $filehandle    = \*STDERR;   ## The filehandle to write to
15
16         pod2usage($message_text);
17
18         pod2usage($exit_status);
19
20         pod2usage( { -message => $message_text ,
21                      -exitval => $exit_status  ,
22                      -verbose => $verbose_level,
23                      -output  => $filehandle } );
24
25         pod2usage(   -msg     => $message_text ,
26                      -exitval => $exit_status  ,
27                      -verbose => $verbose_level,
28                      -output  => $filehandle );
29
30         pod2usage(   -verbose => 2,
31                      -noperldoc => 1  );
32
33         pod2usage(   -verbose => 2,
34                      -perlcmd => $path_to_perl,
35                      -perldoc => $path_to_perldoc,
36                      -perldocopt => $perldoc_options );
37

ARGUMENTS

39       pod2usage should be given either a single argument, or a list of
40       arguments corresponding to an associative array (a "hash"). When a
41       single argument is given, it should correspond to exactly one of the
42       following:
43
44       •   A string containing the text of a message to print before printing
45           the usage message
46
47       •   A numeric value corresponding to the desired exit status
48
49       •   A reference to a hash
50
51       If more than one argument is given then the entire argument list is
52       assumed to be a hash.  If a hash is supplied (either as a reference or
53       as a list) it should contain one or more elements with the following
54       keys:
55
56       "-message" string
57       "-msg" string
58           The text of a message to print immediately prior to printing the
59           program's usage message.
60
61       "-exitval" value
62           The desired exit status to pass to the exit() function.  This
63           should be an integer, or else the string "NOEXIT" to indicate that
64           control should simply be returned without terminating the invoking
65           process.
66
67       "-verbose" value
68           The desired level of "verboseness" to use when printing the usage
69           message.  If the value is 0, then only the "SYNOPSIS" and/or
70           "USAGE" sections of the pod documentation are printed. If the value
71           is 1, then the "SYNOPSIS" and/or "USAGE" sections, along with any
72           section entitled "OPTIONS", "ARGUMENTS", or "OPTIONS AND ARGUMENTS"
73           is printed. If the corresponding value is 2 or more then the entire
74           manpage is printed, using perldoc if available; otherwise Pod::Text
75           is used for the formatting. For better readability, the all-capital
76           headings are downcased, e.g. "SYNOPSIS" => "Synopsis".
77
78           The special verbosity level 99 requires to also specify the
79           -sections parameter; then these sections are extracted and printed.
80
81       "-sections" spec
82           There are two ways to specify the selection. Either a string
83           (scalar) representing a selection regexp for sections to be printed
84           when -verbose is set to 99, e.g.
85
86             "NAME|SYNOPSIS|DESCRIPTION|VERSION"
87
88           With the above regexp all content following (and including) any of
89           the given "=head1" headings will be shown. It is possible to
90           restrict the output to particular subsections only, e.g.:
91
92             "DESCRIPTION/Algorithm"
93
94           This will output only the "=head2 Algorithm" heading and content
95           within the "=head1 DESCRIPTION" section. The regexp binding is
96           stronger than the section separator, such that e.g.:
97
98             "DESCRIPTION|OPTIONS|ENVIRONMENT/Caveats"
99
100           will print any "=head2 Caveats" section (only) within any of the
101           three "=head1" sections.
102
103           Alternatively, an array reference of section specifications can be
104           used:
105
106             pod2usage(-verbose => 99, -sections => [
107               qw(DESCRIPTION DESCRIPTION/Introduction) ] );
108
109           This will print only the content of "=head1 DESCRIPTION" and the
110           "=head2 Introduction" sections, but no other "=head2", and no other
111           "=head1" either.
112
113       "-output" handle
114           A reference to a filehandle, or the pathname of a file to which the
115           usage message should be written. The default is "\*STDERR" unless
116           the exit value is less than 2 (in which case the default is
117           "\*STDOUT").
118
119       "-input" handle
120           A reference to a filehandle, or the pathname of a file from which
121           the invoking script's pod documentation should be read.  It
122           defaults to the file indicated by $0 ($PROGRAM_NAME for users of
123           English.pm).
124
125           If you are calling pod2usage() from a module and want to display
126           that module's POD, you can use this:
127
128             use Pod::Find qw(pod_where);
129             pod2usage( -input => pod_where({-inc => 1}, __PACKAGE__) );
130
131       "-pathlist" string
132           A list of directory paths. If the input file does not exist, then
133           it will be searched for in the given directory list (in the order
134           the directories appear in the list). It defaults to the list of
135           directories implied by $ENV{PATH}. The list may be specified either
136           by a reference to an array, or by a string of directory paths which
137           use the same path separator as $ENV{PATH} on your system (e.g., ":"
138           for Unix, ";" for MSWin32 and DOS).
139
140       "-noperldoc"
141           By default, Pod::Usage will call perldoc when -verbose >= 2 is
142           specified.  This does not work well e.g. if the script was packed
143           with PAR. This option suppresses the external call to perldoc and
144           uses the simple text formatter (Pod::Text) to output the POD.
145
146       "-perlcmd"
147           By default, Pod::Usage will call perldoc when -verbose >= 2 is
148           specified. In case of special or unusual Perl installations, this
149           option may be used to supply the path to a perl executable which
150           should run perldoc.
151
152       "-perldoc" path-to-perldoc
153           By default, Pod::Usage will call perldoc when -verbose >= 2 is
154           specified. In case perldoc is not installed where the perl
155           interpreter thinks it is (see Config), the -perldoc option may be
156           used to supply the correct path to perldoc.
157
158       "-perldocopt" string
159           By default, Pod::Usage will call perldoc when -verbose >= 2 is
160           specified.  This option may be used to supply options to perldoc.
161           The string may contain several, space-separated options.
162
163   Formatting base class
164       The default text formatter is Pod::Text. The base class for Pod::Usage
165       can be defined by pre-setting $Pod::Usage::Formatter before loading
166       Pod::Usage, e.g.:
167
168           BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
169           use Pod::Usage qw(pod2usage);
170
171       Pod::Usage uses Pod::Simple's _handle_element_end() method to implement
172       the section selection, and in case of verbosity < 2 it down-cases the
173       all-caps headings to first capital letter and rest lowercase, and adds
174       a colon/newline at the end of the headings, for better readability.
175       Same for verbosity = 99.
176
177   Pass-through options
178       The following options are passed through to the underlying text
179       formatter.  See the manual pages of these modules for more information.
180
181         alt code indent loose margin quotes sentence stderr utf8 width
182

DESCRIPTION

184       pod2usage will print a usage message for the invoking script (using its
185       embedded pod documentation) and then exit the script with the desired
186       exit status. The usage message printed may have any one of three levels
187       of "verboseness": If the verbose level is 0, then only a synopsis is
188       printed. If the verbose level is 1, then the synopsis is printed along
189       with a description (if present) of the command line options and
190       arguments. If the verbose level is 2, then the entire manual page is
191       printed.
192
193       Unless they are explicitly specified, the default values for the exit
194       status, verbose level, and output stream to use are determined as
195       follows:
196
197       •   If neither the exit status nor the verbose level is specified, then
198           the default is to use an exit status of 2 with a verbose level of
199           0.
200
201       •   If an exit status is specified but the verbose level is not, then
202           the verbose level will default to 1 if the exit status is less than
203           2 and will default to 0 otherwise.
204
205       •   If an exit status is not specified but verbose level is given, then
206           the exit status will default to 2 if the verbose level is 0 and
207           will default to 1 otherwise.
208
209       •   If the exit status used is less than 2, then output is printed on
210           "STDOUT".  Otherwise output is printed on "STDERR".
211
212       Although the above may seem a bit confusing at first, it generally does
213       "the right thing" in most situations.  This determination of the
214       default values to use is based upon the following typical Unix
215       conventions:
216
217       •   An exit status of 0 implies "success". For example, diff(1) exits
218           with a status of 0 if the two files have the same contents.
219
220       •   An exit status of 1 implies possibly abnormal, but non-defective,
221           program termination.  For example, grep(1) exits with a status of 1
222           if it did not find a matching line for the given regular
223           expression.
224
225       •   An exit status of 2 or more implies a fatal error. For example,
226           ls(1) exits with a status of 2 if you specify an illegal (unknown)
227           option on the command line.
228
229       •   Usage messages issued as a result of bad command-line syntax should
230           go to "STDERR".  However, usage messages issued due to an explicit
231           request to print usage (like specifying -help on the command line)
232           should go to "STDOUT", just in case the user wants to pipe the
233           output to a pager (such as more(1)).
234
235       •   If program usage has been explicitly requested by the user, it is
236           often desirable to exit with a status of 1 (as opposed to 0) after
237           issuing the user-requested usage message.  It is also desirable to
238           give a more verbose description of program usage in this case.
239
240       pod2usage does not force the above conventions upon you, but it will
241       use them by default if you don't expressly tell it to do otherwise.
242       The ability of pod2usage() to accept a single number or a string makes
243       it convenient to use as an innocent looking error message handling
244       function:
245
246           use strict;
247           use Pod::Usage;
248           use Getopt::Long;
249
250           ## Parse options
251           my %opt;
252           GetOptions(\%opt, "help|?", "man", "flag1")  ||  pod2usage(2);
253           pod2usage(1)  if ($opt{help});
254           pod2usage(-exitval => 0, -verbose => 2)  if ($opt{man});
255
256           ## Check for too many filenames
257           pod2usage("$0: Too many files given.\n")  if (@ARGV > 1);
258
259       Some user's however may feel that the above "economy of expression" is
260       not particularly readable nor consistent and may instead choose to do
261       something more like the following:
262
263           use strict;
264           use Pod::Usage qw(pod2usage);
265           use Getopt::Long qw(GetOptions);
266
267           ## Parse options
268           my %opt;
269           GetOptions(\%opt, "help|?", "man", "flag1")  ||
270             pod2usage(-verbose => 0);
271
272           pod2usage(-verbose => 1)  if ($opt{help});
273           pod2usage(-verbose => 2)  if ($opt{man});
274
275           ## Check for too many filenames
276           pod2usage(-verbose => 2, -message => "$0: Too many files given.\n")
277             if (@ARGV > 1);
278
279       As with all things in Perl, there's more than one way to do it, and
280       pod2usage() adheres to this philosophy.  If you are interested in
281       seeing a number of different ways to invoke pod2usage (although by no
282       means exhaustive), please refer to "EXAMPLES".
283
284   Scripts
285       The Pod::Usage distribution comes with a script pod2usage which offers
286       a command line interface to the functionality of Pod::Usage. See
287       pod2usage.
288

EXAMPLES

290       Each of the following invocations of "pod2usage()" will print just the
291       "SYNOPSIS" section to "STDERR" and will exit with a status of 2:
292
293           pod2usage();
294
295           pod2usage(2);
296
297           pod2usage(-verbose => 0);
298
299           pod2usage(-exitval => 2);
300
301           pod2usage({-exitval => 2, -output => \*STDERR});
302
303           pod2usage({-verbose => 0, -output  => \*STDERR});
304
305           pod2usage(-exitval => 2, -verbose => 0);
306
307           pod2usage(-exitval => 2, -verbose => 0, -output => \*STDERR);
308
309       Each of the following invocations of "pod2usage()" will print a message
310       of "Syntax error." (followed by a newline) to "STDERR", immediately
311       followed by just the "SYNOPSIS" section (also printed to "STDERR") and
312       will exit with a status of 2:
313
314           pod2usage("Syntax error.");
315
316           pod2usage(-message => "Syntax error.", -verbose => 0);
317
318           pod2usage(-msg  => "Syntax error.", -exitval => 2);
319
320           pod2usage({-msg => "Syntax error.", -exitval => 2, -output => \*STDERR});
321
322           pod2usage({-msg => "Syntax error.", -verbose => 0, -output => \*STDERR});
323
324           pod2usage(-msg  => "Syntax error.", -exitval => 2, -verbose => 0);
325
326           pod2usage(-message => "Syntax error.",
327                     -exitval => 2,
328                     -verbose => 0,
329                     -output  => \*STDERR);
330
331       Each of the following invocations of "pod2usage()" will print the
332       "SYNOPSIS" section and any "OPTIONS" and/or "ARGUMENTS" sections to
333       "STDOUT" and will exit with a status of 1:
334
335           pod2usage(1);
336
337           pod2usage(-verbose => 1);
338
339           pod2usage(-exitval => 1);
340
341           pod2usage({-exitval => 1, -output => \*STDOUT});
342
343           pod2usage({-verbose => 1, -output => \*STDOUT});
344
345           pod2usage(-exitval => 1, -verbose => 1);
346
347           pod2usage(-exitval => 1, -verbose => 1, -output => \*STDOUT});
348
349       Each of the following invocations of "pod2usage()" will print the
350       entire manual page to "STDOUT" and will exit with a status of 1:
351
352           pod2usage(-verbose  => 2);
353
354           pod2usage({-verbose => 2, -output => \*STDOUT});
355
356           pod2usage(-exitval  => 1, -verbose => 2);
357
358           pod2usage({-exitval => 1, -verbose => 2, -output => \*STDOUT});
359
360   Recommended Use
361       Most scripts should print some type of usage message to "STDERR" when a
362       command line syntax error is detected. They should also provide an
363       option (usually "-H" or "-help") to print a (possibly more verbose)
364       usage message to "STDOUT". Some scripts may even wish to go so far as
365       to provide a means of printing their complete documentation to "STDOUT"
366       (perhaps by allowing a "-man" option). The following complete example
367       uses Pod::Usage in combination with Getopt::Long to do all of these
368       things:
369
370           use strict;
371           use Getopt::Long qw(GetOptions);
372           use Pod::Usage qw(pod2usage);
373
374           my $man = 0;
375           my $help = 0;
376           ## Parse options and print usage if there is a syntax error,
377           ## or if usage was explicitly requested.
378           GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
379           pod2usage(1) if $help;
380           pod2usage(-verbose => 2) if $man;
381
382           ## If no arguments were given, then allow STDIN to be used only
383           ## if it's not connected to a terminal (otherwise print usage)
384           pod2usage("$0: No files given.")  if ((@ARGV == 0) && (-t STDIN));
385
386           __END__
387
388           =head1 NAME
389
390           sample - Using GetOpt::Long and Pod::Usage
391
392           =head1 SYNOPSIS
393
394           sample [options] [file ...]
395
396            Options:
397              -help            brief help message
398              -man             full documentation
399
400           =head1 OPTIONS
401
402           =over 4
403
404           =item B<-help>
405
406           Print a brief help message and exits.
407
408           =item B<-man>
409
410           Prints the manual page and exits.
411
412           =back
413
414           =head1 DESCRIPTION
415
416           B<This program> will read the given input file(s) and do something
417           useful with the contents thereof.
418
419           =cut
420

CAVEATS

422       By default, pod2usage() will use $0 as the path to the pod input file.
423       Unfortunately, not all systems on which Perl runs will set $0 properly
424       (although if $0 is not found, pod2usage() will search $ENV{PATH} or
425       else the list specified by the "-pathlist" option).  If this is the
426       case for your system, you may need to explicitly specify the path to
427       the pod docs for the invoking script using something similar to the
428       following:
429
430           pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs");
431
432       In the pathological case that a script is called via a relative path
433       and the script itself changes the current working directory (see
434       "chdir" in perlfunc) before calling pod2usage, Pod::Usage will fail
435       even on robust platforms. Don't do that. Or use FindBin to locate the
436       script:
437
438           use FindBin;
439           pod2usage(-input => $FindBin::Bin . "/" . $FindBin::Script);
440

SUPPORT

442       This module is managed in a GitHub repository,
443       <https://github.com/Dual-Life/Pod-Usage> Feel free to fork and
444       contribute, or to clone and send patches!
445
446       Please use <https://github.com/Dual-Life/Pod-Usage/issues/new> to file
447       a bug report.  The previous ticketing system,
448       <https://rt.cpan.org/Dist/Display.html?Queue=Pod-Usage>, is deprecated
449       for this package.
450
451       More general questions or discussion about POD should be sent to the
452       "pod-people@perl.org" mail list. Send an empty email to
453       "pod-people-subscribe@perl.org" to subscribe.
454

AUTHOR

456       Marek Rouchal <marekr@cpan.org>
457
458       Nicolas R <nicolas@atoomic.org>
459
460       Brad Appleton <bradapp@enteract.com>
461
462       Based on code for Pod::Text::pod2text() written by Tom Christiansen
463       <tchrist@mox.perl.com>
464

LICENSE

466       Pod::Usage (the distribution) is licensed under the same terms as Perl.
467

ACKNOWLEDGMENTS

469       Nicolas R (ATOOMIC) for setting up the Github repo and modernizing this
470       package.
471
472       rjbs for refactoring Pod::Usage to not use Pod::Parser any more.
473
474       Steven McDougall <swmcd@world.std.com> for his help and patience with
475       re-writing this manpage.
476

SEE ALSO

478       Pod::Usage is now a standalone distribution, depending on Pod::Text
479       which in turn depends on Pod::Simple.
480
481       Pod::Perldoc, Getopt::Long, Pod::Find, FindBin, Pod::Text,
482       Pod::Text::Termcap, Pod::Simple
483
484
485
486perl v5.34.0                      2022-01-21                     Pod::Usage(3)
Impressum