diff options
Diffstat (limited to 'runtime')
| -rw-r--r-- | runtime/doc/lua.txt | 72 | ||||
| -rw-r--r-- | runtime/doc/news.txt | 4 | ||||
| -rw-r--r-- | runtime/lua/vim/_init_packages.lua | 3 | ||||
| -rw-r--r-- | runtime/lua/vim/version.lua | 297 |
4 files changed, 376 insertions, 0 deletions
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 1eb5ab41e6..3c48cd37a6 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -2497,4 +2497,76 @@ trust({opts}) *vim.secure.trust()* • true and full path of target file if operation was successful • false and error message on failure + +============================================================================== +Lua module: version *lua-version* + +cmp({v1}, {v2}, {opts}) *version.cmp()* + Compares two strings ( `v1` and `v2` ) in semver format. + + Parameters: ~ + • {v1} (string) Version. + • {v2} (string) Version to be compared with v1. + • {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`. + +eq({version_1}, {version_2}) *version.eq()* + Returns `true` if `v1` are `v2` are equal versions. + + Parameters: ~ + • {version_1} (string) + • {version_2} (string) + + Return: ~ + (boolean) + +gt({version_1}, {version_2}) *version.gt()* + Returns `true` if `v1` is greater than `v2` . + + Parameters: ~ + • {version_1} (string) + • {version_2} (string) + + Return: ~ + (boolean) + +lt({version_1}, {version_2}) *version.lt()* + Returns `true` if `v1` is less than `v2` . + + Parameters: ~ + • {version_1} (string) + • {version_2} (string) + + Return: ~ + (boolean) + +parse({version}, {opts}) *version.parse()* + Parses a semantically formatted version string into a table. + + Supports leading "v" and leading and trailing whitespace in the version + string. 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 "` will be parsed as: + + { major = 1, minor = 0, patch = 1, prerelease = 'rc1 , build = 'build.2' }` + + Parameters: ~ + • {version} (string) Version string to be parsed. + • {opts} (table|nil) Optional keyword arguments: + • strict (boolean): when set to `true` an error will be + thrown for version strings that do not conform to the + semver specification (v2.0.0) (see + semver.org/spec/v2.0.0.html for details). This means that + `semver.parse('v1.2)` will throw an error. When set to + `false`, `semver.parse('v1.2)` will coerce 'v1.2' to + 'v1.2.0' and return the table: `{ major = 1, minor = 2, + patch = 0 }`. Defaults to false. + + Return: ~ + (table|nil) parsed_version Parsed version table or `nil` if `version` + is not valid. + 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 415195e27e..b5cb975066 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -55,6 +55,10 @@ NEW FEATURES *news-features* The following new APIs or features were added. +• Added |version.parse()|, |version.cmp()|, |version.lt()|, |version.eq()| + and |version.gt()| to |vim.version| for parsing and comparing version numbers + according to the semver specification, see |lua-version|. + • A new environment variable named NVIM_APPNAME enables configuring the directories where Neovim should find its configuration and state files. See `:help $NVIM_APPNAME` . diff --git a/runtime/lua/vim/_init_packages.lua b/runtime/lua/vim/_init_packages.lua index e3a442af5e..d032026796 100644 --- a/runtime/lua/vim/_init_packages.lua +++ b/runtime/lua/vim/_init_packages.lua @@ -69,6 +69,9 @@ setmetatable(vim, { t[key] = val return t[key] end + elseif key == 'version' then + t[key] = require('vim.version') + return t[key] end end, }) diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua new file mode 100644 index 0000000000..49ef019295 --- /dev/null +++ b/runtime/lua/vim/version.lua @@ -0,0 +1,297 @@ +local M = {} + +---@private +--- Compares the prerelease component of the two versions. +---@param v1_parsed table Parsed version. +---@param v2_parsed table Parsed version. +---@return integer `-1` if `v1_parsed < v2_parsed`, `0` if `v1_parsed == v2_parsed`, `1` if `v1_parsed > v2_parsed`. +local function cmp_prerelease(v1_parsed, v2_parsed) + if v1_parsed.prerelease and not v2_parsed.prerelease then + return -1 + end + if not v1_parsed.prerelease and v2_parsed.prerelease then + return 1 + end + if not v1_parsed.prerelease and not v2_parsed.prerelease then + return 0 + end + + local v1_identifiers = vim.split(v1_parsed.prerelease, '.', { plain = true }) + local v2_identifiers = vim.split(v2_parsed.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 + end + i = i + 1 + end + + return 0 +end + +---@private +--- Compares the version core component of the two versions. +---@param v1_parsed table Parsed version. +---@param v2_parsed table Parsed version. +---@return integer `-1` if `v1_parsed < v2_parsed`, `0` if `v1_parsed == v2_parsed`, `1` if `v1_parsed > v2_parsed`. +local function cmp_version_core(v1_parsed, v2_parsed) + if + v1_parsed.major == v2_parsed.major + and v1_parsed.minor == v2_parsed.minor + and v1_parsed.patch == v2_parsed.patch + then + return 0 + end + + if + v1_parsed.major > v2_parsed.major + or v1_parsed.minor > v2_parsed.minor + or v1_parsed.patch > v2_parsed.patch + then + return 1 + end + + return -1 +end + +--- Compares two strings (`v1` and `v2`) in semver format. +---@param v1 string Version. +---@param v2 string Version to be compared 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 = M.parse(v1, opts) + local v2_parsed = M.parse(v2, opts) + + local result = cmp_version_core(v1_parsed, v2_parsed) + if result == 0 then + result = cmp_prerelease(v1_parsed, v2_parsed) + end + return result +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 + end + -- This pattern matches "-(alpha)". + result = labels:match('^%-([%w%.]+)') + if result then + return result + 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 + end + + -- Pattern matches "+(build.15)". + result = labels:match('^%+([%w%.]+)$') + if result then + return result + 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 +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 + 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 +end + +---@private +---@param version string +---@return string +local function create_err_msg(version) + return string.format('invalid version: "%s"', version) +end + +--- Parses a semantically formatted version string into a table. +--- +--- Supports leading "v" and leading and trailing whitespace in the version +--- string. 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 "` will be parsed as: +--- +--- `{ major = 1, minor = 0, patch = 1, prerelease = 'rc1', build = 'build.2' }` +--- +---@param version string Version string to be parsed. +---@param opts table|nil Optional keyword arguments: +--- - strict (boolean): when set to `true` an error will be thrown for version +--- strings that do not conform to the semver specification (v2.0.0) (see +--- semver.org/spec/v2.0.0.html for details). This means that +--- `semver.parse('v1.2)` will throw an error. When set to `false`, +--- `semver.parse('v1.2)` will coerce 'v1.2' to 'v1.2.0' and return the table: +--- `{ major = 1, minor = 2, patch = 0 }`. Defaults to false. +---@return table|nil parsed_version Parsed version table or `nil` if `version` is not valid. +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 + 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) + end + + return { + major = major, + minor = minor, + patch = patch, + prerelease = prerelease, + build = build, + } +end + +---@private +--- Throws an error if `version` cannot be parsed. +---@param version string +local function assert_version(version) + if M.parse(version) == nil then + error(create_err_msg(version)) + end +end + +---Returns `true` if `v1` are `v2` are equal versions. +---@param version_1 string +---@param version_2 string +---@return boolean +function M.eq(version_1, version_2) + assert_version(version_1) + assert_version(version_2) + + return M.cmp(version_1, version_2) == 0 +end + +---Returns `true` if `v1` is less than `v2`. +---@param version_1 string +---@param version_2 string +---@return boolean +function M.lt(version_1, version_2) + assert_version(version_1) + assert_version(version_2) + + return M.cmp(version_1, version_2) == -1 +end + +---Returns `true` if `v1` is greater than `v2`. +---@param version_1 string +---@param version_2 string +---@return boolean +function M.gt(version_1, version_2) + assert_version(version_1) + assert_version(version_2) + + return M.cmp(version_1, version_2) == 1 +end + +setmetatable(M, { + __call = function() + return vim.fn.api_info().version + end, +}) + +return M |