Merge remote-tracking branch 'upstream/master' into rahm

1 files changed, 198 insertions, 125 deletions

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index e170befa4c..d6c3e25b3b 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 src/nvim/lua/vim.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 {}
 
@@ -13,8 +15,8 @@ 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.
-function vim.deepcopy(orig) end  -- luacheck: no unused
+---@return table Table of copied keys and (nested) values.
+function vim.deepcopy(orig) end -- luacheck: no unused
 vim.deepcopy = (function()
   local function _id(v)
     return v
@@ -22,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
@@ -44,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)()
@@ -55,19 +59,19 @@ 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}}
+  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, ...
@@ -85,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
@@ -103,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
@@ -117,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
@@ -126,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
 
@@ -137,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)
@@ -152,10 +156,10 @@ 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)))
+  assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
 
   local keys = {}
   for k, _ in pairs(t) do
@@ -167,10 +171,10 @@ 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)))
+  assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
 
   local values = {}
   for _, v in pairs(t) do
@@ -181,10 +185,11 @@ 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'}}
+  vim.validate({ func = { func, 'c' }, t = { t, 't' } })
 
   local rettab = {}
   for k, v in pairs(t) do
@@ -195,10 +200,11 @@ 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'}}
+  vim.validate({ func = { func, 'c' }, t = { t, 't' } })
 
   local rettab = {}
   for _, entry in pairs(t) do
@@ -211,13 +217,13 @@ 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'}}
+  vim.validate({ t = { t, 't' } })
 
-  for _,v in ipairs(t) do
+  for _, v in ipairs(t) do
     if v == value then
       return true
     end
@@ -229,25 +235,30 @@ 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)))
+  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))
+  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 = {}
@@ -257,15 +268,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
@@ -279,11 +290,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
@@ -292,25 +304,30 @@ 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 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
@@ -329,40 +346,77 @@ 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.
+--- ``tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }``
+---
+--- 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
     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
   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 Table to index
+---@param ... string Optional strings (0 or more, variadic) via which to index the table
+---
+---@return any Nested value indexed by key (if it exists), else nil
+function vim.tbl_get(o, ...)
+  local keys = { ... }
+  if #keys == 0 then
+    return
+  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
+    end
+  end
+  return o
+end
+
 --- Extends a list-like table with the values of another list-like table.
 ---
 --- NOTE: This mutates dst!
 ---
 ---@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'};
-    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
@@ -374,15 +428,15 @@ 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)
     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)
@@ -399,8 +453,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
@@ -409,7 +463,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
@@ -436,26 +490,28 @@ 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'}}
+  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
 
 --- 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
-    new_list[#new_list+1] = list[i]
+    new_list[#new_list + 1] = list[i]
   end
   return new_list
 end
@@ -463,40 +519,40 @@ 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'}}
+  vim.validate({ s = { s, 's' } })
   return s:match('^%s*(.*%S)') or ''
 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'}}
+  vim.validate({ s = { s, 's' } })
   return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1')
 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'}; }
+  vim.validate({ s = { s, 's' }, prefix = { prefix, 's' } })
   return s:sub(1, #prefix) == prefix
 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'}; }
+  vim.validate({ s = { s, 's' }, suffix = { suffix, 's' } })
   return #suffix == 0 or s:sub(-#suffix) == suffix
 end
 
@@ -536,7 +592,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
@@ -550,18 +606,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',
   }
 
@@ -580,21 +642,22 @@ 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.
+        -- 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
@@ -614,10 +677,16 @@ 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
 
@@ -633,12 +702,16 @@ 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 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