Версия

Функции для разбора и сопоставления версий с требованиями.

Версия — это строка в определенном формате или Version, сгенерированная после разбора с помощью Version.parse/1.

Version разбор и требования следуют схеме SemVer 2.0.

Версии

Вкратце, версия представлена тремя числами:

MAJOR.MINOR.PATCH

Предварительные версии поддерживаются путем добавления дефиса и ряда идентификаторов, разделенных точками, непосредственно после версии исправления. Идентификаторы состоят только из буквенно-цифровых ASCII-символов и дефисов ([0-9A-Za-z-]):

"1.0.0-alpha.3"

Дополнительную информацию о сборке можно добавить, добавив знак плюс и ряд идентификаторов, разделенных точками, непосредственно после версии исправления или предварительной версии. Идентификаторы состоят только из буквенно-цифровых ASCII-символов и дефисов ([0-9A-Za-z-]):

"1.0.0-alpha.3+20130417140000.amd64"

Структура

Версия представлена структурой Version, и поля названы в соответствии со схемой SemVer: :major, :minor, :patch, :pre, и :build.

Требования

Требования позволяют вам указать, с какими версиями конкретной зависимости вы готовы работать. Требования поддерживают стандартные операторы сравнения, такие как >, >=, <, <=, ==, !=, которые работают как ожидается, а также специальный оператор ~>, описанный более подробно ниже.

# Only version 2.0.0
"== 2.0.0"

# Anything later than 2.0.0
"> 2.0.0"

Требования также поддерживают and и or для сложных условий:

# 2.0.0 and later until 2.1.0
">= 2.0.0 and < 2.1.0"

Поскольку пример выше является таким распространенным требованием, его можно выразить как:

"~> 2.0.0"

~> никогда не будет включать предварительные версии своего верхнего предела, независимо от использования опции :allow_pre или является ли операнд предварительной версией. Он также может использоваться для установки верхнего предела только для части основной версии. См. таблицу ниже для ~> требований и их соответствующих переводов.

`~>`	Перевод
`~> 2.0.0`	`>= 2.0.0 and < 2.1.0`
`~> 2.1.2`	`>= 2.1.2 and < 2.2.0`
`~> 2.1.3-dev`	`>= 2.1.3-dev and < 2.2.0`
`~> 2.0`	`>= 2.0.0 and < 3.0.0`
`~> 2.1`	`>= 2.1.0 and < 3.0.0`

Операнд требования после ~> может опустить версию исправления, что позволяет нам выразить ~> 2.1 или ~> 2.1-dev, чего нельзя сделать с помощью стандартных операторов сравнения.

Когда опция :allow_pre установлена false в Version.match?/3, требование не будет соответствовать предварительной версии, если операнд не является предварительной версией. По умолчанию предварительные версии всегда разрешены, но обратите внимание, что в Hex :allow_pre установлено значение false. См. таблицу ниже для примеров.

Требование	Версия	`:allow_pre`	Соответствует
`~> 2.0`	`2.1.0`	`true` или `false`	`true`
`~> 2.0`	`3.0.0`	`true` или `false`	`false`
`~> 2.0.0`	`2.0.5`	`true` или `false`	`true`
`~> 2.0.0`	`2.1.0`	`true` или `false`	`false`
`~> 2.1.2`	`2.1.6-dev`	`true`	`true`
`~> 2.1.2`	`2.1.6-dev`	`false`	`false`
`~> 2.1-dev`	`2.2.0-dev`	`true` или `false`	`true`
`~> 2.1.2-dev`	`2.1.6-dev`	`true` или `false`	`true`
`>= 2.1.0`	`2.2.0-dev`	`true`	`true`
`>= 2.1.0`	`2.2.0-dev`	`false`	`false`
`>= 2.1.0-dev`	`2.2.6-dev`	`true` или `false`	`true`

Краткое описание

Функции

compare(version1, version2): Сравнивает две версии.
compile_requirement(requirement): Компилирует требование в его внутреннее представление с :ets.match_spec_compile/1 для более быстрого сопоставления.
match?(version, requirement, opts \\ []): Проверяет, соответствует ли заданная версия спецификации.
parse(string): Разбирает строку версии в структуру Version.
parse!(string): Разбирает строку версии в Version.
parse_requirement(string): Разбирает строку требования к версии в структуру Version.Requirement.
parse_requirement!(string): Разбирает строку требования к версии в структуру Version.Requirement структуру.

END_OF_DOCUMENT_MARKER ```

Типы

build()

Спецификации

build() :: String.t() | nil

major()

Спецификации

major() :: non_neg_integer()

minor()

Спецификации

minor() :: non_neg_integer()

patch()

Спецификации

patch() :: non_neg_integer()

pre()

Спецификации

pre() :: [String.t() | non_neg_integer()]

requirement()

Спецификации

requirement() :: String.t() | Version.Requirement.t()

t()

Спецификации

t() :: %Version{
  build: build(),
  major: major(),
  minor: minor(),
  patch: patch(),
  pre: pre()
}

version()

Спецификации

version() :: String.t() | t()

Функции

compare(version1, version2)

Спецификации

compare(version(), version()) :: :gt | :eq | :lt

Сравнивает две версии.

Возвращает :gt, если первая версия больше второй, и :lt, в противном случае. Если версии равны, возвращается :eq.

Предварительные версии строго меньше соответствующих релизных версий.

Сегменты патчей сравниваются лексикографически, если они являются буквенно-цифровыми, и численно в противном случае.

Сегменты сборки игнорируются: если две версии отличаются только сегментом сборки, они считаются равными.

Возникает исключение Version.InvalidVersionError, если какая-либо из двух заданных версий не может быть обработана. Если передана уже обработанная версия, эта функция не будет вызывать исключение.

Примеры

iex> Version.compare("2.0.1-alpha1", "2.0.0")
:gt

iex> Version.compare("1.0.0-beta", "1.0.0-rc1")
:lt

iex> Version.compare("1.0.0-10", "1.0.0-2")
:gt

iex> Version.compare("2.0.1+build0", "2.0.1")
:eq

iex> Version.compare("invalid", "2.0.1")
** (Version.InvalidVersionError) invalid version: "invalid"

compile_requirement(requirement)

Спецификации

compile_requirement(Version.Requirement.t()) :: Version.Requirement.t()

Компилирует требование до его внутренней формы с помощью :ets.match_spec_compile/1 для более быстрого соответствия.

Внутреннее представление является неявным и не может быть преобразовано в внешний формат и обратно, не потеряв своих свойств (т. е. не может быть отправлено процессу на другом узле и остаться действительной сохраненной спецификацией, а также не может быть сохранено на диске).

match?(version, requirement, opts \\ [])

Спецификации

match?(version(), requirement(), keyword()) :: boolean()

Проверяет, соответствует ли данная версия спецификации.

Возвращает true, если version удовлетворяет requirement, и false, в противном случае. Возникает исключение Version.InvalidRequirementError, если requirement не может быть обработано, или исключение Version.InvalidVersionError, если version не может быть обработано. Если переданы уже обработанные версия и требование, эта функция не будет вызывать исключение.

Параметры

:allow_pre (булево) - когда false, предварительные версии не будут соответствовать, если операнд не является предварительной версией. По умолчанию true. Примеры см. в таблице выше в разделе "Требования".

Примеры

iex> Version.match?("2.0.0", "> 1.0.0")
true

iex> Version.match?("2.0.0", "== 1.0.0")
false

iex> Version.match?("2.1.6-dev", "~> 2.1.2")
true

iex> Version.match?("2.1.6-dev", "~> 2.1.2", allow_pre: false)
false

iex> Version.match?("foo", "== 1.0.0")
** (Version.InvalidVersionError) invalid version: "foo"

iex> Version.match?("2.0.0", "== == 1.0.0")
** (Version.InvalidRequirementError) invalid requirement: "== == 1.0.0"

parse(string)

Спецификации

parse(String.t()) :: {:ok, t()} | :error

Обрабатывает строку версии в структуру Version.

Примеры

iex> {:ok, version} = Version.parse("2.0.1-alpha1")
iex> version
#Version<2.0.1-alpha1>

iex> Version.parse("2.0-alpha1")
:error

parse!(string)

Спецификации

parse!(String.t()) :: t()

Обрабатывает строку версии в структуру Version.

Если string является недопустимой версией, возникает исключение Version.InvalidVersionError.

Примеры

iex> Version.parse!("2.0.1-alpha1")
#Version<2.0.1-alpha1>

iex> Version.parse!("2.0-alpha1")
** (Version.InvalidVersionError) invalid version: "2.0-alpha1"

parse_requirement(string)

Спецификации

parse_requirement(String.t()) :: {:ok, Version.Requirement.t()} | :error

Обрабатывает строку требования версии в структуру Version.Requirement.

Примеры

iex> {:ok, requirement} = Version.parse_requirement("== 2.0.1")
iex> requirement
#Version.Requirement<== 2.0.1>

iex> Version.parse_requirement("== == 2.0.1")
:error

parse_requirement!(string)

Спецификации

parse_requirement!(String.t()) :: Version.Requirement.t()

Обрабатывает строку требования версии в структуру Version.Requirement структуру.

Если string является недопустимым требованием, возникает исключение Version.InvalidRequirementError.

Примеры

iex> Version.parse_requirement!("== 2.0.1")
#Version.Requirement<== 2.0.1>

iex> Version.parse_requirement!("== == 2.0.1")
** (Version.InvalidRequirementError) invalid requirement: "== == 2.0.1"