W3cubDocs

Version

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. It supports 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 allow 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`

Summary

Functions

compare(version1, version2): 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
compile_requirement(req): Compiles a requirement to its internal representation with :ets.match_spec_compile/1 for faster matching
match?(version, requirement, opts \\ []): Checks if the given version matches the specification
parse(string): Parses a version string into a Version
parse!(string): Parses a version string into a Version
parse_requirement(string): Parses a version requirement string into a Version.Requirement

Types

build()

build() :: String.t | nil

major()

major() :: String.t | non_neg_integer

matchable()

matchable() :: {major :: major, minor :: minor, patch :: patch, pre :: pre}

minor()

minor() :: non_neg_integer | nil

patch()

patch() :: non_neg_integer | nil

pre()

pre() :: [String.t | non_neg_integer]

requirement()

requirement() :: String.t | Version.Requirement.t

t()

t() :: %Version{build: build, major: major, minor: minor, patch: patch, pre: pre}

version()

version() :: String.t | t

Functions

compare(version1, version2)

compare(version, version) :: :gt | :eq | :lt

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 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

compile_requirement(req)

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 can not 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, opts \\ [])

match?(version, requirement, Keyword.t) :: 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 Version.InvalidVersionError if version is not parsable. If given an already parsed version and requirement this function won’t raise.

Options

:allow_pre - when false pre-release versions will not match unless the operand is a pre-release version, see the table above for examples (default: true);

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) foo

iex> Version.match?("2.0.0", "== ==1.0.0")
** (Version.InvalidRequirementError) == ==1.0.0

parse(string)

parse(String.t) :: {:ok, t} | :error

Parses a version string into a Version.

Examples

iex> {:ok, version} = Version.parse("2.0.1-alpha1")
iex> version
#Version<2.0.1-alpha1>

iex> Version.parse("2.0-alpha1")
:error

parse!(string)

parse!(String.t) :: t | no_return

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) 2.0-alpha1

parse_requirement(string)

parse_requirement(String.t) ::
  {:ok, Version.Requirement.t} |
  :error

Parses a version requirement string into a Version.Requirement.

Examples

iex> {:ok, req} = Version.parse_requirement("== 2.0.1")
iex> req
#Version.Requirement<== 2.0.1>

iex> Version.parse_requirement("== == 2.0.1")
:error