1Pod::Usage(3) User Contributed Perl Documentation Pod::Usage(3)
2
6 Pod::Usage - print a usage message from embedded pod documentation
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" 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 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. The -noperldoc option suppresses the external call to
144 perldoc and uses the simple text formatter (Pod::Text) to output
145 the POD.
146 "-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 "-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 "-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 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 BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
170 use Pod::Usage qw(pod2usage);
171 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 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 alt code indent loose margin quotes sentence stderr utf8 width
183
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 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 · 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 · 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 · 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 · If the exit status used is less than 2, then output is printed on
211 "STDOUT". Otherwise output is printed on "STDERR".
212 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 · 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 · 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 · 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 · 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 · 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 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 use strict;
248 use Pod::Usage;
249 use Getopt::Long;
250 ## 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 ## Check for too many filenames
258 pod2usage("$0: Too many files given.\n") if (@ARGV > 1);
259 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 use strict;
265 use Pod::Usage qw(pod2usage);
266 use Getopt::Long qw(GetOptions);
267 ## Parse options
269 my %opt;
270 GetOptions(\%opt, "help|?", "man", "flag1") ||
271 pod2usage(-verbose => 0);
272 pod2usage(-verbose => 1) if ($opt{help});
274 pod2usage(-verbose => 2) if ($opt{man});
275 ## Check for too many filenames
277 pod2usage(-verbose => 2, -message => "$0: Too many files given.\n")
278 if (@ARGV > 1);
279 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 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
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 pod2usage();
295 pod2usage(2);
297 pod2usage(-verbose => 0);
299 pod2usage(-exitval => 2);
301 pod2usage({-exitval => 2, -output => \*STDERR});
303 pod2usage({-verbose => 0, -output => \*STDERR});
305 pod2usage(-exitval => 2, -verbose => 0);
307 pod2usage(-exitval => 2, -verbose => 0, -output => \*STDERR);
309 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 pod2usage("Syntax error.");
316 pod2usage(-message => "Syntax error.", -verbose => 0);
318 pod2usage(-msg => "Syntax error.", -exitval => 2);
320 pod2usage({-msg => "Syntax error.", -exitval => 2, -output => \*STDERR});
322 pod2usage({-msg => "Syntax error.", -verbose => 0, -output => \*STDERR});
324 pod2usage(-msg => "Syntax error.", -exitval => 2, -verbose => 0);
326 pod2usage(-message => "Syntax error.",
328 -exitval => 2,
329 -verbose => 0,
330 -output => \*STDERR);
331 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 pod2usage(1);
337 pod2usage(-verbose => 1);
339 pod2usage(-exitval => 1);
341 pod2usage({-exitval => 1, -output => \*STDOUT});
343 pod2usage({-verbose => 1, -output => \*STDOUT});
345 pod2usage(-exitval => 1, -verbose => 1);
347 pod2usage(-exitval => 1, -verbose => 1, -output => \*STDOUT});
349 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 pod2usage(-verbose => 2);
354 pod2usage({-verbose => 2, -output => \*STDOUT});
356 pod2usage(-exitval => 1, -verbose => 2);
358 pod2usage({-exitval => 1, -verbose => 2, -output => \*STDOUT});
360 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 use strict;
372 use Getopt::Long qw(GetOptions);
373 use Pod::Usage qw(pod2usage);
374 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 ## 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 __END__
388 =head1 NAME
390 sample - Using GetOpt::Long and Pod::Usage
392 =head1 SYNOPSIS
394 sample [options] [file ...]
396 Options:
398 -help brief help message
399 -man full documentation
400 =head1 OPTIONS
402 =over 4
404 =item B<-help>
406 Print a brief help message and exits.
408 =item B<-man>
410 Prints the manual page and exits.
412 =back
414 =head1 DESCRIPTION
416 B<This program> will read the given input file(s) and do something
418 useful with the contents thereof.
419 =cut
421
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 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 Please report bugs using <http://rt.cpan.org>.
443 Marek Rouchal <marekr@cpan.org>
445 Brad Appleton <bradapp@enteract.com>
447 Based on code for Pod::Text::pod2text() written by Tom Christiansen
449 <tchrist@mox.perl.com>
450
452 Pod::Usage (the distribution) is licensed under the same terms as Perl.
453
455 rjbs for refactoring Pod::Usage to not use Pod::Parser any more.
456 Steven McDougall <swmcd@world.std.com> for his help and patience with
458 re-writing this manpage.
459
461 Pod::Usage is now a standalone distribution, depending on Pod::Text
462 which in turn depends on Pod::Simple.
463 Pod::Perldoc, Getopt::Long, Pod::Find, FindBin, Pod::Text,
465 Pod::Text::Termcap, Pod::Simple
466perl v5.30.1 2020-03-16 Pod::Usage(3)