1Pod::Usage(3pm) Perl Programmers Reference Guide Pod::Usage(3pm)
2
6 Pod::Usage, pod2usage() - print a usage message from embedded pod
7 documentation
8
10 use Pod::Usage
11 my $message_text = "This text precedes the usage message.";
13 my $exit_status = 2; ## The exit status to use
14 my $verbose_level = 0; ## The verbose level to use
15 my $filehandle = \*STDERR; ## The filehandle to write to
16 pod2usage($message_text);
18 pod2usage($exit_status);
20 pod2usage( { -message => $message_text ,
22 -exitval => $exit_status ,
23 -verbose => $verbose_level,
24 -output => $filehandle } );
25 pod2usage( -msg => $message_text ,
27 -exitval => $exit_status ,
28 -verbose => $verbose_level,
29 -output => $filehandle );
30 pod2usage( -verbose => 2,
32 -noperldoc => 1 )
33
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 · A string containing the text of a message to print before printing
41 the usage message
42 · A numeric value corresponding to the desired exit status
44 · A reference to a hash
46 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
49 as a list) it should contain one or more elements with the following
50 keys:
51 "-message"
53 "-msg"
54 The text of a message to print immediately prior to printing the
55 program's usage message.
56 "-exitval"
58 The desired exit status to pass to the exit() function. This
59 should be an integer, or else the string "NOEXIT" to indicate that
60 control should simply be returned without terminating the invoking
61 process.
62 "-verbose"
64 The desired level of "verboseness" to use when printing the usage
65 message. If the corresponding value is 0, then only the "SYNOPSIS"
66 section of the pod documentation is printed. If the corresponding
67 value is 1, then the "SYNOPSIS" section, along with any section
68 entitled "OPTIONS", "ARGUMENTS", or "OPTIONS AND ARGUMENTS" is
69 printed. If the corresponding value is 2 or more then the entire
70 manpage is printed.
71 The special verbosity level 99 requires to also specify the
73 -sections parameter; then these sections are extracted (see
74 Pod::Select) and printed.
75 "-sections"
77 A string representing a selection list for sections to be printed
78 when -verbose is set to 99, e.g.
79 "NAME|SYNOPSIS|DESCRIPTION|VERSION".
80 Alternatively, an array reference of section specifications can be
82 used:
83 pod2usage(-verbose => 99,
85 -sections => [ qw(fred fred/subsection) ] );
86 "-output"
88 A reference to a filehandle, or the pathname of a file to which the
89 usage message should be written. The default is "\*STDERR" unless
90 the exit value is less than 2 (in which case the default is
91 "\*STDOUT").
92 "-input"
94 A reference to a filehandle, or the pathname of a file from which
95 the invoking script's pod documentation should be read. It
96 defaults to the file indicated by $0 ($PROGRAM_NAME for users of
97 English.pm).
98 If you are calling pod2usage() from a module and want to display
100 that module's POD, you can use this:
101 use Pod::Find qw(pod_where);
103 pod2usage( -input => pod_where({-inc => 1}, __PACKAGE__) );
104 "-pathlist"
106 A list of directory paths. If the input file does not exist, then
107 it will be searched for in the given directory list (in the order
108 the directories appear in the list). It defaults to the list of
109 directories implied by $ENV{PATH}. The list may be specified either
110 by a reference to an array, or by a string of directory paths which
111 use the same path separator as $ENV{PATH} on your system (e.g., ":"
112 for Unix, ";" for MSWin32 and DOS).
113 "-noperldoc"
115 By default, Pod::Usage will call perldoc when -verbose >= 2 is
116 specified. This does not work well e.g. if the script was packed
117 with PAR. The -noperldoc option suppresses the external call to
118 perldoc and uses the simple text formatter (Pod::Text) to output
119 the POD.
120
122 pod2usage will print a usage message for the invoking script (using its
123 embedded pod documentation) and then exit the script with the desired
124 exit status. The usage message printed may have any one of three levels
125 of "verboseness": If the verbose level is 0, then only a synopsis is
126 printed. If the verbose level is 1, then the synopsis is printed along
127 with a description (if present) of the command line options and
128 arguments. If the verbose level is 2, then the entire manual page is
129 printed.
130 Unless they are explicitly specified, the default values for the exit
132 status, verbose level, and output stream to use are determined as
133 follows:
134 · If neither the exit status nor the verbose level is specified, then
136 the default is to use an exit status of 2 with a verbose level of
137 0.
138 · If an exit status is specified but the verbose level is not, then
140 the verbose level will default to 1 if the exit status is less than
141 2 and will default to 0 otherwise.
142 · If an exit status is not specified but verbose level is given, then
144 the exit status will default to 2 if the verbose level is 0 and
145 will default to 1 otherwise.
146 · If the exit status used is less than 2, then output is printed on
148 "STDOUT". Otherwise output is printed on "STDERR".
149 Although the above may seem a bit confusing at first, it generally does
151 "the right thing" in most situations. This determination of the
152 default values to use is based upon the following typical Unix
153 conventions:
154 · An exit status of 0 implies "success". For example, diff(1) exits
156 with a status of 0 if the two files have the same contents.
157 · An exit status of 1 implies possibly abnormal, but non-defective,
159 program termination. For example, grep(1) exits with a status of 1
160 if it did not find a matching line for the given regular
161 expression.
162 · An exit status of 2 or more implies a fatal error. For example,
164 ls(1) exits with a status of 2 if you specify an illegal (unknown)
165 option on the command line.
166 · Usage messages issued as a result of bad command-line syntax should
168 go to "STDERR". However, usage messages issued due to an explicit
169 request to print usage (like specifying -help on the command line)
170 should go to "STDOUT", just in case the user wants to pipe the
171 output to a pager (such as more(1)).
172 · If program usage has been explicitly requested by the user, it is
174 often desirable to exit with a status of 1 (as opposed to 0) after
175 issuing the user-requested usage message. It is also desirable to
176 give a more verbose description of program usage in this case.
177 pod2usage doesn't force the above conventions upon you, but it will use
179 them by default if you don't expressly tell it to do otherwise. The
180 ability of pod2usage() to accept a single number or a string makes it
181 convenient to use as an innocent looking error message handling
182 function:
183 use Pod::Usage;
185 use Getopt::Long;
186 ## Parse options
188 GetOptions("help", "man", "flag1") || pod2usage(2);
189 pod2usage(1) if ($opt_help);
190 pod2usage(-verbose => 2) if ($opt_man);
191 ## Check for too many filenames
193 pod2usage("$0: Too many files given.\n") if (@ARGV > 1);
194 Some user's however may feel that the above "economy of expression" is
196 not particularly readable nor consistent and may instead choose to do
197 something more like the following:
198 use Pod::Usage;
200 use Getopt::Long;
201 ## Parse options
203 GetOptions("help", "man", "flag1") || pod2usage(-verbose => 0);
204 pod2usage(-verbose => 1) if ($opt_help);
205 pod2usage(-verbose => 2) if ($opt_man);
206 ## Check for too many filenames
208 pod2usage(-verbose => 2, -message => "$0: Too many files given.\n")
209 if (@ARGV > 1);
210 As with all things in Perl, there's more than one way to do it, and
212 pod2usage() adheres to this philosophy. If you are interested in
213 seeing a number of different ways to invoke pod2usage (although by no
214 means exhaustive), please refer to "EXAMPLES".
215
217 Each of the following invocations of "pod2usage()" will print just the
218 "SYNOPSIS" section to "STDERR" and will exit with a status of 2:
219 pod2usage();
221 pod2usage(2);
223 pod2usage(-verbose => 0);
225 pod2usage(-exitval => 2);
227 pod2usage({-exitval => 2, -output => \*STDERR});
229 pod2usage({-verbose => 0, -output => \*STDERR});
231 pod2usage(-exitval => 2, -verbose => 0);
233 pod2usage(-exitval => 2, -verbose => 0, -output => \*STDERR);
235 Each of the following invocations of "pod2usage()" will print a message
237 of "Syntax error." (followed by a newline) to "STDERR", immediately
238 followed by just the "SYNOPSIS" section (also printed to "STDERR") and
239 will exit with a status of 2:
240 pod2usage("Syntax error.");
242 pod2usage(-message => "Syntax error.", -verbose => 0);
244 pod2usage(-msg => "Syntax error.", -exitval => 2);
246 pod2usage({-msg => "Syntax error.", -exitval => 2, -output => \*STDERR});
248 pod2usage({-msg => "Syntax error.", -verbose => 0, -output => \*STDERR});
250 pod2usage(-msg => "Syntax error.", -exitval => 2, -verbose => 0);
252 pod2usage(-message => "Syntax error.",
254 -exitval => 2,
255 -verbose => 0,
256 -output => \*STDERR);
257 Each of the following invocations of "pod2usage()" will print the
259 "SYNOPSIS" section and any "OPTIONS" and/or "ARGUMENTS" sections to
260 "STDOUT" and will exit with a status of 1:
261 pod2usage(1);
263 pod2usage(-verbose => 1);
265 pod2usage(-exitval => 1);
267 pod2usage({-exitval => 1, -output => \*STDOUT});
269 pod2usage({-verbose => 1, -output => \*STDOUT});
271 pod2usage(-exitval => 1, -verbose => 1);
273 pod2usage(-exitval => 1, -verbose => 1, -output => \*STDOUT});
275 Each of the following invocations of "pod2usage()" will print the
277 entire manual page to "STDOUT" and will exit with a status of 1:
278 pod2usage(-verbose => 2);
280 pod2usage({-verbose => 2, -output => \*STDOUT});
282 pod2usage(-exitval => 1, -verbose => 2);
284 pod2usage({-exitval => 1, -verbose => 2, -output => \*STDOUT});
286 Recommended Use
288 Most scripts should print some type of usage message to "STDERR" when a
289 command line syntax error is detected. They should also provide an
290 option (usually "-H" or "-help") to print a (possibly more verbose)
291 usage message to "STDOUT". Some scripts may even wish to go so far as
292 to provide a means of printing their complete documentation to "STDOUT"
293 (perhaps by allowing a "-man" option). The following complete example
294 uses Pod::Usage in combination with Getopt::Long to do all of these
295 things:
296 use Getopt::Long;
298 use Pod::Usage;
299 my $man = 0;
301 my $help = 0;
302 ## Parse options and print usage if there is a syntax error,
303 ## or if usage was explicitly requested.
304 GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
305 pod2usage(1) if $help;
306 pod2usage(-verbose => 2) if $man;
307 ## If no arguments were given, then allow STDIN to be used only
309 ## if it's not connected to a terminal (otherwise print usage)
310 pod2usage("$0: No files given.") if ((@ARGV == 0) && (-t STDIN));
311 __END__
312 =head1 NAME
314 sample - Using GetOpt::Long and Pod::Usage
316 =head1 SYNOPSIS
318 sample [options] [file ...]
320 Options:
322 -help brief help message
323 -man full documentation
324 =head1 OPTIONS
326 =over 8
328 =item B<-help>
330 Print a brief help message and exits.
332 =item B<-man>
334 Prints the manual page and exits.
336 =back
338 =head1 DESCRIPTION
340 B<This program> will read the given input file(s) and do something
342 useful with the contents thereof.
343 =cut
345
347 By default, pod2usage() will use $0 as the path to the pod input file.
348 Unfortunately, not all systems on which Perl runs will set $0 properly
349 (although if $0 isn't found, pod2usage() will search $ENV{PATH} or else
350 the list specified by the "-pathlist" option). If this is the case for
351 your system, you may need to explicitly specify the path to the pod
352 docs for the invoking script using something similar to the following:
353 pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs");
355 In the pathological case that a script is called via a relative path
357 and the script itself changes the current working directory (see
358 "chdir" in perlfunc) before calling pod2usage, Pod::Usage will fail
359 even on robust platforms. Don't do that.
360
362 Please report bugs using <http://rt.cpan.org>.
363 Marek Rouchal <marekr@cpan.org>
365 Brad Appleton <bradapp@enteract.com>
367 Based on code for Pod::Text::pod2text() written by Tom Christiansen
369 <tchrist@mox.perl.com>
370
372 Steven McDougall <swmcd@world.std.com> for his help and patience with
373 re-writing this manpage.
374
376 Pod::Parser, Getopt::Long, Pod::Find
377perl v5.10.1 2009-04-12 Pod::Usage(3pm)