diff options
Diffstat (limited to 'runtime/lua/vim/version.lua')
| -rw-r--r-- | runtime/lua/vim/version.lua | 101 |
1 files changed, 63 insertions, 38 deletions
diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua index 306eef90d3..0b149700b5 100644 --- a/runtime/lua/vim/version.lua +++ b/runtime/lua/vim/version.lua @@ -1,6 +1,5 @@ ---- @defgroup vim.version ---- ---- @brief The \`vim.version\` module provides functions for comparing versions and ranges +--- @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. --- @@ -13,9 +12,9 @@ --- end --- ``` --- ---- \*vim.version()\* returns the version of the current Nvim process. +--- [vim.version()]() returns the version of the current Nvim process. --- ---- VERSION RANGE SPEC \*version-range\* +--- 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()|. @@ -55,7 +54,8 @@ local M = {} ----@class Version +---@nodoc +---@class vim.Version ---@field [1] number ---@field [2] number ---@field [3] number @@ -69,6 +69,8 @@ Version.__index = Version --- Compares prerelease strings: per semver, number parts must be must be treated as numbers: --- "pre1.10" is greater than "pre1.2". https://semver.org/#spec-item-11 +---@param prerel1 string? +---@param prerel2 string? local function cmp_prerel(prerel1, prerel2) if not prerel1 or not prerel2 then return prerel1 and -1 or (prerel2 and 1 or 0) @@ -78,8 +80,8 @@ local function cmp_prerel(prerel1, prerel2) local iter1 = prerel1:gmatch('([^0-9]*)(%d*)') local iter2 = prerel2:gmatch('([^0-9]*)(%d*)') while true do - local word1, n1 = iter1() - local word2, n2 = iter2() + local word1, n1 = iter1() --- @type string?, string|number|nil + local word2, n2 = iter2() --- @type string?, string|number|nil if word1 == nil and word2 == nil then -- Done iterating. return 0 end @@ -110,7 +112,7 @@ function Version:__newindex(key, value) end end ----@param other Version +---@param other vim.Version function Version:__eq(other) for i = 1, 3 do if self[i] ~= other[i] then @@ -131,7 +133,7 @@ function Version:__tostring() return ret end ----@param other Version +---@param other vim.Version function Version:__lt(other) for i = 1, 3 do if self[i] > other[i] then @@ -143,7 +145,7 @@ function Version:__lt(other) return -1 == cmp_prerel(self.prerelease, other.prerelease) end ----@param other Version +---@param other vim.Version function Version:__le(other) return self < other or self == other end @@ -152,13 +154,13 @@ end --- --- Creates a new Version object, or returns `nil` if `version` is invalid. --- ---- @param version string|number[]|Version +--- @param version string|number[]|vim.Version --- @param strict? boolean Reject "1.0", "0-x", "3.2a" or other non-conforming version strings ---- @return Version? +--- @return vim.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) + return setmetatable(vim.deepcopy(version, true), Version) end return setmetatable({ major = version[1] or 0, @@ -168,6 +170,7 @@ function M._version(version, strict) -- Adapted from https://github.com/folke/la end if not strict then -- TODO: add more "scrubbing". + --- @cast version string version = version:match('%d[^ ]*') end @@ -201,7 +204,7 @@ end ---TODO: generalize this, move to func.lua --- ----@generic T: Version +---@generic T: vim.Version ---@param versions T[] ---@return T? function M.last(versions) @@ -214,21 +217,22 @@ function M.last(versions) return last end ----@class VersionRange ----@field from Version ----@field to? Version +---@class vim.VersionRange +---@inlinedoc +---@field from vim.Version +---@field to? vim.Version local VersionRange = {} --- @private --- ----@param version string|Version +---@param version string|vim.Version function VersionRange:has(version) if type(version) == 'string' then ---@diagnostic disable-next-line: cast-local-type version = M.parse(version) elseif getmetatable(version) ~= Version then -- Need metatable to compare versions. - version = setmetatable(vim.deepcopy(version), Version) + version = setmetatable(vim.deepcopy(version, true), Version) end if version then if version.prerelease ~= self.from.prerelease then @@ -259,16 +263,18 @@ end --- print(r:has(vim.version())) -- check against current Nvim version --- ``` --- ---- Or use cmp(), eq(), lt(), and gt() to compare `.to` and `.from` directly: +--- Or use cmp(), le(), lt(), ge(), gt(), and/or eq() to compare a version +--- against `.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)) +--- local r = vim.version.range('1.0.0 - 2.0.0') -- >=1.0, <2.0 +--- print(vim.version.ge({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to)) --- ``` --- --- @see # https://github.com/npm/node-semver#ranges --- --- @param spec string Version range "spec" +--- @return vim.VersionRange? 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 = VersionRange }) @@ -297,8 +303,9 @@ function M.range(spec) -- Adapted from https://github.com/folke/lazy.nvim local semver = M.parse(version) if semver then - local from = semver - local to = vim.deepcopy(semver) + local from = semver --- @type vim.Version? + local to = vim.deepcopy(semver, true) --- @type vim.Version? + ---@diagnostic disable: need-check-nil if mods == '' or mods == '=' then to.patch = to.patch + 1 elseif mods == '<' then @@ -308,9 +315,9 @@ function M.range(spec) -- Adapted from https://github.com/folke/lazy.nvim to.patch = to.patch + 1 elseif mods == '>' then from.patch = from.patch + 1 - to = nil ---@diagnostic disable-line: cast-local-type + to = nil elseif mods == '>=' then - to = nil ---@diagnostic disable-line: cast-local-type + to = nil elseif mods == '~' then if #parts >= 2 then to[2] = to[2] + 1 @@ -331,11 +338,12 @@ function M.range(spec) -- Adapted from https://github.com/folke/lazy.nvim end end end + ---@diagnostic enable: need-check-nil return setmetatable({ from = from, to = to }, { __index = VersionRange }) end end ----@param v string|Version +---@param v string|vim.Version ---@return string local function create_err_msg(v) if type(v) == 'string' then @@ -364,8 +372,8 @@ end --- --- @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`. +---@param v1 vim.Version|number[]|string Version object. +---@param v2 vim.Version|number[]|string 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)) @@ -380,24 +388,40 @@ function M.cmp(v1, v2) end ---Returns `true` if the given versions are equal. See |vim.version.cmp()| for usage. ----@param v1 Version|number[] ----@param v2 Version|number[] +---@param v1 vim.Version|number[]|string +---@param v2 vim.Version|number[]|string ---@return boolean function M.eq(v1, v2) return M.cmp(v1, v2) == 0 end +---Returns `true` if `v1 <= v2`. See |vim.version.cmp()| for usage. +---@param v1 vim.Version|number[]|string +---@param v2 vim.Version|number[]|string +---@return boolean +function M.le(v1, v2) + return M.cmp(v1, v2) <= 0 +end + ---Returns `true` if `v1 < v2`. See |vim.version.cmp()| for usage. ----@param v1 Version|number[] ----@param v2 Version|number[] +---@param v1 vim.Version|number[]|string +---@param v2 vim.Version|number[]|string ---@return boolean function M.lt(v1, v2) return M.cmp(v1, v2) == -1 end +---Returns `true` if `v1 >= v2`. See |vim.version.cmp()| for usage. +---@param v1 vim.Version|number[]|string +---@param v2 vim.Version|number[]|string +---@return boolean +function M.ge(v1, v2) + return M.cmp(v1, v2) >= 0 +end + ---Returns `true` if `v1 > v2`. See |vim.version.cmp()| for usage. ----@param v1 Version|number[] ----@param v2 Version|number[] +---@param v1 vim.Version|number[]|string +---@param v2 vim.Version|number[]|string ---@return boolean function M.gt(v1, v2) return M.cmp(v1, v2) == 1 @@ -417,7 +441,7 @@ end --- - 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. +---@return vim.Version? 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 } @@ -426,8 +450,9 @@ end setmetatable(M, { --- Returns the current Nvim version. + ---@return vim.Version __call = function() - local version = vim.fn.api_info().version + local version = vim.fn.api_info().version ---@type vim.Version -- Workaround: vim.fn.api_info().version reports "prerelease" as a boolean. version.prerelease = version.prerelease and 'dev' or nil return setmetatable(version, Version) |