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

1 files changed, 86 insertions, 59 deletions

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index bd553598c7..e9e4326057 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -356,7 +356,7 @@ end
 
 --- We only merge empty tables or tables that are not an array (indexed by integers)
 local function can_merge(v)
-  return type(v) == 'table' and (vim.tbl_isempty(v) or not vim.tbl_isarray(v))
+  return type(v) == 'table' and (vim.tbl_isempty(v) or not vim.isarray(v))
 end
 
 local function tbl_extend(behavior, deep_extend, ...)
@@ -402,7 +402,7 @@ end
 ---
 ---@see |extend()|
 ---
----@param behavior string Decides what to do if a key is found in more than one map:
+---@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
@@ -418,7 +418,7 @@ end
 ---
 ---@generic T1: table
 ---@generic T2: table
----@param behavior "error"|"keep"|"force" (string) Decides what to do if a key is found in more than one map:
+---@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
@@ -502,7 +502,7 @@ end
 ---
 ---@param o table Table to index
 ---@param ... any Optional keys (0 or more, variadic) via which to index the table
----@return any : 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
@@ -544,6 +544,7 @@ function vim.list_extend(dst, src, start, finish)
   return dst
 end
 
+--- @deprecated
 --- Creates a copy of a list-like table such that any nested tables are
 --- "unrolled" and appended to the result.
 ---
@@ -552,6 +553,7 @@ end
 ---@param t table List-like table
 ---@return table Flattened copy of the given list-like table
 function vim.tbl_flatten(t)
+  vim.deprecate('vim.tbl_flatten', 'vim.iter(…):flatten():totable()', '0.13')
   local result = {}
   --- @param _t table<any,any>
   local function _tbl_flatten(_t)
@@ -578,7 +580,7 @@ end
 ---@return fun(table: table<K, V>, index?: K):K, V # |for-in| iterator over sorted keys and their values
 ---@return T
 function vim.spairs(t)
-  vim.validate({ t = { t, 't' } })
+  assert(type(t) == 'table', ('expected table, got %s'):format(type(t)))
   --- @cast t table<any,any>
 
   -- collect the keys
@@ -601,16 +603,16 @@ end
 
 --- Tests if `t` is an "array": a table indexed _only_ by integers (potentially non-contiguous).
 ---
---- If the indexes start from 1 and are contiguous then the array is also a list. |vim.tbl_islist()|
+--- If the indexes start from 1 and are contiguous then the array is also a list. |vim.islist()|
 ---
 --- Empty table `{}` is an array, unless it was created by |vim.empty_dict()| or returned as
 --- a dict-like |API| or Vimscript result, for example from |rpcrequest()| or |vim.fn|.
 ---
 ---@see https://github.com/openresty/luajit2#tableisarray
 ---
----@param t table
+---@param t? table
 ---@return boolean `true` if array-like table, else `false`.
-function vim.tbl_isarray(t)
+function vim.isarray(t)
   if type(t) ~= 'table' then
     return false
   end
@@ -640,17 +642,23 @@ function vim.tbl_isarray(t)
   end
 end
 
+--- @deprecated
+function vim.tbl_islist(t)
+  vim.deprecate('vim.tbl_islist', 'vim.islist', '0.12')
+  return vim.islist(t)
+end
+
 --- Tests if `t` is a "list": a table indexed _only_ by contiguous integers starting from 1 (what
 --- |lua-length| calls a "regular array").
 ---
 --- Empty table `{}` is a list, unless it was created by |vim.empty_dict()| or returned as
 --- a dict-like |API| or Vimscript result, for example from |rpcrequest()| or |vim.fn|.
 ---
----@see |vim.tbl_isarray()|
+---@see |vim.isarray()|
 ---
----@param t table
+---@param t? table
 ---@return boolean `true` if list-like table, else `false`.
-function vim.tbl_islist(t)
+function vim.islist(t)
   if type(t) ~= 'table' then
     return false
   end
@@ -788,6 +796,61 @@ do
     return type(val) == t or (t == 'callable' and vim.is_callable(val))
   end
 
+  --- @param param_name string
+  --- @param spec vim.validate.Spec
+  --- @return string?
+  local function is_param_valid(param_name, spec)
+    if type(spec) ~= 'table' then
+      return 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 optional = (true == spec[3])
+
+    if type(types) == 'string' then
+      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))
+        if optional_message ~= nil then
+          error_message = string.format('%s. Info: %s', error_message, optional_message)
+        end
+
+        return error_message
+      end
+    elseif type(types) == 'table' then
+      local success = false
+      for i, t in ipairs(types) do
+        local t_name = type_names[t]
+        if not t_name then
+          return string.format('invalid type name: %s', t)
+        end
+        types[i] = t_name
+
+        if (optional and val == nil) or _is_type(val, t_name) then
+          success = true
+          break
+        end
+      end
+      if not success then
+        return string.format(
+          '%s: expected %s, got %s',
+          param_name,
+          table.concat(types, '|'),
+          type(val)
+        )
+      end
+    else
+      return string.format('invalid type name: %s', tostring(types))
+    end
+  end
+
   --- @param opt table<vim.validate.Type,vim.validate.Spec>
   --- @return boolean, string?
   local function is_valid(opt)
@@ -795,63 +858,27 @@ do
       return false, string.format('opt: expected table, got %s', type(opt))
     end
 
-    for param_name, spec in pairs(opt) do
-      if type(spec) ~= 'table' then
-        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 optional = (true == spec[3])
+    local report --- @type table<string,string>?
 
-      if type(types) == 'string' then
-        types = { types }
+    for param_name, spec in pairs(opt) do
+      local msg = is_param_valid(param_name, spec)
+      if msg then
+        report = report or {}
+        report[param_name] = msg
       end
+    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))
-          if optional_message ~= nil then
-            error_message = error_message .. string.format('. Info: %s', optional_message)
-          end
-
-          return false, error_message
-        end
-      elseif type(types) == 'table' then
-        local success = false
-        for i, t in ipairs(types) do
-          local t_name = type_names[t]
-          if not t_name then
-            return false, string.format('invalid type name: %s', t)
-          end
-          types[i] = t_name
-
-          if (optional and val == nil) or _is_type(val, t_name) then
-            success = true
-            break
-          end
-        end
-        if not success then
-          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))
+    if report then
+      for _, msg in vim.spairs(report) do -- luacheck: ignore
+        return false, msg
       end
     end
 
     return true
   end
 
-  --- Validates a parameter specification (types and values).
+  --- Validates a parameter specification (types and values). Specs are evaluated in alphanumeric
+  --- order, until the first failure.
   ---
   --- Usage example:
   ---