version.lua

Contents

• Functions

Modules

• version

Topics

• readme

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

Info:

• Copyright: Mashape 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.
range:semver (v)	Matches a provider-version on a consumer-version based on the semantic versioning specification.
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.

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). If omitted it will default 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

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

range: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)

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

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