diff options
Diffstat (limited to 'runtime/lua/vim')
| -rw-r--r-- | runtime/lua/vim/_meta/api.lua | 2 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/options.lua | 5 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/vimfn.lua | 2 | ||||
| -rw-r--r-- | runtime/lua/vim/shared.lua | 153 | ||||
| -rw-r--r-- | runtime/lua/vim/treesitter/dev.lua | 5 | ||||
| -rw-r--r-- | runtime/lua/vim/treesitter/query.lua | 8 |
6 files changed, 88 insertions, 87 deletions
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 41bb5636b8..81fa7ce7ec 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1903,7 +1903,7 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end --- @param rhs string Right-hand-side `{rhs}` of the mapping. --- @param opts vim.api.keyset.keymap Optional parameters map: Accepts all `:map-arguments` as keys --- except `<buffer>`, values are booleans (default false). Also: ---- • "noremap" non-recursive mapping `:noremap` +--- • "noremap" disables `recursive_mapping`, like `:noremap` --- • "desc" human-readable description. --- • "callback" Lua function called in place of {rhs}. --- • "replace_keycodes" (boolean) When "expr" is true, replace diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index af676fa961..734096a755 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -3088,9 +3088,8 @@ vim.go.icon = vim.o.icon vim.o.iconstring = "" vim.go.iconstring = vim.o.iconstring ---- Ignore case in search patterns. Also used when searching in the tags ---- file. ---- Also see 'smartcase' and 'tagcase'. +--- Ignore case in search patterns, completion, and when searching the tags file. +--- See also 'smartcase' and 'tagcase'. --- Can be overruled by using "\c" or "\C" in the pattern, see --- `/ignorecase`. --- diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 2062e96b21..4113797759 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -4528,7 +4528,7 @@ function vim.fn.jobresize(job, width, height) end --- @return any function vim.fn.jobsend(...) end ---- Note: Prefer |vim.system()| in Lua. +--- Note: Prefer |vim.system()| in Lua (unless using the `pty` option). --- --- Spawns {cmd} as a job. --- If {cmd} is a List it runs directly (no 'shell'). diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index 0c38fa955a..9542d93789 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -534,12 +534,12 @@ function vim.tbl_flatten(t) return result end ---- Enumerate a table sorted by its keys. +--- Enumerates key-value pairs of a table, ordered by key. --- ---@see Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua --- ---@param t table Dict-like table ----@return function iterator over sorted keys and their values +---@return function # |for-in| iterator over sorted keys and their values function vim.spairs(t) assert(type(t) == 'table', string.format('Expected table, got %s', type(t))) @@ -551,7 +551,6 @@ function vim.spairs(t) table.sort(keys) -- Return the iterator function. - -- TODO(justinmk): Return "iterator function, table {t}, and nil", like pairs()? local i = 0 return function() i = i + 1 @@ -561,11 +560,14 @@ function vim.spairs(t) end end ---- Tests if a Lua table can be treated as an array (a table indexed by integers). +--- Tests if `t` is an "array": a table indexed _only_ by integers (potentially non-contiguous). --- ---- Empty table `{}` is assumed to be 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|. +--- If the indexes start from 1 and are contiguous then the array is also a list. |vim.tbl_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 ---@return boolean `true` if array-like table, else `false`. @@ -597,11 +599,13 @@ function vim.tbl_isarray(t) end end ---- Tests if a Lua table can be treated as a list (a table indexed by consecutive integers starting from 1). +--- 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|. --- ---- Empty table `{}` is assumed to be an 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()| --- ---@param t table ---@return boolean `true` if list-like table, else `false`. @@ -705,61 +709,6 @@ function vim.endswith(s, suffix) return #suffix == 0 or s:sub(-#suffix) == suffix end ---- Validates a parameter specification (types and values). ---- ---- Usage example: ---- ---- ```lua ---- function user.new(name, age, hobbies) ---- vim.validate{ ---- name={name, 'string'}, ---- age={age, 'number'}, ---- hobbies={hobbies, 'table'}, ---- } ---- ... ---- end ---- ``` ---- ---- Examples with explicit argument values (can be run directly): ---- ---- ```lua ---- vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}} ---- --> NOP (success) ---- ---- vim.validate{arg1={1, 'table'}} ---- --> error('arg1: expected table, got number') ---- ---- vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}} ---- --> error('arg1: expected even number, got 3') ---- ``` ---- ---- If multiple types are valid they can be given as a list. ---- ---- ```lua ---- vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}} ---- -- NOP (success) ---- ---- vim.validate{arg1={1, {'string', 'table'}}} ---- -- error('arg1: expected string|table, got number') ---- ---- ``` ---- ----@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 ---- - 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 -function vim.validate(opt) end -- luacheck: no unused - do local type_names = { ['table'] = 'table', @@ -844,6 +793,59 @@ do return true, nil end + --- Validates a parameter specification (types and values). + --- + --- Usage example: + --- + --- ```lua + --- function user.new(name, age, hobbies) + --- vim.validate{ + --- name={name, 'string'}, + --- age={age, 'number'}, + --- hobbies={hobbies, 'table'}, + --- } + --- ... + --- end + --- ``` + --- + --- Examples with explicit argument values (can be run directly): + --- + --- ```lua + --- vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}} + --- --> NOP (success) + --- + --- vim.validate{arg1={1, 'table'}} + --- --> error('arg1: expected table, got number') + --- + --- vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}} + --- --> error('arg1: expected even number, got 3') + --- ``` + --- + --- If multiple types are valid they can be given as a list. + --- + --- ```lua + --- vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}} + --- -- NOP (success) + --- + --- vim.validate{arg1={1, {'string', 'table'}}} + --- -- error('arg1: expected string|table, got number') + --- + --- ``` + --- + ---@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 + --- - 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 function vim.validate(opt) local ok, err_msg = is_valid(opt) if not ok then @@ -866,28 +868,25 @@ function vim.is_callable(f) return type(m.__call) == 'function' end ---- Creates a table whose members are automatically created when accessed, if they don't already ---- exist. ---- ---- They mimic defaultdict in python. +--- Creates a table whose missing keys are provided by {createfn} (like Python's "defaultdict"). --- ---- If {create} is `nil`, this will create a defaulttable whose constructor function is ---- this function, effectively allowing to create nested tables on the fly: +--- If {createfn} is `nil` it defaults to defaulttable() itself, so accessing nested keys creates +--- nested tables: --- --- ```lua --- local a = vim.defaulttable() --- a.b.c = 1 --- ``` --- ----@param create function?(key:any):any The function called to create a missing value. ----@return table Empty table with metamethod -function vim.defaulttable(create) - create = create or function(_) +---@param createfn function?(key:any):any Provides the value for a missing `key`. +---@return table # Empty table with `__index` metamethod. +function vim.defaulttable(createfn) + createfn = createfn or function(_) return vim.defaulttable() end return setmetatable({}, { __index = function(tbl, key) - rawset(tbl, key, create(key)) + rawset(tbl, key, createfn(key)) return rawget(tbl, key) end, }) diff --git a/runtime/lua/vim/treesitter/dev.lua b/runtime/lua/vim/treesitter/dev.lua index 7f24ba8590..61d84017d4 100644 --- a/runtime/lua/vim/treesitter/dev.lua +++ b/runtime/lua/vim/treesitter/dev.lua @@ -597,8 +597,9 @@ function M.edit_query(lang) }) api.nvim_buf_set_lines(query_buf, 0, -1, false, { - ';; Write your query here. Use @captures to highlight matches in the source buffer.', - ';; Completion for grammar nodes is available (see :h compl-omni)', + ';; Write queries here (see $VIMRUNTIME/queries/ for examples).', + ';; Move cursor to a capture ("@foo") to highlight matches in the source buffer.', + ';; Completion for grammar nodes is available (:help compl-omni)', '', '', }) diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua index 44ed37d64e..313d837d5c 100644 --- a/runtime/lua/vim/treesitter/query.lua +++ b/runtime/lua/vim/treesitter/query.lua @@ -843,11 +843,13 @@ function M.omnifunc(findstart, base) return require('vim.treesitter._query_linter').omnifunc(findstart, base) end ---- Open a window for live editing of a treesitter query. +--- Opens a live editor to query the buffer you started from. --- ---- Can also be shown with `:EditQuery`. *:EditQuery* +--- Can also be shown with *:EditQuery*. --- ---- Note that the editor opens a scratch buffer, and so queries aren't persisted on disk. +--- If you move the cursor to a capture name ("@foo"), text matching the capture is highlighted in +--- the source buffer. The query editor is a scratch buffer, use `:write` to save it. You can find +--- example queries at `$VIMRUNTIME/queries/`. --- --- @param lang? string language to open the query editor for. If omitted, inferred from the current buffer's filetype. function M.edit(lang) |