Spec-Zone.ru › Perl 5.28

version

СОДЕРЖАНИЕ

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

НАЗВАНИЕ

version - Perl-расширение для объектов Version

СИНОПСИС

# 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

Существуют два разных типа объектов версии, соответствующие двум разным стилям используемых версий:

Десятичные версии

Классическое число с плавающей точкой $VERSION. Преимущество этого стиля заключается в том, что вам ничего не нужно делать, просто введите число в файл исходного кода. Рекомендуется использование кавычек, так как это гарантирует сохранение заключительных нулей («1.50») в любых предупреждениях или других выходных данных.

Точечно-десятичные версии

Более современный способ задания версии с 3 (или потенциально большим числом) целыми числами, разделенными точками (например, v1.2.3). Это форма, которую Perl использует с момента выпуска 5.6.0. Ведущая «v» сейчас настоятельно рекомендуется для ясности и вызовет предупреждение в будущей версии, если ее не будет. Ведущий символ «v» обязателен для прохождения проверки "is_strict()".

ОПРЕДЕЛЕНИЕ VERSION

Если у вас есть модуль, использующий десятичное $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()

Метод declare() всегда создает объекты точечно-десятичной версии. При использовании в модуле вы должны поместить его на той же строке, что и «use version», чтобы убедиться, что $VERSION правильно считывается инструментами PAUSE и установщиком. Вы также должны добавить «version» в раздел «configure_requires» вашего файла метаданных модуля. См. инструкции в ExtUtils::MakeMaker или Module::Build для получения подробностей.

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

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

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

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

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

См. также version::Internals для получения дополнительной информации о преобразовании номеров версий, использовании кавычек, вычислении номеров версий и объявлении версий разработчика или «альфа» версий.

ПАРСИНГ И СРАВНЕНИЕ VERSION

Если вам необходимо сравнить номера версий, но вы не уверены, выражены ли они числами, строками, строками с префиксом v или объектами версии, тогда вы должны использовать version.pm для разбора их всех в объекты для сравнения.

Как разобрать() версию

Метод 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()

Критерии «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()

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

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

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

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

is_strict()

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

Эта функция принимает скалярный аргумент и возвращает логическое значение, указывающее, соответствует ли аргумент правилам «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.28.3/version

Spec-Zone.ru

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