目錄

名稱

Module::Metadata - 從 Perl 模組檔案收集套件和 POD 資訊

版本

版本 1.000037

語法

use Module::Metadata;

# information about a .pm file
my $info = Module::Metadata->new_from_file( $file );
my $version = $info->version;

# CPAN META 'provides' field for .pm files in a directory
my $provides = Module::Metadata->provides(
  dir => 'lib', version => 2
);

說明

此模組提供一種標準方式，透過（大多數）靜態分析和（一些）程式碼執行來收集有關 .pm 檔案的元資料。在決定模組版本時，會對 $VERSION 指派進行 eval，這是 CPAN 工具鏈中的傳統做法。

類別方法

new_from_file($filename, collect_pod => 1, decode_pod => 1)

根據檔案路徑建立一個 Module::Metadata 物件。如果檔案名稱不存在，則傳回未定義。

collect_pod 是個可選的布林值引數，用來決定是否收集 POD 資料並儲存以供參考。預設不會收集 POD 資料。POD 標題會永遠收集。

如果檔案以 UTF-8、UTF-16BE 或 UTF-16LE 位元組順序標記開頭，則在處理之前會略過它，且從 Perl 5.8 開始，也會適當地解碼檔案內容。

或者，如果設定了 decode_pod，它會根據 =encoding 宣告來解碼收集到的 pod 區段。

new_from_handle($handle, $filename, collect_pod => 1, decode_pod => 1)

這與 new_from_file 的運作方式相同，但可以將控制代碼提供為第一個引數。

請注意，沒有驗證來確認控制代碼是控制代碼或可以像控制代碼一樣運作的東西。傳遞非控制代碼的東西會在嘗試從其中讀取時導致例外。filename 引數是強制性的，否則會傳回未定義。

您有責任在 $handle 上設定解碼層（如果需要）。

new_from_module($module, collect_pod => 1, inc => \@dirs, decode_pod => 1)

根據模組或套件名稱建立一個 Module::Metadata 物件。如果找不到模組，則傳回未定義。

除了接受如上所述的 collect_pod 和 decode_pod 引數外，此方法還接受一個 inc 引數，它是用於搜尋模組的目錄陣列的參考。如果沒有提供任何目錄，預設值為 @INC。

如果包含模組的檔案以 UTF-8、UTF-16BE 或 UTF-16LE 位元組順序標記開頭，則在處理之前會略過它，且從 Perl 5.8 開始，也會適當地解碼檔案內容。

find_module_by_name($module, \@dirs)

根據模組或套件名稱傳回模組的路徑。可以將目錄清單作為可選參數傳遞，否則會搜尋 @INC。

可以作為物件或類別方法呼叫。

find_module_dir_by_name($module, \@dirs)

傳回 @dirs (或預設為 @INC) 中包含模組 $module 的項目。可以將目錄清單傳入作為選用參數，否則會搜尋 @INC。

可以作為物件或類別方法呼叫。

provides( %options )

這是 package_versions_from_directory 的便利包裝器，用於產生 CPAN META provides 資料結構。它採用鍵值對。有效的選項鍵包括

version (必填)

指定應使用哪個版本的 CPAN::Meta::Spec 作為 provides 輸出的格式。目前僅支援「1.4」和「2」（其格式相同）。隨著 provides 定義的變更，這可能會在未來變更。

version 選項是必填。如果省略或給出不支援的版本，則 provides 會擲回錯誤。

dir

遞迴搜尋 .pm 檔案的目錄。不得與 files 一起指定。

files

要檢查的檔案陣列參考。不得與 dir 一起指定。

prefix

字串，預先加到結果輸出的 file 欄位。這預設為 lib，這是大多數 CPAN 發行版的常見情況，其 .pm 檔案位於 lib 中。此選項可確保 META 資訊具有正確的相對路徑，即使 dir 或 files 引數是絕對路徑或具有來自發行版根目錄以外位置的相對路徑。

例如，給定 dir 為「lib」和 prefix 為「lib」，回傳值是下列形式的雜湊

{
  'Package::Name' => {
    version => '0.123',
    file => 'lib/Package/Name.pm'
  },
  'OtherPackage::Name' => ...
}

package_versions_from_directory($dir, \@files?)

掃描 $dir 以尋找 .pm 檔案（除非給定 @files，這種情況下會在 $dir 中尋找這些檔案） - 並讀取每個檔案的套件和版本，傳回下列形式的雜湊

{
  'Package::Name' => {
    version => '0.123',
    file => 'Package/Name.pm'
  },
  'OtherPackage::Name' => ...
}

DB 和 main 套件總是會被省略，任何在命名空間中具有前導底線的「私人」套件也是如此（例如 Foo::_private）

請注意，如果指定了 $dir，則檔案路徑相對於 $dir。這不得直接用於 CPAN META provides。請改用 provides 方法。

log_info (internal)

在內部用於執行記錄；如果已載入 Log::Contextual，則從 Log::Contextual 匯入，否則僅呼叫 warn。

OBJECT 方法

name()

傳回此模組所表示的套件名稱。如果有多個套件，它會根據檔案名稱進行最佳猜測。如果是腳本（即不是 *.pm），則套件名稱為「main」。

version($package)

傳回套件的 $VERSION 變數所定義的版本，如果未提供任何參數，則會傳回 name 方法所傳回的版本。如果給定套件名稱，則會嘗試傳回該套件的版本（如果在檔案中指定的話）。

filename()

傳回檔案的絕對路徑。請注意，此檔案實際上可能尚未存在於磁碟上，例如，如果模組是由記憶體中的檔案處理程式讀取的。

packages_inside()

傳回套件清單。請注意：這是已發現（或假設，例如 main）的套件原始清單。它不會過濾 DB、main 或私人套件，就像 provides 方法所做的那樣。無效的套件名稱不會傳回，例如「Foo:Bar」。會傳回奇怪但有效的套件名稱，例如「Foo::Bar::」，並由呼叫者決定如何處理。

pod_inside()

傳回 POD 區段清單。

contains_pod()

如果檔案中有任何 POD，則傳回 true。

pod($section)

傳回指定區段中的 POD 資料。

is_indexable($package) 或 is_indexable()

自 1.000020 版起提供。

傳回布林值，表示套件（如果提供）或任何套件（否則）是否有資格由 Perl 作者上傳伺服器 PAUSE 編製索引。請注意，這只會檢查有效的 package 宣告，而不會考慮任何所有權資訊。

支援

錯誤回報可以透過 RT 錯誤追蹤器 (或 bug-Module-Metadata@rt.cpan.org) 提交。

此套件也有提供使用者郵件列表，網址為 http://lists.perl.org/list/cpan-workers.html。

此套件也有提供使用者 IRC 頻道，網址為 #toolchain on irc.perl.org。

作者

原始程式碼來自 Ken Williams <kwilliams@cpan.org> 和 Randy W. Sims <RandyS@ThePierianSpring.org> 的 Module::Build::ModuleInfo。

由 Matt S Trout (mst) <mst@shadowcat.co.uk> 以 David Golden (xdg) <dagolden@cpan.org> 的協助，以 Module::Metadata 發布。

貢獻者

版權與授權

原始程式碼版權所有 (c) 2001-2011 Ken Williams。其他程式碼版權所有 (c) 2010-2011 Matt Trout 和 David Golden。保留所有權利。

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