2019-05-19 08:58:54 -07:00
|
|
|
-- Functions shared by Nvim and its test-suite.
|
|
|
|
--
|
2022-03-06 05:13:10 -07:00
|
|
|
-- 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)
|
2019-01-17 16:44:35 -07:00
|
|
|
|
2024-02-15 10:16:04 -07:00
|
|
|
---@nodoc
|
2023-08-09 02:06:13 -07:00
|
|
|
---@diagnostic disable-next-line: lowercase-global
|
2022-10-09 03:40:56 -07:00
|
|
|
vim = vim or {}
|
2019-01-17 16:44:35 -07:00
|
|
|
|
2024-01-02 08:47:55 -07:00
|
|
|
---@generic T
|
|
|
|
---@param orig T
|
|
|
|
---@param cache? table<any,any>
|
|
|
|
---@return T
|
|
|
|
local function deepcopy(orig, cache)
|
|
|
|
if orig == vim.NIL then
|
|
|
|
return vim.NIL
|
|
|
|
elseif type(orig) == 'userdata' or type(orig) == 'thread' then
|
|
|
|
error('Cannot deepcopy object of type ' .. type(orig))
|
|
|
|
elseif type(orig) ~= 'table' then
|
|
|
|
return orig
|
|
|
|
end
|
2023-07-18 07:42:30 -07:00
|
|
|
|
2024-01-02 08:47:55 -07:00
|
|
|
--- @cast orig table<any,any>
|
|
|
|
|
|
|
|
if cache and cache[orig] then
|
|
|
|
return cache[orig]
|
|
|
|
end
|
2023-07-18 07:42:30 -07:00
|
|
|
|
2024-01-02 08:47:55 -07:00
|
|
|
local copy = {} --- @type table<any,any>
|
2023-07-18 07:42:30 -07:00
|
|
|
|
2024-01-02 08:47:55 -07:00
|
|
|
if cache then
|
2023-07-18 07:42:30 -07:00
|
|
|
cache[orig] = copy
|
2024-01-02 08:47:55 -07:00
|
|
|
end
|
2023-07-18 07:42:30 -07:00
|
|
|
|
2024-01-02 08:47:55 -07:00
|
|
|
for k, v in pairs(orig) do
|
|
|
|
copy[deepcopy(k, cache)] = deepcopy(v, cache)
|
2023-07-18 07:42:30 -07:00
|
|
|
end
|
2024-01-02 08:47:55 -07:00
|
|
|
|
|
|
|
return setmetatable(copy, getmetatable(orig))
|
2023-07-18 07:42:30 -07:00
|
|
|
end
|
|
|
|
|
2019-05-19 08:58:54 -07:00
|
|
|
--- 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.
|
2020-04-18 16:04:37 -07:00
|
|
|
--- Functions are naively copied, so functions in the copied table point to the
|
|
|
|
--- same functions as those in the input table. Userdata and threads are not
|
|
|
|
--- copied and will throw an error.
|
2019-05-19 08:58:54 -07:00
|
|
|
---
|
2024-01-02 08:47:55 -07:00
|
|
|
--- Note: `noref=true` is much more performant on tables with unique table
|
|
|
|
--- fields, while `noref=false` is more performant on tables that reuse table
|
|
|
|
--- fields.
|
|
|
|
---
|
2022-09-27 13:44:01 -07:00
|
|
|
---@generic T: table
|
|
|
|
---@param orig T Table to copy
|
2024-01-02 08:47:55 -07:00
|
|
|
---@param noref? boolean
|
|
|
|
--- When `false` (default) a contained table is only copied once and all
|
|
|
|
--- references point to this single copy. When `true` every occurrence of a
|
|
|
|
--- table results in a new copy. This also means that a cyclic reference can
|
|
|
|
--- cause `deepcopy()` to fail.
|
2022-09-27 13:44:01 -07:00
|
|
|
---@return T Table of copied keys and (nested) values.
|
2024-01-02 08:47:55 -07:00
|
|
|
function vim.deepcopy(orig, noref)
|
|
|
|
return deepcopy(orig, not noref and {} or nil)
|
2023-07-18 07:42:30 -07:00
|
|
|
end
|
2019-05-19 08:58:54 -07:00
|
|
|
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @class vim.gsplit.Opts
|
2024-02-27 08:20:32 -07:00
|
|
|
--- @inlinedoc
|
|
|
|
---
|
|
|
|
--- Use `sep` literally (as in string.find).
|
|
|
|
--- @field plain? boolean
|
|
|
|
---
|
|
|
|
--- Discard empty segments at start and end of the sequence.
|
|
|
|
--- @field trimempty? boolean
|
2024-02-15 03:53:51 -07:00
|
|
|
|
2023-07-12 10:27:14 -07:00
|
|
|
--- Gets an |iterator| that splits a string at each instance of a separator, in "lazy" fashion
|
|
|
|
--- (as opposed to |vim.split()| which is "eager").
|
2019-05-19 09:31:40 -07:00
|
|
|
---
|
2023-03-20 00:12:33 -07:00
|
|
|
--- Example:
|
2023-09-14 06:23:01 -07:00
|
|
|
---
|
|
|
|
--- ```lua
|
|
|
|
--- for s in vim.gsplit(':aa::b:', ':', {plain=true}) do
|
|
|
|
--- print(s)
|
|
|
|
--- end
|
|
|
|
--- ```
|
2023-03-20 00:12:33 -07:00
|
|
|
---
|
2023-03-22 07:14:51 -07:00
|
|
|
--- If you want to also inspect the separator itself (instead of discarding it), use
|
|
|
|
--- |string.gmatch()|. Example:
|
2023-09-14 06:23:01 -07:00
|
|
|
---
|
|
|
|
--- ```lua
|
|
|
|
--- for word, num in ('foo111bar222'):gmatch('([^0-9]*)(%d*)') do
|
|
|
|
--- print(('word: %s num: %s'):format(word, num))
|
|
|
|
--- end
|
|
|
|
--- ```
|
2023-03-22 07:14:51 -07:00
|
|
|
---
|
2023-03-20 05:36:06 -07:00
|
|
|
--- @see |string.gmatch()|
|
|
|
|
--- @see |vim.split()|
|
2023-08-03 08:35:10 -07:00
|
|
|
--- @see |lua-patterns|
|
2023-03-20 05:36:06 -07:00
|
|
|
--- @see https://www.lua.org/pil/20.2.html
|
|
|
|
--- @see http://lua-users.org/wiki/StringLibraryTutorial
|
2019-05-19 09:31:40 -07:00
|
|
|
---
|
2023-03-20 05:36:06 -07:00
|
|
|
--- @param s string String to split
|
|
|
|
--- @param sep string Separator or pattern
|
2024-02-27 08:20:32 -07:00
|
|
|
--- @param opts? vim.gsplit.Opts Keyword arguments |kwargs|:
|
2024-03-05 05:06:15 -07:00
|
|
|
--- @return fun():string? : Iterator over the split components
|
2023-03-20 00:12:33 -07:00
|
|
|
function vim.gsplit(s, sep, opts)
|
2024-02-15 03:53:51 -07:00
|
|
|
local plain --- @type boolean?
|
2023-03-20 00:12:33 -07:00
|
|
|
local trimempty = false
|
|
|
|
if type(opts) == 'boolean' then
|
|
|
|
plain = opts -- For backwards compatibility.
|
|
|
|
else
|
|
|
|
vim.validate({ s = { s, 's' }, sep = { sep, 's' }, opts = { opts, 't', true } })
|
|
|
|
opts = opts or {}
|
2023-03-22 07:14:51 -07:00
|
|
|
plain, trimempty = opts.plain, opts.trimempty
|
2023-03-20 00:12:33 -07:00
|
|
|
end
|
2019-05-19 09:31:40 -07:00
|
|
|
|
|
|
|
local start = 1
|
|
|
|
local done = false
|
2023-03-20 00:12:33 -07:00
|
|
|
|
2023-04-20 22:26:44 -07:00
|
|
|
-- For `trimempty`: queue of collected segments, to be emitted at next pass.
|
|
|
|
local segs = {}
|
2023-03-20 00:12:33 -07:00
|
|
|
local empty_start = true -- Only empty segments seen so far.
|
2019-05-19 09:31:40 -07:00
|
|
|
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @param i integer?
|
|
|
|
--- @param j integer
|
|
|
|
--- @param ... unknown
|
|
|
|
--- @return string
|
|
|
|
--- @return ...
|
2019-05-19 09:31:40 -07:00
|
|
|
local function _pass(i, j, ...)
|
|
|
|
if i then
|
|
|
|
assert(j + 1 > start, 'Infinite loop detected')
|
|
|
|
local seg = s:sub(start, i - 1)
|
|
|
|
start = j + 1
|
|
|
|
return seg, ...
|
|
|
|
else
|
|
|
|
done = true
|
|
|
|
return s:sub(start)
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
return function()
|
2023-04-20 22:26:44 -07:00
|
|
|
if trimempty and #segs > 0 then
|
|
|
|
-- trimempty: Pop the collected segments.
|
|
|
|
return table.remove(segs)
|
2023-03-20 00:12:33 -07:00
|
|
|
elseif done or (s == '' and sep == '') then
|
|
|
|
return nil
|
|
|
|
elseif sep == '' then
|
2019-05-19 09:31:40 -07:00
|
|
|
if start == #s then
|
|
|
|
done = true
|
|
|
|
end
|
|
|
|
return _pass(start + 1, start)
|
|
|
|
end
|
2023-03-20 00:12:33 -07:00
|
|
|
|
|
|
|
local seg = _pass(s:find(sep, start, plain))
|
|
|
|
|
|
|
|
-- Trim empty segments from start/end.
|
2023-04-20 22:26:44 -07:00
|
|
|
if trimempty and seg ~= '' then
|
2023-04-20 21:46:18 -07:00
|
|
|
empty_start = false
|
2023-04-20 22:26:44 -07:00
|
|
|
elseif trimempty and seg == '' then
|
2023-03-20 00:12:33 -07:00
|
|
|
while not done and seg == '' do
|
2023-04-20 22:26:44 -07:00
|
|
|
table.insert(segs, 1, '')
|
2023-03-20 00:12:33 -07:00
|
|
|
seg = _pass(s:find(sep, start, plain))
|
|
|
|
end
|
|
|
|
if done and seg == '' then
|
|
|
|
return nil
|
|
|
|
elseif empty_start then
|
|
|
|
empty_start = false
|
2023-04-20 22:26:44 -07:00
|
|
|
segs = {}
|
2023-03-20 00:12:33 -07:00
|
|
|
return seg
|
|
|
|
end
|
2023-04-20 22:26:44 -07:00
|
|
|
if seg ~= '' then
|
|
|
|
table.insert(segs, 1, seg)
|
|
|
|
end
|
|
|
|
return table.remove(segs)
|
2023-03-20 00:12:33 -07:00
|
|
|
end
|
|
|
|
|
|
|
|
return seg
|
2019-05-19 09:31:40 -07:00
|
|
|
end
|
|
|
|
end
|
|
|
|
|
2023-07-12 10:27:14 -07:00
|
|
|
--- Splits a string at each instance of a separator and returns the result as a table (unlike
|
|
|
|
--- |vim.gsplit()|).
|
2019-05-19 09:31:40 -07:00
|
|
|
---
|
|
|
|
--- Examples:
|
2023-09-14 06:23:01 -07:00
|
|
|
---
|
|
|
|
--- ```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'}
|
|
|
|
--- ```
|
feat: add trimempty optional parameter to vim.split
The `split()` VimL function trims empty items from the returned list by
default, so that, e.g.
split("\nhello\nworld\n\n", "\n")
returns
["hello", "world"]
The Lua implementation of vim.split does not do this. For example,
vim.split("\nhello\nworld\n\n", "\n")
returns
{'', 'hello', 'world', '', ''}
Add an optional parameter to the vim.split function that, when true,
trims these empty elements from the front and back of the returned
table. This is only possible for vim.split and not vim.gsplit; because
vim.gsplit is an iterator, there is no way for it to know if the current
item is the last non-empty item.
Note that in order to preserve backward compatibility, the parameter for
the Lua vim.split function is `trimempty`, while the VimL function uses
`keepempty` (i.e. they are opposites). This means there is a disconnect
between these two functions that may surprise users.
2021-07-29 13:48:04 -07:00
|
|
|
---
|
2021-08-22 13:55:28 -07:00
|
|
|
---@see |vim.gsplit()|
|
2023-03-22 07:14:51 -07:00
|
|
|
---@see |string.gmatch()|
|
2019-05-19 09:31:40 -07:00
|
|
|
---
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param s string String to split
|
|
|
|
---@param sep string Separator or pattern
|
2024-02-27 08:20:32 -07:00
|
|
|
---@param opts? vim.gsplit.Opts Keyword arguments |kwargs|:
|
2024-02-15 10:16:04 -07:00
|
|
|
---@return string[] : List of split components
|
2023-03-20 00:12:33 -07:00
|
|
|
function vim.split(s, sep, opts)
|
feat: add trimempty optional parameter to vim.split
The `split()` VimL function trims empty items from the returned list by
default, so that, e.g.
split("\nhello\nworld\n\n", "\n")
returns
["hello", "world"]
The Lua implementation of vim.split does not do this. For example,
vim.split("\nhello\nworld\n\n", "\n")
returns
{'', 'hello', 'world', '', ''}
Add an optional parameter to the vim.split function that, when true,
trims these empty elements from the front and back of the returned
table. This is only possible for vim.split and not vim.gsplit; because
vim.gsplit is an iterator, there is no way for it to know if the current
item is the last non-empty item.
Note that in order to preserve backward compatibility, the parameter for
the Lua vim.split function is `trimempty`, while the VimL function uses
`keepempty` (i.e. they are opposites). This means there is a disconnect
between these two functions that may surprise users.
2021-07-29 13:48:04 -07:00
|
|
|
local t = {}
|
2023-03-20 00:12:33 -07:00
|
|
|
for c in vim.gsplit(s, sep, opts) do
|
|
|
|
table.insert(t, c)
|
feat: add trimempty optional parameter to vim.split
The `split()` VimL function trims empty items from the returned list by
default, so that, e.g.
split("\nhello\nworld\n\n", "\n")
returns
["hello", "world"]
The Lua implementation of vim.split does not do this. For example,
vim.split("\nhello\nworld\n\n", "\n")
returns
{'', 'hello', 'world', '', ''}
Add an optional parameter to the vim.split function that, when true,
trims these empty elements from the front and back of the returned
table. This is only possible for vim.split and not vim.gsplit; because
vim.gsplit is an iterator, there is no way for it to know if the current
item is the last non-empty item.
Note that in order to preserve backward compatibility, the parameter for
the Lua vim.split function is `trimempty`, while the VimL function uses
`keepempty` (i.e. they are opposites). This means there is a disconnect
between these two functions that may surprise users.
2021-07-29 13:48:04 -07:00
|
|
|
end
|
2019-05-19 09:31:40 -07:00
|
|
|
return t
|
|
|
|
end
|
|
|
|
|
2019-11-13 13:55:26 -07:00
|
|
|
--- Return a list of all keys used in a table.
|
|
|
|
--- However, the order of the return table of keys is not guaranteed.
|
|
|
|
---
|
2021-08-22 13:55:28 -07:00
|
|
|
---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
|
2019-11-13 13:55:26 -07:00
|
|
|
---
|
2024-02-15 10:16:04 -07:00
|
|
|
---@generic T
|
2022-10-24 05:53:53 -07:00
|
|
|
---@param t table<T, any> (table) Table
|
2024-02-15 10:16:04 -07:00
|
|
|
---@return T[] : List of keys
|
2019-11-13 13:55:26 -07:00
|
|
|
function vim.tbl_keys(t)
|
2024-05-27 06:08:23 -07:00
|
|
|
vim.validate('t', t, 'table')
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @cast t table<any,any>
|
2019-11-13 13:55:26 -07:00
|
|
|
|
|
|
|
local keys = {}
|
2024-02-15 03:53:51 -07:00
|
|
|
for k in pairs(t) do
|
2019-11-13 13:55:26 -07:00
|
|
|
table.insert(keys, k)
|
|
|
|
end
|
|
|
|
return keys
|
|
|
|
end
|
|
|
|
|
|
|
|
--- Return a list of all values used in a table.
|
|
|
|
--- However, the order of the return table of values is not guaranteed.
|
|
|
|
---
|
2022-09-27 13:44:01 -07:00
|
|
|
---@generic T
|
2022-09-28 04:22:08 -07:00
|
|
|
---@param t table<any, T> (table) Table
|
2024-02-15 10:16:04 -07:00
|
|
|
---@return T[] : List of values
|
2019-11-13 13:55:26 -07:00
|
|
|
function vim.tbl_values(t)
|
2024-05-27 06:08:23 -07:00
|
|
|
vim.validate('t', t, 'table')
|
2019-11-13 13:55:26 -07:00
|
|
|
|
|
|
|
local values = {}
|
2024-02-15 03:53:51 -07:00
|
|
|
for _, v in
|
|
|
|
pairs(t --[[@as table<any,any>]])
|
|
|
|
do
|
2019-11-13 13:55:26 -07:00
|
|
|
table.insert(values, v)
|
|
|
|
end
|
|
|
|
return values
|
|
|
|
end
|
|
|
|
|
2020-02-18 01:41:29 -07:00
|
|
|
--- Apply a function to all values of a table.
|
|
|
|
---
|
2022-09-27 13:44:01 -07:00
|
|
|
---@generic T
|
2024-03-05 05:06:15 -07:00
|
|
|
---@param func fun(value: T): any Function
|
|
|
|
---@param t table<any, T> Table
|
2024-02-15 10:16:04 -07:00
|
|
|
---@return table : Table of transformed values
|
2020-02-18 01:41:29 -07:00
|
|
|
function vim.tbl_map(func, t)
|
|
|
|
vim.validate({ func = { func, 'c' }, t = { t, 't' } })
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @cast t table<any,any>
|
2020-02-18 01:41:29 -07:00
|
|
|
|
2024-02-15 03:53:51 -07:00
|
|
|
local rettab = {} --- @type table<any,any>
|
2020-02-18 01:41:29 -07:00
|
|
|
for k, v in pairs(t) do
|
|
|
|
rettab[k] = func(v)
|
|
|
|
end
|
|
|
|
return rettab
|
|
|
|
end
|
|
|
|
|
|
|
|
--- Filter a table using a predicate function
|
|
|
|
---
|
2022-09-27 13:44:01 -07:00
|
|
|
---@generic T
|
2022-09-28 04:22:08 -07:00
|
|
|
---@param func fun(value: T): boolean (function) Function
|
|
|
|
---@param t table<any, T> (table) Table
|
2024-02-15 10:16:04 -07:00
|
|
|
---@return T[] : Table of filtered values
|
2020-02-18 01:41:29 -07:00
|
|
|
function vim.tbl_filter(func, t)
|
|
|
|
vim.validate({ func = { func, 'c' }, t = { t, 't' } })
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @cast t table<any,any>
|
2020-02-18 01:41:29 -07:00
|
|
|
|
2024-02-15 03:53:51 -07:00
|
|
|
local rettab = {} --- @type table<any,any>
|
2020-02-18 01:41:29 -07:00
|
|
|
for _, entry in pairs(t) do
|
|
|
|
if func(entry) then
|
2024-02-15 03:53:51 -07:00
|
|
|
rettab[#rettab + 1] = entry
|
2020-02-18 01:41:29 -07:00
|
|
|
end
|
|
|
|
end
|
|
|
|
return rettab
|
|
|
|
end
|
|
|
|
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @class vim.tbl_contains.Opts
|
2024-02-27 08:20:32 -07:00
|
|
|
--- @inlinedoc
|
|
|
|
---
|
|
|
|
--- `value` is a function reference to be checked (default false)
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @field predicate? boolean
|
|
|
|
|
2023-04-14 01:39:57 -07:00
|
|
|
--- Checks if a table contains a given value, specified either directly or via
|
|
|
|
--- a predicate that is checked for each value.
|
|
|
|
---
|
|
|
|
--- Example:
|
2023-09-14 06:23:01 -07:00
|
|
|
---
|
|
|
|
--- ```lua
|
|
|
|
--- vim.tbl_contains({ 'a', { 'b', 'c' } }, function(v)
|
|
|
|
--- return vim.deep_equal(v, { 'b', 'c' })
|
|
|
|
--- end, { predicate = true })
|
|
|
|
--- -- true
|
|
|
|
--- ```
|
2023-04-14 01:39:57 -07:00
|
|
|
---
|
|
|
|
---@see |vim.list_contains()| for checking values in list-like tables
|
2019-05-19 08:58:54 -07:00
|
|
|
---
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param t table Table to check
|
2023-04-14 01:39:57 -07:00
|
|
|
---@param value any Value to compare or predicate function reference
|
2024-02-27 08:20:32 -07:00
|
|
|
---@param opts? vim.tbl_contains.Opts Keyword arguments |kwargs|:
|
2023-04-14 01:39:57 -07:00
|
|
|
---@return boolean `true` if `t` contains `value`
|
|
|
|
function vim.tbl_contains(t, value, opts)
|
|
|
|
vim.validate({ t = { t, 't' }, opts = { opts, 't', true } })
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @cast t table<any,any>
|
2023-04-14 01:39:57 -07:00
|
|
|
|
2024-02-15 03:53:51 -07:00
|
|
|
local pred --- @type fun(v: any): boolean?
|
2023-04-14 01:39:57 -07:00
|
|
|
if opts and opts.predicate then
|
|
|
|
vim.validate({ value = { value, 'c' } })
|
|
|
|
pred = value
|
|
|
|
else
|
|
|
|
pred = function(v)
|
|
|
|
return v == value
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
for _, v in pairs(t) do
|
|
|
|
if pred(v) then
|
|
|
|
return true
|
|
|
|
end
|
|
|
|
end
|
|
|
|
return false
|
|
|
|
end
|
|
|
|
|
|
|
|
--- Checks if a list-like table (integer keys without gaps) contains `value`.
|
|
|
|
---
|
|
|
|
---@see |vim.tbl_contains()| for checking values in general tables
|
|
|
|
---
|
|
|
|
---@param t table Table to check (must be list-like, not validated)
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param value any Value to compare
|
|
|
|
---@return boolean `true` if `t` contains `value`
|
2023-04-14 01:39:57 -07:00
|
|
|
function vim.list_contains(t, value)
|
2024-05-27 06:08:23 -07:00
|
|
|
vim.validate('t', t, 'table')
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @cast t table<any,any>
|
2019-10-21 07:46:28 -07:00
|
|
|
|
2019-05-18 07:00:06 -07:00
|
|
|
for _, v in ipairs(t) do
|
|
|
|
if v == value then
|
|
|
|
return true
|
|
|
|
end
|
|
|
|
end
|
|
|
|
return false
|
|
|
|
end
|
|
|
|
|
2020-08-31 00:51:35 -07:00
|
|
|
--- Checks if a table is empty.
|
|
|
|
---
|
2021-08-22 13:55:28 -07:00
|
|
|
---@see https://github.com/premake/premake-core/blob/master/src/base/table.lua
|
2020-08-31 00:51:35 -07:00
|
|
|
---
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param t table Table to check
|
|
|
|
---@return boolean `true` if `t` is empty
|
2019-11-13 13:55:26 -07:00
|
|
|
function vim.tbl_isempty(t)
|
2024-05-27 06:08:23 -07:00
|
|
|
vim.validate('t', t, 'table')
|
2019-11-13 13:55:26 -07:00
|
|
|
return next(t) == nil
|
|
|
|
end
|
|
|
|
|
2024-09-03 09:14:25 -07:00
|
|
|
--- Recursive worker for tbl_extend
|
|
|
|
--- @param behavior 'error'|'keep'|'force'
|
|
|
|
--- @param deep_extend boolean
|
|
|
|
--- @param ... table<any,any>
|
|
|
|
local function tbl_extend_rec(behavior, deep_extend, ...)
|
2024-02-15 03:53:51 -07:00
|
|
|
local ret = {} --- @type table<any,any>
|
2020-02-12 23:02:30 -07:00
|
|
|
if vim._empty_dict_mt ~= nil and getmetatable(select(1, ...)) == vim._empty_dict_mt then
|
|
|
|
ret = vim.empty_dict()
|
|
|
|
end
|
|
|
|
|
2019-01-17 16:44:35 -07:00
|
|
|
for i = 1, select('#', ...) do
|
2024-09-03 09:14:25 -07:00
|
|
|
local tbl = select(i, ...) --[[@as table<any,any>]]
|
2019-01-17 16:44:35 -07:00
|
|
|
if tbl then
|
|
|
|
for k, v in pairs(tbl) do
|
2024-09-03 09:14:25 -07:00
|
|
|
if deep_extend and type(v) == 'table' and type(ret[k]) == 'table' then
|
|
|
|
ret[k] = tbl_extend_rec(behavior, true, ret[k], v)
|
2020-05-17 10:24:34 -07:00
|
|
|
elseif behavior ~= 'force' and ret[k] ~= nil then
|
2019-01-17 16:44:35 -07:00
|
|
|
if behavior == 'error' then
|
|
|
|
error('key found in more than one map: ' .. k)
|
|
|
|
end -- Else behavior is "keep".
|
|
|
|
else
|
|
|
|
ret[k] = v
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
2024-09-03 09:14:25 -07:00
|
|
|
|
2019-01-17 16:44:35 -07:00
|
|
|
return ret
|
|
|
|
end
|
|
|
|
|
2024-09-03 09:14:25 -07:00
|
|
|
--- @param behavior 'error'|'keep'|'force'
|
|
|
|
--- @param deep_extend boolean
|
|
|
|
--- @param ... table<any,any>
|
|
|
|
local function tbl_extend(behavior, deep_extend, ...)
|
|
|
|
if behavior ~= 'error' and behavior ~= 'keep' and behavior ~= 'force' then
|
|
|
|
error('invalid "behavior": ' .. tostring(behavior))
|
|
|
|
end
|
|
|
|
|
|
|
|
local nargs = select('#', ...)
|
|
|
|
|
|
|
|
if nargs < 2 then
|
|
|
|
error(('wrong number of arguments (given %d, expected at least 3)'):format(1 + nargs))
|
|
|
|
end
|
|
|
|
|
|
|
|
for i = 1, nargs do
|
|
|
|
vim.validate('after the second argument', select(i, ...), 'table')
|
|
|
|
end
|
|
|
|
|
|
|
|
return tbl_extend_rec(behavior, deep_extend, ...)
|
|
|
|
end
|
|
|
|
|
2023-05-13 12:33:22 -07:00
|
|
|
--- Merges two or more tables.
|
2020-05-17 10:24:34 -07:00
|
|
|
---
|
2021-08-22 13:55:28 -07:00
|
|
|
---@see |extend()|
|
2020-05-17 10:24:34 -07:00
|
|
|
---
|
2023-12-30 22:08:07 -07:00
|
|
|
---@param behavior 'error'|'keep'|'force' Decides what to do if a key is found in more than one map:
|
2020-05-17 10:24:34 -07:00
|
|
|
--- - "error": raise an error
|
|
|
|
--- - "keep": use value from the leftmost map
|
|
|
|
--- - "force": use value from the rightmost map
|
2023-05-13 12:33:22 -07:00
|
|
|
---@param ... table Two or more tables
|
2024-02-15 10:16:04 -07:00
|
|
|
---@return table : Merged table
|
2020-05-17 10:24:34 -07:00
|
|
|
function vim.tbl_extend(behavior, ...)
|
|
|
|
return tbl_extend(behavior, false, ...)
|
|
|
|
end
|
|
|
|
|
2023-05-13 12:33:22 -07:00
|
|
|
--- Merges recursively two or more tables.
|
2020-05-17 10:24:34 -07:00
|
|
|
---
|
2022-09-25 16:58:27 -07:00
|
|
|
---@see |vim.tbl_extend()|
|
2020-05-17 10:24:34 -07:00
|
|
|
---
|
2022-09-27 13:44:01 -07:00
|
|
|
---@generic T1: table
|
|
|
|
---@generic T2: table
|
2023-12-30 22:08:07 -07:00
|
|
|
---@param behavior 'error'|'keep'|'force' Decides what to do if a key is found in more than one map:
|
2020-05-17 10:24:34 -07:00
|
|
|
--- - "error": raise an error
|
|
|
|
--- - "keep": use value from the leftmost map
|
|
|
|
--- - "force": use value from the rightmost map
|
2023-05-13 12:33:22 -07:00
|
|
|
---@param ... T2 Two or more tables
|
2022-09-28 04:22:08 -07:00
|
|
|
---@return T1|T2 (table) Merged table
|
2020-05-17 10:24:34 -07:00
|
|
|
function vim.tbl_deep_extend(behavior, ...)
|
|
|
|
return tbl_extend(behavior, true, ...)
|
|
|
|
end
|
|
|
|
|
2019-11-13 13:55:26 -07:00
|
|
|
--- Deep compare values for equality
|
2021-09-10 06:22:40 -07:00
|
|
|
---
|
2022-05-11 09:23:46 -07:00
|
|
|
--- Tables are compared recursively unless they both provide the `eq` metamethod.
|
2021-09-10 06:22:40 -07:00
|
|
|
--- All other types are compared using the equality `==` operator.
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param a any First value
|
|
|
|
---@param b any Second value
|
|
|
|
---@return boolean `true` if values are equals, else `false`
|
2019-11-13 13:55:26 -07:00
|
|
|
function vim.deep_equal(a, b)
|
|
|
|
if a == b then
|
|
|
|
return true
|
|
|
|
end
|
|
|
|
if type(a) ~= type(b) then
|
|
|
|
return false
|
|
|
|
end
|
|
|
|
if type(a) == 'table' then
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @cast a table<any,any>
|
|
|
|
--- @cast b table<any,any>
|
2019-11-13 13:55:26 -07:00
|
|
|
for k, v in pairs(a) do
|
|
|
|
if not vim.deep_equal(v, b[k]) then
|
|
|
|
return false
|
|
|
|
end
|
|
|
|
end
|
2024-02-15 03:53:51 -07:00
|
|
|
for k in pairs(b) do
|
2021-09-10 06:22:40 -07:00
|
|
|
if a[k] == nil then
|
2019-11-13 13:55:26 -07:00
|
|
|
return false
|
|
|
|
end
|
|
|
|
end
|
|
|
|
return true
|
|
|
|
end
|
|
|
|
return false
|
|
|
|
end
|
|
|
|
|
|
|
|
--- Add the reverse lookup values to an existing table.
|
|
|
|
--- For example:
|
2024-02-15 10:16:04 -07:00
|
|
|
--- `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }`
|
2022-05-11 09:23:46 -07:00
|
|
|
---
|
|
|
|
--- Note that this *modifies* the input.
|
2024-03-02 14:11:23 -07:00
|
|
|
---@deprecated
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param o table Table to add the reverse to
|
|
|
|
---@return table o
|
2019-11-13 13:55:26 -07:00
|
|
|
function vim.tbl_add_reverse_lookup(o)
|
2024-03-02 14:11:23 -07:00
|
|
|
vim.deprecate('vim.tbl_add_reverse_lookup', nil, '0.12')
|
|
|
|
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @cast o table<any,any>
|
|
|
|
--- @type any[]
|
2019-11-13 13:55:26 -07:00
|
|
|
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)
|
2022-05-09 02:23:51 -07:00
|
|
|
)
|
|
|
|
)
|
2019-11-13 13:55:26 -07:00
|
|
|
end
|
|
|
|
o[v] = k
|
|
|
|
end
|
|
|
|
return o
|
|
|
|
end
|
|
|
|
|
2022-03-24 12:01:04 -07:00
|
|
|
--- Index into a table (first argument) via string keys passed as subsequent arguments.
|
|
|
|
--- Return `nil` if the key does not exist.
|
2022-05-11 09:23:46 -07:00
|
|
|
---
|
2022-03-24 12:01:04 -07:00
|
|
|
--- Examples:
|
2023-09-14 06:23:01 -07:00
|
|
|
---
|
|
|
|
--- ```lua
|
|
|
|
--- vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
|
|
|
|
--- vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
|
|
|
|
--- ```
|
2022-03-24 12:01:04 -07:00
|
|
|
---
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param o table Table to index
|
2023-06-11 15:48:13 -07:00
|
|
|
---@param ... any Optional keys (0 or more, variadic) via which to index the table
|
2024-04-21 08:29:10 -07:00
|
|
|
---@return any # Nested value indexed by key (if it exists), else nil
|
2022-03-24 12:01:04 -07:00
|
|
|
function vim.tbl_get(o, ...)
|
|
|
|
local keys = { ... }
|
|
|
|
if #keys == 0 then
|
2022-12-14 18:27:23 -07:00
|
|
|
return nil
|
2022-03-24 12:01:04 -07:00
|
|
|
end
|
2022-05-01 12:08:05 -07:00
|
|
|
for i, k in ipairs(keys) do
|
2024-02-15 03:53:51 -07:00
|
|
|
o = o[k] --- @type any
|
2022-03-24 12:01:04 -07:00
|
|
|
if o == nil then
|
2022-12-14 18:27:23 -07:00
|
|
|
return nil
|
|
|
|
elseif type(o) ~= 'table' and next(keys, i) then
|
|
|
|
return nil
|
2022-03-24 12:01:04 -07:00
|
|
|
end
|
|
|
|
end
|
|
|
|
return o
|
|
|
|
end
|
|
|
|
|
2019-11-25 02:08:02 -07:00
|
|
|
--- Extends a list-like table with the values of another list-like table.
|
|
|
|
---
|
|
|
|
--- NOTE: This mutates dst!
|
|
|
|
---
|
2021-08-22 13:55:28 -07:00
|
|
|
---@see |vim.tbl_extend()|
|
2019-11-25 02:08:02 -07:00
|
|
|
---
|
2022-09-27 13:44:01 -07:00
|
|
|
---@generic T: table
|
|
|
|
---@param dst T List which will be modified and appended to
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param src table List from which values will be inserted
|
2024-02-15 10:16:04 -07:00
|
|
|
---@param start integer? Start index on src. Defaults to 1
|
|
|
|
---@param finish integer? Final index on src. Defaults to `#src`
|
2022-09-27 13:44:01 -07:00
|
|
|
---@return T dst
|
2019-11-20 18:09:21 -07:00
|
|
|
function vim.list_extend(dst, src, start, finish)
|
|
|
|
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])
|
2019-11-13 13:55:26 -07:00
|
|
|
end
|
|
|
|
return dst
|
|
|
|
end
|
|
|
|
|
2024-04-21 15:58:48 -07:00
|
|
|
--- @deprecated
|
2019-05-19 08:58:54 -07:00
|
|
|
--- Creates a copy of a list-like table such that any nested tables are
|
|
|
|
--- "unrolled" and appended to the result.
|
|
|
|
---
|
2021-08-22 13:55:28 -07:00
|
|
|
---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
|
2019-11-13 13:55:26 -07:00
|
|
|
---
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param t table List-like table
|
|
|
|
---@return table Flattened copy of the given list-like table
|
2019-10-22 18:50:42 -07:00
|
|
|
function vim.tbl_flatten(t)
|
2024-05-16 09:42:13 -07:00
|
|
|
vim.deprecate('vim.tbl_flatten', 'vim.iter(…):flatten():totable()', '0.13')
|
2019-05-18 07:00:06 -07:00
|
|
|
local result = {}
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @param _t table<any,any>
|
2019-05-18 07:00:06 -07:00
|
|
|
local function _tbl_flatten(_t)
|
|
|
|
local n = #_t
|
|
|
|
for i = 1, n do
|
|
|
|
local v = _t[i]
|
|
|
|
if type(v) == 'table' then
|
|
|
|
_tbl_flatten(v)
|
|
|
|
elseif v then
|
|
|
|
table.insert(result, v)
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
_tbl_flatten(t)
|
|
|
|
return result
|
|
|
|
end
|
|
|
|
|
2023-09-20 04:15:23 -07:00
|
|
|
--- Enumerates key-value pairs of a table, ordered by key.
|
2023-01-23 02:26:46 -07:00
|
|
|
---
|
|
|
|
---@see Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
|
|
|
|
---
|
2024-03-05 05:06:15 -07:00
|
|
|
---@generic T: table, K, V
|
|
|
|
---@param t T Dict-like table
|
|
|
|
---@return fun(table: table<K, V>, index?: K):K, V # |for-in| iterator over sorted keys and their values
|
|
|
|
---@return T
|
2023-01-23 02:26:46 -07:00
|
|
|
function vim.spairs(t)
|
2024-05-27 06:08:23 -07:00
|
|
|
vim.validate('t', t, 'table')
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @cast t table<any,any>
|
2023-01-23 02:26:46 -07:00
|
|
|
|
|
|
|
-- collect the keys
|
|
|
|
local keys = {}
|
|
|
|
for k in pairs(t) do
|
|
|
|
table.insert(keys, k)
|
|
|
|
end
|
|
|
|
table.sort(keys)
|
|
|
|
|
|
|
|
-- Return the iterator function.
|
|
|
|
local i = 0
|
|
|
|
return function()
|
|
|
|
i = i + 1
|
|
|
|
if keys[i] then
|
|
|
|
return keys[i], t[keys[i]]
|
|
|
|
end
|
2024-03-06 03:03:55 -07:00
|
|
|
end,
|
|
|
|
t
|
2023-01-23 02:26:46 -07:00
|
|
|
end
|
|
|
|
|
2023-09-20 04:15:23 -07:00
|
|
|
--- Tests if `t` is an "array": a table indexed _only_ by integers (potentially non-contiguous).
|
2020-07-02 04:09:17 -07:00
|
|
|
---
|
2024-04-21 06:19:43 -07:00
|
|
|
--- If the indexes start from 1 and are contiguous then the array is also a list. |vim.islist()|
|
2023-09-20 04:15:23 -07:00
|
|
|
---
|
|
|
|
--- 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
|
2019-11-13 13:55:26 -07:00
|
|
|
---
|
2024-04-21 08:29:10 -07:00
|
|
|
---@param t? table
|
2023-04-14 03:01:08 -07:00
|
|
|
---@return boolean `true` if array-like table, else `false`.
|
2024-04-21 08:29:10 -07:00
|
|
|
function vim.isarray(t)
|
2019-11-13 13:55:26 -07:00
|
|
|
if type(t) ~= 'table' then
|
|
|
|
return false
|
|
|
|
end
|
|
|
|
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @cast t table<any,any>
|
|
|
|
|
2019-11-13 13:55:26 -07:00
|
|
|
local count = 0
|
|
|
|
|
|
|
|
for k, _ in pairs(t) do
|
2023-12-28 16:00:30 -07:00
|
|
|
-- Check if the number k is an integer
|
2023-04-14 03:01:08 -07:00
|
|
|
if type(k) == 'number' and k == math.floor(k) then
|
2019-11-13 13:55:26 -07:00
|
|
|
count = count + 1
|
|
|
|
else
|
|
|
|
return false
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
if count > 0 then
|
|
|
|
return true
|
|
|
|
else
|
2019-11-27 12:45:41 -07:00
|
|
|
-- TODO(bfredl): in the future, we will always be inside nvim
|
|
|
|
-- then this check can be deleted.
|
|
|
|
if vim._empty_dict_mt == nil then
|
2022-10-24 05:53:53 -07:00
|
|
|
return false
|
2019-11-27 12:45:41 -07:00
|
|
|
end
|
|
|
|
return getmetatable(t) ~= vim._empty_dict_mt
|
2019-11-13 13:55:26 -07:00
|
|
|
end
|
|
|
|
end
|
|
|
|
|
2024-04-21 06:19:43 -07:00
|
|
|
--- @deprecated
|
|
|
|
function vim.tbl_islist(t)
|
|
|
|
vim.deprecate('vim.tbl_islist', 'vim.islist', '0.12')
|
|
|
|
return vim.islist(t)
|
|
|
|
end
|
|
|
|
|
2023-09-20 04:15:23 -07:00
|
|
|
--- 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|.
|
2023-04-14 03:01:08 -07:00
|
|
|
---
|
2024-04-21 08:29:10 -07:00
|
|
|
---@see |vim.isarray()|
|
2023-04-14 03:01:08 -07:00
|
|
|
---
|
2024-04-21 06:19:43 -07:00
|
|
|
---@param t? table
|
2023-04-14 03:01:08 -07:00
|
|
|
---@return boolean `true` if list-like table, else `false`.
|
2024-04-21 06:19:43 -07:00
|
|
|
function vim.islist(t)
|
2023-04-14 03:01:08 -07:00
|
|
|
if type(t) ~= 'table' then
|
|
|
|
return false
|
|
|
|
end
|
|
|
|
|
2024-03-06 02:40:11 -07:00
|
|
|
if next(t) == nil then
|
2023-04-14 03:01:08 -07:00
|
|
|
return getmetatable(t) ~= vim._empty_dict_mt
|
2024-03-06 02:40:11 -07:00
|
|
|
end
|
|
|
|
|
|
|
|
local j = 1
|
|
|
|
for _ in
|
|
|
|
pairs(t--[[@as table<any,any>]])
|
|
|
|
do
|
|
|
|
if t[j] == nil then
|
|
|
|
return false
|
2023-04-14 03:01:08 -07:00
|
|
|
end
|
2024-03-06 02:40:11 -07:00
|
|
|
j = j + 1
|
2023-04-14 03:01:08 -07:00
|
|
|
end
|
2024-03-06 02:40:11 -07:00
|
|
|
|
|
|
|
return true
|
2023-04-14 03:01:08 -07:00
|
|
|
end
|
|
|
|
|
2020-03-02 00:38:43 -07:00
|
|
|
--- Counts the number of non-nil values in table `t`.
|
|
|
|
---
|
2023-09-14 06:23:01 -07:00
|
|
|
--- ```lua
|
2022-11-23 04:31:49 -07:00
|
|
|
--- vim.tbl_count({ a=1, b=2 }) --> 2
|
|
|
|
--- vim.tbl_count({ 1, 2 }) --> 2
|
2023-09-14 06:23:01 -07:00
|
|
|
--- ```
|
2020-03-02 00:38:43 -07:00
|
|
|
---
|
2021-08-22 13:55:28 -07:00
|
|
|
---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param t table Table
|
2024-02-15 10:16:04 -07:00
|
|
|
---@return integer : Number of non-nil values in table
|
2020-03-02 00:38:43 -07:00
|
|
|
function vim.tbl_count(t)
|
2024-05-27 06:08:23 -07:00
|
|
|
vim.validate('t', t, 'table')
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @cast t table<any,any>
|
2020-03-02 00:38:43 -07:00
|
|
|
|
|
|
|
local count = 0
|
|
|
|
for _ in pairs(t) do
|
|
|
|
count = count + 1
|
|
|
|
end
|
|
|
|
return count
|
|
|
|
end
|
|
|
|
|
2021-03-07 18:18:32 -07:00
|
|
|
--- Creates a copy of a table containing only elements from start to end (inclusive)
|
|
|
|
---
|
2022-09-27 13:44:01 -07:00
|
|
|
---@generic T
|
2024-02-15 10:16:04 -07:00
|
|
|
---@param list T[] Table
|
2023-03-04 06:07:39 -07:00
|
|
|
---@param start integer|nil Start range of slice
|
|
|
|
---@param finish integer|nil End range of slice
|
2024-02-15 10:16:04 -07:00
|
|
|
---@return T[] Copy of table sliced from start to finish (inclusive)
|
2021-03-07 18:18:32 -07:00
|
|
|
function vim.list_slice(list, start, finish)
|
2024-02-15 03:53:51 -07:00
|
|
|
local new_list = {} --- @type `T`[]
|
2021-03-07 18:18:32 -07:00
|
|
|
for i = start or 1, finish or #list do
|
|
|
|
new_list[#new_list + 1] = list[i]
|
|
|
|
end
|
|
|
|
return new_list
|
|
|
|
end
|
|
|
|
|
2019-05-25 01:00:41 -07:00
|
|
|
--- Trim whitespace (Lua pattern "%s") from both sides of a string.
|
2019-05-20 14:06:14 -07:00
|
|
|
---
|
2023-08-03 08:35:10 -07:00
|
|
|
---@see |lua-patterns|
|
2021-08-22 13:55:28 -07:00
|
|
|
---@see https://www.lua.org/pil/20.2.html
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param s string String to trim
|
|
|
|
---@return string String with whitespace removed from its beginning and end
|
2019-10-22 18:50:42 -07:00
|
|
|
function vim.trim(s)
|
2024-05-27 06:08:23 -07:00
|
|
|
vim.validate('s', s, 'string')
|
2019-05-20 14:06:14 -07:00
|
|
|
return s:match('^%s*(.*%S)') or ''
|
|
|
|
end
|
|
|
|
|
2022-08-08 09:58:32 -07:00
|
|
|
--- Escapes magic chars in |lua-patterns|.
|
2019-09-03 13:51:45 -07:00
|
|
|
---
|
2021-08-22 13:55:28 -07:00
|
|
|
---@see https://github.com/rxi/lume
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param s string String to escape
|
|
|
|
---@return string %-escaped pattern string
|
2019-10-22 18:50:42 -07:00
|
|
|
function vim.pesc(s)
|
2024-05-27 06:08:23 -07:00
|
|
|
vim.validate('s', s, 'string')
|
2022-10-24 05:53:53 -07:00
|
|
|
return (s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1'))
|
2019-09-03 13:51:45 -07:00
|
|
|
end
|
|
|
|
|
2020-01-13 00:41:55 -07:00
|
|
|
--- Tests if `s` starts with `prefix`.
|
|
|
|
---
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param s string String
|
|
|
|
---@param prefix string Prefix to match
|
|
|
|
---@return boolean `true` if `prefix` is a prefix of `s`
|
2019-12-01 06:32:55 -07:00
|
|
|
function vim.startswith(s, prefix)
|
2024-05-27 06:08:23 -07:00
|
|
|
vim.validate('s', s, 'string')
|
|
|
|
vim.validate('prefix', prefix, 'string')
|
2019-12-01 06:32:55 -07:00
|
|
|
return s:sub(1, #prefix) == prefix
|
|
|
|
end
|
|
|
|
|
2020-01-13 00:41:55 -07:00
|
|
|
--- Tests if `s` ends with `suffix`.
|
|
|
|
---
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param s string String
|
|
|
|
---@param suffix string Suffix to match
|
|
|
|
---@return boolean `true` if `suffix` is a suffix of `s`
|
2019-12-01 06:32:55 -07:00
|
|
|
function vim.endswith(s, suffix)
|
2024-05-27 06:08:23 -07:00
|
|
|
vim.validate('s', s, 'string')
|
|
|
|
vim.validate('suffix', suffix, 'string')
|
2019-12-01 06:32:55 -07:00
|
|
|
return #suffix == 0 or s:sub(-#suffix) == suffix
|
|
|
|
end
|
|
|
|
|
2020-03-26 11:24:04 -07:00
|
|
|
do
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @alias vim.validate.Type
|
|
|
|
--- | 't' | 'table'
|
|
|
|
--- | 's' | 'string'
|
|
|
|
--- | 'n' | 'number'
|
|
|
|
--- | 'f' | 'function'
|
|
|
|
--- | 'c' | 'callable'
|
|
|
|
--- | 'nil'
|
|
|
|
--- | 'thread'
|
|
|
|
--- | 'userdata
|
|
|
|
|
2019-11-10 20:58:14 -07:00
|
|
|
local type_names = {
|
2020-03-26 11:24:04 -07:00
|
|
|
['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',
|
2019-11-10 20:58:14 -07:00
|
|
|
}
|
2020-03-26 11:24:04 -07:00
|
|
|
|
2024-02-27 08:20:32 -07:00
|
|
|
--- @nodoc
|
2024-06-04 06:06:02 -07:00
|
|
|
--- @class vim.validate.Spec [any, string|string[], boolean]
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @field [1] any Argument value
|
|
|
|
--- @field [2] string|string[]|fun(v:any):boolean, string? Type name, or callable
|
|
|
|
--- @field [3]? boolean
|
|
|
|
|
2019-11-10 23:18:59 -07:00
|
|
|
local function _is_type(val, t)
|
lsp: vim.lsp.diagnostic (#12655)
Breaking Changes:
- Deprecated all `vim.lsp.util.{*diagnostics*}()` functions.
- Instead, all functions must be found in vim.lsp.diagnostic
- For now, they issue a warning ONCE per neovim session. In a
"little while" we will remove them completely.
- `vim.lsp.callbacks` has moved to `vim.lsp.handlers`.
- For a "little while" we will just redirect `vim.lsp.callbacks` to
`vim.lsp.handlers`. However, we will remove this at some point, so
it is recommended that you change all of your references to
`callbacks` into `handlers`.
- This also means that for functions like |vim.lsp.start_client()|
and similar, keyword style arguments have moved from "callbacks"
to "handlers". Once again, these are currently being forward, but
will cease to be forwarded in a "little while".
- Changed the highlight groups for LspDiagnostic highlight as they were
inconsistently named.
- For more information, see |lsp-highlight-diagnostics|
- Changed the sign group names as well, to be consistent with
|lsp-highlight-diagnostics|
General Enhancements:
- Rewrote much of the getting started help document for lsp. It also
provides a much nicer configuration strategy, so as to not recommend
globally overwriting builtin neovim mappings.
LSP Enhancements:
- Introduced the concept of |lsp-handlers| which will allow much better
customization for users without having to copy & paste entire files /
functions / etc.
Diagnostic Enhancements:
- "goto next diagnostic" |vim.lsp.diagnostic.goto_next()|
- "goto prev diagnostic" |vim.lsp.diagnostic.goto_prev()|
- For each of the gotos, auto open diagnostics is available as a
configuration option
- Configurable diagnostic handling:
- See |vim.lsp.diagnostic.on_publish_diagnostics()|
- Delay display until after insert mode
- Configure signs
- Configure virtual text
- Configure underline
- Set the location list with the buffers diagnostics.
- See |vim.lsp.diagnostic.set_loclist()|
- Better performance for getting counts and line diagnostics
- They are now cached on save, to enhance lookups.
- Particularly useful for checking in statusline, etc.
- Actual testing :)
- See ./test/functional/plugin/lsp/diagnostic_spec.lua
- Added `guisp` for underline highlighting
NOTE: "a little while" means enough time to feel like most plugins and
plugin authors have had a chance to refactor their code to use the
updated calls. Then we will remove them completely. There is no need to
keep them, because we don't have any released version of neovim that
exposes these APIs. I'm trying to be nice to people following HEAD :)
Co-authored: [Twitch Chat 2020](https://twitch.tv/teej_dv)
2020-11-12 20:21:34 -07:00
|
|
|
return type(val) == t or (t == 'callable' and vim.is_callable(val))
|
2019-10-28 04:52:18 -07:00
|
|
|
end
|
|
|
|
|
2024-05-15 05:13:47 -07:00
|
|
|
--- @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
|
|
|
|
|
2024-02-15 03:53:51 -07:00
|
|
|
--- @param opt table<vim.validate.Type,vim.validate.Spec>
|
|
|
|
--- @return boolean, string?
|
2020-03-26 11:24:04 -07:00
|
|
|
local function is_valid(opt)
|
|
|
|
if type(opt) ~= 'table' then
|
|
|
|
return false, string.format('opt: expected table, got %s', type(opt))
|
|
|
|
end
|
|
|
|
|
2024-05-15 05:13:47 -07:00
|
|
|
local report --- @type table<string,string>?
|
2019-10-28 04:52:18 -07:00
|
|
|
|
2024-05-15 05:13:47 -07:00
|
|
|
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
|
2022-01-01 12:35:15 -07:00
|
|
|
end
|
2024-05-15 05:13:47 -07:00
|
|
|
end
|
2020-03-26 11:24:04 -07:00
|
|
|
|
2024-05-15 05:13:47 -07:00
|
|
|
if report then
|
|
|
|
for _, msg in vim.spairs(report) do -- luacheck: ignore
|
|
|
|
return false, msg
|
2019-10-28 04:52:18 -07:00
|
|
|
end
|
|
|
|
end
|
2020-03-26 11:24:04 -07:00
|
|
|
|
2024-02-15 03:53:51 -07:00
|
|
|
return true
|
2019-10-28 04:52:18 -07:00
|
|
|
end
|
|
|
|
|
2024-05-27 06:08:23 -07:00
|
|
|
--- Validate function arguments.
|
|
|
|
---
|
|
|
|
--- This function has two valid forms:
|
|
|
|
---
|
|
|
|
--- 1. vim.validate(name: str, value: any, type: string, optional?: bool)
|
|
|
|
--- 2. vim.validate(spec: table)
|
|
|
|
---
|
|
|
|
--- Form 1 validates that argument {name} with value {value} has the type
|
|
|
|
--- {type}. {type} must be a value returned by |lua-type()|. If {optional} is
|
|
|
|
--- true, then {value} may be null. This form is significantly faster and
|
|
|
|
--- should be preferred for simple cases.
|
|
|
|
---
|
|
|
|
--- Example:
|
|
|
|
---
|
|
|
|
--- ```lua
|
|
|
|
--- function vim.startswith(s, prefix)
|
|
|
|
--- vim.validate('s', s, 'string')
|
|
|
|
--- vim.validate('prefix', prefix, 'string')
|
|
|
|
--- ...
|
|
|
|
--- end
|
|
|
|
--- ```
|
|
|
|
---
|
|
|
|
--- Form 2 validates a parameter specification (types and values). Specs are
|
|
|
|
--- evaluated in alphanumeric order, until the first failure.
|
2023-09-20 04:15:23 -07:00
|
|
|
---
|
|
|
|
--- Usage example:
|
|
|
|
---
|
|
|
|
--- ```lua
|
2024-02-15 10:16:04 -07:00
|
|
|
--- function user.new(name, age, hobbies)
|
|
|
|
--- vim.validate{
|
|
|
|
--- name={name, 'string'},
|
|
|
|
--- age={age, 'number'},
|
|
|
|
--- hobbies={hobbies, 'table'},
|
|
|
|
--- }
|
|
|
|
--- ...
|
|
|
|
--- end
|
2023-09-20 04:15:23 -07:00
|
|
|
--- ```
|
|
|
|
---
|
|
|
|
--- Examples with explicit argument values (can be run directly):
|
|
|
|
---
|
|
|
|
--- ```lua
|
2024-02-15 10:16:04 -07:00
|
|
|
--- vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
|
|
|
|
--- --> NOP (success)
|
2023-09-20 04:15:23 -07:00
|
|
|
---
|
2024-02-15 10:16:04 -07:00
|
|
|
--- vim.validate{arg1={1, 'table'}}
|
|
|
|
--- --> error('arg1: expected table, got number')
|
2023-09-20 04:15:23 -07:00
|
|
|
---
|
2024-02-15 10:16:04 -07:00
|
|
|
--- vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
|
|
|
|
--- --> error('arg1: expected even number, got 3')
|
2023-09-20 04:15:23 -07:00
|
|
|
--- ```
|
|
|
|
---
|
|
|
|
--- If multiple types are valid they can be given as a list.
|
|
|
|
---
|
|
|
|
--- ```lua
|
2024-02-15 10:16:04 -07:00
|
|
|
--- vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}}
|
|
|
|
--- -- NOP (success)
|
2023-09-20 04:15:23 -07:00
|
|
|
---
|
2024-02-15 10:16:04 -07:00
|
|
|
--- vim.validate{arg1={1, {'string', 'table'}}}
|
|
|
|
--- -- error('arg1: expected string|table, got number')
|
2023-09-20 04:15:23 -07:00
|
|
|
--- ```
|
|
|
|
---
|
2024-02-15 03:53:51 -07:00
|
|
|
---@param opt table<vim.validate.Type,vim.validate.Spec> (table) Names of parameters to validate. Each key is a parameter
|
2023-09-20 04:15:23 -07:00
|
|
|
--- name; each value is a tuple in one of these forms:
|
|
|
|
--- 1. (arg_value, type_name, optional)
|
|
|
|
--- - arg_value: argument value
|
|
|
|
--- - type_name: string|table type name, one of: ("table", "t", "string",
|
|
|
|
--- "s", "number", "n", "boolean", "b", "function", "f", "nil",
|
|
|
|
--- "thread", "userdata") or list of them.
|
|
|
|
--- - optional: (optional) boolean, if true, `nil` is valid
|
|
|
|
--- 2. (arg_value, fn, msg)
|
|
|
|
--- - arg_value: argument value
|
|
|
|
--- - fn: any function accepting one argument, returns true if and
|
|
|
|
--- 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
|
2024-05-27 06:08:23 -07:00
|
|
|
--- @overload fun(name: string, val: any, expected: string, optional?: boolean)
|
|
|
|
function vim.validate(opt, ...)
|
|
|
|
local ok = false
|
|
|
|
local err_msg ---@type string?
|
|
|
|
local narg = select('#', ...)
|
|
|
|
if narg == 0 then
|
|
|
|
ok, err_msg = is_valid(opt)
|
|
|
|
elseif narg >= 2 then
|
|
|
|
-- Overloaded signature for fast/simple cases
|
|
|
|
local name = opt --[[@as string]]
|
|
|
|
local v, expected, optional = ... ---@type string, string, boolean?
|
|
|
|
local actual = type(v)
|
|
|
|
|
|
|
|
ok = (actual == expected) or (v == nil and optional == true)
|
|
|
|
if not ok then
|
|
|
|
err_msg = ('%s: expected %s, got %s%s'):format(
|
|
|
|
name,
|
|
|
|
expected,
|
|
|
|
actual,
|
|
|
|
v and (' (%s)'):format(v) or ''
|
|
|
|
)
|
|
|
|
end
|
|
|
|
else
|
|
|
|
error('invalid arguments')
|
|
|
|
end
|
|
|
|
|
2020-03-26 11:24:04 -07:00
|
|
|
if not ok then
|
2021-11-06 07:26:10 -07:00
|
|
|
error(err_msg, 2)
|
2020-03-26 11:24:04 -07:00
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
2019-11-10 23:18:59 -07:00
|
|
|
--- Returns true if object `f` can be called as a function.
|
2019-10-28 04:52:18 -07:00
|
|
|
---
|
2022-05-11 09:23:46 -07:00
|
|
|
---@param f any Any object
|
|
|
|
---@return boolean `true` if `f` is callable, else `false`
|
2019-10-28 04:52:18 -07:00
|
|
|
function vim.is_callable(f)
|
|
|
|
if type(f) == 'function' then
|
|
|
|
return true
|
|
|
|
end
|
|
|
|
local m = getmetatable(f)
|
|
|
|
if m == nil then
|
|
|
|
return false
|
|
|
|
end
|
2024-07-03 15:36:00 -07:00
|
|
|
return type(rawget(m, '__call')) == 'function'
|
2019-10-28 04:52:18 -07:00
|
|
|
end
|
|
|
|
|
2023-09-20 04:15:23 -07:00
|
|
|
--- Creates a table whose missing keys are provided by {createfn} (like Python's "defaultdict").
|
2022-09-06 23:39:56 -07:00
|
|
|
---
|
2023-09-20 04:15:23 -07:00
|
|
|
--- If {createfn} is `nil` it defaults to defaulttable() itself, so accessing nested keys creates
|
|
|
|
--- nested tables:
|
2022-09-06 23:39:56 -07:00
|
|
|
---
|
2023-09-14 06:23:01 -07:00
|
|
|
--- ```lua
|
2022-09-06 23:39:56 -07:00
|
|
|
--- local a = vim.defaulttable()
|
|
|
|
--- a.b.c = 1
|
2023-09-14 06:23:01 -07:00
|
|
|
--- ```
|
2022-09-06 23:39:56 -07:00
|
|
|
---
|
2024-01-09 10:36:46 -07:00
|
|
|
---@param createfn? fun(key:any):any Provides the value for a missing `key`.
|
2023-09-20 04:15:23 -07:00
|
|
|
---@return table # Empty table with `__index` metamethod.
|
|
|
|
function vim.defaulttable(createfn)
|
|
|
|
createfn = createfn or function(_)
|
2023-04-01 07:02:58 -07:00
|
|
|
return vim.defaulttable()
|
|
|
|
end
|
2022-09-06 23:39:56 -07:00
|
|
|
return setmetatable({}, {
|
|
|
|
__index = function(tbl, key)
|
2023-09-20 04:15:23 -07:00
|
|
|
rawset(tbl, key, createfn(key))
|
2022-09-06 23:39:56 -07:00
|
|
|
return rawget(tbl, key)
|
|
|
|
end,
|
|
|
|
})
|
|
|
|
end
|
|
|
|
|
2023-06-08 03:11:24 -07:00
|
|
|
do
|
|
|
|
---@class vim.Ringbuf<T>
|
|
|
|
---@field private _items table[]
|
|
|
|
---@field private _idx_read integer
|
|
|
|
---@field private _idx_write integer
|
|
|
|
---@field private _size integer
|
2024-02-07 10:22:03 -07:00
|
|
|
---@overload fun(self): table?
|
2023-06-08 03:11:24 -07:00
|
|
|
local Ringbuf = {}
|
|
|
|
|
|
|
|
--- Clear all items
|
|
|
|
function Ringbuf.clear(self)
|
|
|
|
self._items = {}
|
|
|
|
self._idx_read = 0
|
|
|
|
self._idx_write = 0
|
|
|
|
end
|
|
|
|
|
|
|
|
--- Adds an item, overriding the oldest item if the buffer is full.
|
|
|
|
---@generic T
|
|
|
|
---@param item T
|
|
|
|
function Ringbuf.push(self, item)
|
|
|
|
self._items[self._idx_write] = item
|
|
|
|
self._idx_write = (self._idx_write + 1) % self._size
|
|
|
|
if self._idx_write == self._idx_read then
|
|
|
|
self._idx_read = (self._idx_read + 1) % self._size
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
--- Removes and returns the first unread item
|
|
|
|
---@generic T
|
|
|
|
---@return T?
|
|
|
|
function Ringbuf.pop(self)
|
|
|
|
local idx_read = self._idx_read
|
|
|
|
if idx_read == self._idx_write then
|
|
|
|
return nil
|
|
|
|
end
|
|
|
|
local item = self._items[idx_read]
|
|
|
|
self._items[idx_read] = nil
|
|
|
|
self._idx_read = (idx_read + 1) % self._size
|
|
|
|
return item
|
|
|
|
end
|
|
|
|
|
|
|
|
--- Returns the first unread item without removing it
|
|
|
|
---@generic T
|
|
|
|
---@return T?
|
|
|
|
function Ringbuf.peek(self)
|
|
|
|
if self._idx_read == self._idx_write then
|
|
|
|
return nil
|
|
|
|
end
|
|
|
|
return self._items[self._idx_read]
|
|
|
|
end
|
|
|
|
|
|
|
|
--- Create a ring buffer limited to a maximal number of items.
|
|
|
|
--- Once the buffer is full, adding a new entry overrides the oldest entry.
|
|
|
|
---
|
2023-09-14 06:23:01 -07:00
|
|
|
--- ```lua
|
2024-02-15 10:16:04 -07:00
|
|
|
--- local ringbuf = vim.ringbuf(4)
|
|
|
|
--- ringbuf:push("a")
|
|
|
|
--- ringbuf:push("b")
|
|
|
|
--- ringbuf:push("c")
|
|
|
|
--- ringbuf:push("d")
|
|
|
|
--- ringbuf:push("e") -- overrides "a"
|
|
|
|
--- print(ringbuf:pop()) -- returns "b"
|
|
|
|
--- print(ringbuf:pop()) -- returns "c"
|
2023-06-08 03:11:24 -07:00
|
|
|
---
|
2024-02-15 10:16:04 -07:00
|
|
|
--- -- Can be used as iterator. Pops remaining items:
|
|
|
|
--- for val in ringbuf do
|
|
|
|
--- print(val)
|
|
|
|
--- end
|
2023-09-14 06:23:01 -07:00
|
|
|
--- ```
|
2023-06-08 03:11:24 -07:00
|
|
|
---
|
|
|
|
--- Returns a Ringbuf instance with the following methods:
|
|
|
|
---
|
|
|
|
--- - |Ringbuf:push()|
|
|
|
|
--- - |Ringbuf:pop()|
|
|
|
|
--- - |Ringbuf:peek()|
|
|
|
|
--- - |Ringbuf:clear()|
|
|
|
|
---
|
|
|
|
---@param size integer
|
2024-03-05 05:06:15 -07:00
|
|
|
---@return vim.Ringbuf ringbuf
|
2023-06-08 03:11:24 -07:00
|
|
|
function vim.ringbuf(size)
|
|
|
|
local ringbuf = {
|
|
|
|
_items = {},
|
|
|
|
_size = size + 1,
|
|
|
|
_idx_read = 0,
|
|
|
|
_idx_write = 0,
|
|
|
|
}
|
|
|
|
return setmetatable(ringbuf, {
|
|
|
|
__index = Ringbuf,
|
|
|
|
__call = function(self)
|
|
|
|
return self:pop()
|
|
|
|
end,
|
|
|
|
})
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
2024-01-22 10:23:28 -07:00
|
|
|
--- @private
|
|
|
|
--- @generic T
|
|
|
|
--- @param root string
|
|
|
|
--- @param mod T
|
|
|
|
--- @return T
|
|
|
|
function vim._defer_require(root, mod)
|
|
|
|
return setmetatable({}, {
|
|
|
|
---@param t table<string, any>
|
|
|
|
---@param k string
|
|
|
|
__index = function(t, k)
|
|
|
|
if not mod[k] then
|
|
|
|
return
|
|
|
|
end
|
|
|
|
local name = string.format('%s.%s', root, k)
|
|
|
|
t[k] = require(name)
|
|
|
|
return t[k]
|
|
|
|
end,
|
|
|
|
})
|
|
|
|
end
|
|
|
|
|
2024-06-03 10:04:28 -07:00
|
|
|
--- @nodoc
|
|
|
|
--- @class vim.context.mods
|
2024-06-21 06:23:05 -07:00
|
|
|
--- @field bo? table<string, any>
|
2024-06-03 10:04:28 -07:00
|
|
|
--- @field buf? integer
|
|
|
|
--- @field emsg_silent? boolean
|
2024-06-23 07:13:06 -07:00
|
|
|
--- @field env? table<string, any>
|
2024-06-21 06:23:05 -07:00
|
|
|
--- @field go? table<string, any>
|
2024-06-03 10:04:28 -07:00
|
|
|
--- @field hide? boolean
|
|
|
|
--- @field keepalt? boolean
|
|
|
|
--- @field keepjumps? boolean
|
|
|
|
--- @field keepmarks? boolean
|
|
|
|
--- @field keeppatterns? boolean
|
|
|
|
--- @field lockmarks? boolean
|
|
|
|
--- @field noautocmd? boolean
|
2024-06-21 06:23:05 -07:00
|
|
|
--- @field o? table<string, any>
|
2024-06-03 10:04:28 -07:00
|
|
|
--- @field sandbox? boolean
|
|
|
|
--- @field silent? boolean
|
|
|
|
--- @field unsilent? boolean
|
|
|
|
--- @field win? integer
|
2024-06-21 06:23:05 -07:00
|
|
|
--- @field wo? table<string, any>
|
|
|
|
|
|
|
|
--- @nodoc
|
|
|
|
--- @class vim.context.state
|
|
|
|
--- @field bo? table<string, any>
|
2024-06-23 07:13:06 -07:00
|
|
|
--- @field env? table<string, any>
|
2024-06-21 06:23:05 -07:00
|
|
|
--- @field go? table<string, any>
|
|
|
|
--- @field wo? table<string, any>
|
|
|
|
|
|
|
|
local scope_map = { buf = 'bo', global = 'go', win = 'wo' }
|
2024-06-23 07:13:06 -07:00
|
|
|
local scope_order = { 'o', 'wo', 'bo', 'go', 'env' }
|
|
|
|
local state_restore_order = { 'bo', 'wo', 'go', 'env' }
|
2024-06-21 06:23:05 -07:00
|
|
|
|
|
|
|
--- Gets data about current state, enough to properly restore specified options/env/etc.
|
|
|
|
--- @param context vim.context.mods
|
|
|
|
--- @return vim.context.state
|
|
|
|
local get_context_state = function(context)
|
2024-06-23 07:13:06 -07:00
|
|
|
local res = { bo = {}, env = {}, go = {}, wo = {} }
|
2024-06-21 06:23:05 -07:00
|
|
|
|
|
|
|
-- Use specific order from possibly most to least intrusive
|
|
|
|
for _, scope in ipairs(scope_order) do
|
|
|
|
for name, _ in pairs(context[scope] or {}) do
|
|
|
|
local sc = scope == 'o' and scope_map[vim.api.nvim_get_option_info2(name, {}).scope] or scope
|
|
|
|
|
|
|
|
-- Do not override already set state and fall back to `vim.NIL` for
|
|
|
|
-- state `nil` values (which still needs restoring later)
|
|
|
|
res[sc][name] = res[sc][name] or vim[sc][name] or vim.NIL
|
|
|
|
|
|
|
|
-- Always track global option value to properly restore later.
|
|
|
|
-- This matters for at least `o` and `wo` (which might set either/both
|
|
|
|
-- local and global option values).
|
2024-06-23 07:13:06 -07:00
|
|
|
if sc ~= 'env' then
|
|
|
|
res.go[name] = res.go[name] or vim.go[name]
|
|
|
|
end
|
2024-06-21 06:23:05 -07:00
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
return res
|
|
|
|
end
|
2024-06-03 10:04:28 -07:00
|
|
|
|
|
|
|
--- Executes function `f` with the given context specification.
|
|
|
|
---
|
2024-06-21 06:23:02 -07:00
|
|
|
--- Notes:
|
|
|
|
--- - Context `{ buf = buf }` has no guarantees about current window when
|
|
|
|
--- inside context.
|
|
|
|
--- - Context `{ buf = buf, win = win }` is yet not allowed, but this seems
|
|
|
|
--- to be an implementation detail.
|
|
|
|
--- - There should be no way to revert currently set `context.sandbox = true`
|
|
|
|
--- (like with nested `vim._with()` calls). Otherwise it kind of breaks the
|
|
|
|
--- whole purpose of sandbox execution.
|
2024-06-21 06:23:05 -07:00
|
|
|
--- - Saving and restoring option contexts (`bo`, `go`, `o`, `wo`) trigger
|
|
|
|
--- `OptionSet` events. This is an implementation issue because not doing it
|
|
|
|
--- seems to mean using either 'eventignore' option or extra nesting with
|
|
|
|
--- `{ noautocmd = true }` (which itself is a wrapper for 'eventignore').
|
|
|
|
--- As `{ go = { eventignore = '...' } }` is a valid context which should be
|
|
|
|
--- properly set and restored, this is not a good approach.
|
|
|
|
--- Not triggering `OptionSet` seems to be a good idea, though. So probably
|
|
|
|
--- only moving context save and restore to lower level might resolve this.
|
2024-06-21 06:23:02 -07:00
|
|
|
---
|
2024-06-03 10:04:28 -07:00
|
|
|
--- @param context vim.context.mods
|
2024-06-08 12:40:18 -07:00
|
|
|
--- @param f function
|
|
|
|
--- @return any
|
2024-06-03 10:04:28 -07:00
|
|
|
function vim._with(context, f)
|
|
|
|
vim.validate('context', context, 'table')
|
|
|
|
vim.validate('f', f, 'function')
|
|
|
|
|
2024-06-21 06:23:05 -07:00
|
|
|
vim.validate('context.bo', context.bo, 'table', true)
|
2024-06-03 10:04:28 -07:00
|
|
|
vim.validate('context.buf', context.buf, 'number', true)
|
|
|
|
vim.validate('context.emsg_silent', context.emsg_silent, 'boolean', true)
|
2024-06-23 07:13:06 -07:00
|
|
|
vim.validate('context.env', context.env, 'table', true)
|
2024-06-21 06:23:05 -07:00
|
|
|
vim.validate('context.go', context.go, 'table', true)
|
2024-06-03 10:04:28 -07:00
|
|
|
vim.validate('context.hide', context.hide, 'boolean', true)
|
|
|
|
vim.validate('context.keepalt', context.keepalt, 'boolean', true)
|
|
|
|
vim.validate('context.keepjumps', context.keepjumps, 'boolean', true)
|
|
|
|
vim.validate('context.keepmarks', context.keepmarks, 'boolean', true)
|
|
|
|
vim.validate('context.keeppatterns', context.keeppatterns, 'boolean', true)
|
|
|
|
vim.validate('context.lockmarks', context.lockmarks, 'boolean', true)
|
|
|
|
vim.validate('context.noautocmd', context.noautocmd, 'boolean', true)
|
2024-06-21 06:23:05 -07:00
|
|
|
vim.validate('context.o', context.o, 'table', true)
|
2024-06-03 10:04:28 -07:00
|
|
|
vim.validate('context.sandbox', context.sandbox, 'boolean', true)
|
|
|
|
vim.validate('context.silent', context.silent, 'boolean', true)
|
|
|
|
vim.validate('context.unsilent', context.unsilent, 'boolean', true)
|
|
|
|
vim.validate('context.win', context.win, 'number', true)
|
2024-06-21 06:23:05 -07:00
|
|
|
vim.validate('context.wo', context.wo, 'table', true)
|
2024-06-03 10:04:28 -07:00
|
|
|
|
|
|
|
-- Check buffer exists
|
|
|
|
if context.buf then
|
|
|
|
if not vim.api.nvim_buf_is_valid(context.buf) then
|
|
|
|
error('Invalid buffer id: ' .. context.buf)
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
-- Check window exists
|
|
|
|
if context.win then
|
|
|
|
if not vim.api.nvim_win_is_valid(context.win) then
|
|
|
|
error('Invalid window id: ' .. context.win)
|
|
|
|
end
|
2024-06-21 06:23:02 -07:00
|
|
|
-- TODO: Maybe allow it?
|
|
|
|
if context.buf and vim.api.nvim_win_get_buf(context.win) ~= context.buf then
|
|
|
|
error('Can not set both `buf` and `win` context.')
|
|
|
|
end
|
2024-06-03 10:04:28 -07:00
|
|
|
end
|
|
|
|
|
2024-06-21 06:23:05 -07:00
|
|
|
-- Decorate so that save-set-restore options is done in correct window-buffer
|
|
|
|
local callback = function()
|
|
|
|
-- Cache current values to be changed by context
|
|
|
|
-- Abort early in case of bad context value
|
|
|
|
local ok, state = pcall(get_context_state, context)
|
|
|
|
if not ok then
|
|
|
|
error(state, 0)
|
2024-06-03 10:04:28 -07:00
|
|
|
end
|
|
|
|
|
2024-06-21 06:23:05 -07:00
|
|
|
-- Apply some parts of the context in specific order
|
|
|
|
-- NOTE: triggers `OptionSet` event
|
|
|
|
for _, scope in ipairs(scope_order) do
|
|
|
|
for name, context_value in pairs(context[scope] or {}) do
|
|
|
|
vim[scope][name] = context_value
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
-- Execute
|
|
|
|
local res = { pcall(f) }
|
|
|
|
|
|
|
|
-- Restore relevant cached values in specific order, global scope last
|
|
|
|
-- NOTE: triggers `OptionSet` event
|
|
|
|
for _, scope in ipairs(state_restore_order) do
|
|
|
|
for name, cached_value in pairs(state[scope]) do
|
|
|
|
vim[scope][name] = cached_value
|
|
|
|
end
|
|
|
|
end
|
2024-06-03 10:04:28 -07:00
|
|
|
|
2024-06-21 06:23:05 -07:00
|
|
|
-- Return
|
|
|
|
if not res[1] then
|
|
|
|
error(res[2], 0)
|
2024-06-03 10:04:28 -07:00
|
|
|
end
|
2024-06-21 06:23:05 -07:00
|
|
|
table.remove(res, 1)
|
|
|
|
return unpack(res, 1, table.maxn(res))
|
2024-06-03 10:04:28 -07:00
|
|
|
end
|
|
|
|
|
2024-06-21 06:23:05 -07:00
|
|
|
return vim._with_c(context, callback)
|
2024-06-03 10:04:28 -07:00
|
|
|
end
|
|
|
|
|
2019-10-22 18:50:42 -07:00
|
|
|
return vim
|