Spec-Zone.ru › Perl 5.34

версия

СОДЕРЖАНИЕ

  • ИМЯ
  • СИНОПС
  • ОПИСАНИЕ
  • ТИПЫ ОБЪЕКТОВ ВЕРСИИ
  • ОПРЕДЕЛЕНИЕ ВЕРСИЙ
    • Как преобразовать модуль из десятичного в десятичный с точкой
    • Как объявить() версию с точкой и десятичной дробью
  • РАЗБОР И СРАВНЕНИЕ ВЕРСИЙ
    • Как разобрать() версию
    • Как проверить строку версии на соответствие правилам
    • Как сравнить объекты версии
  • МЕТОДЫ ОБЪЕКТА
    • is_alpha()
    • is_qv()
    • normal()
    • numify()
    • stringify()
  • ЭКСПОРТИРОВАННЫЕ ФУНКЦИИ
    • qv()
    • is_lax()
    • is_strict()
  • АВТОР
  • СМОТРИТЕ ТАКЖЕ

ИМЯ

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 и предоставляет API для объектов версии для всех версий Perl. Все предыдущие версии до 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» теперь настоятельно рекомендуется для ясности и вызовет предупреждение в будущей версии, если ее не будет. Ведущий символ «v» необходим для прохождения теста "is_strict()".

ОПРЕДЕЛЕНИЕ ВЕРСИЙ

Если у вас есть модуль, который использует десятичную версию $VERSION (с плавающей запятой), и вы не собираетесь ее изменять, этот модуль вам не нужен. Модуль version.pm не предоставляет никаких преимуществ по сравнению с простым присвоением $VERSION:

our $VERSION = "1.02";

Поскольку Perl v5.10.0 включает в себя логику сравнения version.pm, вам вообще ничего не нужно делать.

Как преобразовать модуль из десятичного в десятичный с точкой

Если вы использовали десятичную версию $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», чтобы убедиться, что $VERSION правильно считывается инструментами PAUSE и установки. Вы также должны добавить «version» в раздел «configure_requires» файла метаданных вашего модуля. См. инструкции в ExtUtils::MakeMaker или Module::Build для получения подробностей.

Важное примечание: даже если вы передаете то, что выглядит как десятичное число («1.2»), будет создан объект версии с точкой и десятичной дробью («v1.200.0»). Чтобы избежать путаницы или непреднамеренных ошибок в более старых версиях Perl, следуйте этим рекомендациям:

  • Всегда используйте версию с точкой и десятичной дробью с (по крайней мере) тремя компонентами

  • Всегда используйте ведущую «v»

  • Всегда используйте кавычки для версии

Если вы действительно настаиваете на использовании version.pm с обычной десятичной версией, используйте parse() вместо declare. См. раздел "РАЗБОР И СРАВНЕНИЕ ВЕРСИЙ" для получения подробностей.

См. также 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

См. version::Internals для получения подробностей о регулярных выражениях, определяющих допустимые формы строк версии, а также о том, как использовать эти регулярные выражения в собственном коде, если is_lax() и is_strict() не удовлетворяют вашим потребностям.

Как сравнить объекты версии

Объекты версии перегружают операторы 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

Обратите внимание, что объекты версии «альфа» (где строка версии содержит заключительный сегмент с подчеркиванием) сравниваются как меньшие, чем эквивалентные версии без подчеркивания:

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

См. 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» и как минимум тремя компонентами.

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()

(Не экспортируется по умолчанию)

Эта функция принимает скалярный аргумент и возвращает логическое значение, указывающее, соответствует ли аргумент правилам «жесткости» для номера версии. Пробелы в начале и конце не допускаются.

АВТОР

John Peacock <jpeacock@cpan.org>

СМОТРИТЕ ТАКЖЕ

version::Internals.

perl.

© 1993–2021 Larry Wall and others
Licensed under the GNU General Public License version 1 or later, or the Artistic License.
The Perl logo is a trademark of the Perl Foundation.
https://perldoc.perl.org/5.34.0/version

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API