内容

• 名称
• 概要
• 参数
  • 格式化基类
  • 直通选项
• 描述
  • 脚本
• 示例
  • 推荐用法
• 注意事项
• 支持
• 作者
• 许可证
• 致谢
• 参见

#名称

Pod::Usage - 提取 POD 文档并显示使用信息

#概要

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 );

#参数

pod2usage 应该被赋予一个参数，或者一个与关联数组（“哈希”）相对应的参数列表。当给出一个参数时，它应该对应于以下内容之一

• 包含要打印的在打印使用信息之前的消息文本的字符串

• 对应于所需退出状态的数值

• 对哈希的引用

如果给出了多个参数，则整个参数列表被假定为一个哈希。如果提供了一个哈希（作为引用或列表），它应该包含一个或多个具有以下键的元素

#-message 字符串

#-msg string

在打印程序的使用说明之前立即打印的消息文本。

#-exitval value

要传递给exit()函数的期望退出状态。这应该是一个整数，或者字符串NOEXIT表示应该简单地返回控制权而不终止调用进程。

#-verbose value

打印使用说明时使用的期望“详细程度”级别。如果值为 0，则仅打印 pod 文档的“概要”和/或“用法”部分。如果值为 1，则打印“概要”和/或“用法”部分，以及任何标题为“选项”、“参数”或“选项和参数”的部分。如果对应值为 2 或更大，则打印整个手册页，如果可用，则使用 perldoc；否则使用 Pod::Text 进行格式化。为了更好的可读性，所有大写标题都将转换为小写，例如 SYNOPSIS => Synopsis。

特殊的详细程度级别 99 需要同时指定 -sections 参数；然后提取并打印这些部分。

#-sections spec

有两种方法可以指定选择。要么是一个字符串（标量），表示当 -verbose 设置为 99 时要打印的部分的选择正则表达式，例如

"NAME|SYNOPSIS|DESCRIPTION|VERSION"

使用上面的正则表达式，将显示任何给定 =head1 标题之后（包括）的所有内容。可以将输出限制为特定子部分，例如

"DESCRIPTION/Algorithm"

这将仅输出 =head1 DESCRIPTION 部分中的 =head2 Algorithm 标题和内容。正则表达式绑定比部分分隔符更强，例如

"DESCRIPTION|OPTIONS|ENVIRONMENT/Caveats"

将打印任何三个 =head1 部分中的任何 =head2 Caveats 部分（仅）。

或者，可以使用部分规范的数组引用

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

这将只打印=head1 DESCRIPTION和=head2 Introduction部分的内容，但不会打印其他=head2或=head1部分。

#-output handle

指向文件句柄的引用，或用于写入使用说明消息的文件的路径名。默认情况下为\*STDERR，除非退出值为小于 2（在这种情况下，默认值为\*STDOUT）。

#-input handle

指向文件句柄的引用，或用于读取调用脚本的 pod 文档的文件的路径名。默认情况下为$0（对于 English.pm 的用户，则为$PROGRAM_NAME）指示的文件。

如果您从模块中调用pod2usage()并希望显示该模块的 POD，您可以使用此方法

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

#-pathlist string

目录路径列表。如果输入文件不存在，则将在给定的目录列表中搜索它（按照目录在列表中出现的顺序）。默认情况下为$ENV{PATH}隐含的目录列表。该列表可以通过指向数组的引用来指定，也可以通过使用与系统上的$ENV{PATH}相同的路径分隔符的目录路径字符串来指定（例如，对于 Unix 为:，对于 MSWin32 和 DOS 为;）。

#-noperldoc

默认情况下，Pod::Usage 会在指定 -verbose >= 2 时调用perldoc。这在脚本使用PAR打包时效果不佳。此选项会抑制对perldoc的外部调用，并使用简单的文本格式化程序（Pod::Text）来输出 POD。

#-perlcmd

默认情况下，Pod::Usage 会在指定 -verbose >= 2 时调用perldoc。在特殊或非标准的 Perl 安装情况下，可以使用此选项提供应运行perldoc的perl可执行文件的路径。

#-perldoc path-to-perldoc

默认情况下，Pod::Usage 会在指定 -verbose >= 2 时调用perldoc。如果perldoc未安装在perl解释器认为的位置（请参阅Config），则可以使用 -perldoc 选项提供perldoc的正确路径。

#-perldocopt string

默认情况下，Pod::Usage 会在指定 -verbose >= 2 时调用 perldoc。可以使用此选项为 perldoc 提供选项。字符串可以包含多个用空格分隔的选项。

#格式化基类

默认文本格式化程序是 Pod::Text。可以通过在加载 Pod::Usage 之前 预先设置 $Pod::Usage::Formatter 来定义 Pod::Usage 的基类，例如：

BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
use Pod::Usage qw(pod2usage);

Pod::Usage 使用 Pod::Simple 的 _handle_element_end() 方法来实现节选择，并且在 verbosity < 2 的情况下，它会将所有大写标题转换为首字母大写，其余字母小写，并在标题末尾添加冒号/换行符，以提高可读性。verbosity = 99 也是如此。

#传递选项

以下选项将传递给底层文本格式化程序。有关更多信息，请参阅这些模块的手册页。

alt code indent loose margin quotes sentence stderr utf8 width

#DESCRIPTION

pod2usage 将为调用脚本打印使用信息（使用其嵌入的 pod 文档），然后使用所需的退出状态退出脚本。打印的使用信息可能具有三种“详细程度”级别之一：如果详细程度为 0，则仅打印概要。如果详细程度为 1，则将打印概要以及命令行选项和参数的描述（如果存在）。如果详细程度为 2，则将打印整个手册页。

除非明确指定，否则退出状态、详细程度和要使用的输出流的默认值将按如下方式确定

• 如果既没有指定退出状态也没有指定详细程度，则默认使用退出状态 2 和详细程度 0。

• 如果指定了退出状态但没有指定详细程度，则如果退出状态小于 2，则详细程度将默认为 1，否则将默认为 0。

• 如果没有指定退出状态但给出了详细程度，则如果详细程度为 0，则退出状态将默认为 2，否则将默认为 1。

• 如果使用的退出状态小于 2，则输出将打印到 STDOUT。否则，输出将打印到 STDERR。

虽然以上内容乍看起来可能有点令人困惑，但在大多数情况下它通常会“做正确的事”。这种对要使用的默认值的确定是基于以下典型的 Unix 约定。

• 退出状态为 0 表示“成功”。例如，如果两个文件的内容相同，则 diff(1) 将以状态 0 退出。

• 退出状态为 1 表示可能异常，但非缺陷的程序终止。例如，如果 grep(1) 没有找到给定正则表达式的匹配行，则它将以状态 1 退出。

• 退出状态为 2 或更大表示致命错误。例如，如果您在命令行上指定了非法（未知）选项，则 ls(1) 将以状态 2 退出。

• 由于错误的命令行语法而发出的使用消息应发送到 STDERR。但是，由于显式请求打印使用情况（例如在命令行上指定 -help）而发出的使用消息应发送到 STDOUT，以防用户希望将输出管道到分页器（例如 more(1)）。

• 如果用户显式请求程序使用情况，则在发出用户请求的使用消息后，通常希望以状态 1（而不是 0）退出。在这种情况下，最好提供更详细的程序使用情况说明。

pod2usage 不会强迫您遵守上述约定，但如果您没有明确告诉它这样做，它将在默认情况下使用它们。pod2usage() 能够接受单个数字或字符串，这使得它可以方便地用作一个看起来无害的错误消息处理函数。

use strict;
use Pod::Usage;
use Getopt::Long;

## Parse options
my %opt;
GetOptions(\%opt, "help|?", "man", "flag1")  ||  pod2usage(2);
pod2usage(1)  if ($opt{help});
pod2usage(-exitval => 0, -verbose => 2)  if ($opt{man});

## Check for too many filenames
pod2usage("$0: Too many files given.\n")  if (@ARGV > 1);

然而，一些用户可能会认为上述“表达经济”并不特别易读或一致，而可能会选择做一些更像以下内容的事情。

use strict;
use Pod::Usage qw(pod2usage);
use Getopt::Long qw(GetOptions);

## Parse options
my %opt;
GetOptions(\%opt, "help|?", "man", "flag1")  ||
  pod2usage(-verbose => 0);

pod2usage(-verbose => 1)  if ($opt{help});
pod2usage(-verbose => 2)  if ($opt{man});

## Check for too many filenames
pod2usage(-verbose => 2, -message => "$0: Too many files given.\n")
  if (@ARGV > 1);

与 Perl 中的所有事物一样，有多种方法可以做到这一点，而 pod2usage() 遵循这种理念。如果您有兴趣查看调用 pod2usage 的多种不同方法（虽然绝非详尽无遗），请参阅 "示例"。

#脚本

Pod::Usage 发行版附带一个脚本 pod2usage，它为 Pod::Usage 的功能提供了一个命令行界面。请参阅 pod2usage。

#示例

以下每个 pod2usage() 调用都将只将“概要”部分打印到 STDERR，并将以状态 2 退出。

pod2usage();

pod2usage(2);

pod2usage(-verbose => 0);

pod2usage(-exitval => 2);

pod2usage({-exitval => 2, -output => \*STDERR});

pod2usage({-verbose => 0, -output  => \*STDERR});

pod2usage(-exitval => 2, -verbose => 0);

pod2usage(-exitval => 2, -verbose => 0, -output => \*STDERR);

以下每个 pod2usage() 调用都将打印一条“语法错误。”的消息（后面跟一个换行符）到 STDERR，紧随其后是“概要”部分（也打印到 STDERR），并将以状态 2 退出。

pod2usage("Syntax error.");

pod2usage(-message => "Syntax error.", -verbose => 0);

pod2usage(-msg  => "Syntax error.", -exitval => 2);

pod2usage({-msg => "Syntax error.", -exitval => 2, -output => \*STDERR});

pod2usage({-msg => "Syntax error.", -verbose => 0, -output => \*STDERR});

pod2usage(-msg  => "Syntax error.", -exitval => 2, -verbose => 0);

pod2usage(-message => "Syntax error.",
          -exitval => 2,
          -verbose => 0,
          -output  => \*STDERR);

以下每个 pod2usage() 调用都会将“SYNOPSIS”部分以及任何“OPTIONS”和/或“ARGUMENTS”部分打印到 STDOUT，并以状态码 1 退出。

pod2usage(1);

pod2usage(-verbose => 1);

pod2usage(-exitval => 1);

pod2usage({-exitval => 1, -output => \*STDOUT});

pod2usage({-verbose => 1, -output => \*STDOUT});

pod2usage(-exitval => 1, -verbose => 1);

pod2usage(-exitval => 1, -verbose => 1, -output => \*STDOUT});

以下每个 pod2usage() 调用都会将整个手册页打印到 STDOUT，并以状态码 1 退出。

pod2usage(-verbose  => 2);

pod2usage({-verbose => 2, -output => \*STDOUT});

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

pod2usage({-exitval => 1, -verbose => 2, -output => \*STDOUT});

#推荐使用

大多数脚本在检测到命令行语法错误时，应该向 STDERR 打印某种类型的使用信息。它们还应该提供一个选项（通常是 -H 或 -help）来将（可能更详细的）使用信息打印到 STDOUT。一些脚本甚至可能希望提供一种将完整文档打印到 STDOUT 的方法（可能通过允许 -man 选项）。以下完整示例使用 Pod::Usage 与 Getopt::Long 结合来完成所有这些操作。

use strict;
use Getopt::Long qw(GetOptions);
use Pod::Usage qw(pod2usage);

my $man = 0;
my $help = 0;
## Parse options and print usage if there is a syntax error,
## or if usage was explicitly requested.
GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
pod2usage(1) if $help;
pod2usage(-verbose => 2) if $man;

## If no arguments were given, then allow STDIN to be used only
## if it's not connected to a terminal (otherwise print usage)
pod2usage("$0: No files given.")  if ((@ARGV == 0) && (-t STDIN));

__END__

=head1 NAME

sample - Using GetOpt::Long and Pod::Usage

=head1 SYNOPSIS

sample [options] [file ...]

 Options:
   -help            brief help message
   -man             full documentation

=head1 OPTIONS

=over 4

=item B<-help>

Print a brief help message and exits.

=item B<-man>

Prints the manual page and exits.

=back

=head1 DESCRIPTION

B<This program> will read the given input file(s) and do something
useful with the contents thereof.

=cut

#注意事项

默认情况下，pod2usage() 将使用 $0 作为 pod 输入文件的路径。不幸的是，并非所有运行 Perl 的系统都会正确设置 $0（尽管如果找不到 $0，pod2usage() 将搜索 $ENV{PATH} 或 -pathlist 选项指定的列表）。如果你的系统出现这种情况，你可能需要使用类似以下内容显式指定调用脚本的 pod 文档的路径。

pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs");

在病态情况下，如果脚本通过相对路径调用，并且脚本本身在调用 pod2usage 之前更改了当前工作目录（参见 "perlfunc 中的 chdir"），即使在健壮的平台上，Pod::Usage 也会失败。不要这样做。或者使用 FindBin 来定位脚本。

use FindBin;
pod2usage(-input => $FindBin::Bin . "/" . $FindBin::Script);

#支持

此模块在 GitHub 存储库中进行管理，https://github.com/Dual-Life/Pod-Usage。欢迎 fork 和贡献，或克隆并发送补丁！

请使用 https://github.com/Dual-Life/Pod-Usage/issues/new 提交错误报告。以前的工单系统，https://rt.cpan.org/Dist/Display.html?Queue=Pod-Usage，已弃用此软件包。

有关 POD 的更一般性问题或讨论，请发送到 [email protected] 邮件列表。发送空邮件到 [email protected] 订阅。

#作者

Marek Rouchal <[email protected]>

Nicolas R <[email protected]>

Brad Appleton <[email protected]>

基于 Tom Christiansen <[email protected]> 编写的 Pod::Text::pod2text() 代码。

#许可证

Pod::Usage（发行版）的许可条款与 Perl 相同。

#致谢

Nicolas R (ATOOMIC) 为创建 Github 仓库和现代化此包做出了贡献。

rjbs 为重构 Pod::Usage 以不再使用 Pod::Parser 做出了贡献。

Steven McDougall <[email protected]> 为帮助重写此手册页提供了帮助和耐心。

#参见

Pod::Usage 现在是一个独立的发行版，依赖于 Pod::Text，而 Pod::Text 又依赖于 Pod::Simple。

Pod::Perldoc，Getopt::Long，Pod::Find，FindBin，Pod::Text，Pod::Text::Termcap，Pod::Simple

Perldoc 浏览器由 Dan Book (DBOOK) 维护。如果您遇到网站本身、搜索或文档渲染方面的任何问题，请通过 GitHub 问题跟踪器 或 电子邮件 联系他。

Perl 文档由 Perl 5 移植者在 Perl 开发过程中维护。如果您遇到文档内容或格式方面的任何问题，请通过 Perl 问题跟踪器、邮件列表 或 IRC 联系他们。