| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "Pod::Usage 3perl" |
| 58 |
.TH Pod::Usage 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
Pod::Usage \- extracts POD documentation and shows usage information |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& use Pod::Usage; |
| 69 |
\& |
| 70 |
\& my $message_text = "This text precedes the usage message."; |
| 71 |
\& my $exit_status = 2; ## The exit status to use |
| 72 |
\& my $verbose_level = 0; ## The verbose level to use |
| 73 |
\& my $filehandle = \e*STDERR; ## The filehandle to write to |
| 74 |
\& |
| 75 |
\& pod2usage($message_text); |
| 76 |
\& |
| 77 |
\& pod2usage($exit_status); |
| 78 |
\& |
| 79 |
\& pod2usage( { \-message => $message_text , |
| 80 |
\& \-exitval => $exit_status , |
| 81 |
\& \-verbose => $verbose_level, |
| 82 |
\& \-output => $filehandle } ); |
| 83 |
\& |
| 84 |
\& pod2usage( \-msg => $message_text , |
| 85 |
\& \-exitval => $exit_status , |
| 86 |
\& \-verbose => $verbose_level, |
| 87 |
\& \-output => $filehandle ); |
| 88 |
\& |
| 89 |
\& pod2usage( \-verbose => 2, |
| 90 |
\& \-noperldoc => 1 ); |
| 91 |
\& |
| 92 |
\& pod2usage( \-verbose => 2, |
| 93 |
\& \-perlcmd => $path_to_perl, |
| 94 |
\& \-perldoc => $path_to_perldoc, |
| 95 |
\& \-perldocopt => $perldoc_options ); |
| 96 |
.Ve |
| 97 |
.SH ARGUMENTS |
| 98 |
.IX Header "ARGUMENTS" |
| 99 |
\&\fBpod2usage\fR should be given either a single argument, or a list of |
| 100 |
arguments corresponding to an associative array (a "hash"). When a single |
| 101 |
argument is given, it should correspond to exactly one of the following: |
| 102 |
.IP \(bu 4 |
| 103 |
A string containing the text of a message to print \fIbefore\fR printing |
| 104 |
the usage message |
| 105 |
.IP \(bu 4 |
| 106 |
A numeric value corresponding to the desired exit status |
| 107 |
.IP \(bu 4 |
| 108 |
A reference to a hash |
| 109 |
.PP |
| 110 |
If more than one argument is given then the entire argument list is |
| 111 |
assumed to be a hash. If a hash is supplied (either as a reference or |
| 112 |
as a list) it should contain one or more elements with the following |
| 113 |
keys: |
| 114 |
.ie n .IP """\-message"" \fIstring\fR" 4 |
| 115 |
.el .IP "\f(CW\-message\fR \fIstring\fR" 4 |
| 116 |
.IX Item "-message string" |
| 117 |
.PD 0 |
| 118 |
.ie n .IP """\-msg"" \fIstring\fR" 4 |
| 119 |
.el .IP "\f(CW\-msg\fR \fIstring\fR" 4 |
| 120 |
.IX Item "-msg string" |
| 121 |
.PD |
| 122 |
The text of a message to print immediately prior to printing the |
| 123 |
program's usage message. |
| 124 |
.ie n .IP """\-exitval"" \fIvalue\fR" 4 |
| 125 |
.el .IP "\f(CW\-exitval\fR \fIvalue\fR" 4 |
| 126 |
.IX Item "-exitval value" |
| 127 |
The desired exit status to pass to the \fBexit()\fR function. |
| 128 |
This should be an integer, or else the string \f(CW\*(C`NOEXIT\*(C'\fR to |
| 129 |
indicate that control should simply be returned without |
| 130 |
terminating the invoking process. |
| 131 |
.ie n .IP """\-verbose"" \fIvalue\fR" 4 |
| 132 |
.el .IP "\f(CW\-verbose\fR \fIvalue\fR" 4 |
| 133 |
.IX Item "-verbose value" |
| 134 |
The desired level of "verboseness" to use when printing the usage message. |
| 135 |
If the value is 0, then only the "SYNOPSIS" and/or "USAGE" sections of the |
| 136 |
pod documentation are printed. If the value is 1, then the "SYNOPSIS" and/or |
| 137 |
"USAGE" sections, along with any section entitled "OPTIONS", "ARGUMENTS", or |
| 138 |
"OPTIONS AND ARGUMENTS" is printed. If the corresponding value is 2 or more |
| 139 |
then the entire manpage is printed, using perldoc if available; otherwise |
| 140 |
Pod::Text is used for the formatting. For better readability, the |
| 141 |
all-capital headings are downcased, e.g. \f(CW\*(C`SYNOPSIS\*(C'\fR => \f(CW\*(C`Synopsis\*(C'\fR. |
| 142 |
.Sp |
| 143 |
The special verbosity level 99 requires to also specify the \-sections |
| 144 |
parameter; then these sections are extracted and printed. |
| 145 |
.ie n .IP """\-sections"" \fIspec\fR" 4 |
| 146 |
.el .IP "\f(CW\-sections\fR \fIspec\fR" 4 |
| 147 |
.IX Item "-sections spec" |
| 148 |
There are two ways to specify the selection. Either a string (scalar) |
| 149 |
representing a selection regexp for sections to be printed when \-verbose |
| 150 |
is set to 99, e.g. |
| 151 |
.Sp |
| 152 |
.Vb 1 |
| 153 |
\& "NAME|SYNOPSIS|DESCRIPTION|VERSION" |
| 154 |
.Ve |
| 155 |
.Sp |
| 156 |
With the above regexp all content following (and including) any of the |
| 157 |
given \f(CW\*(C`=head1\*(C'\fR headings will be shown. It is possible to restrict the |
| 158 |
output to particular subsections only, e.g.: |
| 159 |
.Sp |
| 160 |
.Vb 1 |
| 161 |
\& "DESCRIPTION/Algorithm" |
| 162 |
.Ve |
| 163 |
.Sp |
| 164 |
This will output only the \f(CW\*(C`=head2 Algorithm\*(C'\fR heading and content within |
| 165 |
the \f(CW\*(C`=head1 DESCRIPTION\*(C'\fR section. The regexp binding is stronger than the |
| 166 |
section separator, such that e.g.: |
| 167 |
.Sp |
| 168 |
.Vb 1 |
| 169 |
\& "DESCRIPTION|OPTIONS|ENVIRONMENT/Caveats" |
| 170 |
.Ve |
| 171 |
.Sp |
| 172 |
will print any \f(CW\*(C`=head2 Caveats\*(C'\fR section (only) within any of the three |
| 173 |
\&\f(CW\*(C`=head1\*(C'\fR sections. |
| 174 |
.Sp |
| 175 |
Alternatively, an array reference of section specifications can be used: |
| 176 |
.Sp |
| 177 |
.Vb 2 |
| 178 |
\& pod2usage(\-verbose => 99, \-sections => [ |
| 179 |
\& qw(DESCRIPTION DESCRIPTION/Introduction) ] ); |
| 180 |
.Ve |
| 181 |
.Sp |
| 182 |
This will print only the content of \f(CW\*(C`=head1 DESCRIPTION\*(C'\fR and the |
| 183 |
\&\f(CW\*(C`=head2 Introduction\*(C'\fR sections, but no other \f(CW\*(C`=head2\*(C'\fR, and no other |
| 184 |
\&\f(CW\*(C`=head1\*(C'\fR either. |
| 185 |
.ie n .IP """\-output"" \fIhandle\fR" 4 |
| 186 |
.el .IP "\f(CW\-output\fR \fIhandle\fR" 4 |
| 187 |
.IX Item "-output handle" |
| 188 |
A reference to a filehandle, or the pathname of a file to which the |
| 189 |
usage message should be written. The default is \f(CW\*(C`\e*STDERR\*(C'\fR unless the |
| 190 |
exit value is less than 2 (in which case the default is \f(CW\*(C`\e*STDOUT\*(C'\fR). |
| 191 |
.ie n .IP """\-input"" \fIhandle\fR" 4 |
| 192 |
.el .IP "\f(CW\-input\fR \fIhandle\fR" 4 |
| 193 |
.IX Item "-input handle" |
| 194 |
A reference to a filehandle, or the pathname of a file from which the |
| 195 |
invoking script's pod documentation should be read. It defaults to the |
| 196 |
file indicated by \f(CW$0\fR (\f(CW$PROGRAM_NAME\fR for users of \fIEnglish.pm\fR). |
| 197 |
.Sp |
| 198 |
If you are calling \fBpod2usage()\fR from a module and want to display |
| 199 |
that module's POD, you can use this: |
| 200 |
.Sp |
| 201 |
.Vb 2 |
| 202 |
\& use Pod::Find qw(pod_where); |
| 203 |
\& pod2usage( \-input => pod_where({\-inc => 1}, _\|_PACKAGE_\|_) ); |
| 204 |
.Ve |
| 205 |
.ie n .IP """\-pathlist"" \fIstring\fR" 4 |
| 206 |
.el .IP "\f(CW\-pathlist\fR \fIstring\fR" 4 |
| 207 |
.IX Item "-pathlist string" |
| 208 |
A list of directory paths. If the input file does not exist, then it |
| 209 |
will be searched for in the given directory list (in the order the |
| 210 |
directories appear in the list). It defaults to the list of directories |
| 211 |
implied by \f(CW$ENV{PATH}\fR. The list may be specified either by a reference |
| 212 |
to an array, or by a string of directory paths which use the same path |
| 213 |
separator as \f(CW$ENV{PATH}\fR on your system (e.g., \f(CW\*(C`:\*(C'\fR for Unix, \f(CW\*(C`;\*(C'\fR for |
| 214 |
MSWin32 and DOS). |
| 215 |
.ie n .IP """\-noperldoc""" 4 |
| 216 |
.el .IP \f(CW\-noperldoc\fR 4 |
| 217 |
.IX Item "-noperldoc" |
| 218 |
By default, Pod::Usage will call perldoc when \-verbose >= 2 is specified. |
| 219 |
This does not work well e.g. if the script was packed with PAR. This option |
| 220 |
suppresses the external call to perldoc and uses the simple text formatter |
| 221 |
(Pod::Text) to output the POD. |
| 222 |
.ie n .IP """\-perlcmd""" 4 |
| 223 |
.el .IP \f(CW\-perlcmd\fR 4 |
| 224 |
.IX Item "-perlcmd" |
| 225 |
By default, Pod::Usage will call perldoc when \-verbose >= 2 is |
| 226 |
specified. In case of special or unusual Perl installations, |
| 227 |
this option may be used to supply the path to a perl executable |
| 228 |
which should run perldoc. |
| 229 |
.ie n .IP """\-perldoc"" \fIpath-to-perldoc\fR" 4 |
| 230 |
.el .IP "\f(CW\-perldoc\fR \fIpath-to-perldoc\fR" 4 |
| 231 |
.IX Item "-perldoc path-to-perldoc" |
| 232 |
By default, Pod::Usage will call perldoc when \-verbose >= 2 is |
| 233 |
specified. In case perldoc is not installed where the perl interpreter |
| 234 |
thinks it is (see Config), the \-perldoc option may be used to supply |
| 235 |
the correct path to perldoc. |
| 236 |
.ie n .IP """\-perldocopt"" \fIstring\fR" 4 |
| 237 |
.el .IP "\f(CW\-perldocopt\fR \fIstring\fR" 4 |
| 238 |
.IX Item "-perldocopt string" |
| 239 |
By default, Pod::Usage will call perldoc when \-verbose >= 2 is specified. |
| 240 |
This option may be used to supply options to perldoc. The |
| 241 |
string may contain several, space-separated options. |
| 242 |
.SS "Formatting base class" |
| 243 |
.IX Subsection "Formatting base class" |
| 244 |
The default text formatter is Pod::Text. The base class for Pod::Usage can |
| 245 |
be defined by pre-setting \f(CW$Pod::Usage::Formatter\fR \fIbefore\fR |
| 246 |
loading Pod::Usage, e.g.: |
| 247 |
.PP |
| 248 |
.Vb 2 |
| 249 |
\& BEGIN { $Pod::Usage::Formatter = \*(AqPod::Text::Termcap\*(Aq; } |
| 250 |
\& use Pod::Usage qw(pod2usage); |
| 251 |
.Ve |
| 252 |
.PP |
| 253 |
Pod::Usage uses Pod::Simple's \fB_handle_element_end()\fR method to implement |
| 254 |
the section selection, and in case of verbosity < 2 it down-cases the |
| 255 |
all-caps headings to first capital letter and rest lowercase, and adds |
| 256 |
a colon/newline at the end of the headings, for better readability. Same for |
| 257 |
verbosity = 99. |
| 258 |
.SS "Pass-through options" |
| 259 |
.IX Subsection "Pass-through options" |
| 260 |
The following options are passed through to the underlying text formatter. |
| 261 |
See the manual pages of these modules for more information. |
| 262 |
.PP |
| 263 |
.Vb 1 |
| 264 |
\& alt code indent loose margin quotes sentence stderr utf8 width |
| 265 |
.Ve |
| 266 |
.SH DESCRIPTION |
| 267 |
.IX Header "DESCRIPTION" |
| 268 |
\&\fBpod2usage\fR will print a usage message for the invoking script (using |
| 269 |
its embedded pod documentation) and then exit the script with the |
| 270 |
desired exit status. The usage message printed may have any one of three |
| 271 |
levels of "verboseness": If the verbose level is 0, then only a synopsis |
| 272 |
is printed. If the verbose level is 1, then the synopsis is printed |
| 273 |
along with a description (if present) of the command line options and |
| 274 |
arguments. If the verbose level is 2, then the entire manual page is |
| 275 |
printed. |
| 276 |
.PP |
| 277 |
Unless they are explicitly specified, the default values for the exit |
| 278 |
status, verbose level, and output stream to use are determined as |
| 279 |
follows: |
| 280 |
.IP \(bu 4 |
| 281 |
If neither the exit status nor the verbose level is specified, then the |
| 282 |
default is to use an exit status of 2 with a verbose level of 0. |
| 283 |
.IP \(bu 4 |
| 284 |
If an exit status \fIis\fR specified but the verbose level is \fInot\fR, then the |
| 285 |
verbose level will default to 1 if the exit status is less than 2 and |
| 286 |
will default to 0 otherwise. |
| 287 |
.IP \(bu 4 |
| 288 |
If an exit status is \fInot\fR specified but verbose level \fIis\fR given, then |
| 289 |
the exit status will default to 2 if the verbose level is 0 and will |
| 290 |
default to 1 otherwise. |
| 291 |
.IP \(bu 4 |
| 292 |
If the exit status used is less than 2, then output is printed on |
| 293 |
\&\f(CW\*(C`STDOUT\*(C'\fR. Otherwise output is printed on \f(CW\*(C`STDERR\*(C'\fR. |
| 294 |
.PP |
| 295 |
Although the above may seem a bit confusing at first, it generally does |
| 296 |
"the right thing" in most situations. This determination of the default |
| 297 |
values to use is based upon the following typical Unix conventions: |
| 298 |
.IP \(bu 4 |
| 299 |
An exit status of 0 implies "success". For example, \fBdiff\|(1)\fR exits |
| 300 |
with a status of 0 if the two files have the same contents. |
| 301 |
.IP \(bu 4 |
| 302 |
An exit status of 1 implies possibly abnormal, but non-defective, program |
| 303 |
termination. For example, \fBgrep\|(1)\fR exits with a status of 1 if |
| 304 |
it did \fInot\fR find a matching line for the given regular expression. |
| 305 |
.IP \(bu 4 |
| 306 |
An exit status of 2 or more implies a fatal error. For example, \fBls\|(1)\fR |
| 307 |
exits with a status of 2 if you specify an illegal (unknown) option on |
| 308 |
the command line. |
| 309 |
.IP \(bu 4 |
| 310 |
Usage messages issued as a result of bad command-line syntax should go |
| 311 |
to \f(CW\*(C`STDERR\*(C'\fR. However, usage messages issued due to an explicit request |
| 312 |
to print usage (like specifying \fB\-help\fR on the command line) should go |
| 313 |
to \f(CW\*(C`STDOUT\*(C'\fR, just in case the user wants to pipe the output to a pager |
| 314 |
(such as \fBmore\|(1)\fR). |
| 315 |
.IP \(bu 4 |
| 316 |
If program usage has been explicitly requested by the user, it is often |
| 317 |
desirable to exit with a status of 1 (as opposed to 0) after issuing |
| 318 |
the user-requested usage message. It is also desirable to give a |
| 319 |
more verbose description of program usage in this case. |
| 320 |
.PP |
| 321 |
\&\fBpod2usage\fR does not force the above conventions upon you, but it will |
| 322 |
use them by default if you don't expressly tell it to do otherwise. The |
| 323 |
ability of \fBpod2usage()\fR to accept a single number or a string makes it |
| 324 |
convenient to use as an innocent looking error message handling function: |
| 325 |
.PP |
| 326 |
.Vb 3 |
| 327 |
\& use strict; |
| 328 |
\& use Pod::Usage; |
| 329 |
\& use Getopt::Long; |
| 330 |
\& |
| 331 |
\& ## Parse options |
| 332 |
\& my %opt; |
| 333 |
\& GetOptions(\e%opt, "help|?", "man", "flag1") || pod2usage(2); |
| 334 |
\& pod2usage(1) if ($opt{help}); |
| 335 |
\& pod2usage(\-exitval => 0, \-verbose => 2) if ($opt{man}); |
| 336 |
\& |
| 337 |
\& ## Check for too many filenames |
| 338 |
\& pod2usage("$0: Too many files given.\en") if (@ARGV > 1); |
| 339 |
.Ve |
| 340 |
.PP |
| 341 |
Some user's however may feel that the above "economy of expression" is |
| 342 |
not particularly readable nor consistent and may instead choose to do |
| 343 |
something more like the following: |
| 344 |
.PP |
| 345 |
.Vb 3 |
| 346 |
\& use strict; |
| 347 |
\& use Pod::Usage qw(pod2usage); |
| 348 |
\& use Getopt::Long qw(GetOptions); |
| 349 |
\& |
| 350 |
\& ## Parse options |
| 351 |
\& my %opt; |
| 352 |
\& GetOptions(\e%opt, "help|?", "man", "flag1") || |
| 353 |
\& pod2usage(\-verbose => 0); |
| 354 |
\& |
| 355 |
\& pod2usage(\-verbose => 1) if ($opt{help}); |
| 356 |
\& pod2usage(\-verbose => 2) if ($opt{man}); |
| 357 |
\& |
| 358 |
\& ## Check for too many filenames |
| 359 |
\& pod2usage(\-verbose => 2, \-message => "$0: Too many files given.\en") |
| 360 |
\& if (@ARGV > 1); |
| 361 |
.Ve |
| 362 |
.PP |
| 363 |
As with all things in Perl, \fIthere's more than one way to do it\fR, and |
| 364 |
\&\fBpod2usage()\fR adheres to this philosophy. If you are interested in |
| 365 |
seeing a number of different ways to invoke \fBpod2usage\fR (although by no |
| 366 |
means exhaustive), please refer to "EXAMPLES". |
| 367 |
.SS Scripts |
| 368 |
.IX Subsection "Scripts" |
| 369 |
The Pod::Usage distribution comes with a script pod2usage which offers |
| 370 |
a command line interface to the functionality of Pod::Usage. See |
| 371 |
pod2usage. |
| 372 |
.SH EXAMPLES |
| 373 |
.IX Header "EXAMPLES" |
| 374 |
Each of the following invocations of \f(CWpod2usage()\fR will print just the |
| 375 |
"SYNOPSIS" section to \f(CW\*(C`STDERR\*(C'\fR and will exit with a status of 2: |
| 376 |
.PP |
| 377 |
.Vb 1 |
| 378 |
\& pod2usage(); |
| 379 |
\& |
| 380 |
\& pod2usage(2); |
| 381 |
\& |
| 382 |
\& pod2usage(\-verbose => 0); |
| 383 |
\& |
| 384 |
\& pod2usage(\-exitval => 2); |
| 385 |
\& |
| 386 |
\& pod2usage({\-exitval => 2, \-output => \e*STDERR}); |
| 387 |
\& |
| 388 |
\& pod2usage({\-verbose => 0, \-output => \e*STDERR}); |
| 389 |
\& |
| 390 |
\& pod2usage(\-exitval => 2, \-verbose => 0); |
| 391 |
\& |
| 392 |
\& pod2usage(\-exitval => 2, \-verbose => 0, \-output => \e*STDERR); |
| 393 |
.Ve |
| 394 |
.PP |
| 395 |
Each of the following invocations of \f(CWpod2usage()\fR will print a message |
| 396 |
of "Syntax error." (followed by a newline) to \f(CW\*(C`STDERR\*(C'\fR, immediately |
| 397 |
followed by just the "SYNOPSIS" section (also printed to \f(CW\*(C`STDERR\*(C'\fR) and |
| 398 |
will exit with a status of 2: |
| 399 |
.PP |
| 400 |
.Vb 1 |
| 401 |
\& pod2usage("Syntax error."); |
| 402 |
\& |
| 403 |
\& pod2usage(\-message => "Syntax error.", \-verbose => 0); |
| 404 |
\& |
| 405 |
\& pod2usage(\-msg => "Syntax error.", \-exitval => 2); |
| 406 |
\& |
| 407 |
\& pod2usage({\-msg => "Syntax error.", \-exitval => 2, \-output => \e*STDERR}); |
| 408 |
\& |
| 409 |
\& pod2usage({\-msg => "Syntax error.", \-verbose => 0, \-output => \e*STDERR}); |
| 410 |
\& |
| 411 |
\& pod2usage(\-msg => "Syntax error.", \-exitval => 2, \-verbose => 0); |
| 412 |
\& |
| 413 |
\& pod2usage(\-message => "Syntax error.", |
| 414 |
\& \-exitval => 2, |
| 415 |
\& \-verbose => 0, |
| 416 |
\& \-output => \e*STDERR); |
| 417 |
.Ve |
| 418 |
.PP |
| 419 |
Each of the following invocations of \f(CWpod2usage()\fR will print the |
| 420 |
"SYNOPSIS" section and any "OPTIONS" and/or "ARGUMENTS" sections to |
| 421 |
\&\f(CW\*(C`STDOUT\*(C'\fR and will exit with a status of 1: |
| 422 |
.PP |
| 423 |
.Vb 1 |
| 424 |
\& pod2usage(1); |
| 425 |
\& |
| 426 |
\& pod2usage(\-verbose => 1); |
| 427 |
\& |
| 428 |
\& pod2usage(\-exitval => 1); |
| 429 |
\& |
| 430 |
\& pod2usage({\-exitval => 1, \-output => \e*STDOUT}); |
| 431 |
\& |
| 432 |
\& pod2usage({\-verbose => 1, \-output => \e*STDOUT}); |
| 433 |
\& |
| 434 |
\& pod2usage(\-exitval => 1, \-verbose => 1); |
| 435 |
\& |
| 436 |
\& pod2usage(\-exitval => 1, \-verbose => 1, \-output => \e*STDOUT}); |
| 437 |
.Ve |
| 438 |
.PP |
| 439 |
Each of the following invocations of \f(CWpod2usage()\fR will print the |
| 440 |
entire manual page to \f(CW\*(C`STDOUT\*(C'\fR and will exit with a status of 1: |
| 441 |
.PP |
| 442 |
.Vb 1 |
| 443 |
\& pod2usage(\-verbose => 2); |
| 444 |
\& |
| 445 |
\& pod2usage({\-verbose => 2, \-output => \e*STDOUT}); |
| 446 |
\& |
| 447 |
\& pod2usage(\-exitval => 1, \-verbose => 2); |
| 448 |
\& |
| 449 |
\& pod2usage({\-exitval => 1, \-verbose => 2, \-output => \e*STDOUT}); |
| 450 |
.Ve |
| 451 |
.SS "Recommended Use" |
| 452 |
.IX Subsection "Recommended Use" |
| 453 |
Most scripts should print some type of usage message to \f(CW\*(C`STDERR\*(C'\fR when a |
| 454 |
command line syntax error is detected. They should also provide an |
| 455 |
option (usually \f(CW\*(C`\-H\*(C'\fR or \f(CW\*(C`\-help\*(C'\fR) to print a (possibly more verbose) |
| 456 |
usage message to \f(CW\*(C`STDOUT\*(C'\fR. Some scripts may even wish to go so far as to |
| 457 |
provide a means of printing their complete documentation to \f(CW\*(C`STDOUT\*(C'\fR |
| 458 |
(perhaps by allowing a \f(CW\*(C`\-man\*(C'\fR option). The following complete example |
| 459 |
uses \fBPod::Usage\fR in combination with \fBGetopt::Long\fR to do all of these |
| 460 |
things: |
| 461 |
.PP |
| 462 |
.Vb 3 |
| 463 |
\& use strict; |
| 464 |
\& use Getopt::Long qw(GetOptions); |
| 465 |
\& use Pod::Usage qw(pod2usage); |
| 466 |
\& |
| 467 |
\& my $man = 0; |
| 468 |
\& my $help = 0; |
| 469 |
\& ## Parse options and print usage if there is a syntax error, |
| 470 |
\& ## or if usage was explicitly requested. |
| 471 |
\& GetOptions(\*(Aqhelp|?\*(Aq => \e$help, man => \e$man) or pod2usage(2); |
| 472 |
\& pod2usage(1) if $help; |
| 473 |
\& pod2usage(\-verbose => 2) if $man; |
| 474 |
\& |
| 475 |
\& ## If no arguments were given, then allow STDIN to be used only |
| 476 |
\& ## if it\*(Aqs not connected to a terminal (otherwise print usage) |
| 477 |
\& pod2usage("$0: No files given.") if ((@ARGV == 0) && (\-t STDIN)); |
| 478 |
\& |
| 479 |
\& _\|_END_\|_ |
| 480 |
\& |
| 481 |
\& =head1 NAME |
| 482 |
\& |
| 483 |
\& sample \- Using GetOpt::Long and Pod::Usage |
| 484 |
\& |
| 485 |
\& =head1 SYNOPSIS |
| 486 |
\& |
| 487 |
\& sample [options] [file ...] |
| 488 |
\& |
| 489 |
\& Options: |
| 490 |
\& \-help brief help message |
| 491 |
\& \-man full documentation |
| 492 |
\& |
| 493 |
\& =head1 OPTIONS |
| 494 |
\& |
| 495 |
\& =over 4 |
| 496 |
\& |
| 497 |
\& =item B<\-help> |
| 498 |
\& |
| 499 |
\& Print a brief help message and exits. |
| 500 |
\& |
| 501 |
\& =item B<\-man> |
| 502 |
\& |
| 503 |
\& Prints the manual page and exits. |
| 504 |
\& |
| 505 |
\& =back |
| 506 |
\& |
| 507 |
\& =head1 DESCRIPTION |
| 508 |
\& |
| 509 |
\& B<This program> will read the given input file(s) and do something |
| 510 |
\& useful with the contents thereof. |
| 511 |
\& |
| 512 |
\& =cut |
| 513 |
.Ve |
| 514 |
.SH CAVEATS |
| 515 |
.IX Header "CAVEATS" |
| 516 |
By default, \fBpod2usage()\fR will use \f(CW$0\fR as the path to the pod input |
| 517 |
file. Unfortunately, not all systems on which Perl runs will set \f(CW$0\fR |
| 518 |
properly (although if \f(CW$0\fR is not found, \fBpod2usage()\fR will search |
| 519 |
\&\f(CW$ENV{PATH}\fR or else the list specified by the \f(CW\*(C`\-pathlist\*(C'\fR option). |
| 520 |
If this is the case for your system, you may need to explicitly specify |
| 521 |
the path to the pod docs for the invoking script using something |
| 522 |
similar to the following: |
| 523 |
.PP |
| 524 |
.Vb 1 |
| 525 |
\& pod2usage(\-exitval => 2, \-input => "/path/to/your/pod/docs"); |
| 526 |
.Ve |
| 527 |
.PP |
| 528 |
In the pathological case that a script is called via a relative path |
| 529 |
\&\fIand\fR the script itself changes the current working directory |
| 530 |
(see "chdir" in perlfunc) \fIbefore\fR calling pod2usage, Pod::Usage will |
| 531 |
fail even on robust platforms. Don't do that. Or use FindBin to locate |
| 532 |
the script: |
| 533 |
.PP |
| 534 |
.Vb 2 |
| 535 |
\& use FindBin; |
| 536 |
\& pod2usage(\-input => $FindBin::Bin . "/" . $FindBin::Script); |
| 537 |
.Ve |
| 538 |
.SH SUPPORT |
| 539 |
.IX Header "SUPPORT" |
| 540 |
This module is managed in a GitHub repository, |
| 541 |
<https://github.com/Dual\-Life/Pod\-Usage> Feel free to fork and contribute, or |
| 542 |
to clone and send patches! |
| 543 |
.PP |
| 544 |
Please use <https://github.com/Dual\-Life/Pod\-Usage/issues/new> to file a bug |
| 545 |
report. The previous ticketing system, |
| 546 |
<https://rt.cpan.org/Dist/Display.html?Queue=Pod\-Usage>, is deprecated for |
| 547 |
this package. |
| 548 |
.PP |
| 549 |
More general questions or discussion about POD should be sent to the |
| 550 |
\&\f(CW\*(C`pod\[email protected]\*(C'\fR mail list. Send an empty email to |
| 551 |
\&\f(CW\*(C`pod\-people\[email protected]\*(C'\fR to subscribe. |
| 552 |
.SH AUTHOR |
| 553 |
.IX Header "AUTHOR" |
| 554 |
Marek Rouchal <[email protected]> |
| 555 |
.PP |
| 556 |
Nicolas R <[email protected]> |
| 557 |
.PP |
| 558 |
Brad Appleton <[email protected]> |
| 559 |
.PP |
| 560 |
Based on code for \fBPod::Text::pod2text()\fR written by |
| 561 |
Tom Christiansen <[email protected]> |
| 562 |
.SH LICENSE |
| 563 |
.IX Header "LICENSE" |
| 564 |
Pod::Usage (the distribution) is licensed under the same terms as Perl. |
| 565 |
.SH ACKNOWLEDGMENTS |
| 566 |
.IX Header "ACKNOWLEDGMENTS" |
| 567 |
Nicolas R (ATOOMIC) for setting up the Github repo and modernizing this |
| 568 |
package. |
| 569 |
.PP |
| 570 |
rjbs for refactoring Pod::Usage to not use Pod::Parser any more. |
| 571 |
.PP |
| 572 |
Steven McDougall <[email protected]> for his help and patience with |
| 573 |
re-writing this manpage. |
| 574 |
.SH "SEE ALSO" |
| 575 |
.IX Header "SEE ALSO" |
| 576 |
\&\fBPod::Usage\fR is now a standalone distribution, depending on |
| 577 |
Pod::Text which in turn depends on Pod::Simple. |
| 578 |
.PP |
| 579 |
Pod::Perldoc, Getopt::Long, Pod::Find, FindBin, |
| 580 |
Pod::Text, Pod::Text::Termcap, Pod::Simple |