version

(源代码, CPAN)

version 0.9929

内容

名称
概要
描述
版本对象类型
声明版本
- 如何将模块从十进制转换为点分十进制
- 如何声明() 点分十进制版本
解析和比较版本
对象方法
- is_alpha()
- is_qv()
- normal()
- numify()
- stringify()
导出函数
作者
参见

#名称

version - Perl 版本对象扩展

#概要

# Parsing version strings (decimal or dotted-decimal)

use version 0.77; # get latest bug-fixes and API
$ver = version->parse($string)

# Declaring a dotted-decimal $VERSION (keep on one line!)

use version; our $VERSION = version->declare("v1.2.3"); # formal
use version; our $VERSION = qv("v1.2.3");               # deprecated
use version; our $VERSION = qv("v1.2_3");               # deprecated

# Declaring an old-style decimal $VERSION (use quotes!)

our $VERSION = "1.0203";                                # recommended
use version; our $VERSION = version->parse("1.0203");   # formal
use version; our $VERSION = version->parse("1.02_03");  # alpha

# Comparing mixed version styles (decimals, dotted-decimals, objects)

if ( version->parse($v1) == version->parse($v2) ) {
  # do stuff
}

# Sorting mixed version styles

@ordered = sort { version->parse($a) <=> version->parse($b) } @list;

#描述

版本对象在 Perl 5.10 中被添加。此模块为旧版本的 Perl 实现版本对象，并为所有版本的 Perl 提供版本对象 API。所有之前 0.74 之前的版本都已弃用，由于 API 更改不兼容，不应使用。版本 0.77 引入了新的“parse”和“declare”方法来标准化使用。强烈建议您在代码中将 0.77 设置为最小值，例如：

use version 0.77; # even for Perl v.5.10.0

#版本对象的类型

有两种不同类型的版本对象，对应于使用的两种不同版本的样式

#十进制版本: 经典的浮点数 $VERSION。这种样式的优点是您不需要做任何特殊的事情，只需在源文件中输入一个数字即可。建议使用引号，因为它可以确保尾随零（“1.50”）在任何警告或其他输出中保留。
#点分十进制版本: 更现代的版本分配形式，用小数点分隔的 3（或可能更多）个整数（例如 v1.2.3）。这是 Perl 自 5.6.0 发布以来一直使用的形式。现在强烈建议使用前导“v”以提高清晰度，如果省略，将在将来的版本中发出警告。要通过 "is_strict()" 测试，需要前导“v”字符。

#声明版本

如果您有一个使用十进制 $VERSION（浮点数）的模块，并且您不打算更改它，那么此模块不适合您。与简单的 $VERSION 赋值相比，version.pm 不会为您带来任何好处。

our $VERSION = "1.02";

由于 Perl v5.10.0 包含 version.pm 比较逻辑，因此您无需执行任何操作。

#如何将模块从十进制转换为点分十进制

如果您过去使用过十进制 $VERSION，并且希望切换到点分十进制 $VERSION，那么您需要对新格式进行一次性转换。

重要提示：您必须确保新的 $VERSION 在数值上大于当前的十进制 $VERSION；这并不总是显而易见的。首先，将旧的十进制版本（例如 1.02）转换为规范化的点分十进制形式

$ perl -Mversion -e 'print version->parse("1.02")->normal'
v1.20.0

然后递增任何点分十进制组件（v1.20.1 或 v1.21.0）。

#如何`declare()`点分十进制版本

use version; our $VERSION = version->declare("v1.2.3");

declare() 方法始终创建点分十进制版本对象。在模块中使用时，您 **必须** 将其放在与“use version”同一行，以确保 PAUSE 和安装程序工具能够正确读取 $VERSION。您还应将“version”添加到模块元数据文件中的“configure_requires”部分。有关详细信息，请参阅 ExtUtils::MakeMaker 或 Module::Build 中的说明。

重要提示：即使您传入看起来像十进制数（“1.2”）的内容，也会创建点分十进制数（“v1.200.0”）。为了避免在旧版 Perl 中出现混淆或意外错误，请遵循以下指南

始终使用至少包含三个组件的点分十进制数
始终使用前导 v
始终引用版本

如果您确实坚持使用 version.pm 和普通十进制版本，请使用 parse() 而不是 declare。有关详细信息，请参阅 “解析和比较版本”。

有关版本号转换、引用、计算版本号和声明开发人员或“alpha”版本号的更多信息，请参阅 version::Internals。

#解析和比较版本

如果您需要比较版本号，但无法确定它们是表示为数字、字符串、v 字符串还是版本对象，那么您应该使用 version.pm 将它们全部解析为对象以进行比较。

#如何 `parse()` 版本

parse() 方法接受任何可能为版本的内容，并返回相应的版本对象，在此过程中执行任何必要的转换。

点分十进制：裸 v 字符串（v1.2.3）和包含多个小数点和前导“v”的字符串（“v1.2.3”）；注意，您可以在技术上使用 v 字符串或包含前导 v 和只有一个小数点的字符串（v1.2 或“v1.2”），但您会让自己和其他人感到困惑。
十进制：常规十进制数（字面量或字符串中）

一些示例

$variable   version->parse($variable)
---------   -------------------------
1.23        v1.230.0
"1.23"      v1.230.0
v1.23       v1.23.0
"v1.23"     v1.23.0
"1.2.3"     v1.2.3
"v1.2.3"    v1.2.3

有关版本号转换的更多信息，请参阅 version::Internals。

#如何检查合法版本字符串

如果您不想实际创建完整的版本对象，但仍想验证给定字符串是否满足作为版本解析的标准，则可以使用两个可以直接使用的辅助函数

#is_lax()

宽松的标准对应于当前版本解析器允许的内容。以下所有格式对于点分十进制格式字符串都是可接受的

v1.2
1.2345.6
v1.23_4
1.2345
1.2345_01

#is_strict()

如果您想将自己限制在对版本字符串构成的一个更狭窄的定义上，is_strict()仅限于以下列表中的版本字符串

v1.234.5
2.3456

有关定义合法版本字符串形式的正则表达式的详细信息，以及如何在您自己的代码中使用这些正则表达式（如果is_lax()和is_strict()不能满足您的需求），请参阅version::Internals。

#如何比较版本对象

版本对象重载了cmp和<=>运算符。Perl会根据这两个运算符自动生成所有其他比较运算符，因此所有正常的逻辑比较都将起作用。

if ( version->parse($v1) == version->parse($v2) ) {
  # do stuff
}

如果版本对象与非版本对象进行比较，则非对象项将使用parse()转换为版本对象。这可能会产生意外的结果

$v1 = version->parse("v0.95.0");
$bool = $v1 < 0.94; # TRUE since 0.94 is v0.940.0

始终与版本对象进行比较将有助于避免意外情况

$bool = $v1 < version->parse("v0.94.0"); # FALSE

请注意，“alpha”版本对象（版本字符串包含尾部下划线段）的比较结果小于没有下划线的等效版本

$bool = version->parse("1.23_45") < version->parse("1.2345"); # TRUE

有关“alpha”版本的更多详细信息，请参阅version::Internals。

#对象方法

#is_alpha()

当且仅当版本对象是用下划线创建时为真，例如

version->parse('1.002_03')->is_alpha;  # TRUE
version->declare('1.2.3_4')->is_alpha; # TRUE

#is_qv()

仅当版本对象是点分十进制版本时为真，例如

version->parse('v1.2.0')->is_qv;       # TRUE
version->declare('v1.2')->is_qv;       # TRUE
qv('1.2')->is_qv;                      # TRUE
version->parse('1.2')->is_qv;          # FALSE

#normal()

返回一个字符串，其中包含标准的“规范化”点分十进制形式，带有前导 v 和至少 3 个组件。

version->declare('v1.2')->normal;  # v1.2.0
version->parse('1.2')->normal;     # v1.200.0

#numify()

返回一个值，该值以纯十进制表示对象。

version->declare('v1.2')->numify;  # 1.002000
version->parse('1.2')->numify;     # 1.200

#stringify()

返回一个字符串，该字符串尽可能接近原始表示形式。如果原始表示形式是数字文字，它将以 perl 通常在字符串中表示它的方式返回。每当版本对象被插值到字符串中时，都会使用此方法。

version->declare('v1.2')->stringify;    # v1.2
version->parse('1.200')->stringify;     # 1.2
version->parse(1.02_30)->stringify;     # 1.023

#导出函数

#qv()

此函数不再推荐使用，但为了与现有代码兼容而保留。如果您不想将其导出到您的命名空间，请使用此形式

use version 0.77 ();

#is_lax()

(默认情况下不导出)

此函数接受一个标量参数，并返回一个布尔值，指示该参数是否满足版本号的“宽松”规则。不允许前导和尾随空格。

#is_strict()