1Pod::Usage(3pm)        Perl Programmers Reference Guide        Pod::Usage(3pm)
2
3
4

NAME

6       Pod::Usage, pod2usage() - print a usage message from embedded pod
7       documentation
8

SYNOPSIS

10         use Pod::Usage
11
12         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
17         pod2usage($message_text);
18
19         pod2usage($exit_status);
20
21         pod2usage( { -message => $message_text ,
22                      -exitval => $exit_status  ,
23                      -verbose => $verbose_level,
24                      -output  => $filehandle } );
25
26         pod2usage(   -msg     => $message_text ,
27                      -exitval => $exit_status  ,
28                      -verbose => $verbose_level,
29                      -output  => $filehandle   );
30
31         pod2usage(   -verbose => 2,
32                      -noperldoc => 1  )
33

ARGUMENTS

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
40       ·   A string containing the text of a message to print before printing
41           the usage message
42
43       ·   A numeric value corresponding to the desired exit status
44
45       ·   A reference to a hash
46
47       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
52       "-message"
53       "-msg"
54           The text of a message to print immediately prior to printing the
55           program's usage message.
56
57       "-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
63       "-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
72           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
76       "-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
81           Alternatively, an array reference of section specifications can be
82           used:
83
84             pod2usage(-verbose => 99,
85                       -sections => [ qw(fred fred/subsection) ] );
86
87       "-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
93       "-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
99           If you are calling pod2usage() from a module and want to display
100           that module's POD, you can use this:
101
102             use Pod::Find qw(pod_where);
103             pod2usage( -input => pod_where({-inc => 1}, __PACKAGE__) );
104
105       "-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
114       "-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

DESCRIPTION

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
131       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
135       ·   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
139       ·   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
143       ·   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
147       ·   If the exit status used is less than 2, then output is printed on
148           "STDOUT".  Otherwise output is printed on "STDERR".
149
150       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
155       ·   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
158       ·   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
163       ·   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
167       ·   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
173       ·   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
178       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
184           use Pod::Usage;
185           use Getopt::Long;
186
187           ## Parse options
188           GetOptions("help", "man", "flag1")  ||  pod2usage(2);
189           pod2usage(1)  if ($opt_help);
190           pod2usage(-verbose => 2)  if ($opt_man);
191
192           ## Check for too many filenames
193           pod2usage("$0: Too many files given.\n")  if (@ARGV > 1);
194
195       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
199           use Pod::Usage;
200           use Getopt::Long;
201
202           ## 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
207           ## Check for too many filenames
208           pod2usage(-verbose => 2, -message => "$0: Too many files given.\n")
209               if (@ARGV > 1);
210
211       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

EXAMPLES

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
220           pod2usage();
221
222           pod2usage(2);
223
224           pod2usage(-verbose => 0);
225
226           pod2usage(-exitval => 2);
227
228           pod2usage({-exitval => 2, -output => \*STDERR});
229
230           pod2usage({-verbose => 0, -output  => \*STDERR});
231
232           pod2usage(-exitval => 2, -verbose => 0);
233
234           pod2usage(-exitval => 2, -verbose => 0, -output => \*STDERR);
235
236       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
241           pod2usage("Syntax error.");
242
243           pod2usage(-message => "Syntax error.", -verbose => 0);
244
245           pod2usage(-msg  => "Syntax error.", -exitval => 2);
246
247           pod2usage({-msg => "Syntax error.", -exitval => 2, -output => \*STDERR});
248
249           pod2usage({-msg => "Syntax error.", -verbose => 0, -output => \*STDERR});
250
251           pod2usage(-msg  => "Syntax error.", -exitval => 2, -verbose => 0);
252
253           pod2usage(-message => "Syntax error.",
254                     -exitval => 2,
255                     -verbose => 0,
256                     -output  => \*STDERR);
257
258       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
262           pod2usage(1);
263
264           pod2usage(-verbose => 1);
265
266           pod2usage(-exitval => 1);
267
268           pod2usage({-exitval => 1, -output => \*STDOUT});
269
270           pod2usage({-verbose => 1, -output => \*STDOUT});
271
272           pod2usage(-exitval => 1, -verbose => 1);
273
274           pod2usage(-exitval => 1, -verbose => 1, -output => \*STDOUT});
275
276       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
279           pod2usage(-verbose  => 2);
280
281           pod2usage({-verbose => 2, -output => \*STDOUT});
282
283           pod2usage(-exitval  => 1, -verbose => 2);
284
285           pod2usage({-exitval => 1, -verbose => 2, -output => \*STDOUT});
286
287   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
297           use Getopt::Long;
298           use Pod::Usage;
299
300           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
308           ## 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
313           =head1 NAME
314
315           sample - Using GetOpt::Long and Pod::Usage
316
317           =head1 SYNOPSIS
318
319           sample [options] [file ...]
320
321            Options:
322              -help            brief help message
323              -man             full documentation
324
325           =head1 OPTIONS
326
327           =over 8
328
329           =item B<-help>
330
331           Print a brief help message and exits.
332
333           =item B<-man>
334
335           Prints the manual page and exits.
336
337           =back
338
339           =head1 DESCRIPTION
340
341           B<This program> will read the given input file(s) and do something
342           useful with the contents thereof.
343
344           =cut
345

CAVEATS

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
354           pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs");
355
356       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

AUTHOR

362       Please report bugs using <http://rt.cpan.org>.
363
364       Marek Rouchal <marekr@cpan.org>
365
366       Brad Appleton <bradapp@enteract.com>
367
368       Based on code for Pod::Text::pod2text() written by Tom Christiansen
369       <tchrist@mox.perl.com>
370

ACKNOWLEDGMENTS

372       Steven McDougall <swmcd@world.std.com> for his help and patience with
373       re-writing this manpage.
374

SEE ALSO

376       Pod::Parser, Getopt::Long, Pod::Find
377
378
379
380perl v5.12.4                      2011-06-01                   Pod::Usage(3pm)
Impressum