Module version
Version comparison library for Lua.
Comparison is simple and straightforward, with basic support for SemVer.
Usage:
local version = require("version") -- create a version and perform some comparisons local v = version("3.1.0") assert( v == version("3.1")) -- missing elements default to zero, and hence are equal assert( v > version("3.0")) -- create a version range, and check whether a version is within that range local r = version.range("2.75", "3.50.3") assert(r:matches(v)) -- create a set of multiple ranges, adding elements in a chained fashion local compatible = version.set("1.1","1.2"):allowed("2.1", "2.5"):disallowed("2.3") assert(compatible:matches("1.1.3")) assert(compatible:matches("1.1.3")) assert(compatible:matches("2.4")) assert(not compatible:matches("2.0")) assert(not compatible:matches("2.3")) -- print a formatted set print(compatible) --> "1.1 to 1.2 and 2.1 to 2.5, but not 2.3" -- create an upwards compatibility check, allowing all versions 1.x local c = version.set("1.0","2.0"):disallowed("2.0") assert(c:matches("1.4")) assert(not c:matches("2.0")) -- default parsing print(version("5.2")) -- "5.2" print(version("Lua 5.2 for me")) -- "5.2" print(version("5..2")) -- nil, "Not a valid version element: '5..2'" -- strict parsing print(version.strict("5.2")) -- "5.2" print(version.strict("Lua 5.2 for me")) -- nil, "Not a valid version element: 'Lua 5.2 for me'" print(version.strict("5..2")) -- nil, "Not a valid version element: '5..2'"
Info:
- Copyright: Kong Inc.
- License: Apache 2.0
- Author: Thijs Schreijer
Functions
new (v) | Creates a new version object from a string. |
range (v1, v2) | Creates a version range. |
range:matches (v) | Matches a version on a range. |
set (v1, v2) | Creates a version set. |
set:allowed (v1, v2) | Adds an ALLOWED range to the set. |
set:disallowed (v1, v2) | Adds a DISALLOWED range to the set. |
set:matches (v1) | Matches a version against the set of allowed and disallowed versions. |
ver:semver (v) | Matches a provider-version on a consumer-version based on the semantic versioning specification. |
Fields
strict | Similar module, but with stricter parsing rules. |
Functions
- new (v)
-
Creates a new version object from a string.
The returned table will have
comparison operators, eg. LT, EQ, GT. For all comparisons, any missing numbers
will be assumed to be “0” on the least significant side of the version string.
Calling on the module table is a shortcut to new.
Parameters:
- v String formatted as numbers separated by dots (no limit on number of elements).
Returns:
-
version object, or
nil+err
Usage:
local v = version.new("0.1") -- is identical to local v = version("0.1") print(v) --> "0.1" print(v[1]) --> 0 print(v[2]) --> 1
- range (v1, v2)
-
Creates a version range. A range object represents a range of versions.
Parameters:
- v1
The FROM version of the range (string or version object). If
nil
, assumed to be 0. - v2
(optional) The TO version of the range (string or version object). Defaults to
v1
.
Returns:
-
range object with
from
andto
fields and set:matches method, ornil+err
.Usage:
local r = version.range("0.1"," 2.4") print(v.from) --> "0.1" print(v.to[1]) --> 2 print(v.to[2]) --> 4
- v1
The FROM version of the range (string or version object). If
- range:matches (v)
-
Matches a version on a range.
Parameters:
- v Version (string or version object) to match
Returns:
true
orfalse
whether the version matches the range, ornil+err
- set (v1, v2)
-
Creates a version set.
A set is an object that contains a number of allowed and disallowed version range objects.
Parameters:
- v1 initial version/range to allow, see set:allowed for parameter descriptions
- v2 initial version/range to allow, see set:allowed for parameter descriptions
Returns:
-
a set object, with
ok
andnok
lists and a set:matches method, ornil+err
- set:allowed (v1, v2)
-
Adds an ALLOWED range to the set.
Parameters:
- v1 Version or range, if version, the FROM version in either string or version object format
- v2 Version (optional), TO version in either string or version object format
Returns:
-
The set object, to easy chain multiple allowed/disallowed ranges, or
nil+err
- set:disallowed (v1, v2)
-
Adds a DISALLOWED range to the set.
Parameters:
- v1 Version or range, if version, the FROM version in either string or version object format
- v2 Version (optional), TO version in either string or version object format
Returns:
-
The set object, to easy chain multiple allowed/disallowed ranges, or
nil+err
- set:matches (v1)
-
Matches a version against the set of allowed and disallowed versions.
NOTE: disallowed has a higher precedence, so a version that matches the allowed set, but also the disallowed set, will return
false
.Parameters:
- v1 Version to match (either string or version object).
Returns:
true
orfalse
whether the version matches the set, ornil+err
- ver:semver (v)
-
Matches a provider-version on a consumer-version based on the
semantic versioning specification.
The implementation does not support pre-release and/or build metadata,
only the major, minor, and patch levels are compared.
Parameters:
- v Version (string or version object) as served by the provider
Returns:
true
orfalse
whether the version matches, ornil+err
Usage:
local consumer = "1.2" -- consumer requested version local provider = "1.5.2" -- provider served version local compatible = version(consumer):semver(provider)
Fields
- strict
-
Similar module, but with stricter parsing rules.
version.strict is identical to the version module itself, but it requires
exact version strings, where as the regular parser will simply grab the
first sequence of numbers and dots from the string.
- strict same module, but for stricter parsing.