1Pod::Usage(3) User Contributed Perl Documentation Pod::Usage(3)
2
6 Pod::Usage - extracts POD documentation and shows usage information
7
9 use Pod::Usage;
10 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 pod2usage($message_text);
17 pod2usage($exit_status);
19 pod2usage( { -message => $message_text ,
21 -exitval => $exit_status ,
22 -verbose => $verbose_level,
23 -output => $filehandle } );
24 pod2usage( -msg => $message_text ,
26 -exitval => $exit_status ,
27 -verbose => $verbose_level,
28 -output => $filehandle );
29 pod2usage( -verbose => 2,
31 -noperldoc => 1 );
32 pod2usage( -verbose => 2,
34 -perlcmd => $path_to_perl,
35 -perldoc => $path_to_perldoc,
36 -perldocopt => $perldoc_options );
37
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 • A string containing the text of a message to print before printing
45 the usage message
46 • A numeric value corresponding to the desired exit status
48 • A reference to a hash
50 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 "-message" string
57 "-msg" string
58 The text of a message to print immediately prior to printing the
59 program's usage message.
60 "-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 "-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 The special verbosity level 99 requires to also specify the
79 -sections parameter; then these sections are extracted and printed.
80 "-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 "NAME|SYNOPSIS|DESCRIPTION|VERSION"
87 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 "DESCRIPTION/Algorithm"
93 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 "DESCRIPTION|OPTIONS|ENVIRONMENT/Caveats"
99 will print any "=head2 Caveats" section (only) within any of the
101 three "=head1" sections.
102 Alternatively, an array reference of section specifications can be
104 used:
105 pod2usage(-verbose => 99, -sections => [
107 qw(DESCRIPTION DESCRIPTION/Introduction) ] );
108 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 "-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 "-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 If you are calling pod2usage() from a module and want to display
126 that module's POD, you can use this:
127 use Pod::Find qw(pod_where);
129 pod2usage( -input => pod_where({-inc => 1}, __PACKAGE__) );
130 "-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 "-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 "-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 "-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 "-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 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 BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
169 use Pod::Usage qw(pod2usage);
170 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 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 alt code indent loose margin quotes sentence stderr utf8 width
182
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 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 • 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 • 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 • 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 • If the exit status used is less than 2, then output is printed on
210 "STDOUT". Otherwise output is printed on "STDERR".
211 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 • 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 • 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 • 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 • 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 • 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 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 use strict;
247 use Pod::Usage;
248 use Getopt::Long;
249 ## 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 ## Check for too many filenames
257 pod2usage("$0: Too many files given.\n") if (@ARGV > 1);
258 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 use strict;
264 use Pod::Usage qw(pod2usage);
265 use Getopt::Long qw(GetOptions);
266 ## Parse options
268 my %opt;
269 GetOptions(\%opt, "help|?", "man", "flag1") ||
270 pod2usage(-verbose => 0);
271 pod2usage(-verbose => 1) if ($opt{help});
273 pod2usage(-verbose => 2) if ($opt{man});
274 ## Check for too many filenames
276 pod2usage(-verbose => 2, -message => "$0: Too many files given.\n")
277 if (@ARGV > 1);
278 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 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
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 pod2usage();
294 pod2usage(2);
296 pod2usage(-verbose => 0);
298 pod2usage(-exitval => 2);
300 pod2usage({-exitval => 2, -output => \*STDERR});
302 pod2usage({-verbose => 0, -output => \*STDERR});
304 pod2usage(-exitval => 2, -verbose => 0);
306 pod2usage(-exitval => 2, -verbose => 0, -output => \*STDERR);
308 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 pod2usage("Syntax error.");
315 pod2usage(-message => "Syntax error.", -verbose => 0);
317 pod2usage(-msg => "Syntax error.", -exitval => 2);
319 pod2usage({-msg => "Syntax error.", -exitval => 2, -output => \*STDERR});
321 pod2usage({-msg => "Syntax error.", -verbose => 0, -output => \*STDERR});
323 pod2usage(-msg => "Syntax error.", -exitval => 2, -verbose => 0);
325 pod2usage(-message => "Syntax error.",
327 -exitval => 2,
328 -verbose => 0,
329 -output => \*STDERR);
330 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 pod2usage(1);
336 pod2usage(-verbose => 1);
338 pod2usage(-exitval => 1);
340 pod2usage({-exitval => 1, -output => \*STDOUT});
342 pod2usage({-verbose => 1, -output => \*STDOUT});
344 pod2usage(-exitval => 1, -verbose => 1);
346 pod2usage(-exitval => 1, -verbose => 1, -output => \*STDOUT});
348 Each of the following invocations of pod2usage() will print the entire
350 manual page to "STDOUT" and will exit with a status of 1:
351 pod2usage(-verbose => 2);
353 pod2usage({-verbose => 2, -output => \*STDOUT});
355 pod2usage(-exitval => 1, -verbose => 2);
357 pod2usage({-exitval => 1, -verbose => 2, -output => \*STDOUT});
359 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 use strict;
371 use Getopt::Long qw(GetOptions);
372 use Pod::Usage qw(pod2usage);
373 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 ## 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 __END__
387 =head1 NAME
389 sample - Using GetOpt::Long and Pod::Usage
391 =head1 SYNOPSIS
393 sample [options] [file ...]
395 Options:
397 -help brief help message
398 -man full documentation
399 =head1 OPTIONS
401 =over 4
403 =item B<-help>
405 Print a brief help message and exits.
407 =item B<-man>
409 Prints the manual page and exits.
411 =back
413 =head1 DESCRIPTION
415 B<This program> will read the given input file(s) and do something
417 useful with the contents thereof.
418 =cut
420
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 pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs");
431 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 use FindBin;
439 pod2usage(-input => $FindBin::Bin . "/" . $FindBin::Script);
440
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 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 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
456 Marek Rouchal <marekr@cpan.org>
457 Nicolas R <nicolas@atoomic.org>
459 Brad Appleton <bradapp@enteract.com>
461 Based on code for Pod::Text::pod2text() written by Tom Christiansen
463 <tchrist@mox.perl.com>
464
466 Pod::Usage (the distribution) is licensed under the same terms as Perl.
467
469 Nicolas R (ATOOMIC) for setting up the Github repo and modernizing this
470 package.
471 rjbs for refactoring Pod::Usage to not use Pod::Parser any more.
473 Steven McDougall <swmcd@world.std.com> for his help and patience with
475 re-writing this manpage.
476
478 Pod::Usage is now a standalone distribution, depending on Pod::Text
479 which in turn depends on Pod::Simple.
480 Pod::Perldoc, Getopt::Long, Pod::Find, FindBin, Pod::Text,
482 Pod::Text::Termcap, Pod::Simple
483perl v5.36.0 2023-01-20 Pod::Usage(3)