Elixir

v1.2.6

Elixir

Elixir v1.2.6 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

Summary

Types

build()
major()
matchable()
minor()
patch()
pre()
requirement()
t()
version()

Functions

compare(version1, version2)

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

match?(version, requirement)

Checks if the given version matches the specification

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 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 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("2.0.1+build0", "2.0.1")
:eq

iex> Version.compare("invalid", "2.0.1")
** (Version.InvalidVersionError) invalid
match?(version, requirement) 
match?(version, requirement) :: 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.

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