Версия

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

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

Хотя проекты Elixir не обязаны следовать SemVer, они должны следовать формату, описанному в схеме 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 2.0: :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`	`false` или `true`	`true`
`~> 2.0`	`3.0.0`	`false` или `true`	`false`
`~> 2.0.0`	`2.0.5`	`false` или `true`	`true`
`~> 2.0.0`	`2.1.0`	`false` или `true`	`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`	`false` или `true`	`true`
`~> 2.1.2-dev`	`2.1.6-dev`	`false` или `true`	`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`	`false` или `true`	`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"