diff options
| -rw-r--r-- | runtime/autoload/provider/clipboard.vim | 4 | ||||
| -rw-r--r-- | runtime/doc/lua.txt | 172 | ||||
| -rw-r--r-- | runtime/doc/news.txt | 4 | ||||
| -rw-r--r-- | runtime/lua/vim/version.lua | 535 | ||||
| -rw-r--r-- | test/functional/lua/version_spec.lua | 431 | ||||
| -rw-r--r-- | test/functional/terminal/buffer_spec.lua | 2 |
6 files changed, 645 insertions, 503 deletions
diff --git a/runtime/autoload/provider/clipboard.vim b/runtime/autoload/provider/clipboard.vim index 98c80f1843..6d238ddb55 100644 --- a/runtime/autoload/provider/clipboard.vim +++ b/runtime/autoload/provider/clipboard.vim @@ -145,8 +145,8 @@ function! provider#clipboard#Executable() abort let s:paste['*'] = s:paste['+'] return 'termux-clipboard' elseif !empty($TMUX) && executable('tmux') - let ver = matchlist(systemlist(['tmux', '-V'])[0], '\vtmux %(next-)?(\d+)\.(\d+)') - if len(ver) >= 3 && (ver[1] > 3 || (ver[1] == 3 && ver[2] >= 2)) + let tmux_v = v:lua.vim.version.parse(system(['tmux', '-V'])) + if !empty(tmux_v) && !v:lua.vim.version.lt(tmux_v, [3,2,0]) let s:copy['+'] = ['tmux', 'load-buffer', '-w', '-'] else let s:copy['+'] = ['tmux', 'load-buffer', '-'] diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index e7dcc79f4a..cec3c1303f 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -782,9 +782,6 @@ vim.api.{func}({...}) *vim.api* Example: call the "nvim_get_current_line()" API function: >lua print(tostring(vim.api.nvim_get_current_line())) -vim.version() *vim.version* - Gets the version of the current Nvim build. - vim.in_fast_event() *vim.in_fast_event()* Returns true if the code is executing as part of a "fast" event handler, where most of the API is disabled. These are low-level events (e.g. @@ -1391,8 +1388,7 @@ deprecate({name}, {alternative}, {version}, {plugin}, {backtrace}) Parameters: ~ • {name} string Deprecated feature (function, API, etc.). • {alternative} (string|nil) Suggested alternative feature. - • {version} string Version when the deprecated function will be - removed. + • {version} string Version when the deprecated function will be removed. • {plugin} string|nil Name of the plugin that owns the deprecated feature. Defaults to "Nvim". • {backtrace} boolean|nil Prints backtrace. Defaults to true. @@ -2533,67 +2529,179 @@ trust({opts}) *vim.secure.trust()* ============================================================================== Lua module: version *lua-version* -cmp({v1}, {v2}, {opts}) *vim.version.cmp()* - Compares two strings ( `v1` and `v2` ) in semver format. + +The `vim.version` module provides functions for comparing versions and +ranges conforming to the + +https://semver.org + +spec. Plugins, and plugin managers, can use this to check available tools +and dependencies on the current system. + +Example: >lua + + local v = vim.version.parse(vim.fn.system({'tmux', '-V'}), {strict=false}) + if vim.version.gt(v, {3, 2, 0}) then + -- ... + end + +< + +*vim.version()* returns the version of the current Nvim process. + +VERSION RANGE SPEC *version-range* + +A version "range spec" defines a semantic version range which can be +tested against a version, using |vim.version.range()|. + +Supported range specs are shown in the following table. Note: suffixed +versions (1.2.3-rc1) are not matched. > + + 1.2.3 is 1.2.3 + =1.2.3 is 1.2.3 + >1.2.3 greater than 1.2.3 + <1.2.3 before 1.2.3 + >=1.2.3 at least 1.2.3 + ~1.2.3 is >=1.2.3 <1.3.0 "reasonably close to 1.2.3" + ^1.2.3 is >=1.2.3 <2.0.0 "compatible with 1.2.3" + ^0.2.3 is >=0.2.3 <0.3.0 (0.x.x is special) + ^0.0.1 is =0.0.1 (0.0.x is special) + ^1.2 is >=1.2.0 <2.0.0 (like ^1.2.0) + ~1.2 is >=1.2.0 <1.3.0 (like ~1.2.0) + ^1 is >=1.0.0 <2.0.0 "compatible with 1" + ~1 same "reasonably close to 1" + 1.x same + 1.* same + 1 same + * any version + x same + + 1.2.3 - 2.3.4 is >=1.2.3 <=2.3.4 + + Partial right: missing pieces treated as x (2.3 => 2.3.x). + 1.2.3 - 2.3 is >=1.2.3 <2.4.0 + 1.2.3 - 2 is >=1.2.3 <3.0.0 + + Partial left: missing pieces treated as 0 (1.2 => 1.2.0). + 1.2 - 2.3.0 is 1.2.0 - 2.3.0 + +< + +cmp({v1}, {v2}) *vim.version.cmp()* + Parses and compares two version version objects (the result of + |vim.version.parse()|, or specified literally as a `{major, minor, patch}` + tuple, e.g. `{1, 0, 3}`). + + Example: >lua + + if vim.version.cmp({1,0,3}, {0,2,1}) == 0 then + -- ... + end + local v1 = vim.version.parse('1.0.3-pre') + local v2 = vim.version.parse('0.2.1') + if vim.version.cmp(v1, v2) == 0 then + -- ... + end +< + + Note: + Per semver, build metadata is ignored when comparing two + otherwise-equivalent versions. Parameters: ~ - • {v1} (string) Version. - • {v2} (string) Version to compare with v1. - • {opts} (table|nil) Optional keyword arguments: - • strict (boolean): see `semver.parse` for details. Defaults - to false. + • {v1} Version|number[] Version object. + • {v2} Version|number[] Version to compare with `v1` . Return: ~ - (integer) `-1` if `v1 < v2`, `0` if `v1 == v2`, `1` if `v1 > v2`. + (integer) -1 if `v1 < v2`, 0 if `v1 == v2`, 1 if `v1 > v2`. eq({v1}, {v2}) *vim.version.eq()* - Returns `true` if `v1` are `v2` are equal versions. + Returns `true` if the given versions are equal. Parameters: ~ - • {v1} (string) - • {v2} (string) + • {v1} Version|number[] + • {v2} Version|number[] Return: ~ (boolean) gt({v1}, {v2}) *vim.version.gt()* - Returns `true` if `v1` is greater than `v2` . + Returns `true` if `v1 > v2` . Parameters: ~ - • {v1} (string) - • {v2} (string) + • {v1} Version|number[] + • {v2} Version|number[] Return: ~ (boolean) +last({versions}) *vim.version.last()* + TODO: generalize this, move to func.lua + + Parameters: ~ + • {versions} Version [] + + Return: ~ + Version ?|ni + lt({v1}, {v2}) *vim.version.lt()* - Returns `true` if `v1` is less than `v2` . + Returns `true` if `v1 < v2` . Parameters: ~ - • {v1} (string) - • {v2} (string) + • {v1} Version|number[] + • {v2} Version|number[] Return: ~ (boolean) parse({version}, {opts}) *vim.version.parse()* - Parses a semantic version string. - - Ignores leading "v" and surrounding whitespace, e.g. " - v1.0.1-rc1+build.2", "1.0.1-rc1+build.2", "v1.0.1-rc1+build.2" and - "v1.0.1-rc1+build.2 " are all parsed as: > + Parses a semantic version string and returns a version object which can be + used with other `vim.version` functions. For example "1.0.1-rc1+build.2" returns: > { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" } < Parameters: ~ - • {version} (string) Version string to be parsed. + • {version} (string) Version string to parse. • {opts} (table|nil) Optional keyword arguments: - • strict (boolean): Default false. If `true` , no coercion is attempted on input not strictly - conforming to semver v2.0.0 ( https://semver.org/spec/v2.0.0.html ). E.g. `parse("v1.2")` returns nil. + • strict (boolean): Default false. If `true`, no coercion + is attempted on input not conforming to semver v2.0.0. If + `false`, `parse()` attempts to coerce input such as + "1.0", "0-x", "tmux 3.2a" into valid versions. Return: ~ - (table|nil) parsed_version Parsed version table or `nil` if `version` - is invalid. + (table|nil) parsed_version Version object or `nil` if input is invalid. + + See also: ~ + • # https://semver.org/spec/v2.0.0.html + +range({spec}) *vim.version.range()* + Parses a semver |version-range| "spec" and returns a range object: > + + { + from: Version + to: Version + has(v: string|Version) + } +< + + `:has()` checks if a version is in the range (inclusive `from` , exclusive `to` ). Example: >lua + + local r = vim.version.range('1.0.0 - 2.0.0') + print(r:has('1.9.9')) -- true + print(r:has('2.0.0')) -- false +< + + Or use cmp(), eq(), lt(), and gt() to compare `.to` and `.from` directly: >lua + + local r = vim.version.range('1.0.0 - 2.0.0') + print(vim.version.gt({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to)) +< + + Parameters: ~ + • {spec} string Version range "spec" + + See also: ~ + • # https://github.com/npm/node-semver#ranges vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 5ac6db6f84..c326ae15c7 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -65,8 +65,8 @@ NEW FEATURES *news-features* The following new APIs or features were added. -• Added |vim.version| for parsing and comparing version strings conforming to - the semver specification, see |lua-version|. +• Added |lua-version| for parsing and comparing version strings conforming to + the semver specification. • A new environment variable named NVIM_APPNAME enables configuring the directories where Neovim should find its configuration and state files. See diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua index 35629c461f..8d8b0d6da7 100644 --- a/runtime/lua/vim/version.lua +++ b/runtime/lua/vim/version.lua @@ -1,273 +1,390 @@ +--- @defgroup lua-version +--- +--- @brief The \`vim.version\` module provides functions for comparing versions and ranges +--- conforming to the https://semver.org spec. Plugins, and plugin managers, can use this to check +--- available tools and dependencies on the current system. +--- +--- Example: +--- <pre>lua +--- local v = vim.version.parse(vim.fn.system({'tmux', '-V'}), {strict=false}) +--- if vim.version.gt(v, {3, 2, 0}) then +--- -- ... +--- end +--- </pre> +--- +--- \*vim.version()\* returns the version of the current Nvim process. +--- +--- VERSION RANGE SPEC \*version-range\* +--- +--- A version "range spec" defines a semantic version range which can be tested against a version, +--- using |vim.version.range()|. +--- +--- Supported range specs are shown in the following table. +--- Note: suffixed versions (1.2.3-rc1) are not matched. +--- <pre> +--- 1.2.3 is 1.2.3 +--- =1.2.3 is 1.2.3 +--- >1.2.3 greater than 1.2.3 +--- <1.2.3 before 1.2.3 +--- >=1.2.3 at least 1.2.3 +--- ~1.2.3 is >=1.2.3 <1.3.0 "reasonably close to 1.2.3" +--- ^1.2.3 is >=1.2.3 <2.0.0 "compatible with 1.2.3" +--- ^0.2.3 is >=0.2.3 <0.3.0 (0.x.x is special) +--- ^0.0.1 is =0.0.1 (0.0.x is special) +--- ^1.2 is >=1.2.0 <2.0.0 (like ^1.2.0) +--- ~1.2 is >=1.2.0 <1.3.0 (like ~1.2.0) +--- ^1 is >=1.0.0 <2.0.0 "compatible with 1" +--- ~1 same "reasonably close to 1" +--- 1.x same +--- 1.* same +--- 1 same +--- * any version +--- x same +--- +--- 1.2.3 - 2.3.4 is >=1.2.3 <=2.3.4 +--- +--- Partial right: missing pieces treated as x (2.3 => 2.3.x). +--- 1.2.3 - 2.3 is >=1.2.3 <2.4.0 +--- 1.2.3 - 2 is >=1.2.3 <3.0.0 +--- +--- Partial left: missing pieces treated as 0 (1.2 => 1.2.0). +--- 1.2 - 2.3.0 is 1.2.0 - 2.3.0 +--- </pre> + local M = {} ----@private ----@param version string ----@return string -local function create_err_msg(v) - if type(v) == 'string' then - return string.format('invalid version: "%s"', tostring(v)) - end - return string.format('invalid version: %s (%s)', tostring(v), type(v)) +---@class Version +---@field [1] number +---@field [2] number +---@field [3] number +---@field major number +---@field minor number +---@field patch number +---@field prerelease? string +---@field build? string +local Version = {} +Version.__index = Version + +function Version:__index(key) + return type(key) == 'number' and ({ self.major, self.minor, self.patch })[key] or Version[key] end ----@private ---- Throws an error if `version` cannot be parsed. ----@param version string -local function assert_version(version, opt) - local rv = M.parse(version, opt) - if rv == nil then - error(create_err_msg(version)) +function Version:__newindex(key, value) + if key == 1 then + self.major = value + elseif key == 2 then + self.minor = value + elseif key == 3 then + self.patch = value + else + rawset(self, key, value) end - return rv end ----@private ---- Compares the prerelease component of the two versions. -local function cmp_prerelease(v1, v2) - if v1.prerelease and not v2.prerelease then - return -1 +---@param other Version +function Version:__eq(other) + for i = 1, 3 do + if self[i] ~= other[i] then + return false + end end - if not v1.prerelease and v2.prerelease then - return 1 + return self.prerelease == other.prerelease +end + +function Version:__tostring() + local ret = table.concat({ self.major, self.minor, self.patch }, '.') + if self.prerelease then + ret = ret .. '-' .. self.prerelease end - if not v1.prerelease and not v2.prerelease then - return 0 + if self.build then + ret = ret .. '+' .. self.build end + return ret +end - local v1_identifiers = vim.split(v1.prerelease, '.', { plain = true }) - local v2_identifiers = vim.split(v2.prerelease, '.', { plain = true }) - local i = 1 - local max = math.max(vim.tbl_count(v1_identifiers), vim.tbl_count(v2_identifiers)) - while i <= max do - local v1_identifier = v1_identifiers[i] - local v2_identifier = v2_identifiers[i] - if v1_identifier ~= v2_identifier then - local v1_num = tonumber(v1_identifier) - local v2_num = tonumber(v2_identifier) - local is_number = v1_num and v2_num - if is_number then - -- Number comparisons - if not v1_num and v2_num then - return -1 - end - if v1_num and not v2_num then - return 1 - end - if v1_num == v2_num then - return 0 - end - if v1_num > v2_num then - return 1 - end - if v1_num < v2_num then - return -1 - end - else - -- String comparisons - if v1_identifier and not v2_identifier then - return 1 - end - if not v1_identifier and v2_identifier then - return -1 - end - if v1_identifier < v2_identifier then - return -1 - end - if v1_identifier > v2_identifier then - return 1 - end - if v1_identifier == v2_identifier then - return 0 - end - end +---@param other Version +function Version:__lt(other) + for i = 1, 3 do + if self[i] > other[i] then + return false + elseif self[i] < other[i] then + return true end - i = i + 1 end + if self.prerelease and not other.prerelease then + return true + end + if other.prerelease and not self.prerelease then + return false + end + return (self.prerelease or '') < (other.prerelease or '') +end - return 0 +---@param other Version +function Version:__le(other) + return self < other or self == other end ----@private -local function cmp_version_core(v1, v2) - if v1.major == v2.major and v1.minor == v2.minor and v1.patch == v2.patch then - return 0 +--- @private +--- +--- Creates a new Version object. Not public currently. +--- +--- @param version string|number[]|Version +--- @param strict? boolean Reject "1.0", "0-x", "3.2a" or other non-conforming version strings +--- @return Version? +function M._version(version, strict) -- Adapted from https://github.com/folke/lazy.nvim + if type(version) == 'table' then + if version.major then + return setmetatable(vim.deepcopy(version), Version) + end + return setmetatable({ + major = version[1] or 0, + minor = version[2] or 0, + patch = version[3] or 0, + }, Version) + end + + if not strict then -- TODO: add more "scrubbing". + version = version:match('%d[^ ]*') end + + local prerel = version:match('%-([^+]*)') + local prerel_strict = version:match('%-([0-9A-Za-z-]*)') if - v1.major > v2.major - or (v1.major == v2.major and v1.minor > v2.minor) - or (v1.major == v2.major and v1.minor == v2.minor and v1.patch > v2.patch) + strict + and prerel + and (prerel_strict == nil or prerel_strict == '' or not vim.startswith(prerel, prerel_strict)) then - return 1 + return nil -- Invalid prerelease. end - return -1 -end + local build = prerel and version:match('%-[^+]*%+(.*)$') or version:match('%+(.*)$') + local major, minor, patch = + version:match('^v?(%d+)%.?(%d*)%.?(%d*)' .. (strict and (prerel and '%-' or '$') or '')) ---- Compares two strings (`v1` and `v2`) in semver format. ----@param v1 string Version. ----@param v2 string Version to compare with v1. ----@param opts table|nil Optional keyword arguments: ---- - strict (boolean): see `semver.parse` for details. Defaults to false. ----@return integer `-1` if `v1 < v2`, `0` if `v1 == v2`, `1` if `v1 > v2`. -function M.cmp(v1, v2, opts) - opts = opts or { strict = false } - local v1_parsed = assert_version(v1, opts) - local v2_parsed = assert_version(v2, opts) + if + (not strict and major) + or (major and minor and patch and major ~= '' and minor ~= '' and patch ~= '') + then + return setmetatable({ + major = tonumber(major), + minor = minor == '' and 0 or tonumber(minor), + patch = patch == '' and 0 or tonumber(patch), + prerelease = prerel ~= '' and prerel or nil, + build = build ~= '' and build or nil, + }, Version) + end +end - local result = cmp_version_core(v1_parsed, v2_parsed) - if result == 0 then - result = cmp_prerelease(v1_parsed, v2_parsed) +---TODO: generalize this, move to func.lua +--- +---@generic T: Version +---@param versions T[] +---@return T? +function M.last(versions) + local last = versions[1] + for i = 2, #versions do + if versions[i] > last then + last = versions[i] + end end - return result + return last end ----@private ----@param labels string Prerelease and build component of semantic version string e.g. "-rc1+build.0". ----@return string|nil -local function parse_prerelease(labels) - -- This pattern matches "-(alpha)+build.15". - -- '^%-[%w%.]+$' - local result = labels:match('^%-([%w%.]+)+.+$') - if result then - return result +---@class Range +---@field from Version +---@field to? Version +local Range = {} + +--- @private +--- +---@param version string|Version +function Range:has(version) + if type(version) == 'string' then + ---@diagnostic disable-next-line: cast-local-type + version = M.parse(version) end - -- This pattern matches "-(alpha)". - result = labels:match('^%-([%w%.]+)') - if result then - return result + if version then + if version.prerelease ~= self.from.prerelease then + return false + end + return version >= self.from and (self.to == nil or version < self.to) end - - return nil end ----@private ----@param labels string Prerelease and build component of semantic version string e.g. "-rc1+build.0". ----@return string|nil -local function parse_build(labels) - -- Pattern matches "-alpha+(build.15)". - local result = labels:match('^%-[%w%.]+%+([%w%.]+)$') - if result then - return result +--- Parses a semver |version-range| "spec" and returns a range object: +--- <pre> +--- { +--- from: Version +--- to: Version +--- has(v: string|Version) +--- } +--- </pre> +--- +--- `:has()` checks if a version is in the range (inclusive `from`, exclusive `to`). Example: +--- <pre>lua +--- local r = vim.version.range('1.0.0 - 2.0.0') +--- print(r:has('1.9.9')) -- true +--- print(r:has('2.0.0')) -- false +--- </pre> +--- +--- Or use cmp(), eq(), lt(), and gt() to compare `.to` and `.from` directly: +--- <pre>lua +--- local r = vim.version.range('1.0.0 - 2.0.0') +--- print(vim.version.gt({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to)) +--- </pre> +--- +--- @see # https://github.com/npm/node-semver#ranges +--- +--- @param spec string Version range "spec" +function M.range(spec) -- Adapted from https://github.com/folke/lazy.nvim + if spec == '*' or spec == '' then + return setmetatable({ from = M.parse('0.0.0') }, { __index = Range }) end - -- Pattern matches "+(build.15)". - result = labels:match('^%+([%w%.]+)$') - if result then - return result + ---@type number? + local hyphen = spec:find(' - ', 1, true) + if hyphen then + local a = spec:sub(1, hyphen - 1) + local b = spec:sub(hyphen + 3) + local parts = vim.split(b, '.', { plain = true }) + local ra = M.range(a) + local rb = M.range(b) + return setmetatable({ + from = ra and ra.from, + to = rb and (#parts == 3 and rb.from or rb.to), + }, { __index = Range }) + end + ---@type string, string + local mods, version = spec:lower():match('^([%^=>~]*)(.*)$') + version = version:gsub('%.[%*x]', '') + local parts = vim.split(version:gsub('%-.*', ''), '.', { plain = true }) + if #parts < 3 and mods == '' then + mods = '~' end - return nil -end - ----@private ---- Extracts the major, minor, patch and preprelease and build components from ---- `version`. ----@param version string Version string -local function extract_components_strict(version) - local major, minor, patch, prerelease_and_build = version:match('^v?(%d+)%.(%d+)%.(%d+)(.*)$') - return tonumber(major), tonumber(minor), tonumber(patch), prerelease_and_build -end - ----@private ---- Extracts the major, minor, patch and preprelease and build components from ---- `version`. When `minor` and `patch` components are not found (nil), coerce ---- them to 0. ----@param version string Version string -local function extract_components_loose(version) - local major, minor, patch, prerelease_and_build = version:match('^v?(%d+)%.?(%d*)%.?(%d*)(.*)$') - major = tonumber(major) - minor = tonumber(minor) or 0 - patch = tonumber(patch) or 0 - return major, minor, patch, prerelease_and_build + local semver = M.parse(version) + if semver then + local from = semver + local to = vim.deepcopy(semver) + if mods == '' or mods == '=' then + to.patch = to.patch + 1 + elseif mods == '>' then + from.patch = from.patch + 1 + to = nil ---@diagnostic disable-line: cast-local-type + elseif mods == '>=' then + to = nil ---@diagnostic disable-line: cast-local-type + elseif mods == '~' then + if #parts >= 2 then + to[2] = to[2] + 1 + to[3] = 0 + else + to[1] = to[1] + 1 + to[2] = 0 + to[3] = 0 + end + elseif mods == '^' then + for i = 1, 3 do + if to[i] ~= 0 then + to[i] = to[i] + 1 + for j = i + 1, 3 do + to[j] = 0 + end + break + end + end + end + return setmetatable({ from = from, to = to }, { __index = Range }) + end end ---@private ---- Validates the prerelease and build string e.g. "-rc1+build.0". If the ---- prerelease, build or both are valid forms then it will return true, if it ---- is not of any valid form, it will return false. ----@param prerelease_and_build string ----@return boolean -local function is_prerelease_and_build_valid(prerelease_and_build) - if prerelease_and_build == '' then - return true +---@param v string|Version +---@return string +local function create_err_msg(v) + if type(v) == 'string' then + return string.format('invalid version: "%s"', tostring(v)) + elseif type(v) == 'table' and v.major then + return string.format('invalid version: %s', vim.inspect(v)) end - local has_build = parse_build(prerelease_and_build) ~= nil - local has_prerelease = parse_prerelease(prerelease_and_build) ~= nil - local has_prerelease_and_build = has_prerelease and has_build - return has_build or has_prerelease or has_prerelease_and_build + return string.format('invalid version: %s (%s)', tostring(v), type(v)) end ---- Parses a semantic version string. +--- Parses and compares two version version objects (the result of |vim.version.parse()|, or +--- specified literally as a `{major, minor, patch}` tuple, e.g. `{1, 0, 3}`). --- ---- Ignores leading "v" and surrounding whitespace, e.g. " v1.0.1-rc1+build.2", ---- "1.0.1-rc1+build.2", "v1.0.1-rc1+build.2" and "v1.0.1-rc1+build.2 " are all parsed as: ---- <pre> ---- { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" } +--- Example: +--- <pre>lua +--- if vim.version.cmp({1,0,3}, {0,2,1}) == 0 then +--- -- ... +--- end +--- local v1 = vim.version.parse('1.0.3-pre') +--- local v2 = vim.version.parse('0.2.1') +--- if vim.version.cmp(v1, v2) == 0 then +--- -- ... +--- end --- </pre> --- ----@param version string Version string to be parsed. ----@param opts table|nil Optional keyword arguments: ---- - strict (boolean): Default false. If `true`, no coercion is attempted on ---- input not strictly conforming to semver v2.0.0 ---- (https://semver.org/spec/v2.0.0.html). E.g. `parse("v1.2")` returns nil. ----@return table|nil parsed_version Parsed version table or `nil` if `version` is invalid. -function M.parse(version, opts) - if type(version) ~= 'string' then - error(create_err_msg(version)) - end - - opts = opts or { strict = false } - - version = vim.trim(version) - - local extract_components = opts.strict and extract_components_strict or extract_components_loose - local major, minor, patch, prerelease_and_build = extract_components(version) - - -- If major is nil then that means that the version does not begin with a - -- digit with or without a "v" prefix. - if major == nil or not is_prerelease_and_build_valid(prerelease_and_build) then - return nil +--- @note Per semver, build metadata is ignored when comparing two otherwise-equivalent versions. +--- +---@param v1 Version|number[] Version object. +---@param v2 Version|number[] Version to compare with `v1`. +---@return integer -1 if `v1 < v2`, 0 if `v1 == v2`, 1 if `v1 > v2`. +function M.cmp(v1, v2) + local v1_parsed = assert(M._version(v1), create_err_msg(v1)) + local v2_parsed = assert(M._version(v2), create_err_msg(v1)) + if v1_parsed == v2_parsed then + return 0 end - - local prerelease = nil - local build = nil - if prerelease_and_build ~= nil then - prerelease = parse_prerelease(prerelease_and_build) - build = parse_build(prerelease_and_build) + if v1_parsed > v2_parsed then + return 1 end - - return { - major = major, - minor = minor, - patch = patch, - prerelease = prerelease, - build = build, - } + return -1 end ----Returns `true` if `v1` are `v2` are equal versions. ----@param v1 string ----@param v2 string +---Returns `true` if the given versions are equal. +---@param v1 Version|number[] +---@param v2 Version|number[] ---@return boolean function M.eq(v1, v2) return M.cmp(v1, v2) == 0 end ----Returns `true` if `v1` is less than `v2`. ----@param v1 string ----@param v2 string +---Returns `true` if `v1 < v2`. +---@param v1 Version|number[] +---@param v2 Version|number[] ---@return boolean function M.lt(v1, v2) return M.cmp(v1, v2) == -1 end ----Returns `true` if `v1` is greater than `v2`. ----@param v1 string ----@param v2 string +---Returns `true` if `v1 > v2`. +---@param v1 Version|number[] +---@param v2 Version|number[] ---@return boolean function M.gt(v1, v2) return M.cmp(v1, v2) == 1 end +--- Parses a semantic version string and returns a version object which can be used with other +--- `vim.version` functions. For example "1.0.1-rc1+build.2" returns: +--- <pre> +--- { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" } +--- </pre> +--- +--- @see # https://semver.org/spec/v2.0.0.html +--- +---@param version string Version string to parse. +---@param opts table|nil Optional keyword arguments: +--- - strict (boolean): Default false. If `true`, no coercion is attempted on +--- input not conforming to semver v2.0.0. If `false`, `parse()` attempts to +--- coerce input such as "1.0", "0-x", "tmux 3.2a" into valid versions. +---@return table|nil parsed_version Version object or `nil` if input is invalid. +function M.parse(version, opts) + assert(type(version) == 'string', create_err_msg(version)) + opts = opts or { strict = false } + return M._version(version, opts.strict) +end + setmetatable(M, { __call = function() return vim.fn.api_info().version diff --git a/test/functional/lua/version_spec.lua b/test/functional/lua/version_spec.lua index b68727ca77..014fea5272 100644 --- a/test/functional/lua/version_spec.lua +++ b/test/functional/lua/version_spec.lua @@ -1,186 +1,133 @@ local helpers = require('test.functional.helpers')(after_each) local clear = helpers.clear local eq = helpers.eq +local ok = helpers.ok local exec_lua = helpers.exec_lua local matches = helpers.matches local pcall_err = helpers.pcall_err -local version = require('vim.version') - -local function quote_empty(s) - return tostring(s) == '' and '""' or tostring(s) +local function v(ver) + return vim.version._version(ver) end describe('version', function() + it('package', function() clear() eq({ major = 42, minor = 3, patch = 99 }, exec_lua("return vim.version.parse('v42.3.99')")) end) + describe('_version()', function() + local tests = { + ['v1.2.3'] = { major = 1, minor = 2, patch = 3 }, + ['v1.2'] = { major = 1, minor = 2, patch = 0 }, + ['v1.2.3-prerelease'] = { major = 1, minor = 2, patch = 3, prerelease = 'prerelease' }, + ['v1.2-prerelease'] = { major = 1, minor = 2, patch = 0, prerelease = 'prerelease' }, + ['v1.2.3-prerelease+build'] = { major = 1, minor = 2, patch = 3, prerelease = 'prerelease', build = 'build' }, + ['1.2.3+build'] = { major = 1, minor = 2, patch = 3, build = 'build' }, + } + for input, output in pairs(tests) do + it('parses ' .. input, function() + eq(output, v(input)) + end) + end + end) + + describe('range', function() + local tests = { + ['1.2.3'] = { from = { 1, 2, 3 }, to = { 1, 2, 4 } }, + ['1.2'] = { from = { 1, 2, 0 }, to = { 1, 3, 0 } }, + ['=1.2.3'] = { from = { 1, 2, 3 }, to = { 1, 2, 4 } }, + ['>1.2.3'] = { from = { 1, 2, 4 } }, + ['>=1.2.3'] = { from = { 1, 2, 3 } }, + ['~1.2.3'] = { from = { 1, 2, 3 }, to = { 1, 3, 0 } }, + ['^1.2.3'] = { from = { 1, 2, 3 }, to = { 2, 0, 0 } }, + ['^0.2.3'] = { from = { 0, 2, 3 }, to = { 0, 3, 0 } }, + ['^0.0.1'] = { from = { 0, 0, 1 }, to = { 0, 0, 2 } }, + ['^1.2'] = { from = { 1, 2, 0 }, to = { 2, 0, 0 } }, + ['~1.2'] = { from = { 1, 2, 0 }, to = { 1, 3, 0 } }, + ['~1'] = { from = { 1, 0, 0 }, to = { 2, 0, 0 } }, + ['^1'] = { from = { 1, 0, 0 }, to = { 2, 0, 0 } }, + ['1.*'] = { from = { 1, 0, 0 }, to = { 2, 0, 0 } }, + ['1'] = { from = { 1, 0, 0 }, to = { 2, 0, 0 } }, + ['1.x'] = { from = { 1, 0, 0 }, to = { 2, 0, 0 } }, + ['1.2.x'] = { from = { 1, 2, 0 }, to = { 1, 3, 0 } }, + ['1.2.*'] = { from = { 1, 2, 0 }, to = { 1, 3, 0 } }, + ['*'] = { from = { 0, 0, 0 } }, + ['1.2 - 2.3.0'] = { from = { 1, 2, 0 }, to = { 2, 3, 0 } }, + ['1.2.3 - 2.3.4'] = { from = { 1, 2, 3 }, to = { 2, 3, 4 } }, + ['1.2.3 - 2'] = { from = { 1, 2, 3 }, to = { 3, 0, 0 } }, + } + for input, output in pairs(tests) do + output.from = v(output.from) + output.to = output.to and v(output.to) + local range = vim.version.range(input) + + it('parses ' .. input, function() + eq(output, range) + end) + + it('[from] in range ' .. input, function() + assert(range:has(output.from)) + end) + + it('[from-1] not in range ' .. input, function() + local lower = vim.deepcopy(range.from) + lower.major = lower.major - 1 + assert(not range:has(lower)) + end) + + it('[to] not in range ' .. input .. ' to:' .. tostring(range.to), function() + if range.to then + assert(not (range.to < range.to)) + assert(not range:has(range.to)) + end + end) + end + + it('handles prerelease', function() + assert(not vim.version.range('1.2.3'):has('1.2.3-alpha')) + assert(vim.version.range('1.2.3-alpha'):has('1.2.3-alpha')) + assert(not vim.version.range('1.2.3-alpha'):has('1.2.3-beta')) + end) + end) + describe('cmp()', function() local testcases = { - { - desc = '(v1 < v2)', - v1 = 'v0.0.99', - v2 = 'v9.0.0', - want = -1, - }, - { - desc = '(v1 < v2)', - v1 = 'v0.4.0', - v2 = 'v0.9.99', - want = -1, - }, - { - desc = '(v1 < v2)', - v1 = 'v0.2.8', - v2 = 'v1.0.9', - want = -1, - }, - { - desc = '(v1 == v2)', - v1 = 'v0.0.0', - v2 = 'v0.0.0', - want = 0, - }, - { - desc = '(v1 > v2)', - v1 = 'v9.0.0', - v2 = 'v0.9.0', - want = 1, - }, - { - desc = '(v1 > v2)', - v1 = 'v0.9.0', - v2 = 'v0.0.0', - want = 1, - }, - { - desc = '(v1 > v2)', - v1 = 'v0.0.9', - v2 = 'v0.0.0', - want = 1, - }, - { - desc = '(v1 < v2) when v1 has prerelease', - v1 = 'v1.0.0-alpha', - v2 = 'v1.0.0', - want = -1, - }, - { - desc = '(v1 > v2) when v2 has prerelease', - v1 = '1.0.0', - v2 = '1.0.0-alpha', - want = 1, - }, - { - desc = '(v1 > v2) when v1 has a higher number identifier', - v1 = '1.0.0-2', - v2 = '1.0.0-1', - want = 1, - }, - { - desc = '(v1 < v2) when v2 has a higher number identifier', - v1 = '1.0.0-2', - v2 = '1.0.0-9', - want = -1, - }, - { - desc = '(v1 < v2) when v2 has more identifiers', - v1 = '1.0.0-2', - v2 = '1.0.0-2.0', - want = -1, - }, - { - desc = '(v1 > v2) when v1 has more identifiers', - v1 = '1.0.0-2.0', - v2 = '1.0.0-2', - want = 1, - }, - { - desc = '(v1 == v2) when v2 has same numeric identifiers', - v1 = '1.0.0-2.0', - v2 = '1.0.0-2.0', - want = 0, - }, - { - desc = '(v1 == v2) when v2 has same alphabet identifiers', - v1 = '1.0.0-alpha', - v2 = '1.0.0-alpha', - want = 0, - }, - { - desc = '(v1 < v2) when v2 has an alphabet identifier with higher ASCII sort order', - v1 = '1.0.0-alpha', - v2 = '1.0.0-beta', - want = -1, - }, - { - desc = '(v1 > v2) when v1 has an alphabet identifier with higher ASCII sort order', - v1 = '1.0.0-beta', - v2 = '1.0.0-alpha', - want = 1, - }, - { - desc = '(v1 < v2) when v2 has prerelease and number identifer', - v1 = '1.0.0-alpha', - v2 = '1.0.0-alpha.1', - want = -1, - }, - { - desc = '(v1 > v2) when v1 has prerelease and number identifer', - v1 = '1.0.0-alpha.1', - v2 = '1.0.0-alpha', - want = 1, - }, - { - desc = '(v1 > v2) when v1 has an additional alphabet identifier', - v1 = '1.0.0-alpha.beta', - v2 = '1.0.0-alpha', - want = 1, - }, - { - desc = '(v1 < v2) when v2 has an additional alphabet identifier', - v1 = '1.0.0-alpha', - v2 = '1.0.0-alpha.beta', - want = -1, - }, - { - desc = '(v1 < v2) when v2 has an a first alphabet identifier with higher precedence', - v1 = '1.0.0-alpha.beta', - v2 = '1.0.0-beta', - want = -1, - }, - { - desc = '(v1 > v2) when v1 has an a first alphabet identifier with higher precedence', - v1 = '1.0.0-beta', - v2 = '1.0.0-alpha.beta', - want = 1, - }, - { - desc = '(v1 < v2) when v2 has an additional number identifer', - v1 = '1.0.0-beta', - v2 = '1.0.0-beta.2', - want = -1, - }, - { - desc = '(v1 < v2) when v2 has same first alphabet identifier but has a higher number identifer', - v1 = '1.0.0-beta.2', - v2 = '1.0.0-beta.11', - want = -1, - }, - { - desc = '(v1 < v2) when v2 has higher alphabet precedence', - v1 = '1.0.0-beta.11', - v2 = '1.0.0-rc.1', - want = -1, - }, + { v1 = 'v0.0.99', v2 = 'v9.0.0', want = -1, }, + { v1 = 'v0.4.0', v2 = 'v0.9.99', want = -1, }, + { v1 = 'v0.2.8', v2 = 'v1.0.9', want = -1, }, + { v1 = 'v0.0.0', v2 = 'v0.0.0', want = 0, }, + { v1 = 'v9.0.0', v2 = 'v0.9.0', want = 1, }, + { v1 = 'v0.9.0', v2 = 'v0.0.0', want = 1, }, + { v1 = 'v0.0.9', v2 = 'v0.0.0', want = 1, }, + { v1 = 'v1.0.0-alpha', v2 = 'v1.0.0', want = -1, }, + { v1 = '1.0.0', v2 = '1.0.0-alpha', want = 1, }, + { v1 = '1.0.0-2', v2 = '1.0.0-1', want = 1, }, + { v1 = '1.0.0-2', v2 = '1.0.0-9', want = -1, }, + { v1 = '1.0.0-2', v2 = '1.0.0-2.0', want = -1, }, + { v1 = '1.0.0-2.0', v2 = '1.0.0-2', want = 1, }, + { v1 = '1.0.0-2.0', v2 = '1.0.0-2.0', want = 0, }, + { v1 = '1.0.0-alpha', v2 = '1.0.0-alpha', want = 0, }, + { v1 = '1.0.0-alpha', v2 = '1.0.0-beta', want = -1, }, + { v1 = '1.0.0-beta', v2 = '1.0.0-alpha', want = 1, }, + { v1 = '1.0.0-alpha', v2 = '1.0.0-alpha.1', want = -1, }, + { v1 = '1.0.0-alpha.1', v2 = '1.0.0-alpha', want = 1, }, + { v1 = '1.0.0-alpha.beta', v2 = '1.0.0-alpha', want = 1, }, + { v1 = '1.0.0-alpha', v2 = '1.0.0-alpha.beta', want = -1, }, + { v1 = '1.0.0-alpha.beta', v2 = '1.0.0-beta', want = -1, }, + { v1 = '1.0.0-beta', v2 = '1.0.0-alpha.beta', want = 1, }, + { v1 = '1.0.0-beta', v2 = '1.0.0-beta.2', want = -1, }, + -- TODO + -- { v1 = '1.0.0-beta.2', v2 = '1.0.0-beta.11', want = -1, }, + { v1 = '1.0.0-beta.11', v2 = '1.0.0-rc.1', want = -1, }, } for _, tc in ipairs(testcases) do - it( - string.format('%d %s (v1 = %s, v2 = %s)', tc.want, tc.desc, tc.v1, tc.v2), + local msg = function(s) return ('v1 %s v2'):format(s == 0 and '==' or (s == 1 and '>' or '<')) end + it(string.format('(v1 = %s, v2 = %s)', tc.v1, tc.v2), function() - eq(tc.want, version.cmp(tc.v1, tc.v2, { strict = true })) + local rv = vim.version.cmp(tc.v1, tc.v2, { strict = true }) + ok(tc.want == rv, msg(tc.want), msg(rv)) end ) end @@ -189,64 +136,19 @@ describe('version', function() describe('parse()', function() describe('strict=true', function() local testcases = { - { - desc = 'version without leading "v"', - version = '10.20.123', - want = { - major = 10, - minor = 20, - patch = 123, - prerelease = nil, - build = nil, - }, - }, - { - desc = 'valid version with leading "v"', - version = 'v1.2.3', - want = { major = 1, minor = 2, patch = 3 }, - }, - { - desc = 'valid version with leading "v" and whitespace', - version = ' v1.2.3', - want = { major = 1, minor = 2, patch = 3 }, - }, - { - desc = 'valid version with leading "v" and trailing whitespace', - version = 'v1.2.3 ', - want = { major = 1, minor = 2, patch = 3 }, - }, - { - desc = 'version with prerelease', - version = '1.2.3-alpha', - want = { major = 1, minor = 2, patch = 3, prerelease = 'alpha' }, - }, - { - desc = 'version with prerelease with additional identifiers', - version = '1.2.3-alpha.1', - want = { major = 1, minor = 2, patch = 3, prerelease = 'alpha.1' }, - }, - { - desc = 'version with build', - version = '1.2.3+build.15', - want = { major = 1, minor = 2, patch = 3, build = 'build.15' }, - }, - { - desc = 'version with prerelease and build', - version = '1.2.3-rc1+build.15', - want = { - major = 1, - minor = 2, - patch = 3, - prerelease = 'rc1', - build = 'build.15', - }, - }, + { desc = 'Nvim version', version = 'v0.9.0-dev-1233+g210120dde81e', want = { major = 0, minor = 9, patch = 0, prerelease = 'dev-1233', build = 'g210120dde81e', }, }, + { desc = 'no v', version = '10.20.123', want = { major = 10, minor = 20, patch = 123, prerelease = nil, build = nil, }, }, + { desc = 'with v', version = 'v1.2.3', want = { major = 1, minor = 2, patch = 3 }, }, + { desc = 'prerelease', version = '1.2.3-alpha', want = { major = 1, minor = 2, patch = 3, prerelease = 'alpha' }, }, + { desc = 'prerelease.x', version = '1.2.3-alpha.1', want = { major = 1, minor = 2, patch = 3, prerelease = 'alpha.1' }, }, + { desc = 'build.x', version = '1.2.3+build.15', want = { major = 1, minor = 2, patch = 3, build = 'build.15' }, }, + { desc = 'prerelease and build', version = '1.2.3-rc1+build.15', want = { major = 1, minor = 2, patch = 3, prerelease = 'rc1', build = 'build.15', }, }, } for _, tc in ipairs(testcases) do it( - string.format('for %q: version = %q', tc.desc, tc.version), + string.format('%q: version = %q', tc.desc, tc.version), function() - eq(tc.want, version.parse(tc.version, { strict = true })) + eq(tc.want, vim.version.parse(tc.version)) end ) end @@ -254,32 +156,19 @@ describe('version', function() describe('strict=false', function() local testcases = { - { - desc = 'version missing patch version', - version = '1.2', - want = { major = 1, minor = 2, patch = 0 }, - }, - { - desc = 'version missing minor and patch version', - version = '1', - want = { major = 1, minor = 0, patch = 0 }, - }, - { - desc = 'version missing patch version with prerelease', - version = '1.1-0', - want = { major = 1, minor = 1, patch = 0, prerelease = '0' }, - }, - { - desc = 'version missing minor and patch version with prerelease', - version = '1-1.0', - want = { major = 1, minor = 0, patch = 0, prerelease = '1.0' }, - }, + { version = '1.2', want = { major = 1, minor = 2, patch = 0 }, }, + { version = '1', want = { major = 1, minor = 0, patch = 0 }, }, + { version = '1.1-0', want = { major = 1, minor = 1, patch = 0, prerelease = '0' }, }, + { version = '1-1.0', want = { major = 1, minor = 0, patch = 0, prerelease = '1.0' }, }, + { version = 'v1.2.3 ', want = { major = 1, minor = 2, patch = 3 }, }, + { version = ' v1.2.3', want = { major = 1, minor = 2, patch = 3 }, }, + { version = 'tmux 3.2a', want = { major = 3, minor = 2, patch = 0, }, }, } for _, tc in ipairs(testcases) do it( - string.format('for %q: version = %q', tc.desc, tc.version), + string.format('version = %q', tc.version), function() - eq(tc.want, version.parse(tc.version, { strict = false })) + eq(tc.want, vim.version.parse(tc.version, { strict = false })) end ) end @@ -287,22 +176,29 @@ describe('version', function() describe('invalid semver', function() local testcases = { - { desc = 'a word', version = 'foo' }, - { desc = 'empty string', version = '' }, - { desc = 'trailing period character', version = '0.0.0.' }, - { desc = 'leading period character', version = '.0.0.0' }, - { desc = 'negative major version', version = '-1.0.0' }, - { desc = 'negative minor version', version = '0.-1.0' }, - { desc = 'negative patch version', version = '0.0.-1' }, - { desc = 'leading invalid string', version = 'foobar1.2.3' }, - { desc = 'trailing invalid string', version = '1.2.3foobar' }, - { desc = 'an invalid prerelease', version = '1.2.3-%?' }, - { desc = 'an invalid build', version = '1.2.3+%?' }, - { desc = 'build metadata before prerelease', version = '1.2.3+build.0-rc1' }, + { version = 'foo' }, + { version = '' }, + { version = '0.0.0.' }, + { version = '.0.0.0' }, + { version = '-1.0.0' }, + { version = '0.-1.0' }, + { version = '0.0.-1' }, + { version = 'foobar1.2.3' }, + { version = '1.2.3foobar' }, + { version = '1.2.3-%?' }, + { version = '1.2.3+%?' }, + { version = '1.2.3+build.0-rc1' }, + { version = '3.2a', }, + { version = 'tmux 3.2a', }, } + + local function quote_empty(s) + return tostring(s) == '' and '""' or tostring(s) + end + for _, tc in ipairs(testcases) do - it(string.format('(%s): %s', tc.desc, quote_empty(tc.version)), function() - eq(nil, version.parse(tc.version, { strict = true })) + it(quote_empty(tc.version), function() + eq(nil, vim.version.parse(tc.version, { strict = true })) end) end end) @@ -319,21 +215,42 @@ describe('version', function() it(string.format('(%s): %s', tc.desc, tostring(tc.version)), function() local expected = string.format(type(tc.version) == 'string' and 'invalid version: "%s"' or 'invalid version: %s', tostring(tc.version)) - matches(expected, pcall_err(version.parse, tc.version, { strict = true })) + matches(expected, pcall_err(vim.version.parse, tc.version, { strict = true })) end) end end) end) + it('relational metamethods (== < >)', function() + assert(v('v1.2.3') == v('1.2.3')) + assert(not (v('v1.2.3') < v('1.2.3'))) + assert(v('v1.2.3') > v('1.2.3-prerelease')) + assert(v('v1.2.3-alpha') < v('1.2.3-beta')) + assert(v('v1.2.3-prerelease') < v('1.2.3')) + assert(v('v1.2.3') >= v('1.2.3')) + assert(v('v1.2.3') >= v('1.0.3')) + assert(v('v1.2.3') >= v('1.2.2')) + assert(v('v1.2.3') > v('1.2.2')) + assert(v('v1.2.3') > v('1.0.3')) + eq(vim.version.last({ v('1.2.3'), v('2.0.0') }), v('2.0.0')) + eq(vim.version.last({ v('2.0.0'), v('1.2.3') }), v('2.0.0')) + end) + it('lt()', function() - eq(true, version.lt('1', '2')) + eq(true, vim.version.lt('1', '2')) + eq(false, vim.version.lt({3}, {0, 7, 4})) + eq(false, vim.version.lt({major=3, minor=3, patch=0}, {3, 2, 0})) end) it('gt()', function() - eq(true, version.gt('2', '1')) + eq(true, vim.version.gt('2', '1')) + eq(true, vim.version.gt({3}, {0, 7, 4})) + eq(true, vim.version.gt({major=3, minor=3, patch=0}, {3, 2, 0})) end) it('eq()', function() - eq(true, version.eq('2', '2')) + eq(true, vim.version.eq('2', '2')) + eq(true, vim.version.eq({3, 1, 0}, '3.1.0')) + eq(true, vim.version.eq({major=3, minor=3, patch=0}, {3, 3, 0})) end) end) diff --git a/test/functional/terminal/buffer_spec.lua b/test/functional/terminal/buffer_spec.lua index 676be151ee..b983ea89d5 100644 --- a/test/functional/terminal/buffer_spec.lua +++ b/test/functional/terminal/buffer_spec.lua @@ -202,7 +202,7 @@ describe(':terminal buffer', function() -- Save the buffer number of the terminal for later testing. local tbuf = eval('bufnr("%")') - local exitcmd = helpers.is_os('win') + local exitcmd = is_os('win') and "['cmd', '/c', 'exit']" or "['sh', '-c', 'exit']" source([[ |