From 0e7196438d8f856eecd7c90e160b79cbc8fb08dc Mon Sep 17 00:00:00 2001
From: Kelly Lin <findkellylin@gmail.com>
Date: Sun, 19 Feb 2023 22:33:57 +1100
Subject: feat(lua): add semver api

---
 runtime/lua/vim/version.lua | 297 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 297 insertions(+)
 create mode 100644 runtime/lua/vim/version.lua

(limited to 'runtime/lua/vim/version.lua')

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


From e31e49a8e3aac25e923dce15cc76dca4a447947f Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Mon, 6 Mar 2023 13:23:03 +0100
Subject: refactor(vim.version): cleanup

- version.cmp(): assert valid version
- add test for loading vim.version (the other tests use shared.lua in
  the test runner)
- reduce test scopes, reword test descriptions
---
 runtime/lua/vim/version.lua | 134 +++++++++++++++++++-------------------------
 1 file changed, 58 insertions(+), 76 deletions(-)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 49ef019295..ddbe228244 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -1,23 +1,41 @@
 local M = {}
 
+---@private
+---@param version string
+---@return string
+local function create_err_msg(version)
+  return string.format('invalid version: "%s"', version)
+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))
+  end
+  return rv
+end
+
 ---@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
+---@param v1 table Parsed version.
+---@param v2 table Parsed version.
+---@return integer `-1` if `v1 < v2`, `0` if `v1 == v2`, `1` if `v1 > v2`.
+local function cmp_prerelease(v1, v2)
+  if v1.prerelease and not v2.prerelease then
     return -1
   end
-  if not v1_parsed.prerelease and v2_parsed.prerelease then
+  if not v1.prerelease and v2.prerelease then
     return 1
   end
-  if not v1_parsed.prerelease and not v2_parsed.prerelease then
+  if not v1.prerelease and not v2.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 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
@@ -71,23 +89,15 @@ 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
+---@param v1 table Parsed version.
+---@param v2 table Parsed version.
+---@return integer `-1` if `v1 < v2`, `0` if `v1 == v2`, `1` if `v1 > v2`.
+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
   end
 
-  if
-    v1_parsed.major > v2_parsed.major
-    or v1_parsed.minor > v2_parsed.minor
-    or v1_parsed.patch > v2_parsed.patch
-  then
+  if v1.major > v2.major or v1.minor > v2.minor or v1.patch > v2.patch then
     return 1
   end
 
@@ -96,14 +106,14 @@ end
 
 --- Compares two strings (`v1` and `v2`) in semver format.
 ---@param v1 string Version.
----@param v2 string Version to be compared with v1.
+---@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 = M.parse(v1, opts)
-  local v2_parsed = M.parse(v2, opts)
+  local v1_parsed = assert_version(v1, opts)
+  local v2_parsed = assert_version(v2, opts)
 
   local result = cmp_version_core(v1_parsed, v2_parsed)
   if result == 0 then
@@ -188,30 +198,20 @@ local function is_prerelease_and_build_valid(prerelease_and_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:
+--- Parses a semantic version string.
 ---
---- `{ major = 1, minor = 0, patch = 1, prerelease = 'rc1', build = 'build.2' }`
+--- 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):  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.
+---                      - 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))
@@ -246,46 +246,28 @@ function M.parse(version, opts)
   }
 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
+---@param v1 string
+---@param v2 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
+function M.eq(v1, v2)
+  return M.cmp(v1, v2) == 0
 end
 
 ---Returns `true` if `v1` is less than `v2`.
----@param version_1 string
----@param version_2 string
+---@param v1 string
+---@param v2 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
+function M.lt(v1, v2)
+  return M.cmp(v1, v2) == -1
 end
 
 ---Returns `true` if `v1` is greater than `v2`.
----@param version_1 string
----@param version_2 string
+---@param v1 string
+---@param v2 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
+function M.gt(v1, v2)
+  return M.cmp(v1, v2) == 1
 end
 
 setmetatable(M, {
-- 
cgit 


From 74ffebf8ec725a25c2ae1dde81cf26b83fc7ae61 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Mon, 6 Mar 2023 15:08:22 +0100
Subject: fix(vim.version): incorrect version.cmp()

Problem:
If major<major but minor>minor, cmp_version_core returns 1

Solution:
- Fix logic in cmp_version_core
- Delete most eq()/gt()/lt() tests, they are redundant.
---
 runtime/lua/vim/version.lua | 22 ++++++++++------------
 1 file changed, 10 insertions(+), 12 deletions(-)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index ddbe228244..35629c461f 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -3,8 +3,11 @@ local M = {}
 ---@private
 ---@param version string
 ---@return string
-local function create_err_msg(version)
-  return string.format('invalid version: "%s"', version)
+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))
 end
 
 ---@private
@@ -20,9 +23,6 @@ end
 
 ---@private
 --- Compares the prerelease component of the two versions.
----@param v1 table Parsed version.
----@param v2 table Parsed version.
----@return integer `-1` if `v1 < v2`, `0` if `v1 == v2`, `1` if `v1 > v2`.
 local function cmp_prerelease(v1, v2)
   if v1.prerelease and not v2.prerelease then
     return -1
@@ -88,19 +88,17 @@ local function cmp_prerelease(v1, v2)
 end
 
 ---@private
---- Compares the version core component of the two versions.
----@param v1 table Parsed version.
----@param v2 table Parsed version.
----@return integer `-1` if `v1 < v2`, `0` if `v1 == v2`, `1` if `v1 > v2`.
 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
   end
-
-  if v1.major > v2.major or v1.minor > v2.minor or v1.patch > v2.patch then
+  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)
+  then
     return 1
   end
-
   return -1
 end
 
-- 
cgit 


From 990c481551af2b346f315d75aa0815e9b65051f3 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Thu, 16 Mar 2023 14:50:20 +0100
Subject: refactor(vim.version): use lazy.nvim semver module

Use semver code from https://github.com/folke/lazy.nvim
License: Apache License 2.0

Co-authored-by: Folke Lemaitre <folke.lemaitre@gmail.com>
---
 runtime/lua/vim/version.lua | 191 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 191 insertions(+)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 35629c461f..b409483755 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -1,5 +1,196 @@
 local M = {}
 
+local LazyM = {}
+M.LazyM = LazyM
+
+---@class Semver
+---@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 Semver = {}
+Semver.__index = Semver
+
+function Semver:__index(key)
+  return type(key) == "number" and ({ self.major, self.minor, self.patch })[key] or Semver[key]
+end
+
+function Semver:__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
+end
+
+---@param other Semver
+function Semver:__eq(other)
+  for i = 1, 3 do
+    if self[i] ~= other[i] then
+      return false
+    end
+  end
+  return self.prerelease == other.prerelease
+end
+
+function Semver:__tostring()
+  local ret = table.concat({ self.major, self.minor, self.patch }, ".")
+  if self.prerelease then
+    ret = ret .. "-" .. self.prerelease
+  end
+  if self.build then
+    ret = ret .. "+" .. self.build
+  end
+  return ret
+end
+
+---@param other Semver
+function Semver:__lt(other)
+  for i = 1, 3 do
+    if self[i] > other[i] then
+      return false
+    elseif self[i] < other[i] then
+      return true
+    end
+  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
+
+---@param other Semver
+function Semver:__le(other)
+  return self < other or self == other
+end
+
+---@param version string|number[]
+---@return Semver?
+function LazyM.parse(version)
+  if type(version) == "table" then
+    return setmetatable({
+      major = version[1] or 0,
+      minor = version[2] or 0,
+      patch = version[3] or 0,
+    }, Semver)
+  end
+  local major, minor, patch, prerelease, build = version:match("^v?(%d+)%.?(%d*)%.?(%d*)%-?([^+]*)+?(.*)$")
+  if major then
+    return setmetatable({
+      major = tonumber(major),
+      minor = minor == "" and 0 or tonumber(minor),
+      patch = patch == "" and 0 or tonumber(patch),
+      prerelease = prerelease ~= "" and prerelease or nil,
+      build = build ~= "" and build or nil,
+    }, Semver)
+  end
+end
+
+---@generic T: Semver
+---@param versions T[]
+---@return T?
+function LazyM.last(versions)
+  local last = versions[1]
+  for i = 2, #versions do
+    if versions[i] > last then
+      last = versions[i]
+    end
+  end
+  return last
+end
+
+---@class SemverRange
+---@field from Semver
+---@field to? Semver
+local Range = {}
+
+---@param version string|Semver
+function Range:matches(version)
+  if type(version) == "string" then
+    ---@diagnostic disable-next-line: cast-local-type
+    version = LazyM.parse(version)
+  end
+  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
+end
+
+---@param spec string
+function LazyM.range(spec)
+  if spec == "*" or spec == "" then
+    return setmetatable({ from = LazyM.parse("0.0.0") }, { __index = Range })
+  end
+
+  ---@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 = LazyM.range(a)
+    local rb = LazyM.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
+
+  local semver = LazyM.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
+    elseif mods == ">=" then
+      to = nil
+    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
 ---@param version string
 ---@return string
-- 
cgit 


From a715e6f87eede36775d0921b3537c7c57a82890a Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Thu, 16 Mar 2023 22:49:12 +0100
Subject: refactor(vim.version): use lazy.nvim semver module

Now the Nvim version string "v0.9.0-dev-1233+g210120dde81e" parses
correctly.
---
 runtime/lua/vim/version.lua | 295 +++++++++++---------------------------------
 1 file changed, 70 insertions(+), 225 deletions(-)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index b409483755..e79acf079b 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -16,7 +16,7 @@ local Semver = {}
 Semver.__index = Semver
 
 function Semver:__index(key)
-  return type(key) == "number" and ({ self.major, self.minor, self.patch })[key] or Semver[key]
+  return type(key) == 'number' and ({ self.major, self.minor, self.patch })[key] or Semver[key]
 end
 
 function Semver:__newindex(key, value)
@@ -42,12 +42,12 @@ function Semver:__eq(other)
 end
 
 function Semver:__tostring()
-  local ret = table.concat({ self.major, self.minor, self.patch }, ".")
+  local ret = table.concat({ self.major, self.minor, self.patch }, '.')
   if self.prerelease then
-    ret = ret .. "-" .. self.prerelease
+    ret = ret .. '-' .. self.prerelease
   end
   if self.build then
-    ret = ret .. "+" .. self.build
+    ret = ret .. '+' .. self.build
   end
   return ret
 end
@@ -67,7 +67,7 @@ function Semver:__lt(other)
   if other.prerelease and not self.prerelease then
     return false
   end
-  return (self.prerelease or "") < (other.prerelease or "")
+  return (self.prerelease or '') < (other.prerelease or '')
 end
 
 ---@param other Semver
@@ -76,23 +76,40 @@ function Semver:__le(other)
 end
 
 ---@param version string|number[]
+---@param strict? boolean Reject "1.0", "0-x" or other non-conforming version strings
 ---@return Semver?
-function LazyM.parse(version)
-  if type(version) == "table" then
+function LazyM.version(version, strict)
+  if type(version) == 'table' then
     return setmetatable({
       major = version[1] or 0,
       minor = version[2] or 0,
       patch = version[3] or 0,
     }, Semver)
   end
-  local major, minor, patch, prerelease, build = version:match("^v?(%d+)%.?(%d*)%.?(%d*)%-?([^+]*)+?(.*)$")
-  if major then
+
+  local prerel = version:match('%-([^+]*)')
+  local prerel_strict = version:match('%-([0-9A-Za-z-]*)')
+  if
+    strict
+    and prerel
+    and (prerel_strict == nil or prerel_strict == '' or not vim.startswith(prerel, prerel_strict))
+  then
+    return nil -- Invalid prerelease.
+  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 ''))
+
+  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 = prerelease ~= "" and prerelease or nil,
-      build = build ~= "" and build or nil,
+      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,
     }, Semver)
   end
 end
@@ -100,7 +117,7 @@ end
 ---@generic T: Semver
 ---@param versions T[]
 ---@return T?
-function LazyM.last(versions)
+function M.last(versions)
   local last = versions[1]
   for i = 2, #versions do
     if versions[i] > last then
@@ -117,9 +134,9 @@ local Range = {}
 
 ---@param version string|Semver
 function Range:matches(version)
-  if type(version) == "string" then
+  if type(version) == 'string' then
     ---@diagnostic disable-next-line: cast-local-type
-    version = LazyM.parse(version)
+    version = M.parse(version)
   end
   if version then
     if version.prerelease ~= self.from.prerelease then
@@ -131,16 +148,16 @@ end
 
 ---@param spec string
 function LazyM.range(spec)
-  if spec == "*" or spec == "" then
-    return setmetatable({ from = LazyM.parse("0.0.0") }, { __index = Range })
+  if spec == '*' or spec == '' then
+    return setmetatable({ from = M.parse('0.0.0') }, { __index = Range })
   end
 
   ---@type number?
-  local hyphen = spec:find(" - ", 1, true)
+  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 parts = vim.split(b, '.', { plain = true })
     local ra = LazyM.range(a)
     local rb = LazyM.range(b)
     return setmetatable({
@@ -149,25 +166,25 @@ function LazyM.range(spec)
     }, { __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 = "~"
+  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
 
-  local semver = LazyM.parse(version)
+  local semver = M.parse(version)
   if semver then
     local from = semver
     local to = vim.deepcopy(semver)
-    if mods == "" or mods == "=" then
+    if mods == '' or mods == '=' then
       to.patch = to.patch + 1
-    elseif mods == ">" then
+    elseif mods == '>' then
       from.patch = from.patch + 1
-      to = nil
-    elseif mods == ">=" then
-      to = nil
-    elseif mods == "~" then
+      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
@@ -176,7 +193,7 @@ function LazyM.range(spec)
         to[2] = 0
         to[3] = 0
       end
-    elseif mods == "^" then
+    elseif mods == '^' then
       for i = 1, 3 do
         if to[i] ~= 0 then
           to[i] = to[i] + 1
@@ -192,7 +209,7 @@ function LazyM.range(spec)
 end
 
 ---@private
----@param version string
+---@param v string
 ---@return string
 local function create_err_msg(v)
   if type(v) == 'string' then
@@ -203,188 +220,36 @@ 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)
+---@param v string
+local function assert_version(v, opt)
+  local rv = M.parse(v, opt)
   if rv == nil then
-    error(create_err_msg(version))
+    error(create_err_msg(v))
   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
-  end
-  if not v1.prerelease and v2.prerelease then
-    return 1
-  end
-  if not v1.prerelease and not v2.prerelease then
-    return 0
-  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
-    end
-    i = i + 1
-  end
-
-  return 0
-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
-  end
-  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)
-  then
-    return 1
-  end
-  return -1
-end
-
---- Compares two strings (`v1` and `v2`) in semver format.
+--- Parses and compares two version strings.
+---
+--- semver notes:
+--- - Build metadata MUST be ignored when comparing versions.
+---
 ---@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.
+---                      - 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)
-
-  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
+  if v1_parsed == v2_parsed then
+    return 0
   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
+  if v1_parsed > v2_parsed then
+    return 1
   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 -1
 end
 
 --- Parses a semantic version string.
@@ -405,34 +270,14 @@ 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)
+  if opts.strict then
+    return LazyM.version(version, true)
   end
 
-  return {
-    major = major,
-    minor = minor,
-    patch = patch,
-    prerelease = prerelease,
-    build = build,
-  }
+  version = vim.trim(version) -- TODO: add more "scrubbing".
+  return LazyM.version(version, false)
 end
 
 ---Returns `true` if `v1` are `v2` are equal versions.
-- 
cgit 


From a40eb7cc991eb4f8b89f467e8e42563868efa76b Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Fri, 17 Mar 2023 01:12:33 +0100
Subject: feat(vim.version): more coercion with strict=false

Problem:
"tmux 3.2a" (output from "tmux -V") is not parsed easily.

Solution:
With `strict=false`, discard everything before the first digit.

- rename Semver => Version
- rename vim.version.version() => vim.version._version()
- rename matches() => has()
- remove `opts` from cmp()
---
 runtime/lua/vim/version.lua | 267 +++++++++++++++++++++++++++++---------------
 1 file changed, 174 insertions(+), 93 deletions(-)

(limited to 'runtime/lua/vim/version.lua')

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


From 8a70adbde03ee9931dc4e1b6f31bd8635eb3633b Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Mon, 20 Mar 2023 13:36:06 +0100
Subject: fix(vim.version): prerelease compare

Problem:
semver specifies that digit sequences in a prerelease string should be
compared as numbers, not lexically: https://semver.org/#spec-item-11
> Precedence for two pre-release versions with the same major, minor,
> and patch version MUST be determined by comparing each dot separated
> identifier from left to right until a difference is found as follows:
> 1. Identifiers consisting of only digits are compared numerically.
> 2. Identifiers with letters or hyphens are compared lexically in ASCII sort order.
> 3. Numeric identifiers always have lower precedence than non-numeric identifiers.
> 4. A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal.
Example:
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

Solution:
cmp_prerel() treats all digit sequences in a prerelease string as
numbers. This doesn't _exactly_ match the spec, which specifies that
only dot-delimited digit sequences should be treated as numbers...
---
 runtime/lua/vim/version.lua | 46 +++++++++++++++++++++++++++++++++------------
 1 file changed, 34 insertions(+), 12 deletions(-)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 8d8b0d6da7..43001c195c 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -65,6 +65,33 @@ local M = {}
 local Version = {}
 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
+local function cmp_prerel(prerel1, prerel2)
+  if not prerel1 or not prerel2 then
+    return prerel1 and -1 or (prerel2 and 1 or 0)
+  end
+  -- TODO(justinmk): not fully spec-compliant; this treats non-dot-delimited digit sequences as
+  -- numbers. Maybe better: "(.-)(%.%d*)".
+  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()
+    if word1 == nil and word2 == nil then -- Done iterating.
+      return 0
+    end
+    word1, n1, word2, n2 =
+      word1 or '', n1 and tonumber(n1) or 0, word2 or '', n2 and tonumber(n2) or 0
+    if word1 ~= word2 then
+      return word1 < word2 and -1 or 1
+    end
+    if n1 ~= n2 then
+      return n1 < n2 and -1 or 1
+    end
+  end
+end
+
 function Version:__index(key)
   return type(key) == 'number' and ({ self.major, self.minor, self.patch })[key] or Version[key]
 end
@@ -88,7 +115,7 @@ function Version:__eq(other)
       return false
     end
   end
-  return self.prerelease == other.prerelease
+  return 0 == cmp_prerel(self.prerelease, other.prerelease)
 end
 
 function Version:__tostring()
@@ -111,13 +138,7 @@ function Version:__lt(other)
       return true
     end
   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 '')
+  return -1 == cmp_prerel(self.prerelease, other.prerelease)
 end
 
 ---@param other Version
@@ -127,7 +148,7 @@ end
 
 --- @private
 ---
---- Creates a new Version object. Not public currently.
+--- Creates a new Version object, or returns `nil` if `version` is invalid.
 ---
 --- @param version string|number[]|Version
 --- @param strict? boolean Reject "1.0", "0-x", "3.2a" or other non-conforming version strings
@@ -173,6 +194,7 @@ function M._version(version, strict) -- Adapted from https://github.com/folke/la
       build = build ~= '' and build or nil,
     }, Version)
   end
+  return nil -- Invalid version string.
 end
 
 ---TODO: generalize this, move to func.lua
@@ -341,7 +363,7 @@ function M.cmp(v1, v2)
   return -1
 end
 
----Returns `true` if the given versions are equal.
+---Returns `true` if the given versions are equal. See |vim.version.cmp()| for usage.
 ---@param v1 Version|number[]
 ---@param v2 Version|number[]
 ---@return boolean
@@ -349,7 +371,7 @@ function M.eq(v1, v2)
   return M.cmp(v1, v2) == 0
 end
 
----Returns `true` if `v1 < v2`.
+---Returns `true` if `v1 < v2`. See |vim.version.cmp()| for usage.
 ---@param v1 Version|number[]
 ---@param v2 Version|number[]
 ---@return boolean
@@ -357,7 +379,7 @@ function M.lt(v1, v2)
   return M.cmp(v1, v2) == -1
 end
 
----Returns `true` if `v1 > v2`.
+---Returns `true` if `v1 > v2`. See |vim.version.cmp()| for usage.
 ---@param v1 Version|number[]
 ---@param v2 Version|number[]
 ---@return boolean
-- 
cgit 


From e51139f5c1d70bef1424f29e63eb527514e42865 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Wed, 22 Mar 2023 15:14:51 +0100
Subject: refactor(vim.gsplit): remove "keepsep"

string.gmatch() is superior, use that instead.
---
 runtime/lua/vim/version.lua | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 43001c195c..3aacf3d4e0 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -65,6 +65,8 @@ local M = {}
 local Version = {}
 Version.__index = Version
 
+--- @private
+---
 --- 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
 local function cmp_prerel(prerel1, prerel2)
-- 
cgit 


From 08991b078267e5de0a19a136d00d4f71ad651a32 Mon Sep 17 00:00:00 2001
From: dundargoc <33953936+dundargoc@users.noreply.github.com>
Date: Sat, 13 May 2023 21:33:22 +0200
Subject: docs: small fixes

Co-authored-by: Christian Clason <c.clason@uni-graz.at>
Co-authored-by: Gregory Anders <greg@gpanders.com>
Co-authored-by: HiPhish <hiphish@posteo.de>
Co-authored-by: Julio B <julio.bacel@gmail.com>
Co-authored-by: T727 <74924917+T-727@users.noreply.github.com>
Co-authored-by: camoz <camoz@users.noreply.github.com>
Co-authored-by: champignoom <66909116+champignoom@users.noreply.github.com>
---
 runtime/lua/vim/version.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 3aacf3d4e0..ebe8f4e053 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -333,7 +333,7 @@ local function create_err_msg(v)
   return string.format('invalid version: %s (%s)', tostring(v), type(v))
 end
 
---- Parses and compares two version version objects (the result of |vim.version.parse()|, or
+--- Parses and compares two version objects (the result of |vim.version.parse()|, or
 --- specified literally as a `{major, minor, patch}` tuple, e.g. `{1, 0, 3}`).
 ---
 --- Example:
-- 
cgit 


From ca887b80a911df4db4ab5f5496075b9415b9990a Mon Sep 17 00:00:00 2001
From: Gianmaria Bajo <mg1979.git@gmail.com>
Date: Tue, 6 Jun 2023 15:38:45 +0200
Subject: fix: version-range < and <= #23539

vim.version.range() couldn't parse them correctly.
For example, vim.version.range('<0.9.0'):has('0.9.0') returned `true`.

fix: range:has() accepts vim.version()
So that it's possible to compare a range with:

    vim.version.range(spec):has(vim.version())
---
 runtime/lua/vim/version.lua | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index ebe8f4e053..d4a3752e37 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -226,8 +226,13 @@ function Range:has(version)
   if type(version) == 'string' then
     ---@diagnostic disable-next-line: cast-local-type
     version = M.parse(version)
+  else
+    -- Need metatable to compare versions.
+    version = setmetatable(vim.deepcopy(version), Version)
   end
   if version then
+    -- Workaround: vim.version() reports "prerelease" as a boolean.
+    version.prerelease = version.prerelease or nil
     if version.prerelease ~= self.from.prerelease then
       return false
     end
@@ -244,11 +249,14 @@ end
 ---   }
 ---   </pre>
 ---
---- `:has()` checks if a version is in the range (inclusive `from`, exclusive `to`). Example:
+--- `: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
+---   print(r:has('1.9.9'))       -- true
+---   print(r:has('2.0.0'))       -- false
+---   print(r:has(vim.version())) -- check against current Nvim version
 ---   </pre>
 ---
 --- Or use cmp(), eq(), lt(), and gt() to compare `.to` and `.from` directly:
@@ -279,7 +287,7 @@ function M.range(spec) -- Adapted from https://github.com/folke/lazy.nvim
     }, { __index = Range })
   end
   ---@type string, string
-  local mods, version = spec:lower():match('^([%^=>~]*)(.*)$')
+  local mods, version = spec:lower():match('^([%^=<>~]*)(.*)$')
   version = version:gsub('%.[%*x]', '')
   local parts = vim.split(version:gsub('%-.*', ''), '.', { plain = true })
   if #parts < 3 and mods == '' then
@@ -292,6 +300,11 @@ function M.range(spec) -- Adapted from https://github.com/folke/lazy.nvim
     local to = vim.deepcopy(semver)
     if mods == '' or mods == '=' then
       to.patch = to.patch + 1
+    elseif mods == '<' then
+      from = M._version({})
+    elseif mods == '<=' then
+      from = M._version({})
+      to.patch = to.patch + 1
     elseif mods == '>' then
       from.patch = from.patch + 1
       to = nil ---@diagnostic disable-line: cast-local-type
-- 
cgit 


From ecdb6465e272119f80f3b68a6695e0f74b02ca49 Mon Sep 17 00:00:00 2001
From: Gianmaria Bajo <mg1979.git@gmail.com>
Date: Wed, 7 Jun 2023 14:28:44 +0200
Subject: feat: vim.version() returns a Version object

- vim.version() returns a Version object.
  Makes it printable and removes the need of workarounds when passing it
  to other vim.version methods.
---
 runtime/lua/vim/version.lua | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index d4a3752e37..5578423453 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -226,13 +226,11 @@ function Range:has(version)
   if type(version) == 'string' then
     ---@diagnostic disable-next-line: cast-local-type
     version = M.parse(version)
-  else
+  elseif getmetatable(version) ~= Version then
     -- Need metatable to compare versions.
     version = setmetatable(vim.deepcopy(version), Version)
   end
   if version then
-    -- Workaround: vim.version() reports "prerelease" as a boolean.
-    version.prerelease = version.prerelease or nil
     if version.prerelease ~= self.from.prerelease then
       return false
     end
@@ -423,8 +421,12 @@ function M.parse(version, opts)
 end
 
 setmetatable(M, {
+  --- Returns the current Nvim version.
   __call = function()
-    return vim.fn.api_info().version
+    local version = vim.fn.api_info().version
+    -- Workaround: vim.fn.api_info().version reports "prerelease" as a boolean.
+    version.prerelease = version.prerelease or nil
+    return setmetatable(version, Version)
   end,
 })
 
-- 
cgit 


From e6887932539315e02621edb77d5e77c7c2a0b033 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Mon, 12 Jun 2023 01:14:33 +0200
Subject: feat: tostring(vim.version())
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Problem:
tostring(vim.version()) returns "table: 0x…".

Solution:
Modify vim.version() to return a string prerelease instead of a boolean.

Fix #23863
---
 runtime/lua/vim/version.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 5578423453..92250ff1f8 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -425,7 +425,7 @@ setmetatable(M, {
   __call = function()
     local version = vim.fn.api_info().version
     -- Workaround: vim.fn.api_info().version reports "prerelease" as a boolean.
-    version.prerelease = version.prerelease or nil
+    version.prerelease = version.prerelease and 'dev' or nil
     return setmetatable(version, Version)
   end,
 })
-- 
cgit 


From 43e76cc3462bc5bcf2b6ade8af1c36e21d3da3c9 Mon Sep 17 00:00:00 2001
From: Julian Grinblat <julian@dotcore.co.il>
Date: Thu, 22 Jun 2023 16:36:38 +0900
Subject: fix: tostring(vim.version()) fails if build is NIL #24097
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Problem:
Since #23925, Version.build may be vim.NIL, which causes tostring() to fail:
    E5108: Error executing lua E5114: Error while converting print argument #1: …/version.lua:129:
    attempt to concatenate field 'build' (a userdata value)
    stack traceback:
            [C]: in function 'print'
            [string ":lua"]:1: in main chunk

Solution:
Handle vim.NIL in Version:__tostring().
---
 runtime/lua/vim/version.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 92250ff1f8..cd28a9b54b 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -125,7 +125,7 @@ function Version:__tostring()
   if self.prerelease then
     ret = ret .. '-' .. self.prerelease
   end
-  if self.build then
+  if self.build and self.build ~= vim.NIL then
     ret = ret .. '+' .. self.build
   end
   return ret
-- 
cgit 


From c2d7c2826ca77b0ca31bec511fdcdf1e4abaf946 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Mon, 17 Jul 2023 15:13:54 +0100
Subject: docs(lua): change *lua-foo* -> *vim.foo*

---
 runtime/lua/vim/version.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index cd28a9b54b..8ff8a19cb9 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -1,4 +1,4 @@
---- @defgroup lua-version
+--- @defgroup vim.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
-- 
cgit 


From be74807eef13ff8c90d55cf8b22b01d6d33b1641 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Tue, 18 Jul 2023 15:42:30 +0100
Subject: docs(lua): more improvements (#24387)

* docs(lua): teach lua2dox how to table

* docs(lua): teach gen_vimdoc.py about local functions

No more need to mark local functions with @private

* docs(lua): mention @nodoc and @meta in dev-lua-doc

* fixup!

Co-authored-by: Justin M. Keyes <justinkz@gmail.com>

---------

Co-authored-by: Justin M. Keyes <justinkz@gmail.com>
---
 runtime/lua/vim/version.lua | 3 ---
 1 file changed, 3 deletions(-)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 8ff8a19cb9..96889438eb 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -65,8 +65,6 @@ local M = {}
 local Version = {}
 Version.__index = Version
 
---- @private
----
 --- 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
 local function cmp_prerel(prerel1, prerel2)
@@ -332,7 +330,6 @@ function M.range(spec) -- Adapted from https://github.com/folke/lazy.nvim
   end
 end
 
----@private
 ---@param v string|Version
 ---@return string
 local function create_err_msg(v)
-- 
cgit 


From c43c745a14dced87a23227d7be4f1c33d4455193 Mon Sep 17 00:00:00 2001
From: Christian Clason <c.clason@uni-graz.at>
Date: Wed, 9 Aug 2023 11:06:13 +0200
Subject: fix(lua): improve annotations for stricter luals diagnostics (#24609)

Problem: luals returns stricter diagnostics with bundled luarc.json
Solution: Improve some function and type annotations:

* use recognized uv.* types
* disable diagnostic for global `vim` in shared.lua
* docs: don't start comment lines with taglink (otherwise LuaLS will interpret it as a type)
* add type alias for lpeg pattern
* fix return annotation for `vim.secure.trust`
* rename local Range object in vim.version (shadows `Range` in vim.treesitter)
* fix some "missing fields" warnings
* add missing required fields for test functions in eval.lua
* rename lsp meta files for consistency
---
 runtime/lua/vim/version.lua | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 96889438eb..056e1678ff 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -212,15 +212,15 @@ function M.last(versions)
   return last
 end
 
----@class Range
+---@class VersionRange
 ---@field from Version
 ---@field to? Version
-local Range = {}
+local VersionRange = {}
 
 --- @private
 ---
 ---@param version string|Version
-function Range:has(version)
+function VersionRange:has(version)
   if type(version) == 'string' then
     ---@diagnostic disable-next-line: cast-local-type
     version = M.parse(version)
@@ -266,7 +266,7 @@ end
 --- @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 })
+    return setmetatable({ from = M.parse('0.0.0') }, { __index = VersionRange })
   end
 
   ---@type number?
@@ -280,7 +280,7 @@ function M.range(spec) -- Adapted from https://github.com/folke/lazy.nvim
     return setmetatable({
       from = ra and ra.from,
       to = rb and (#parts == 3 and rb.from or rb.to),
-    }, { __index = Range })
+    }, { __index = VersionRange })
   end
   ---@type string, string
   local mods, version = spec:lower():match('^([%^=<>~]*)(.*)$')
@@ -326,7 +326,7 @@ function M.range(spec) -- Adapted from https://github.com/folke/lazy.nvim
         end
       end
     end
-    return setmetatable({ from = from, to = to }, { __index = Range })
+    return setmetatable({ from = from, to = to }, { __index = VersionRange })
   end
 end
 
-- 
cgit 


From 2e92065686f62851318150a315591c30b8306a4b Mon Sep 17 00:00:00 2001
From: Gregory Anders <8965202+gpanders@users.noreply.github.com>
Date: Thu, 14 Sep 2023 08:23:01 -0500
Subject: docs: replace <pre> with ``` (#25136)

---
 runtime/lua/vim/version.lua | 131 +++++++++++++++++++++++---------------------
 1 file changed, 69 insertions(+), 62 deletions(-)

(limited to 'runtime/lua/vim/version.lua')

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 056e1678ff..306eef90d3 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -5,12 +5,13 @@
 --- 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>
+---
+--- ```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.
 ---
@@ -21,35 +22,36 @@
 ---
 --- 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
+--- ```
+--- 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 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>
+--- Partial left: missing pieces treated as 0 (1.2 => 1.2.0).
+--- 1.2 - 2.3.0       is 1.2.0 - 2.3.0
+--- ```
 
 local M = {}
 
@@ -237,29 +239,32 @@ function VersionRange:has(version)
 end
 
 --- Parses a semver |version-range| "spec" and returns a range object:
----   <pre>
----   {
----     from: Version
----     to: Version
----     has(v: string|Version)
----   }
----   </pre>
+---
+--- ```
+--- {
+---   from: Version
+---   to: Version
+---   has(v: string|Version)
+--- }
+--- ```
 ---
 --- `: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
----   print(r:has(vim.version())) -- check against current Nvim version
----   </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
+--- print(r:has(vim.version())) -- check against current Nvim version
+--- ```
 ---
 --- 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>
+---
+--- ```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))
+--- ```
 ---
 --- @see # https://github.com/npm/node-semver#ranges
 ---
@@ -345,16 +350,17 @@ end
 --- specified literally as a `{major, minor, patch}` tuple, e.g. `{1, 0, 3}`).
 ---
 --- 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>
+---
+--- ```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.
 ---
@@ -399,9 +405,10 @@ 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>
+---
+--- ```
+--- { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" }
+--- ```
 ---
 --- @see # https://semver.org/spec/v2.0.0.html
 ---
-- 
cgit