Версия

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

Версия — это строка в определенном формате или 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.1 или ~> 2.1-dev, что не было бы возможно при использовании общих операторов сравнения.

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

Резюме

Типы

build()

major()

minor()

patch()

pre()

requirement()

t()

version()

Функции

compare(version1, version2)

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

compile_requirement(req)

Компилирует требование до его внутренней формы с помощью :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 структуру.

Типы

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

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

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

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

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"