Version

Introduction #

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 given 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 it has its fields 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"
Source

Types #

version :: String.t | t

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

major :: String.t | non_neg_integer

minor :: non_neg_integer | nil

patch :: non_neg_integer | nil

pre :: [String.t]

build :: String.t | nil

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

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

Functions #

compare(vsn1, vsn2)

(function)

Specs

Compares two versions. Returns :gt if first version is greater than the second and :lt for vice versa. If the two versions are equal :eq is returned

Raises a Version.InvalidVersionError exception if version is not parseable. 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("2.0.1+build0", "2.0.1")
:eq

iex> Version.compare("invalid", "2.0.1")
** (Version.InvalidVersionError) invalid

match?(vsn, req)

(function)

Specs

Check if the given version matches the specification.

Returns true if version satisfies requirement, false otherwise. Raises a Version.InvalidRequirementError exception if requirement is not parseable, or Version.InvalidVersionError if version is not parseable. If given an already parsed version and requirement this function won't raise.

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)

(function)

Specs

Parse 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_requirement(string)

(function)

Specs

Parse 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