Copyright (C) 2000-2012 |
Manpages UsageSection: User Contributed Perl Documentation (3)Updated: 1999-12-09 Index Return to Main Contents NAMEpod2usage - print a usage message using a script's embedded pod documentationSYNOPSISuse PDL::Pod::Usage; pod2usage(); pod2usage(2); pod2usage({EXIT => 2}); pod2usage({EXIT => 2, VERBOSE => 0}); pod2usage(EXIT => 1, VERBOSE => 2, OUTPUT=\*STDERR); pod2usage(VERBOSE => 2); DESCRIPTIONpod2usage will print a usage message for the invoking script (using its embedded pod documentation) and then exit the script with the specified exit value. It takes a single argument which is either a numeric value corresponding to the desired exit status (which defaults to 2), or a reference to a hash. If more than one argument is given then the entire argument list is assumed to be a hash. If a hash is supplied it should contain elements with one or more of the following keys:
If neither the exit value nor the verbose level is specified, then the default is to use an exit value of 2 with a verbose level of 0. If an exit value is specified but the verbose level is not, then the verbose level will default to 1 if the exit value is less than 2 and will default to 0 otherwise. If a verbose level is specified but an exit value is not, then the exit value will default to 2 if the verbose level is 0 and will default to 1 otherwise. EXAMPLEMost scripts should print some type of usage message to STDERR when a command line syntax error is detected. They should also provide an option (usually "-h" or "-help") to print a (possibly more verbose) usage message to STDOUT. Some scripts may even wish to go so far as to provide a means of printing their complete documentation to STDOUT (perhaps by allowing a "-man" option). The following example uses pod2usage in combination with Getopt::Long to do all of these things:
use PDL::Pod::Usage; use Getopt::Long; GetOptions("help", "man") || pod2usage(2); pod2usage(1) if ($opt_help); pod2usage(VERBOSE => 2) if ($opt_man); CAVEATSBy default, pod2usage() will use $0 as the path to the pod input file. Unfortunately, not all systems on which Perl runs will set $0 properly (although if $0 isn't found, pod2usage() will search $ENV{PATH}). If this is the case for your system, you may need to explicitly specify the path to the pod docs for the invoking script using something similar to the following:
AUTHORBrad Appleton <Brad_Appleton-GBDA001@email.mot.com>Based on code for Pod::Text::pod2text() written by Tom Christiansen <tchrist@mox.perl.com>
IndexThis document was created by man2html, using the manual pages. Time: 14:11:57 GMT, April 25, 2024 |