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

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

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

Хотя проекты Elixir не обязаны следовать SemVer, они должны соответствовать формату, описанному в схеме 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.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`

Краткое описание

Функции

%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): Преобразует заданную версию в строку.

Типы

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"

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