目錄

名稱

CPAN::Meta - CPAN dist 的發行說明資料

版本

版本 2.150010

語法

use v5.10;
use strict;
use warnings;
use CPAN::Meta;
use Module::Load;

my $meta = CPAN::Meta->load_file('META.json');

printf "testing requirements for %s version %s\n",
$meta->name,
$meta->version;

my $prereqs = $meta->effective_prereqs;

for my $phase ( qw/configure runtime build test/ ) {
    say "Requirements for $phase:";
    my $reqs = $prereqs->requirements_for($phase, "requires");
    for my $module ( sort $reqs->required_modules ) {
        my $status;
        if ( eval { load $module unless $module eq 'perl'; 1 } ) {
            my $version = $module eq 'perl' ? $] : $module->VERSION;
            $status = $reqs->accepts_module($module, $version)
                    ? "$version ok" : "$version not ok";
        } else {
            $status = "missing"
        };
        say "  $module ($status)";
    }
}

說明

釋出至 CPAN 的軟體發行包含一個 META.json，或對於較舊的發行，META.yml，其中說明發行、其內容，以及建置和安裝發行的需求。儲存在 META.json 檔案中的資料結構說明於 CPAN::Meta::Spec。

CPAN::Meta 提供一個簡單的類別來表示此發行說明資料 (或 distmeta)，以及一些有用的方法來查詢該資料。

下列文件僅針對 CPAN::Meta 物件的方法。有關個別欄位意義的資訊，請參閱規格。

方法

new

my $meta = CPAN::Meta->new($distmeta_struct, \%options);

傳回有效的 CPAN::Meta 物件，或是在提供的元資料雜湊參考驗證失敗時執行 die。如果舊格式的元資料驗證通過原始聲明的規格，將會轉換為版本 2。

它會採用選用的選項雜湊。有效的選項包括

create

my $meta = CPAN::Meta->create($distmeta_struct, \%options);

這與 new() 相同，但如果未提供，將會產生 generated_by 和 meta-spec 欄位。這表示元資料結構假設會遵循最新的 CPAN::Meta::Spec。

load_file

my $meta = CPAN::Meta->load_file($distmeta_file, \%options);

給定包含元資料的檔案路徑名稱，這會根據檔案字尾反序列化檔案，並建構新的 CPAN::Meta 物件，就像 new() 一樣。如果反序列化的版本驗證通過聲明的規格版本失敗，它將會執行 die。

它採用與 new() 相同的選項，但 lazy_validation 預設為 true。

load_yaml_string

my $meta = CPAN::Meta->load_yaml_string($yaml, \%options);

這個方法使用給定 YAML 字串中的第一個文件傳回新的 CPAN::Meta 物件。在其他方面，它與 load_file() 相同。

load_json_string

my $meta = CPAN::Meta->load_json_string($json, \%options);

這個方法使用給定 JSON 字串表示的結構傳回新的 CPAN::Meta 物件。在其他方面，它與 load_file() 相同。

load_string

my $meta = CPAN::Meta->load_string($string, \%options);

如果您不知道字串是否包含 YAML 或 JSON，這個方法將會使用 Parse::CPAN::Meta 猜測。在其他方面，它與 load_file() 相同。

save

$meta->save($distmeta_file, \%options);

將物件序列化為 JSON 並寫入給定的檔案。唯一的有效選項是 version，預設為 '2'。在 Perl 5.8.1 或更新版本中，檔案會以 UTF-8 編碼儲存。

對於 version 2（或更高版本），檔案名稱應以 '.json' 結尾。 JSON::PP 是預設的 JSON 後端。使用其他 JSON 後端需要 JSON 2.5 或更新版本，而且您必須將 $ENV{PERL_JSON_BACKEND} 設定為受支援的替代後端，例如 JSON::XS。

對於小於 2 的版本，檔案名稱應以「.yml」結尾。CPAN::Meta::Converter 用於產生較舊的元資料結構，並序列化為 YAML。CPAN::Meta::YAML 是預設的 YAML 後端。你可以將 $ENV{PERL_YAML_BACKEND} 設定為支援的替代後端，不過由於 CPAN 上的 YAML 剖析器之間有細微的不相容性，因此不建議這麼做。

meta_spec_version

此方法傳回 distmeta 結構中 meta_spec 項目中的版本部分。等同於

$meta->meta_spec->{version};

effective_prereqs

my $prereqs = $meta->effective_prereqs;

my $prereqs = $meta->effective_prereqs( \@feature_identifiers );

此方法傳回一個 CPAN::Meta::Prereqs 物件，描述散佈的全部先決條件。如果提供功能識別碼的陣列參考，則在傳回 CPAN::Meta::Prereqs 物件之前，會將已識別功能的先決條件與散佈的核心先決條件合併在一起。

should_index_file

... if $meta->should_index_file( $filename );

如果應該索引指定的檔案，此方法會傳回 true。它會透過檢查 distmeta 結構的 no_index 屬性中的 file 和 directory 鍵來決定。請注意，版本格式和 release_status 都不會被考慮。

$filename 應以 unix 格式提供。

should_index_package

... if $meta->should_index_package( $package );

如果應該索引指定的套件，此方法會傳回 true。它會透過檢查 distmeta 結構的 no_index 屬性中的 package 和 namespace 鍵來決定。請注意，版本格式和 release_status 都不會被考慮。

features

my @feature_objects = $meta->features;

此方法傳回 CPAN::Meta::Feature 物件的清單，每個物件代表散佈的元資料所描述的一個選用功能。

feature

my $feature_object = $meta->feature( $identifier );

此方法傳回具有指定識別碼的選用功能的 CPAN::Meta::Feature 物件。如果沒有具有該識別碼的功能，則會引發例外狀況。

as_struct

my $copy = $meta->as_struct( \%options );

此方法傳回物件的元資料的深度拷貝，作為未加祝福的雜湊參考。它需要一個選用的選項雜湊參考。如果雜湊參考包含 version 參數，則拷貝的元資料會轉換為該規格的版本，然後傳回。例如

my $old_spec = $meta->as_struct( {version => "1.4"} );

as_string

my $string = $meta->as_string( \%options );

此方法回傳一個序列化物件的元資料副本，以字元串表示。（字串並未使用 UTF-8 編碼。）它會採用一個選用的選項雜湊。如果雜湊包含 version 參數，複製的元資料將會轉換為該規格版本並回傳。例如

my $string = $meta->as_string( {version => "1.4"} );

對於大於或等於 2 的 version，字串將會以 JSON 序列化。對於小於 2 的 version，字串將會以 YAML 序列化。在兩種情況下，都會遵循與 save() 方法相同的規則，以選擇序列化後端。

序列化的結構將會包含一個 x_serialization_backend 項目，提供用於序列化的套件和版本。給定 $meta 物件中的任何現有金鑰都將會被覆寫。

字串資料

下列方法回傳單一值，也就是 distmeta 結構中對應項目的值。值應該是未定義或字串。

清單資料

這些方法回傳字串值的清單，可能在 distmeta 結構中表示為陣列參考或純量

authors 和 licenses 方法也可以分別稱為 author 和 license，以符合 distmeta 結構中的欄位名稱。

對應資料

這些讀取器回傳任意未祝福資料結構的雜湊，每個結構在規格中都有更詳細的說明

自訂資料

可以從 custom_keys 方法取得自訂金鑰清單，並可以使用 custom 方法擷取特定金鑰。

say $meta->custom($_) for $meta->custom_keys;

如果自訂金鑰參照資料結構，將會回傳深度複製。

錯誤

請使用 CPAN 要求追蹤器回報任何錯誤或功能。錯誤可以透過網路介面提交至 http://rt.cpan.org/Dist/Display.html?Queue=CPAN-Meta

提交錯誤或要求時，請包含測試檔案或現有測試檔案的修補程式，用以說明錯誤或所需功能。

另請參閱

支援

錯誤 / 功能要求

請透過 https://github.com/Perl-Toolchain-Gang/CPAN-Meta/issues 上的問題追蹤器回報任何錯誤或功能要求。您將會自動收到問題進度的通知。

原始碼

這是開源軟體。程式碼存放庫可供公眾檢視和貢獻，並受許可條款約束。

https://github.com/Perl-Toolchain-Gang/CPAN-Meta

git clone https://github.com/Perl-Toolchain-Gang/CPAN-Meta.git

作者

貢獻者

版權和授權

此軟體的版權為 (c) 2010 David Golden、Ricardo Signes、Adam Kennedy 和貢獻者所有。

這是免費軟體；您可以在與 Perl 5 程式語言系統相同的條款下重新散布和/或修改它。