內容

名稱

Pod::Simple::Search - 在目錄樹中尋找 POD 文件

語法

use Pod::Simple::Search;
my $name2path = Pod::Simple::Search->new->limit_glob('LWP::*')->survey;
print "Looky see what I found: ",
  join(' ', sort keys %$name2path), "\n";

print "LWPUA docs = ",
  Pod::Simple::Search->new->find('LWP::UserAgent') || "?",
  "\n";

說明

Pod::Simple::Search 是用於執行 Pod 檔案搜尋的類別。此類別的物件有數個屬性（大部分是控制搜尋選項的選項），以及一些根據這些屬性進行搜尋的方法。

使用此類別的方法是建立此類別的新物件，設定任何選項，然後呼叫其中一個搜尋選項（可能是 survey 或 find）。以下各節討論執行所有這些操作的語法。

建構函式

此類別提供一個建構函式，稱為 new。它不帶任何參數

use Pod::Simple::Search;
my $search = Pod::Simple::Search->new;

存取器

此類別定義了數個方法，用於設定（偶爾也會讀取）物件的內容。除了本節末尾討論的兩個例外，這些屬性僅用於控制搜尋執行的方式。

請注意，當您呼叫它們為 $self->whatever(value) 時，這些每個都會傳回 $self。這樣您可以串聯設定屬性的呼叫，如下所示

my $name2path =
  Pod::Simple::Search->new
  -> inc(0) -> verbose(1) -> callback(\&blab)
  ->survey(@there);

...這會像您執行以下動作一樣運作

my $search = Pod::Simple::Search->new;
$search->inc(0);
$search->verbose(1);
$search->callback(\&blab);
my $name2path = $search->survey(@there);
$search->inc( true-or-false );

此屬性（如果設定為 true 值）表示搜尋應該隱式新增 perl 的 @INC 路徑。這會自動考量在 PERL5LIB 環境中指定的路徑，因為 Perl 解譯器本身會將其置於 @INC 之前。此屬性的預設值為 TRUE。如果您只想搜尋特定目錄，請在呼叫 $inc->survey 或 $inc->find 之前設定 $self->inc(0)。

$search->verbose( nonnegative-number );

此屬性（如果設定為非零正值）會讓搜尋在執行時透過 warn 輸出（關於它們在執行什麼）的注意事項。此選項可能有助於除錯與 pod 相關的模組。此屬性的預設值為零，表示不會產生 warn 訊息。（將 verbose 設定為 1 會開啟一些訊息，而將其設定為 2 會開啟更多訊息，亦即，讓以下搜尋比 1 讓它們更冗長。）

$search->limit_glob( some-glob-string );

此選項表示您只想將結果限制為其 pod 名稱符合所提供 glob/萬用字元表達式的項目。例如，您可以將搜尋限制為僅「LWP::*」，以僅搜尋以「LWP::*」開頭的模組（但不包括「LWP」模組本身）；或者您可以將搜尋限制為「LW*」，以僅查看（完整）名稱以「LW」開頭的模組；或者您可以搜尋「*Find*」，以搜尋完整名稱中某處有「Find」的所有模組。（您也可以在 glob 表達式中使用「?」；因此「DB?」會符合「DBI」和「DBD」。）

$search->callback( \&some_routine );

此屬性表示，每當此搜尋看到符合的 Pod 檔案時，它應呼叫此回呼常式。常式會使用兩個參數呼叫：目前的檔案檔案規格，以及其 pod 名稱。（例如：("/etc/perljunk/File/Crunk.pm", "File::Crunk") 會在 @_ 中。）

回呼常式的傳回值不用於任何用途。

此屬性的預設值為 false，表示不會呼叫任何回呼。

$search->laborious( true-or-false );

除非您將此屬性設定為 true 值，否則 Pod::Search 會套用 Perl 特定的啟發法，以快速找到正確的模組 POD。此屬性的預設值為 false。您通常不需要將其設定為 true。

具體來說：開啟此選項會停用啟發法，以僅查看具有 Perl 類似副檔名的檔案，省略數字子目錄，但與目前的 Perl 解譯器版本 ID 不相符，抑制 site_perl 作為模組階層名稱，等等。

$search->recurse( true-or-false );

除非您將此屬性設定為 false 值，否則 Pod::Search 會遞迴進入搜尋目錄的子目錄。

$search->shadows( true-or-false );

除非您將此屬性設定為 true 值，否則 Pod::Simple::Search 在查看指定目錄時，只會考慮給定模組名稱的第一個檔案；亦即，如果在此搜尋中，Pod::Simple::Search 已看到 somepathdir/Foo/Bar.pm，則在該搜尋中，它不會費心查看 somelaterpathdir/Foo/Bar.pm，因為該檔案只是一個「影子」。但如果您開啟 $self->shadows(1)，則也會檢查這些「影子」檔案，並在 pathname2podname 傳回雜湊中記錄下來。

此屬性的預設值為 false；通常您不需要開啟它。

$search->is_case_insensitive( true-or-false );

Pod::Simple::Search 會根據找到類別檔案的底層檔案系統預設內部假設是否區分大小寫。

如果判定為不區分大小寫，在 survey() 期間可能會略過與已見名稱相等的 pod 檔案/模組，忽略大小寫。

不過，不同目錄中可能會有故意使用相同名稱的個別檔案，只在大小寫上有所不同，應該予以回報。因此，您可以透過將此設定設為 true 或 false 來強制執行行為。

$search->limit_re( some-regxp );

設定這個屬性（為正規表示式的值）表示您只想將結果限制為 pod 名稱符合所提供正規表示式的項目。通常不需要這個選項，而會改用更有效率的 limit_glob 屬性。

$search->dir_prefix( some-string-value );

將這個屬性設定為字串值表示搜尋應該從指定的子目錄名稱開始（例如「Pod」或「File::Find」，也可以表示為「File/Find」）。例如，搜尋選項 $search->limit_glob("File::Find::R*") 與搜尋選項 $search->limit_re("^File::Find::R") -> dir_prefix("File::Find") 的組合相同。

通常您不需要知道 dir_prefix 選項，但我將其包含在內，以防對某人有幫助。

（在實作上，使用 limit_glob 搜尋會設定 limit_re，通常也會設定 dir_prefix。）

$search->progress( some-progress-object );

如果您為這個屬性設定值，預期這個值會是一個物件（可能屬於您定義的類別），具有 reach 方法和 done 方法。這是為了在搜尋期間回報進度，如果您不想要使用簡單的回呼。

通常您不需要知道 progress 選項，但我將其包含在內，以防對某人有幫助。

在搜尋進行期間，會像這樣呼叫進度物件的 reach 和 done 方法

# Every time a file is being scanned for pod:
$progress->reach($count, "Scanning $file");   ++$count;

# And then at the end of the search:
$progress->done("Noted $count Pod files total");

在內部，我們通常會將此設定為 Pod::Simple::Progress 類別的物件。那個類別可能沒有文件，但您可能想看看它的原始碼。

$name2path = $self->name2path;

此屬性並非搜尋參數，但用於回報 survey 方法的結果，如同下一段所討論的。

$path2name = $self->path2name;

此屬性並非搜尋參數，但用於回報 survey 方法的結果，如同下一段所討論的。

主要搜尋方法

一旦你設定好任何你想要的選項（如果有），你可以繼續使用以下方法以特定方式搜尋 Pod 檔案。

$search->survey( @directories )

方法 survey 在給定的檔案和/或目錄集中搜尋 POD 文件。這會根據上面存取器設定的各種選項執行搜尋。（例如，如果 inc 屬性開啟，預設為開啟，則 perl @INC 目錄會隱含地加入到你指定的目錄清單（如果有）中。）

survey 的回傳值是兩個雜湊

name2path

一個雜湊，從每個 pod 名稱對應到檔案規格（例如「Stuff::Thing」=>「/whatever/plib/Stuff/Thing.pm」）

path2name

一個雜湊，從每個 Pod 檔案規格對應到其 pod 名稱（例如「/whatever/plib/Stuff/Thing.pm」=>「Stuff::Thing」）

除了將這些雜湊儲存為雜湊參考屬性 name2path 和 path2name，呼叫此函數也會回傳這些雜湊參考。在清單內容中，$search->survey 的回傳值是清單 (\%name2path, \%path2name)。在純量內容中，回傳值是 \%name2path。或者你也可以在空內容中呼叫它。

無論呼叫內容為何，呼叫 survey 會將其結果儲存在其 name2path 和 path2name 屬性中。

例如，在 $HOME/perl5lib 中搜尋時，檔案 $HOME/perl5lib/MyModule.pm 會取得 POD 名稱 MyModule，而 $HOME/perl5lib/Myclass/Subclass.pm 會是 Myclass::Subclass。名稱資訊可用於 POD 轉譯器。

只會找到包含至少一個有效 POD 指令的文字檔案。

在詳細模式中，如果找到影子（例如，找到多個具有相同 POD 名稱的 POD 檔案，例如不同目錄中的 CPAN.pm），會印出警告。這通常表示 @INC 搜尋路徑中有模組重複出現，偶爾會無意發生（但通常只是使用者路徑目錄具有比系統一般路徑目錄更新的版本）。

此引數的選項是遞迴搜尋的目錄或檔案清單。（通常你不會指定檔案，只會指定目錄。）或者你也可以只指定一個空清單，就像在 $name2path 中；預設開啟 inc 選項。

檔案的 POD 名稱是純粹的基本名稱，移除任何 Perl 類型的副檔名（.pm、.pl、.pod），並將路徑分隔符號替換為 ::。

呼叫 Pod::Simple::Search->search(...) 是 Pod::Simple::Search->new->search(...) 的簡寫。也就是說，會使用具有預設屬性值的拋棄式物件。

$search->simplify_name( $str )

方法 simplify_name 等同於 basename，但也會移除 Perl 類似延伸檔 (.pm、.pl、.pod) 和延伸檔，例如 Win32 和 OS/2 上的 .bat、.cmd，或 VMS 上的 .com。

$search->find( $pod )

$search->find( $pod, @search_dirs )

傳回 Pod 檔案的位置，給定 Pod/模組/指令碼名稱 (例如「Foo::Bar」或「perlvar」或「perldoc」)，以及要尋找的檔案/目錄概念。它會根據上述存取器設定的各種選項進行搜尋。(例如，如果 inc 屬性開啟 (預設開啟)，則 perl @INC 目錄會隱式新增至您指定的目錄清單 (如果有)。)

這會傳回檔案第一次出現的完整路徑。套件名稱 (例如「A::B」) 會自動轉換為所選目錄中的目錄名稱。此外，'.pm'、'.pl' 和 '.pod' 會自動附加至搜尋，視需要而定。(因此，例如，在 Unix 下，「A::B」會轉換為「somedir/A/B.pm」、「somedir/A/B.pod」或「somedir/A/B.pl」，視情況而定。)

如果找不到此類 Pod 檔案，此方法會傳回未定義。

如果任何給定的搜尋目錄包含 pod/ 子目錄，則會搜尋該目錄。(例如，這就是我們設法找到 perlfunc 的方式，它通常位於大多數 Perl dist 中的 pod/perlfunc 中。)

verbose 和 inc 屬性會影響此搜尋的行為；特別是 inc，如果為 true，會將 @INC 和 $Config::Config{'scriptdir'} 新增至要搜尋的目錄清單中。

通常只會說 $filename = Pod::Simple::Search-> new ->find("perlvar")，以便只搜尋 @INC (以及 scriptdir) 目錄。(這是因為 inc 屬性預設為 true。)

呼叫 Pod::Simple::Search->find(...) 是 Pod::Simple::Search->new->find(...) 的簡寫。也就是說，會使用具有預設屬性值的拋棄式物件。

$self->contains_pod( $file )

如果提供的檔案名稱 (非 POD 模組) 包含一些 Pod 文件，則傳回 true。

支援

有關 POD 和 Pod::Simple 的問題或討論應寄送至 pod-people@perl.org 郵件清單。寄送空白電子郵件至 pod-people-subscribe@perl.org 以訂閱。

此模組在開放的 GitHub 存放庫中管理，https://github.com/perl-pod/pod-simple/。歡迎分岔和貢獻，或複製 git://github.com/perl-pod/pod-simple.git 並傳送修補程式！

歡迎針對 Pod::Simple 提出修補程式。請將錯誤報告寄送至 <bug-pod-simple@rt.cpan.org>。

著作權和免責聲明

著作權所有 (c) 2002 Sean M. Burke。

此函式庫為免費軟體；您可以在與 Perl 相同的條款下重新散布或修改它。

此程式散布的目的是希望它對您有幫助，但沒有任何擔保；甚至沒有對特定目的的適售性或適用性的默示擔保。

作者

Pod::Simple 是由 Sean M. Burke <sburke@cpan.org> 建立的，並借用 Marek Rouchal 的 Pod::Find 程式碼，而該程式碼又大量借用了 Nick Ing-Simmons 的 PodToHtml 程式碼。

但別去煩他，他已經退休了。

Pod::Simple 由下列人員維護：