Исходный код Версия

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

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

Если 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"

© 2012-2024 The Elixir Team
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.17.2/Version.html