From 80e6f81862d943b2d31639a0e437b6abdff3373c Mon Sep 17 00:00:00 2001
From: zeertzjq <zeertzjq@outlook.com>
Date: Sun, 6 Mar 2022 21:16:21 +0800
Subject: docs(lua): reference runtime/lua/vim/_editor.lua

---
 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 e170befa4c..48d0bd3672 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -2,7 +2,7 @@
 --
 -- The singular purpose of this module is to share code with the Nvim
 -- test-suite. If, in the future, Nvim itself is used to run the test-suite
--- instead of "vanilla Lua", these functions could move to src/nvim/lua/vim.lua
+-- instead of "vanilla Lua", these functions could move to runtime/lua/vim/_editor.lua
 
 local vim = vim or {}
 
-- 
cgit 


From f39a12d629500bdbacb389ed593adac34d058fcb Mon Sep 17 00:00:00 2001
From: bfredl <bjorn.linse@gmail.com>
Date: Sun, 6 Mar 2022 13:13:10 +0100
Subject: refactor(lua): make vim submodule lazy loading declarative

This will allow us to also use the same logic for lua threads and
processes, later.
---
 runtime/lua/vim/shared.lua | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 48d0bd3672..8124b23eb1 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -1,8 +1,10 @@
 -- Functions shared by Nvim and its test-suite.
 --
--- The singular purpose of this module is to share code with the Nvim
--- test-suite. If, in the future, Nvim itself is used to run the test-suite
--- instead of "vanilla Lua", these functions could move to runtime/lua/vim/_editor.lua
+-- These are "pure" lua functions not depending of the state of the editor.
+-- Thus they should always be available whenever nvim-related lua code is run,
+-- regardless if it is code in the editor itself, or in worker threads/processes,
+-- 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 {}
 
-- 
cgit 


From d238b8f6003d34cae7f65ff7585b48a2cd9449fb Mon Sep 17 00:00:00 2001
From: dundargoc <33953936+dundargoc@users.noreply.github.com>
Date: Thu, 17 Mar 2022 06:21:24 +0100
Subject: chore: fix typos (#17670)

Co-authored-by: zeertzjq <zeertzjq@outlook.com>
---
 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 8124b23eb1..3eb332279a 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -331,7 +331,7 @@ end
 
 --- Add the reverse lookup values to an existing table.
 --- For example:
---- `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }`
+--- ``tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }``
 --
 --Do note that it *modifies* the input.
 ---@param o table The table to add the reverse to.
-- 
cgit 


From 69f1de86dca28d6e339351082df1309ef4fbb6a6 Mon Sep 17 00:00:00 2001
From: Michael Lingelbach <m.j.lbach@gmail.com>
Date: Thu, 24 Mar 2022 12:01:04 -0700
Subject: feat: add vim.tbl_get (#17831)

vim.tbl_get takes a table with subsequent string arguments (variadic) that
index into the table. If the value pointed to by the set of keys exists,
the function returns the value. If the set of keys does not exist, the
function returns nil.
---
 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 3eb332279a..f0dc34608c 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -347,6 +347,33 @@ function vim.tbl_add_reverse_lookup(o)
   return o
 end
 
+--- Index into a table (first argument) via string keys passed as subsequent arguments.
+--- Return `nil` if the key does not exist.
+--_
+--- Examples:
+--- <pre>
+---  vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
+---  vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
+--- </pre>
+---
+---@param o Table to index
+---@param ... Optional strings (0 or more, variadic) via which to index the table
+---
+---@returns nested value indexed by key if it exists, else nil
+function vim.tbl_get(o, ...)
+  local keys = {...}
+  if #keys == 0 then
+    return
+  end
+  for _, k in ipairs(keys) do
+    o = o[k]
+    if o == nil then
+      return
+    end
+  end
+  return o
+end
+
 --- Extends a list-like table with the values of another list-like table.
 ---
 --- NOTE: This mutates dst!
-- 
cgit 


From 069da468d5d2af01279a121473aef09c87b163aa Mon Sep 17 00:00:00 2001
From: William Boman <william@redwill.se>
Date: Sun, 1 May 2022 21:08:05 +0200
Subject: fix(shared): avoid indexing unindexable values in vim.tbl_get()
 (#18337)

---
 runtime/lua/vim/shared.lua | 5 ++++-
 1 file changed, 4 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 f0dc34608c..172fac3a88 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -365,7 +365,10 @@ function vim.tbl_get(o, ...)
   if #keys == 0 then
     return
   end
-  for _, k in ipairs(keys) do
+  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
-- 
cgit 


From aefdc6783cb77f09786542c90901a9e7120bea42 Mon Sep 17 00:00:00 2001
From: Christian Clason <c.clason@uni-graz.at>
Date: Mon, 9 May 2022 11:23:51 +0200
Subject: chore: format runtime with stylua

---
 runtime/lua/vim/shared.lua | 144 ++++++++++++++++++++++++++-------------------
 1 file changed, 84 insertions(+), 60 deletions(-)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 172fac3a88..d9dc77e219 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -16,7 +16,7 @@ local vim = vim or {}
 ---
 ---@param orig table Table to copy
 ---@returns New table of copied keys and (nested) values.
-function vim.deepcopy(orig) end  -- luacheck: no unused
+function vim.deepcopy(orig) end -- luacheck: no unused
 vim.deepcopy = (function()
   local function _id(v)
     return v
@@ -24,7 +24,9 @@ vim.deepcopy = (function()
 
   local deepcopy_funcs = {
     table = function(orig, cache)
-      if cache[orig] then return cache[orig] end
+      if cache[orig] then
+        return cache[orig]
+      end
       local copy = {}
 
       cache[orig] = copy
@@ -46,7 +48,7 @@ vim.deepcopy = (function()
     if f then
       return f(orig, cache or {})
     else
-      error("Cannot deepcopy object of type "..type(orig))
+      error('Cannot deepcopy object of type ' .. type(orig))
     end
   end
 end)()
@@ -62,14 +64,14 @@ end)()
 ---@param plain If `true` use `sep` literally (passed to String.find)
 ---@returns Iterator over the split components
 function vim.gsplit(s, sep, plain)
-  vim.validate{s={s,'s'},sep={sep,'s'},plain={plain,'b',true}}
+  vim.validate({ s = { s, 's' }, sep = { sep, 's' }, plain = { plain, 'b', true } })
 
   local start = 1
   local done = false
 
   local function _pass(i, j, ...)
     if i then
-      assert(j+1 > start, "Infinite loop detected")
+      assert(j + 1 > start, 'Infinite loop detected')
       local seg = s:sub(start, i - 1)
       start = j + 1
       return seg, ...
@@ -87,7 +89,7 @@ function vim.gsplit(s, sep, plain)
       if start == #s then
         done = true
       end
-      return _pass(start+1, start)
+      return _pass(start + 1, start)
     end
     return _pass(s:find(sep, start, plain))
   end
@@ -119,7 +121,7 @@ function vim.split(s, sep, kwargs)
     -- Support old signature for backward compatibility
     plain = kwargs
   else
-    vim.validate { kwargs = {kwargs, 't', true} }
+    vim.validate({ kwargs = { kwargs, 't', true } })
     kwargs = kwargs or {}
     plain = kwargs.plain
     trimempty = kwargs.trimempty
@@ -128,7 +130,7 @@ function vim.split(s, sep, kwargs)
   local t = {}
   local skip = trimempty
   for c in vim.gsplit(s, sep, plain) do
-    if c ~= "" then
+    if c ~= '' then
       skip = false
     end
 
@@ -139,7 +141,7 @@ function vim.split(s, sep, kwargs)
 
   if trimempty then
     for i = #t, 1, -1 do
-      if t[i] ~= "" then
+      if t[i] ~= '' then
         break
       end
       table.remove(t, i)
@@ -157,7 +159,7 @@ end
 ---@param t Table
 ---@returns list of keys
 function vim.tbl_keys(t)
-  assert(type(t) == 'table', string.format("Expected table, got %s", type(t)))
+  assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
 
   local keys = {}
   for k, _ in pairs(t) do
@@ -172,7 +174,7 @@ end
 ---@param t Table
 ---@returns list of values
 function vim.tbl_values(t)
-  assert(type(t) == 'table', string.format("Expected table, got %s", type(t)))
+  assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
 
   local values = {}
   for _, v in pairs(t) do
@@ -186,7 +188,7 @@ end
 ---@param func function or callable table
 ---@param t table
 function vim.tbl_map(func, t)
-  vim.validate{func={func,'c'},t={t,'t'}}
+  vim.validate({ func = { func, 'c' }, t = { t, 't' } })
 
   local rettab = {}
   for k, v in pairs(t) do
@@ -200,7 +202,7 @@ end
 ---@param func function or callable table
 ---@param t table
 function vim.tbl_filter(func, t)
-  vim.validate{func={func,'c'},t={t,'t'}}
+  vim.validate({ func = { func, 'c' }, t = { t, 't' } })
 
   local rettab = {}
   for _, entry in pairs(t) do
@@ -217,9 +219,9 @@ end
 ---@param value Value to compare
 ---@returns true if `t` contains `value`
 function vim.tbl_contains(t, value)
-  vim.validate{t={t,'t'}}
+  vim.validate({ t = { t, 't' } })
 
-  for _,v in ipairs(t) do
+  for _, v in ipairs(t) do
     if v == value then
       return true
     end
@@ -233,23 +235,23 @@ end
 ---
 ---@param t Table to check
 function vim.tbl_isempty(t)
-  assert(type(t) == 'table', string.format("Expected table, got %s", type(t)))
+  assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
   return next(t) == nil
 end
 
 --- we only merge empty tables or tables that are not a list
 ---@private
 local function can_merge(v)
-  return type(v) == "table" and (vim.tbl_isempty(v) or not vim.tbl_islist(v))
+  return type(v) == 'table' and (vim.tbl_isempty(v) or not vim.tbl_islist(v))
 end
 
 local function tbl_extend(behavior, deep_extend, ...)
-  if (behavior ~= 'error' and behavior ~= 'keep' and behavior ~= 'force') then
-    error('invalid "behavior": '..tostring(behavior))
+  if behavior ~= 'error' and behavior ~= 'keep' and behavior ~= 'force' then
+    error('invalid "behavior": ' .. tostring(behavior))
   end
 
   if select('#', ...) < 2 then
-    error('wrong number of arguments (given '..tostring(1 + select('#', ...))..', expected at least 3)')
+    error('wrong number of arguments (given ' .. tostring(1 + select('#', ...)) .. ', expected at least 3)')
   end
 
   local ret = {}
@@ -259,15 +261,15 @@ local function tbl_extend(behavior, deep_extend, ...)
 
   for i = 1, select('#', ...) do
     local tbl = select(i, ...)
-    vim.validate{["after the second argument"] = {tbl,'t'}}
+    vim.validate({ ['after the second argument'] = { tbl, 't' } })
     if tbl then
       for k, v in pairs(tbl) do
         if deep_extend and can_merge(v) and can_merge(ret[k]) then
           ret[k] = tbl_extend(behavior, true, ret[k], v)
         elseif behavior ~= 'force' and ret[k] ~= nil then
           if behavior == 'error' then
-            error('key found in more than one map: '..k)
-          end  -- Else behavior is "keep".
+            error('key found in more than one map: ' .. k)
+          end -- Else behavior is "keep".
         else
           ret[k] = v
         end
@@ -311,8 +313,12 @@ end
 ---@param b second value
 ---@returns `true` if values are equals, else `false`.
 function vim.deep_equal(a, b)
-  if a == b then return true end
-  if type(a) ~= type(b) then return false end
+  if a == b then
+    return true
+  end
+  if type(a) ~= type(b) then
+    return false
+  end
   if type(a) == 'table' then
     for k, v in pairs(a) do
       if not vim.deep_equal(v, b[k]) then
@@ -340,7 +346,13 @@ function vim.tbl_add_reverse_lookup(o)
   for _, k in ipairs(keys) do
     local v = o[k]
     if o[v] then
-      error(string.format("The reverse lookup found an existing value for %q while processing key %q", tostring(v), tostring(k)))
+      error(
+        string.format(
+          'The reverse lookup found an existing value for %q while processing key %q',
+          tostring(v),
+          tostring(k)
+        )
+      )
     end
     o[v] = k
   end
@@ -361,7 +373,7 @@ end
 ---
 ---@returns nested value indexed by key if it exists, else nil
 function vim.tbl_get(o, ...)
-  local keys = {...}
+  local keys = { ... }
   if #keys == 0 then
     return
   end
@@ -389,12 +401,12 @@ end
 ---@param finish Final index on src. defaults to #src
 ---@returns dst
 function vim.list_extend(dst, src, start, finish)
-  vim.validate {
-    dst = {dst, 't'};
-    src = {src, 't'};
-    start = {start, 'n', true};
-    finish = {finish, 'n', true};
-  }
+  vim.validate({
+    dst = { dst, 't' },
+    src = { src, 't' },
+    start = { start, 'n', true },
+    finish = { finish, 'n', true },
+  })
   for i = start or 1, finish or #src do
     table.insert(dst, src[i])
   end
@@ -414,7 +426,7 @@ function vim.tbl_flatten(t)
     local n = #_t
     for i = 1, n do
       local v = _t[i]
-      if type(v) == "table" then
+      if type(v) == 'table' then
         _tbl_flatten(v)
       elseif v then
         table.insert(result, v)
@@ -441,7 +453,7 @@ function vim.tbl_islist(t)
   local count = 0
 
   for k, _ in pairs(t) do
-    if type(k) == "number" then
+    if type(k) == 'number' then
       count = count + 1
     else
       return false
@@ -471,10 +483,12 @@ end
 ---@param t Table
 ---@returns Number that is the number of the value in table
 function vim.tbl_count(t)
-  vim.validate{t={t,'t'}}
+  vim.validate({ t = { t, 't' } })
 
   local count = 0
-  for _ in pairs(t) do count = count + 1 end
+  for _ in pairs(t) do
+    count = count + 1
+  end
   return count
 end
 
@@ -487,7 +501,7 @@ end
 function vim.list_slice(list, start, finish)
   local new_list = {}
   for i = start or 1, finish or #list do
-    new_list[#new_list+1] = list[i]
+    new_list[#new_list + 1] = list[i]
   end
   return new_list
 end
@@ -498,7 +512,7 @@ end
 ---@param s String to trim
 ---@returns String with whitespace removed from its beginning and end
 function vim.trim(s)
-  vim.validate{s={s,'s'}}
+  vim.validate({ s = { s, 's' } })
   return s:match('^%s*(.*%S)') or ''
 end
 
@@ -508,7 +522,7 @@ end
 ---@param s  String to escape
 ---@returns  %-escaped pattern string
 function vim.pesc(s)
-  vim.validate{s={s,'s'}}
+  vim.validate({ s = { s, 's' } })
   return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1')
 end
 
@@ -518,7 +532,7 @@ end
 ---@param prefix (string) a prefix
 ---@return (boolean) true if `prefix` is a prefix of s
 function vim.startswith(s, prefix)
-  vim.validate { s = {s, 's'}; prefix = {prefix, 's'}; }
+  vim.validate({ s = { s, 's' }, prefix = { prefix, 's' } })
   return s:sub(1, #prefix) == prefix
 end
 
@@ -528,7 +542,7 @@ end
 ---@param suffix (string) a suffix
 ---@return (boolean) true if `suffix` is a suffix of s
 function vim.endswith(s, suffix)
-  vim.validate { s = {s, 's'}; suffix = {suffix, 's'}; }
+  vim.validate({ s = { s, 's' }, suffix = { suffix, 's' } })
   return #suffix == 0 or s:sub(-#suffix) == suffix
 end
 
@@ -582,18 +596,24 @@ end
 ---               only if the argument is valid. Can optionally return an additional
 ---               informative error message as the second returned value.
 ---             - msg: (optional) error string if validation fails
-function vim.validate(opt) end  -- luacheck: no unused
+function vim.validate(opt) end -- luacheck: no unused
 
 do
   local type_names = {
-    ['table']    = 'table',    t = 'table',
-    ['string']   = 'string',   s = 'string',
-    ['number']   = 'number',   n = 'number',
-    ['boolean']  = 'boolean',  b = 'boolean',
-    ['function'] = 'function', f = 'function',
-    ['callable'] = 'callable', c = 'callable',
-    ['nil']      = 'nil',
-    ['thread']   = 'thread',
+    ['table'] = 'table',
+    t = 'table',
+    ['string'] = 'string',
+    s = 'string',
+    ['number'] = 'number',
+    n = 'number',
+    ['boolean'] = 'boolean',
+    b = 'boolean',
+    ['function'] = 'function',
+    f = 'function',
+    ['callable'] = 'callable',
+    c = 'callable',
+    ['nil'] = 'nil',
+    ['thread'] = 'thread',
     ['userdata'] = 'userdata',
   }
 
@@ -612,21 +632,21 @@ do
         return false, string.format('opt[%s]: expected table, got %s', param_name, type(spec))
       end
 
-      local val = spec[1]   -- Argument value.
-      local types = spec[2]     -- Type name, or callable.
+      local val = spec[1] -- Argument value.
+      local types = spec[2] -- Type name, or callable.
       local optional = (true == spec[3])
 
       if type(types) == 'string' then
-        types = {types}
+        types = { types }
       end
 
       if vim.is_callable(types) then
         -- Check user-provided validation function.
         local valid, optional_message = types(val)
         if not valid then
-          local error_message = string.format("%s: expected %s, got %s", param_name, (spec[3] or '?'), tostring(val))
+          local error_message = string.format('%s: expected %s, got %s', param_name, (spec[3] or '?'), tostring(val))
           if optional_message ~= nil then
-            error_message = error_message .. string.format(". Info: %s", optional_message)
+            error_message = error_message .. string.format('. Info: %s', optional_message)
           end
 
           return false, error_message
@@ -646,10 +666,10 @@ do
           end
         end
         if not success then
-          return false, string.format("%s: expected %s, got %s", param_name, table.concat(types, '|'), type(val))
+          return false, string.format('%s: expected %s, got %s', param_name, table.concat(types, '|'), type(val))
         end
       else
-        return false, string.format("invalid type name: %s", tostring(types))
+        return false, string.format('invalid type name: %s', tostring(types))
       end
     end
 
@@ -668,9 +688,13 @@ end
 ---@param f Any object
 ---@return true if `f` is callable, else false
 function vim.is_callable(f)
-  if type(f) == 'function' then return true end
+  if type(f) == 'function' then
+    return true
+  end
   local m = getmetatable(f)
-  if m == nil then return false end
+  if m == nil then
+    return false
+  end
   return type(m.__call) == 'function'
 end
 
-- 
cgit 


From a6f4cfdefa6937b7a0a364277a8157d483631f6d Mon Sep 17 00:00:00 2001
From: adrian5 <adrian5@users.noreply.github.com>
Date: Wed, 11 May 2022 18:23:46 +0200
Subject: docs(api): improve shared lua functions docs (#17933)

---
 runtime/lua/vim/shared.lua | 142 +++++++++++++++++++++++----------------------
 1 file changed, 74 insertions(+), 68 deletions(-)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index d9dc77e219..9bbe356f03 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -15,7 +15,7 @@ local vim = vim or {}
 --- copied and will throw an error.
 ---
 ---@param orig table Table to copy
----@returns New table of copied keys and (nested) values.
+---@return table Table of copied keys and (nested) values.
 function vim.deepcopy(orig) end -- luacheck: no unused
 vim.deepcopy = (function()
   local function _id(v)
@@ -59,10 +59,10 @@ end)()
 ---@see https://www.lua.org/pil/20.2.html
 ---@see http://lua-users.org/wiki/StringLibraryTutorial
 ---
----@param s String to split
----@param sep Separator string or pattern
----@param plain If `true` use `sep` literally (passed to String.find)
----@returns Iterator over the split components
+---@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
 function vim.gsplit(s, sep, plain)
   vim.validate({ s = { s, 's' }, sep = { sep, 's' }, plain = { plain, 'b', true } })
 
@@ -107,13 +107,13 @@ end
 ---
 ---@see |vim.gsplit()|
 ---
----@param s String to split
----@param sep Separator string or pattern
----@param kwargs Keyword arguments:
+---@param s string String to split
+---@param sep string Separator or pattern
+---@param kwargs table 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
----@returns List-like table of the split components.
+---@return table List of split components
 function vim.split(s, sep, kwargs)
   local plain
   local trimempty = false
@@ -156,8 +156,8 @@ end
 ---
 ---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
----@param t Table
----@returns list of keys
+---@param t table Table
+---@return table List of keys
 function vim.tbl_keys(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
 
@@ -171,8 +171,8 @@ 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
----@returns list of values
+---@param t table Table
+---@return table List of values
 function vim.tbl_values(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
 
@@ -185,8 +185,9 @@ end
 
 --- Apply a function to all values of a table.
 ---
----@param func function or callable table
----@param t table
+---@param func function|table Function or callable table
+---@param t table Table
+---@return table Table of transformed values
 function vim.tbl_map(func, t)
   vim.validate({ func = { func, 'c' }, t = { t, 't' } })
 
@@ -199,8 +200,9 @@ end
 
 --- Filter a table using a predicate function
 ---
----@param func function or callable table
----@param t table
+---@param func function|table Function or callable table
+---@param t table Table
+---@return table Table of filtered values
 function vim.tbl_filter(func, t)
   vim.validate({ func = { func, 'c' }, t = { t, 't' } })
 
@@ -215,9 +217,9 @@ end
 
 --- Checks if a list-like (vector) table contains `value`.
 ---
----@param t Table to check
----@param value Value to compare
----@returns true if `t` contains `value`
+---@param t table Table to check
+---@param value any Value to compare
+---@return boolean `true` if `t` contains `value`
 function vim.tbl_contains(t, value)
   vim.validate({ t = { t, 't' } })
 
@@ -233,13 +235,14 @@ end
 ---
 ---@see https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
----@param t Table to check
+---@param t table Table to check
+---@return boolean `true` if `t` is empty
 function vim.tbl_isempty(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
   return next(t) == nil
 end
 
---- we only merge empty tables or tables that are not a list
+--- We only merge empty tables or tables that are not a list
 ---@private
 local function can_merge(v)
   return type(v) == 'table' and (vim.tbl_isempty(v) or not vim.tbl_islist(v))
@@ -283,11 +286,12 @@ end
 ---
 ---@see |extend()|
 ---
----@param behavior Decides what to do if a key is found in more than one map:
+---@param behavior 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 ... Two or more map-like tables.
+---@param ... table Two or more map-like tables
+---@return table Merged table
 function vim.tbl_extend(behavior, ...)
   return tbl_extend(behavior, false, ...)
 end
@@ -296,22 +300,23 @@ end
 ---
 ---@see |tbl_extend()|
 ---
----@param behavior Decides what to do if a key is found in more than one map:
+---@param behavior 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 ... Two or more map-like tables.
+---@param ... table Two or more map-like tables
+---@return table Merged table
 function vim.tbl_deep_extend(behavior, ...)
   return tbl_extend(behavior, true, ...)
 end
 
 --- Deep compare values for equality
 ---
---- Tables are compared recursively unless they both provide the `eq` methamethod.
+--- Tables are compared recursively unless they both provide the `eq` metamethod.
 --- All other types are compared using the equality `==` operator.
----@param a first value
----@param b second value
----@returns `true` if values are equals, else `false`.
+---@param a any First value
+---@param b any Second value
+---@return boolean `true` if values are equals, else `false`
 function vim.deep_equal(a, b)
   if a == b then
     return true
@@ -338,9 +343,10 @@ end
 --- Add the reverse lookup values to an existing table.
 --- For example:
 --- ``tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }``
---
---Do note that it *modifies* the input.
----@param o table The table to add the reverse to.
+---
+--- Note that this *modifies* the input.
+---@param o table Table to add the reverse to
+---@return table o
 function vim.tbl_add_reverse_lookup(o)
   local keys = vim.tbl_keys(o)
   for _, k in ipairs(keys) do
@@ -361,17 +367,17 @@ end
 
 --- Index into a table (first argument) via string keys passed as subsequent arguments.
 --- Return `nil` if the key does not exist.
---_
+---
 --- Examples:
 --- <pre>
 ---  vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
 ---  vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
 --- </pre>
 ---
----@param o Table to index
----@param ... Optional strings (0 or more, variadic) via which to index the table
+---@param o table Table to index
+---@param ... string Optional strings (0 or more, variadic) via which to index the table
 ---
----@returns nested value indexed by key if it exists, else nil
+---@return any Nested value indexed by key (if it exists), else nil
 function vim.tbl_get(o, ...)
   local keys = { ... }
   if #keys == 0 then
@@ -395,11 +401,11 @@ end
 ---
 ---@see |vim.tbl_extend()|
 ---
----@param dst list which will be modified and appended to.
----@param src list from which values will be inserted.
----@param start Start index on src. defaults to 1
----@param finish Final index on src. defaults to #src
----@returns dst
+---@param dst table 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
 function vim.list_extend(dst, src, start, finish)
   vim.validate({
     dst = { dst, 't' },
@@ -418,8 +424,8 @@ end
 ---
 ---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
----@param t List-like table
----@returns Flattened copy of the given list-like table.
+---@param t table List-like table
+---@return table Flattened copy of the given list-like table
 function vim.tbl_flatten(t)
   local result = {}
   local function _tbl_flatten(_t)
@@ -443,8 +449,8 @@ end
 --- |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result,
 --- for example from |rpcrequest()| or |vim.fn|.
 ---
----@param t Table
----@returns `true` if array-like table, else `false`.
+---@param t table Table
+---@return boolean `true` if array-like table, else `false`
 function vim.tbl_islist(t)
   if type(t) ~= 'table' then
     return false
@@ -480,8 +486,8 @@ end
 --- </pre>
 ---
 ---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
----@param t Table
----@returns Number that is the number of the value in table
+---@param t table Table
+---@return number Number of non-nil values in table
 function vim.tbl_count(t)
   vim.validate({ t = { t, 't' } })
 
@@ -494,10 +500,10 @@ end
 
 --- Creates a copy of a table containing only elements from start to end (inclusive)
 ---
----@param list table table
----@param start integer Start range of slice
----@param finish integer End range of slice
----@returns Copy of table sliced from start to finish (inclusive)
+---@param list table 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)
 function vim.list_slice(list, start, finish)
   local new_list = {}
   for i = start or 1, finish or #list do
@@ -509,8 +515,8 @@ end
 --- Trim whitespace (Lua pattern "%s") from both sides of a string.
 ---
 ---@see https://www.lua.org/pil/20.2.html
----@param s String to trim
----@returns String with whitespace removed from its beginning and end
+---@param s string String to trim
+---@return string String with whitespace removed from its beginning and end
 function vim.trim(s)
   vim.validate({ s = { s, 's' } })
   return s:match('^%s*(.*%S)') or ''
@@ -519,8 +525,8 @@ end
 --- Escapes magic chars in a Lua pattern.
 ---
 ---@see https://github.com/rxi/lume
----@param s  String to escape
----@returns  %-escaped pattern string
+---@param s string String to escape
+---@return string %-escaped pattern string
 function vim.pesc(s)
   vim.validate({ s = { s, 's' } })
   return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1')
@@ -528,9 +534,9 @@ end
 
 --- Tests if `s` starts with `prefix`.
 ---
----@param s (string) a string
----@param prefix (string) a prefix
----@return (boolean) true if `prefix` is a prefix of s
+---@param s string String
+---@param prefix string Prefix to match
+---@return boolean `true` if `prefix` is a prefix of `s`
 function vim.startswith(s, prefix)
   vim.validate({ s = { s, 's' }, prefix = { prefix, 's' } })
   return s:sub(1, #prefix) == prefix
@@ -538,9 +544,9 @@ end
 
 --- Tests if `s` ends with `suffix`.
 ---
----@param s (string) a string
----@param suffix (string) a suffix
----@return (boolean) true if `suffix` is a suffix of s
+---@param s string String
+---@param suffix string Suffix to match
+---@return boolean `true` if `suffix` is a suffix of `s`
 function vim.endswith(s, suffix)
   vim.validate({ s = { s, 's' }, suffix = { suffix, 's' } })
   return #suffix == 0 or s:sub(-#suffix) == suffix
@@ -582,7 +588,7 @@ end
 ---
 --- </pre>
 ---
----@param opt table of parameter names to validations. Each key is a parameter
+---@param opt table Names of parameters to validate. Each key is a parameter
 ---          name; each value is a tuple in one of these forms:
 ---          1. (arg_value, type_name, optional)
 ---             - arg_value: argument value
@@ -632,8 +638,8 @@ do
         return false, string.format('opt[%s]: expected table, got %s', param_name, type(spec))
       end
 
-      local val = spec[1] -- Argument value.
-      local types = spec[2] -- Type name, or callable.
+      local val = spec[1] -- Argument value
+      local types = spec[2] -- Type name, or callable
       local optional = (true == spec[3])
 
       if type(types) == 'string' then
@@ -641,7 +647,7 @@ do
       end
 
       if vim.is_callable(types) then
-        -- Check user-provided validation function.
+        -- Check user-provided validation function
         local valid, optional_message = types(val)
         if not valid then
           local error_message = string.format('%s: expected %s, got %s', param_name, (spec[3] or '?'), tostring(val))
@@ -685,8 +691,8 @@ do
 end
 --- Returns true if object `f` can be called as a function.
 ---
----@param f Any object
----@return true if `f` is callable, else false
+---@param f any Any object
+---@return boolean `true` if `f` is callable, else `false`
 function vim.is_callable(f)
   if type(f) == 'function' then
     return true
-- 
cgit 


From aa4f9c5341f5280f16cce0630ea54b84eef717b3 Mon Sep 17 00:00:00 2001
From: Christian Clason <c.clason@uni-graz.at>
Date: Thu, 7 Jul 2022 18:27:18 +0200
Subject: refactor(lua): reformat with stylua 0.14.0 (#19264)

* reformat Lua runtime to make lint CI pass
* reduce max line length to 100
---
 runtime/lua/vim/shared.lua | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

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

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 9bbe356f03..d6c3e25b3b 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -254,7 +254,11 @@ local function tbl_extend(behavior, deep_extend, ...)
   end
 
   if select('#', ...) < 2 then
-    error('wrong number of arguments (given ' .. tostring(1 + select('#', ...)) .. ', expected at least 3)')
+    error(
+      'wrong number of arguments (given '
+        .. tostring(1 + select('#', ...))
+        .. ', expected at least 3)'
+    )
   end
 
   local ret = {}
@@ -650,7 +654,8 @@ do
         -- Check user-provided validation function
         local valid, optional_message = types(val)
         if not valid then
-          local error_message = string.format('%s: expected %s, got %s', param_name, (spec[3] or '?'), tostring(val))
+          local error_message =
+            string.format('%s: expected %s, got %s', param_name, (spec[3] or '?'), tostring(val))
           if optional_message ~= nil then
             error_message = error_message .. string.format('. Info: %s', optional_message)
           end
@@ -672,7 +677,13 @@ do
           end
         end
         if not success then
-          return false, string.format('%s: expected %s, got %s', param_name, table.concat(types, '|'), type(val))
+          return false,
+            string.format(
+              '%s: expected %s, got %s',
+              param_name,
+              table.concat(types, '|'),
+              type(val)
+            )
         end
       else
         return false, string.format('invalid type name: %s', tostring(types))
-- 
cgit