Spec-Zone.ru › Perl 5.38

версия

СОДЕРЖАНИЕ

  • ИМЯ
  • СИНОПСИС
  • ОПИСАНИЕ
  • ТИПЫ ОБЪЕКТОВ ВЕРСИЙ
  • ОПРЕДЕЛЕНИЕ ВЕРСИЙ
    • Как преобразовать модуль из десятичного в десятичный с точкой
    • Как объявить() версию с точкой
  • ПАРСИНГ И СРАВНЕНИЕ ВЕРСИЙ
    • Как разобрать() версию
    • Как проверить строку версии на соответствие формату
    • Как сравнить объекты версий
  • МЕТОДЫ ОБЪЕКТА
    • 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» сейчас настоятельно рекомендуется для ясности и вызовет предупреждение в будущей версии, если она будет опущенa. Ведущий символ «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()

Критерий «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» и по крайней мере 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–2023 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.38.0/version

Spec-Zone.ru

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