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

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

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

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

Функции

%Version{}: Структура Version.
compare(version1, version2): Сравнивает две версии.
compile_requirement(requirement): Компилирует требование в внутреннее представление, которое может оптимизировать сопоставление.
match?(version, requirement, opts \\ []): Проверяет, соответствует ли заданная версия спецификации.
parse(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 (логический) - если 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.18.1/Version.html