1Usage(3) User Contributed Perl Documentation Usage(3)
2
6 pod2usage - print a usage message using a script's embedded pod
7 documentation
8
10 use PDL::Pod::Usage;
11 pod2usage();
12 pod2usage(2);
13 pod2usage({EXIT => 2});
14 pod2usage({EXIT => 2, VERBOSE => 0});
15 pod2usage(EXIT => 1, VERBOSE => 2, OUTPUT=\*STDERR);
16 pod2usage(VERBOSE => 2);
17
19 pod2usage will print a usage message for the invoking script (using its
20 embedded pod documentation) and then exit the script with the specified
21 exit value. It takes a single argument which is either a numeric value
22 corresponding to the desired exit status (which defaults to 2), or a
23 reference to a hash. If more than one argument is given then the entire
24 argument list is assumed to be a hash. If a hash is supplied it should
25 contain elements with one or more of the following keys:
26 "EXIT"
28 The desired exit status to pass to the exit() function.
29 "VERBOSE"
31 The desired level of "verboseness" to use when printing the usage
32 message. If the corresponding value is 0, then only the "SYNOPSIS"
33 section of the pod documentation is printed. If the corresponding
34 value is 1, then the "SYNOPSIS" section, along with any section
35 entitled "OPTIONS", "ARGUMENTS", or "OPTIONS AND ARGUMENTS" is
36 printed. If the corresponding value is 2 or more then the entire
37 manpage is printed.
38 "OUTPUT"
40 A reference to a filehandle, or the pathname of a file to which the
41 usage message should be written. The default is "\*STDERR" unless
42 the exit value is less than 2 (in which case the default is
43 "\*STDOUT").
44 "INPUT"
46 A reference to a filehandle, or the pathname of a file from which
47 the invoking script's pod documentation should be read. It
48 defaults to the file indicated by $0 ($PROGRAM_NAME for "use
49 English;" users).
50 If neither the exit value nor the verbose level is specified, then the
52 default is to use an exit value of 2 with a verbose level of 0.
53 If an exit value is specified but the verbose level is not, then the
55 verbose level will default to 1 if the exit value is less than 2 and
56 will default to 0 otherwise.
57 If a verbose level is specified but an exit value is not, then the exit
59 value will default to 2 if the verbose level is 0 and will default to 1
60 otherwise.
61
63 Most scripts should print some type of usage message to STDERR when a
64 command line syntax error is detected. They should also provide an
65 option (usually "-h" or "-help") to print a (possibly more verbose)
66 usage message to STDOUT. Some scripts may even wish to go so far as to
67 provide a means of printing their complete documentation to STDOUT
68 (perhaps by allowing a "-man" option). The following example uses
69 pod2usage in combination with Getopt::Long to do all of these things:
70 use PDL::Pod::Usage;
72 use Getopt::Long;
73 GetOptions("help", "man") || pod2usage(2);
75 pod2usage(1) if ($opt_help);
76 pod2usage(VERBOSE => 2) if ($opt_man);
77
79 By default, pod2usage() will use $0 as the path to the pod input file.
80 Unfortunately, not all systems on which Perl runs will set $0 properly
81 (although if $0 isn't found, pod2usage() will search $ENV{PATH}). If
82 this is the case for your system, you may need to explicitly specify
83 the path to the pod docs for the invoking script using something
84 similar to the following:
85 ยท "pod2usage(EXIT => 2, INPUT => "/path/to/your/pod/docs");"
87
89 Brad Appleton <Brad_Appleton-GBDA001@email.mot.com>
90 Based on code for Pod::Text::pod2text() written by Tom Christiansen
92 <tchrist@mox.perl.com>
93perl v5.12.3 2009-10-17 Usage(3)