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

NAME

6       Pod::Usage - print a usage message from embedded pod documentation
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" section of
70           the pod documentation is printed. If the value is 1, then the
71           "SYNOPSIS" section, along with any section entitled "OPTIONS",
72           "ARGUMENTS", or "OPTIONS AND ARGUMENTS" is printed. If the
73           corresponding value is 2 or more then the entire manpage is
74           printed, using perldoc if available; otherwise Pod::Text is used
75           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. The -noperldoc option suppresses the external call to
144           perldoc and uses the simple text formatter (Pod::Text) to output
145           the POD.
146
147       "-perlcmd"
148           By default, Pod::Usage will call perldoc when -verbose >= 2 is
149           specified. In case of special or unusual Perl installations, the
150           -perlcmd option may be used to supply the path to a perl executable
151           which should run perldoc.
152
153       "-perldoc" path-to-perldoc
154           By default, Pod::Usage will call perldoc when -verbose >= 2 is
155           specified. In case perldoc is not installed where the perl
156           interpreter thinks it is (see Config), the -perldoc option may be
157           used to supply the correct path to perldoc.
158
159       "-perldocopt" string
160           By default, Pod::Usage will call perldoc when -verbose >= 2 is
161           specified.  The -perldocopt option may be used to supply options to
162           perldoc. The string may contain several, space-separated options.
163
164   Formatting base class
165       The default text formatter is Pod::Text. The base class for Pod::Usage
166       can be defined by pre-setting $Pod::Usage::Formatter before loading
167       Pod::Usage, e.g.:
168
169           BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
170           use Pod::Usage qw(pod2usage);
171
172       Pod::Usage uses Pod::Simple's _handle_element_end() method to implement
173       the section selection, and in case of verbosity < 2 it down-cases the
174       all-caps headings to first capital letter and rest lowercase, and adds
175       a colon/newline at the end of the headings, for better readability.
176       Same for verbosity = 99.
177
178   Pass-through options
179       The following options are passed through to the underlying text
180       formatter.  See the manual pages of these modules for more information.
181
182         alt code indent loose margin quotes sentence stderr utf8 width
183

DESCRIPTION

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

EXAMPLES

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

CAVEATS

423       By default, pod2usage() will use $0 as the path to the pod input file.
424       Unfortunately, not all systems on which Perl runs will set $0 properly
425       (although if $0 isn't found, pod2usage() will search $ENV{PATH} or else
426       the list specified by the "-pathlist" option).  If this is the case for
427       your system, you may need to explicitly specify the path to the pod
428       docs for the invoking script using something similar to the 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

AUTHOR

442       Please report bugs using <http://rt.cpan.org>.
443
444       Marek Rouchal <marekr@cpan.org>
445
446       Brad Appleton <bradapp@enteract.com>
447
448       Based on code for Pod::Text::pod2text() written by Tom Christiansen
449       <tchrist@mox.perl.com>
450

LICENSE

452       Pod::Usage (the distribution) is licensed under the same terms as Perl.
453

ACKNOWLEDGMENTS

455       rjbs for refactoring Pod::Usage to not use Pod::Parser any more.
456
457       Steven McDougall <swmcd@world.std.com> for his help and patience with
458       re-writing this manpage.
459

SEE ALSO

461       Pod::Usage is now a standalone distribution, depending on Pod::Text
462       which in turn depends on Pod::Simple.
463
464       Pod::Perldoc, Getopt::Long, Pod::Find, FindBin, Pod::Text,
465       Pod::Text::Termcap, Pod::Simple
466
467
468
469perl v5.30.1                      2020-03-16                     Pod::Usage(3)
Impressum