Spec-Zone.ru › Perl 5.30

версия

СОДЕРЖАНИЕ

  • НАЗВАНИЕ
  • СИНТЕКС
  • ОПИСАНИЕ
  • ТИПЫ ОБЪЕКТОВ ВЕРСИИ
  • ОПРЕДЕЛЕНИЕ ВЕРСИЙ
    • Как преобразовать модуль из десятичного в точечно-десятичный
    • Как объявить() точечно-десятичную версию
  • ПАРСИНГ И СРАВНЕНИЕ ВЕРСИЙ
    • Как разобрать() версию
    • Как проверить строку версии на корректность
    • Как сравнить объекты версии
  • МЕТОДЫ ОБЪЕКТА
    • 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 численно больше вашей текущей десятичной версии $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.96; # FALSE since 0.96 is v0.960.0

Для избежания неожиданных результатов всегда сравнивайте с объектом версии:

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

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

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

См. version::Internals для получения дополнительной информации об «альфа»-версиях.

МЕТОДЫ ОБЪЕКТА

is_alpha()

True только в том случае, если объект версии был создан с подчеркиванием, например:

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

is_qv()

True только в том случае, если объект версии является точечно-десятичной версией, например:

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

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

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

АВТОР

John Peacock <jpeacock@cpan.org>

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

version::Internals.

perl.

© 1993–2020 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.30.3/version

Spec-Zone.ru

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