Spec-Zone.ru › Perl 5.36

версия

СОДЕРЖАНИЕ

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

  • Десятичная версия с точкой: обычные строки с лидирующим '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' и по крайней мере 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–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.36.0/version

Spec-Zone.ru

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