CONTENTS

• NAME
• SYNOPSIS
• ARGUMENTS
  • Formatting base class
  • Pass-through options
• DESCRIPTION
  • Scripts
• EXAMPLES
  • Recommended Use
• CAVEATS
• SUPPORT
• AUTHOR
• LICENSE
• ACKNOWLEDGMENTS
• SEE ALSO

#NAME

Pod::Usage - extracts POD documentation and shows usage information

#SYNOPSIS

use Pod::Usage;

my $message_text  = "This text precedes the usage message.";
my $exit_status   = 2;          ## The exit status to use
my $verbose_level = 0;          ## The verbose level to use
my $filehandle    = \*STDERR;   ## The filehandle to write to

pod2usage($message_text);

pod2usage($exit_status);

pod2usage( { -message => $message_text ,
             -exitval => $exit_status  ,
             -verbose => $verbose_level,
             -output  => $filehandle } );

pod2usage(   -msg     => $message_text ,
             -exitval => $exit_status  ,
             -verbose => $verbose_level,
             -output  => $filehandle );

pod2usage(   -verbose => 2,
             -noperldoc => 1  );

pod2usage(   -verbose => 2,
             -perlcmd => $path_to_perl,
             -perldoc => $path_to_perldoc,
             -perldocopt => $perldoc_options );

#ARGUMENTS

pod2usage should be given either a single argument, or a list of arguments corresponding to an associative array (a "hash"). When a single argument is given, it should correspond to exactly one of the following:

• A string containing the text of a message to print before printing the usage message

• A numeric value corresponding to the desired exit status

• 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 (either as a reference or as a list) it should contain one or more elements with the following keys:

#-message string

#-msg string

The text of a message to print immediately prior to printing the program's usage message.

#-exitval value

The desired exit status to pass to the exit() function. This should be an integer, or else the string NOEXIT to indicate that control should simply be returned without terminating the invoking process.

#-verbose value

The desired level of "verboseness" to use when printing the usage message. If the value is 0, then only the "SYNOPSIS" and/or "USAGE" sections of the pod documentation are printed. If the value is 1, then the "SYNOPSIS" and/or "USAGE" sections, along with any section entitled "OPTIONS", "ARGUMENTS", or "OPTIONS AND ARGUMENTS" is printed. If the corresponding value is 2 or more then the entire manpage is printed, using perldoc if available; otherwise Pod::Text is used for the formatting. For better readability, the all-capital headings are downcased, e.g. SYNOPSIS => Synopsis.

The special verbosity level 99 requires to also specify the -sections parameter; then these sections are extracted and printed.

#-sections spec

There are two ways to specify the selection. Either a string (scalar) representing a selection regexp for sections to be printed when -verbose is set to 99, e.g.

"NAME|SYNOPSIS|DESCRIPTION|VERSION"

With the above regexp all content following (and including) any of the given =head1 headings will be shown. It is possible to restrict the output to particular subsections only, e.g.:

"DESCRIPTION/Algorithm"

This will output only the =head2 Algorithm heading and content within the =head1 DESCRIPTION section. The regexp binding is stronger than the section separator, such that e.g.:

"DESCRIPTION|OPTIONS|ENVIRONMENT/Caveats"

will print any =head2 Caveats section (only) within any of the three =head1 sections.

Alternatively, an array reference of section specifications can be used:

pod2usage(-verbose => 99, -sections => [
  qw(DESCRIPTION DESCRIPTION/Introduction) ] );

This will print only the content of =head1 DESCRIPTION and the =head2 Introduction sections, but no other =head2, and no other =head1 either.

#-output handle

A reference to a filehandle, or the pathname of a file to which the usage message should be written. The default is \*STDERR unless the exit value is less than 2 (in which case the default is \*STDOUT).

#-input handle

A reference to a filehandle, or the pathname of a file from which the invoking script's pod documentation should be read. It defaults to the file indicated by $0 ($PROGRAM_NAME for users of English.pm).

If you are calling pod2usage() from a module and want to display that module's POD, you can use this:

use Pod::Find qw(pod_where);
pod2usage( -input => pod_where({-inc => 1}, __PACKAGE__) );

#-pathlist string

A list of directory paths. If the input file does not exist, then it will be searched for in the given directory list (in the order the directories appear in the list). It defaults to the list of directories implied by $ENV{PATH}. The list may be specified either by a reference to an array, or by a string of directory paths which use the same path separator as $ENV{PATH} on your system (e.g., : for Unix, ; for MSWin32 and DOS).

#-noperldoc

By default, Pod::Usage will call perldoc when -verbose >= 2 is specified. This does not work well e.g. if the script was packed with PAR. This option suppresses the external call to perldoc and uses the simple text formatter (Pod::Text) to output the POD.

#-perlcmd

By default, Pod::Usage will call perldoc when -verbose >= 2 is specified. In case of special or unusual Perl installations, this option may be used to supply the path to a perl executable which should run perldoc.

#-perldoc path-to-perldoc

By default, Pod::Usage will call perldoc when -verbose >= 2 is specified. In case perldoc is not installed where the perl interpreter thinks it is (see Config), the -perldoc option may be used to supply the correct path to perldoc.

#