Elixir v1.6.4 Version View Source
Functions for parsing and matching versions against requirements.
A version is a string in a specific format or a Version
generated after parsing via Version.parse/1
.
Version
parsing and requirements follow
SemVer 2.0 schema.
Versions
In a nutshell, a version is represented by three numbers:
MAJOR.MINOR.PATCH
Pre-releases are supported by appending -[0-9A-Za-z-\.]
:
"1.0.0-alpha.3"
Build information can be added by appending +[0-9A-Za-z-\.]
:
"1.0.0-alpha.3+20130417140000"
Struct
The version is represented by the Version
struct and fields
are named according to SemVer: :major
, :minor
, :patch
,
:pre
, and :build
.
Requirements
Requirements allow you to specify which versions of a given
dependency you are willing to work against. Requirements support common
operators like >=
, <=
, >
, ==
, and friends that
work as one would expect:
# Only version 2.0.0
"== 2.0.0"
# Anything later than 2.0.0
"> 2.0.0"
Requirements also support and
and or
for complex conditions:
# 2.0.0 and later until 2.1.0
">= 2.0.0 and < 2.1.0"
Since the example above is such a common requirement, it can be expressed as:
"~> 2.0.0"
~>
will never include pre-release versions of its upper bound.
It can also be used to set an upper bound on only the major
version part. See the table below for ~>
requirements and
their corresponding translation.
~> | Translation |
---|---|
~> 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 |
When allow_pre: false
is set, the requirement will not match a
pre-release version unless the operand is a pre-release version.
The default is to always allow pre-releases but note that in
Hex :allow_pre
is set to false
. See the table below for examples.
Requirement | Version | :allow_pre | Matches |
---|---|---|---|
~> 2.0 | 2.1.0 | - | true |
~> 2.0 | 3.0.0 | - | false |
~> 2.0.0 | 2.0.1 | - | true |
~> 2.0.0 | 2.1.0 | - | false |
~> 2.1.2 | 2.1.3-dev | true | true |
~> 2.1.2 | 2.1.3-dev | false | false |
~> 2.1-dev | 2.2.0-dev | false | true |
~> 2.1.2-dev | 2.1.3-dev | false | true |
>= 2.1.0 | 2.2.0-dev | false | false |
>= 2.1.0-dev | 2.2.3-dev | true | true |
Link to this section Summary
Functions
Compares two versions
Compiles a requirement to its internal representation with
:ets.match_spec_compile/1
for faster matching
Checks if the given version matches the specification
Parses a version string into a Version
struct
Parses a version string into a Version
Parses a version requirement string into a Version.Requirement
struct
Link to this section Types
Link to this section Functions
Compares two versions.
Returns :gt
if the first version is greater than the second one, and :lt
for vice versa. If the two versions are equal, :eq
is returned.
Pre-releases are strictly less than their corresponding release versions.
Patch segments are compared lexicographically if they are alphanumeric, and numerically otherwise.
Build segments are ignored: if two versions differ only in their build segment they are considered to be equal.
Raises a Version.InvalidVersionError
exception if any of the two given
versions are not parsable. If given an already parsed version this function
won’t raise.
Examples
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(Version.Requirement.t()) :: Version.Requirement.t()
Compiles a requirement to its internal representation with
:ets.match_spec_compile/1
for faster matching.
The internal representation is opaque and cannot be converted to external term format and then back again without losing its properties (meaning it can not be sent to a process on another node and still remain a valid compiled match_spec, nor can it be stored on disk).
match?(version(), requirement(), keyword()) :: boolean()
Checks if the given version matches the specification.
Returns true
if version
satisfies requirement
, false
otherwise.
Raises a Version.InvalidRequirementError
exception if requirement
is not
parsable, or a Version.InvalidVersionError
exception if version
is not parsable.
If given an already parsed version and requirement this function won’t
raise.
Options
:allow_pre
(boolean) - whenfalse
, pre-release versions will not match unless the operand is a pre-release version. See the table above for examples. Defaults totrue
.
Examples
iex> Version.match?("2.0.0", "> 1.0.0")
true
iex> Version.match?("2.0.0", "== 1.0.0")
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"
Parses a version string into a Version
struct.
Examples
iex> {:ok, version} = Version.parse("2.0.1-alpha1")
iex> version
#Version<2.0.1-alpha1>
iex> Version.parse("2.0-alpha1")
:error
Parses a version string into a Version
.
If string
is an invalid version, an InvalidVersionError
is raised.
Examples
iex> Version.parse!("2.0.1-alpha1")
#Version<2.0.1-alpha1>
iex> Version.parse!("2.0-alpha1")
** (Version.InvalidVersionError) invalid version: "2.0-alpha1"
parse_requirement(String.t()) :: {:ok, Version.Requirement.t()} | :error
Parses a version requirement string into a Version.Requirement
struct.
Examples
iex> {:ok, requirement} = Version.parse_requirement("== 2.0.1")
iex> requirement
#Version.Requirement<== 2.0.1>
iex> Version.parse_requirement("== == 2.0.1")
:error