version (ex_stdlib v0.3.0)
View SourceSemantic versioning (https://semver.org), inspired by Elixir's Version module.
A version is a map with the keys major, minor, patch, pre (a list of pre-release identifiers, integers or binaries) and build (a binary or undefined):
{ok, #{major := 2, minor := 0, patch := 1, pre := [<<"alpha">>, 1]}} =
version:parse(<<"2.0.1-alpha.1">>),
lt = version:compare(<<"1.0.0-beta">>, <<"1.0.0-rc1">>),
true = version:match(<<"2.1.6">>, <<"~> 2.1.2">>).Requirements
A requirement is made of one or more operator/version pairs joined by and or or, such as ">= 2.0.0 and < 2.1.0". The operators are ==, != (deprecated in Elixir), >, >=, <, <= and ~>. A version without an operator means ==.
~> allows the last given component to increase:
~> 2.0.0is>= 2.0.0 and < 2.1.0-0~> 2.1.2is>= 2.1.2 and < 2.2.0-0~> 2.1is>= 2.1.0 and < 3.0.0-0~> 2.1-betais>= 2.1.0-beta and < 3.0.0-0
Build segments (+...) are ignored when comparing and matching.
Summary
Functions
Compares two versions, returning gt, eq or lt.
Compiles a requirement for faster matching. Requirements are already stored in their matching form, so this returns it unchanged; it exists for API compatibility.
Checks if the version matches the requirement, allowing pre-releases.
Checks if the version matches the requirement.
Parses a version string.
Parses a requirement string.
Converts a version to a string.
Types
-type match_option() :: {allow_pre, boolean()}.
-type pre_identifier() :: non_neg_integer() | binary().
-opaque requirement()
-type version() :: #{major := non_neg_integer(), minor := non_neg_integer(), patch := non_neg_integer(), pre := [pre_identifier()], build := binary() | undefined}.
Functions
Compares two versions, returning gt, eq or lt.
Pre-releases are lower than their release; numeric pre-release identifiers are compared numerically and lower than alphanumeric ones. Build segments are ignored. Raises {invalid_version, V} if a version string cannot be parsed.
gt = version:compare("2.0.1-alpha1", "2.0.0"),
gt = version:compare("1.0.0-10", "1.0.0-2"),
eq = version:compare("2.0.1+build0", "2.0.1").-spec compile_requirement(requirement()) -> requirement().
Compiles a requirement for faster matching. Requirements are already stored in their matching form, so this returns it unchanged; it exists for API compatibility.
Checks if the version matches the requirement, allowing pre-releases.
-spec match(version() | binary() | string(), requirement() | binary() | string(), [match_option()] | #{allow_pre => boolean()}) -> boolean().
Checks if the version matches the requirement.
With {allow_pre, false}, pre-release versions do not match the ~>, > and >= operators unless the requirement's version is itself a pre-release. Raises {invalid_version, V} or {invalid_requirement, R} if a string cannot be parsed.
true = version:match("2.1.6-dev", "~> 2.1.2"),
false = version:match("2.1.6-dev", "~> 2.1.2", [{allow_pre, false}]).Parses a version string.
{ok, #{major := 2, minor := 0, patch := 1, pre := [<<"alpha1">>]}} = version:parse("2.0.1-alpha1"),
error = version:parse("2.0-alpha1").-spec parse_requirement(binary() | string()) -> {ok, requirement()} | error.
Parses a requirement string.
{ok, Req} = version:parse_requirement(">= 1.0.0 and < 2.0.0"),
error = version:parse_requirement("== == 2.0.1").-spec to_string(version() | requirement()) -> binary().
Converts a version to a string.
<<"1.14.0-rc.0+build0">> = version:to_string(Version).