diff options
Diffstat (limited to 'runtime/lua/vim/_meta')
| -rw-r--r-- | runtime/lua/vim/_meta/api.lua | 206 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/api_keysets.lua | 102 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/api_keysets_extra.lua | 66 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/builtin.lua | 5 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/json.lua | 15 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/options.lua | 209 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/vimfn.lua | 315 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/vvars.lua | 34 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/vvars_extra.lua | 77 |
9 files changed, 643 insertions, 386 deletions
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 3c9b9d4f44..3d10729d23 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -3,6 +3,10 @@ -- DO NOT EDIT error('Cannot require a meta file') +--- This file embeds vimdoc as the function descriptions +--- so ignore any doc related errors. +--- @diagnostic disable: undefined-doc-name,luadoc-miss-symbol + vim.api = {} --- @private @@ -163,35 +167,14 @@ function vim.api.nvim__stats() end --- @return any function vim.api.nvim__unpack(str) end ---- Adds a highlight to buffer. ---- ---- Useful for plugins that dynamically generate highlights to a buffer ---- (like a semantic highlighter or linter). The function adds a single ---- highlight to a buffer. Unlike `matchaddpos()` highlights follow changes to ---- line numbering (as lines are inserted/removed above the highlighted line), ---- like signs and marks do. ---- ---- Namespaces are used for batch deletion/updating of a set of highlights. To ---- create a namespace, use `nvim_create_namespace()` which returns a namespace ---- id. Pass it in to this function as `ns_id` to add highlights to the ---- namespace. All highlights in the same namespace can then be cleared with ---- single call to `nvim_buf_clear_namespace()`. If the highlight never will be ---- deleted by an API call, pass `ns_id = -1`. ---- ---- As a shorthand, `ns_id = 0` can be used to create a new namespace for the ---- highlight, the allocated id is then returned. If `hl_group` is the empty ---- string no highlight is added, but a new `ns_id` is still returned. This is ---- supported for backwards compatibility, new code should use ---- `nvim_create_namespace()` to create a new empty namespace. ---- ---- @param buffer integer Buffer handle, or 0 for current buffer ---- @param ns_id integer namespace to use or -1 for ungrouped highlight ---- @param hl_group string Name of the highlight group to use ---- @param line integer Line to highlight (zero-indexed) ---- @param col_start integer Start of (byte-indexed) column range to highlight ---- @param col_end integer End of (byte-indexed) column range to highlight, ---- or -1 to highlight to end of line ---- @return integer # The ns_id that was used +--- @deprecated +--- @param buffer integer +--- @param ns_id integer +--- @param hl_group string +--- @param line integer +--- @param col_start integer +--- @param col_end integer +--- @return integer function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start, col_end) end --- Activates buffer-update events on a channel, or as Lua callbacks. @@ -272,12 +255,12 @@ function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end --- This temporarily switches current buffer to "buffer". --- If the current window already shows "buffer", the window is not switched. --- If a window inside the current tabpage (including a float) already shows the ---- buffer, then one of these windows will be set as current window temporarily. +--- buffer, then one of those windows will be set as current window temporarily. --- Otherwise a temporary scratch window (called the "autocmd window" for --- historical reasons) will be used. --- --- This is useful e.g. to call Vimscript functions that only work with the ---- current buffer/window currently, like `termopen()`. +--- current buffer/window currently, like `jobstart(…, {'term': v:true})`. --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param fun function Function to call inside the buffer (currently Lua callable @@ -452,7 +435,7 @@ function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param mode string Mode short-name ("n", "i", "v", ...) ---- @return vim.api.keyset.keymap[] # Array of |maparg()|-like dictionaries describing mappings. +--- @return vim.api.keyset.get_keymap[] # Array of |maparg()|-like dictionaries describing mappings. --- The "buffer" key holds the associated buffer handle. function vim.api.nvim_buf_get_keymap(buffer, mode) end @@ -595,6 +578,9 @@ function vim.api.nvim_buf_line_count(buffer) end --- - hl_group : highlight group used for the text range. This and below --- highlight groups can be supplied either as a string or as an integer, --- the latter of which can be obtained using `nvim_get_hl_id_by_name()`. +--- +--- Multiple highlight groups can be stacked by passing an array (highest +--- priority last). --- - hl_eol : when true, for a multiline highlight covering the --- EOL of a line, continue the highlight for the rest --- of the screen line (just like for diff and @@ -607,6 +593,15 @@ function vim.api.nvim_buf_line_count(buffer) end --- (highest priority last). --- - virt_text_pos : position of virtual text. Possible values: --- - "eol": right after eol character (default). +--- - "eol_right_align": display right aligned in the window +--- unless the virtual text is longer than +--- the space available. If the virtual +--- text is too long, it is truncated to +--- fit in the window after the EOL +--- character. If the line is wrapped, the +--- virtual text is shown after the end of +--- the line rather than the previous +--- screen line. --- - "overlay": display over the specified column, without --- shifting the underlying text. --- - "right_align": display right aligned in the window. @@ -885,10 +880,8 @@ function vim.api.nvim_cmd(cmd, opts) end --- --- On execution error: fails with Vimscript error, updates v:errmsg. --- ---- Prefer using `nvim_cmd()` or `nvim_exec2()` over this. To evaluate multiple lines of Vim script ---- or an Ex command directly, use `nvim_exec2()`. To construct an Ex command using a structured ---- format and then execute it, use `nvim_cmd()`. To modify an Ex command before evaluating it, use ---- `nvim_parse_cmd()` in conjunction with `nvim_cmd()`. +--- Prefer `nvim_cmd()` or `nvim_exec2()` instead. To modify an Ex command in a structured way +--- before executing it, modify the result of `nvim_parse_cmd()` then pass it to `nvim_cmd()`. --- --- @param command string Ex command string function vim.api.nvim_command(command) end @@ -963,9 +956,9 @@ function vim.api.nvim_create_augroup(name, opts) end --- - id: (number) autocommand id --- - event: (string) name of the triggered event `autocmd-events` --- - group: (number|nil) autocommand group id, if any ---- - match: (string) expanded value of [<amatch>] ---- - buf: (number) expanded value of [<abuf>] ---- - file: (string) expanded value of [<afile>] +--- - file: (string) [<afile>] (not expanded to a full path) +--- - match: (string) [<amatch>] (expanded to a full path) +--- - buf: (number) [<abuf>] --- - data: (any) arbitrary data passed from [nvim_exec_autocmds()] [event-data]() --- - command (string) optional: Vim command to execute on event. Cannot be used with --- {callback} @@ -989,7 +982,7 @@ function vim.api.nvim_create_buf(listed, scratch) end --- Creates a new namespace or gets an existing one. [namespace]() --- --- Namespaces are used for buffer highlights and virtual text, see ---- `nvim_buf_add_highlight()` and `nvim_buf_set_extmark()`. +--- `nvim_buf_set_extmark()`. --- --- Namespaces can be named or anonymous. If `name` matches an existing --- namespace, the associated id is returned. If `name` is an empty string @@ -1012,7 +1005,7 @@ function vim.api.nvim_create_namespace(name) end --- ``` --- --- @param name string Name of the new user command. Must begin with an uppercase letter. ---- @param command any Replacement command to execute when this user command is executed. When called +--- @param command string|fun(args: vim.api.keyset.create_user_command.command_args) Replacement command to execute when this user command is executed. When called --- from Lua, the command can also be a Lua function. The function is called with a --- single table argument that contains the following keys: --- - name: (string) Command name @@ -1099,29 +1092,28 @@ function vim.api.nvim_del_user_command(name) end --- @param name string Variable name function vim.api.nvim_del_var(name) end ---- Echo a message. +--- Prints a message given by a list of `[text, hl_group]` "chunks". +--- +--- Example: +--- ```lua +--- vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {}) +--- ``` --- ---- @param chunks any[] A list of `[text, hl_group]` arrays, each representing a ---- text chunk with specified highlight group name or ID. ---- `hl_group` element can be omitted for no highlight. +--- @param chunks any[] List of `[text, hl_group]` pairs, where each is a `text` string highlighted by +--- the (optional) name or ID `hl_group`. --- @param history boolean if true, add to `message-history`. --- @param opts vim.api.keyset.echo_opts Optional parameters. ---- - verbose: Message is printed as a result of 'verbose' option. ---- If Nvim was invoked with -V3log_file, the message will be ---- redirected to the log_file and suppressed from direct output. +--- - err: Treat the message like `:echoerr`. Sets `hl_group` to `hl-ErrorMsg` by default. +--- - verbose: Message is controlled by the 'verbose' option. Nvim invoked with `-V3log` +--- will write the message to the "log" file instead of standard output. function vim.api.nvim_echo(chunks, history, opts) end ---- Writes a message to the Vim error buffer. Does not append "\n", the ---- message is buffered (won't display) until a linefeed is written. ---- ---- @param str string Message +--- @deprecated +--- @param str string function vim.api.nvim_err_write(str) end ---- Writes a message to the Vim error buffer. Appends "\n", so the buffer is ---- flushed (and displayed). ---- ---- @see vim.api.nvim_err_write ---- @param str string Message +--- @deprecated +--- @param str string function vim.api.nvim_err_writeln(str) end --- Evaluates a Vimscript `expression`. Dicts and Lists are recursively expanded. @@ -1152,7 +1144,9 @@ function vim.api.nvim_eval(expr) end --- the "highlights" key in {opts} is true. Each element of the array is a --- |Dict| with these keys: --- - start: (number) Byte index (0-based) of first character that uses the highlight. ---- - group: (string) Name of highlight group. +--- - group: (string) Name of highlight group. May be removed in the future, use +--- `groups` instead. +--- - groups: (array) Names of stacked highlight groups (highest priority last). function vim.api.nvim_eval_statusline(str, opts) end --- @deprecated @@ -1256,31 +1250,34 @@ function vim.api.nvim_get_all_options_info() end --- match any combination of them. --- --- @param opts vim.api.keyset.get_autocmds Dict with at least one of the following: ---- - group (string|integer): the autocommand group name or id to match against. ---- - event (string|array): event or events to match against `autocmd-events`. ---- - pattern (string|array): pattern or patterns to match against `autocmd-pattern`. ---- Cannot be used with {buffer} ---- - buffer: Buffer number or list of buffer numbers for buffer local autocommands +--- - buffer: (integer) Buffer number or list of buffer numbers for buffer local autocommands --- `autocmd-buflocal`. Cannot be used with {pattern} +--- - event: (string|table) event or events to match against `autocmd-events`. +--- - id: (integer) Autocommand ID to match. +--- - group: (string|table) the autocommand group name or id to match against. +--- - pattern: (string|table) pattern or patterns to match against `autocmd-pattern`. +--- Cannot be used with {buffer} --- @return vim.api.keyset.get_autocmds.ret[] # Array of autocommands matching the criteria, with each item --- containing the following fields: ---- - id (number): the autocommand id (only when defined with the API). ---- - group (integer): the autocommand group id. ---- - group_name (string): the autocommand group name. ---- - desc (string): the autocommand description. ---- - event (string): the autocommand event. ---- - command (string): the autocommand command. Note: this will be empty if a callback is set. ---- - callback (function|string|nil): Lua function or name of a Vim script function +--- - buffer: (integer) the buffer number. +--- - buflocal: (boolean) true if the autocommand is buffer local. +--- - command: (string) the autocommand command. Note: this will be empty if a callback is set. +--- - callback: (function|string|nil): Lua function or name of a Vim script function --- which is executed when this autocommand is triggered. ---- - once (boolean): whether the autocommand is only run once. ---- - pattern (string): the autocommand pattern. +--- - desc: (string) the autocommand description. +--- - event: (string) the autocommand event. +--- - id: (integer) the autocommand id (only when defined with the API). +--- - group: (integer) the autocommand group id. +--- - group_name: (string) the autocommand group name. +--- - once: (boolean) whether the autocommand is only run once. +--- - pattern: (string) the autocommand pattern. --- If the autocommand is buffer local |autocmd-buffer-local|: ---- - buflocal (boolean): true if the autocommand is buffer local. ---- - buffer (number): the buffer number. function vim.api.nvim_get_autocmds(opts) end --- Gets information about a channel. --- +--- See `nvim_list_uis()` for an example of how to get channel info. +--- --- @param chan integer channel_id, or 0 for current channel --- @return table<string,any> # Channel info dict with these keys: --- - "id" Channel id. @@ -1298,8 +1295,8 @@ function vim.api.nvim_get_autocmds(opts) end --- "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g. --- for conpty on Windows). --- - "buffer" (optional) Buffer connected to |terminal| instance. ---- - "client" (optional) Info about the peer (client on the other end of the RPC channel), ---- which it provided via |nvim_set_client_info()|. +--- - "client" (optional) Info about the peer (client on the other end of the channel), as set +--- by |nvim_set_client_info()|. --- function vim.api.nvim_get_chan_info(chan) end @@ -1416,7 +1413,7 @@ function vim.api.nvim_get_hl_ns(opts) end --- Gets a list of global (non-buffer-local) `mapping` definitions. --- --- @param mode string Mode short-name ("n", "i", "v", ...) ---- @return vim.api.keyset.keymap[] # Array of |maparg()|-like dictionaries describing mappings. +--- @return vim.api.keyset.get_keymap[] # Array of |maparg()|-like dictionaries describing mappings. --- The "buffer" key is always zero. function vim.api.nvim_get_keymap(mode) end @@ -1621,6 +1618,14 @@ function vim.api.nvim_list_tabpages() end --- Gets a list of dictionaries representing attached UIs. --- +--- Example: The Nvim builtin `TUI` sets its channel info as described in `startup-tui`. In +--- particular, it sets `client.name` to "nvim-tui". So you can check if the TUI is running by +--- inspecting the client name of each UI: +--- +--- ```lua +--- vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name) +--- ``` +--- --- @return any[] # Array of UI dictionaries, each with these keys: --- - "height" Requested height of the UI --- - "width" Requested width of the UI @@ -1640,21 +1645,17 @@ function vim.api.nvim_list_wins() end --- @return any function vim.api.nvim_load_context(dict) end ---- Notify the user with a message ---- ---- Relays the call to vim.notify . By default forwards your message in the ---- echo area but can be overridden to trigger desktop notifications. ---- ---- @param msg string Message to display to the user ---- @param log_level integer The log level ---- @param opts table<string,any> Reserved for future use. +--- @deprecated +--- @param msg string +--- @param log_level integer +--- @param opts table<string,any> --- @return any function vim.api.nvim_notify(msg, log_level, opts) end --- Open a terminal instance in a buffer --- --- By default (and currently the only option) the terminal will not be ---- connected to an external process. Instead, input send on the channel +--- connected to an external process. Instead, input sent on the channel --- will be echoed directly by the terminal. This is useful to display --- ANSI terminal sequences returned as part of a rpc message, or similar. --- @@ -1665,6 +1666,19 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- Then `nvim_chan_send()` can be called immediately to process sequences --- in a virtual terminal having the intended size. --- +--- Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you +--- can use Nvim as a "scrollback pager" (for terminals like kitty): [ansi-colorize]() +--- [terminal-scrollback-pager]() +--- +--- ```lua +--- vim.api.nvim_create_user_command('TermHl', function() +--- local b = vim.api.nvim_create_buf(false, true) +--- local chan = vim.api.nvim_open_term(b, {}) +--- vim.api.nvim_chan_send(chan, table.concat(vim.api.nvim_buf_get_lines(0, 0, -1, false), '\n')) +--- vim.api.nvim_win_set_buf(0, b) +--- end, { desc = 'Highlights ANSI termcodes in curbuf' }) +--- ``` +--- --- @param buffer integer the buffer to use (expected to be empty) --- @param opts vim.api.keyset.open_term Optional parameters. --- - on_input: Lua callback for input sent, i e keypresses in terminal @@ -1738,10 +1752,12 @@ function vim.api.nvim_open_term(buffer, opts) end --- @param config vim.api.keyset.win_config Map defining the window configuration. Keys: --- - relative: Sets the window layout to "floating", placed at (row,col) --- coordinates relative to: ---- - "editor" The global editor grid ---- - "win" Window given by the `win` field, or current window. ---- - "cursor" Cursor position in current window. ---- - "mouse" Mouse position +--- - "cursor" Cursor position in current window. +--- - "editor" The global editor grid. +--- - "laststatus" 'laststatus' if present, or last row. +--- - "mouse" Mouse position. +--- - "tabline" Tabline if present, or first row. +--- - "win" Window given by the `win` field, or current window. --- - win: `window-ID` window to split, or relative window when creating a --- float (relative="win"). --- - anchor: Decides which corner of the float to place at (row,col): @@ -1849,10 +1865,8 @@ function vim.api.nvim_open_term(buffer, opts) end --- @return integer # Window handle, or 0 on error function vim.api.nvim_open_win(buffer, enter, config) end ---- Writes a message to the Vim output buffer. Does not append "\n", the ---- message is buffered (won't display) until a linefeed is written. ---- ---- @param str string Message +--- @deprecated +--- @param str string function vim.api.nvim_out_write(str) end --- Parse command line. @@ -2124,8 +2138,8 @@ function vim.api.nvim_set_current_win(window) end --- ``` --- ["start", tick] --- ``` ---- - on_buf: called for each buffer being redrawn (before ---- window callbacks) +--- - on_buf: called for each buffer being redrawn (once per edit, +--- before window callbacks) --- ``` --- ["buf", bufnr, tick] --- ``` diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index bf184dee2d..4d0665872b 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -4,11 +4,11 @@ error('Cannot require a meta file') --- @class vim.api.keyset.buf_attach ---- @field on_lines? function ---- @field on_bytes? function ---- @field on_changedtick? function ---- @field on_detach? function ---- @field on_reload? function +--- @field on_lines? fun(_: "lines", bufnr: integer, changedtick: integer, first: integer, last_old: integer, last_new: integer, byte_count: integer, deleted_codepoints?: integer, deleted_codeunits?: integer): boolean? +--- @field on_bytes? fun(_: "bytes", bufnr: integer, changedtick: integer, start_row: integer, start_col: integer, start_byte: integer, old_end_row: integer, old_end_col: integer, old_end_byte: integer, new_end_row: integer, new_end_col: integer, new_end_byte: integer): boolean? +--- @field on_changedtick? fun(_: "changedtick", bufnr: integer, changedtick: integer) +--- @field on_detach? fun(_: "detach", bufnr: integer) +--- @field on_reload? fun(_: "reload", bufnr: integer) --- @field utf_sizes? boolean --- @field preview? boolean @@ -18,9 +18,9 @@ error('Cannot require a meta file') --- @class vim.api.keyset.clear_autocmds --- @field buffer? integer ---- @field event? any ---- @field group? any ---- @field pattern? any +--- @field event? string|string[] +--- @field group? integer|string +--- @field pattern? string|string[] --- @class vim.api.keyset.cmd --- @field cmd? string @@ -28,12 +28,12 @@ error('Cannot require a meta file') --- @field count? integer --- @field reg? string --- @field bang? boolean ---- @field args? any[] +--- @field args? string[] --- @field magic? table<string,any> --- @field mods? table<string,any> ---- @field nargs? any ---- @field addr? any ---- @field nextcmd? any +--- @field nargs? integer|string +--- @field addr? string +--- @field nextcmd? string --- @class vim.api.keyset.cmd_magic --- @field file? boolean @@ -72,22 +72,23 @@ error('Cannot require a meta file') --- @field info? string --- @class vim.api.keyset.context ---- @field types? any[] +--- @field types? string[] --- @class vim.api.keyset.create_augroup ---- @field clear? any +--- @field clear? boolean --- @class vim.api.keyset.create_autocmd --- @field buffer? integer ---- @field callback? any +--- @field callback? string|(fun(args: vim.api.keyset.create_autocmd.callback_args): boolean?) --- @field command? string --- @field desc? string ---- @field group? any +--- @field group? integer|string --- @field nested? boolean --- @field once? boolean ---- @field pattern? any +--- @field pattern? string|string[] --- @class vim.api.keyset.echo_opts +--- @field err? boolean --- @field verbose? boolean --- @class vim.api.keyset.empty @@ -103,19 +104,20 @@ error('Cannot require a meta file') --- @class vim.api.keyset.exec_autocmds --- @field buffer? integer ---- @field group? any +--- @field group? integer|string --- @field modeline? boolean ---- @field pattern? any +--- @field pattern? string|string[] --- @field data? any --- @class vim.api.keyset.exec_opts --- @field output? boolean --- @class vim.api.keyset.get_autocmds ---- @field event? any ---- @field group? any ---- @field pattern? any ---- @field buffer? any +--- @field event? string|string[] +--- @field group? integer|string +--- @field pattern? string|string[] +--- @field buffer? integer|integer[] +--- @field id? integer --- @class vim.api.keyset.get_commands --- @field builtin? boolean @@ -154,17 +156,17 @@ error('Cannot require a meta file') --- @field altfont? boolean --- @field nocombine? boolean --- @field default? boolean ---- @field cterm? any ---- @field foreground? any ---- @field fg? any ---- @field background? any ---- @field bg? any ---- @field ctermfg? any ---- @field ctermbg? any ---- @field special? any ---- @field sp? any ---- @field link? any ---- @field global_link? any +--- @field cterm? integer|string +--- @field foreground? integer|string +--- @field fg? integer|string +--- @field background? integer|string +--- @field bg? integer|string +--- @field ctermfg? integer|string +--- @field ctermbg? integer|string +--- @field special? integer|string +--- @field sp? integer|string +--- @field link? integer|string +--- @field global_link? integer|string --- @field fallback? boolean --- @field blend? integer --- @field fg_indexed? boolean @@ -201,7 +203,7 @@ error('Cannot require a meta file') --- @field wins? any[] --- @class vim.api.keyset.open_term ---- @field on_input? function +--- @field on_input? fun(_: "input", term: integer, bufnr: integer, data: any) --- @field force_crlf? boolean --- @class vim.api.keyset.option @@ -227,20 +229,20 @@ error('Cannot require a meta file') --- @field do_source? boolean --- @class vim.api.keyset.set_decoration_provider ---- @field on_start? function ---- @field on_buf? function ---- @field on_win? function ---- @field on_line? function ---- @field on_end? function ---- @field _on_hl_def? function ---- @field _on_spell_nav? function +--- @field on_start? fun(_: "start", tick: integer): boolean? +--- @field on_buf? fun(_: "buf", bufnr: integer, tick: integer) +--- @field on_win? fun(_: "win", winid: integer, bufnr: integer, toprow: integer, botrow: integer): boolean? +--- @field on_line? fun(_: "line", winid: integer, bufnr: integer, row: integer): boolean? +--- @field on_end? fun(_: "end", tick: integer) +--- @field _on_hl_def? fun(_: "hl_def") +--- @field _on_spell_nav? fun(_: "spell_nav") --- @class vim.api.keyset.set_extmark --- @field id? integer --- @field end_line? integer --- @field end_row? integer --- @field end_col? integer ---- @field hl_group? number|string +--- @field hl_group? any --- @field virt_text? any[] --- @field virt_text_pos? string --- @field virt_text_win_col? integer @@ -258,10 +260,10 @@ error('Cannot require a meta file') --- @field virt_lines_leftcol? boolean --- @field strict? boolean --- @field sign_text? string ---- @field sign_hl_group? number|string ---- @field number_hl_group? number|string ---- @field line_hl_group? number|string ---- @field cursorline_hl_group? number|string +--- @field sign_hl_group? integer|string +--- @field number_hl_group? integer|string +--- @field line_hl_group? integer|string +--- @field cursorline_hl_group? integer|string --- @field conceal? string --- @field spell? boolean --- @field ui_watched? boolean @@ -292,7 +294,7 @@ error('Cannot require a meta file') --- @field relative? string --- @field split? string --- @field win? integer ---- @field bufpos? any[] +--- @field bufpos? integer[] --- @field external? boolean --- @field focusable? boolean --- @field mouse? boolean @@ -315,12 +317,12 @@ error('Cannot require a meta file') --- @field end_vcol? integer --- @class vim.api.keyset.xdl_diff ---- @field on_hunk? function +--- @field on_hunk? fun(start_a: integer, count_a: integer, start_b: integer, count_b: integer): integer? --- @field result_type? string --- @field algorithm? string --- @field ctxlen? integer --- @field interhunkctxlen? integer ---- @field linematch? any +--- @field linematch? boolean|integer --- @field ignore_whitespace? boolean --- @field ignore_whitespace_change? boolean --- @field ignore_whitespace_change_at_eol? boolean diff --git a/runtime/lua/vim/_meta/api_keysets_extra.lua b/runtime/lua/vim/_meta/api_keysets_extra.lua index 81bce50746..fbef6fa3bc 100644 --- a/runtime/lua/vim/_meta/api_keysets_extra.lua +++ b/runtime/lua/vim/_meta/api_keysets_extra.lua @@ -73,6 +73,51 @@ error('Cannot require a meta file') --- @field buflocal? boolean --- @field buffer? integer +--- @class vim.api.keyset.create_autocmd.callback_args +--- @field id integer autocommand id +--- @field event string name of the triggered event |autocmd-events| +--- @field group? integer autocommand group id, if any +--- @field match string expanded value of <amatch> +--- @field buf integer expanded value of <abuf> +--- @field file string expanded value of <afile> +--- @field data? any arbitrary data passed from |nvim_exec_autocmds()| *event-data* + +--- @class vim.api.keyset.create_user_command.command_args +--- @field name string Command name +--- +--- The args passed to the command, if any <args> +--- @field args string +--- +--- The args split by unescaped whitespace +--- (when more than one argument is allowed), if any <f-args> +--- @field fargs string[] +--- +--- Number of arguments |:command-nargs| +--- @field nargs string +--- +--- "true" if the command was executed with a ! modifier <bang> +--- @field bang boolean +--- +--- The starting line of the command range <line1> +--- @field line1 integer +--- +--- The final line of the command range <line2> +--- @field line2 integer +--- +--- The number of items in the command range: 0, 1, or 2 <range> +--- @field range integer +--- +--- Any count supplied <count> +--- @field count integer +--- The optional register, if specified <reg> +--- @field reg string +--- Command modifiers, if any <mods> +--- @field mods string +--- +--- Command modifiers in a structured format. Has the same structure as the +--- "mods" key of |nvim_parse_cmd()|. +--- @field smods table + --- @class vim.api.keyset.command_info --- @field name string --- @field definition string @@ -114,6 +159,7 @@ error('Cannot require a meta file') --- @field bg? integer --- @field sp? integer --- @field default? true +--- @field link? string --- @field blend? integer --- @field cterm? vim.api.keyset.hl_info.cterm @@ -127,6 +173,26 @@ error('Cannot require a meta file') --- @field force? true --- @field cterm? vim.api.keyset.hl_info.cterm +--- @class vim.api.keyset.get_keymap +--- @field abbr? 0|1 +--- @field buffer? 0|1 +--- @field callback? function +--- @field desc? string +--- @field expr? 0|1 +--- @field lhs? string +--- @field lhsraw? string +--- @field lhsrawalt? string +--- @field lnum? integer +--- @field mode? string +--- @field mode_bits? integer +--- @field noremap? 0|1 +--- @field nowait? 0|1 +--- @field rhs? string +--- @field script? 0|1 +--- @field scriptversion? integer +--- @field sid? integer +--- @field silent? 0|1 + --- @class vim.api.keyset.get_mode --- @field blocking boolean --- @field mode string diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua index b8779b66fe..9fa2e242c4 100644 --- a/runtime/lua/vim/_meta/builtin.lua +++ b/runtime/lua/vim/_meta/builtin.lua @@ -233,9 +233,8 @@ function vim.wait(time, callback, interval, fast_only) end --- {callback} receives event name plus additional parameters. See |ui-popupmenu| --- and the sections below for event format for respective events. --- ---- Callbacks for `msg_show` events are executed in |api-fast| context unless ---- Nvim will wait for input, in which case messages should be shown ---- immediately. +--- Callbacks for `msg_show` events are executed in |api-fast| context; showing +--- the message should be scheduled. --- --- Excessive errors inside the callback will result in forced detachment. --- diff --git a/runtime/lua/vim/_meta/json.lua b/runtime/lua/vim/_meta/json.lua index 07d89aafc8..0d59de5fa6 100644 --- a/runtime/lua/vim/_meta/json.lua +++ b/runtime/lua/vim/_meta/json.lua @@ -25,15 +25,18 @@ vim.json = {} --- ---@param str string Stringified JSON data. ---@param opts? table<string,any> Options table with keys: ---- - luanil: (table) Table with keys: ---- * object: (boolean) When true, converts `null` in JSON objects ---- to Lua `nil` instead of |vim.NIL|. ---- * array: (boolean) When true, converts `null` in JSON arrays ---- to Lua `nil` instead of |vim.NIL|. +--- - luanil: (table) Table with keys: +--- - object: (boolean) When true, converts `null` in JSON objects +--- to Lua `nil` instead of |vim.NIL|. +--- - array: (boolean) When true, converts `null` in JSON arrays +--- to Lua `nil` instead of |vim.NIL|. ---@return any function vim.json.decode(str, opts) end --- Encodes (or "packs") Lua object {obj} as JSON in a Lua string. ---@param obj any +---@param opts? table<string,any> Options table with keys: +--- - escape_slash: (boolean) (default false) Escape slash +--- characters "/" in string values. ---@return string -function vim.json.encode(obj) end +function vim.json.encode(obj, opts) end diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index cb783720ac..52c556867f 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -52,7 +52,7 @@ vim.go.ari = vim.go.allowrevins --- set to one of CJK locales. See Unicode Standard Annex #11 --- (https://www.unicode.org/reports/tr11). --- ---- @type string +--- @type 'single'|'double' vim.o.ambiwidth = "single" vim.o.ambw = vim.o.ambiwidth vim.go.ambiwidth = vim.o.ambiwidth @@ -208,7 +208,7 @@ vim.go.awa = vim.go.autowriteall --- will change. To use other settings, place ":highlight" commands AFTER --- the setting of the 'background' option. --- ---- @type string +--- @type 'light'|'dark' vim.o.background = "dark" vim.o.bg = vim.o.background vim.go.background = vim.o.background @@ -595,7 +595,7 @@ vim.wo.briopt = vim.wo.breakindentopt --- This option is used together with 'buftype' and 'swapfile' to specify --- special kinds of buffers. See `special-buffers`. --- ---- @type string +--- @type ''|'hide'|'unload'|'delete'|'wipe' vim.o.bufhidden = "" vim.o.bh = vim.o.bufhidden vim.bo.bufhidden = vim.o.bufhidden @@ -658,7 +658,7 @@ vim.bo.bl = vim.bo.buflisted --- without saving. For writing there must be matching `BufWriteCmd|, --- |FileWriteCmd` or `FileAppendCmd` autocommands. --- ---- @type string +--- @type ''|'acwrite'|'help'|'nofile'|'nowrite'|'quickfix'|'terminal'|'prompt' vim.o.buftype = "" vim.o.bt = vim.o.buftype vim.bo.buftype = vim.o.buftype @@ -1086,9 +1086,9 @@ vim.go.cia = vim.go.completeitemalign --- a match from the menu. Only works in combination with --- "menu" or "menuone". No effect if "longest" is present. --- ---- noselect Do not select a match in the menu, force the user to ---- select one from the menu. Only works in combination with ---- "menu" or "menuone". +--- noselect Same as "noinsert", except that no menu item is +--- pre-selected. If both "noinsert" and "noselect" are +--- present, "noselect" has precedence. --- --- fuzzy Enable `fuzzy-matching` for completion candidates. This --- allows for more flexible and intuitive matching, where @@ -1098,6 +1098,16 @@ vim.go.cia = vim.go.completeitemalign --- list of alternatives, but not how the candidates are --- collected (using different completion types). --- +--- nosort Disable sorting of completion candidates based on fuzzy +--- scores when "fuzzy" is enabled. Candidates will appear +--- in their original order. +--- +--- preinsert +--- Preinsert the portion of the first candidate word that is +--- not part of the current completion leader and using the +--- `hl-ComplMatchIns` highlight group. Does not work when +--- "fuzzy" is also included. +--- --- @type string vim.o.completeopt = "menu,preview" vim.o.cot = vim.o.completeopt @@ -1118,7 +1128,7 @@ vim.go.cot = vim.go.completeopt --- For Insert mode completion the buffer-local value is used. For --- command line completion the global value is used. --- ---- @type string +--- @type ''|'slash'|'backslash' vim.o.completeslash = "" vim.o.csl = vim.o.completeslash vim.bo.completeslash = vim.o.completeslash @@ -1621,11 +1631,20 @@ vim.go.dex = vim.go.diffexpr --- Option settings for diff mode. It can consist of the following items. --- All are optional. Items must be separated by a comma. --- ---- filler Show filler lines, to keep the text ---- synchronized with a window that has inserted ---- lines at the same position. Mostly useful ---- when windows are side-by-side and 'scrollbind' ---- is set. +--- algorithm:{text} Use the specified diff algorithm with the +--- internal diff engine. Currently supported +--- algorithms are: +--- myers the default algorithm +--- minimal spend extra time to generate the +--- smallest possible diff +--- patience patience diff algorithm +--- histogram histogram diff algorithm +--- +--- closeoff When a window is closed where 'diff' is set +--- and there is only one window remaining in the +--- same tab page with 'diff' set, execute +--- `:diffoff` in that window. This undoes a +--- `:diffsplit` command. --- --- context:{n} Use a context of {n} lines between a change --- and a fold that contains unchanged lines. @@ -1636,6 +1655,23 @@ vim.go.dex = vim.go.diffexpr --- value (999999) to disable folding completely. --- See `fold-diff`. --- +--- filler Show filler lines, to keep the text +--- synchronized with a window that has inserted +--- lines at the same position. Mostly useful +--- when windows are side-by-side and 'scrollbind' +--- is set. +--- +--- foldcolumn:{n} Set the 'foldcolumn' option to {n} when +--- starting diff mode. Without this 2 is used. +--- +--- followwrap Follow the 'wrap' option and leave as it is. +--- +--- horizontal Start diff mode with horizontal splits (unless +--- explicitly specified otherwise). +--- +--- hiddenoff Do not use diff mode for a buffer when it +--- becomes hidden. +--- --- iblank Ignore changes where lines are all blank. Adds --- the "-B" flag to the "diff" command if --- 'diffexpr' is empty. Check the documentation @@ -1649,6 +1685,17 @@ vim.go.dex = vim.go.diffexpr --- are considered the same. Adds the "-i" flag --- to the "diff" command if 'diffexpr' is empty. --- +--- indent-heuristic +--- Use the indent heuristic for the internal +--- diff library. +--- +--- internal Use the internal diff library. This is +--- ignored when 'diffexpr' is set. *E960* +--- When running out of memory when writing a +--- buffer this item will be ignored for diffs +--- involving that buffer. Set the 'verbose' +--- option to see when this happens. +--- --- iwhite Ignore changes in amount of white space. Adds --- the "-b" flag to the "diff" command if --- 'diffexpr' is empty. Check the documentation @@ -1668,56 +1715,19 @@ vim.go.dex = vim.go.diffexpr --- of the "diff" command for what this does --- exactly. --- ---- horizontal Start diff mode with horizontal splits (unless ---- explicitly specified otherwise). +--- linematch:{n} Align and mark changes between the most +--- similar lines between the buffers. When the +--- total number of lines in the diff hunk exceeds +--- {n}, the lines will not be aligned because for +--- very large diff hunks there will be a +--- noticeable lag. A reasonable setting is +--- "linematch:60", as this will enable alignment +--- for a 2 buffer diff hunk of 30 lines each, +--- or a 3 buffer diff hunk of 20 lines each. --- --- vertical Start diff mode with vertical splits (unless --- explicitly specified otherwise). --- ---- closeoff When a window is closed where 'diff' is set ---- and there is only one window remaining in the ---- same tab page with 'diff' set, execute ---- `:diffoff` in that window. This undoes a ---- `:diffsplit` command. ---- ---- hiddenoff Do not use diff mode for a buffer when it ---- becomes hidden. ---- ---- foldcolumn:{n} Set the 'foldcolumn' option to {n} when ---- starting diff mode. Without this 2 is used. ---- ---- followwrap Follow the 'wrap' option and leave as it is. ---- ---- internal Use the internal diff library. This is ---- ignored when 'diffexpr' is set. *E960* ---- When running out of memory when writing a ---- buffer this item will be ignored for diffs ---- involving that buffer. Set the 'verbose' ---- option to see when this happens. ---- ---- indent-heuristic ---- Use the indent heuristic for the internal ---- diff library. ---- ---- linematch:{n} Enable a second stage diff on each generated ---- hunk in order to align lines. When the total ---- number of lines in a hunk exceeds {n}, the ---- second stage diff will not be performed as ---- very large hunks can cause noticeable lag. A ---- recommended setting is "linematch:60", as this ---- will enable alignment for a 2 buffer diff with ---- hunks of up to 30 lines each, or a 3 buffer ---- diff with hunks of up to 20 lines each. ---- ---- algorithm:{text} Use the specified diff algorithm with the ---- internal diff engine. Currently supported ---- algorithms are: ---- myers the default algorithm ---- minimal spend extra time to generate the ---- smallest possible diff ---- patience patience diff algorithm ---- histogram histogram diff algorithm ---- --- Examples: --- --- ```vim @@ -1824,7 +1834,7 @@ vim.go.dy = vim.go.display --- hor horizontally, height of windows is not affected --- both width and height of windows is affected --- ---- @type string +--- @type 'both'|'ver'|'hor' vim.o.eadirection = "both" vim.o.ead = vim.o.eadirection vim.go.eadirection = vim.o.eadirection @@ -2126,7 +2136,7 @@ vim.go.fencs = vim.go.fileencodings --- option is set, because the file would be different when written. --- This option cannot be changed when 'modifiable' is off. --- ---- @type string +--- @type 'unix'|'dos'|'mac' vim.o.fileformat = "unix" vim.o.ff = vim.o.fileformat vim.bo.fileformat = vim.o.fileformat @@ -2382,7 +2392,7 @@ vim.go.fcl = vim.go.foldclose --- "[1-9]": to display a fixed number of columns --- See `folding`. --- ---- @type string +--- @type 'auto'|'auto:1'|'auto:2'|'auto:3'|'auto:4'|'auto:5'|'auto:6'|'auto:7'|'auto:8'|'auto:9'|'0'|'1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9' vim.o.foldcolumn = "0" vim.o.fdc = vim.o.foldcolumn vim.wo.foldcolumn = vim.o.foldcolumn @@ -2479,7 +2489,7 @@ vim.wo.fmr = vim.wo.foldmarker --- `fold-syntax` syntax Syntax highlighting items specify folds. --- `fold-diff` diff Fold text that is not changed. --- ---- @type string +--- @type 'manual'|'expr'|'marker'|'indent'|'syntax'|'diff' vim.o.foldmethod = "manual" vim.o.fdm = vim.o.foldmethod vim.wo.foldmethod = vim.o.foldmethod @@ -2783,6 +2793,7 @@ vim.go.gp = vim.go.grepprg --- ci Command-line Insert mode --- cr Command-line Replace mode --- sm showmatch in Insert mode +--- t Terminal mode --- a all modes --- The argument-list is a dash separated list of these arguments: --- hor{N} horizontal bar, {N} percent of the character height @@ -2802,7 +2813,8 @@ vim.go.gp = vim.go.grepprg --- ```vim --- set guicursor=n:blinkon0 --- ``` ---- - Default is "blinkon0" for each mode. +--- +--- Default is "blinkon0" for each mode. --- {group-name} --- Highlight group that decides the color and font of the --- cursor. @@ -2848,7 +2860,7 @@ vim.go.gp = vim.go.grepprg --- --- --- @type string -vim.o.guicursor = "n-v-c-sm:block,i-ci-ve:ver25,r-cr-o:hor20" +vim.o.guicursor = "n-v-c-sm:block,i-ci-ve:ver25,r-cr-o:hor20,t:block-blinkon500-blinkoff500-TermCursor" vim.o.gcr = vim.o.guicursor vim.go.guicursor = vim.o.guicursor vim.go.gcr = vim.go.guicursor @@ -3016,7 +3028,7 @@ vim.go.hid = vim.go.hidden --- A history of ":" commands, and a history of previous search patterns --- is remembered. This option decides how many entries may be stored in ---- each of these histories (see `cmdline-editing` and 'msghistory' for +--- each of these histories (see `cmdline-editing` and 'messagesopt' for --- the number of messages to remember). --- The maximum value is 10000. --- @@ -3142,7 +3154,7 @@ vim.bo.ims = vim.bo.imsearch --- 'redrawtime') then 'inccommand' is automatically disabled until --- `Command-line-mode` is done. --- ---- @type string +--- @type 'nosplit'|'split'|'' vim.o.inccommand = "nosplit" vim.o.icm = vim.o.inccommand vim.go.inccommand = vim.o.inccommand @@ -4084,6 +4096,31 @@ vim.o.mis = vim.o.menuitems vim.go.menuitems = vim.o.menuitems vim.go.mis = vim.go.menuitems +--- Option settings for outputting messages. It can consist of the +--- following items. Items must be separated by a comma. +--- +--- hit-enter Use a `hit-enter` prompt when the message is longer than +--- 'cmdheight' size. +--- +--- wait:{n} Instead of using a `hit-enter` prompt, simply wait for +--- {n} milliseconds so that the user has a chance to read +--- the message. The maximum value of {n} is 10000. Use +--- 0 to disable the wait (but then the user may miss an +--- important message). +--- This item is ignored when "hit-enter" is present, but +--- required when "hit-enter" is not present. +--- +--- history:{n} Determines how many entries are remembered in the +--- `:messages` history. The maximum value is 10000. +--- Setting it to zero clears the message history. +--- This item must always be present. +--- +--- @type string +vim.o.messagesopt = "hit-enter,history:500" +vim.o.mopt = vim.o.messagesopt +vim.go.messagesopt = vim.o.messagesopt +vim.go.mopt = vim.go.messagesopt + --- Parameters for `:mkspell`. This tunes when to start compressing the --- word tree. Compression can be slow when there are many words, but --- it's needed to avoid running out of memory. The amount of memory used @@ -4327,7 +4364,7 @@ vim.go.mh = vim.go.mousehide --- "g<LeftMouse>" is "<C-LeftMouse> (jump to tag under mouse click) --- "g<RightMouse>" is "<C-RightMouse> ("CTRL-T") --- ---- @type string +--- @type 'extend'|'popup'|'popup_setpos' vim.o.mousemodel = "popup_setpos" vim.o.mousem = vim.o.mousemodel vim.go.mousemodel = vim.o.mousemodel @@ -4379,15 +4416,6 @@ vim.o.mouset = vim.o.mousetime vim.go.mousetime = vim.o.mousetime vim.go.mouset = vim.go.mousetime ---- Determines how many entries are remembered in the `:messages` history. ---- The maximum value is 10000. ---- ---- @type integer -vim.o.msghistory = 500 -vim.o.mhi = vim.o.msghistory -vim.go.msghistory = vim.o.msghistory -vim.go.mhi = vim.go.msghistory - --- This defines what bases Vim will consider for numbers when using the --- CTRL-A and CTRL-X commands for adding to and subtracting from a number --- respectively; see `CTRL-A` for more info on these commands. @@ -4827,8 +4855,8 @@ vim.go.redrawdebug = vim.o.redrawdebug vim.go.rdb = vim.go.redrawdebug --- Time in milliseconds for redrawing the display. Applies to ---- 'hlsearch', 'inccommand', `:match` highlighting and syntax ---- highlighting. +--- 'hlsearch', 'inccommand', `:match` highlighting, syntax highlighting, +--- and async `LanguageTree:parse()`. --- When redrawing takes more than this many milliseconds no further --- matches will be highlighted. --- For syntax highlighting the time applies per window. When over the @@ -4994,6 +5022,7 @@ vim.go.ruf = vim.go.rulerformat --- indent/ indent scripts `indent-expression` --- keymap/ key mapping files `mbyte-keymap` --- lang/ menu translations `:menutrans` +--- lsp/ LSP client configurations `lsp-config` --- lua/ `Lua` plugins --- menu.vim GUI menus `menu.vim` --- pack/ packages `:packadd` @@ -5197,11 +5226,13 @@ vim.go.sect = vim.go.sections --- selection. --- When "old" is used and 'virtualedit' allows the cursor to move past --- the end of line the line break still isn't included. +--- When "exclusive" is used, cursor position in visual mode will be +--- adjusted for inclusive motions `inclusive-motion-selection-exclusive`. --- Note that when "exclusive" is used and selecting from the end --- backwards, you cannot include the last character of a line, when --- starting in Normal mode and 'virtualedit' empty. --- ---- @type string +--- @type 'inclusive'|'exclusive'|'old' vim.o.selection = "inclusive" vim.o.sel = vim.o.selection vim.go.selection = vim.o.selection @@ -5767,7 +5798,7 @@ vim.go.sc = vim.go.showcmd --- place the text. Without a custom 'statusline' or 'tabline' it will be --- displayed in a convenient location. --- ---- @type string +--- @type 'last'|'statusline'|'tabline' vim.o.showcmdloc = "last" vim.o.sloc = vim.o.showcmdloc vim.go.showcmdloc = vim.o.showcmdloc @@ -5899,7 +5930,7 @@ vim.go.siso = vim.go.sidescrolloff --- "number" display signs in the 'number' column. If the number --- column is not present, then behaves like "auto". --- ---- @type string +--- @type 'yes'|'no'|'auto'|'auto:1'|'auto:2'|'auto:3'|'auto:4'|'auto:5'|'auto:6'|'auto:7'|'auto:8'|'auto:9'|'yes:1'|'yes:2'|'yes:3'|'yes:4'|'yes:5'|'yes:6'|'yes:7'|'yes:8'|'yes:9'|'number' vim.o.signcolumn = "auto" vim.o.scl = vim.o.signcolumn vim.wo.signcolumn = vim.o.signcolumn @@ -6207,7 +6238,7 @@ vim.go.sb = vim.go.splitbelow --- with the previous cursor position. For "screen", the text cannot always --- be kept on the same screen line when 'wrap' is enabled. --- ---- @type string +--- @type 'cursor'|'screen'|'topline' vim.o.splitkeep = "cursor" vim.o.spk = vim.o.splitkeep vim.go.splitkeep = vim.o.splitkeep @@ -6310,6 +6341,7 @@ vim.wo.stc = vim.wo.statuscolumn --- All fields except the {item} are optional. A single percent sign can --- be given as "%%". --- +--- *stl-%!* --- When the option starts with "%!" then it is used as an expression, --- evaluated and the result is used as the option value. Example: --- @@ -6854,7 +6886,7 @@ vim.go.tbs = vim.go.tagbsearch --- match Match case --- smart Ignore case unless an upper case letter is used --- ---- @type string +--- @type 'followic'|'ignore'|'match'|'followscs'|'smart' vim.o.tagcase = "followic" vim.o.tc = vim.o.tagcase vim.bo.tagcase = vim.o.tagcase @@ -7122,6 +7154,13 @@ vim.go.titleold = vim.o.titleold --- expanded according to the rules used for 'statusline'. If it contains --- an invalid '%' format, the value is used as-is and no error or warning --- will be given when the value is set. +--- +--- The default behaviour is equivalent to: +--- +--- ```vim +--- set titlestring=%t%(\ %M%)%(\ \(%{expand(\"%:~:h\")}\)%)%a\ -\ Nvim +--- ``` +--- --- This option cannot be set in a modeline when 'modelineexpr' is off. --- --- Example: @@ -7729,7 +7768,7 @@ vim.go.wop = vim.go.wildoptions --- key is never used for the menu. --- This option is not used for <F10>; on Win32. --- ---- @type string +--- @type 'yes'|'menu'|'no' vim.o.winaltkeys = "menu" vim.o.wak = vim.o.winaltkeys vim.go.winaltkeys = vim.o.winaltkeys diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 5eb15e1eee..098c0e907a 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -1023,16 +1023,22 @@ function vim.fn.complete_check() end --- See |complete_info_mode| for the values. --- pum_visible |TRUE| if popup menu is visible. --- See |pumvisible()|. ---- items List of completion matches. Each item is a ---- dictionary containing the entries "word", +--- items List of all completion candidates. Each item +--- is a dictionary containing the entries "word", --- "abbr", "menu", "kind", "info" and "user_data". --- See |complete-items|. +--- matches Same as "items", but only returns items that +--- are matching current query. If both "matches" +--- and "items" are in "what", the returned list +--- will still be named "items", but each item +--- will have an additional "match" field. --- selected Selected item index. First index is zero. --- Index is -1 if no item is selected (showing --- typed text only, or the last completion after --- no item is selected when using the <Up> or --- <Down> keys) ---- inserted Inserted string. [NOT IMPLEMENTED YET] +--- completed Return a dictionary containing the entries of +--- the currently selected index item. --- preview_winid Info floating preview window id. --- preview_bufnr Info floating preview buffer id. --- @@ -1147,8 +1153,9 @@ function vim.fn.confirm(msg, choices, default, type) end --- A |Dictionary| is copied in a similar way as a |List|. --- Also see |deepcopy()|. --- ---- @param expr any ---- @return any +--- @generic T +--- @param expr T +--- @return T function vim.fn.copy(expr) end --- Return the cosine of {expr}, measured in radians, as a |Float|. @@ -1228,7 +1235,7 @@ function vim.fn.ctxpush(types) end --- --- @param context table --- @param index? integer ---- @return any +--- @return integer function vim.fn.ctxset(context, index) end --- Returns the size of the |context-stack|. @@ -1308,9 +1315,10 @@ function vim.fn.debugbreak(pid) end --- {noref} set to 1 will fail. --- Also see |copy()|. --- ---- @param expr any +--- @generic T +--- @param expr T --- @param noref? boolean ---- @return any +--- @return T function vim.fn.deepcopy(expr, noref) end --- Without {flags} or with {flags} empty: Deletes the file by the @@ -1421,7 +1429,7 @@ function vim.fn.dictwatcherdel(dict, pattern, callback) end --- editing another buffer to set 'filetype' and load a syntax --- file. --- ---- @return any +--- @return integer function vim.fn.did_filetype() end --- Returns the number of filler lines above line {lnum}. @@ -1433,7 +1441,7 @@ function vim.fn.did_filetype() end --- Returns 0 if the current window is not in diff mode. --- --- @param lnum integer ---- @return any +--- @return integer function vim.fn.diff_filler(lnum) end --- Returns the highlight ID for diff mode at line {lnum} column @@ -1468,7 +1476,7 @@ function vim.fn.diff_hlID(lnum, col) end --- < --- --- @param chars string ---- @return any +--- @return string function vim.fn.digraph_get(chars) end --- Return a list of digraphs. If the {listall} argument is given @@ -1486,7 +1494,7 @@ function vim.fn.digraph_get(chars) end --- < --- --- @param listall? boolean ---- @return any +--- @return string[][] function vim.fn.digraph_getlist(listall) end --- Add digraph {chars} to the list. {chars} must be a string @@ -1538,7 +1546,7 @@ function vim.fn.digraph_setlist(digraphlist) end --- - A |Blob| is empty when its length is zero. --- --- @param expr any ---- @return any +--- @return integer function vim.fn.empty(expr) end --- Return all of environment variables as dictionary. You can @@ -1561,7 +1569,7 @@ function vim.fn.environ() end --- --- @param string string --- @param chars string ---- @return any +--- @return string function vim.fn.escape(string, chars) end --- Evaluate {string} and return the result. Especially useful to @@ -2368,7 +2376,7 @@ function vim.fn.foldtextresult(lnum) end --- --- @param expr1 string|table --- @param expr2 string|function ---- @return any +--- @return string|table function vim.fn.foreach(expr1, expr2) end --- Get the full command name from a short abbreviated command @@ -2675,7 +2683,7 @@ function vim.fn.getbufinfo(dict) end --- @param buf integer|string --- @param lnum integer --- @param end_? integer ---- @return any +--- @return string[] function vim.fn.getbufline(buf, lnum, end_) end --- Just like `getbufline()` but only get one line and return it @@ -2740,12 +2748,14 @@ function vim.fn.getcellwidths() end function vim.fn.getchangelist(buf) end --- Get a single character from the user or input stream. ---- If {expr} is omitted, wait until a character is available. +--- If {expr} is omitted or is -1, wait until a character is +--- available. --- If {expr} is 0, only get a character when one is available. --- Return zero otherwise. --- If {expr} is 1, only check if a character is available, it is --- not consumed. Return zero if no character available. ---- If you prefer always getting a string use |getcharstr()|. +--- If you prefer always getting a string use |getcharstr()|, or +--- specify |FALSE| as "number" in {opts}. --- --- Without {expr} and when {expr} is 0 a whole character or --- special key is returned. If it is a single character, the @@ -2755,7 +2765,8 @@ function vim.fn.getchangelist(buf) end --- starting with 0x80 (decimal: 128). This is the same value as --- the String "\<Key>", e.g., "\<Left>". The returned value is --- also a String when a modifier (shift, control, alt) was used ---- that is not included in the character. +--- that is not included in the character. |keytrans()| can also +--- be used to convert a returned String into a readable form. --- --- When {expr} is 0 and Esc is typed, there will be a short delay --- while Vim waits to see if this is the start of an escape @@ -2767,6 +2778,32 @@ function vim.fn.getchangelist(buf) end --- --- Use getcharmod() to obtain any additional modifiers. --- +--- The optional argument {opts} is a Dict and supports the +--- following items: +--- +--- cursor A String specifying cursor behavior +--- when waiting for a character. +--- "hide": hide the cursor. +--- "keep": keep current cursor unchanged. +--- "msg": move cursor to message area. +--- (default: automagically decide +--- between "keep" and "msg") +--- +--- number If |TRUE|, return a Number when getting +--- a single character. +--- If |FALSE|, the return value is always +--- converted to a String, and an empty +--- String (instead of 0) is returned when +--- no character is available. +--- (default: |TRUE|) +--- +--- simplify If |TRUE|, include modifiers in the +--- character if possible. E.g., return +--- the same value for CTRL-I and <Tab>. +--- If |FALSE|, don't include modifiers in +--- the character. +--- (default: |TRUE|) +--- --- When the user clicks a mouse button, the mouse event will be --- returned. The position can then be found in |v:mouse_col|, --- |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. @@ -2803,9 +2840,10 @@ function vim.fn.getchangelist(buf) end --- endfunction --- < --- ---- @param expr? 0|1 ---- @return integer -function vim.fn.getchar(expr) end +--- @param expr? -1|0|1 +--- @param opts? table +--- @return integer|string +function vim.fn.getchar(expr, opts) end --- The result is a Number which is the state of the modifiers for --- the last obtained character with getchar() or in another way. @@ -2864,20 +2902,13 @@ function vim.fn.getcharpos(expr) end --- @return table function vim.fn.getcharsearch() end ---- Get a single character from the user or input stream as a ---- string. ---- If {expr} is omitted, wait until a character is available. ---- If {expr} is 0 or false, only get a character when one is ---- available. Return an empty string otherwise. ---- If {expr} is 1 or true, only check if a character is ---- available, it is not consumed. Return an empty string ---- if no character is available. ---- Otherwise this works like |getchar()|, except that a number ---- result is converted to a string. ---- ---- @param expr? 0|1 +--- The same as |getchar()|, except that this always returns a +--- String, and "number" isn't allowed in {opts}. +--- +--- @param expr? -1|0|1 +--- @param opts? table --- @return string -function vim.fn.getcharstr(expr) end +function vim.fn.getcharstr(expr, opts) end --- Return completion pattern of the current command-line. --- Only works when the command line is being edited, thus @@ -2943,7 +2974,7 @@ function vim.fn.getcmdprompt() end --- Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and --- |setcmdline()|. --- ---- @return any +--- @return integer function vim.fn.getcmdscreenpos() end --- Return the current command-line type. Possible return values @@ -3763,6 +3794,20 @@ function vim.fn.getregtype(regname) end --- @return vim.fn.getscriptinfo.ret[] function vim.fn.getscriptinfo(opts) end +--- Returns the current stack trace of Vim scripts. +--- Stack trace is a |List|, of which each item is a |Dictionary| +--- with the following items: +--- funcref The funcref if the stack is at a function, +--- otherwise this item is omitted. +--- event The string of the event description if the +--- stack is at an autocmd event, otherwise this +--- item is omitted. +--- lnum The line number in the script on the stack. +--- filepath The file path of the script on the stack. +--- +--- @return table[] +function vim.fn.getstacktrace() end + --- If {tabnr} is not specified, then information about all the --- tab pages is returned as a |List|. Each List item is a --- |Dictionary|. Otherwise, {tabnr} specifies the tab page @@ -3869,7 +3914,7 @@ function vim.fn.gettagstack(winnr) end --- strings. --- --- @param text string ---- @return any +--- @return string function vim.fn.gettext(text) end --- Returns information about windows as a |List| with Dictionaries. @@ -3885,6 +3930,8 @@ function vim.fn.gettext(text) end --- botline last complete displayed buffer line --- bufnr number of buffer in the window --- height window height (excluding winbar) +--- leftcol first column displayed; only used when +--- 'wrap' is off --- loclist 1 if showing a location list --- quickfix 1 if quickfix or location list window --- terminal 1 if a terminal window @@ -4018,7 +4065,7 @@ function vim.fn.glob(expr, nosuf, list, alllinks) end --- a backslash usually means a path separator. --- --- @param string string ---- @return any +--- @return string function vim.fn.glob2regpat(string) end --- Perform glob() for String {expr} on all directories in {path} @@ -4352,7 +4399,7 @@ function vim.fn.hostname() end --- @param string string --- @param from string --- @param to string ---- @return any +--- @return string function vim.fn.iconv(string, from, to) end --- Returns a |String| which is a unique identifier of the @@ -4372,7 +4419,7 @@ function vim.fn.iconv(string, from, to) end --- reuse identifiers of the garbage-collected ones. --- --- @param expr any ---- @return any +--- @return string function vim.fn.id(expr) end --- The result is a Number, which is indent of line {lnum} in the @@ -4416,7 +4463,7 @@ function vim.fn.indent(lnum) end --- @param expr any --- @param start? integer --- @param ic? boolean ---- @return any +--- @return integer function vim.fn.index(object, expr, start, ic) end --- Returns the index of an item in {object} where {expr} is @@ -4460,14 +4507,14 @@ function vim.fn.index(object, expr, start, ic) end --- @param object any --- @param expr any --- @param opts? table ---- @return any +--- @return integer function vim.fn.indexof(object, expr, opts) end --- --- @param prompt string --- @param text? string --- @param completion? string ---- @return any +--- @return string function vim.fn.input(prompt, text, completion) end --- The result is a String, which is whatever the user typed on @@ -4581,7 +4628,7 @@ function vim.fn.input(prompt, text, completion) end --- < --- --- @param opts table ---- @return any +--- @return string function vim.fn.input(opts) end --- @deprecated @@ -4616,7 +4663,7 @@ function vim.fn.inputlist(textlist) end --- called. Calling it more often is harmless though. --- Returns TRUE when there is nothing to restore, FALSE otherwise. --- ---- @return any +--- @return integer function vim.fn.inputrestore() end --- Preserve typeahead (also from mappings) and clear it, so that @@ -4626,7 +4673,7 @@ function vim.fn.inputrestore() end --- many inputrestore() calls. --- Returns TRUE when out of memory, FALSE otherwise. --- ---- @return any +--- @return integer function vim.fn.inputsave() end --- This function acts much like the |input()| function with but @@ -4641,7 +4688,7 @@ function vim.fn.inputsave() end --- --- @param prompt string --- @param text? string ---- @return any +--- @return string function vim.fn.inputsecret(prompt, text) end --- When {object} is a |List| or a |Blob| insert {item} at the start @@ -4687,8 +4734,8 @@ function vim.fn.interrupt() end --- let bits = invert(bits) --- < --- ---- @param expr number ---- @return any +--- @param expr integer +--- @return integer function vim.fn.invert(expr) end --- The result is a Number, which is |TRUE| when {path} is an @@ -4767,7 +4814,7 @@ function vim.fn.isnan(expr) end --- cases, items() returns a List with the index and the value at --- the index. --- ---- @param dict any +--- @param dict table --- @return any function vim.fn.items(dict) end @@ -4801,7 +4848,7 @@ function vim.fn.jobresize(job, width, height) end --- @return any function vim.fn.jobsend(...) end ---- Note: Prefer |vim.system()| in Lua (unless using the `pty` option). +--- Note: Prefer |vim.system()| in Lua (unless using `rpc`, `pty`, or `term`). --- --- Spawns {cmd} as a job. --- If {cmd} is a List it runs directly (no 'shell'). @@ -4809,8 +4856,11 @@ function vim.fn.jobsend(...) end --- call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}']) --- <(See |shell-unquoting| for details.) --- ---- Example: >vim ---- call jobstart('nvim -h', {'on_stdout':{j,d,e->append(line('.'),d)}}) +--- Example: start a job and handle its output: >vim +--- call jobstart(['nvim', '-h'], {'on_stdout':{j,d,e->append(line('.'),d)}}) +--- < +--- Example: start a job in a |terminal| connected to the current buffer: >vim +--- call jobstart(['nvim', '-h'], {'term':v:true}) --- < --- Returns |job-id| on success, 0 on invalid arguments (or job --- table is full), -1 if {cmd}[0] or 'shell' is not executable. @@ -4875,6 +4925,10 @@ function vim.fn.jobsend(...) end --- stdin: (string) Either "pipe" (default) to connect the --- job's stdin to a channel or "null" to disconnect --- stdin. +--- term: (boolean) Spawns {cmd} in a new pseudo-terminal session +--- connected to the current (unmodified) buffer. Implies "pty". +--- Default "height" and "width" are set to the current window +--- dimensions. |jobstart()|. Defaults $TERM to "xterm-256color". --- width: (number) Width of the `pty` terminal. --- --- {opts} is passed as |self| dictionary to the callback; the @@ -4888,7 +4942,7 @@ function vim.fn.jobsend(...) end --- --- @param cmd string|string[] --- @param opts? table ---- @return any +--- @return integer function vim.fn.jobstart(cmd, opts) end --- Stop |job-id| {id} by sending SIGTERM to the job process. If @@ -4901,7 +4955,7 @@ function vim.fn.jobstart(cmd, opts) end --- exited or stopped. --- --- @param id integer ---- @return any +--- @return integer function vim.fn.jobstop(id) end --- Waits for jobs and their |on_exit| handlers to complete. @@ -4926,7 +4980,7 @@ function vim.fn.jobstop(id) end --- --- @param jobs integer[] --- @param timeout? integer ---- @return any +--- @return integer[] function vim.fn.jobwait(jobs, timeout) end --- Join the items in {list} together into one String. @@ -4941,7 +4995,7 @@ function vim.fn.jobwait(jobs, timeout) end --- --- @param list any[] --- @param sep? string ---- @return any +--- @return string function vim.fn.join(list, sep) end --- Convert {expr} from JSON object. Accepts |readfile()|-style @@ -4974,14 +5028,14 @@ function vim.fn.json_decode(expr) end --- |Blob|s are converted to arrays of the individual bytes. --- --- @param expr any ---- @return any +--- @return string function vim.fn.json_encode(expr) end --- Return a |List| with all the keys of {dict}. The |List| is in --- arbitrary order. Also see |items()| and |values()|. --- --- @param dict table ---- @return any +--- @return string[] function vim.fn.keys(dict) end --- Turn the internal byte representation of keys into a form that @@ -4991,7 +5045,7 @@ function vim.fn.keys(dict) end --- < <C-Home> --- --- @param string string ---- @return any +--- @return string function vim.fn.keytrans(string) end --- @deprecated @@ -5010,8 +5064,8 @@ function vim.fn.last_buffer_nr() end --- |Dictionary| is returned. --- Otherwise an error is given and returns zero. --- ---- @param expr any ---- @return any +--- @param expr any[] +--- @return integer function vim.fn.len(expr) end --- Call function {funcname} in the run-time library {libname} @@ -5122,7 +5176,7 @@ function vim.fn.line2byte(lnum) end --- When {lnum} is invalid, -1 is returned. --- --- @param lnum integer ---- @return any +--- @return integer function vim.fn.lispindent(lnum) end --- Return a Blob concatenating all the number values in {list}. @@ -5135,7 +5189,7 @@ function vim.fn.lispindent(lnum) end --- |blob2list()| does the opposite. --- --- @param list any[] ---- @return any +--- @return string function vim.fn.list2blob(list) end --- Convert each number in {list} to a character string can @@ -5155,13 +5209,13 @@ function vim.fn.list2blob(list) end --- --- @param list any[] --- @param utf8? boolean ---- @return any +--- @return string function vim.fn.list2str(list, utf8) end --- Return the current time, measured as seconds since 1st Jan --- 1970. See also |strftime()|, |strptime()| and |getftime()|. --- ---- @return any +--- @return integer function vim.fn.localtime() end --- Return the natural logarithm (base e) of {expr} as a |Float|. @@ -5175,7 +5229,7 @@ function vim.fn.localtime() end --- < 5.0 --- --- @param expr number ---- @return any +--- @return number function vim.fn.log(expr) end --- Return the logarithm of Float {expr} to base 10 as a |Float|. @@ -5188,7 +5242,7 @@ function vim.fn.log(expr) end --- < -2.0 --- --- @param expr number ---- @return any +--- @return number function vim.fn.log10(expr) end --- {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. @@ -5950,7 +6004,7 @@ function vim.fn.matchstrpos(expr, pat, start, count) end --- an error. An empty |List| or |Dictionary| results in zero. --- --- @param expr any ---- @return any +--- @return number function vim.fn.max(expr) end --- Returns a |List| of |Dictionaries| describing |menus| (defined @@ -6088,7 +6142,7 @@ function vim.fn.menu_info(name, mode) end --- an error. An empty |List| or |Dictionary| results in zero. --- --- @param expr any ---- @return any +--- @return number function vim.fn.min(expr) end --- Create directory {name}. @@ -6133,7 +6187,7 @@ function vim.fn.min(expr) end --- @param name string --- @param flags? string --- @param prot? string ---- @return any +--- @return integer function vim.fn.mkdir(name, flags, prot) end --- Return a string that indicates the current mode. @@ -6296,7 +6350,7 @@ function vim.fn.msgpackparse(data) end --- See also |prevnonblank()|. --- --- @param lnum integer ---- @return any +--- @return integer function vim.fn.nextnonblank(lnum) end --- Return a string with a single character, which has the number @@ -6315,7 +6369,7 @@ function vim.fn.nextnonblank(lnum) end --- --- @param expr integer --- @param utf8? boolean ---- @return any +--- @return string function vim.fn.nr2char(expr, utf8) end --- Bitwise OR on the two arguments. The arguments are converted @@ -6349,7 +6403,7 @@ vim.fn['or'] = function(expr, expr1) end --- --- @param path string --- @param len? integer ---- @return any +--- @return string function vim.fn.pathshorten(path, len) end --- Evaluate |perl| expression {expr} and return its result @@ -6383,7 +6437,7 @@ function vim.fn.perleval(expr) end --- --- @param x number --- @param y number ---- @return any +--- @return number function vim.fn.pow(x, y) end --- Return the line number of the first line at or above {lnum} @@ -6395,7 +6449,7 @@ function vim.fn.pow(x, y) end --- Also see |nextnonblank()|. --- --- @param lnum integer ---- @return any +--- @return integer function vim.fn.prevnonblank(lnum) end --- Return a String with {fmt}, where "%" items are replaced by @@ -7014,10 +7068,11 @@ function vim.fn.readfile(fname, type, max) end --- echo reduce('xyz', { acc, val -> acc .. ',' .. val }) --- < --- +--- @generic T --- @param object any ---- @param func function +--- @param func fun(accumulator: T, current: any): any --- @param initial? any ---- @return any +--- @return T function vim.fn.reduce(object, func, initial) end --- Returns the single letter name of the register being executed. @@ -7170,7 +7225,7 @@ function vim.fn.remove(dict, key) end --- --- @param from string --- @param to string ---- @return any +--- @return integer function vim.fn.rename(from, to) end --- Repeat {expr} {count} times and return the concatenated @@ -7200,7 +7255,7 @@ vim.fn['repeat'] = function(expr, count) end --- path name) and also keeps a trailing path separator. --- --- @param filename string ---- @return any +--- @return string function vim.fn.resolve(filename) end --- Reverse the order of items in {object}. {object} can be a @@ -7213,8 +7268,9 @@ function vim.fn.resolve(filename) end --- let revlist = reverse(copy(mylist)) --- < --- ---- @param object any ---- @return any +--- @generic T +--- @param object T[] +--- @return T[] function vim.fn.reverse(object) end --- Round off {expr} to the nearest integral value and return it @@ -7231,7 +7287,7 @@ function vim.fn.reverse(object) end --- < -5.0 --- --- @param expr number ---- @return any +--- @return number function vim.fn.round(expr) end --- Sends {event} to {channel} via |RPC| and returns immediately. @@ -7242,9 +7298,9 @@ function vim.fn.round(expr) end --- --- @param channel integer --- @param event string ---- @param args? any ---- @return any -function vim.fn.rpcnotify(channel, event, args) end +--- @param ... any +--- @return integer +function vim.fn.rpcnotify(channel, event, ...) end --- Sends a request to {channel} to invoke {method} via --- |RPC| and blocks until a response is received. @@ -7254,9 +7310,9 @@ function vim.fn.rpcnotify(channel, event, args) end --- --- @param channel integer --- @param method string ---- @param args? any +--- @param ... any --- @return any -function vim.fn.rpcrequest(channel, method, args) end +function vim.fn.rpcrequest(channel, method, ...) end --- @deprecated --- Deprecated. Replace >vim @@ -7300,7 +7356,7 @@ function vim.fn.rubyeval(expr) end --- --- @param row integer --- @param col integer ---- @return any +--- @return integer function vim.fn.screenattr(row, col) end --- The result is a Number, which is the character at position @@ -7314,7 +7370,7 @@ function vim.fn.screenattr(row, col) end --- --- @param row integer --- @param col integer ---- @return any +--- @return integer function vim.fn.screenchar(row, col) end --- The result is a |List| of Numbers. The first number is the same @@ -7325,7 +7381,7 @@ function vim.fn.screenchar(row, col) end --- --- @param row integer --- @param col integer ---- @return any +--- @return integer[] function vim.fn.screenchars(row, col) end --- The result is a Number, which is the current screen column of @@ -7342,7 +7398,7 @@ function vim.fn.screenchars(row, col) end --- noremap GG <Cmd>echom screencol()<CR> --- < --- ---- @return any +--- @return integer[] function vim.fn.screencol() end --- The result is a Dict with the screen position of the text @@ -7381,7 +7437,7 @@ function vim.fn.screenpos(winid, lnum, col) end --- --- Note: Same restrictions as with |screencol()|. --- ---- @return any +--- @return integer function vim.fn.screenrow() end --- The result is a String that contains the base character and @@ -7393,7 +7449,7 @@ function vim.fn.screenrow() end --- --- @param row integer --- @param col integer ---- @return any +--- @return string function vim.fn.screenstring(row, col) end --- Search for regexp pattern {pattern}. The search starts at the @@ -7505,7 +7561,7 @@ function vim.fn.screenstring(row, col) end --- @param stopline? integer --- @param timeout? integer --- @param skip? string|function ---- @return any +--- @return integer function vim.fn.search(pattern, flags, stopline, timeout, skip) end --- Get or update the last search count, like what is displayed @@ -7798,7 +7854,7 @@ function vim.fn.searchpos(pattern, flags, stopline, timeout, skip) end --- echo serverlist() --- < --- ---- @return any +--- @return string[] function vim.fn.serverlist() end --- Opens a socket or named pipe at {address} and listens for @@ -7835,7 +7891,7 @@ function vim.fn.serverlist() end --- < --- --- @param address? string ---- @return any +--- @return string function vim.fn.serverstart(address) end --- Closes the pipe or socket at {address}. @@ -7844,7 +7900,7 @@ function vim.fn.serverstart(address) end --- address in |serverlist()|. --- --- @param address string ---- @return any +--- @return integer function vim.fn.serverstop(address) end --- Set line {lnum} to {text} in buffer {buf}. This works like @@ -7874,7 +7930,7 @@ function vim.fn.serverstop(address) end --- @param buf integer|string --- @param lnum integer --- @param text string|string[] ---- @return any +--- @return integer function vim.fn.setbufline(buf, lnum, text) end --- Set option or local variable {varname} in buffer {buf} to @@ -7979,7 +8035,7 @@ function vim.fn.setcharsearch(dict) end --- --- @param str string --- @param pos? integer ---- @return any +--- @return integer function vim.fn.setcmdline(str, pos) end --- Set the cursor position in the command line to byte position @@ -8289,7 +8345,7 @@ function vim.fn.setpos(expr, list) end --- @param list vim.quickfix.entry[] --- @param action? string --- @param what? vim.fn.setqflist.what ---- @return any +--- @return integer function vim.fn.setqflist(list, action, what) end --- Set the register {regname} to {value}. @@ -8442,7 +8498,7 @@ function vim.fn.setwinvar(nr, varname, val) end --- checksum of {string}. --- --- @param string string ---- @return any +--- @return string function vim.fn.sha256(string) end --- Escape {string} for use as a shell command argument. @@ -8478,7 +8534,7 @@ function vim.fn.sha256(string) end --- --- @param string string --- @param special? boolean ---- @return any +--- @return string function vim.fn.shellescape(string, special) end --- Returns the effective value of 'shiftwidth'. This is the @@ -8930,7 +8986,7 @@ function vim.fn.sign_unplacelist(list) end --- links before simplifying the path name, use |resolve()|. --- --- @param filename string ---- @return any +--- @return string function vim.fn.simplify(filename) end --- Return the sine of {expr}, measured in radians, as a |Float|. @@ -8943,7 +8999,7 @@ function vim.fn.simplify(filename) end --- < 0.763301 --- --- @param expr number ---- @return any +--- @return number function vim.fn.sin(expr) end --- Return the hyperbolic sine of {expr} as a |Float| in the range @@ -9077,10 +9133,11 @@ function vim.fn.sockconnect(mode, address, opts) end --- eval mylist->sort({i1, i2 -> i1 - i2}) --- < --- ---- @param list any +--- @generic T +--- @param list T[] --- @param how? string|function --- @param dict? any ---- @return any +--- @return T[] function vim.fn.sort(list, how, dict) end --- Return the sound-folded equivalent of {word}. Uses the first @@ -9091,7 +9148,7 @@ function vim.fn.sort(list, how, dict) end --- the method can be quite slow. --- --- @param word string ---- @return any +--- @return string function vim.fn.soundfold(word) end --- Without argument: The result is the badly spelled word under @@ -9144,7 +9201,7 @@ function vim.fn.spellbadword(sentence) end --- @param word string --- @param max? integer --- @param capital? boolean ---- @return any +--- @return string[] function vim.fn.spellsuggest(word, max, capital) end --- Make a |List| out of {string}. When {pattern} is omitted or @@ -9174,7 +9231,7 @@ function vim.fn.spellsuggest(word, max, capital) end --- @param string string --- @param pattern? string --- @param keepempty? boolean ---- @return any +--- @return string[] function vim.fn.split(string, pattern, keepempty) end --- Return the non-negative square root of Float {expr} as a @@ -9326,6 +9383,7 @@ function vim.fn.str2float(string, quoted) end --- and exists only for backwards-compatibility. --- With UTF-8 composing characters are handled properly: >vim --- echo str2list("á") " returns [97, 769] +--- < --- --- @param string string --- @param utf8? boolean @@ -10160,23 +10218,12 @@ function vim.fn.tanh(expr) end --- @return string function vim.fn.tempname() end ---- Spawns {cmd} in a new pseudo-terminal session connected ---- to the current (unmodified) buffer. Parameters and behavior ---- are the same as |jobstart()| except "pty", "width", "height", ---- and "TERM" are ignored: "height" and "width" are taken from ---- the current window. Note that termopen() implies a "pty" arg ---- to jobstart(), and thus has the implications documented at ---- |jobstart()|. ---- ---- Returns the same values as jobstart(). ---- ---- Terminal environment is initialized as in |jobstart-env|, ---- except $TERM is set to "xterm-256color". Full behavior is ---- described in |terminal|. +--- @deprecated +--- Use |jobstart()| with `{term: v:true}` instead. --- --- @param cmd string|string[] --- @param opts? table ---- @return any +--- @return integer function vim.fn.termopen(cmd, opts) end --- Return a list with information about timers. @@ -10576,7 +10623,7 @@ function vim.fn.virtcol(expr, list, winid) end --- @param winid integer --- @param lnum integer --- @param col integer ---- @return any +--- @return integer function vim.fn.virtcol2col(winid, lnum, col) end --- The result is a String, which describes the last Visual mode @@ -10597,7 +10644,7 @@ function vim.fn.virtcol2col(winid, lnum, col) end --- the old value is returned. See |non-zero-arg|. --- --- @param expr? boolean ---- @return any +--- @return string function vim.fn.visualmode(expr) end --- Waits until {condition} evaluates to |TRUE|, where {condition} @@ -10714,7 +10761,7 @@ function vim.fn.win_id2tabwin(expr) end --- Return 0 if the window cannot be found in the current tabpage. --- --- @param expr integer ---- @return any +--- @return integer function vim.fn.win_id2win(expr) end --- Move window {nr}'s vertical separator (i.e., the right border) @@ -10868,7 +10915,7 @@ function vim.fn.winheight(nr) end --- < --- --- @param tabnr? integer ---- @return any +--- @return any[] function vim.fn.winlayout(tabnr) end --- The result is a Number, which is the screen line of the cursor @@ -10912,7 +10959,7 @@ function vim.fn.winline() end --- < --- --- @param arg? string|integer ---- @return any +--- @return integer function vim.fn.winnr(arg) end --- Returns a sequence of |:resize| commands that should restore @@ -10925,7 +10972,7 @@ function vim.fn.winnr(arg) end --- exe cmd --- < --- ---- @return any +--- @return string function vim.fn.winrestcmd() end --- Uses the |Dictionary| returned by |winsaveview()| to restore @@ -10990,7 +11037,7 @@ function vim.fn.winsaveview() end --- option. --- --- @param nr integer ---- @return any +--- @return integer function vim.fn.winwidth(nr) end --- The result is a dictionary of byte/chars/word statistics for @@ -11075,7 +11122,7 @@ function vim.fn.writefile(object, fname, flags) end --- let bits = xor(bits, 0x80) --- < --- ---- @param expr number ---- @param expr1 number ---- @return any +--- @param expr integer +--- @param expr1 integer +--- @return integer function vim.fn.xor(expr, expr1) end diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua index 8784fdbac9..c1b8695bbf 100644 --- a/runtime/lua/vim/_meta/vvars.lua +++ b/runtime/lua/vim/_meta/vvars.lua @@ -15,7 +15,7 @@ vim.v.argv = ... --- Argument for evaluating 'formatexpr' and used for the typed --- character when using <expr> in an abbreviation `:map-<expr>`. --- It is also used by the `InsertCharPre` and `InsertEnter` events. ---- @type any +--- @type string vim.v.char = ... --- The name of the character encoding of a file to be converted. @@ -60,7 +60,7 @@ vim.v.collate = ... --- mode. --- Note: Plugins can modify the value to emulate the builtin --- `CompleteDone` event behavior. ---- @type any +--- @type vim.v.completed_item vim.v.completed_item = ... --- The count given for the last Normal mode command. Can be used @@ -90,7 +90,7 @@ vim.v.count1 = ... --- This variable can not be set directly, use the `:language` --- command. --- See `multi-lang`. ---- @type any +--- @type string vim.v.ctype = ... --- Normally zero. When a deadly signal is caught it's set to @@ -197,11 +197,14 @@ vim.v.errors = ... --- changing window (or tab) on `DirChanged`. --- status Job status or exit code, -1 means "unknown". `TermClose` --- reason Reason for completion being done. `CompleteDone` ---- @type any +--- complete_word The word that was selected, empty if abandoned complete. +--- complete_type See `complete_info_mode` +--- @type vim.v.event vim.v.event = ... --- The value of the exception most recently caught and not ---- finished. See also `v:throwpoint` and `throw-variables`. +--- finished. See also `v:stacktrace`, `v:throwpoint`, and +--- `throw-variables`. --- Example: --- --- ```vim @@ -223,7 +226,7 @@ vim.v.exception = ... --- ```vim --- :au VimLeave * echo "Exit value is " .. v:exiting --- ``` ---- @type any +--- @type integer? vim.v.exiting = ... --- Special value used to put "false" in JSON and msgpack. See @@ -419,7 +422,7 @@ vim.v.mouse_winid = ... --- and `msgpackdump()`. All types inside dictionary are fixed --- (not editable) empty lists. To check whether some list is one --- of msgpack types, use `is` operator. ---- @type any +--- @type table vim.v.msgpack_types = ... --- Special value used to put "null" in JSON and NIL in msgpack. @@ -563,7 +566,7 @@ vim.v.relnum = ... --- typed command. --- This can be used to find out why your script causes the --- hit-enter prompt. ---- @type any +--- @type string vim.v.scrollstart = ... --- Search direction: 1 after a forward search, 0 after a @@ -614,6 +617,13 @@ vim.v.servername = ... --- @type integer vim.v.shell_error = ... +--- The stack trace of the exception most recently caught and +--- not finished. Refer to `getstacktrace()` for the structure of +--- stack trace. See also `v:exception`, `v:throwpoint`, and +--- `throw-variables`. +--- @type table[] +vim.v.stacktrace = ... + --- Last given status message. --- Modifiable (can be set). --- @type string @@ -705,18 +715,18 @@ vim.v.termrequest = ... vim.v.termresponse = ... --- Must be set before using `test_garbagecollect_now()`. ---- @type any +--- @type integer vim.v.testing = ... --- Full filename of the last loaded or saved session file. --- Empty when no session file has been saved. See `:mksession`. --- Modifiable (can be set). ---- @type any +--- @type string vim.v.this_session = ... --- The point where the exception most recently caught and not --- finished was thrown. Not set when commands are typed. See ---- also `v:exception` and `throw-variables`. +--- also `v:exception`, `v:stacktrace`, and `throw-variables`. --- Example: --- --- ```vim @@ -728,7 +738,7 @@ vim.v.this_session = ... --- ``` --- --- Output: "Exception from test.vim, line 2" ---- @type any +--- @type string vim.v.throwpoint = ... --- Special value used to put "true" in JSON and msgpack. See diff --git a/runtime/lua/vim/_meta/vvars_extra.lua b/runtime/lua/vim/_meta/vvars_extra.lua new file mode 100644 index 0000000000..7ef3021e89 --- /dev/null +++ b/runtime/lua/vim/_meta/vvars_extra.lua @@ -0,0 +1,77 @@ +--- @meta _ +error('Cannot require a meta file') + +--- Extra types for vim.v dictionary fields + +--- @class vim.v.completed_item +--- @field word? string the text that will be inserted, mandatory +--- abbreviation of "word"; when not empty it is used in the menu instead of "word" +--- @field abbr? string +--- extra text for the popup menu, displayed after "word" or "abbr" +--- @field menu? string +--- more information about the item, can be displayed in a preview window +--- @field info? string +--- @field kind? string single letter indicating the type of completion +--- when non-zero case is to be ignored when comparing items to be equal; when +--- omitted zero is used, thus items that only differ in case are added +--- @field icase? integer +--- when non-zero, always treat this item to be equal when comparing. Which +--- means, "equal=1" disables filtering of this item. +--- @field equal? integer +--- when non-zero this match will be added even when an item with the same word +--- is already present. +--- @field dup? integer +--- when non-zero this match will be added even when it is an empty string +--- @field empty? integer +--- custom data which is associated with the item and available +--- in |v:completed_item|; it can be any type; defaults to an empty string +--- @field user_data? any +--- an additional highlight group whose attributes are combined +--- with |hl-PmenuSel| and |hl-Pmenu| or |hl-PmenuMatchSel| and |hl-PmenuMatch| +--- highlight attributes in the popup menu to apply cterm and gui properties +--- (with higher priority) like strikethrough to the completion items abbreviation +--- @field abbr_hlgroup? string +--- an additional highlight group specifically for setting the highlight +--- attributes of the completion kind. When this field is present, it will +--- override the |hl-PmenuKind| highlight group, allowing for the customization +--- of ctermfg and guifg properties for the completion kind +--- @field kind_hlgroup? string + +--- @class vim.v.event +--- Whether the event triggered during an aborting condition (e.g. |c_Esc| or +--- |c_CTRL-C| for |CmdlineLeave|). +--- @field abort? boolean +--- @field chan? integer See |channel-id| +--- @field info? table Dict of arbitrary event data. +--- @field cmdlevel? integer Level of cmdline. +--- @field cmdtype? string Type of cmdline, |cmdline-char|. +--- @field cwd? string Current working directory. +--- @field inclusive? boolean Motion is |inclusive|, else exclusive. +--- @field scope? string Event-specific scope name. +--- Current |operator|. Also set for Ex commands (unlike |v:operator|). For +--- example if |TextYankPost| is triggered by the |:yank| Ex command then +--- `v:event.operator` is "y". +--- @field operator? string +--- Text stored in the register as a |readfile()|-style list of lines. +--- @field regcontents? string +--- Requested register (e.g "x" for "xyy) or the empty string for an unnamed operation. +--- @field regname? string +--- @field regtype? string Type of register as returned by |getregtype()|. +--- @field visual? boolean Selection is visual (as opposed to, e.g., via motion). +--- @field completed_item? vim.v.completed_item +--- Current selected complete item on |CompleteChanged|, Is `{}` when no +--- complete item selected. +--- @field height? integer +--- @field width? integer Height of popup menu on |CompleteChanged| +--- @field row? integer Width of popup menu on |CompleteChanged| +--- Col count of popup menu on |CompleteChanged|, relative to screen. +--- @field col? integer +--- @field size? integer Total number of completion items on |CompleteChanged|. +--- Is |v:true| if popup menu have scrollbar, or |v:false| if not. +--- @field scrollbar? boolean +--- Is |v:true| if the event fired while changing window (or tab) on |DirChanged|. +--- @field changed_window? boolean +--- @field status? boolean Job status or exit code, -1 means "unknown". |TermClose| +--- @field reason? string Reason for completion being done. |CompleteDone| +--- The word that was selected, empty if abandoned complete. @field complete_word? string +--- @field complete_type? string See |complete_info_mode| |