Версия

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

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

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

Версии

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

MAJOR.MINOR.PATCH

Предварительные версии поддерживаются добавлением -[0-9A-Za-z-\.]:

"1.0.0-alpha.3"

Информация о сборке может быть добавлена путем добавления +[0-9A-Za-z-\.]:

"1.0.0-alpha.3+20130417140000"

Структура

Версия представлена структурой 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: false задано, требование не будет соответствовать предварительной версии, если операнд не является предварительной версией. По умолчанию предварительные версии всегда разрешены, но обратите внимание, что в Hex :allow_pre установлено в false. В таблице ниже приведены примеры.

Обзор

Типы

build()

major()

matchable()

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

Типы

build()

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

major()

major() :: String.t() | non_neg_integer()

matchable()

matchable() :: {major :: major(), minor :: minor(), patch :: patch(), pre :: pre()}

minor()

minor() :: non_neg_integer() | nil

patch()

patch() :: non_neg_integer() | nil

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?("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() | no_return()

Разбирает строку версии в Version.

Если string является недопустимой версией, генерируется 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