内容

名称

CPAN::Meta - CPAN 发行版元数据

版本

版本 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 对象，如果提供的元数据哈希引用无法验证，则会抛出异常。旧格式的元数据将在验证通过原始声明的规范后被升级到版本 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() 一样。如果反序列化的版本无法通过其声明的规范版本验证，则会终止程序。

它接受与 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。

对于 version 小于 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 );

此方法返回一个布尔值，表示是否应该索引给定文件。它通过检查 distmeta 结构的 no_index 属性中的 file 和 directory 键来决定。请注意，版本格式和 release_status 都不考虑在内。

$filename 应以 Unix 格式给出。

should_index_package

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

此方法返回一个布尔值，表示是否应该索引给定包。它通过检查 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 结构中对应条目的值。值应为 undef 或字符串。

列表数据

这些方法返回字符串值的列表，这些值可能在 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

提交错误或请求时，请包含一个测试文件或对现有测试文件的修补程序，以说明错误或所需功能。

另请参阅

支持

错误/功能请求

请通过以下地址的 issue 跟踪器报告任何错误或功能请求：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 编程语言系统本身相同的条款重新分发和/或修改它。