vendor.version module

Version comparison library for Lua.

Comparison is simple and straightforward, with basic support for SemVer.

• Copyright: Kong Inc.
• License: Apache 2.0
• Author: Thijs Schreijer

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

Functions

ver:semver(v)	Matches a provider-version on a consumer-version based on the semantic versioning specification.
range:matches(v)	Matches a version on a range.
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.
new(v)	Creates a new version object from a string.
range(v1, v2)	Creates a version range.
set(v1, v2)	Creates a version set.

Fields

strict	Similar module, but with stricter parsing rules.

Functions

# 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 or false whether the version matches, or nil+err

Usage:

local consumer = "1.2"     -- consumer requested version
local provider = "1.5.2"   -- provider served version

local compatible = version(consumer):semver(provider)

# range:matches(v)

Matches a version on a range.

Parameters:

• v : Version (string or version object) to match

Returns:

• true or false whether the version matches the range, or nil+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 or false whether the version matches the set, or nil+err

# 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 and to fields and set:matches method, or nil+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

# 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 and nok lists and a set:matches method, or nil+err

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.