Версия

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

Версия — это строка в определенном формате или 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"

Требования

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

# 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`

Обзор

Функции

%Version{}: Структура Version.
compare(version1, version2): Сравнивает две версии.
compile_requirement(requirement): Компилирует требование к внутренней представлению, которое может оптимизировать сопоставление.
match?(version, requirement, opts \\ []): Проверяет, соответствует ли заданная версия спецификации.
parse(string): Разбирает строку версии в структуру Version.
parse!(string): Разбирает строку версии в Version.
parse_requirement(string): Разбирает строку требования к версии в структуру Version.Requirement.
parse_requirement!(string): Разбирает строку требования к версии в структуру Version.Requirement структуру.
to_string(version): Преобразует заданную версию в строку.

END_OF_DOCUMENT_MARKER

Типы

build()Source

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

major()Source

@type major() :: non_neg_integer()

minor()Source

@type minor() :: non_neg_integer()

patch()Source

@type patch() :: non_neg_integer()

pre()Source

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

requirement()Source

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

t()Source

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

version()Source

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

Функции

%Version{}Source

Структура Version.

Она содержит поля :major, :minor, :patch, :pre, и :build в соответствии со спецификацией SemVer 2.0, где :pre — список.

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

compare(version1, version2)Source

@spec 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)Source

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

Компилирует требование к внутренней форме, которая может оптимизировать сопоставление.

Внутренняя форма неявна.

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

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

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

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

Параметры

:allow_pre (boolean) — когда 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)Source

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

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

Примеры

iex> Version.parse("2.0.1-alpha1")
{:ok, %Version{major: 2, minor: 0, patch: 1, pre: ["alpha1"]}}

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

parse!(string)Source

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

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

Если string — недействительная версия, генерируется исключение Version.InvalidVersionError.

Примеры

iex> Version.parse!("2.0.1-alpha1")
%Version{major: 2, minor: 0, patch: 1, pre: ["alpha1"]}

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

parse_requirement(string)Source

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

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

Примеры

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

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

parse_requirement!(string)Source

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

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

Если string — некорректное требование, генерируется исключение Version.InvalidRequirementError.

Примеры

iex> Version.parse_requirement!("== 2.0.1")
Version.parse_requirement!("== 2.0.1")

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

to_string(version)Source

@spec to_string(t()) :: String.t()

Преобразует заданную версию в строку.

Примеры

iex> Version.to_string(%Version{major: 1, minor: 2, patch: 3})
"1.2.3"
iex> Version.to_string(Version.parse!("1.14.0-rc.0+build0"))
"1.14.0-rc.0+build0"