Версия

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

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