From fd1595514b747d8b083f78007579d869ccfbe89c Mon Sep 17 00:00:00 2001 From: Thomas Vigouroux Date: Wed, 7 Sep 2022 08:39:56 +0200 Subject: Use weak tables in tree-sitter code (#17117) feat(treesitter): use weak tables when possible Also add the defaulttable function to create a table whose values are created when a key is missing. --- runtime/lua/vim/shared.lua | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) (limited to 'runtime/lua/vim/shared.lua') diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index e1b4ed4ea9..59cb669609 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -715,5 +715,30 @@ function vim.is_callable(f) return type(m.__call) == 'function' end +--- Creates a table whose members are automatically created when accessed, if they don't already +--- exist. +--- +--- They mimic defaultdict in python. +--- +--- If @p create is @c nil, this will create a defaulttable whose constructor function is +--- this function, effectively allowing to create nested tables on the fly: +--- +--- 
+--- local a = vim.defaulttable()
+--- a.b.c = 1
+---
+--- +---@param create function|nil The function called to create a missing value. +---@return table Empty table with metamethod +function vim.defaulttable(create) + create = create or vim.defaulttable + return setmetatable({}, { + __index = function(tbl, key) + rawset(tbl, key, create()) + return rawget(tbl, key) + end, + }) +end + return vim -- vim:sw=2 ts=2 et -- cgit From ddb762f4013ac2532ad45704466058d867e3a6ed Mon Sep 17 00:00:00 2001 From: Christian Clason Date: Wed, 14 Sep 2022 11:08:31 +0200 Subject: docs(treesitter): clean up and update treesitter.txt (#20142) * add type annotations to code * clean up and expand static documentation * consistent use of tags for static and generated docs --- runtime/lua/vim/shared.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/shared.lua') diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index 59cb669609..de5f7240aa 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -720,7 +720,7 @@ end --- --- They mimic defaultdict in python. --- ---- If @p create is @c nil, this will create a defaulttable whose constructor function is +--- If {create} is `nil`, this will create a defaulttable whose constructor function is --- this function, effectively allowing to create nested tables on the fly: --- --- 
-- 
cgit 


From 63be7651829f8b77c4974d08ebe09f7775e41a8a Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" 
Date: Sun, 25 Sep 2022 19:58:27 -0400
Subject: fix(docs): invalid :help links #20345

Fix those naughty single quotes.

closes #20159
---
 runtime/lua/vim/shared.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index de5f7240aa..c5c31b6ddf 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -302,7 +302,7 @@ end
 
 --- Merges recursively two or more map-like tables.
 ---
----@see |tbl_extend()|
+---@see |vim.tbl_extend()|
 ---
 ---@param behavior string Decides what to do if a key is found in more than one map:
 ---      - "error": raise an error
-- 
cgit 


From 548a4e258777a405cc2b1225cab9a8292924407b Mon Sep 17 00:00:00 2001
From: Elizabeth Paź 
Date: Wed, 5 Oct 2022 13:21:45 +0200
Subject: docs(docstrings): fix runtime type annotations

---
 runtime/lua/vim/shared.lua | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index c5c31b6ddf..63a932479e 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -107,9 +107,11 @@ end
 ---
 ---@see |vim.gsplit()|
 ---
+---@alias split_kwargs {plain: boolean, trimempty: boolean} | boolean | nil
+---
 ---@param s string String to split
 ---@param sep string Separator or pattern
----@param kwargs table Keyword arguments:
+---@param kwargs split_kwargs Keyword arguments:
 ---       - plain: (boolean) If `true` use `sep` literally (passed to string.find)
 ---       - trimempty: (boolean) If `true` remove empty items from the front
 ---         and back of the list
-- 
cgit 


From c8d1b9a2d6ef910a9c1993875723387d522e6c4a Mon Sep 17 00:00:00 2001
From: Folke Lemaitre 
Date: Tue, 27 Sep 2022 22:44:01 +0200
Subject: docs: added proper annotations to functions in shared.lua

---
 runtime/lua/vim/shared.lua | 55 +++++++++++++++++++++++++++-------------------
 1 file changed, 32 insertions(+), 23 deletions(-)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 63a932479e..1d0a6d5406 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -14,8 +14,9 @@ local vim = vim or {}
 --- same functions as those in the input table. Userdata and threads are not
 --- copied and will throw an error.
 ---
----@param orig table Table to copy
----@return table Table of copied keys and (nested) values.
+---@generic T: table
+---@param orig T Table to copy
+---@return T Table of copied keys and (nested) values.
 function vim.deepcopy(orig) end -- luacheck: no unused
 vim.deepcopy = (function()
   local function _id(v)
@@ -62,7 +63,7 @@ end)()
 ---@param s string String to split
 ---@param sep string Separator or pattern
 ---@param plain boolean If `true` use `sep` literally (passed to string.find)
----@return function Iterator over the split components
+---@return fun():string Iterator over the split components
 function vim.gsplit(s, sep, plain)
   vim.validate({ s = { s, 's' }, sep = { sep, 's' }, plain = { plain, 'b', true } })
 
@@ -111,11 +112,11 @@ end
 ---
 ---@param s string String to split
 ---@param sep string Separator or pattern
----@param kwargs split_kwargs Keyword arguments:
+---@param kwargs {plain: boolean, trimempty: boolean}|nil Keyword arguments:
 ---       - plain: (boolean) If `true` use `sep` literally (passed to string.find)
 ---       - trimempty: (boolean) If `true` remove empty items from the front
 ---         and back of the list
----@return table List of split components
+---@return string[] List of split components
 function vim.split(s, sep, kwargs)
   local plain
   local trimempty = false
@@ -158,8 +159,9 @@ end
 ---
 ---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
----@param t table Table
----@return table List of keys
+---@param t table Table
+---@generic T: table
+---@return T[] List of keys
 function vim.tbl_keys(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
 
@@ -173,8 +175,9 @@ end
 --- Return a list of all values used in a table.
 --- However, the order of the return table of values is not guaranteed.
 ---
----@param t table Table
----@return table List of values
+---@generic T
+---@param t table Table
+---@return T[] List of values
 function vim.tbl_values(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
 
@@ -187,8 +190,9 @@ end
 
 --- Apply a function to all values of a table.
 ---
----@param func function|table Function or callable table
----@param t table Table
+---@generic T
+---@param func fun(value: T): any Function
+---@param t table Table
 ---@return table Table of transformed values
 function vim.tbl_map(func, t)
   vim.validate({ func = { func, 'c' }, t = { t, 't' } })
@@ -202,9 +206,10 @@ end
 
 --- Filter a table using a predicate function
 ---
----@param func function|table Function or callable table
----@param t table Table
----@return table Table of filtered values
+---@generic T
+---@param func fun(value: T): boolean Function
+---@param t table Table
+---@return T[] Table of filtered values
 function vim.tbl_filter(func, t)
   vim.validate({ func = { func, 'c' }, t = { t, 't' } })
 
@@ -306,12 +311,14 @@ end
 ---
 ---@see |vim.tbl_extend()|
 ---
----@param behavior string Decides what to do if a key is found in more than one map:
+---@generic T1: table
+---@generic T2: table
+---@param behavior "error"|"keep"|"force" Decides what to do if a key is found in more than one map:
 ---      - "error": raise an error
 ---      - "keep":  use value from the leftmost map
 ---      - "force": use value from the rightmost map
----@param ... table Two or more map-like tables
----@return table Merged table
+---@param ... T2 Two or more map-like tables
+---@return T1|T2 Merged table
 function vim.tbl_deep_extend(behavior, ...)
   return tbl_extend(behavior, true, ...)
 end
@@ -407,11 +414,12 @@ end
 ---
 ---@see |vim.tbl_extend()|
 ---
----@param dst table List which will be modified and appended to
+---@generic T: table
+---@param dst T List which will be modified and appended to
 ---@param src table List from which values will be inserted
----@param start number Start index on src. Defaults to 1
----@param finish number Final index on src. Defaults to `#src`
----@return table dst
+---@param start number|nil Start index on src. Defaults to 1
+---@param finish number|nil Final index on src. Defaults to `#src`
+---@return T dst
 function vim.list_extend(dst, src, start, finish)
   vim.validate({
     dst = { dst, 't' },
@@ -506,10 +514,11 @@ end
 
 --- Creates a copy of a table containing only elements from start to end (inclusive)
 ---
----@param list table Table
+---@generic T
+---@param list T[] Table
 ---@param start number Start range of slice
 ---@param finish number End range of slice
----@return table Copy of table sliced from start to finish (inclusive)
+---@return T[] Copy of table sliced from start to finish (inclusive)
 function vim.list_slice(list, start, finish)
   local new_list = {}
   for i = start or 1, finish or #list do
-- 
cgit 


From 24a1c7f556bba35a9c31c2fdd19cf4b8c00a4395 Mon Sep 17 00:00:00 2001
From: Folke Lemaitre 
Date: Wed, 28 Sep 2022 09:11:21 +0200
Subject: feat: added support for optional params to lua2dox

---
 runtime/lua/vim/shared.lua | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 1d0a6d5406..5566bd5e35 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -417,8 +417,8 @@ end
 ---@generic T: table
 ---@param dst T List which will be modified and appended to
 ---@param src table List from which values will be inserted
----@param start number|nil Start index on src. Defaults to 1
----@param finish number|nil Final index on src. Defaults to `#src`
+---@param start? number Start index on src. Defaults to 1
+---@param finish? number Final index on src. Defaults to `#src`
 ---@return T dst
 function vim.list_extend(dst, src, start, finish)
   vim.validate({
-- 
cgit 


From 1da7b4eb699fb04cc97dec389470fd0fbd64091d Mon Sep 17 00:00:00 2001
From: Folke Lemaitre 
Date: Wed, 28 Sep 2022 13:22:08 +0200
Subject: feat: added support for specifying types for lua2dox

---
 runtime/lua/vim/shared.lua | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 5566bd5e35..fa2af57cfc 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -63,7 +63,7 @@ end)()
 ---@param s string String to split
 ---@param sep string Separator or pattern
 ---@param plain boolean If `true` use `sep` literally (passed to string.find)
----@return fun():string Iterator over the split components
+---@return fun():string (function) Iterator over the split components
 function vim.gsplit(s, sep, plain)
   vim.validate({ s = { s, 's' }, sep = { sep, 's' }, plain = { plain, 'b', true } })
 
@@ -112,7 +112,7 @@ end
 ---
 ---@param s string String to split
 ---@param sep string Separator or pattern
----@param kwargs {plain: boolean, trimempty: boolean}|nil Keyword arguments:
+---@param kwargs? {plain: boolean, trimempty: boolean} (table|nil) Keyword arguments:
 ---       - plain: (boolean) If `true` use `sep` literally (passed to string.find)
 ---       - trimempty: (boolean) If `true` remove empty items from the front
 ---         and back of the list
@@ -159,9 +159,9 @@ end
 ---
 ---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
----@param t table Table
+---@param t table (table) Table
 ---@generic T: table
----@return T[] List of keys
+---@return T[] (list) List of keys
 function vim.tbl_keys(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
 
@@ -176,8 +176,8 @@ end
 --- However, the order of the return table of values is not guaranteed.
 ---
 ---@generic T
----@param t table Table
----@return T[] List of values
+---@param t table (table) Table
+---@return T[] (list) List of values
 function vim.tbl_values(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
 
@@ -191,8 +191,8 @@ end
 --- Apply a function to all values of a table.
 ---
 ---@generic T
----@param func fun(value: T): any Function
----@param t table Table
+---@param func fun(value: T): any (function) Function
+---@param t table (table) Table
 ---@return table Table of transformed values
 function vim.tbl_map(func, t)
   vim.validate({ func = { func, 'c' }, t = { t, 't' } })
@@ -207,9 +207,9 @@ end
 --- Filter a table using a predicate function
 ---
 ---@generic T
----@param func fun(value: T): boolean Function
----@param t table Table
----@return T[] Table of filtered values
+---@param func fun(value: T): boolean (function) Function
+---@param t table (table) Table
+---@return T[] (table) Table of filtered values
 function vim.tbl_filter(func, t)
   vim.validate({ func = { func, 'c' }, t = { t, 't' } })
 
@@ -313,12 +313,12 @@ end
 ---
 ---@generic T1: table
 ---@generic T2: table
----@param behavior "error"|"keep"|"force" Decides what to do if a key is found in more than one map:
+---@param behavior "error"|"keep"|"force" (string) Decides what to do if a key is found in more than one map:
 ---      - "error": raise an error
 ---      - "keep":  use value from the leftmost map
 ---      - "force": use value from the rightmost map
 ---@param ... T2 Two or more map-like tables
----@return T1|T2 Merged table
+---@return T1|T2 (table) Merged table
 function vim.tbl_deep_extend(behavior, ...)
   return tbl_extend(behavior, true, ...)
 end
@@ -515,10 +515,10 @@ end
 --- Creates a copy of a table containing only elements from start to end (inclusive)
 ---
 ---@generic T
----@param list T[] Table
+---@param list T[] (list) Table
 ---@param start number Start range of slice
 ---@param finish number End range of slice
----@return T[] Copy of table sliced from start to finish (inclusive)
+---@return T[] (list) Copy of table sliced from start to finish (inclusive)
 function vim.list_slice(list, start, finish)
   local new_list = {}
   for i = start or 1, finish or #list do
-- 
cgit 


From 8c2226fc30931690186390d86f963cd43e6947ef Mon Sep 17 00:00:00 2001
From: Folke Lemaitre 
Date: Sun, 9 Oct 2022 12:40:56 +0200
Subject: fix(lua): properly configure luacheck and remove `local vim = ...`
 lines (#20551)

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

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index fa2af57cfc..4b3a681eb2 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -6,7 +6,7 @@
 -- or the test suite. (Eventually the test suite will be run in a worker process,
 -- so this wouldn't be a separate case to consider)
 
-local vim = vim or {}
+vim = vim or {}
 
 --- Returns a deep copy of the given object. Non-table objects are copied as
 --- in a typical Lua assignment, whereas table objects are copied recursively.
-- 
cgit 


From a7a83bc4c25d63f3ae0a7a56e5211df1444699c4 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" 
Date: Sun, 9 Oct 2022 18:19:43 +0200
Subject: fix(docs-html): update parser

- Improve generated HTML by updating parser which includes fixes for
  single "'" and single "|":
  https://github.com/neovim/tree-sitter-vimdoc/pull/31
- Updated parser also fixes the conceal issue for "help" highlight
  queries https://github.com/neovim/tree-sitter-vimdoc/issues/23 by
  NOT including whitespace in nodes.
  - But this means we need to restore the getws() function which scrapes
    leading whitespace from the original input (buffer).
---
 runtime/lua/vim/shared.lua | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 4b3a681eb2..f03d608e56 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -100,10 +100,10 @@ end
 ---
 --- Examples:
 --- 
----  split(":aa::b:", ":")     --> {'','aa','','b',''}
----  split("axaby", "ab?")     --> {'','x','y'}
----  split("x*yz*o", "*", {plain=true})  --> {'x','yz','o'}
----  split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
+---  split(":aa::b:", ":")     => {'','aa','','b',''}
+---  split("axaby", "ab?")     => {'','x','y'}
+---  split("x*yz*o", "*", {plain=true})  => {'x','yz','o'}
+---  split("|x|y|z|", "|", {trimempty=true}) => {'x', 'y', 'z'}
 --- 

 ---
 ---@see |vim.gsplit()|
-- 
cgit 


From 4573cfa3adac3a7dbf1b6b032471a1c14adc7427 Mon Sep 17 00:00:00 2001
From: NAKAI Tsuyoshi <82267684+uga-rosa@users.noreply.github.com>
Date: Mon, 24 Oct 2022 21:53:53 +0900
Subject: fix(lua): pesc, tbl_islist result types #20751

Problem:
- pesc() returns multiple results, it should return a single result.
- tbl_islist() returns non-boolean in some branches.
- Docstring: @generic must be declared first

Solution:
Constrain docstring annotations.
Fix return types.

Co-authored-by: Justin M. Keyes 
---
 runtime/lua/vim/shared.lua | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index f03d608e56..f980547ae4 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -62,7 +62,7 @@ end)()
 ---
 ---@param s string String to split
 ---@param sep string Separator or pattern
----@param plain boolean If `true` use `sep` literally (passed to string.find)
+---@param plain (boolean|nil) If `true` use `sep` literally (passed to string.find)
 ---@return fun():string (function) Iterator over the split components
 function vim.gsplit(s, sep, plain)
   vim.validate({ s = { s, 's' }, sep = { sep, 's' }, plain = { plain, 'b', true } })
@@ -108,11 +108,9 @@ end
 ---
 ---@see |vim.gsplit()|
 ---
----@alias split_kwargs {plain: boolean, trimempty: boolean} | boolean | nil
----
 ---@param s string String to split
 ---@param sep string Separator or pattern
----@param kwargs? {plain: boolean, trimempty: boolean} (table|nil) Keyword arguments:
+---@param kwargs ({plain: boolean, trimempty: boolean}|nil) Keyword arguments:
 ---       - plain: (boolean) If `true` use `sep` literally (passed to string.find)
 ---       - trimempty: (boolean) If `true` remove empty items from the front
 ---         and back of the list
@@ -159,8 +157,8 @@ end
 ---
 ---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
----@param t table (table) Table
 ---@generic T: table
+---@param t table (table) Table
 ---@return T[] (list) List of keys
 function vim.tbl_keys(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
@@ -417,8 +415,8 @@ end
 ---@generic T: table
 ---@param dst T List which will be modified and appended to
 ---@param src table List from which values will be inserted
----@param start? number Start index on src. Defaults to 1
----@param finish? number Final index on src. Defaults to `#src`
+---@param start (number|nil) Start index on src. Defaults to 1
+---@param finish (number|nil) Final index on src. Defaults to `#src`
 ---@return T dst
 function vim.list_extend(dst, src, start, finish)
   vim.validate({
@@ -486,7 +484,7 @@ function vim.tbl_islist(t)
     -- TODO(bfredl): in the future, we will always be inside nvim
     -- then this check can be deleted.
     if vim._empty_dict_mt == nil then
-      return nil
+      return false
     end
     return getmetatable(t) ~= vim._empty_dict_mt
   end
@@ -544,7 +542,7 @@ end
 ---@return string %-escaped pattern string
 function vim.pesc(s)
   vim.validate({ s = { s, 's' } })
-  return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1')
+  return (s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1'))
 end
 
 --- Tests if `s` starts with `prefix`.
-- 
cgit 


From e15f61b1bd60f6a198a0d9969cea407784ff71d0 Mon Sep 17 00:00:00 2001
From: Max 
Date: Mon, 14 Nov 2022 20:26:27 +0100
Subject: fix(lua): make `vim.deepcopy` work with `vim.NIL`

style: changed double quotes to single quotes

feat: add tests

fix tests
---
 runtime/lua/vim/shared.lua | 3 +++
 1 file changed, 3 insertions(+)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index f980547ae4..f4a57c13c8 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -49,6 +49,9 @@ vim.deepcopy = (function()
     if f then
       return f(orig, cache or {})
     else
+      if type(orig) == 'userdata' and orig == vim.NIL then
+        return vim.NIL
+      end
       error('Cannot deepcopy object of type ' .. type(orig))
     end
   end
-- 
cgit 


From 0b05bd87c04f9cde5c84a062453619349e370795 Mon Sep 17 00:00:00 2001
From: Christian Clason 
Date: Wed, 23 Nov 2022 12:31:49 +0100
Subject: docs(gen): support language annotation in docstrings

---
 runtime/lua/vim/shared.lua | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index f4a57c13c8..9129500866 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -102,11 +102,11 @@ end
 --- Splits a string at each instance of a separator.
 ---
 --- Examples:
---- 
----  split(":aa::b:", ":")     => {'','aa','','b',''}
----  split("axaby", "ab?")     => {'','x','y'}
----  split("x*yz*o", "*", {plain=true})  => {'x','yz','o'}
----  split("|x|y|z|", "|", {trimempty=true}) => {'x', 'y', 'z'}
+--- 
lua
+---  split(":aa::b:", ":")                   --> {'','aa','','b',''}
+---  split("axaby", "ab?")                   --> {'','x','y'}
+---  split("x*yz*o", "*", {plain=true})      --> {'x','yz','o'}
+---  split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
 --- 

 ---
 ---@see |vim.gsplit()|
@@ -383,7 +383,7 @@ end
 --- Return `nil` if the key does not exist.
 ---
 --- Examples:
---- 
+--- 
lua
 ---  vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
 ---  vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
 --- 

@@ -495,9 +495,9 @@ end
 
 --- Counts the number of non-nil values in table `t`.
 ---
---- 
---- vim.tbl_count({ a=1, b=2 }) => 2
---- vim.tbl_count({ 1, 2 }) => 2
+--- 
lua
+--- vim.tbl_count({ a=1, b=2 })  --> 2
+--- vim.tbl_count({ 1, 2 })      --> 2
 --- 

 ---
 ---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
@@ -571,7 +571,7 @@ end
 --- Validates a parameter specification (types and values).
 ---
 --- Usage example:
---- 
+--- 
lua
 ---  function user.new(name, age, hobbies)
 ---    vim.validate{
 ---      name={name, 'string'},
@@ -583,24 +583,24 @@ end
 --- 

 ---
 --- Examples with explicit argument values (can be run directly):
---- 
+--- 
lua
 ---  vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
----     => NOP (success)
+---     --> NOP (success)
 ---
 ---  vim.validate{arg1={1, 'table'}}
----     => error('arg1: expected table, got number')
+---     --> error('arg1: expected table, got number')
 ---
 ---  vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
----     => error('arg1: expected even number, got 3')
+---     --> error('arg1: expected even number, got 3')
 --- 

 ---
 --- If multiple types are valid they can be given as a list.
---- 
+--- 
lua
 ---  vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}}
----     => NOP (success)
+---     --> NOP (success)
 ---
 ---  vim.validate{arg1={1, {'string', table'}}}
----     => error('arg1: expected string|table, got number')
+---     --> error('arg1: expected string|table, got number')
 ---
 --- 

 ---
@@ -735,7 +735,7 @@ end
 --- If {create} is `nil`, this will create a defaulttable whose constructor function is
 --- this function, effectively allowing to create nested tables on the fly:
 ---
---- 
+--- 
lua
 --- local a = vim.defaulttable()
 --- a.b.c = 1
 --- 

-- 
cgit 


From 26c918d03f5b38df900316c0601065ec1ea96264 Mon Sep 17 00:00:00 2001
From: William Boman 
Date: Thu, 15 Dec 2022 02:27:23 +0100
Subject: fix(lua): always return nil values in vim.tbl_get when no results

While `return` and `return nil` are for most intents and purposes
identical, there are situations where they're not. For example,
calculating the amount of values via the `select()` function will yield
varying results:

```lua
local function nothing() return     end
local function null()    return nil end

select('#', nothing()) -- 0
select('#', null())    -- 1
```

`vim.tbl_get` currently returns both nil and no results, which makes it
unreliable to use in certain situations without manually accounting for
these discrepancies.
---
 runtime/lua/vim/shared.lua | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 9129500866..5ffd11682c 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -395,15 +395,14 @@ end
 function vim.tbl_get(o, ...)
   local keys = { ... }
   if #keys == 0 then
-    return
+    return nil
   end
   for i, k in ipairs(keys) do
-    if type(o[k]) ~= 'table' and next(keys, i) then
-      return nil
-    end
     o = o[k]
     if o == nil then
-      return
+      return nil
+    elseif type(o) ~= 'table' and next(keys, i) then
+      return nil
     end
   end
   return o
-- 
cgit 


From dfb840970c36056584e9a55d77a2030b4e403e9d Mon Sep 17 00:00:00 2001
From: Christian Clason 
Date: Wed, 28 Dec 2022 14:20:42 +0100
Subject: docs(lua): fix treesitter parsing errors

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

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 5ffd11682c..6fc40bb905 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -113,7 +113,7 @@ end
 ---
 ---@param s string String to split
 ---@param sep string Separator or pattern
----@param kwargs ({plain: boolean, trimempty: boolean}|nil) Keyword arguments:
+---@param kwargs (table|nil) Keyword arguments:
 ---       - plain: (boolean) If `true` use `sep` literally (passed to string.find)
 ---       - trimempty: (boolean) If `true` remove empty items from the front
 ---         and back of the list
-- 
cgit 


From e35b9020b16985eee26e942f9a3f6b045bc3809b Mon Sep 17 00:00:00 2001
From: notomo 
Date: Wed, 4 Jan 2023 20:48:41 +0900
Subject: docs(lua): adjust some type annotations

---
 runtime/lua/vim/shared.lua | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 6fc40bb905..b53c66ba63 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -516,8 +516,8 @@ end
 ---
 ---@generic T
 ---@param list T[] (list) Table
----@param start number Start range of slice
----@param finish number End range of slice
+---@param start number|nil Start range of slice
+---@param finish number|nil End range of slice
 ---@return T[] (list) Copy of table sliced from start to finish (inclusive)
 function vim.list_slice(list, start, finish)
   local new_list = {}
-- 
cgit 


From 34b973b1d9e3b0c6f546e3aa661c29edd5a1ab87 Mon Sep 17 00:00:00 2001
From: Naru 
Date: Mon, 16 Jan 2023 06:32:23 +0900
Subject: docs(lua): use luaref tag instead of www.lua.org #21813

---
 runtime/lua/vim/shared.lua | 2 ++
 1 file changed, 2 insertions(+)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index b53c66ba63..7967d13943 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -60,6 +60,7 @@ end)()
 --- Splits a string at each instance of a separator.
 ---
 ---@see |vim.split()|
+---@see |luaref-patterns|
 ---@see https://www.lua.org/pil/20.2.html
 ---@see http://lua-users.org/wiki/StringLibraryTutorial
 ---
@@ -529,6 +530,7 @@ end
 
 --- Trim whitespace (Lua pattern "%s") from both sides of a string.
 ---
+---@see |luaref-patterns|
 ---@see https://www.lua.org/pil/20.2.html
 ---@param s string String to trim
 ---@return string String with whitespace removed from its beginning and end
-- 
cgit 


From cb757f2663e6950e655c6306d713338dfa66b18d Mon Sep 17 00:00:00 2001
From: Arnout Engelen 
Date: Mon, 23 Jan 2023 10:26:46 +0100
Subject: build: make generated source files reproducible #21586

Problem:
Build is not reproducible, because generated source files (.c/.h/) are not
deterministic, mostly because Lua pairs() is unordered by design (for security).

https://github.com/LuaJIT/LuaJIT/issues/626#issuecomment-707005671
https://www.lua.org/manual/5.1/manual.html#pdf-next
> The order in which the indices are enumerated is not specified [...]
>
>> The hardening of the VM deliberately randomizes string hashes. This in
>> turn randomizes the iteration order of tables with string keys.

Solution:
- Update the code generation scripts to be deterministic.
    - That is only a partial solution: the exported function
      (funcs_metadata.generated.h) and ui event
      (ui_events_metadata.generated.h) metadata have some mpack'ed
      tables, which are not serialized deterministically.
    - As a workaround, introduce `PRG_GEN_LUA` cmake setting, so you can
      inject a modified build of luajit (with LUAJIT_SECURITY_PRN=0)
      that preserves table order.
    - Longer-term we should change the mpack'ed data structure so it no
      longer uses tables keyed by strings.

Closes #20124

Co-Authored-By: dundargoc 
Co-Authored-By: Arnout Engelen 
---
 runtime/lua/vim/shared.lua | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 7967d13943..cc48e3f193 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -458,6 +458,33 @@ function vim.tbl_flatten(t)
   return result
 end
 
+--- Enumerate a table sorted by its keys.
+---
+---@see Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
+---
+---@param t table List-like table
+---@return iterator over sorted keys and their values
+function vim.spairs(t)
+  assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
+
+  -- collect the keys
+  local keys = {}
+  for k in pairs(t) do
+    table.insert(keys, k)
+  end
+  table.sort(keys)
+
+  -- Return the iterator function.
+  -- TODO(justinmk): Return "iterator function, table {t}, and nil", like pairs()?
+  local i = 0
+  return function()
+    i = i + 1
+    if keys[i] then
+      return keys[i], t[keys[i]]
+    end
+  end
+end
+
 --- Tests if a Lua table can be treated as an array.
 ---
 --- Empty table `{}` is assumed to be an array, unless it was created by
-- 
cgit