From 2d9e1ebb50c59cf7589560747057f3bfd6200697 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 26 Apr 2026 17:07:32 +0200 Subject: [PATCH] docs: sort quasi-keysets --- runtime/doc/api.txt | 310 +++++++++++----------- runtime/doc/diagnostic.txt | 264 +++++++++--------- runtime/doc/lsp.txt | 154 +++++------ runtime/doc/lua.txt | 216 +++++++-------- runtime/doc/pack.txt | 10 +- runtime/doc/plugins.txt | 32 +-- runtime/doc/treesitter.txt | 44 +-- runtime/lua/vim/_meta/api.gen.lua | 300 ++++++++++----------- runtime/lua/vim/_meta/api_keysets.gen.lua | 284 ++++++++++---------- runtime/lua/vim/hl.lua | 4 +- runtime/lua/vim/lsp/util.lua | 6 +- runtime/lua/vim/treesitter.lua | 8 +- runtime/lua/vim/treesitter/query.lua | 6 +- src/nvim/api/autocmd.c | 12 +- src/nvim/api/buffer.c | 26 +- src/nvim/api/command.c | 12 +- src/nvim/api/extmark.c | 200 +++++++------- src/nvim/api/options.c | 12 +- src/nvim/api/vim.c | 28 +- src/nvim/api/window.c | 10 +- 20 files changed, 969 insertions(+), 969 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index af470547c7..8c8aceea4b 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -724,19 +724,19 @@ nvim_eval_statusline({str}, {opts}) *nvim_eval_statusline()* Parameters: ~ • {str} (`string`) Statusline string (see 'statusline'). • {opts} (`vim.api.keyset.eval_statusline`) Optional parameters. - • winid: (number) |window-ID| of the window to use as context - for statusline. - • maxwidth: (number) Maximum width of statusline. • fillchar: (string) Character to fill blank spaces in the statusline (see 'fillchars'). Treated as single-width even if it isn't. • highlights: (boolean) Return highlight information. - • use_winbar: (boolean) Evaluate winbar instead of statusline. + • maxwidth: (number) Maximum width of statusline. + • use_statuscol_lnum: (number) Evaluate statuscolumn for this + line number instead of statusline. • use_tabline: (boolean) Evaluate tabline instead of statusline. When true, {winid} is ignored. Mutually exclusive with {use_winbar}. - • use_statuscol_lnum: (number) Evaluate statuscolumn for this - line number instead of statusline. + • use_winbar: (boolean) Evaluate winbar instead of statusline. + • winid: (number) |window-ID| of the window to use as context + for statusline. Return: ~ (`vim.api.keyset.eval_statusline_ret`) Dict containing statusline @@ -950,12 +950,12 @@ nvim_get_hl({ns_id}, {opts}) *nvim_get_hl()* |nvim_get_namespaces()|. Use 0 to get global highlight groups |:highlight|. • {opts} (`vim.api.keyset.get_highlight`) Options dict: - • name: (string) Get a highlight definition by name. + • create: (boolean, default true) When highlight group + doesn't exist create it. • id: (integer) Get a highlight definition by id. • link: (boolean, default true) Show linked group name instead of effective definition |:hi-link|. - • create: (boolean, default true) When highlight group - doesn't exist create it. + • name: (string) Get a highlight definition by name. Return: ~ (`vim.api.keyset.get_hl_info`) Highlight groups as a map from group @@ -1289,13 +1289,13 @@ nvim_open_term({buf}, {opts}) *nvim_open_term()* • {buf} (`integer`) Buffer to use. Buffer contents (if any) will be written to the PTY. • {opts} (`vim.api.keyset.open_term`) Optional parameters. + • force_crlf: (boolean, default true) Convert "\n" to "\r\n". • on_input: Lua callback for input sent, i e keypresses in terminal mode. Note: keypresses are sent raw as they would be to the pty master end. For instance, a carriage return is sent as a "\r", not as a "\n". |textlock| applies. It is possible to call |nvim_chan_send()| directly in the callback however. `["input", term, bufnr, data]` - • force_crlf: (boolean, default true) Convert "\n" to "\r\n". Return: ~ (`integer`) Channel id, or 0 on error @@ -1849,24 +1849,24 @@ nvim__redraw({opts}) *nvim__redraw()* Parameters: ~ • {opts} (`vim.api.keyset.redraw`) Optional parameters. - • win: Target a specific |window-ID| as described below. • buf: Target a specific buffer number as described below. + • cursor: Immediately update cursor position on the screen in + `win` or the current window. • flush: Update the screen with pending updates. - • valid: When present mark `win`, `buf`, or all windows for - redraw. When `true`, only redraw changed lines (useful for - decoration providers). When `false`, forcefully redraw. • range: Redraw a range in `buf`, the buffer in `win` or the current buffer (useful for decoration providers). Expects a tuple `[first, last]` with the first and last line number of the range, 0-based end-exclusive |api-indexing|. - • cursor: Immediately update cursor position on the screen in - `win` or the current window. • statuscolumn: Redraw the 'statuscolumn' in `buf`, `win` or all windows. • statusline: Redraw the 'statusline' in `buf`, `win` or all windows. - • winbar: Redraw the 'winbar' in `buf`, `win` or all windows. • tabline: Redraw the 'tabline'. + • valid: When present mark `win`, `buf`, or all windows for + redraw. When `true`, only redraw changed lines (useful for + decoration providers). When `false`, forcefully redraw. + • win: Target a specific |window-ID| as described below. + • winbar: Redraw the 'winbar' in `buf`, `win` or all windows. See also: ~ • |:redraw| @@ -2065,20 +2065,20 @@ nvim_clear_autocmds({opts}) *nvim_clear_autocmds()* Parameters: ~ • {opts} (`vim.api.keyset.clear_autocmds`) Optional parameters: + • buf: (`integer?`) Select |autocmd-buflocal| autocommands. + Not allowed with {pattern}. • event: (`vim.api.keyset.events|vim.api.keyset.events[]?`) Examples: • event: "pat1" • event: { "pat1" } • event: { "pat1", "pat2", "pat3" } + • group: (`string|int?`) Group name or id. + • NOTE: If not given, matches autocmds not in any group. • pattern: (`string|table?`) Filter by patterns (exact match). Not allowed with {buf}. • Example: if you have `*.py` as that pattern for the autocmd, you must pass `*.py` exactly to clear it. `test.py` will not match the pattern. - • buf: (`integer?`) Select |autocmd-buflocal| autocommands. - Not allowed with {pattern}. - • group: (`string|int?`) Group name or id. - • NOTE: If not given, matches autocmds not in any group. nvim_create_augroup({name}, {opts}) *nvim_create_augroup()* Create or get an autocommand group |autocmd-groups|. @@ -2228,16 +2228,16 @@ nvim_exec_autocmds({event}, {opts}) *nvim_exec_autocmds()* • {event} (`vim.api.keyset.events|vim.api.keyset.events[]`) Event(s) to execute. • {opts} (`vim.api.keyset.exec_autocmds`) Optional filters: - • group (`string|integer?`) Group name or id to match - against. |autocmd-groups|. - • pattern (`string|array?`, default: current file name) - |autocmd-pattern|. Not allowed with {buf}. • buf (`integer?`) Buffer id |autocmd-buflocal|. Not allowed with {pattern}. - • modeline (`boolean?`, default: true) Process the modeline - after the autocommands . • data (`any`): Arbitrary data passed to the callback. See |nvim_create_autocmd()|. + • group (`string|integer?`) Group name or id to match + against. |autocmd-groups|. + • modeline (`boolean?`, default: true) Process the modeline + after the autocommands . + • pattern (`string|array?`, default: current file name) + |autocmd-pattern|. Not allowed with {buf}. See also: ~ • |:doautocmd| @@ -2339,19 +2339,6 @@ nvim_buf_attach({buf}, {send_buffer}, {opts}) *nvim_buf_attach()* will be `nvim_buf_changedtick_event`. Not for Lua callbacks. • {opts} (`vim.api.keyset.buf_attach`) Optional parameters. - • on_lines: Called on linewise changes. Not called on - buffer reload (`:checktime`, `:edit`, …), see - `on_reload:`. Return a |lua-truthy| value to detach. - Args: - • the string "lines" - • buffer id - • b:changedtick - • first line that changed (zero-indexed) - • last line that was changed - • last line in the updated range - • byte count of previous contents - • deleted_codepoints (if `utf_sizes` is true) - • deleted_codeunits (if `utf_sizes` is true) • on_bytes: Called on granular changes (compared to on_lines). Not called on buffer reload (`:checktime`, `:edit`, …), see `on_reload:`. Return a @@ -2381,15 +2368,28 @@ nvim_buf_attach({buf}, {send_buffer}, {opts}) *nvim_buf_attach()* • on_detach: Called on detach. Args: • the string "detach" • buffer id + • on_lines: Called on linewise changes. Not called on + buffer reload (`:checktime`, `:edit`, …), see + `on_reload:`. Return a |lua-truthy| value to detach. + Args: + • the string "lines" + • buffer id + • b:changedtick + • first line that changed (zero-indexed) + • last line that was changed + • last line in the updated range + • byte count of previous contents + • deleted_codepoints (if `utf_sizes` is true) + • deleted_codeunits (if `utf_sizes` is true) • on_reload: Called on whole-buffer load (`:checktime`, `:edit`, …). Clients should typically re-fetch the entire buffer contents. Args: • the string "reload" • buffer id - • utf_sizes: include UTF-32 and UTF-16 size of the - replaced region, as args to `on_lines`. • preview: also attach to command preview (i.e. 'inccommand') events. + • utf_sizes: include UTF-32 and UTF-16 size of the + replaced region, as args to `on_lines`. Return: ~ (`boolean`) False if attach failed (invalid parameter, or buffer isn't @@ -2934,21 +2934,21 @@ nvim_create_user_command({name}, {cmd}, {opts}) 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 • args: (string) The args passed to the command, if any - • fargs: (table) The args split by unescaped whitespace (when - more than one argument is allowed), if any - • nargs: (string) Number of arguments |:command-nargs| • bang: (boolean) "true" if the command was executed with a ! modifier + • count: (number) Any count supplied + • fargs: (table) The args split by unescaped whitespace (when + more than one argument is allowed), if any • line1: (number) The starting line of the command range • line2: (number) The final line of the command range + • mods: (string) Command modifiers, if any + • name: (string) Command name + • nargs: (string) Number of arguments |:command-nargs| • range: (number) The number of items in the command range: 0, 1, or 2 - • count: (number) Any count supplied • reg: (string) The optional register, if specified - • mods: (string) Command modifiers, if any • smods: (table) Command modifiers in a structured format. Has the same structure as the "mods" key of |nvim_parse_cmd()|. • {opts} (`vim.api.keyset.user_command`) Optional flags @@ -3180,10 +3180,10 @@ nvim_buf_get_extmarks({buf}, {ns_id}, {start}, {end}, {opts}) valid extmark id (whose position defines the bound). |api-indexing| • {opts} (`vim.api.keyset.get_extmarks`) Optional parameters. Keys: - • limit: Maximum number of marks to return • details: Whether to include the details dict • hl_name: Whether to include highlight group name instead of id, true if omitted + • limit: Maximum number of marks to return • overlap: Also include marks which overlap the range, even if their start position is less than `start` • type: Filter marks by type: "highlight", "sign", @@ -3223,46 +3223,40 @@ nvim_buf_set_extmark({buf}, {ns_id}, {line}, {col}, {opts}) • {col} (`integer`) Column where to place the mark, 0-based. |api-indexing| • {opts} (`vim.api.keyset.set_extmark`) Optional parameters. - • id : id of the extmark to edit. - • end_row : ending line of the mark, 0-based inclusive. + • conceal: either a boolean or a string. + • when a string is given, it should be either empty or a + single character. Enable concealing similar to + |:syn-conceal|. When a character is supplied it is used + as |:syn-cchar|. "hl_group" is used as highlight for the + cchar if provided, otherwise it defaults to |hl-Conceal|. + • when a boolean is given, true is equivalent to "" and + false overrides any existing conceal to remove it. + • conceal_lines: string which should be empty. When provided, + lines in the range are not drawn at all (according to + 'conceallevel'); the next unconcealed line is drawn + instead. + • cursorline_hl_group: highlight group used for the sign + column text when the cursor is on the same line as the mark + and 'cursorline' is enabled. • end_col : ending col of the mark, 0-based exclusive, or -1 to extend the range to end of line (if strict=false). + • end_right_gravity : boolean that indicates the direction + the extmark end position (if it exists) will be shifted in + when new text is inserted (true for right, false for left). + Defaults to false. + • end_row : ending line of the mark, 0-based inclusive. + • ephemeral : for use with |nvim_set_decoration_provider()| + callbacks. The mark will only be used for the current + redraw cycle, and not be permanently stored in the buffer. + • 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 cursorline highlight). • 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 cursorline highlight). - • virt_text : *virtual-text* to link to this mark. A list of - `[text, highlight]` tuples, each representing a text chunk - with specified highlight. `highlight` element can either be - a single highlight group, or an array of multiple highlight - groups that will be stacked (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. - • "inline": display at the specified column, and shift the - buffer text to the right as needed. - • virt_text_win_col : position the virtual text at a fixed - window column (starting from the first text column of the - screen line) instead of "virt_text_pos". - • virt_text_hide : hide the virtual text when the background - text is selected or hidden because of scrolling with - 'nowrap' or 'smoothscroll'. Currently only affects - "overlay" virt_text. - • virt_text_repeat_linebreak : repeat the virtual text on - 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. @@ -3271,6 +3265,41 @@ nvim_buf_set_extmark({buf}, {ns_id}, {line}, {col}, {opts}) • "combine": combine with background text color. • "blend": blend with background text color. Not supported for "inline" virt_text. + • id : id of the extmark to edit. + • invalidate : boolean that indicates whether to hide the + extmark if the entirety of its range is deleted. For hidden + marks, an "invalid" key is added to the "details" array of + |nvim_buf_get_extmarks()| and family. If "undo_restore" is + false, the extmark is deleted instead. + • line_hl_group: highlight group used for the whole line. + • number_hl_group: highlight group used for the number + column. + • priority: a priority value for the highlight group, sign + attribute or virtual text. For virtual text, item with + highest priority is drawn last. For example treesitter + highlighting uses a value of 100. + • right_gravity : boolean that indicates the direction the + extmark will be shifted in when new text is inserted (true + for right, false for left). Defaults to true. + • sign_hl_group: highlight group used for the sign column + text. + • sign_text: string of length 1-2 used to display in the sign + column. + • spell: boolean indicating that spell checking should be + performed within this extmark + • strict: boolean that indicates extmark should not be placed + if the line or column value is past the end of the buffer + or end of the line respectively. Defaults to true. + • ui_watched: boolean that indicates the mark should be drawn + by a UI. When set, the UI will receive win_extmark events. + Note: the mark is positioned by virt_text attributes. Can + be used together with virt_text. + • undo_restore : Restore the exact position of the mark if + text around the mark was deleted and then restored by undo. + Defaults to true. + • url: A URL to associate with this extmark. In the TUI, the + OSC 8 control sequence is used to generate a clickable + hyperlink to this URL. • virt_lines : virtual lines to add next to this mark This should be an array over lines, where each line in turn is an array over `[text, highlight]` tuples. In general, @@ -3289,62 +3318,33 @@ nvim_buf_set_extmark({buf}, {ns_id}, {line}, {col}, {opts}) • "trunc": truncate virtual lines on the right (default). • "scroll": virtual lines can scroll horizontally with 'nowrap', otherwise the same as "trunc". - • ephemeral : for use with |nvim_set_decoration_provider()| - callbacks. The mark will only be used for the current - redraw cycle, and not be permanently stored in the buffer. - • right_gravity : boolean that indicates the direction the - extmark will be shifted in when new text is inserted (true - for right, false for left). Defaults to true. - • end_right_gravity : boolean that indicates the direction - the extmark end position (if it exists) will be shifted in - when new text is inserted (true for right, false for left). - Defaults to false. - • undo_restore : Restore the exact position of the mark if - text around the mark was deleted and then restored by undo. - Defaults to true. - • invalidate : boolean that indicates whether to hide the - extmark if the entirety of its range is deleted. For hidden - marks, an "invalid" key is added to the "details" array of - |nvim_buf_get_extmarks()| and family. If "undo_restore" is - false, the extmark is deleted instead. - • priority: a priority value for the highlight group, sign - attribute or virtual text. For virtual text, item with - highest priority is drawn last. For example treesitter - highlighting uses a value of 100. - • strict: boolean that indicates extmark should not be placed - if the line or column value is past the end of the buffer - or end of the line respectively. Defaults to true. - • sign_text: string of length 1-2 used to display in the sign - column. - • sign_hl_group: highlight group used for the sign column - text. - • number_hl_group: highlight group used for the number - column. - • line_hl_group: highlight group used for the whole line. - • cursorline_hl_group: highlight group used for the sign - column text when the cursor is on the same line as the mark - and 'cursorline' is enabled. - • conceal: either a boolean or a string. - • when a string is given, it should be either empty or a - single character. Enable concealing similar to - |:syn-conceal|. When a character is supplied it is used - as |:syn-cchar|. "hl_group" is used as highlight for the - cchar if provided, otherwise it defaults to |hl-Conceal|. - • when a boolean is given, true is equivalent to "" and - false overrides any existing conceal to remove it. - • conceal_lines: string which should be empty. When provided, - lines in the range are not drawn at all (according to - 'conceallevel'); the next unconcealed line is drawn - instead. - • spell: boolean indicating that spell checking should be - performed within this extmark - • ui_watched: boolean that indicates the mark should be drawn - by a UI. When set, the UI will receive win_extmark events. - Note: the mark is positioned by virt_text attributes. Can - be used together with virt_text. - • url: A URL to associate with this extmark. In the TUI, the - OSC 8 control sequence is used to generate a clickable - hyperlink to this URL. + • virt_text : *virtual-text* to link to this mark. A list of + `[text, highlight]` tuples, each representing a text chunk + with specified highlight. `highlight` element can either be + a single highlight group, or an array of multiple highlight + groups that will be stacked (highest priority last). + • virt_text_hide : hide the virtual text when the background + text is selected or hidden because of scrolling with + 'nowrap' or 'smoothscroll'. Currently only affects + "overlay" virt_text. + • 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. + • "inline": display at the specified column, and shift the + buffer text to the right as needed. + • virt_text_repeat_linebreak : repeat the virtual text on + wrapped lines. + • virt_text_win_col : position the virtual text at a fixed + window column (starting from the first text column of the + screen line) instead of "virt_text_pos". Return: ~ (`integer`) Id of the created/updated extmark @@ -3417,15 +3417,12 @@ nvim_set_decoration_provider({ns_id}, {opts}) • {ns_id} (`integer`) Namespace id from |nvim_create_namespace()| • {opts} (`vim.api.keyset.set_decoration_provider`) Table of callbacks: - • on_start: called first on each screen redraw > - ["start", tick] -< • on_buf: called for each buffer being redrawn (once per edit, before window callbacks) > ["buf", bufnr, tick] < - • on_win: called when starting to redraw a specific window. > - ["win", winid, bufnr, toprow, botrow] + • on_end: called at the end of a redraw cycle > + ["end", tick] < • on_line: (deprecated, use on_range instead) > ["line", winid, bufnr, row] @@ -3444,8 +3441,11 @@ nvim_set_decoration_provider({ns_id}, {opts}) a range which continues beyond the skipped position. A single integer return value `skip_row` is short for `skip_row, 0` - • on_end: called at the end of a redraw cycle > - ["end", tick] + • on_start: called first on each screen redraw > + ["start", tick] +< + • on_win: called when starting to redraw a specific window. > + ["win", winid, bufnr, toprow, botrow] < nvim__ns_get({ns_id}) *nvim__ns_get()* @@ -3517,11 +3517,11 @@ nvim_get_option_info2({name}, {opts}) *nvim_get_option_info2()* Parameters: ~ • {name} (`string`) Option name • {opts} (`vim.api.keyset.option`) Optional parameters + • buf: Buffer number. Used for getting buffer local options. + Implies {scope} is "local". • scope: One of "global" or "local". Analogous to |:setglobal| and |:setlocal|, respectively. • win: |window-ID|. Used for getting window local options. - • buf: Buffer number. Used for getting buffer local options. - Implies {scope} is "local". Return: ~ (`vim.api.keyset.get_option_info`) Option Information @@ -3538,15 +3538,15 @@ nvim_get_option_value({name}, {opts}) *nvim_get_option_value()* Parameters: ~ • {name} (`string`) Option name • {opts} (`vim.api.keyset.option`) Optional parameters - • scope: One of "global" or "local". Analogous to |:setglobal| - and |:setlocal|, respectively. - • win: |window-ID|. Used for getting window local options. • buf: Buffer number. Used for getting buffer local options. Implies {scope} is "local". • filetype: |filetype|. Used to get the default option for a specific filetype. Cannot be used with any other option. Note: this will trigger |ftplugin| and all |FileType| autocommands for the corresponding filetype. + • scope: One of "global" or "local". Analogous to |:setglobal| + and |:setlocal|, respectively. + • win: |window-ID|. Used for getting window local options. Return: ~ (`any`) Option value @@ -3566,10 +3566,10 @@ nvim_set_option_value({name}, {value}, {opts}) • {name} (`string`) Option name • {value} (`any`) New option value • {opts} (`vim.api.keyset.option`) Optional parameters + • buf: Buffer number. Used for setting buffer local option. • scope: One of "global" or "local". Analogous to |:setglobal| and |:setlocal|, respectively. • win: |window-ID|. Used for setting window local option. - • buf: Buffer number. Used for setting buffer local option. ============================================================================== @@ -4299,13 +4299,8 @@ nvim_win_text_height({win}, {opts}) *nvim_win_text_height()* Parameters: ~ • {win} (`integer`) |window-ID|, or 0 for current window. • {opts} (`vim.api.keyset.win_text_height`) Optional parameters: - • start_row: Starting line index, 0-based inclusive. When - omitted start at the very top. • end_row: Ending line index, 0-based inclusive. When omitted end at the very bottom. - • start_vcol: Starting virtual column index on "start_row", - 0-based inclusive, rounded down to full screen lines. When - omitted include the whole line. • end_vcol: Ending virtual column index on "end_row", 0-based exclusive, rounded up to full screen lines. When 0 only include diff filler and virtual lines above "end_row". When @@ -4316,6 +4311,11 @@ nvim_win_text_height({win}, {opts}) *nvim_win_text_height()* to find out how many buffer lines beyond "start_row" take up a certain number of logical lines (returned in "end_row" and "end_vcol"). + • start_row: Starting line index, 0-based inclusive. When + omitted start at the very top. + • start_vcol: Starting virtual column index on "start_row", + 0-based inclusive, rounded down to full screen lines. When + omitted include the whole line. Return: ~ (`vim.api.keyset.win_text_height_ret`) Dict containing text height diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 7fb406da25..9cf56cd077 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -447,48 +447,48 @@ Lua module: vim.diagnostic *diagnostic-api* Fields: ~ • {bufnr} (`integer`) Buffer number - • {end_lnum} (`integer`) The final line of the diagnostic (0-indexed) • {col} (`integer`) The starting column of the diagnostic (0-indexed) • {end_col} (`integer`) The final column of the diagnostic (0-indexed) + • {end_lnum} (`integer`) The final line of the diagnostic (0-indexed) + • {namespace}? (`integer`) • {severity} (`vim.diagnostic.Severity`) The severity of the diagnostic |vim.diagnostic.severity| - • {namespace}? (`integer`) *vim.Diagnostic.Set* Diagnostics use the same indexing as the rest of the Nvim API (i.e. 0-based rows and columns). |api-indexing| Fields: ~ - • {lnum} (`integer`) The starting line of the diagnostic - (0-indexed) + • {code}? (`string|integer`) The diagnostic code • {col}? (`integer`, default: `0`) The starting column of the diagnostic (0-indexed) - • {end_lnum}? (`integer`, default: `lnum`) The final line of the - diagnostic (0-indexed) • {end_col}? (`integer`, default: `col`) The final column of the diagnostic (0-indexed) + • {end_lnum}? (`integer`, default: `lnum`) The final line of the + diagnostic (0-indexed) + • {lnum} (`integer`) The starting line of the diagnostic + (0-indexed) + • {message} (`string`) The diagnostic text • {severity}? (`vim.diagnostic.Severity`, default: `vim.diagnostic.severity.ERROR`) The severity of the diagnostic |vim.diagnostic.severity| - • {message} (`string`) The diagnostic text • {source}? (`string`) The source of the diagnostic - • {code}? (`string|integer`) The diagnostic code • {user_data}? (`any`) arbitrary data plugins can add *vim.diagnostic.GetOpts* A table with the following keys: Fields: ~ - • {namespace}? (`integer[]|integer`) Limit diagnostics to one or more - namespaces. - • {lnum}? (`integer`) Limit diagnostics to those spanning the - specified line number. - • {severity}? (`vim.diagnostic.SeverityFilter`) See - |diagnostic-severity|. • {enabled}? (`boolean`, default: `nil`) Limit diagnostics to only enabled or disabled. If nil, enablement is ignored. See |vim.diagnostic.enable()| + • {lnum}? (`integer`) Limit diagnostics to those spanning the + specified line number. + • {namespace}? (`integer[]|integer`) Limit diagnostics to one or more + namespaces. + • {severity}? (`vim.diagnostic.SeverityFilter`) See + |diagnostic-severity|. *vim.diagnostic.JumpOpts* Extends: |vim.diagnostic.GetOpts| @@ -497,35 +497,35 @@ Lua module: vim.diagnostic *diagnostic-api* their default values changed with |vim.diagnostic.config()|. Fields: ~ - • {diagnostic}? (`vim.Diagnostic`) The diagnostic to jump to. Mutually - exclusive with {count}, {namespace}, and {severity}. - See |vim.Diagnostic|. • {count}? (`integer`) The number of diagnostics to move by, starting from {pos}. A positive integer moves forward by {count} diagnostics, while a negative integer moves backward by {count} diagnostics. Mutually exclusive with {diagnostic}. + • {diagnostic}? (`vim.Diagnostic`) The diagnostic to jump to. Mutually + exclusive with {count}, {namespace}, and {severity}. + See |vim.Diagnostic|. + • {on_jump}? (`fun(diagnostic:vim.Diagnostic?, bufnr:integer)`) + Optional callback invoked with the diagnostic that was + jumped to. • {pos}? (`[integer,integer]`) Cursor position as a `(row, col)` tuple. See |nvim_win_get_cursor()|. Used to find the nearest diagnostic when {count} is used. Only used when {count} is non-nil. Default is the current cursor position. - • {wrap}? (`boolean`, default: `true`) Whether to loop around - file or not. Similar to 'wrapscan'. • {severity}? (`vim.diagnostic.SeverityFilter`) See |diagnostic-severity|. - • {on_jump}? (`fun(diagnostic:vim.Diagnostic?, bufnr:integer)`) - Optional callback invoked with the diagnostic that was - jumped to. • {winid}? (`integer`, default: `0`) Window ID + • {wrap}? (`boolean`, default: `true`) Whether to loop around + file or not. Similar to 'wrapscan'. *vim.diagnostic.NS* Fields: ~ + • {disabled}? (`boolean`) • {name} (`string`) • {opts} (`vim.diagnostic.Opts`) See |vim.diagnostic.Opts|. • {user_data} (`table`) - • {disabled}? (`boolean`) *vim.diagnostic.Opts* Many of the configuration options below accept one of the following: @@ -537,29 +537,12 @@ Lua module: vim.diagnostic *diagnostic-api* of the above. Fields: ~ - • {underline}? (`boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline`, default: `true`) - Used to call attention to a diagnostic - ("underline" is a misnomer). Controls the - |hl-DiagnosticUnnecessary| and - |hl-DiagnosticDeprecated| highlights. - • {virtual_text}? (`boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText`, default: `false`) - Use virtual text for diagnostics. If multiple - diagnostics are set for a namespace, one prefix - per diagnostic + the last diagnostic message are - shown. - • {virtual_lines}? (`boolean|vim.diagnostic.Opts.VirtualLines|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualLines`, default: `false`) - Use virtual lines for diagnostics. - • {signs}? (`boolean|vim.diagnostic.Opts.Signs|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Signs`, default: `true`) - Use signs for diagnostics |diagnostic-signs|. • {float}? (`boolean|vim.diagnostic.Opts.Float|fun(namespace?: integer|integer[], bufnr:integer): vim.diagnostic.Opts.Float`) Options for floating windows. See |vim.diagnostic.Opts.Float|. - • {status}? (`vim.diagnostic.Opts.Status`) Options for the - statusline component. See - |vim.diagnostic.Opts.Status|. - • {update_in_insert}? (`boolean`, default: `false`) Update diagnostics - in Insert mode (if `false`, diagnostics are - updated on |InsertLeave|) + • {jump}? (`vim.diagnostic.Opts.Jump`) Default values for + |vim.diagnostic.jump()|. See + |vim.diagnostic.Opts.Jump|. • {severity_sort}? (`boolean|{reverse?:boolean}`, default: `false`) Sort diagnostics by severity. This affects the order in which signs, virtual text, and @@ -567,9 +550,26 @@ Lua module: vim.diagnostic *diagnostic-api* severities are displayed before lower severities (e.g. ERROR is displayed before WARN). Options: • {reverse}? (boolean) Reverse sort order - • {jump}? (`vim.diagnostic.Opts.Jump`) Default values for - |vim.diagnostic.jump()|. See - |vim.diagnostic.Opts.Jump|. + • {signs}? (`boolean|vim.diagnostic.Opts.Signs|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Signs`, default: `true`) + Use signs for diagnostics |diagnostic-signs|. + • {status}? (`vim.diagnostic.Opts.Status`) Options for the + statusline component. See + |vim.diagnostic.Opts.Status|. + • {underline}? (`boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline`, default: `true`) + Used to call attention to a diagnostic + ("underline" is a misnomer). Controls the + |hl-DiagnosticUnnecessary| and + |hl-DiagnosticDeprecated| highlights. + • {update_in_insert}? (`boolean`, default: `false`) Update diagnostics + in Insert mode (if `false`, diagnostics are + updated on |InsertLeave|) + • {virtual_lines}? (`boolean|vim.diagnostic.Opts.VirtualLines|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualLines`, default: `false`) + Use virtual lines for diagnostics. + • {virtual_text}? (`boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText`, default: `false`) + Use virtual text for diagnostics. If multiple + diagnostics are set for a namespace, one prefix + per diagnostic + the last diagnostic message are + shown. *vim.diagnostic.Opts.Float* Extends: |vim.lsp.util.open_floating_preview.Opts| @@ -578,34 +578,6 @@ Lua module: vim.diagnostic *diagnostic-api* Fields: ~ • {bufnr}? (`integer`, default: current buffer) Buffer number to show diagnostics from. - • {namespace}? (`integer|integer[]`) Limit diagnostics to the given - namespace(s). - • {scope}? (`'line'|'buffer'|'cursor'|'c'|'l'|'b'`, default: - `line`) Show diagnostics from the whole buffer - (`buffer`), the current cursor line (`line`), or the - current cursor position (`cursor`). Shorthand - versions are also accepted (`c` for `cursor`, `l` - for `line`, `b` for `buffer`). - • {pos}? (`integer|[integer,integer]`) If {scope} is "line" - or "cursor", use this position rather than the - cursor position. If a number, interpreted as a line - number; otherwise, a (row, col) tuple. - • {severity_sort}? (`boolean|{reverse?:boolean}`, default: `false`) - Sort diagnostics by severity. Overrides the setting - from |vim.diagnostic.config()|. - • {severity}? (`vim.diagnostic.SeverityFilter`) See - |diagnostic-severity|. Overrides the setting from - |vim.diagnostic.config()|. - • {header}? (`string|[string,any]`) String to use as the header - for the floating window. If a table, it is - interpreted as a `[text, hl_group]` tuple. Overrides - the setting from |vim.diagnostic.config()|. - • {source}? (`boolean|'if_many'`) Include the diagnostic source - in the message. Use "if_many" to only show sources - if there is more than one source of diagnostics in - the buffer. Otherwise, any truthy value means to - always show the diagnostic source. Overrides the - setting from |vim.diagnostic.config()|. • {format}? (`fun(diagnostic:vim.Diagnostic): string?`) A function that takes a diagnostic as input and returns a string or nil. If the return value is nil, @@ -613,6 +585,16 @@ Lua module: vim.diagnostic *diagnostic-api* the output text is used to display the diagnostic. Overrides the setting from |vim.diagnostic.config()|. + • {header}? (`string|[string,any]`) String to use as the header + for the floating window. If a table, it is + interpreted as a `[text, hl_group]` tuple. Overrides + the setting from |vim.diagnostic.config()|. + • {namespace}? (`integer|integer[]`) Limit diagnostics to the given + namespace(s). + • {pos}? (`integer|[integer,integer]`) If {scope} is "line" + or "cursor", use this position rather than the + cursor position. If a number, interpreted as a line + number; otherwise, a (row, col) tuple. • {prefix}? (`string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)`) Prefix each diagnostic in the floating window: • If a `function`, {i} is the index of the @@ -627,6 +609,24 @@ Lua module: vim.diagnostic *diagnostic-api* • If a `string`, it is prepended to each diagnostic in the window with no highlight. Overrides the setting from |vim.diagnostic.config()|. + • {scope}? (`'line'|'buffer'|'cursor'|'c'|'l'|'b'`, default: + `line`) Show diagnostics from the whole buffer + (`buffer`), the current cursor line (`line`), or the + current cursor position (`cursor`). Shorthand + versions are also accepted (`c` for `cursor`, `l` + for `line`, `b` for `buffer`). + • {severity}? (`vim.diagnostic.SeverityFilter`) See + |diagnostic-severity|. Overrides the setting from + |vim.diagnostic.config()|. + • {severity_sort}? (`boolean|{reverse?:boolean}`, default: `false`) + Sort diagnostics by severity. Overrides the setting + from |vim.diagnostic.config()|. + • {source}? (`boolean|'if_many'`) Include the diagnostic source + in the message. Use "if_many" to only show sources + if there is more than one source of diagnostics in + the buffer. Otherwise, any truthy value means to + always show the diagnostic source. Overrides the + setting from |vim.diagnostic.config()|. • {suffix}? (`string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)`) Same as {prefix}, but appends the text to the diagnostic instead of prepending it. Overrides the @@ -638,21 +638,27 @@ Lua module: vim.diagnostic *diagnostic-api* • {on_jump}? (`fun(diagnostic:vim.Diagnostic?, bufnr:integer)`) Default value of the {on_jump} parameter of |vim.diagnostic.jump()|. - • {wrap}? (`boolean`, default: true) Default value of the {wrap} - parameter of |vim.diagnostic.jump()|. • {severity}? (`vim.diagnostic.SeverityFilter`) Default value of the {severity} parameter of |vim.diagnostic.jump()|. + • {wrap}? (`boolean`, default: true) Default value of the {wrap} + parameter of |vim.diagnostic.jump()|. *vim.diagnostic.Opts.Signs* Fields: ~ - • {severity}? (`vim.diagnostic.SeverityFilter`) Only show signs for - diagnostics matching the given severity - |diagnostic-severity| + • {linehl}? (`table`) A table mapping + |diagnostic-severity| to the highlight group used for the + whole line the sign is placed in. + • {numhl}? (`table`) A table mapping + |diagnostic-severity| to the highlight group used for the + line number where the sign is placed. • {priority}? (`integer`, default: `10`) Base priority to use for signs. When {severity_sort} is used, the priority of a sign is adjusted based on its severity. Otherwise, all signs use the same priority. + • {severity}? (`vim.diagnostic.SeverityFilter`) Only show signs for + diagnostics matching the given severity + |diagnostic-severity| • {text}? (`table`) A table mapping |diagnostic-severity| to the sign text to display in the sign column. The default is to use `"E"`, `"W"`, `"I"`, @@ -662,12 +668,6 @@ Lua module: vim.diagnostic *diagnostic-api* signs = { text = { [vim.diagnostic.severity.ERROR] = 'E', ... } } }) < - • {numhl}? (`table`) A table mapping - |diagnostic-severity| to the highlight group used for the - line number where the sign is placed. - • {linehl}? (`table`) A table mapping - |diagnostic-severity| to the highlight group used for the - whole line the sign is placed in. *vim.diagnostic.Opts.Status* @@ -714,9 +714,6 @@ Lua module: vim.diagnostic *diagnostic-api* *vim.diagnostic.Opts.VirtualLines* Fields: ~ - • {severity}? (`vim.diagnostic.SeverityFilter`) Only show virtual - lines for diagnostics matching the given severity - |diagnostic-severity| • {current_line}? (`boolean`, default: `false`) Only show diagnostics for the current line. • {format}? (`fun(diagnostic:vim.Diagnostic): string?`) A @@ -724,36 +721,19 @@ Lua module: vim.diagnostic *diagnostic-api* a string or nil. If the return value is nil, the diagnostic is not displayed by the handler. Else the output text is used to display the diagnostic. + • {severity}? (`vim.diagnostic.SeverityFilter`) Only show virtual + lines for diagnostics matching the given severity + |diagnostic-severity| *vim.diagnostic.Opts.VirtualText* Fields: ~ - • {severity}? (`vim.diagnostic.SeverityFilter`) Only show - virtual text for diagnostics matching the given - severity |diagnostic-severity| • {current_line}? (`boolean`) Show or hide diagnostics based on the current cursor line. If `true`, only diagnostics on the current cursor line are shown. If `false`, all diagnostics are shown except on the current cursor line. If `nil`, all diagnostics are shown. (default `nil`) - • {source}? (`boolean|"if_many"`) Include the diagnostic - source in virtual text. Use `'if_many'` to only - show sources if there is more than one - diagnostic source in the buffer. Otherwise, any - truthy value means to always show the diagnostic - source. - • {spacing}? (`integer`) Amount of empty spaces inserted at - the beginning of the virtual text. - • {prefix}? (`string|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string)`) - Prepend diagnostic message with prefix. If a - `function`, {i} is the index of the diagnostic - being evaluated, and {total} is the total number - of diagnostics for the line. This can be used to - render diagnostic symbols or error codes. - • {suffix}? (`string|(fun(diagnostic:vim.Diagnostic): string)`) - Append diagnostic message with suffix. This can - be used to render an LSP diagnostic error code. • {format}? (`fun(diagnostic:vim.Diagnostic): string?`) If not nil, the return value is the text used to display the diagnostic. Example: >lua @@ -769,11 +749,31 @@ Lua module: vim.diagnostic *diagnostic-api* not displayed by the handler. • {hl_mode}? (`'replace'|'combine'|'blend'`) See |nvim_buf_set_extmark()|. + • {prefix}? (`string|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string)`) + Prepend diagnostic message with prefix. If a + `function`, {i} is the index of the diagnostic + being evaluated, and {total} is the total number + of diagnostics for the line. This can be used to + render diagnostic symbols or error codes. + • {severity}? (`vim.diagnostic.SeverityFilter`) Only show + virtual text for diagnostics matching the given + severity |diagnostic-severity| + • {source}? (`boolean|"if_many"`) Include the diagnostic + source in virtual text. Use `'if_many'` to only + show sources if there is more than one + diagnostic source in the buffer. Otherwise, any + truthy value means to always show the diagnostic + source. + • {spacing}? (`integer`) Amount of empty spaces inserted at + the beginning of the virtual text. + • {suffix}? (`string|(fun(diagnostic:vim.Diagnostic): string)`) + Append diagnostic message with suffix. This can + be used to render an LSP diagnostic error code. • {virt_text}? (`[string,any][]`) See |nvim_buf_set_extmark()|. + • {virt_text_hide}? (`boolean`) See |nvim_buf_set_extmark()|. • {virt_text_pos}? (`'eol'|'eol_right_align'|'inline'|'overlay'|'right_align'`) See |nvim_buf_set_extmark()|. • {virt_text_win_col}? (`integer`) See |nvim_buf_set_extmark()|. - • {virt_text_hide}? (`boolean`) See |nvim_buf_set_extmark()|. config({opts}, {namespace}) *vim.diagnostic.config()* @@ -829,10 +829,10 @@ enable({enable}, {filter}) *vim.diagnostic.enable()* Parameters: ~ • {enable} (`boolean?`) true/nil to enable, false to disable • {filter} (`table?`) Optional filters |kwargs|, or `nil` for all. - • {ns_id}? (`integer`) Diagnostic namespace, or `nil` for - all. • {bufnr}? (`integer`) Buffer number, or 0 for current buffer, or `nil` for all buffers. + • {ns_id}? (`integer`) Diagnostic namespace, or `nil` for + all. fromqflist({list}, {opts}) *vim.diagnostic.fromqflist()* Convert a list of quickfix items to a list of diagnostics. @@ -921,10 +921,10 @@ is_enabled({filter}) *vim.diagnostic.is_enabled()* Parameters: ~ • {filter} (`table?`) Optional filters |kwargs|, or `nil` for all. - • {ns_id}? (`integer`) Diagnostic namespace, or `nil` for - all. • {bufnr}? (`integer`) Buffer number, or 0 for current buffer, or `nil` for all buffers. + • {ns_id}? (`integer`) Diagnostic namespace, or `nil` for + all. Return: ~ (`boolean`) @@ -1009,41 +1009,41 @@ setloclist({opts}) *vim.diagnostic.setloclist()* Parameters: ~ • {opts} (`table?`) Configuration table with the following keys: - • {namespace}? (`integer[]|integer`) Only add diagnostics from - the given namespace(s). - • {winnr}? (`integer`, default: `0`) Window number to set - location list for. - • {open}? (`boolean`, default: `true`) Open the location list - after setting. - • {title}? (`string`) Title of the location list. Defaults to - "Diagnostics". - • {severity}? (`vim.diagnostic.SeverityFilter`) See - |diagnostic-severity|. • {format}? (`fun(diagnostic:vim.Diagnostic): string?`) A function that takes a diagnostic as input and returns a string or nil. If the return value is nil, the diagnostic is not displayed in the location list. Else the output text is used to display the diagnostic. + • {namespace}? (`integer[]|integer`) Only add diagnostics from + the given namespace(s). + • {open}? (`boolean`, default: `true`) Open the location list + after setting. + • {severity}? (`vim.diagnostic.SeverityFilter`) See + |diagnostic-severity|. + • {title}? (`string`) Title of the location list. Defaults to + "Diagnostics". + • {winnr}? (`integer`, default: `0`) Window number to set + location list for. setqflist({opts}) *vim.diagnostic.setqflist()* Add all diagnostics to the quickfix list. Parameters: ~ • {opts} (`table?`) Configuration table with the following keys: - • {namespace}? (`integer[]|integer`) Only add diagnostics from - the given namespace(s). - • {open}? (`boolean`, default: `true`) Open quickfix list - after setting. - • {title}? (`string`) Title of quickfix list. Defaults to - "Diagnostics". If there's already a quickfix list with this - title, it's updated. If not, a new quickfix list is created. - • {severity}? (`vim.diagnostic.SeverityFilter`) See - |diagnostic-severity|. • {format}? (`fun(diagnostic:vim.Diagnostic): string?`) A function that takes a diagnostic as input and returns a string or nil. If the return value is nil, the diagnostic is not displayed in the quickfix list. Else the output text is used to display the diagnostic. + • {namespace}? (`integer[]|integer`) Only add diagnostics from + the given namespace(s). + • {open}? (`boolean`, default: `true`) Open quickfix list + after setting. + • {severity}? (`vim.diagnostic.SeverityFilter`) See + |diagnostic-severity|. + • {title}? (`string`) Title of quickfix list. Defaults to + "Diagnostics". If there's already a quickfix list with this + title, it's updated. If not, a new quickfix list is created. *vim.diagnostic.show()* show({namespace}, {bufnr}, {diagnostics}, {opts}) diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 6f5f806b8f..98609a0d0b 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -1256,12 +1256,12 @@ get_clients({filter}) *vim.lsp.get_clients()* Parameters: ~ • {filter} (`table?`) Key-value pairs used to filter the returned clients. - • {id}? (`integer`) Only return clients with the given id • {bufnr}? (`integer`) Only return clients attached to this buffer - • {name}? (`string`) Only return clients with the given name + • {id}? (`integer`) Only return clients with the given id • {method}? (`string`) Only return clients supporting the given method + • {name}? (`string`) Only return clients with the given name Return: ~ (`vim.lsp.Client[]`) List of |vim.lsp.Client| objects @@ -1362,6 +1362,11 @@ start({config}, {opts}) *vim.lsp.start()* • {config} (`vim.lsp.ClientConfig`) Configuration for the server. See |vim.lsp.ClientConfig|. • {opts} (`table?`) Optional keyword arguments. + • {attach}? (`boolean`) Whether to attach the client to a + buffer (default true). If set to `false`, `reuse_client` + and `bufnr` will be ignored. + • {bufnr}? (`integer`) Buffer handle to attach to if + starting or re-using a client (0 for current). • {reuse_client}? (`fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean`) Predicate used to decide if a client should be re-used. @@ -1369,11 +1374,6 @@ start({config}, {opts}) *vim.lsp.start()* re-uses a client if it has the same name and if the given workspace folders (or root_dir) are all included in the client's workspace folders. - • {bufnr}? (`integer`) Buffer handle to attach to if - starting or re-using a client (0 for current). - • {attach}? (`boolean`) Whether to attach the client to a - buffer (default true). If set to `false`, `reuse_client` - and `bufnr` will be ignored. • {silent}? (`boolean`) Suppress error reporting if the LSP server fails to start (default false). @@ -1413,6 +1413,11 @@ the current buffer. *vim.lsp.ListOpts* Fields: ~ + • {loclist}? (`boolean`) Whether to use the |location-list| or the + |quickfix| list in the default handler. >lua + vim.lsp.buf.definition({ loclist = true }) + vim.lsp.buf.references(nil, { loclist = false }) +< • {on_list}? (`fun(what: vim.fn.setqflist.what)`) list-handler replacing the default handler. Called for any non-empty result. The default handler populates the quickfix (or @@ -1442,11 +1447,6 @@ the current buffer. See |setqflist-what| for the structure of the `what` parameter. - • {loclist}? (`boolean`) Whether to use the |location-list| or the - |quickfix| list in the default handler. >lua - vim.lsp.buf.definition({ loclist = true }) - vim.lsp.buf.references(nil, { loclist = false }) -< *vim.lsp.buf.hover.Opts* Extends: |vim.lsp.util.open_floating_preview.Opts| @@ -1480,6 +1480,9 @@ code_action({opts}) *vim.lsp.buf.code_action()* Parameters: ~ • {opts} (`table?`) A table with the following fields: + • {apply}? (`boolean`) When set to `true`, and there is just + one remaining action (after filtering), the action is + applied without user query. • {context}? (`table`) Corresponds to `lsp.CodeActionContext`, but all fields are optional: • {diagnostics}? (`lsp.Diagnostic[]`) Inferred from the @@ -1493,9 +1496,6 @@ code_action({opts}) *vim.lsp.buf.code_action()* (`fun(x: lsp.CodeAction|lsp.Command, client_id: integer):boolean`) Predicate taking a code action or command and the provider's ID. If it returns false, the action is filtered out. - • {apply}? (`boolean`) When set to `true`, and there is just - one remaining action (after filtering), the action is - applied without user query. • {range}? (`{start: integer[], end: integer[]}`) Range for which code actions should be requested. If in visual mode this defaults to the active selection. Table must contain @@ -1548,13 +1548,9 @@ format({opts}) *vim.lsp.buf.format()* Parameters: ~ • {opts} (`table?`) A table with the following fields: - • {formatting_options}? (`lsp.FormattingOptions`) Can be used - to specify FormattingOptions. Some unspecified options will - be automatically derived from the current Nvim options. See - https://microsoft.github.io/language-server-protocol/specification/#formattingOptions - • {timeout_ms}? (`integer`, default: `1000`) Time in - milliseconds to block for formatting requests. No effect if - async=true. + • {async}? (`boolean`, default: false) If true the method + won't block. Editing the buffer while formatting + asynchronous can lead to unexpected changes. • {bufnr}? (`integer`, default: current buffer) Restrict formatting to the clients attached to the given buffer. • {filter}? (`fun(client: vim.lsp.Client): boolean?`) @@ -1566,9 +1562,10 @@ format({opts}) *vim.lsp.buf.format()* filter = function(client) return client.name ~= "ts_ls" end } < - • {async}? (`boolean`, default: false) If true the method - won't block. Editing the buffer while formatting - asynchronous can lead to unexpected changes. + • {formatting_options}? (`lsp.FormattingOptions`) Can be used + to specify FormattingOptions. Some unspecified options will + be automatically derived from the current Nvim options. See + https://microsoft.github.io/language-server-protocol/specification/#formattingOptions • {id}? (`integer`) Restrict formatting to the client with ID (client.id) matching this field. • {name}? (`string`) Restrict formatting to the client with @@ -1581,6 +1578,9 @@ format({opts}) *vim.lsp.buf.format()* using (1,0) indexing. Can also be a list of tables that contain `start` and `end` keys as described above, in which case `textDocument/rangesFormatting` support is required. + • {timeout_ms}? (`integer`, default: `1000`) Time in + milliseconds to block for formatting requests. No effect if + async=true. hover({config}) *vim.lsp.buf.hover()* Displays hover information about the symbol under the cursor in a floating @@ -1647,13 +1647,13 @@ rename({new_name}, {opts}) *vim.lsp.buf.rename()* • {new_name} (`string?`) If not provided, the user will be prompted for a new name using |vim.ui.input()|. • {opts} (`table?`) Additional options: + • {bufnr}? (`integer`) (default: current buffer) • {filter}? (`fun(client: vim.lsp.Client): boolean?`) Predicate used to filter clients. Receives a client as argument and must return a boolean. Clients matching the predicate are included. • {name}? (`string`) Restrict clients used for rename to ones where client.name matches this field. - • {bufnr}? (`integer`) (default: current buffer) *vim.lsp.buf.selection_range()* selection_range({direction}, {timeout_ms}) @@ -1724,6 +1724,8 @@ Lua module: vim.lsp.client *lsp-client* Fields: ~ • {attached_buffers} (`table`) + • {cancel_request} (`fun(self: vim.lsp.Client, id: integer): boolean`) + See |Client:cancel_request()|. • {capabilities} (`lsp.ClientCapabilities`) Capabilities provided by the client (editor or tool), at startup. @@ -1734,6 +1736,8 @@ Lua module: vim.lsp.client *lsp-client* |vim.lsp.ClientConfig|. • {dynamic_capabilities} (`lsp.DynamicCapabilities`) Capabilities provided at runtime (after startup). + • {exec_cmd} (`fun(self: vim.lsp.Client, cmd: lsp.Command, context: {bufnr?: integer}?, handler: lsp.Handler?)`) + See |Client:exec_cmd()|. • {exit_timeout} (`integer|boolean`, default: `false`) See |vim.lsp.ClientConfig|. • {flags} (`table`) Experimental client flags: @@ -1750,13 +1754,23 @@ Lua module: vim.lsp.client *lsp-client* |vim.lsp.ClientConfig|. • {id} (`integer`) The id allocated to the client. • {initialized} (`true?`) + • {is_stopped} (`fun(self: vim.lsp.Client): boolean`) See + |Client:is_stopped()|. • {name} (`string`) See |vim.lsp.ClientConfig|. + • {notify} (`fun(self: vim.lsp.Client, method: string, params: table?): boolean`) + See |Client:notify()|. • {offset_encoding} (`'utf-8'|'utf-16'|'utf-32'`) See |vim.lsp.ClientConfig|. + • {on_attach} (`fun(self: vim.lsp.Client, bufnr: integer)`) + See |Client:on_attach()|. • {progress} (`vim.lsp.Client.Progress`) A ring buffer (|vim.ringbuf()|) containing progress messages sent by the server. See |vim.lsp.Client.Progress|. + • {request} (`fun(self: vim.lsp.Client, method: string, params: table?, handler: lsp.Handler?, bufnr: integer?): boolean, integer?`) + See |Client:request()|. + • {request_sync} (`fun(self: vim.lsp.Client, method: string, params: table, timeout_ms: integer?, bufnr: integer?): {err: lsp.ResponseError?, result:any}?, string?`) + See |Client:request_sync()|. • {requests} (`table`) The current pending requests in flight to the server. Entries are key-value pairs with the @@ -1779,26 +1793,12 @@ Lua module: vim.lsp.client *lsp-client* sent on `initialize` describing server information (e.g. version). • {settings} (`lsp.LSPObject`) See |vim.lsp.ClientConfig|. - • {workspace_folders} (`lsp.WorkspaceFolder[]?`) See - |vim.lsp.ClientConfig|. - • {request} (`fun(self: vim.lsp.Client, method: string, params: table?, handler: lsp.Handler?, bufnr: integer?): boolean, integer?`) - See |Client:request()|. - • {request_sync} (`fun(self: vim.lsp.Client, method: string, params: table, timeout_ms: integer?, bufnr: integer?): {err: lsp.ResponseError?, result:any}?, string?`) - See |Client:request_sync()|. - • {notify} (`fun(self: vim.lsp.Client, method: string, params: table?): boolean`) - See |Client:notify()|. - • {cancel_request} (`fun(self: vim.lsp.Client, id: integer): boolean`) - See |Client:cancel_request()|. • {stop} (`fun(self: vim.lsp.Client, force: integer|boolean?)`) See |Client:stop()|. - • {is_stopped} (`fun(self: vim.lsp.Client): boolean`) See - |Client:is_stopped()|. - • {exec_cmd} (`fun(self: vim.lsp.Client, cmd: lsp.Command, context: {bufnr?: integer}?, handler: lsp.Handler?)`) - See |Client:exec_cmd()|. - • {on_attach} (`fun(self: vim.lsp.Client, bufnr: integer)`) - See |Client:on_attach()|. • {supports_method} (`fun(self: vim.lsp.Client, method: string|string, bufnr: integer?): boolean`) See |Client:supports_method()|. + • {workspace_folders} (`lsp.WorkspaceFolder[]?`) See + |vim.lsp.ClientConfig|. *vim.lsp.Client.Progress* Extends: |vim.Ringbuf| @@ -2214,10 +2214,10 @@ enable({enable}, {client_id}, {bufnr}, {opts}) • {autotrigger}? (`boolean`) (default: false) When true, completion triggers automatically based on the server's `triggerCharacters`. - • {convert}? (`fun(item: lsp.CompletionItem): table`) - Transforms an LSP CompletionItem to |complete-items|. • {cmp}? (`fun(a: table, b: table): boolean`) Comparator for sorting merged completion items from all servers. + • {convert}? (`fun(item: lsp.CompletionItem): table`) + Transforms an LSP CompletionItem to |complete-items|. get({opts}) *vim.lsp.completion.get()* Triggers LSP completion once in the current buffer, if LSP completion is @@ -2459,10 +2459,10 @@ To try it out, here is a quickstart example using Copilot: *lsp-copilot* Fields: ~ • {client_id} (`integer`) Client ID + • {command}? (`lsp.Command`) Corresponding server command. • {insert_text} (`string|lsp.StringValue`) The text to be inserted, can be a snippet. • {range}? (`vim.Range`) Which range it be applied. - • {command}? (`lsp.Command`) Corresponding server command. enable({enable}, {filter}) *vim.lsp.inline_completion.enable()* @@ -2648,11 +2648,11 @@ Lua module: vim.lsp.rpc *lsp-rpc* Client RPC object Fields: ~ - • {request} (`fun(method: string, params: table?, callback: fun(err?: lsp.ResponseError, result: any, request_id: integer), notify_reply_callback?: fun(message_id: integer)):boolean,integer?`) - See |vim.lsp.rpc.request()| + • {is_closing} (`fun(): boolean`) Indicates if the RPC is closing. • {notify} (`fun(method: string, params: any): boolean`) See |vim.lsp.rpc.notify()| - • {is_closing} (`fun(): boolean`) Indicates if the RPC is closing. + • {request} (`fun(method: string, params: table?, callback: fun(err?: lsp.ResponseError, result: any, request_id: integer), notify_reply_callback?: fun(message_id: integer)):boolean,integer?`) + See |vim.lsp.rpc.request()| • {terminate} (`fun()`) Terminates the RPC client. @@ -2738,11 +2738,11 @@ start({cmd}, {dispatchers}, {extra_spawn_params}) *vim.lsp.rpc.start()* • {dispatchers} (`table?`) Dispatchers for LSP message types. • {notification} (`fun(method: string, params: table)`) - • {server_request} - (`fun(method: string, params: table): any?, lsp.ResponseError?`) + • {on_error} (`fun(code: integer, err: any)`) • {on_exit} (`fun(code: integer, signal: integer)`) - • {on_error} (`fun(code: integer, err: any)`) + • {server_request} + (`fun(method: string, params: table): any?, lsp.ResponseError?`) • {extra_spawn_params} (`table?`) Additional context for the LSP server process. • {cwd}? (`string`) Working directory for the @@ -2845,29 +2845,6 @@ Lua module: vim.lsp.util *lsp-util* *vim.lsp.util.open_floating_preview.Opts* Fields: ~ - • {height}? (`integer`) Height of floating window - • {width}? (`integer`) Width of floating window - • {wrap}? (`boolean`, default: `true`) Wrap long lines - • {wrap_at}? (`integer`) Character to wrap at for computing height - when wrap is enabled - • {max_width}? (`integer`) Maximal width of floating window - • {max_height}? (`integer`) Maximal height of floating window - • {focus_id}? (`string`) If a popup with this id is opened, then - focus it - • {close_events}? (`table`) List of events that closes the floating - window - • {focusable}? (`boolean`, default: `true`) Make float focusable. - • {focus}? (`boolean`, default: `true`) If `true`, and if - {focusable} is also `true`, focus an existing - floating window with the same {focus_id} - • {offset_x}? (`integer`) offset to add to `col` - • {offset_y}? (`integer`) offset to add to `row` - • {border}? (`string|(string|[string,string])[]`) override - `border` - • {zindex}? (`integer`) override `zindex`, defaults to 50 - • {title}? (`string|[string,string][]`) - • {title_pos}? (`'left'|'center'|'right'`) - • {relative}? (`'mouse'|'cursor'|'editor'`) (default: `'cursor'`) • {anchor_bias}? (`'auto'|'above'|'below'`, default: `'auto'`) Adjusts placement relative to cursor. • "auto": place window based on which side of the @@ -2878,6 +2855,29 @@ Lua module: vim.lsp.util *lsp-util* • "below": place the window below the cursor unless there are not enough lines to display the full window height. + • {border}? (`string|(string|[string,string])[]`) override + `border` + • {close_events}? (`table`) List of events that closes the floating + window + • {focus}? (`boolean`, default: `true`) If `true`, and if + {focusable} is also `true`, focus an existing + floating window with the same {focus_id} + • {focus_id}? (`string`) If a popup with this id is opened, then + focus it + • {focusable}? (`boolean`, default: `true`) Make float focusable. + • {height}? (`integer`) Height of floating window + • {max_height}? (`integer`) Maximal height of floating window + • {max_width}? (`integer`) Maximal width of floating window + • {offset_x}? (`integer`) offset to add to `col` + • {offset_y}? (`integer`) offset to add to `row` + • {relative}? (`'mouse'|'cursor'|'editor'`) (default: `'cursor'`) + • {title}? (`string|[string,string][]`) + • {title_pos}? (`'left'|'center'|'right'`) + • {width}? (`integer`) Width of floating window + • {wrap}? (`boolean`, default: `true`) Wrap long lines + • {wrap_at}? (`integer`) Character to wrap at for computing height + when wrap is enabled + • {zindex}? (`integer`) override `zindex`, defaults to 50 *vim.lsp.util.apply_text_document_edit()* @@ -3180,8 +3180,8 @@ rename({old_fname}, {new_fname}, {opts}) *vim.lsp.util.rename()* • {old_fname} (`string`) • {new_fname} (`string`) • {opts} (`table?`) Options: - • {overwrite}? (`boolean`) • {ignoreIfExists}? (`boolean`) + • {overwrite}? (`boolean`) *vim.lsp.util.show_document()* show_document({location}, {position_encoding}, {opts}) @@ -3191,10 +3191,10 @@ show_document({location}, {position_encoding}, {opts}) • {location} (`lsp.Location|lsp.LocationLink`) • {position_encoding} (`'utf-8'|'utf-16'|'utf-32'?`) • {opts} (`table?`) A table with the following fields: - • {reuse_win}? (`boolean`) Jump to existing - window if buffer is already open. • {focus}? (`boolean`) Whether to focus/jump to location if possible. (defaults: true) + • {reuse_win}? (`boolean`) Jump to existing + window if buffer is already open. Return: ~ (`boolean`) `true` if succeeded diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 0a5017e1c5..f2f847029a 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1538,15 +1538,15 @@ vim.inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()* • {col} (`integer?`) col to inspect, 0-based. Defaults to the col of the current cursor • {filter} (`table?`) Table with key-value pairs to filter the items - • {syntax} (`boolean`, default: `true`) Include syntax based - highlight groups. - • {treesitter} (`boolean`, default: `true`) Include - treesitter based highlight groups. • {extmarks} (`boolean|"all"`, default: true) Include extmarks. When `all`, then extmarks without a `hl_group` will also be included. • {semantic_tokens} (`boolean`, default: true) Include semantic token highlights. + • {syntax} (`boolean`, default: `true`) Include syntax based + highlight groups. + • {treesitter} (`boolean`, default: `true`) Include + treesitter based highlight groups. Return: ~ (`table`) a table with the following key-value pairs. Items are in @@ -1579,15 +1579,15 @@ vim.show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()* • {col} (`integer?`) col to inspect, 0-based. Defaults to the col of the current cursor • {filter} (`table?`) A table with the following fields: - • {syntax} (`boolean`, default: `true`) Include syntax based - highlight groups. - • {treesitter} (`boolean`, default: `true`) Include - treesitter based highlight groups. • {extmarks} (`boolean|"all"`, default: true) Include extmarks. When `all`, then extmarks without a `hl_group` will also be included. • {semantic_tokens} (`boolean`, default: true) Include semantic token highlights. + • {syntax} (`boolean`, default: `true`) Include syntax based + highlight groups. + • {treesitter} (`boolean`, default: `true`) Include + treesitter based highlight groups. @@ -1596,9 +1596,9 @@ vim.show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()* Fields: ~ • {clear} (`fun()`) See |Ringbuf:clear()|. - • {push} (`fun(item: T)`) See |Ringbuf:push()|. - • {pop} (`fun(): T?`) See |Ringbuf:pop()|. • {peek} (`fun(): T?`) See |Ringbuf:peek()|. + • {pop} (`fun(): T?`) See |Ringbuf:pop()|. + • {push} (`fun(item: T)`) See |Ringbuf:push()|. Ringbuf:clear() *Ringbuf:clear()* @@ -1807,17 +1807,17 @@ vim.list.bisect({t}, {val}, {opts}) *vim.list.bisect()* • {t} (`any[]`) A comparable list. • {val} (`any`) The value to search. • {opts} (`table?`) A table with the following fields: - • {lo}? (`integer`, default: `1`) Start index of the list. - • {hi}? (`integer`, default: `#t + 1`) End index of the list, - exclusive. - • {key}? (`fun(val: any): any`) Optional, compare the return - value instead of the {val} itself if provided. • {bound}? (`'lower'|'upper'`, default: `'lower'`) Specifies the search variant. • "lower": returns the first position where inserting {val} keeps the list sorted. • "upper": returns the last position where inserting {val} keeps the list sorted.. + • {hi}? (`integer`, default: `#t + 1`) End index of the list, + exclusive. + • {key}? (`fun(val: any): any`) Optional, compare the return + value instead of the {val} itself if provided. + • {lo}? (`integer`, default: `1`) Start index of the list. Return: ~ (`integer`) index serves as either the lower bound or the upper bound @@ -2377,9 +2377,9 @@ vim.filetype.add({filetypes}) *vim.filetype.add()* Parameters: ~ • {filetypes} (`table`) A table containing new filetype maps (see example). - • {pattern}? (`vim.filetype.mapping`) • {extension}? (`vim.filetype.mapping`) • {filename}? (`vim.filetype.mapping`) + • {pattern}? (`vim.filetype.mapping`) *vim.filetype.get_option()* vim.filetype.get_option({filetype}, {option}) @@ -2457,6 +2457,9 @@ vim.filetype.match({args}) *vim.filetype.match()* Accepted keys are: • {buf}? (`integer`) Buffer number to use for matching. Mutually exclusive with {contents} + • {contents}? (`string[]`) An array of lines representing file + contents to use for matching. Can be used with {filename}. + Mutually exclusive with {buf}. • {filename}? (`string`) Filename to use for matching. When {buf} is given, defaults to the filename of the given buffer number. The file need not actually exist in the filesystem. @@ -2464,9 +2467,6 @@ vim.filetype.match({args}) *vim.filetype.match()* for filetype matching. This may result in failure to detect the filetype in cases where the filename alone is not enough to disambiguate the filetype. - • {contents}? (`string[]`) An array of lines representing file - contents to use for matching. Can be used with {filename}. - Mutually exclusive with {buf}. Return (multiple): ~ (`string?`) The matched filetype, if any. @@ -2558,12 +2558,12 @@ vim.fs.dir({path}, {opts}) *vim.fs.dir()* |vim.fs.normalize()|. • {opts} (`table?`) Optional keyword arguments: • {depth}? (`integer`, default: `1`) How deep to traverse. + • {follow}? (`boolean`, default: `false`) Follow symbolic + links. • {skip}? (`fun(dir_name: string): boolean`) Predicate to control traversal. Return false to stop searching the current directory. Only useful when depth > 1 Return an iterator over the items located in {path} - • {follow}? (`boolean`, default: `false`) Follow symbolic - links. Return: ~ (`Iterator`) over items in {path}. Each iteration yields two values: @@ -2648,19 +2648,19 @@ vim.fs.find({names}, {opts}) *vim.fs.find()* The function should return `true` if the given item is considered a match. • {opts} (`table?`) Optional keyword arguments: + • {follow}? (`boolean`, default: `false`) Follow symbolic + links. + • {limit}? (`number`, default: `1`) Stop searching after this + many matches. Use `math.huge` for "unlimited". • {path}? (`string`) Path to begin searching from, defaults to |current-directory|. Not expanded. - • {upward}? (`boolean`, default: `false`) Search upward - through parent directories. Otherwise, search child - directories (recursively). • {stop}? (`string`) Stop searching when this directory is reached. The directory itself is not searched. • {type}? (`string`) Find only items of the given type. If omitted, all items that match {names} are included. - • {limit}? (`number`, default: `1`) Stop searching after this - many matches. Use `math.huge` for "unlimited". - • {follow}? (`boolean`, default: `false`) Follow symbolic - links. + • {upward}? (`boolean`, default: `false`) Search upward + through parent directories. Otherwise, search child + directories (recursively). Return: ~ (`string[]`) Normalized paths |vim.fs.normalize()| of all matching @@ -2793,9 +2793,9 @@ vim.fs.rm({path}, {opts}) *vim.fs.rm()* Parameters: ~ • {path} (`string`) Path to remove (not expanded/resolved). • {opts} (`table?`) A table with the following fields: + • {force}? (`boolean`) Ignore nonexistent files and arguments. • {recursive}? (`boolean`) Remove directory contents recursively. - • {force}? (`boolean`) Ignore nonexistent files and arguments. vim.fs.root({source}, {marker}) *vim.fs.root()* Find the first parent directory containing a specific "marker", relative @@ -2903,15 +2903,15 @@ vim.hl.on_yank({opts}) *vim.hl.on_yank()* Parameters: ~ • {opts} (`table?`) Optional parameters + • event event structure (default vim.v.event) • higroup highlight group for yanked region (default "IncSearch") - • timeout time in ms before highlight is cleared (default 150) • on_macro highlight when executing macro (default false) • on_visual highlight when yanking visual selection (default true) - • event event structure (default vim.v.event) • priority integer priority (default |vim.hl.priorities|`.user`) + • timeout time in ms before highlight is cleared (default 150) vim.hl.priorities *vim.hl.priorities* Table with default priorities used for highlighting: @@ -2935,12 +2935,12 @@ vim.hl.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts}) • {finish} (`[integer,integer]|string`) End of region as a (line, column) tuple or string accepted by |getpos()| • {opts} (`table?`) A table with the following fields: - • {regtype}? (`string`, default: `'v'` i.e. charwise) Type - of range. See |getregtype()| • {inclusive}? (`boolean`, default: `false`) Indicates whether the range is end-inclusive • {priority}? (`integer`, default: `vim.hl.priorities.user`) Highlight priority + • {regtype}? (`string`, default: `'v'` i.e. charwise) Type + of range. See |getregtype()| • {timeout}? (`integer`, default: -1 no timeout) Time in ms before highlight is cleared @@ -3742,21 +3742,21 @@ vim.loader.find({modname}, {opts}) *vim.loader.find()* • {modname} (`string`) Module name, or `"*"` to find the top-level modules instead • {opts} (`table?`) Options for finding a module: - • {rtp}? (`boolean`, default: `true`) Search for modname in - the runtime path. + • {all}? (`boolean`, default: `false`) Search for all + matches. • {paths}? (`string[]`, default: `{}`) Extra paths to search for modname • {patterns}? (`string[]`, default: `{"/init.lua", ".lua"}`) List of patterns to use when searching for modules. A pattern is a string added to the basename of the Lua module being searched. - • {all}? (`boolean`, default: `false`) Search for all - matches. + • {rtp}? (`boolean`, default: `true`) Search for modname in + the runtime path. Return: ~ (`table[]`) A list of objects with the following fields: - • {modpath} (`string`) Path of the module • {modname} (`string`) Name of the module + • {modpath} (`string`) Path of the module • {stat}? (`uv.fs_stat.result`) The fs_stat of the module path. Won't be returned for `modname="*"` @@ -4240,18 +4240,18 @@ vim.net.request({url}, {opts}, {on_response}) *vim.net.request()* Parameters: ~ • {url} (`string`) The URL for the request. • {opts} (`table?`) A table with the following fields: - • {verbose}? (`boolean`) Enables verbose output. - • {retry}? (`integer`) Number of retries on transient - failures (default: 3). - • {outpath}? (`string`) File path to save the response - body to. - • {outbuf}? (`integer`) Buffer to save the response - body to. • {headers}? (`table`) Custom headers to send with the request. Supports basic key/value headers and empty headers as supported by curl. Does not support "@filename" style, internal header deletion ("Header:"). + • {outbuf}? (`integer`) Buffer to save the response + body to. + • {outpath}? (`string`) File path to save the response + body to. + • {retry}? (`integer`) Number of retries on transient + failures (default: 3). + • {verbose}? (`boolean`) Enables verbose output. • {on_response} (`fun(err: string?, response: vim.net.request.Response?)?`) Callback invoked on request completion. The `body` field in the response parameter contains the raw @@ -4297,9 +4297,9 @@ by |vim.Pos| objects. as format conversions. Fields: ~ - • {row} (`integer`) 0-based byte index. - • {col} (`integer`) 0-based byte index. • {buf} (`integer`) buffer handle. + • {col} (`integer`) 0-based byte index. + • {row} (`integer`) 0-based byte index. cursor({buf}, {pos}) *vim.pos.cursor()* @@ -4409,11 +4409,11 @@ Provides operations to compare, calculate, and convert ranges represented by < Fields: ~ - • {start_row} (`integer`) 0-based byte index. - • {start_col} (`integer`) 0-based byte index. - • {end_row} (`integer`) 0-based byte index. - • {end_col} (`integer`) 0-based byte index. • {buf} (`integer`) Optional buffer handle. + • {end_col} (`integer`) 0-based byte index. + • {end_row} (`integer`) 0-based byte index. + • {start_col} (`integer`) 0-based byte index. + • {start_row} (`integer`) 0-based byte index. cursor({buf}, {start_pos}, {end_pos}) *vim.range.cursor()* @@ -4705,10 +4705,10 @@ vim.secure.trust({opts}) *vim.secure.trust()* it, • `'deny'` to add a file to the trust database and deny it, • `'remove'` to remove file from the trust database - • {path}? (`string`) Path to a file to update. Mutually - exclusive with {bufnr}. • {bufnr}? (`integer`) Buffer number to update. Mutually exclusive with {path}. + • {path}? (`string`) Path to a file to update. Mutually + exclusive with {bufnr}. Return (multiple): ~ (`boolean`) success true if operation was successful @@ -4814,24 +4814,24 @@ Lua module: vim.system *lua-vim-system* Fields: ~ • {code} (`integer`) • {signal} (`integer`) - • {stdout}? (`string`) `nil` if stdout is disabled or has a custom - handler. • {stderr}? (`string`) `nil` if stderr is disabled or has a custom handler. + • {stdout}? (`string`) `nil` if stdout is disabled or has a custom + handler. *vim.SystemObj* Fields: ~ • {cmd} (`string[]`) Command name and args - • {pid} (`integer`) Process ID + • {is_closing} (`fun(self: vim.SystemObj): boolean`) See + |SystemObj:is_closing()|. • {kill} (`fun(self: vim.SystemObj, signal: integer|string)`) See |SystemObj:kill()|. + • {pid} (`integer`) Process ID • {wait} (`fun(self: vim.SystemObj, timeout: integer?): vim.SystemCompleted`) See |SystemObj:wait()|. • {write} (`fun(self: vim.SystemObj, data: string[]|string?)`) See |SystemObj:write()|. - • {is_closing} (`fun(self: vim.SystemObj): boolean`) See - |SystemObj:is_closing()|. SystemObj:is_closing() *SystemObj:is_closing()* @@ -4930,28 +4930,12 @@ vim.system({cmd}, {opts}, {on_exit}) *vim.system()* Parameters: ~ • {cmd} (`string[]`) Command to execute • {opts} (`table?`) A table with the following fields: - • {cwd}? (`string`) Set the current working directory for - the sub-process. - • {env}? (`table`) Set environment - variables for the new process. Inherits the current - environment with `NVIM` set to |v:servername|. • {clear_env}? (`boolean`) `env` defines the job environment exactly, instead of merging current environment. Note: if `env` is `nil`, the current environment is used but without `NVIM` set. - • {stdin}? (`string|string[]|true`) If `true`, then a pipe - to stdin is opened and can be written to via the - `write()` method to SystemObj. If `string` or `string[]` - then will be written to stdin and closed. - • {stdout}? (`fun(err:string?, data: string?)|boolean`, - default: `true`) Handle output from stdout. - • {stderr}? (`fun(err:string?, data: string?)|boolean`, - default: `true`) Handle output from stderr. - • {text}? (`boolean`) Handle stdout and stderr as text. - Normalizes line endings by replacing `\r\n` with `\n`. - • {timeout}? (`integer`) Run the command with a time limit - in ms. Upon timeout the process is sent the TERM signal - (15) and the exit code is set to 124. + • {cwd}? (`string`) Set the current working directory for + the sub-process. • {detach}? (`boolean`) Spawn the child process in a detached state - this will make it a process group leader, and will effectively enable the child to keep @@ -4959,6 +4943,22 @@ vim.system({cmd}, {opts}, {on_exit}) *vim.system()* process will still keep the parent's event loop alive unless the parent process calls |uv.unref()| on the child's process handle. + • {env}? (`table`) Set environment + variables for the new process. Inherits the current + environment with `NVIM` set to |v:servername|. + • {stderr}? (`fun(err:string?, data: string?)|boolean`, + default: `true`) Handle output from stderr. + • {stdin}? (`string|string[]|true`) If `true`, then a pipe + to stdin is opened and can be written to via the + `write()` method to SystemObj. If `string` or `string[]` + then will be written to stdin and closed. + • {stdout}? (`fun(err:string?, data: string?)|boolean`, + default: `true`) Handle output from stdout. + • {text}? (`boolean`) Handle stdout and stderr as text. + Normalizes line endings by replacing `\r\n` with `\n`. + • {timeout}? (`integer`) Run the command with a time limit + in ms. Upon timeout the process is sent the TERM signal + (15) and the exit code is set to 124. • {on_exit} (`fun(out: vim.SystemCompleted)?`) Called when subprocess exits. When provided, the command runs asynchronously. See return of SystemObj:wait(). @@ -4996,6 +4996,29 @@ vim.text.diff({a}, {b}, {opts}) *vim.text.diff()* • {a} (`string`) First string to compare • {b} (`string`) Second string to compare • {opts} (`table?`) Optional parameters: + • {algorithm}? (`'myers'|'minimal'|'patience'|'histogram'`, + default: `'myers'`) Diff algorithm to use. Values: + • `myers`: the default algorithm + • `minimal`: spend extra time to generate the smallest + possible diff + • `patience`: patience diff algorithm + • `histogram`: histogram diff algorithm + • {ctxlen}? (`integer`) Context length + • {ignore_blank_lines}? (`boolean`) Ignore blank lines + • {ignore_cr_at_eol}? (`boolean`) Ignore carriage return at + end-of-line + • {ignore_whitespace}? (`boolean`) Ignore whitespace + • {ignore_whitespace_change}? (`boolean`) Ignore whitespace + change + • {ignore_whitespace_change_at_eol}? (`boolean`) Ignore + whitespace change at end-of-line. + • {indent_heuristic}? (`boolean`) Use the indent heuristic for + the internal diff library. + • {interhunkctxlen}? (`integer`) Inter hunk context length + • {linematch}? (`boolean|integer`) Run linematch on the + resulting hunks from xdiff. When integer, only hunks upto + this size in lines are run through linematch. Requires + `result_type = indices`, ignored otherwise. • {on_hunk}? (`fun(start_a: integer, count_a: integer, start_b: integer, count_b: integer): integer?`) Invoked for each hunk in the diff. Return a negative number @@ -5009,29 +5032,6 @@ vim.text.diff({a}, {b}, {opts}) *vim.text.diff()* • `unified`: String in unified format. • `indices`: Array of hunk locations. Note: This option is ignored if `on_hunk` is used. - • {linematch}? (`boolean|integer`) Run linematch on the - resulting hunks from xdiff. When integer, only hunks upto - this size in lines are run through linematch. Requires - `result_type = indices`, ignored otherwise. - • {algorithm}? (`'myers'|'minimal'|'patience'|'histogram'`, - default: `'myers'`) Diff algorithm to use. Values: - • `myers`: the default algorithm - • `minimal`: spend extra time to generate the smallest - possible diff - • `patience`: patience diff algorithm - • `histogram`: histogram diff algorithm - • {ctxlen}? (`integer`) Context length - • {interhunkctxlen}? (`integer`) Inter hunk context length - • {ignore_whitespace}? (`boolean`) Ignore whitespace - • {ignore_whitespace_change}? (`boolean`) Ignore whitespace - change - • {ignore_whitespace_change_at_eol}? (`boolean`) Ignore - whitespace change at end-of-line. - • {ignore_cr_at_eol}? (`boolean`) Ignore carriage return at - end-of-line - • {ignore_blank_lines}? (`boolean`) Ignore blank lines - • {indent_heuristic}? (`boolean`) Use the indent heuristic for - the internal diff library. Return: ~ (`string|integer[][]?`) See {opts.result_type}. `nil` if @@ -5107,14 +5107,14 @@ vim.ui.input({opts}, {on_confirm}) *vim.ui.input()* Parameters: ~ • {opts} (`table?`) Additional options. See |input()| - • {prompt}? (`string`) Text of the prompt - • {default}? (`string`) Default reply to the input • {completion}? (`string`) Specifies type of completion supported for input. Supported types are the same that can be supplied to a user-defined command using the "-complete=" argument. See |:command-completion| + • {default}? (`string`) Default reply to the input • {highlight}? (`function`) Function that will be used for highlighting user inputs. + • {prompt}? (`string`) Text of the prompt • {on_confirm} (`fun(input?: string)`) Called once the user confirms or abort the input. `input` is what the user typed (it might be an empty string if nothing was entered), or @@ -5195,11 +5195,13 @@ vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()* Parameters: ~ • {items} (`any[]`) Arbitrary items • {opts} (`table`) Options - • {prompt}? (`string`, default: `"Select one of:"`) - Prompt text. • {format_item}? (`fun(item: any):string`, default: `tostring`) Decides how to format items when displayed in the picker. + • {kind}? (`string`) Arbitrary hint string indicating the + item shape. The picker may wish to use this to infer + the structure or semantics of `items`, or the context + in which select() was called. • {preview_item}? (`fun(item: any):{buf?:integer, pos?:[integer,integer], pos_end?:[integer,integer]}`) Decides how to preview an item by preparing a scratch @@ -5216,10 +5218,8 @@ vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()* (1,0)-indexed (end-exclusive) end position of the preview range. If nil, no range is intended for a preview. - • {kind}? (`string`) Arbitrary hint string indicating the - item shape. The picker may wish to use this to infer - the structure or semantics of `items`, or the context - in which select() was called. + • {prompt}? (`string`, default: `"Select one of:"`) + Prompt text. • {on_choice} (`fun(item: T?, idx: integer?)`) Called once the user made a choice. `idx` is the 1-based index of `item` within `items`, or `nil` if the user aborted the dialog. @@ -5343,9 +5343,9 @@ versions (1.2.3-rc1) are not matched. > Fields: ~ • {from} (`vim.Version`) - • {to}? (`vim.Version`) • {has} (`fun(self: vim.VersionRange, version: string|vim.Version): boolean`) See |VersionRange:has()|. + • {to}? (`vim.Version`) VersionRange:has({version}) *VersionRange:has()* diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt index 9ec47b9fb4..299b93e99f 100644 --- a/runtime/doc/pack.txt +++ b/runtime/doc/pack.txt @@ -401,10 +401,11 @@ These events can be used to execute plugin hooks. For example: >lua *vim.pack.Spec* Fields: ~ - • {src} (`string`) URI from which to install and pull updates. Any - format supported by `git clone` is allowed. + • {data}? (`any`) Arbitrary data associated with a plugin. • {name}? (`string`) Name of plugin. Will be used as directory name. Default: `src` repository name. + • {src} (`string`) URI from which to install and pull updates. Any + format supported by `git clone` is allowed. • {version}? (`string|vim.VersionRange`) Version to use for install and updates. Can be: • `nil` (no value, default) to use repository's default @@ -412,7 +413,6 @@ These events can be used to execute plugin hooks. For example: >lua • String to use specific branch, tag, or commit hash. • Output of |vim.version.range()| to install the greatest/last semver tag inside the version constraint. - • {data}? (`any`) Arbitrary data associated with a plugin. add({specs}, {opts}) *vim.pack.add()* @@ -442,14 +442,14 @@ add({specs}, {opts}) *vim.pack.add()* • {specs} (`(string|vim.pack.Spec)[]`) List of plugin specifications. String item is treated as `src`. • {opts} (`table?`) A table with the following fields: + • {confirm}? (`boolean`) Whether to ask user to confirm + initial install. Default `true`. • {load}? (`boolean|fun(plug_data: {spec: vim.pack.Spec, path: string})`) Load `plugin/` files and `ftdetect/` scripts. If `false`, works like `:packadd!`. If function, called with plugin data and is fully responsible for loading plugin. Default `false` during |init.lua| sourcing and `true` afterwards. - • {confirm}? (`boolean`) Whether to ask user to confirm - initial install. Default `true`. del({names}, {opts}) *vim.pack.del()* Remove plugins from disk diff --git a/runtime/doc/plugins.txt b/runtime/doc/plugins.txt index 71dbc051e3..b619f5d3ce 100644 --- a/runtime/doc/plugins.txt +++ b/runtime/doc/plugins.txt @@ -75,10 +75,10 @@ open({left}, {right}, {opt}) *difftool.open()* similarity for rename detection (0 to 1) • {rename.chunk_size} (`number`, default: `4096`) Maximum chunk size to read from files for similarity calculation - • {method} (`'auto'|'builtin'|'diffr'`, default: `auto`) Diff - method to use • {ignore} (`string[]`, default: `{}`) List of file patterns to ignore (for example: `'.git', '*.log'`) + • {method} (`'auto'|'builtin'|'diffr'`, default: `auto`) Diff + method to use • {rename} (`table`) Controls rename detection @@ -196,13 +196,13 @@ The plugin can be disabled by setting `g:loaded_spellfile_plugin = 1`. A table with the following fields: Fields: ~ + • {confirm} (`boolean`, default: `true`) Whether to ask user to + confirm download. + • {timeout_ms} (`integer`, default: 15000) Number of milliseconds after + which the |vim.net.request()| times out. • {url} (`string`) The base URL from where the spellfiles are downloaded. Uses `g:spellfile_URL` if it's set, otherwise https://ftp.nluug.nl/pub/vim/runtime/spell. - • {timeout_ms} (`integer`, default: 15000) Number of milliseconds after - which the |vim.net.request()| times out. - • {confirm} (`boolean`, default: `true`) Whether to ask user to - confirm download. config({opts}) *spellfile.config()* @@ -225,11 +225,11 @@ get({lang}) *spellfile.get()* Return: ~ (`table?`) A table with the following fields: + • {dir} (`string`) + • {encoding} (`string`) • {files} (`string[]`) • {key} (`string`) • {lang} (`string`) - • {encoding} (`string`) - • {dir} (`string`) ============================================================================== @@ -253,17 +253,17 @@ tohtml({winid}, {opt}) *tohtml.tohtml()* Parameters: ~ • {winid} (`integer?`) Window to convert (defaults to current window) • {opt} (`table?`) Optional parameters. - • {title}? (`string|false`, default: buffer name) Title tag - to set in the generated HTML code. - • {number_lines}? (`boolean`, default: `false`) Show line - numbers. • {font}? (`string[]|string`, default: `guifont`) Fonts to use. + • {number_lines}? (`boolean`, default: `false`) Show line + numbers. + • {range}? (`integer[]`, default: entire buffer) Range of + rows to use. + • {title}? (`string|false`, default: buffer name) Title tag + to set in the generated HTML code. • {width}? (`integer`, default: 'textwidth' if non-zero or window width otherwise) Width used for items which are either right aligned or repeat a character infinitely. - • {range}? (`integer[]`, default: entire buffer) Range of - rows to use. Return: ~ (`string[]`) @@ -287,8 +287,6 @@ open({opts}) *undotree.open()* • {opts} (`table?`) A table with the following fields: • {bufnr} (`integer?`) Buffer to draw the tree into. If omitted, a new buffer is created. - • {winid} (`integer?`) Window id to display the tree buffer - in. If omitted, a new window is created with {command}. • {command} (`string?`) Vimscript command to create the window. Default value is "30vnew". Only used when {winid} is nil. @@ -296,6 +294,8 @@ open({opts}) *undotree.open()* the window. If a function, it accepts the buffer number of the source buffer as its only argument and should return a string. + • {winid} (`integer?`) Window id to display the tree buffer + in. If omitted, a new window is created with {command}. Return: ~ (`boolean?`) Returns true if the window was already open, nil diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 170cd4dc75..576775d204 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -1008,15 +1008,15 @@ get_node({opts}) *vim.treesitter.get_node()* • {opts} (`table?`) Optional keyword arguments: • {bufnr} (`integer?`) Buffer number (nil or 0 for current buffer) - • {pos} (`[integer, integer]?`) 0-indexed (row, col) tuple. - Defaults to cursor position in the current window. Required - if {bufnr} is not the current buffer - • {lang} (`string?`) Parser language. (default: from buffer - filetype) • {ignore_injections} (`boolean?`) Ignore injected languages (default true) • {include_anonymous} (`boolean?`) Include anonymous nodes (default false) + • {lang} (`string?`) Parser language. (default: from buffer + filetype) + • {pos} (`[integer, integer]?`) 0-indexed (row, col) tuple. + Defaults to cursor position in the current window. Required + if {bufnr} is not the current buffer Return: ~ (`TSNode?`) Node at the given position @@ -1115,19 +1115,19 @@ inspect_tree({opts}) *vim.treesitter.inspect_tree()* Parameters: ~ • {opts} (`table?`) Optional options table with the following possible keys: - • lang (string|nil): The language of the source buffer. If - omitted, detect from the filetype of the source buffer. • bufnr (integer|nil): Buffer to draw the tree into. If omitted, a new buffer is created. - • winid (integer|nil): Window id to display the tree buffer - in. If omitted, a new window is created with {command}. • command (string|nil): Vimscript command to create the window. Default value is "60vnew". Only used when {winid} is nil. + • lang (string|nil): The language of the source buffer. If + omitted, detect from the filetype of the source buffer. • title (string|fun(bufnr:integer):string|nil): Title of the window. If a function, it accepts the buffer number of the source buffer as its only argument and should return a string. + • winid (integer|nil): Window id to display the tree buffer + in. If omitted, a new window is created with {command}. is_ancestor({dest}, {source}) *vim.treesitter.is_ancestor()* Determines whether a node is the ancestor of another @@ -1545,20 +1545,20 @@ them to parse text. See |vim.treesitter.query.parse()| for a working example. Parsed query, see |vim.treesitter.query.parse()| Fields: ~ - • {lang} (`string`) parser language name • {captures} (`string[]`) list of (unique) capture names defined in query - • {info} (`vim.treesitter.QueryInfo`) query context - (e.g. captures, predicates, directives) - • {has_conceal_line} (`boolean`) whether the query sets - conceal_lines metadata • {has_combined_injections} (`boolean`) whether the query contains combined injections - • {query} (`TSQuery`) userdata query object + • {has_conceal_line} (`boolean`) whether the query sets + conceal_lines metadata + • {info} (`vim.treesitter.QueryInfo`) query context + (e.g. captures, predicates, directives) • {iter_captures} (`fun(self: vim.treesitter.Query, node: TSNode, source: integer|string, start_row: integer?, end_row: integer?, opts: table?): fun(end_line: integer?, end_col: integer?): integer, TSNode, vim.treesitter.query.TSMetadata, TSQueryMatch, TSTree`) See |Query:iter_captures()|. • {iter_matches} (`fun(self: vim.treesitter.Query, node: TSNode, source: integer|string, start: integer?, stop: integer?, opts: table?): fun(): integer, table, vim.treesitter.query.TSMetadata, TSTree`) See |Query:iter_matches()|. + • {lang} (`string`) parser language name + • {query} (`TSQuery`) userdata query object *vim.treesitter.query.add_directive()* @@ -1655,10 +1655,10 @@ lint({buf}, {opts}) *vim.treesitter.query.lint()* Parameters: ~ • {buf} (`integer`) Buffer handle • {opts} (`table?`) Optional keyword arguments: + • {clear} (`boolean`) Just clear current lint errors • {langs}? (`string|string[]`) Language(s) to use for checking the query. If multiple languages are specified, queries are validated for all of them - • {clear} (`boolean`) Just clear current lint errors list_directives() *vim.treesitter.query.list_directives()* Lists the currently available directives to use in queries. @@ -1762,14 +1762,14 @@ Query:iter_captures({node}, {source}, {start_row}, {end_row}, {opts}) unless `stop_col` is provided). Defaults to `node:end_()`. • {opts} (`table?`) Optional keyword arguments: + • end_col (integer) Stopping column for the search + (end-exclusive). + • match_limit (integer) Set the maximum number of + in-progress matches (Default: 256). • max_start_depth (integer) if non-zero, sets the maximum start depth for each match. This is used to prevent traversing too deep into a tree. - • match_limit (integer) Set the maximum number of - in-progress matches (Default: 256). • start_col (integer) Starting column for the search. - • end_col (integer) Stopping column for the search - (end-exclusive). Return: ~ (`fun(end_line: integer?, end_col: integer?): integer, TSNode, vim.treesitter.query.TSMetadata, TSQueryMatch, TSTree`) @@ -1807,11 +1807,11 @@ Query:iter_matches({node}, {source}, {start}, {stop}, {opts}) • {stop} (`integer?`) Stopping line for the search (end-exclusive). Defaults to `node:end_()`. • {opts} (`table?`) Optional keyword arguments: + • match_limit (integer) Set the maximum number of + in-progress matches (Default: 256). • max_start_depth (integer) if non-zero, sets the maximum start depth for each match. This is used to prevent traversing too deep into a tree. - • match_limit (integer) Set the maximum number of - in-progress matches (Default: 256). Return: ~ (`fun(): integer, table, vim.treesitter.query.TSMetadata, TSTree`) diff --git a/runtime/lua/vim/_meta/api.gen.lua b/runtime/lua/vim/_meta/api.gen.lua index c9a953bce8..cdfec238eb 100644 --- a/runtime/lua/vim/_meta/api.gen.lua +++ b/runtime/lua/vim/_meta/api.gen.lua @@ -135,24 +135,24 @@ function vim.api.nvim__ns_set(ns_id, opts) end --- --- @see `:help :redraw` --- @param opts vim.api.keyset.redraw Optional parameters. ---- - win: Target a specific `window-ID` as described below. --- - buf: Target a specific buffer number as described below. +--- - cursor: Immediately update cursor position on the screen in +--- `win` or the current window. --- - flush: Update the screen with pending updates. ---- - valid: When present mark `win`, `buf`, or all windows for ---- redraw. When `true`, only redraw changed lines (useful for ---- decoration providers). When `false`, forcefully redraw. --- - range: Redraw a range in `buf`, the buffer in `win` or the --- current buffer (useful for decoration providers). Expects a --- tuple `[first, last]` with the first and last line number --- of the range, 0-based end-exclusive `api-indexing`. ---- - cursor: Immediately update cursor position on the screen in ---- `win` or the current window. --- - statuscolumn: Redraw the 'statuscolumn' in `buf`, `win` or --- all windows. --- - statusline: Redraw the 'statusline' in `buf`, `win` or all --- windows. ---- - winbar: Redraw the 'winbar' in `buf`, `win` or all windows. --- - tabline: Redraw the 'tabline'. +--- - valid: When present mark `win`, `buf`, or all windows for +--- redraw. When `true`, only redraw changed lines (useful for +--- decoration providers). When `false`, forcefully redraw. +--- - win: Target a specific `window-ID` as described below. +--- - winbar: Redraw the 'winbar' in `buf`, `win` or all windows. function vim.api.nvim__redraw(opts) end --- WARNING: This feature is experimental/unstable. @@ -211,17 +211,6 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- Else the first notification will be `nvim_buf_changedtick_event`. --- Not for Lua callbacks. --- @param opts vim.api.keyset.buf_attach Optional parameters. ---- - on_lines: Called on linewise changes. Not called on buffer reload (`:checktime`, ---- `:edit`, …), see `on_reload:`. Return a [lua-truthy] value to detach. Args: ---- - the string "lines" ---- - buffer id ---- - b:changedtick ---- - first line that changed (zero-indexed) ---- - last line that was changed ---- - last line in the updated range ---- - byte count of previous contents ---- - deleted_codepoints (if `utf_sizes` is true) ---- - deleted_codeunits (if `utf_sizes` is true) --- - on_bytes: Called on granular changes (compared to on_lines). Not called on buffer --- reload (`:checktime`, `:edit`, …), see `on_reload:`. Return a [lua-truthy] value --- to detach. Args: @@ -247,14 +236,25 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- - on_detach: Called on detach. Args: --- - the string "detach" --- - buffer id +--- - on_lines: Called on linewise changes. Not called on buffer reload (`:checktime`, +--- `:edit`, …), see `on_reload:`. Return a [lua-truthy] value to detach. Args: +--- - the string "lines" +--- - buffer id +--- - b:changedtick +--- - first line that changed (zero-indexed) +--- - last line that was changed +--- - last line in the updated range +--- - byte count of previous contents +--- - deleted_codepoints (if `utf_sizes` is true) +--- - deleted_codeunits (if `utf_sizes` is true) --- - on_reload: Called on whole-buffer load (`:checktime`, `:edit`, …). Clients should --- typically re-fetch the entire buffer contents. Args: --- - the string "reload" --- - buffer id ---- - utf_sizes: include UTF-32 and UTF-16 size of the replaced ---- region, as args to `on_lines`. --- - preview: also attach to command preview (i.e. 'inccommand') --- events. +--- - utf_sizes: include UTF-32 and UTF-16 size of the replaced +--- region, as args to `on_lines`. --- @return boolean # False if attach failed (invalid parameter, or buffer isn't loaded); --- otherwise True. function vim.api.nvim_buf_attach(buf, send_buffer, opts) end @@ -445,9 +445,9 @@ function vim.api.nvim_buf_get_extmark_by_id(buf, ns_id, id, opts) end --- @param end_ any End of range (inclusive): a 0-indexed (row, col) or valid --- extmark id (whose position defines the bound). `api-indexing` --- @param opts vim.api.keyset.get_extmarks Optional parameters. Keys: ---- - limit: Maximum number of marks to return --- - details: Whether to include the details dict --- - hl_name: Whether to include highlight group name instead of id, true if omitted +--- - limit: Maximum number of marks to return --- - overlap: Also include marks which overlap the range, even if --- their start position is less than `start` --- - type: Filter marks by type: "highlight", "sign", "virt_text" and "virt_lines" @@ -595,51 +595,40 @@ function vim.api.nvim_buf_line_count(buf) end --- @param line integer Line where to place the mark, 0-based. `api-indexing` --- @param col integer Column where to place the mark, 0-based. `api-indexing` --- @param opts vim.api.keyset.set_extmark Optional parameters. ---- - id : id of the extmark to edit. ---- - end_row : ending line of the mark, 0-based inclusive. +--- - conceal: either a boolean or a string. +--- - when a string is given, it should be either empty or a single +--- character. Enable concealing similar to `:syn-conceal`. +--- When a character is supplied it is used as `:syn-cchar`. +--- "hl_group" is used as highlight for the cchar if provided, +--- otherwise it defaults to `hl-Conceal`. +--- - when a boolean is given, true is equivalent to "" and false +--- overrides any existing conceal to remove it. +--- - conceal_lines: string which should be empty. When +--- provided, lines in the range are not drawn at all +--- (according to 'conceallevel'); the next unconcealed line +--- is drawn instead. +--- - cursorline_hl_group: highlight group used for the sign +--- column text when the cursor is on the same line as the +--- mark and 'cursorline' is enabled. --- - end_col : ending col of the mark, 0-based exclusive, or -1 to extend the range to end of line (if strict=false). +--- - end_right_gravity : boolean that indicates the direction +--- the extmark end position (if it exists) will be shifted +--- in when new text is inserted (true for right, false +--- for left). Defaults to false. +--- - end_row : ending line of the mark, 0-based inclusive. +--- - ephemeral : for use with `nvim_set_decoration_provider()` +--- callbacks. The mark will only be used for the current +--- redraw cycle, and not be permanently stored in the buffer. +--- - 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 +--- cursorline highlight). --- - 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 ---- cursorline highlight). ---- - virt_text : [](virtual-text) to link to this mark. ---- A list of `[text, highlight]` tuples, each representing a ---- text chunk with specified highlight. `highlight` element ---- can either be a single highlight group, or an array of ---- multiple highlight groups that will be stacked ---- (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. ---- - "inline": display at the specified column, and ---- shift the buffer text to the right as needed. ---- - virt_text_win_col : position the virtual text at a fixed ---- window column (starting from the first ---- text column of the screen line) instead ---- of "virt_text_pos". ---- - virt_text_hide : hide the virtual text when the background ---- text is selected or hidden because of ---- scrolling with 'nowrap' or 'smoothscroll'. ---- Currently only affects "overlay" virt_text. ---- - virt_text_repeat_linebreak : repeat the virtual text on ---- 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` @@ -649,6 +638,38 @@ function vim.api.nvim_buf_line_count(buf) end --- - "blend": blend with background text color. --- Not supported for "inline" virt_text. --- +--- - id : id of the extmark to edit. +--- - invalidate : boolean that indicates whether to hide the +--- extmark if the entirety of its range is deleted. For +--- hidden marks, an "invalid" key is added to the "details" +--- array of `nvim_buf_get_extmarks()` and family. If +--- "undo_restore" is false, the extmark is deleted instead. +--- - line_hl_group: highlight group used for the whole line. +--- - number_hl_group: highlight group used for the number column. +--- - priority: a priority value for the highlight group, sign +--- attribute or virtual text. For virtual text, item with +--- highest priority is drawn last. For example treesitter +--- highlighting uses a value of 100. +--- - right_gravity : boolean that indicates the direction +--- the extmark will be shifted in when new text is inserted +--- (true for right, false for left). Defaults to true. +--- - sign_hl_group: highlight group used for the sign column text. +--- - sign_text: string of length 1-2 used to display in the +--- sign column. +--- - spell: boolean indicating that spell checking should be +--- performed within this extmark +--- - strict: boolean that indicates extmark should not be placed +--- if the line or column value is past the end of the +--- buffer or end of the line respectively. Defaults to true. +--- - ui_watched: boolean that indicates the mark should be drawn +--- by a UI. When set, the UI will receive win_extmark events. +--- Note: the mark is positioned by virt_text attributes. Can be +--- used together with virt_text. +--- - undo_restore : Restore the exact position of the mark +--- if text around the mark was deleted and then restored by undo. +--- Defaults to true. +--- - url: A URL to associate with this extmark. In the TUI, the OSC 8 control +--- sequence is used to generate a clickable hyperlink to this URL. --- - virt_lines : virtual lines to add next to this mark --- This should be an array over lines, where each line in --- turn is an array over `[text, highlight]` tuples. In @@ -669,59 +690,38 @@ function vim.api.nvim_buf_line_count(buf) end --- - "trunc": truncate virtual lines on the right (default). --- - "scroll": virtual lines can scroll horizontally with 'nowrap', --- otherwise the same as "trunc". ---- - ephemeral : for use with `nvim_set_decoration_provider()` ---- callbacks. The mark will only be used for the current ---- redraw cycle, and not be permanently stored in the buffer. ---- - right_gravity : boolean that indicates the direction ---- the extmark will be shifted in when new text is inserted ---- (true for right, false for left). Defaults to true. ---- - end_right_gravity : boolean that indicates the direction ---- the extmark end position (if it exists) will be shifted ---- in when new text is inserted (true for right, false ---- for left). Defaults to false. ---- - undo_restore : Restore the exact position of the mark ---- if text around the mark was deleted and then restored by undo. ---- Defaults to true. ---- - invalidate : boolean that indicates whether to hide the ---- extmark if the entirety of its range is deleted. For ---- hidden marks, an "invalid" key is added to the "details" ---- array of `nvim_buf_get_extmarks()` and family. If ---- "undo_restore" is false, the extmark is deleted instead. ---- - priority: a priority value for the highlight group, sign ---- attribute or virtual text. For virtual text, item with ---- highest priority is drawn last. For example treesitter ---- highlighting uses a value of 100. ---- - strict: boolean that indicates extmark should not be placed ---- if the line or column value is past the end of the ---- buffer or end of the line respectively. Defaults to true. ---- - sign_text: string of length 1-2 used to display in the ---- sign column. ---- - sign_hl_group: highlight group used for the sign column text. ---- - number_hl_group: highlight group used for the number column. ---- - line_hl_group: highlight group used for the whole line. ---- - cursorline_hl_group: highlight group used for the sign ---- column text when the cursor is on the same line as the ---- mark and 'cursorline' is enabled. ---- - conceal: either a boolean or a string. ---- - when a string is given, it should be either empty or a single ---- character. Enable concealing similar to `:syn-conceal`. ---- When a character is supplied it is used as `:syn-cchar`. ---- "hl_group" is used as highlight for the cchar if provided, ---- otherwise it defaults to `hl-Conceal`. ---- - when a boolean is given, true is equivalent to "" and false ---- overrides any existing conceal to remove it. ---- - conceal_lines: string which should be empty. When ---- provided, lines in the range are not drawn at all ---- (according to 'conceallevel'); the next unconcealed line ---- is drawn instead. ---- - spell: boolean indicating that spell checking should be ---- performed within this extmark ---- - ui_watched: boolean that indicates the mark should be drawn ---- by a UI. When set, the UI will receive win_extmark events. ---- Note: the mark is positioned by virt_text attributes. Can be ---- used together with virt_text. ---- - url: A URL to associate with this extmark. In the TUI, the OSC 8 control ---- sequence is used to generate a clickable hyperlink to this URL. +--- - virt_text : [](virtual-text) to link to this mark. +--- A list of `[text, highlight]` tuples, each representing a +--- text chunk with specified highlight. `highlight` element +--- can either be a single highlight group, or an array of +--- multiple highlight groups that will be stacked +--- (highest priority last). +--- - virt_text_hide : hide the virtual text when the background +--- text is selected or hidden because of +--- scrolling with 'nowrap' or 'smoothscroll'. +--- Currently only affects "overlay" virt_text. +--- - 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. +--- - "inline": display at the specified column, and +--- shift the buffer text to the right as needed. +--- - virt_text_repeat_linebreak : repeat the virtual text on +--- wrapped lines. +--- - virt_text_win_col : position the virtual text at a fixed +--- window column (starting from the first +--- text column of the screen line) instead +--- of "virt_text_pos". --- @return integer # Id of the created/updated extmark function vim.api.nvim_buf_set_extmark(buf, ns_id, line, col, opts) end @@ -866,17 +866,17 @@ function vim.api.nvim_chan_send(chan, data) end --- Clears all autocommands matching the {opts} query. To delete autocmds see `nvim_del_autocmd()`. --- --- @param opts vim.api.keyset.clear_autocmds Optional parameters: +--- - buf: (`integer?`) Select `autocmd-buflocal` autocommands. Not allowed with {pattern}. --- - event: (`vim.api.keyset.events|vim.api.keyset.events[]?`) --- Examples: --- - event: "pat1" --- - event: { "pat1" } --- - event: { "pat1", "pat2", "pat3" } +--- - group: (`string|int?`) Group name or id. +--- - NOTE: If not given, matches autocmds *not* in any group. --- - pattern: (`string|table?`) Filter by patterns (exact match). Not allowed with {buf}. --- - Example: if you have `*.py` as that pattern for the autocmd, you must pass `*.py` --- exactly to clear it. `test.py` will not match the pattern. ---- - buf: (`integer?`) Select `autocmd-buflocal` autocommands. Not allowed with {pattern}. ---- - group: (`string|int?`) Group name or id. ---- - NOTE: If not given, matches autocmds *not* in any group. function vim.api.nvim_clear_autocmds(opts) end --- Executes an Ex command `cmd`, specified as a Dict with the same structure as returned by @@ -1037,18 +1037,18 @@ function vim.api.nvim_create_namespace(name) end --- @param cmd 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 --- - args: (string) The args passed to the command, if any [] +--- - bang: (boolean) "true" if the command was executed with a ! modifier [] +--- - count: (number) Any count supplied [] --- - fargs: (table) The args split by unescaped whitespace (when more than one --- argument is allowed), if any [] ---- - nargs: (string) Number of arguments `:command-nargs` ---- - bang: (boolean) "true" if the command was executed with a ! modifier [] --- - line1: (number) The starting line of the command range [] --- - line2: (number) The final line of the command range [] ---- - range: (number) The number of items in the command range: 0, 1, or 2 [] ---- - count: (number) Any count supplied [] ---- - reg: (string) The optional register, if specified [] --- - mods: (string) Command modifiers, if any [] +--- - name: (string) Command name +--- - nargs: (string) Number of arguments `:command-nargs` +--- - range: (number) The number of items in the command range: 0, 1, or 2 [] +--- - reg: (string) The optional register, if specified [] --- - smods: (table) Command modifiers in a structured format. Has the same --- structure as the "mods" key of `nvim_parse_cmd()`. --- @param opts vim.api.keyset.user_command Optional flags @@ -1176,15 +1176,15 @@ function vim.api.nvim_eval(expr) end --- --- @param str string Statusline string (see 'statusline'). --- @param opts vim.api.keyset.eval_statusline Optional parameters. ---- - winid: (number) `window-ID` of the window to use as context for statusline. ---- - maxwidth: (number) Maximum width of statusline. --- - fillchar: (string) Character to fill blank spaces in the statusline (see --- 'fillchars'). Treated as single-width even if it isn't. --- - highlights: (boolean) Return highlight information. ---- - use_winbar: (boolean) Evaluate winbar instead of statusline. +--- - maxwidth: (number) Maximum width of statusline. +--- - use_statuscol_lnum: (number) Evaluate statuscolumn for this line number instead of statusline. --- - use_tabline: (boolean) Evaluate tabline instead of statusline. When true, {winid} --- is ignored. Mutually exclusive with {use_winbar}. ---- - use_statuscol_lnum: (number) Evaluate statuscolumn for this line number instead of statusline. +--- - use_winbar: (boolean) Evaluate winbar instead of statusline. +--- - winid: (number) `window-ID` of the window to use as context for statusline. --- @return vim.api.keyset.eval_statusline_ret # Dict containing statusline information, with these keys: --- - str: (string) Characters that will be displayed on the statusline. --- - width: (number) Display width of the statusline. @@ -1227,12 +1227,12 @@ function vim.api.nvim_exec2(src, opts) end --- @see `:help :doautocmd` --- @param event vim.api.keyset.events|vim.api.keyset.events[] Event(s) to execute. --- @param opts vim.api.keyset.exec_autocmds Optional filters: ---- - group (`string|integer?`) Group name or id to match against. `autocmd-groups`. ---- - pattern (`string|array?`, default: current file name) `autocmd-pattern`. Not allowed with {buf}. --- - buf (`integer?`) Buffer id `autocmd-buflocal`. Not allowed with {pattern}. +--- - data (`any`): Arbitrary data passed to the callback. See `nvim_create_autocmd()`. +--- - group (`string|integer?`) Group name or id to match against. `autocmd-groups`. --- - modeline (`boolean?`, default: true) Process the modeline after the autocommands --- []. ---- - data (`any`): Arbitrary data passed to the callback. See `nvim_create_autocmd()`. +--- - pattern (`string|array?`, default: current file name) `autocmd-pattern`. Not allowed with {buf}. function vim.api.nvim_exec_autocmds(event, opts) end --- Sends input-keys to Nvim, subject to various quirks controlled by `mode` @@ -1411,10 +1411,10 @@ function vim.api.nvim_get_current_win() end --- @param ns_id integer Get highlight groups for namespace ns_id `nvim_get_namespaces()`. --- Use 0 to get global highlight groups `:highlight`. --- @param opts vim.api.keyset.get_highlight Options dict: ---- - name: (string) Get a highlight definition by name. +--- - create: (boolean, default true) When highlight group doesn't exist create it. --- - id: (integer) Get a highlight definition by id. --- - link: (boolean, default true) Show linked group name instead of effective definition `:hi-link`. ---- - create: (boolean, default true) When highlight group doesn't exist create it. +--- - name: (string) Get a highlight definition by name. --- @return vim.api.keyset.get_hl_info # Highlight groups as a map from group name to a highlight definition map as in |nvim_set_hl()|, --- or only a single highlight definition map if requested by name or id. function vim.api.nvim_get_hl(ns_id, opts) end @@ -1521,11 +1521,11 @@ function vim.api.nvim_get_option_info(name) end --- --- @param name string Option name --- @param opts vim.api.keyset.option Optional parameters +--- - buf: Buffer number. Used for getting buffer local options. +--- Implies {scope} is "local". --- - scope: One of "global" or "local". Analogous to --- `:setglobal` and `:setlocal`, respectively. --- - win: `window-ID`. Used for getting window local options. ---- - buf: Buffer number. Used for getting buffer local options. ---- Implies {scope} is "local". --- @return vim.api.keyset.get_option_info # Option Information function vim.api.nvim_get_option_info2(name, opts) end @@ -1536,15 +1536,15 @@ function vim.api.nvim_get_option_info2(name, opts) end --- --- @param name string Option name --- @param opts vim.api.keyset.option Optional parameters ---- - scope: One of "global" or "local". Analogous to ---- `:setglobal` and `:setlocal`, respectively. ---- - win: `window-ID`. Used for getting window local options. --- - buf: Buffer number. Used for getting buffer local options. --- Implies {scope} is "local". --- - filetype: `filetype`. Used to get the default option for a --- specific filetype. Cannot be used with any other option. --- Note: this will trigger `ftplugin` and all `FileType` --- autocommands for the corresponding filetype. +--- - scope: One of "global" or "local". Analogous to +--- `:setglobal` and `:setlocal`, respectively. +--- - win: `window-ID`. Used for getting window local options. --- @return any # Option value function vim.api.nvim_get_option_value(name, opts) end @@ -1731,13 +1731,13 @@ function vim.api.nvim_open_tabpage(buf, enter, config) end --- @param buf integer Buffer to use. Buffer contents (if any) will be written --- to the PTY. --- @param opts vim.api.keyset.open_term Optional parameters. +--- - force_crlf: (boolean, default true) Convert "\n" to "\r\n". --- - on_input: Lua callback for input sent, i e keypresses in terminal --- mode. Note: keypresses are sent raw as they would be to the pty --- master end. For instance, a carriage return is sent --- as a "\r", not as a "\n". `textlock` applies. It is possible --- to call `nvim_chan_send()` directly in the callback however. --- `["input", term, bufnr, data]` ---- - force_crlf: (boolean, default true) Convert "\n" to "\r\n". --- @return integer # Channel id, or 0 on error function vim.api.nvim_open_term(buf, opts) end @@ -2168,18 +2168,14 @@ function vim.api.nvim_set_current_win(win) end --- --- @param ns_id integer Namespace id from `nvim_create_namespace()` --- @param opts vim.api.keyset.set_decoration_provider Table of callbacks: ---- - on_start: called first on each screen redraw ---- ``` ---- ["start", tick] ---- ``` --- - on_buf: called for each buffer being redrawn (once per edit, --- before window callbacks) --- ``` --- ["buf", bufnr, tick] --- ``` ---- - on_win: called when starting to redraw a specific window. +--- - on_end: called at the end of a redraw cycle --- ``` ---- ["win", winid, bufnr, toprow, botrow] +--- ["end", tick] --- ``` --- - on_line: (deprecated, use on_range instead) --- ``` @@ -2200,9 +2196,13 @@ function vim.api.nvim_set_current_win(win) end --- which continues beyond the skipped position. A single integer --- return value `skip_row` is short for `skip_row, 0` --- ---- - on_end: called at the end of a redraw cycle +--- - on_start: called first on each screen redraw --- ``` ---- ["end", tick] +--- ["start", tick] +--- ``` +--- - on_win: called when starting to redraw a specific window. +--- ``` +--- ["win", winid, bufnr, toprow, botrow] --- ``` function vim.api.nvim_set_decoration_provider(ns_id, opts) end @@ -2323,10 +2323,10 @@ function vim.api.nvim_set_option(name, value) end --- @param name string Option name --- @param value any New option value --- @param opts vim.api.keyset.option Optional parameters +--- - buf: Buffer number. Used for setting buffer local option. --- - scope: One of "global" or "local". Analogous to --- `:setglobal` and `:setlocal`, respectively. --- - win: `window-ID`. Used for setting window local option. ---- - buf: Buffer number. Used for setting buffer local option. function vim.api.nvim_set_option_value(name, value, opts) end --- Sets a global (g:) variable. @@ -2600,13 +2600,8 @@ function vim.api.nvim_win_set_width(win, width) end --- @see `:help virtcol()` for text width. --- @param win integer `window-ID`, or 0 for current window. --- @param opts vim.api.keyset.win_text_height Optional parameters: ---- - start_row: Starting line index, 0-based inclusive. ---- When omitted start at the very top. --- - end_row: Ending line index, 0-based inclusive. --- When omitted end at the very bottom. ---- - start_vcol: Starting virtual column index on "start_row", ---- 0-based inclusive, rounded down to full screen lines. ---- When omitted include the whole line. --- - end_vcol: Ending virtual column index on "end_row", --- 0-based exclusive, rounded up to full screen lines. --- When 0 only include diff filler and virtual lines above @@ -2617,6 +2612,11 @@ function vim.api.nvim_win_set_width(win, width) end --- to find out how many buffer lines beyond "start_row" take --- up a certain number of logical lines (returned in --- "end_row" and "end_vcol"). +--- - start_row: Starting line index, 0-based inclusive. +--- When omitted start at the very top. +--- - start_vcol: Starting virtual column index on "start_row", +--- 0-based inclusive, rounded down to full screen lines. +--- When omitted include the whole line. --- @return vim.api.keyset.win_text_height_ret # Dict containing text height information, with these keys: --- - all: The total number of screen lines occupied by the range. --- - fill: The number of diff filler or virtual lines among them. diff --git a/runtime/lua/vim/_meta/api_keysets.gen.lua b/runtime/lua/vim/_meta/api_keysets.gen.lua index 6317b81700..c27a23a0bd 100644 --- a/runtime/lua/vim/_meta/api_keysets.gen.lua +++ b/runtime/lua/vim/_meta/api_keysets.gen.lua @@ -5,51 +5,47 @@ error('Cannot require a meta file') --- @class vim.api.keyset.buf_attach ---- @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_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_reload? fun(_: "reload", bufnr: integer) ---- @field utf_sizes? boolean --- @field preview? boolean +--- @field utf_sizes? boolean --- @class vim.api.keyset.buf_delete --- @field force? boolean --- @field unload? boolean --- @class vim.api.keyset.clear_autocmds ---- @field buffer? integer --- @field buf? integer +--- @field buffer? integer --- @field event? vim.api.keyset.events|vim.api.keyset.events[] --- @field group? integer|string --- @field pattern? string|string[] --- @class vim.api.keyset.cmd ---- @field cmd? string ---- @field range? integer[] ---- @field count? integer ---- @field reg? string ---- @field bang? boolean +--- @field addr? "line"|"arg"|"buf"|"load"|"win"|"tab"|"qf"|"none"|"?" --- @field args? string[] +--- @field bang? boolean +--- @field cmd? string +--- @field count? integer --- @field magic? vim.api.keyset.cmd.magic --- @field mods? vim.api.keyset.cmd.mods --- @field nargs? integer|"?"|"+"|"*" ---- @field addr? "line"|"arg"|"buf"|"load"|"win"|"tab"|"qf"|"none"|"?" --- @field nextcmd? string +--- @field range? integer[] +--- @field reg? string --- @class vim.api.keyset.cmd_magic ---- @field file? boolean --- @field bar? boolean +--- @field file? boolean --- @class vim.api.keyset.cmd_mods ---- @field silent? boolean ---- @field emsg_silent? boolean ---- @field unsilent? boolean ---- @field filter? table ---- @field sandbox? boolean ---- @field noautocmd? boolean --- @field browse? boolean --- @field confirm? boolean +--- @field emsg_silent? boolean +--- @field filter? table --- @field hide? boolean --- @field horizontal? boolean --- @field keepalt? boolean @@ -57,15 +53,19 @@ error('Cannot require a meta file') --- @field keepmarks? boolean --- @field keeppatterns? boolean --- @field lockmarks? boolean +--- @field noautocmd? boolean --- @field noswapfile? boolean +--- @field sandbox? boolean +--- @field silent? boolean +--- @field split? string --- @field tab? integer +--- @field unsilent? boolean --- @field verbose? integer --- @field vertical? boolean ---- @field split? string --- @class vim.api.keyset.cmd_mods_filter ---- @field pattern? string --- @field force? boolean +--- @field pattern? string --- @class vim.api.keyset.cmd_opts --- @field output? boolean @@ -227,8 +227,8 @@ error('Cannot require a meta file') --- |'WinScrolled' --- @class vim.api.keyset.create_autocmd ---- @field buffer? integer --- @field buf? integer +--- @field buffer? integer --- @field callback? string|fun(args: vim.api.keyset.create_autocmd.callback_args): boolean? --- @field command? string --- @field desc? string @@ -238,46 +238,46 @@ error('Cannot require a meta file') --- @field pattern? string|string[] --- @class vim.api.keyset.echo_opts +--- @field data? table --- @field err? boolean ---- @field verbose? boolean ---- @field _truncate? boolean ---- @field kind? string --- @field id? integer|string ---- @field title? string ---- @field status? string +--- @field kind? string --- @field percent? integer --- @field source? string ---- @field data? table +--- @field status? string +--- @field title? string +--- @field verbose? boolean +--- @field _truncate? boolean --- @class vim.api.keyset.empty --- @class vim.api.keyset.eval_statusline ---- @field winid? integer ---- @field maxwidth? integer --- @field fillchar? string --- @field highlights? boolean ---- @field use_winbar? boolean ---- @field use_tabline? boolean +--- @field maxwidth? integer --- @field use_statuscol_lnum? integer +--- @field use_tabline? boolean +--- @field use_winbar? boolean +--- @field winid? integer --- @class vim.api.keyset.exec_autocmds ---- @field buffer? integer --- @field buf? integer +--- @field buffer? integer +--- @field data? any --- @field group? integer|string --- @field modeline? boolean --- @field pattern? string|string[] ---- @field data? any --- @class vim.api.keyset.exec_opts --- @field output? boolean --- @class vim.api.keyset.get_autocmds +--- @field buf? integer|integer[] +--- @field buffer? integer|integer[] --- @field event? vim.api.keyset.events|vim.api.keyset.events[] --- @field group? integer|string ---- @field pattern? string|string[] ---- @field buffer? integer|integer[] ---- @field buf? integer|integer[] --- @field id? integer +--- @field pattern? string|string[] --- @class vim.api.keyset.get_commands --- @field builtin? boolean @@ -287,163 +287,163 @@ error('Cannot require a meta file') --- @field hl_name? boolean --- @class vim.api.keyset.get_extmarks ---- @field limit? integer --- @field details? boolean --- @field hl_name? boolean +--- @field limit? integer --- @field overlap? boolean --- @field type? string --- @class vim.api.keyset.get_highlight ---- @field id? integer ---- @field name? string ---- @field link? boolean --- @field create? boolean +--- @field id? integer +--- @field link? boolean +--- @field name? string --- @class vim.api.keyset.get_ns --- @field winid? integer --- @class vim.api.keyset.highlight --- @field altfont? boolean ---- @field blink? boolean ---- @field bold? boolean ---- @field conceal? boolean ---- @field dim? boolean ---- @field italic? boolean ---- @field nocombine? boolean ---- @field overline? boolean ---- @field reverse? boolean ---- @field standout? boolean ---- @field strikethrough? boolean ---- @field undercurl? boolean ---- @field underdashed? boolean ---- @field underdotted? boolean ---- @field underdouble? boolean ---- @field underline? boolean ---- @field default? boolean ---- @field cterm? vim.api.keyset.highlight_cterm ---- @field foreground? integer|string ---- @field fg? integer|string --- @field background? integer|string --- @field bg? integer|string ---- @field ctermfg? integer|string +--- @field bg_indexed? boolean +--- @field blend? integer +--- @field blink? boolean +--- @field bold? boolean +--- @field conceal? boolean +--- @field cterm? vim.api.keyset.highlight_cterm --- @field ctermbg? integer|string ---- @field special? integer|string ---- @field sp? integer|string +--- @field ctermfg? integer|string +--- @field default? boolean +--- @field dim? boolean +--- @field fallback? boolean +--- @field fg? integer|string +--- @field fg_indexed? boolean +--- @field font? string +--- @field force? boolean +--- @field foreground? integer|string +--- @field italic? boolean --- @field link? integer|string --- @field link_global? integer|string ---- @field fallback? boolean ---- @field blend? integer ---- @field fg_indexed? boolean ---- @field bg_indexed? boolean ---- @field force? boolean ---- @field update? boolean ---- @field url? string ---- @field font? string - ---- @class vim.api.keyset.highlight_cterm ---- @field bold? boolean +--- @field nocombine? boolean +--- @field overline? boolean +--- @field reverse? boolean +--- @field sp? integer|string +--- @field special? integer|string --- @field standout? boolean --- @field strikethrough? boolean ---- @field underline? boolean --- @field undercurl? boolean ---- @field underdouble? boolean ---- @field underdotted? boolean --- @field underdashed? boolean ---- @field italic? boolean ---- @field reverse? boolean +--- @field underdotted? boolean +--- @field underdouble? boolean +--- @field underline? boolean +--- @field update? boolean +--- @field url? string + +--- @class vim.api.keyset.highlight_cterm --- @field altfont? boolean ---- @field dim? boolean --- @field blink? boolean +--- @field bold? boolean --- @field conceal? boolean ---- @field overline? boolean +--- @field dim? boolean +--- @field italic? boolean --- @field nocombine? boolean +--- @field overline? boolean +--- @field reverse? boolean +--- @field standout? boolean +--- @field strikethrough? boolean +--- @field undercurl? boolean +--- @field underdashed? boolean +--- @field underdotted? boolean +--- @field underdouble? boolean +--- @field underline? boolean --- @class vim.api.keyset.keymap ---- @field noremap? boolean ---- @field nowait? boolean ---- @field silent? boolean ---- @field script? boolean ---- @field expr? boolean ---- @field unique? boolean --- @field callback? function --- @field desc? string +--- @field expr? boolean +--- @field noremap? boolean +--- @field nowait? boolean --- @field replace_keycodes? boolean +--- @field script? boolean +--- @field silent? boolean +--- @field unique? boolean --- @class vim.api.keyset.ns_opts --- @field wins? any[] --- @class vim.api.keyset.open_term ---- @field on_input? fun(_: "input", term: integer, bufnr: integer, data: any) --- @field force_crlf? boolean +--- @field on_input? fun(_: "input", term: integer, bufnr: integer, data: any) --- @class vim.api.keyset.option ---- @field scope? string ---- @field win? integer --- @field buf? integer --- @field filetype? string +--- @field scope? string +--- @field win? integer --- @class vim.api.keyset.redraw ---- @field flush? boolean +--- @field buf? integer --- @field cursor? boolean ---- @field valid? boolean +--- @field flush? boolean +--- @field range? any[] --- @field statuscolumn? boolean --- @field statusline? boolean --- @field tabline? boolean ---- @field winbar? boolean ---- @field range? any[] +--- @field valid? boolean --- @field win? integer ---- @field buf? integer +--- @field winbar? boolean --- @class vim.api.keyset.runtime ---- @field is_lua? boolean --- @field do_source? boolean +--- @field is_lua? boolean --- @class vim.api.keyset.set_decoration_provider ---- @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_end? fun(_: "end", tick: integer) --- @field on_line? fun(_: "line", winid: integer, bufnr: integer, row: integer): boolean? --- @field on_range? fun(_: "range", winid: integer, bufnr: integer, start_row: integer, start_col: integer, end_row: integer, end_col: integer): boolean? ---- @field on_end? fun(_: "end", tick: integer) +--- @field on_start? fun(_: "start", tick: integer): boolean? +--- @field on_win? fun(_: "win", winid: integer, bufnr: integer, toprow: integer, botrow: integer): boolean? +--- @field _on_conceal_line? fun(_: "conceal_line") --- @field _on_hl_def? fun(_: "hl_def") --- @field _on_spell_nav? fun(_: "spell_nav") ---- @field _on_conceal_line? fun(_: "conceal_line") --- @class vim.api.keyset.set_extmark ---- @field id? integer ---- @field end_line? integer ---- @field end_row? integer +--- @field conceal? string|boolean +--- @field conceal_lines? string +--- @field cursorline_hl_group? integer|string --- @field end_col? integer ---- @field hl_group? any ---- @field virt_text? any[] ---- @field virt_text_pos? "eol"|"eol_right_align"|"overlay"|"right_align"|"inline" ---- @field virt_text_win_col? integer ---- @field virt_text_hide? boolean ---- @field virt_text_repeat_linebreak? boolean ---- @field hl_eol? boolean ---- @field hl_mode? "replace"|"combine"|"blend" ---- @field invalidate? boolean +--- @field end_line? integer +--- @field end_right_gravity? boolean +--- @field end_row? integer --- @field ephemeral? boolean +--- @field hl_eol? boolean +--- @field hl_group? any +--- @field hl_mode? "replace"|"combine"|"blend" +--- @field id? integer +--- @field invalidate? boolean +--- @field line_hl_group? integer|string +--- @field number_hl_group? integer|string --- @field priority? integer --- @field right_gravity? boolean ---- @field end_right_gravity? boolean +--- @field scoped? boolean +--- @field sign_hl_group? integer|string +--- @field sign_text? string +--- @field spell? boolean +--- @field strict? boolean +--- @field ui_watched? boolean +--- @field undo_restore? boolean +--- @field url? string --- @field virt_lines? any[] --- @field virt_lines_above? boolean --- @field virt_lines_leftcol? boolean --- @field virt_lines_overflow? "trunc"|"scroll" ---- @field strict? boolean ---- @field sign_text? 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|boolean ---- @field conceal_lines? string ---- @field spell? boolean ---- @field ui_watched? boolean ---- @field undo_restore? boolean ---- @field url? string ---- @field scoped? boolean +--- @field virt_text? any[] +--- @field virt_text_hide? boolean +--- @field virt_text_pos? "eol"|"eol_right_align"|"overlay"|"right_align"|"inline" +--- @field virt_text_repeat_linebreak? boolean +--- @field virt_text_win_col? integer --- @field _subpriority? integer --- @class vim.api.keyset.tabpage_config @@ -464,48 +464,48 @@ error('Cannot require a meta file') --- @field register? boolean --- @class vim.api.keyset.win_config +--- @field anchor? "NW"|"NE"|"SW"|"SE" +--- @field border? any[]|"none"|"single"|"double"|"rounded"|"solid"|"shadow" +--- @field bufpos? integer[] +--- @field col? number --- @field external? boolean --- @field fixed? boolean --- @field focusable? boolean --- @field footer? any --- @field footer_pos? "center"|"left"|"right" ---- @field hide? boolean --- @field height? integer +--- @field hide? boolean --- @field mouse? boolean +--- @field noautocmd? boolean --- @field relative? "cursor"|"editor"|"laststatus"|"mouse"|"tabline"|"win" --- @field row? number ---- @field style? ""|"minimal" ---- @field noautocmd? boolean ---- @field vertical? boolean ---- @field win? integer ---- @field width? integer ---- @field zindex? integer ---- @field anchor? "NW"|"NE"|"SW"|"SE" ---- @field border? any[]|"none"|"single"|"double"|"rounded"|"solid"|"shadow" ---- @field bufpos? integer[] ---- @field col? number --- @field split? "left"|"right"|"above"|"below" +--- @field style? ""|"minimal" --- @field title? any --- @field title_pos? "center"|"left"|"right" +--- @field vertical? boolean +--- @field width? integer +--- @field win? integer +--- @field zindex? integer --- @field _cmdline_offset? integer --- @class vim.api.keyset.win_text_height ---- @field start_row? integer --- @field end_row? integer ---- @field start_vcol? integer --- @field end_vcol? integer --- @field max_height? integer +--- @field start_row? integer +--- @field start_vcol? integer --- @class vim.api.keyset.xdl_diff ---- @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? boolean|integer +--- @field ignore_blank_lines? boolean +--- @field ignore_cr_at_eol? boolean --- @field ignore_whitespace? boolean --- @field ignore_whitespace_change? boolean --- @field ignore_whitespace_change_at_eol? boolean ---- @field ignore_cr_at_eol? boolean ---- @field ignore_blank_lines? boolean --- @field indent_heuristic? boolean +--- @field interhunkctxlen? integer +--- @field linematch? boolean|integer +--- @field on_hunk? fun(start_a: integer, count_a: integer, start_b: integer, count_b: integer): integer? +--- @field result_type? string diff --git a/runtime/lua/vim/hl.lua b/runtime/lua/vim/hl.lua index 0af2c82927..aeae11a123 100644 --- a/runtime/lua/vim/hl.lua +++ b/runtime/lua/vim/hl.lua @@ -157,12 +157,12 @@ local yank_ns = api.nvim_create_namespace('nvim.hlyank') --- ``` --- --- @param opts table|nil Optional parameters +--- - event event structure (default vim.v.event) --- - higroup highlight group for yanked region (default "IncSearch") ---- - timeout time in ms before highlight is cleared (default 150) --- - on_macro highlight when executing macro (default false) --- - on_visual highlight when yanking visual selection (default true) ---- - event event structure (default vim.v.event) --- - priority integer priority (default |vim.hl.priorities|`.user`) +--- - timeout time in ms before highlight is cleared (default 150) function M.on_yank(opts) vim.validate('opts', opts, 'table', true) opts = opts or {} diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua index 33d1b80371..4198cfcc97 100644 --- a/runtime/lua/vim/lsp/util.lua +++ b/runtime/lua/vim/lsp/util.lua @@ -1232,11 +1232,11 @@ end ---@param contents string[] of lines to show in window ---@param opts? table with optional fields --- - height of floating window +--- - max_height maximal height of floating window +--- - max_width maximal width of floating window +--- - separator insert separator after code block --- - width of floating window --- - wrap_at character to wrap at for computing height ---- - max_width maximal width of floating window ---- - max_height maximal height of floating window ---- - separator insert separator after code block ---@return table stripped content function M.stylize_markdown(bufnr, contents, opts) vim.deprecate('vim.lsp.util.stylize_markdown', nil, '0.14') diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua index 311e69389a..13657571ca 100644 --- a/runtime/lua/vim/treesitter.lua +++ b/runtime/lua/vim/treesitter.lua @@ -472,17 +472,17 @@ end --- ---@since 11 ---@param opts table|nil Optional options table with the following possible keys: ---- - lang (string|nil): The language of the source buffer. If omitted, detect ---- from the filetype of the source buffer. --- - bufnr (integer|nil): Buffer to draw the tree into. If omitted, a new --- buffer is created. ---- - winid (integer|nil): Window id to display the tree buffer in. If omitted, ---- a new window is created with {command}. --- - command (string|nil): Vimscript command to create the window. Default --- value is "60vnew". Only used when {winid} is nil. +--- - lang (string|nil): The language of the source buffer. If omitted, detect +--- from the filetype of the source buffer. --- - title (string|fun(bufnr:integer):string|nil): Title of the window. If a --- function, it accepts the buffer number of the source buffer as its only --- argument and should return a string. +--- - winid (integer|nil): Window id to display the tree buffer in. If omitted, +--- a new window is created with {command}. function M.inspect_tree(opts) ---@diagnostic disable-next-line: invisible M.dev.inspect_tree(opts) diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua index 337764c0c2..57748fffb3 100644 --- a/runtime/lua/vim/treesitter/query.lua +++ b/runtime/lua/vim/treesitter/query.lua @@ -920,11 +920,11 @@ end ---@param start_row? integer Starting line for the search. Defaults to `node:start()`. ---@param end_row? integer Stopping line for the search (end-inclusive, unless `stop_col` is provided). Defaults to `node:end_()`. ---@param opts? table Optional keyword arguments: +--- - end_col (integer) Stopping column for the search (end-exclusive). +--- - match_limit (integer) Set the maximum number of in-progress matches (Default: 256). --- - max_start_depth (integer) if non-zero, sets the maximum start depth --- for each match. This is used to prevent traversing too deep into a tree. ---- - match_limit (integer) Set the maximum number of in-progress matches (Default: 256). --- - start_col (integer) Starting column for the search. ---- - end_col (integer) Stopping column for the search (end-exclusive). --- ---@return (fun(end_line: integer|nil, end_col: integer|nil): integer, TSNode, vim.treesitter.query.TSMetadata, TSQueryMatch, TSTree): --- capture id, capture node, metadata, match, tree @@ -1041,9 +1041,9 @@ end ---@param start? integer Starting line for the search. Defaults to `node:start()`. ---@param stop? integer Stopping line for the search (end-exclusive). Defaults to `node:end_()`. ---@param opts? table Optional keyword arguments: +--- - match_limit (integer) Set the maximum number of in-progress matches (Default: 256). --- - max_start_depth (integer) if non-zero, sets the maximum start depth --- for each match. This is used to prevent traversing too deep into a tree. ---- - match_limit (integer) Set the maximum number of in-progress matches (Default: 256). --- ---@return (fun(): integer, table, vim.treesitter.query.TSMetadata, TSTree): pattern id, match, metadata, tree function Query:iter_matches(node, source, start, stop, opts) diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c index 43dbbb4cb0..7812ca3018 100644 --- a/src/nvim/api/autocmd.c +++ b/src/nvim/api/autocmd.c @@ -530,17 +530,17 @@ void nvim_del_autocmd(Integer id, Error *err) /// Clears all autocommands matching the {opts} query. To delete autocmds see |nvim_del_autocmd()|. /// /// @param opts Optional parameters: +/// - buf: (`integer?`) Select |autocmd-buflocal| autocommands. Not allowed with {pattern}. /// - event: (`vim.api.keyset.events|vim.api.keyset.events[]?`) /// Examples: /// - event: "pat1" /// - event: { "pat1" } /// - event: { "pat1", "pat2", "pat3" } +/// - group: (`string|int?`) Group name or id. +/// - NOTE: If not given, matches autocmds *not* in any group. /// - pattern: (`string|table?`) Filter by patterns (exact match). Not allowed with {buf}. /// - Example: if you have `*.py` as that pattern for the autocmd, you must pass `*.py` /// exactly to clear it. `test.py` will not match the pattern. -/// - buf: (`integer?`) Select |autocmd-buflocal| autocommands. Not allowed with {pattern}. -/// - group: (`string|int?`) Group name or id. -/// - NOTE: If not given, matches autocmds *not* in any group. /// void nvim_clear_autocmds(Dict(clear_autocmds) *opts, Arena *arena, Error *err) FUNC_API_SINCE(9) @@ -680,12 +680,12 @@ void nvim_del_augroup_by_name(String name, Error *err) /// Executes handlers for {event} that match the corresponding {opts} query. |autocmd-execute| /// @param event Event(s) to execute. /// @param opts Optional filters: -/// - group (`string|integer?`) Group name or id to match against. |autocmd-groups|. -/// - pattern (`string|array?`, default: current file name) |autocmd-pattern|. Not allowed with {buf}. /// - buf (`integer?`) Buffer id |autocmd-buflocal|. Not allowed with {pattern}. +/// - data (`any`): Arbitrary data passed to the callback. See |nvim_create_autocmd()|. +/// - group (`string|integer?`) Group name or id to match against. |autocmd-groups|. /// - modeline (`boolean?`, default: true) Process the modeline after the autocommands /// []. -/// - data (`any`): Arbitrary data passed to the callback. See |nvim_create_autocmd()|. +/// - pattern (`string|array?`, default: current file name) |autocmd-pattern|. Not allowed with {buf}. /// @see |:doautocmd| void nvim_exec_autocmds(Object event, Dict(exec_autocmds) *opts, Arena *arena, Error *err) FUNC_API_SINCE(9) diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 7ab9f20360..28f30030d5 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -125,17 +125,6 @@ Integer nvim_buf_line_count(Buffer buf, Error *err) /// Else the first notification will be `nvim_buf_changedtick_event`. /// Not for Lua callbacks. /// @param opts Optional parameters. -/// - on_lines: Called on linewise changes. Not called on buffer reload (`:checktime`, -/// `:edit`, …), see `on_reload:`. Return a [lua-truthy] value to detach. Args: -/// - the string "lines" -/// - buffer id -/// - b:changedtick -/// - first line that changed (zero-indexed) -/// - last line that was changed -/// - last line in the updated range -/// - byte count of previous contents -/// - deleted_codepoints (if `utf_sizes` is true) -/// - deleted_codeunits (if `utf_sizes` is true) /// - on_bytes: Called on granular changes (compared to on_lines). Not called on buffer /// reload (`:checktime`, `:edit`, …), see `on_reload:`. Return a [lua-truthy] value /// to detach. Args: @@ -161,14 +150,25 @@ Integer nvim_buf_line_count(Buffer buf, Error *err) /// - on_detach: Called on detach. Args: /// - the string "detach" /// - buffer id +/// - on_lines: Called on linewise changes. Not called on buffer reload (`:checktime`, +/// `:edit`, …), see `on_reload:`. Return a [lua-truthy] value to detach. Args: +/// - the string "lines" +/// - buffer id +/// - b:changedtick +/// - first line that changed (zero-indexed) +/// - last line that was changed +/// - last line in the updated range +/// - byte count of previous contents +/// - deleted_codepoints (if `utf_sizes` is true) +/// - deleted_codeunits (if `utf_sizes` is true) /// - on_reload: Called on whole-buffer load (`:checktime`, `:edit`, …). Clients should /// typically re-fetch the entire buffer contents. Args: /// - the string "reload" /// - buffer id -/// - utf_sizes: include UTF-32 and UTF-16 size of the replaced -/// region, as args to `on_lines`. /// - preview: also attach to command preview (i.e. 'inccommand') /// events. +/// - utf_sizes: include UTF-32 and UTF-16 size of the replaced +/// region, as args to `on_lines`. /// @param[out] err Error details, if any /// @return False if attach failed (invalid parameter, or buffer isn't loaded); /// otherwise True. diff --git a/src/nvim/api/command.c b/src/nvim/api/command.c index 063b99c794..22b163a69b 100644 --- a/src/nvim/api/command.c +++ b/src/nvim/api/command.c @@ -981,18 +981,18 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin /// @param cmd 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 /// - args: (string) The args passed to the command, if any [] +/// - bang: (boolean) "true" if the command was executed with a ! modifier [] +/// - count: (number) Any count supplied [] /// - fargs: (table) The args split by unescaped whitespace (when more than one /// argument is allowed), if any [] -/// - nargs: (string) Number of arguments |:command-nargs| -/// - bang: (boolean) "true" if the command was executed with a ! modifier [] /// - line1: (number) The starting line of the command range [] /// - line2: (number) The final line of the command range [] -/// - range: (number) The number of items in the command range: 0, 1, or 2 [] -/// - count: (number) Any count supplied [] -/// - reg: (string) The optional register, if specified [] /// - mods: (string) Command modifiers, if any [] +/// - name: (string) Command name +/// - nargs: (string) Number of arguments |:command-nargs| +/// - range: (number) The number of items in the command range: 0, 1, or 2 [] +/// - reg: (string) The optional register, if specified [] /// - smods: (table) Command modifiers in a structured format. Has the same /// structure as the "mods" key of |nvim_parse_cmd()|. /// @param opts Optional flags diff --git a/src/nvim/api/extmark.c b/src/nvim/api/extmark.c index af3fa8dbdb..a0d47d3280 100644 --- a/src/nvim/api/extmark.c +++ b/src/nvim/api/extmark.c @@ -282,9 +282,9 @@ nvim_buf_get_extmark_by_id(Buffer buf, Integer ns_id, Integer id, Dict(get_extma /// @param end End of range (inclusive): a 0-indexed (row, col) or valid /// extmark id (whose position defines the bound). |api-indexing| /// @param opts Optional parameters. Keys: -/// - limit: Maximum number of marks to return /// - details: Whether to include the details dict /// - hl_name: Whether to include highlight group name instead of id, true if omitted +/// - limit: Maximum number of marks to return /// - overlap: Also include marks which overlap the range, even if /// their start position is less than `start` /// - type: Filter marks by type: "highlight", "sign", "virt_text" and "virt_lines" @@ -400,51 +400,40 @@ ArrayOf(DictAs(get_extmark_item)) nvim_buf_get_extmarks(Buffer buf, Integer ns_i /// @param line Line where to place the mark, 0-based. |api-indexing| /// @param col Column where to place the mark, 0-based. |api-indexing| /// @param opts Optional parameters. -/// - id : id of the extmark to edit. -/// - end_row : ending line of the mark, 0-based inclusive. +/// - conceal: either a boolean or a string. +/// - when a string is given, it should be either empty or a single +/// character. Enable concealing similar to |:syn-conceal|. +/// When a character is supplied it is used as |:syn-cchar|. +/// "hl_group" is used as highlight for the cchar if provided, +/// otherwise it defaults to |hl-Conceal|. +/// - when a boolean is given, true is equivalent to "" and false +/// overrides any existing conceal to remove it. +/// - conceal_lines: string which should be empty. When +/// provided, lines in the range are not drawn at all +/// (according to 'conceallevel'); the next unconcealed line +/// is drawn instead. +/// - cursorline_hl_group: highlight group used for the sign +/// column text when the cursor is on the same line as the +/// mark and 'cursorline' is enabled. /// - end_col : ending col of the mark, 0-based exclusive, or -1 to extend the range to end of line (if strict=false). +/// - end_right_gravity : boolean that indicates the direction +/// the extmark end position (if it exists) will be shifted +/// in when new text is inserted (true for right, false +/// for left). Defaults to false. +/// - end_row : ending line of the mark, 0-based inclusive. +/// - ephemeral : for use with |nvim_set_decoration_provider()| +/// callbacks. The mark will only be used for the current +/// redraw cycle, and not be permanently stored in the buffer. +/// - 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 +/// cursorline highlight). /// - 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 -/// cursorline highlight). -/// - virt_text : [](virtual-text) to link to this mark. -/// A list of `[text, highlight]` tuples, each representing a -/// text chunk with specified highlight. `highlight` element -/// can either be a single highlight group, or an array of -/// multiple highlight groups that will be stacked -/// (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. -/// - "inline": display at the specified column, and -/// shift the buffer text to the right as needed. -/// - virt_text_win_col : position the virtual text at a fixed -/// window column (starting from the first -/// text column of the screen line) instead -/// of "virt_text_pos". -/// - virt_text_hide : hide the virtual text when the background -/// text is selected or hidden because of -/// scrolling with 'nowrap' or 'smoothscroll'. -/// Currently only affects "overlay" virt_text. -/// - virt_text_repeat_linebreak : repeat the virtual text on -/// 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` @@ -454,6 +443,38 @@ ArrayOf(DictAs(get_extmark_item)) nvim_buf_get_extmarks(Buffer buf, Integer ns_i /// - "blend": blend with background text color. /// Not supported for "inline" virt_text. /// +/// - id : id of the extmark to edit. +/// - invalidate : boolean that indicates whether to hide the +/// extmark if the entirety of its range is deleted. For +/// hidden marks, an "invalid" key is added to the "details" +/// array of |nvim_buf_get_extmarks()| and family. If +/// "undo_restore" is false, the extmark is deleted instead. +/// - line_hl_group: highlight group used for the whole line. +/// - number_hl_group: highlight group used for the number column. +/// - priority: a priority value for the highlight group, sign +/// attribute or virtual text. For virtual text, item with +/// highest priority is drawn last. For example treesitter +/// highlighting uses a value of 100. +/// - right_gravity : boolean that indicates the direction +/// the extmark will be shifted in when new text is inserted +/// (true for right, false for left). Defaults to true. +/// - sign_hl_group: highlight group used for the sign column text. +/// - sign_text: string of length 1-2 used to display in the +/// sign column. +/// - spell: boolean indicating that spell checking should be +/// performed within this extmark +/// - strict: boolean that indicates extmark should not be placed +/// if the line or column value is past the end of the +/// buffer or end of the line respectively. Defaults to true. +/// - ui_watched: boolean that indicates the mark should be drawn +/// by a UI. When set, the UI will receive win_extmark events. +/// Note: the mark is positioned by virt_text attributes. Can be +/// used together with virt_text. +/// - undo_restore : Restore the exact position of the mark +/// if text around the mark was deleted and then restored by undo. +/// Defaults to true. +/// - url: A URL to associate with this extmark. In the TUI, the OSC 8 control +/// sequence is used to generate a clickable hyperlink to this URL. /// - virt_lines : virtual lines to add next to this mark /// This should be an array over lines, where each line in /// turn is an array over `[text, highlight]` tuples. In @@ -474,59 +495,38 @@ ArrayOf(DictAs(get_extmark_item)) nvim_buf_get_extmarks(Buffer buf, Integer ns_i /// - "trunc": truncate virtual lines on the right (default). /// - "scroll": virtual lines can scroll horizontally with 'nowrap', /// otherwise the same as "trunc". -/// - ephemeral : for use with |nvim_set_decoration_provider()| -/// callbacks. The mark will only be used for the current -/// redraw cycle, and not be permanently stored in the buffer. -/// - right_gravity : boolean that indicates the direction -/// the extmark will be shifted in when new text is inserted -/// (true for right, false for left). Defaults to true. -/// - end_right_gravity : boolean that indicates the direction -/// the extmark end position (if it exists) will be shifted -/// in when new text is inserted (true for right, false -/// for left). Defaults to false. -/// - undo_restore : Restore the exact position of the mark -/// if text around the mark was deleted and then restored by undo. -/// Defaults to true. -/// - invalidate : boolean that indicates whether to hide the -/// extmark if the entirety of its range is deleted. For -/// hidden marks, an "invalid" key is added to the "details" -/// array of |nvim_buf_get_extmarks()| and family. If -/// "undo_restore" is false, the extmark is deleted instead. -/// - priority: a priority value for the highlight group, sign -/// attribute or virtual text. For virtual text, item with -/// highest priority is drawn last. For example treesitter -/// highlighting uses a value of 100. -/// - strict: boolean that indicates extmark should not be placed -/// if the line or column value is past the end of the -/// buffer or end of the line respectively. Defaults to true. -/// - sign_text: string of length 1-2 used to display in the -/// sign column. -/// - sign_hl_group: highlight group used for the sign column text. -/// - number_hl_group: highlight group used for the number column. -/// - line_hl_group: highlight group used for the whole line. -/// - cursorline_hl_group: highlight group used for the sign -/// column text when the cursor is on the same line as the -/// mark and 'cursorline' is enabled. -/// - conceal: either a boolean or a string. -/// - when a string is given, it should be either empty or a single -/// character. Enable concealing similar to |:syn-conceal|. -/// When a character is supplied it is used as |:syn-cchar|. -/// "hl_group" is used as highlight for the cchar if provided, -/// otherwise it defaults to |hl-Conceal|. -/// - when a boolean is given, true is equivalent to "" and false -/// overrides any existing conceal to remove it. -/// - conceal_lines: string which should be empty. When -/// provided, lines in the range are not drawn at all -/// (according to 'conceallevel'); the next unconcealed line -/// is drawn instead. -/// - spell: boolean indicating that spell checking should be -/// performed within this extmark -/// - ui_watched: boolean that indicates the mark should be drawn -/// by a UI. When set, the UI will receive win_extmark events. -/// Note: the mark is positioned by virt_text attributes. Can be -/// used together with virt_text. -/// - url: A URL to associate with this extmark. In the TUI, the OSC 8 control -/// sequence is used to generate a clickable hyperlink to this URL. +/// - virt_text : [](virtual-text) to link to this mark. +/// A list of `[text, highlight]` tuples, each representing a +/// text chunk with specified highlight. `highlight` element +/// can either be a single highlight group, or an array of +/// multiple highlight groups that will be stacked +/// (highest priority last). +/// - virt_text_hide : hide the virtual text when the background +/// text is selected or hidden because of +/// scrolling with 'nowrap' or 'smoothscroll'. +/// Currently only affects "overlay" virt_text. +/// - 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. +/// - "inline": display at the specified column, and +/// shift the buffer text to the right as needed. +/// - virt_text_repeat_linebreak : repeat the virtual text on +/// wrapped lines. +/// - virt_text_win_col : position the virtual text at a fixed +/// window column (starting from the first +/// text column of the screen line) instead +/// of "virt_text_pos". /// /// @param[out] err Error details, if any /// @return Id of the created/updated extmark @@ -1054,18 +1054,14 @@ void nvim_buf_clear_namespace(Buffer buf, Integer ns_id, Integer line_start, Int /// /// @param ns_id Namespace id from |nvim_create_namespace()| /// @param opts Table of callbacks: -/// - on_start: called first on each screen redraw -/// ``` -/// ["start", tick] -/// ``` /// - on_buf: called for each buffer being redrawn (once per edit, /// before window callbacks) /// ``` /// ["buf", bufnr, tick] /// ``` -/// - on_win: called when starting to redraw a specific window. +/// - on_end: called at the end of a redraw cycle /// ``` -/// ["win", winid, bufnr, toprow, botrow] +/// ["end", tick] /// ``` /// - on_line: (deprecated, use on_range instead) /// ``` @@ -1086,9 +1082,13 @@ void nvim_buf_clear_namespace(Buffer buf, Integer ns_id, Integer line_start, Int /// which continues beyond the skipped position. A single integer /// return value `skip_row` is short for `skip_row, 0` /// -/// - on_end: called at the end of a redraw cycle +/// - on_start: called first on each screen redraw /// ``` -/// ["end", tick] +/// ["start", tick] +/// ``` +/// - on_win: called when starting to redraw a specific window. +/// ``` +/// ["win", winid, bufnr, toprow, botrow] /// ``` void nvim_set_decoration_provider(Integer ns_id, Dict(set_decoration_provider) *opts, Error *err) FUNC_API_SINCE(7) FUNC_API_LUA_ONLY diff --git a/src/nvim/api/options.c b/src/nvim/api/options.c index 14d4a2b286..bf4813d9ee 100644 --- a/src/nvim/api/options.c +++ b/src/nvim/api/options.c @@ -186,15 +186,15 @@ static void wipe_ft_buf(buf_T *buf) /// /// @param name Option name /// @param opts Optional parameters -/// - scope: One of "global" or "local". Analogous to -/// |:setglobal| and |:setlocal|, respectively. -/// - win: |window-ID|. Used for getting window local options. /// - buf: Buffer number. Used for getting buffer local options. /// Implies {scope} is "local". /// - filetype: |filetype|. Used to get the default option for a /// specific filetype. Cannot be used with any other option. /// Note: this will trigger |ftplugin| and all |FileType| /// autocommands for the corresponding filetype. +/// - scope: One of "global" or "local". Analogous to +/// |:setglobal| and |:setlocal|, respectively. +/// - win: |window-ID|. Used for getting window local options. /// @param[out] err Error details, if any /// @return Option value Object nvim_get_option_value(String name, Dict(option) *opts, Error *err) @@ -264,10 +264,10 @@ err: /// @param name Option name /// @param value New option value /// @param opts Optional parameters +/// - buf: Buffer number. Used for setting buffer local option. /// - scope: One of "global" or "local". Analogous to /// |:setglobal| and |:setlocal|, respectively. /// - win: |window-ID|. Used for setting window local option. -/// - buf: Buffer number. Used for setting buffer local option. /// @param[out] err Error details, if any void nvim_set_option_value(uint64_t channel_id, String name, Object value, Dict(option) *opts, Error *err) @@ -350,11 +350,11 @@ Dict nvim_get_all_options_info(Arena *arena, Error *err) /// /// @param name Option name /// @param opts Optional parameters +/// - buf: Buffer number. Used for getting buffer local options. +/// Implies {scope} is "local". /// - scope: One of "global" or "local". Analogous to /// |:setglobal| and |:setlocal|, respectively. /// - win: |window-ID|. Used for getting window local options. -/// - buf: Buffer number. Used for getting buffer local options. -/// Implies {scope} is "local". /// @param[out] err Error details, if any /// @return Option Information DictAs(get_option_info) nvim_get_option_info2(String name, Dict(option) *opts, Arena *arena, diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index ce9018a218..9ef98a0a22 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -111,10 +111,10 @@ Integer nvim_get_hl_id_by_name(String name, Error *err) /// @param ns_id Get highlight groups for namespace ns_id |nvim_get_namespaces()|. /// Use 0 to get global highlight groups |:highlight|. /// @param opts Options dict: -/// - name: (string) Get a highlight definition by name. +/// - create: (boolean, default true) When highlight group doesn't exist create it. /// - id: (integer) Get a highlight definition by id. /// - link: (boolean, default true) Show linked group name instead of effective definition |:hi-link|. -/// - create: (boolean, default true) When highlight group doesn't exist create it. +/// - name: (string) Get a highlight definition by name. /// /// @param[out] err Error details, if any. /// @return Highlight groups as a map from group name to a highlight definition map as in |nvim_set_hl()|, @@ -1140,13 +1140,13 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err) /// @param buf Buffer to use. Buffer contents (if any) will be written /// to the PTY. /// @param opts Optional parameters. +/// - force_crlf: (boolean, default true) Convert "\n" to "\r\n". /// - on_input: Lua callback for input sent, i e keypresses in terminal /// mode. Note: keypresses are sent raw as they would be to the pty /// master end. For instance, a carriage return is sent /// as a "\r", not as a "\n". |textlock| applies. It is possible /// to call |nvim_chan_send()| directly in the callback however. /// `["input", term, bufnr, data]` -/// - force_crlf: (boolean, default true) Convert "\n" to "\r\n". /// @param[out] err Error details, if any /// @return Channel id, or 0 on error Integer nvim_open_term(Buffer buf, Dict(open_term) *opts, Error *err) @@ -2175,15 +2175,15 @@ Tuple(Integer, Integer, Buffer, String) nvim_get_mark(String name, Dict(empty) * /// /// @param str Statusline string (see 'statusline'). /// @param opts Optional parameters. -/// - winid: (number) |window-ID| of the window to use as context for statusline. -/// - maxwidth: (number) Maximum width of statusline. /// - fillchar: (string) Character to fill blank spaces in the statusline (see /// 'fillchars'). Treated as single-width even if it isn't. /// - highlights: (boolean) Return highlight information. -/// - use_winbar: (boolean) Evaluate winbar instead of statusline. +/// - maxwidth: (number) Maximum width of statusline. +/// - use_statuscol_lnum: (number) Evaluate statuscolumn for this line number instead of statusline. /// - use_tabline: (boolean) Evaluate tabline instead of statusline. When true, {winid} /// is ignored. Mutually exclusive with {use_winbar}. -/// - use_statuscol_lnum: (number) Evaluate statuscolumn for this line number instead of statusline. +/// - use_winbar: (boolean) Evaluate winbar instead of statusline. +/// - winid: (number) |window-ID| of the window to use as context for statusline. /// /// @param[out] err Error details, if any. /// @return Dict containing statusline information, with these keys: @@ -2425,24 +2425,24 @@ static void redraw_status(win_T *wp, Dict(redraw) *opts, bool *flush) /// @see |:redraw| /// /// @param opts Optional parameters. -/// - win: Target a specific |window-ID| as described below. /// - buf: Target a specific buffer number as described below. +/// - cursor: Immediately update cursor position on the screen in +/// `win` or the current window. /// - flush: Update the screen with pending updates. -/// - valid: When present mark `win`, `buf`, or all windows for -/// redraw. When `true`, only redraw changed lines (useful for -/// decoration providers). When `false`, forcefully redraw. /// - range: Redraw a range in `buf`, the buffer in `win` or the /// current buffer (useful for decoration providers). Expects a /// tuple `[first, last]` with the first and last line number /// of the range, 0-based end-exclusive |api-indexing|. -/// - cursor: Immediately update cursor position on the screen in -/// `win` or the current window. /// - statuscolumn: Redraw the 'statuscolumn' in `buf`, `win` or /// all windows. /// - statusline: Redraw the 'statusline' in `buf`, `win` or all /// windows. -/// - winbar: Redraw the 'winbar' in `buf`, `win` or all windows. /// - tabline: Redraw the 'tabline'. +/// - valid: When present mark `win`, `buf`, or all windows for +/// redraw. When `true`, only redraw changed lines (useful for +/// decoration providers). When `false`, forcefully redraw. +/// - win: Target a specific |window-ID| as described below. +/// - winbar: Redraw the 'winbar' in `buf`, `win` or all windows. void nvim__redraw(Dict(redraw) *opts, Error *err) FUNC_API_SINCE(12) { diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c index bba587621c..2fcb249b41 100644 --- a/src/nvim/api/window.c +++ b/src/nvim/api/window.c @@ -467,13 +467,8 @@ void nvim_win_set_hl_ns(Window win, Integer ns_id, Error *err) /// /// @param win |window-ID|, or 0 for current window. /// @param opts Optional parameters: -/// - start_row: Starting line index, 0-based inclusive. -/// When omitted start at the very top. /// - end_row: Ending line index, 0-based inclusive. /// When omitted end at the very bottom. -/// - start_vcol: Starting virtual column index on "start_row", -/// 0-based inclusive, rounded down to full screen lines. -/// When omitted include the whole line. /// - end_vcol: Ending virtual column index on "end_row", /// 0-based exclusive, rounded up to full screen lines. /// When 0 only include diff filler and virtual lines above @@ -484,6 +479,11 @@ void nvim_win_set_hl_ns(Window win, Integer ns_id, Error *err) /// to find out how many buffer lines beyond "start_row" take /// up a certain number of logical lines (returned in /// "end_row" and "end_vcol"). +/// - start_row: Starting line index, 0-based inclusive. +/// When omitted start at the very top. +/// - start_vcol: Starting virtual column index on "start_row", +/// 0-based inclusive, rounded down to full screen lines. +/// When omitted include the whole line. /// @return Dict containing text height information, with these keys: /// - all: The total number of screen lines occupied by the range. /// - fill: The number of diff filler or virtual lines among them.