目錄

• 名稱
• 概要
• 參數
  • 格式化基類
  • 傳遞選項
• 描述
  • 腳本
• 示例
  • 推薦使用
• 注意事項
• 支持
• 作者
• 許可證
• 致謝
• 參見

#名稱

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 字符串

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

#-exitval value

傳遞給 exit() 函數的期望退出狀態。這應該是一個整數，否則字符串 NOEXIT 表示控制應該簡單返回而不終止調用進程。

#-verbose value

在打印用法消息時要使用的所需的“冗長性”級別。如果值為0，則僅打印 pod 文檔的“SYNOPSIS”和/或“USAGE”部分。如果值為1，則打印“SYNOPSIS”和/或“USAGE”部分，以及任何標題為“OPTIONS”，“ARGUMENTS”或“OPTIONS AND ARGUMENTS”的部分。如果相應的值為2或更高，則打印整個 man 頁面，如果可用，使用 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

一個文件句柄的引用，或者應該將用法消息寫入的文件的路徑名。除非退出值小於 2（在這種情況下默認為 \*STDOUT），否則默認為 \*STDERR。

#-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

默認情況下，當指定了 -verbose >= 2 時，Pod::Usage 將調用perldoc。例如，如果腳本是使用PAR打包的，這不起作用。此選項抑制對perldoc的外部調用，並使用簡單文本格式化程序（Pod::Text）輸出 POD。

#-perlcmd

默認情況下，當指定了 -verbose >= 2 時，Pod::Usage 將調用perldoc。在特殊或不尋常的 Perl 安裝情況下，可以使用此選項來提供運行perldoc的perl可執行文件的路徑。

#-perldoc path-to-perldoc

默認情況下，當指定了 -verbose >= 2 時，Pod::Usage 將調用perldoc。如果perldoc未安裝在perl解釋器認為的位置（參見Config），則可以使用 -perldoc 選項來提供正確的perldoc路徑。

#-perldocopt string

默認情況下，當指定了 -verbose >= 2 時，Pod::Usage 將調用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() 方法來實現部分選擇，在冗長度小於 2 的情況下，它將全部大寫的標題轉換為首字母大寫並將其餘部分轉換為小寫，並在標題末尾添加冒號/換行符以提高可讀性。冗長度等於 99 時也是如此。

#過渡選項

以下選項將傳遞給底層文本格式化程序。有關這些模塊的手冊頁面的更多信息，請參閱它們。

alt code indent loose margin quotes sentence stderr utf8 width

#描述

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 的方式（雖然絕非盡善盡美），請參閱 "EXAMPLES"。

#腳本

Pod::Usage 分發了一個名為 pod2usage 的腳本，該腳本提供了對 Pod::Usage 功能的命令行介面。參見 pod2usage。

#範例

以下每個對 pod2usage() 的調用將僅將「SYNOPSIS」部分列印到 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 列印一條 "Syntax error." 的訊息（後跟一個換行符號），然後立即將僅「SYNOPSIS」部分列印到 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 之前更改了當前工作目錄（請參閱 "chdir" in perlfunc），即使在強大的平台上，Pod::Usage 也會失敗。請不要這樣做。或者使用 FindBin 來定位腳本

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

#支援

此模塊在 GitHub 存儲庫中管理，https://github.com/Dual-Life/Pod-Usage 歡迎分叉並貢獻，或克隆並發送補丁！

請使用 https://github.com/Dual-Life/Pod-Usage/issues/new 提交錯誤報告。對於這個包，先前的票務系統，https://rt.cpan.org/Dist/Display.html?Queue=Pod-Usage 已經不再使用。

有關 POD 的更一般的問題或討論應發送到 pod-people@perl.org 郵件列表。發送一封空郵件到 pod-people-subscribe@perl.org 以訂閱。

#作者

Marek Rouchal <marekr@cpan.org>

Nicolas R <nicolas@atoomic.org>

Brad Appleton <bradapp@enteract.com>

基於 Tom Christiansen <tchrist@mox.perl.com> 編寫的 Pod::Text::pod2text() 代碼

#許可協議

Pod::Usage（該分發）的許可條款與 Perl 的許可條款相同。

#致謝

Nicolas R（ATOOMIC）設置了 Github 存儲庫並現代化了這個包。

rjbs 對 Pod::Usage 進行了重構，不再使用 Pod::Parser。

Steven McDougall <swmcd@world.std.com> 幫助並耐心重寫了這個 man 頁。

#另見

Pod::Usage 現在是一個獨立的分發，依賴於 Pod::Text，而 Pod::Text 又依賴於 Pod::Simple。

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

Perldoc Browser由Dan Book（DBOOK）維護。如對網站本身、搜尋或文件渲染等任何問題，請透過GitHub問題跟蹤器或電子郵件與他聯繫。

Perl文檔由Perl 5 Porters負責開發Perl的文檔。如對文檔內容或格式等任何問題，請透過Perl問題跟蹤器、郵件列表或IRC與他們聯繫。