diff options
Diffstat (limited to 'runtime')
| -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 | 267 |
4 files changed, 318 insertions, 129 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 e79acf079b..8d8b0d6da7 100644 --- a/runtime/lua/vim/version.lua +++ b/runtime/lua/vim/version.lua @@ -1,9 +1,59 @@ -local M = {} +--- @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 LazyM = {} -M.LazyM = LazyM +local M = {} ----@class Semver +---@class Version ---@field [1] number ---@field [2] number ---@field [3] number @@ -12,14 +62,14 @@ M.LazyM = LazyM ---@field patch number ---@field prerelease? string ---@field build? string -local Semver = {} -Semver.__index = Semver +local Version = {} +Version.__index = Version -function Semver:__index(key) - return type(key) == 'number' and ({ self.major, self.minor, self.patch })[key] or Semver[key] +function Version:__index(key) + return type(key) == 'number' and ({ self.major, self.minor, self.patch })[key] or Version[key] end -function Semver:__newindex(key, value) +function Version:__newindex(key, value) if key == 1 then self.major = value elseif key == 2 then @@ -31,8 +81,8 @@ function Semver:__newindex(key, value) end end ----@param other Semver -function Semver:__eq(other) +---@param other Version +function Version:__eq(other) for i = 1, 3 do if self[i] ~= other[i] then return false @@ -41,7 +91,7 @@ function Semver:__eq(other) return self.prerelease == other.prerelease end -function Semver:__tostring() +function Version:__tostring() local ret = table.concat({ self.major, self.minor, self.patch }, '.') if self.prerelease then ret = ret .. '-' .. self.prerelease @@ -52,8 +102,8 @@ function Semver:__tostring() return ret end ----@param other Semver -function Semver:__lt(other) +---@param other Version +function Version:__lt(other) for i = 1, 3 do if self[i] > other[i] then return false @@ -70,21 +120,32 @@ function Semver:__lt(other) return (self.prerelease or '') < (other.prerelease or '') end ----@param other Semver -function Semver:__le(other) +---@param other Version +function Version:__le(other) return self < other or self == other end ----@param version string|number[] ----@param strict? boolean Reject "1.0", "0-x" or other non-conforming version strings ----@return Semver? -function LazyM.version(version, strict) +--- @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, - }, Semver) + }, Version) + end + + if not strict then -- TODO: add more "scrubbing". + version = version:match('%d[^ ]*') end local prerel = version:match('%-([^+]*)') @@ -110,11 +171,13 @@ function LazyM.version(version, strict) patch = patch == '' and 0 or tonumber(patch), prerelease = prerel ~= '' and prerel or nil, build = build ~= '' and build or nil, - }, Semver) + }, Version) end end ----@generic T: Semver +---TODO: generalize this, move to func.lua +--- +---@generic T: Version ---@param versions T[] ---@return T? function M.last(versions) @@ -127,13 +190,15 @@ function M.last(versions) return last end ----@class SemverRange ----@field from Semver ----@field to? Semver +---@class Range +---@field from Version +---@field to? Version local Range = {} ----@param version string|Semver -function Range:matches(version) +--- @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) @@ -146,8 +211,32 @@ function Range:matches(version) end end ----@param spec string -function LazyM.range(spec) +--- 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 @@ -158,8 +247,8 @@ function LazyM.range(spec) local a = spec:sub(1, hyphen - 1) local b = spec:sub(hyphen + 3) local parts = vim.split(b, '.', { plain = true }) - local ra = LazyM.range(a) - local rb = LazyM.range(b) + 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), @@ -209,40 +298,40 @@ function LazyM.range(spec) end ---@private ----@param v string +---@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 return string.format('invalid version: %s (%s)', tostring(v), type(v)) end ----@private ---- Throws an error if `version` cannot be parsed. ----@param v string -local function assert_version(v, opt) - local rv = M.parse(v, opt) - if rv == nil then - error(create_err_msg(v)) - end - return rv -end - ---- Parses and compares two version strings. +--- 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}`). --- ---- semver notes: ---- - Build metadata MUST be ignored when comparing versions. +--- 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 v1 string Version. ----@param v2 string Version to compare with v1. ----@param opts table|nil Optional keyword arguments: ---- - strict (boolean): see `version.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) +--- @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 @@ -252,58 +341,50 @@ function M.cmp(v1, v2, opts) return -1 end ---- 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: ---- <pre> ---- { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" } ---- </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 } - - if opts.strict then - return LazyM.version(version, true) - end - - version = vim.trim(version) -- TODO: add more "scrubbing". - return LazyM.version(version, false) -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 |