aboutsummaryrefslogtreecommitdiff
path: root/runtime/lua/vim
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/lua/vim')
-rw-r--r--runtime/lua/vim/_editor.lua7
-rw-r--r--runtime/lua/vim/_meta/api.lua27
-rw-r--r--runtime/lua/vim/_meta/vvars.lua11
-rw-r--r--runtime/lua/vim/_system.lua4
-rw-r--r--runtime/lua/vim/filetype.lua4
-rw-r--r--runtime/lua/vim/health.lua2
-rw-r--r--runtime/lua/vim/iter.lua130
-rw-r--r--runtime/lua/vim/lsp/handlers.lua2
-rw-r--r--runtime/lua/vim/lsp/util.lua6
-rw-r--r--runtime/lua/vim/shared.lua2
-rw-r--r--runtime/lua/vim/treesitter/query.lua2
11 files changed, 142 insertions, 55 deletions
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index cde61697b6..4fe601dfd5 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -95,7 +95,7 @@ vim.log = {
--- throws an error if {cmd} cannot be run.
---
--- @param cmd (string[]) Command to execute
---- @param opts (SystemOpts|nil) Options:
+--- @param opts vim.SystemOpts? Options:
--- - cwd: (string) Set the current working directory for the sub-process.
--- - env: table<string,string> Set environment variables for the new process. Inherits the
--- current environment with `NVIM` set to |v:servername|.
@@ -118,7 +118,7 @@ vim.log = {
--- parent exits. Note that the child process will still keep the parent's event loop alive
--- unless the parent process calls |uv.unref()| on the child's process handle.
---
---- @param on_exit (function|nil) Called when subprocess exits. When provided, the command runs
+--- @param on_exit? fun(out: vim.SystemCompleted) Called when subprocess exits. When provided, the command runs
--- asynchronously. Receives SystemCompleted object, see return of SystemObj:wait().
---
--- @return vim.SystemObj Object with the fields:
@@ -219,10 +219,9 @@ do
--- ```
---
---@see |paste|
- ---@alias paste_phase -1 | 1 | 2 | 3
---
---@param lines string[] # |readfile()|-style list of lines to paste. |channel-lines|
- ---@param phase paste_phase -1: "non-streaming" paste: the call contains all lines.
+ ---@param phase (-1|1|2|3) -1: "non-streaming" paste: the call contains all lines.
--- If paste is "streamed", `phase` indicates the stream state:
--- - 1: starts the paste (exactly once)
--- - 2: continues the paste (zero or more times)
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index e85f81f5f9..3f06d4fd43 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -155,7 +155,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
--- will be `nvim_buf_changedtick_event`. Not for Lua
--- callbacks.
--- @param opts vim.api.keyset.buf_attach Optional parameters.
---- • on_lines: Lua callback invoked on change. Return `true` to detach. Args:
+--- • on_lines: Lua callback invoked on change. Return `true` to
+--- detach. Args:
--- • the string "lines"
--- • buffer handle
--- • b:changedtick
@@ -168,7 +169,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
---
--- • on_bytes: Lua callback invoked on change. This
--- callback receives more granular information about the
---- change compared to on_lines. Return `true` to detach. Args:
+--- change compared to on_lines. Return `true` to
+--- detach. Args:
--- • the string "bytes"
--- • buffer handle
--- • b:changedtick
@@ -530,7 +532,8 @@ function vim.api.nvim_buf_line_count(buffer) end
--- wrapped lines.
--- • hl_mode : control how highlights are combined with the
--- highlights of the text. Currently only affects virt_text
---- highlights, but might affect `hl_group` in later versions.
+--- highlights, but might affect `hl_group` in
+--- later versions.
--- • "replace": only show the virt_text color. This is the
--- default.
--- • "combine": combine with background text color.
@@ -740,7 +743,8 @@ function vim.api.nvim_chan_send(chan, data) end
--- • NOTE: Cannot be used with {pattern}
---
--- • group: (string|int) The augroup name or id.
---- • NOTE: If not passed, will only delete autocmds not in any group.
+--- • NOTE: If not passed, will only delete autocmds not in any
+--- group.
function vim.api.nvim_clear_autocmds(opts) end
--- Executes an Ex command.
@@ -808,7 +812,8 @@ function vim.api.nvim_complete_set(index, opts) end
--- @return integer
function vim.api.nvim_create_augroup(name, opts) end
---- Creates an `autocommand` event handler, defined by `callback` (Lua function or Vimscript function name string) or `command` (Ex command string).
+--- Creates an `autocommand` event handler, defined by `callback` (Lua function
+--- or Vimscript function name string) or `command` (Ex command string).
--- Example using Lua callback:
---
--- ```lua
@@ -1525,8 +1530,8 @@ function vim.api.nvim_open_term(buffer, opts) end
--- • height: Window height (in character cells). Minimum of 1.
--- • bufpos: Places float relative to buffer text (only when
--- relative="win"). Takes a tuple of zero-indexed [line,
---- column]. `row` and `col` if given are applied relative to this position, else they
---- default to:
+--- column]. `row` and `col` if given are
+--- applied relative to this position, else they default to:
--- • `row=1` and `col=0` if `anchor` is "NW" or "NE"
--- • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus
--- like a tooltip near the buffer text).
@@ -1541,8 +1546,9 @@ function vim.api.nvim_open_term(buffer, opts) end
--- • external: GUI should display the window as an external
--- top-level window. Currently accepts no other positioning
--- configuration together with this.
---- • zindex: Stacking order. floats with higher `zindex` go on top on floats with lower indices. Must be larger
---- than zero. The following screen elements have hard-coded
+--- • zindex: Stacking order. floats with higher `zindex` go on
+--- top on floats with lower indices. Must be larger than
+--- zero. The following screen elements have hard-coded
--- z-indices:
--- • 100: insert completion popupmenu
--- • 200: message scrollback
@@ -1661,7 +1667,8 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end
--- @param data string Multiline input. May be binary (containing NUL bytes).
--- @param crlf boolean Also break lines at CR and CRLF.
--- @param phase integer -1: paste in a single call (i.e. without streaming). To
---- "stream" a paste, call `nvim_paste` sequentially with these `phase` values:
+--- "stream" a paste, call `nvim_paste` sequentially
+--- with these `phase` values:
--- • 1: starts the paste (exactly once)
--- • 2: continues the paste (zero or more times)
--- • 3: ends the paste (exactly once)
diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua
index e3b89aeff7..ca87fb9d15 100644
--- a/runtime/lua/vim/_meta/vvars.lua
+++ b/runtime/lua/vim/_meta/vvars.lua
@@ -687,11 +687,18 @@ vim.v.t_number = ...
--- @type integer
vim.v.t_string = ...
---- The value of the most recent OSC or DCS escape sequence
+--- The value of the most recent OSC or DCS control sequence
+--- sent from a process running in the embedded `terminal`.
+--- This can be read in a `TermRequest` event handler to respond
+--- to queries from embedded applications.
+--- @type string
+vim.v.termrequest = ...
+
+--- The value of the most recent OSC or DCS control sequence
--- received by Nvim from the terminal. This can be read in a
--- `TermResponse` event handler after querying the terminal using
--- another escape sequence.
---- @type any
+--- @type string
vim.v.termresponse = ...
--- Must be set before using `test_garbagecollect_now()`.
diff --git a/runtime/lua/vim/_system.lua b/runtime/lua/vim/_system.lua
index 9279febddf..9e935b7e95 100644
--- a/runtime/lua/vim/_system.lua
+++ b/runtime/lua/vim/_system.lua
@@ -1,6 +1,6 @@
local uv = vim.uv
---- @class SystemOpts
+--- @class vim.SystemOpts
--- @field stdin? string|string[]|true
--- @field stdout? fun(err:string?, data: string?)|false
--- @field stderr? fun(err:string?, data: string?)|false
@@ -302,7 +302,7 @@ end
--- Run a system command
---
--- @param cmd string[]
---- @param opts? SystemOpts
+--- @param opts? vim.SystemOpts
--- @param on_exit? fun(out: vim.SystemCompleted)
--- @return vim.SystemObj
function M.run(cmd, opts, on_exit)
diff --git a/runtime/lua/vim/filetype.lua b/runtime/lua/vim/filetype.lua
index 9141b1e4c6..8cd5f19569 100644
--- a/runtime/lua/vim/filetype.lua
+++ b/runtime/lua/vim/filetype.lua
@@ -2165,7 +2165,7 @@ end
--- }
--- ```
---
----@param filetypes vim.filetype.add.filetypes A table containing new filetype maps (see example).
+---@param filetypes vim.filetype.add.filetypes (table) A table containing new filetype maps (see example).
function M.add(filetypes)
for k, v in pairs(filetypes.extension or {}) do
extension[k] = v
@@ -2300,7 +2300,7 @@ end
--- vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
--- ```
---
----@param args vim.filetype.match.args Table specifying which matching strategy to use.
+---@param args vim.filetype.match.args (table) Table specifying which matching strategy to use.
--- Accepted keys are:
--- * buf (number): Buffer number to use for matching. Mutually exclusive with
--- {contents}
diff --git a/runtime/lua/vim/health.lua b/runtime/lua/vim/health.lua
index d9265f6bd6..f6f7abef8f 100644
--- a/runtime/lua/vim/health.lua
+++ b/runtime/lua/vim/health.lua
@@ -315,7 +315,7 @@ end
--- Run a system command and timeout after 30 seconds.
---
--- @param cmd table List of command arguments to execute
---- @param args ?table Optional arguments:
+--- @param args? table Optional arguments:
--- - stdin (string): Data to write to the job's stdin
--- - stderr (boolean): Append stderr to stdout
--- - ignore_error (boolean): If true, ignore error output
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index b658dde099..a63d5ba565 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -112,6 +112,35 @@ local function sanitize(t)
return t
end
+--- Flattens a single list-like table. Errors if it attempts to flatten a
+--- dict-like table
+---@param v table table which should be flattened
+---@param max_depth number depth to which the table should be flattened
+---@param depth number current iteration depth
+---@param result table output table that contains flattened result
+---@return table|nil flattened table if it can be flattened, otherwise nil
+local function flatten(v, max_depth, depth, result)
+ if depth < max_depth and type(v) == 'table' then
+ local i = 0
+ for _ in pairs(v) do
+ i = i + 1
+
+ if v[i] == nil then
+ -- short-circuit: this is not a list like table
+ return nil
+ end
+
+ if flatten(v[i], max_depth, depth + 1, result) == nil then
+ return nil
+ end
+ end
+ else
+ result[#result + 1] = v
+ end
+
+ return result
+end
+
--- Determine if the current iterator stage should continue.
---
--- If any arguments are passed to this function, then return those arguments
@@ -152,9 +181,9 @@ end
--- local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded)
--- ```
---
----@param f function(...):bool Takes all values returned from the previous stage
---- in the pipeline and returns false or nil if the
---- current iterator element should be removed.
+---@param f fun(...):bool Takes all values returned from the previous stage
+--- in the pipeline and returns false or nil if the
+--- current iterator element should be removed.
---@return Iter
function Iter.filter(self, f)
return self:map(function(...)
@@ -179,6 +208,54 @@ function ListIter.filter(self, f)
return self
end
+--- Flattens a |list-iterator|, un-nesting nested values up to the given {depth}.
+--- Errors if it attempts to flatten a dict-like value.
+---
+--- Examples:
+---
+--- ```lua
+--- vim.iter({ 1, { 2 }, { { 3 } } }):flatten():totable()
+--- -- { 1, 2, { 3 } }
+---
+--- vim.iter({1, { { a = 2 } }, { 3 } }):flatten():totable()
+--- -- { 1, { a = 2 }, 3 }
+---
+--- vim.iter({ 1, { { a = 2 } }, { 3 } }):flatten(math.huge):totable()
+--- -- error: attempt to flatten a dict-like table
+--- ```
+---
+---@param depth? number Depth to which |list-iterator| should be flattened
+--- (defaults to 1)
+---@return Iter
+function Iter.flatten(self, depth) -- luacheck: no unused args
+ error('flatten() requires a list-like table')
+end
+
+---@private
+function ListIter.flatten(self, depth)
+ depth = depth or 1
+ local inc = self._head < self._tail and 1 or -1
+ local target = {}
+
+ for i = self._head, self._tail - inc, inc do
+ local flattened = flatten(self._table[i], depth, 0, {})
+
+ -- exit early if we try to flatten a dict-like table
+ if flattened == nil then
+ error('flatten() requires a list-like table')
+ end
+
+ for _, v in pairs(flattened) do
+ target[#target + 1] = v
+ end
+ end
+
+ self._head = 1
+ self._tail = #target + 1
+ self._table = target
+ return self
+end
+
--- Maps the items of an iterator pipeline to the values returned by `f`.
---
--- If the map function returns nil, the value is filtered from the iterator.
@@ -195,11 +272,11 @@ end
--- -- { 6, 12 }
--- ```
---
----@param f function(...):any Mapping function. Takes all values returned from
---- the previous stage in the pipeline as arguments
---- and returns one or more new values, which are used
---- in the next pipeline stage. Nil return values
---- are filtered from the output.
+---@param f fun(...):any Mapping function. Takes all values returned from
+--- the previous stage in the pipeline as arguments
+--- and returns one or more new values, which are used
+--- in the next pipeline stage. Nil return values
+--- are filtered from the output.
---@return Iter
function Iter.map(self, f)
-- Implementation note: the reader may be forgiven for observing that this
@@ -263,9 +340,9 @@ end
---
--- For functions with side effects. To modify the values in the iterator, use |Iter:map()|.
---
----@param f function(...) Function to execute for each item in the pipeline.
---- Takes all of the values returned by the previous stage
---- in the pipeline as arguments.
+---@param f fun(...) Function to execute for each item in the pipeline.
+--- Takes all of the values returned by the previous stage
+--- in the pipeline as arguments.
function Iter.each(self, f)
local function fn(...)
if select(1, ...) ~= nil then
@@ -387,7 +464,7 @@ end
---@generic A
---
---@param init A Initial value of the accumulator.
----@param f function(acc:A, ...):A Accumulation function.
+---@param f fun(acc:A, ...):A Accumulation function.
---@return A
function Iter.fold(self, init, f)
local acc = init
@@ -461,9 +538,8 @@ end
--- ```
---
---@return Iter
-function Iter.rev(self)
+function Iter.rev(self) -- luacheck: no unused args
error('rev() requires a list-like table')
- return self
end
---@private
@@ -733,7 +809,6 @@ end
---@diagnostic disable-next-line: unused-local
function Iter.skipback(self, n) -- luacheck: no unused args
error('skipback() requires a list-like table')
- return self
end
---@private
@@ -800,7 +875,6 @@ end
---@diagnostic disable-next-line: unused-local
function Iter.slice(self, first, last) -- luacheck: no unused args
error('slice() requires a list-like table')
- return self
end
---@private
@@ -810,9 +884,9 @@ end
--- Returns true if any of the items in the iterator match the given predicate.
---
----@param pred function(...):bool Predicate function. Takes all values returned from the previous
---- stage in the pipeline as arguments and returns true if the
---- predicate matches.
+---@param pred fun(...):bool Predicate function. Takes all values returned from the previous
+--- stage in the pipeline as arguments and returns true if the
+--- predicate matches.
function Iter.any(self, pred)
local any = false
@@ -834,9 +908,9 @@ end
--- Returns true if all items in the iterator match the given predicate.
---
----@param pred function(...):bool Predicate function. Takes all values returned from the previous
---- stage in the pipeline as arguments and returns true if the
---- predicate matches.
+---@param pred fun(...):bool Predicate function. Takes all values returned from the previous
+--- stage in the pipeline as arguments and returns true if the
+--- predicate matches.
function Iter.all(self, pred)
local all = true
@@ -1032,9 +1106,9 @@ end
---
---@see |Iter:filter()|
---
----@param f function(...):bool Filter function. Accepts the current iterator or table values as
---- arguments and returns true if those values should be kept in the
---- final table
+---@param f fun(...):bool Filter function. Accepts the current iterator or table values as
+--- arguments and returns true if those values should be kept in the
+--- final table
---@param src table|function Table or iterator function to filter
---@return table
function M.filter(f, src, ...)
@@ -1050,9 +1124,9 @@ end
---
---@see |Iter:map()|
---
----@param f function(...):?any Map function. Accepts the current iterator or table values as
---- arguments and returns one or more new values. Nil values are removed
---- from the final table.
+---@param f fun(...): any? Map function. Accepts the current iterator or table values as
+--- arguments and returns one or more new values. Nil values are removed
+--- from the final table.
---@param src table|function Table or iterator function to filter
---@return table
function M.map(f, src, ...)
diff --git a/runtime/lua/vim/lsp/handlers.lua b/runtime/lua/vim/lsp/handlers.lua
index c03a17fa59..daf09b6430 100644
--- a/runtime/lua/vim/lsp/handlers.lua
+++ b/runtime/lua/vim/lsp/handlers.lua
@@ -516,7 +516,7 @@ end
---
--- Displays call hierarchy in the quickfix window.
---
----@param direction `"from"` for incoming calls and `"to"` for outgoing calls
+---@param direction 'from'|'to' `"from"` for incoming calls and `"to"` for outgoing calls
---@return function
--- `CallHierarchyIncomingCall[]` if {direction} is `"from"`,
--- `CallHierarchyOutgoingCall[]` if {direction} is `"to"`,
diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua
index 44465f6cff..a2cc81781a 100644
--- a/runtime/lua/vim/lsp/util.lua
+++ b/runtime/lua/vim/lsp/util.lua
@@ -790,7 +790,7 @@ end
--- Note that if the input is of type `MarkupContent` and its kind is `plaintext`,
--- then the corresponding value is returned without further modifications.
---
----@param input (`MarkedString` | `MarkedString[]` | `MarkupContent`)
+---@param input (lsp.MarkedString | lsp.MarkedString[] | lsp.MarkupContent)
---@param contents (table|nil) List of strings to extend with converted lines. Defaults to {}.
---@return string[] extended with lines of converted markdown.
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
@@ -2115,8 +2115,8 @@ end
--- Returns the UTF-32 and UTF-16 offsets for a position in a certain buffer.
---
---@param buf integer buffer number (0 for current)
----@param row 0-indexed line
----@param col 0-indexed byte offset in line
+---@param row integer 0-indexed line
+---@param col integer 0-indexed byte offset in line
---@param offset_encoding string utf-8|utf-16|utf-32 defaults to `offset_encoding` of first client of `buf`
---@return integer `offset_encoding` index of the character in line {row} column {col} in buffer {buf}
function M.character_offset(buf, row, col, offset_encoding)
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 24bc97bf8e..e76d148b1b 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -875,7 +875,7 @@ end
--- a.b.c = 1
--- ```
---
----@param createfn function?(key:any):any Provides the value for a missing `key`.
+---@param createfn? fun(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(_)
diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua
index 8cbbffcd60..cc8fe319e8 100644
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -793,7 +793,7 @@ end
--- of the query file, e.g., if the path ends in `/lua/highlights.scm`, the parser for the
--- `lua` language will be used.
---@param buf (integer) Buffer handle
----@param opts (QueryLinterOpts|nil) Optional keyword arguments:
+---@param opts? QueryLinterOpts (table) Optional keyword arguments:
--- - langs (string|string[]|nil) Language(s) to use for checking the query.
--- If multiple languages are specified, queries are validated for all of them
--- - clear (boolean) if `true`, just clear current lint errors
generated by cgit (git 2.34.1) at 2025-08-02 06:13:20 +0000