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

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.
generated by LDoc 1.4.6 Last updated 2019-01-10 15:42:55