内容

名称

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 对象。如果文件名不存在，则返回 undef。

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 参数是必需的，否则将返回 undef。

如果需要，您负责在 $handle 上设置解码层。

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

根据模块或包名构造一个 Module::Metadata 对象。如果找不到模块，则返回 undef。

除了接受上面描述的 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)

返回包含模块 $module 的 @dirs（或默认情况下为 @INC）中的条目。可以将目录列表作为可选参数传递，否则将搜索 @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 发行版在其 lib 中包含 .pm 文件的常见情况。此选项确保 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。

对象方法

name()

返回此模块所代表的包的名称。如果有多个包，它会根据文件名做出最佳猜测。如果它是一个脚本（即不是 *.pm），则包名为 'main'。

version($package)

返回由 $VERSION 变量定义的版本，该变量用于由 name 方法返回的包，如果未提供参数。如果给定一个包的名称，它将尝试返回该包的版本，如果该版本在文件中指定。

filename()

返回文件的绝对路径。请注意，此文件可能实际上尚未存在于磁盘上，例如，如果模块是从内存中的文件句柄中读取的。

packages_inside()

返回一个包列表。注意：这是一个发现的原始包列表（或者在 main 的情况下是假设的）。它不会像 provides 方法那样过滤掉 DB、main 或私有包。无效的包名不会返回，例如 "Foo:Bar"。奇怪但有效的包名将被返回，例如 "Foo::Bar::"，并由调用者决定如何处理。

pod_inside()

返回一个 POD 部分列表。

contains_pod()

如果文件中存在任何 POD，则返回 true。

pod($section)

返回给定部分中的 POD 数据。

is_indexable($package) 或 is_indexable()

从版本 1.000020 开始可用。

返回一个布尔值，指示该包（如果提供）或任何包（否则）是否符合 PAUSE（Perl 作者上传服务器）的索引资格。注意这仅检查有效的 package 声明，不考虑任何所有权信息。

SUPPORT

可以通过 RT 缺陷追踪器（或 bug-Module-Metadata@rt.cpan.org）提交缺陷。

此外，还有一个供此发行版用户使用的邮件列表，地址为 http://lists.perl.org/list/cpan-workers.html。

此外，还有一个供此发行版用户使用的 IRC 频道，地址为 irc.perl.org 上的 #toolchain。

AUTHOR

原始代码来自 Ken Williams <kwilliams@cpan.org> 和 Randy W. Sims <RandyS@ThePierianSpring.org> 编写的 Module::Build::ModuleInfo。

由 Matt S Trout (mst) <mst@shadowcat.co.uk> 发布为 Module::Metadata，并得到 David Golden (xdg) <dagolden@cpan.org> 的协助。

CONTRIBUTORS

COPYRIGHT & LICENSE

原始代码版权所有 (c) 2001-2011 Ken Williams。附加代码版权所有 (c) 2010-2011 Matt Trout 和 David Golden。保留所有权利。

此库是免费软件；您可以在 Perl 本身相同的条款下重新分发和/或修改它。