From 3734519e3b4ba1bf19ca772104170b0ef776be46 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Tue, 2 Jan 2024 15:47:55 +0000
Subject: feat(lua): add noref to deepcopy

Problem:

Currently `deepcopy` hashes every single tables it copies so it can be
reused. For tables of mostly unique items that are non recursive, this
hashing is unnecessarily expensive

Solution:

Port the `noref` argument from Vimscripts `deepcopy()`.

The below benchmark demonstrates the results for two extreme cases of
tables of different sizes. One table that uses the same table lots of
times and one with all unique tables.

| test                 | `noref=false` (ms) | `noref=true` (ms) |
| -------------------- | ------------------ | ----------------- |
| unique tables (50)   | 6.59               | 2.62              |
| shared tables (50)   | 3.24               | 6.40              |
| unique tables (2000) | 23381.48           | 2884.53           |
| shared tables (2000) | 3505.54            | 14038.80          |

The results are basically the inverse of each other where `noref` is
much more performance on tables with unique fields, and `not noref` is
more performant on tables that reuse fields.
---
 runtime/lua/vim/version.lua | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

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

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 306eef90d3..0873402e29 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -158,7 +158,7 @@ end
 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,
@@ -228,7 +228,7 @@ function VersionRange:has(version)
     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
@@ -298,7 +298,7 @@ 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 to = vim.deepcopy(semver, true)
     if mods == '' or mods == '=' then
       to.patch = to.patch + 1
     elseif mods == '<' then
-- 
cgit 


From fa4b02fa67e5d04e37de7c767f811d497a72f95e Mon Sep 17 00:00:00 2001
From: Jongwook Choi <wookayin@gmail.com>
Date: Mon, 15 Jan 2024 12:13:09 -0500
Subject: feat(vim.version): add `vim.version.le` and `vim.version.ge`

- Problem: One cannot easily write something like, for example:
    `version_current >= {0, 10, 0}`; writing like
    `not vim.version.lt(version_current, {0, 10, 0})` is verbose.

- Solution: add {`le`,`ge`} in addition to {`lt`,`gt`}.

- Also improve typing on the operator methods: allow `string` as well.

- Update the example in `vim.version.range()` docs: `ge` in place of
  `gt` better matches the semantics of `range:has`.
---
 runtime/lua/vim/version.lua | 42 ++++++++++++++++++++++++++++++------------
 1 file changed, 30 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 0873402e29..4f52938c6e 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -259,11 +259,12 @@ 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
@@ -364,8 +365,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 Version|number[]|string Version object.
+---@param v2 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 +381,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 Version|number[]|string
+---@param v2 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 Version|number[]|string
+---@param v2 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 Version|number[]|string
+---@param v2 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 Version|number[]|string
+---@param v2 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 Version|number[]|string
+---@param v2 Version|number[]|string
 ---@return boolean
 function M.gt(v1, v2)
   return M.cmp(v1, v2) == 1
@@ -417,7 +434,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 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,6 +443,7 @@ end
 
 setmetatable(M, {
   --- Returns the current Nvim version.
+  ---@return Version
   __call = function()
     local version = vim.fn.api_info().version
     -- Workaround: vim.fn.api_info().version reports "prerelease" as a boolean.
-- 
cgit 


From 185752614d1a4906c8f218e4c24c3b52bbe6560e Mon Sep 17 00:00:00 2001
From: Maria José Solano <majosolano99@gmail.com>
Date: Sun, 18 Feb 2024 18:46:19 -0800
Subject: refactor(types): fix miscellaneous type warnings

---
 runtime/lua/vim/version.lua | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

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

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 4f52938c6e..58c2a2386d 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -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
@@ -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
 
@@ -298,8 +301,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, true)
+    local from = semver --- @type Version?
+    local to = vim.deepcopy(semver, true) --- @type Version?
+    ---@diagnostic disable: need-check-nil
     if mods == '' or mods == '=' then
       to.patch = to.patch + 1
     elseif mods == '<' then
@@ -309,9 +313,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
@@ -332,6 +336,7 @@ 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
@@ -445,7 +450,7 @@ setmetatable(M, {
   --- Returns the current Nvim version.
   ---@return Version
   __call = function()
-    local version = vim.fn.api_info().version
+    local version = vim.fn.api_info().version ---@type Version
     -- Workaround: vim.fn.api_info().version reports "prerelease" as a boolean.
     version.prerelease = version.prerelease and 'dev' or nil
     return setmetatable(version, Version)
-- 
cgit 


From 9beb40a4db5613601fc1a4b828a44e5977eca046 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Thu, 15 Feb 2024 17:16:04 +0000
Subject: feat(docs): replace lua2dox.lua

Problem:

The documentation flow (`gen_vimdoc.py`) has several issues:
- it's not very versatile
- depends on doxygen
- doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C.
- The intermediate XML files and filters makes it too much like a rube goldberg machine.

Solution:

Re-implement the flow using Lua, LPEG and treesitter.

- `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic.
- `lua2dox.lua` is gone!
- No more XML files.
- Doxygen is now longer used and instead we now use:
  - LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`).
  - LPEG for C parsing (see `scripts/cdoc_parser.lua`)
  - Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`).
  - Treesitter for Markdown parsing (see `scripts/text_utils.lua`).
- The generated `runtime/doc/*.mpack` files have been removed.
   - `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly.
- Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change).
---
 runtime/lua/vim/version.lua | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

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

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 58c2a2386d..09a6fa825b 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()|.
-- 
cgit 


From a5fe8f59d98398d04bed8586cee73864bbcdde92 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Tue, 27 Feb 2024 15:20:32 +0000
Subject: docs: improve/add documentation of Lua types

- Added `@inlinedoc` so single use Lua types can be inlined into the
  functions docs. E.g.

  ```lua
  --- @class myopts
  --- @inlinedoc
  ---
  --- Documentation for some field
  --- @field somefield integer

  --- @param opts myOpts
  function foo(opts)
  end
  ```

  Will be rendered as

  ```
  foo(opts)

    Parameters:
      - {opts} (table) Object with the fields:
               - somefield (integer) Documentation
                 for some field
  ```

- Marked many classes with with `@nodoc` or `(private)`.
  We can eventually introduce these when we want to.
---
 runtime/lua/vim/version.lua | 61 ++++++++++++++++++++++++---------------------
 1 file changed, 32 insertions(+), 29 deletions(-)

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

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 09a6fa825b..f97e81273e 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -54,7 +54,8 @@
 
 local M = {}
 
----@class Version
+---@nodoc
+---@class vim.Version
 ---@field [1] number
 ---@field [2] number
 ---@field [3] number
@@ -111,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
@@ -132,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
@@ -144,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
@@ -153,9 +154,9 @@ 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
@@ -203,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)
@@ -216,14 +217,15 @@ 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
@@ -272,6 +274,7 @@ end
 --- @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 })
@@ -300,8 +303,8 @@ function M.range(spec) -- Adapted from https://github.com/folke/lazy.nvim
 
   local semver = M.parse(version)
   if semver then
-    local from = semver --- @type Version?
-    local to = vim.deepcopy(semver, true) --- @type Version?
+    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
@@ -340,7 +343,7 @@ function M.range(spec) -- Adapted from https://github.com/folke/lazy.nvim
   end
 end
 
----@param v string|Version
+---@param v string|vim.Version
 ---@return string
 local function create_err_msg(v)
   if type(v) == 'string' then
@@ -369,8 +372,8 @@ end
 ---
 --- @note Per semver, build metadata is ignored when comparing two otherwise-equivalent versions.
 ---
----@param v1 Version|number[]|string Version object.
----@param v2 Version|number[]|string 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))
@@ -385,40 +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[]|string
----@param v2 Version|number[]|string
+---@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 Version|number[]|string
----@param v2 Version|number[]|string
+---@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[]|string
----@param v2 Version|number[]|string
+---@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 Version|number[]|string
----@param v2 Version|number[]|string
+---@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[]|string
----@param v2 Version|number[]|string
+---@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
@@ -438,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 Version? 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 }
@@ -447,9 +450,9 @@ end
 
 setmetatable(M, {
   --- Returns the current Nvim version.
-  ---@return Version
+  ---@return vim.Version
   __call = function()
-    local version = vim.fn.api_info().version ---@type 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)
-- 
cgit 


From 85b13751a5fc28fadbe74d72982325ca27b4c775 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Wed, 6 Mar 2024 12:15:25 +0000
Subject: refactor(types): more fixes (2)

---
 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 f97e81273e..cd8748ede7 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -274,7 +274,7 @@ end
 --- @see # https://github.com/npm/node-semver#ranges
 ---
 --- @param spec string Version range "spec"
---- @return vim.VersionRange
+--- @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 })
-- 
cgit 


From ade1b12f49c3b3914c74847d791eb90ea90b56b7 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Fri, 8 Mar 2024 12:25:18 +0000
Subject: docs: support inline markdown

- Tags are now created with `[tag]()`
- References are now created with `[tag]`
- Code spans are no longer wrapped
---
 runtime/lua/vim/version.lua | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

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

diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index cd8748ede7..0b149700b5 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -12,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()|.
-- 
cgit