From 09a919f313ec8ae691798e45ee459a4467ce5d6a Mon Sep 17 00:00:00 2001 From: Riley Bruins Date: Sat, 30 Dec 2023 21:08:07 -0800 Subject: docs: more accurate typing for vim.tbl_extend --- 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 bd553598c7..a9eebf36da 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -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 -- cgit From fe4583127f0aaf631b05ad3dff7ebb0126314cf2 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 16 Apr 2024 07:31:43 -0700 Subject: fix: vim.validate() order is not deterministic #28377 Problem: The order of the validation performed by vim.validate() is unpredictable. - harder to write reliable tests. - confusing UX because validation result might return different errors randomly. Solution: Iterate the input using `vim.spairs()`. Future: Ideally, the caller could provide an "ordered dict". --- runtime/lua/vim/shared.lua | 7 ++++--- 1 file changed, 4 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 a9eebf36da..eb51c244ef 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -578,7 +578,7 @@ end ---@return fun(table: table, 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 -- collect the keys @@ -795,7 +795,7 @@ do return false, string.format('opt: expected table, got %s', type(opt)) end - for param_name, spec in pairs(opt) do + for param_name, spec in vim.spairs(opt) do if type(spec) ~= 'table' then return false, string.format('opt[%s]: expected table, got %s', param_name, type(spec)) end @@ -851,7 +851,8 @@ do 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: --- -- cgit From d9d890562e43493c999f8a6ff2b848959686f5b6 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 21 Apr 2024 15:19:43 +0200 Subject: refactor(lua): rename tbl_islist => islist ref #24572 --- runtime/lua/vim/shared.lua | 12 +++++++++--- 1 file changed, 9 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 eb51c244ef..6d9e4ad809 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -601,7 +601,7 @@ 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|. @@ -640,6 +640,12 @@ 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"). --- @@ -648,9 +654,9 @@ end --- ---@see |vim.tbl_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 -- cgit From 5c8dfb0e379cd4ae8de418e7aa554dbc5ab7f236 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 21 Apr 2024 17:29:10 +0200 Subject: refactor(lua): rename tbl_isarray => isarray tbl_isarray was not released yet, so it will not go through a deprecation cycle. ref #24572 --- runtime/lua/vim/shared.lua | 16 +++++++++++----- 1 file changed, 11 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 6d9e4ad809..85720b6ea3 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, ...) @@ -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 @@ -599,6 +599,12 @@ function vim.spairs(t) t end +--- @deprecated +function vim.tbl_isarray() + vim.deprecate('vim.tbl_isarray', 'vim.isarray', '0.10-dev') + error('vim.tbl_isarray was renamed to vim.isarray') +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.islist()| @@ -608,9 +614,9 @@ end --- ---@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 @@ -652,7 +658,7 @@ end --- 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 ---@return boolean `true` if list-like table, else `false`. -- cgit From 9912a4c81b0856200f44a38e99d38eae44cef5c9 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 22 Apr 2024 00:58:48 +0200 Subject: refactor(lua): deprecate tbl_flatten Problem: Besides being redundant with vim.iter():flatten(), `tbl_flatten` has these problems: - Has `tbl_` prefix but only accepts lists. - Discards some results! Compare the following: - iter.flatten(): ``` vim.iter({1, { { a = 2 } }, { 3 } }):flatten():totable() ``` - tbl_flatten: ``` vim.tbl_flatten({1, { { a = 2 } }, { 3 } }) ``` Solution: Deprecate tbl_flatten. Note: iter:flatten() currently fails ("flatten() requires a list-like table") on this code from gen_lsp.lua: local anonym = vim.iter({ -- remove nil anonymous_num > 1 and '' or nil, '---@class ' .. anonymous_classname, }):flatten():totable() Should we enhance :flatten() to work for arrays? --- runtime/lua/vim/shared.lua | 1 + 1 file changed, 1 insertion(+) (limited to 'runtime/lua/vim/shared.lua') diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index 85720b6ea3..5bbf8801e8 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -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. --- -- cgit From 013afc6863b0bed401e1d9e70cb861ee347b158f Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 22 Apr 2024 04:27:57 -0700 Subject: refactor(lua): deprecate tbl_flatten #28457 forgot some changes in 9912a4c81b0856200f44a38e99d38eae44cef5c9 --- runtime/lua/vim/shared.lua | 1 + 1 file changed, 1 insertion(+) (limited to 'runtime/lua/vim/shared.lua') diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index 5bbf8801e8..1c8059adab 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -553,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.12') local result = {} --- @param _t table local function _tbl_flatten(_t) -- cgit From e3ec974324bd73b63f54503480a4e48d1887f8d9 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 13 May 2024 05:00:39 -0700 Subject: refactor(lua): remove deprecated features #28725 --- runtime/lua/vim/shared.lua | 6 ------ 1 file changed, 6 deletions(-) (limited to 'runtime/lua/vim/shared.lua') diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index 1c8059adab..4d753d727a 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -601,12 +601,6 @@ function vim.spairs(t) t end ---- @deprecated -function vim.tbl_isarray() - vim.deprecate('vim.tbl_isarray', 'vim.isarray', '0.10-dev') - error('vim.tbl_isarray was renamed to vim.isarray') -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.islist()| -- cgit From cdd87222c86c5b2274a13d36f23de0637462e317 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Wed, 15 May 2024 13:13:47 +0100 Subject: perf(lua): avoid spairs in vim.validate happy path Problem: `vim.validate` is too slow, mainly because of `vim.spairs`. Solution: Collect all errors in via `pairs`, and sort the errors via `spairs`. --- runtime/lua/vim/shared.lua | 112 ++++++++++++++++++++++++++------------------- 1 file changed, 65 insertions(+), 47 deletions(-) (limited to 'runtime/lua/vim/shared.lua') diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index 4d753d727a..200ac44e86 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -796,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 --- @return boolean, string? local function is_valid(opt) @@ -803,56 +858,19 @@ do return false, string.format('opt: expected table, got %s', type(opt)) end - for param_name, spec in vim.spairs(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? - 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 -- cgit From 50749f8df89d7a74ea17d51b28e737e043ac6c51 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Thu, 16 May 2024 17:42:13 +0100 Subject: fix: extend the life of vim.tbl_flatten to 0.13 `vim.iter(t):flatten():totable()` doesn't handle nil so isn't a good enough replacement. --- 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 200ac44e86..e9e4326057 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -553,7 +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.12') + vim.deprecate('vim.tbl_flatten', 'vim.iter(…):flatten():totable()', '0.13') local result = {} --- @param _t table local function _tbl_flatten(_t) -- cgit