aboutsummaryrefslogtreecommitdiff
path: root/runtime/lua/vim/_meta
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/lua/vim/_meta')
-rw-r--r--runtime/lua/vim/_meta/api.lua1021
-rw-r--r--runtime/lua/vim/_meta/api_keysets.lua101
-rw-r--r--runtime/lua/vim/_meta/api_keysets_extra.lua167
-rw-r--r--runtime/lua/vim/_meta/builtin.lua133
-rw-r--r--runtime/lua/vim/_meta/builtin_types.lua6
-rw-r--r--runtime/lua/vim/_meta/json.lua2
-rw-r--r--runtime/lua/vim/_meta/lpeg.lua103
-rw-r--r--runtime/lua/vim/_meta/misc.lua3
-rw-r--r--runtime/lua/vim/_meta/mpack.lua5
-rw-r--r--runtime/lua/vim/_meta/options.lua736
-rw-r--r--runtime/lua/vim/_meta/re.lua54
-rw-r--r--runtime/lua/vim/_meta/regex.lua3
-rw-r--r--runtime/lua/vim/_meta/vimfn.lua268
-rw-r--r--runtime/lua/vim/_meta/vvars.lua779
14 files changed, 2509 insertions, 872 deletions
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 49269ba631..cb4c8749b8 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -38,6 +38,7 @@ function vim.api.nvim__get_runtime(pat, all, opts) end
--- @private
--- Returns object given as argument.
+---
--- This API function is used for testing. One should not rely on its presence
--- in plugins.
---
@@ -47,6 +48,7 @@ function vim.api.nvim__id(obj) end
--- @private
--- Returns array given as argument.
+---
--- This API function is used for testing. One should not rely on its presence
--- in plugins.
---
@@ -56,6 +58,7 @@ function vim.api.nvim__id_array(arr) end
--- @private
--- Returns dictionary given as argument.
+---
--- This API function is used for testing. One should not rely on its presence
--- in plugins.
---
@@ -65,6 +68,7 @@ function vim.api.nvim__id_dictionary(dct) end
--- @private
--- Returns floating-point value given as argument.
+---
--- This API function is used for testing. One should not rely on its presence
--- in plugins.
---
@@ -73,6 +77,9 @@ function vim.api.nvim__id_dictionary(dct) end
function vim.api.nvim__id_float(flt) end
--- @private
+--- NB: if your UI doesn't use hlstate, this will not return hlstate first
+--- time.
+---
--- @param grid integer
--- @param row integer
--- @param col integer
@@ -105,17 +112,20 @@ function vim.api.nvim__stats() end
function vim.api.nvim__unpack(str) end
--- Adds a highlight to buffer.
+---
--- Useful for plugins that dynamically generate highlights to a buffer (like
--- a semantic highlighter or linter). The function adds a single highlight to
--- a buffer. Unlike `matchaddpos()` highlights follow changes to line
--- numbering (as lines are inserted/removed above the highlighted line), like
--- signs and marks do.
+---
--- Namespaces are used for batch deletion/updating of a set of highlights. To
--- create a namespace, use `nvim_create_namespace()` which returns a
--- namespace id. Pass it in to this function as `ns_id` to add highlights to
--- the namespace. All highlights in the same namespace can then be cleared
--- with single call to `nvim_buf_clear_namespace()`. If the highlight never
--- will be deleted by an API call, pass `ns_id = -1`.
+---
--- As a shorthand, `ns_id = 0` can be used to create a new namespace for the
--- highlight, the allocated id is then returned. If `hl_group` is the empty
--- string no highlight is added, but a new `ns_id` is still returned. This is
@@ -128,11 +138,12 @@ function vim.api.nvim__unpack(str) end
--- @param line integer Line to highlight (zero-indexed)
--- @param col_start integer Start of (byte-indexed) column range to highlight
--- @param col_end integer End of (byte-indexed) column range to highlight, or -1 to
---- highlight to end of line
+--- highlight to end of line
--- @return integer
function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start, col_end) end
--- Activates buffer-update events on a channel, or as Lua callbacks.
+---
--- Example (Lua): capture buffer updates in a global `events` variable (use
--- "vim.print(events)" to see its contents):
---
@@ -145,76 +156,78 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
--- })
--- ```
---
+---
--- @param buffer integer Buffer handle, or 0 for current buffer
--- @param send_buffer boolean True if the initial notification should contain the
--- whole buffer: first notification will be
--- `nvim_buf_lines_event`. Else the first notification
--- will be `nvim_buf_changedtick_event`. Not for Lua
--- callbacks.
---- @param opts table<string,function> Optional parameters.
---- • on_lines: Lua callback invoked on change. Return `true` to detach. Args:
---- • the string "lines"
---- • buffer handle
---- • 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: Lua callback invoked on change. This
---- callback receives more granular information about the
---- change compared to on_lines. Return `true` to detach. Args:
---- • the string "bytes"
---- • buffer handle
---- • b:changedtick
---- • start row of the changed text (zero-indexed)
---- • start column of the changed text
---- • byte offset of the changed text (from the start of
---- the buffer)
---- • old end row of the changed text
---- • old end column of the changed text
---- • old end byte length of the changed text
---- • new end row of the changed text
---- • new end column of the changed text
---- • new end byte length of the changed text
----
---- • on_changedtick: Lua callback invoked on changedtick
---- increment without text change. Args:
---- • the string "changedtick"
---- • buffer handle
---- • b:changedtick
----
---- • on_detach: Lua callback invoked on detach. Args:
---- • the string "detach"
---- • buffer handle
----
---- • on_reload: Lua callback invoked on reload. The entire
---- buffer content should be considered changed. Args:
---- • the string "reload"
---- • buffer handle
----
---- • 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.
+--- @param opts vim.api.keyset.buf_attach Optional parameters.
+--- • on_lines: Lua callback invoked on change. Return a truthy
+--- value (not `false` or `nil`) to detach. Args:
+--- • the string "lines"
+--- • buffer handle
+--- • 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: Lua callback invoked on change. This callback
+--- receives more granular information about the change compared
+--- to on_lines. Return a truthy value (not `false` or `nil`) to
+--- detach. Args:
+--- • the string "bytes"
+--- • buffer handle
+--- • b:changedtick
+--- • start row of the changed text (zero-indexed)
+--- • start column of the changed text
+--- • byte offset of the changed text (from the start of the
+--- buffer)
+--- • old end row of the changed text (offset from start row)
+--- • old end column of the changed text (if old end row = 0,
+--- offset from start column)
+--- • old end byte length of the changed text
+--- • new end row of the changed text (offset from start row)
+--- • new end column of the changed text (if new end row = 0,
+--- offset from start column)
+--- • new end byte length of the changed text
+--- • on_changedtick: Lua callback invoked on changedtick
+--- increment without text change. Args:
+--- • the string "changedtick"
+--- • buffer handle
+--- • b:changedtick
+--- • on_detach: Lua callback invoked on detach. Args:
+--- • the string "detach"
+--- • buffer handle
+--- • on_reload: Lua callback invoked on reload. The entire buffer
+--- content should be considered changed. Args:
+--- • the string "reload"
+--- • buffer handle
+--- • 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.
--- @return boolean
function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end
--- call a function with buffer as temporary current buffer
+---
--- This temporarily switches current buffer to "buffer". If the current
--- window already shows "buffer", the window is not switched If a window
--- inside the current tabpage (including a float) already shows the buffer
--- One of these windows will be set as current window temporarily. Otherwise
--- a temporary scratch window (called the "autocmd window" for historical
--- reasons) will be used.
+---
--- This is useful e.g. to call Vimscript functions that only work with the
--- current buffer/window currently, like `termopen()`.
---
--- @param buffer integer Buffer handle, or 0 for current buffer
--- @param fun function Function to call inside the buffer (currently Lua callable
---- only)
+--- only)
--- @return any
function vim.api.nvim_buf_call(buffer, fun) end
@@ -227,14 +240,15 @@ function vim.api.nvim_buf_clear_highlight(buffer, ns_id, line_start, line_end) e
--- Clears `namespace`d objects (highlights, `extmarks`, virtual text) from a
--- region.
+---
--- Lines are 0-indexed. `api-indexing` To clear the namespace in the entire
--- buffer, specify line_start=0 and line_end=-1.
---
--- @param buffer integer Buffer handle, or 0 for current buffer
--- @param ns_id integer Namespace to clear, or -1 to clear all namespaces.
--- @param line_start integer Start of range of lines to clear
---- @param line_end integer End of range of lines to clear (exclusive) or -1 to
---- clear to end of buffer.
+--- @param line_end integer End of range of lines to clear (exclusive) or -1 to clear
+--- to end of buffer.
function vim.api.nvim_buf_clear_namespace(buffer, ns_id, line_start, line_end) end
--- Creates a buffer-local command `user-commands`.
@@ -268,6 +282,7 @@ function vim.api.nvim_buf_del_keymap(buffer, mode, lhs) end
function vim.api.nvim_buf_del_mark(buffer, name) end
--- Delete a buffer-local user-defined command.
+---
--- Only commands created with `:command-buffer` or
--- `nvim_buf_create_user_command()` can be deleted with this function.
---
@@ -284,9 +299,9 @@ function vim.api.nvim_buf_del_var(buffer, name) end
--- Deletes the buffer. See `:bwipeout`
---
--- @param buffer integer Buffer handle, or 0 for current buffer
---- @param opts table<string,any> Optional parameters. Keys:
---- • force: Force deletion and ignore unsaved changes.
---- • unload: Unloaded only, do not delete. See `:bunload`
+--- @param opts vim.api.keyset.buf_delete Optional parameters. Keys:
+--- • force: Force deletion and ignore unsaved changes.
+--- • unload: Unloaded only, do not delete. See `:bunload`
function vim.api.nvim_buf_delete(buffer, opts) end
--- Gets a changed tick of a buffer
@@ -307,15 +322,16 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end
--- @param buffer integer Buffer handle, or 0 for current buffer
--- @param ns_id integer Namespace id from `nvim_create_namespace()`
--- @param id integer Extmark id
---- @param opts table<string,any> Optional parameters. Keys:
---- • details: Whether to include the details dict
---- • hl_name: Whether to include highlight group name instead
---- of id, true if omitted
---- @return integer[]
+--- @param opts vim.api.keyset.get_extmark Optional parameters. Keys:
+--- • details: Whether to include the details dict
+--- • hl_name: Whether to include highlight group name instead of
+--- id, true if omitted
+--- @return vim.api.keyset.get_extmark_item
function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
---- Gets `extmarks` (including `signs`) in "traversal order" from a `charwise`
---- region defined by buffer positions (inclusive, 0-indexed `api-indexing`).
+--- Gets `extmarks` in "traversal order" from a `charwise` region defined by
+--- buffer positions (inclusive, 0-indexed `api-indexing`).
+---
--- Region can be given as (row,col) tuples, or valid extmark ids (whose
--- positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
--- respectively, thus the following are equivalent:
@@ -327,9 +343,15 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
---
--- If `end` is less than `start`, traversal works backwards. (Useful with
--- `limit`, to get the first marks prior to a given position.)
+---
--- Note: when using extmark ranges (marks with a end_row/end_col position)
--- the `overlap` option might be useful. Otherwise only the start position of
--- an extmark will be considered.
+---
+--- Note: legacy signs placed through the `:sign` commands are implemented as
+--- extmarks and will show up here. Their details array will contain a
+--- `sign_name` field.
+---
--- Example:
---
--- ```lua
@@ -347,37 +369,39 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
--- vim.print(ms)
--- ```
---
+---
--- @param buffer integer Buffer handle, or 0 for current buffer
--- @param ns_id integer Namespace id from `nvim_create_namespace()` or -1 for all
---- namespaces
+--- namespaces
--- @param start any Start of range: a 0-indexed (row, col) or valid extmark id
---- (whose position defines the bound). `api-indexing`
+--- (whose position defines the bound). `api-indexing`
--- @param end_ any End of range (inclusive): a 0-indexed (row, col) or valid
---- extmark id (whose position defines the bound).
---- `api-indexing`
+--- 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
---- • 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"
---- @return any[]
+--- • 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
+--- • 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"
+--- @return vim.api.keyset.get_extmark_item[]
function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end
--- Gets a list of buffer-local `mapping` definitions.
---
--- @param buffer integer Buffer handle, or 0 for current buffer
--- @param mode string Mode short-name ("n", "i", "v", ...)
---- @return table<string,any>[]
+--- @return vim.api.keyset.keymap[]
function vim.api.nvim_buf_get_keymap(buffer, mode) end
--- Gets a line-range from the buffer.
+---
--- Indexing is zero-based, end-exclusive. Negative indices are interpreted as
--- length+1+index: -1 refers to the index past the end. So to get the last
--- element use start=-2 and end=-1.
+---
--- Out-of-bounds indices are clamped to the nearest valid value, unless
--- `strict_indexing` is set.
---
@@ -391,6 +415,7 @@ function vim.api.nvim_buf_get_lines(buffer, start, end_, strict_indexing) end
--- Returns a `(row,col)` tuple representing the position of the named mark.
--- "End of line" column position is returned as `v:maxcol` (big number). See
--- `mark-motions`.
+---
--- Marks are (1,0)-indexed. `api-indexing`
---
--- @param buffer integer Buffer handle, or 0 for current buffer
@@ -410,10 +435,12 @@ function vim.api.nvim_buf_get_name(buffer) end
function vim.api.nvim_buf_get_number(buffer) end
--- Returns the byte offset of a line (0-indexed). `api-indexing`
+---
--- Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is one byte.
--- 'fileformat' and 'fileencoding' are ignored. The line index just after the
--- last line gives the total byte-count of the buffer. A final EOL byte is
--- counted if it would be written, see 'eol'.
+---
--- Unlike `line2byte()`, throws error for out-of-bounds indexing. Returns -1
--- for unloaded buffer.
---
@@ -429,10 +456,13 @@ function vim.api.nvim_buf_get_offset(buffer, index) end
function vim.api.nvim_buf_get_option(buffer, name) end
--- Gets a range from the buffer.
+---
--- This differs from `nvim_buf_get_lines()` in that it allows retrieving only
--- portions of a line.
+---
--- Indexing is zero-based. Row indices are end-inclusive, and column indices
--- are end-exclusive.
+---
--- Prefer `nvim_buf_get_lines()` when retrieving entire lines.
---
--- @param buffer integer Buffer handle, or 0 for current buffer
@@ -440,7 +470,7 @@ function vim.api.nvim_buf_get_option(buffer, name) end
--- @param start_col integer Starting column (byte offset) on first line
--- @param end_row integer Last line index, inclusive
--- @param end_col integer Ending column (byte offset) on last line, exclusive
---- @param opts table<string,any> Optional parameters. Currently unused.
+--- @param opts vim.api.keyset.empty Optional parameters. Currently unused.
--- @return string[]
function vim.api.nvim_buf_get_text(buffer, start_row, start_col, end_row, end_col, opts) end
@@ -471,13 +501,16 @@ function vim.api.nvim_buf_is_valid(buffer) end
function vim.api.nvim_buf_line_count(buffer) end
--- Creates or updates an `extmark`.
+---
--- By default a new extmark is created when no id is passed in, but it is
--- also possible to create a new mark by passing in a previously unused id or
--- move an existing mark by passing in its id. The caller must then keep
--- track of existing and unused ids itself. (Useful over RPC, to avoid
--- waiting for the return value.)
+---
--- Using the optional arguments, it is possible to use this to highlight a
--- range of text, and also to associate virtual text to the mark.
+---
--- If present, the position defined by `end_col` and `end_row` should be
--- after the start position in order for the extmark to cover a range. An
--- earlier end position is not an error, but then it behaves like an empty
@@ -488,108 +521,110 @@ function vim.api.nvim_buf_line_count(buffer) 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.
---- • end_col : ending col of the mark, 0-based exclusive.
---- • hl_group : name of the highlight group used to highlight
---- this mark.
---- • 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). A highlight group can be supplied either as a
---- string or as an integer, the latter which can be obtained
---- using `nvim_get_hl_id_by_name()`.
---- • virt_text_pos : position of virtual text. Possible values:
---- • "eol": right after eol character (default).
---- • "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.
---- • 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.
---- • "replace": only show the virt_text color. This is the
---- default.
---- • "combine": combine with background text color.
---- • "blend": blend with background text color. Not supported
---- for "inline" virt_text.
----
---- • 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, buffer
---- and window options do not affect the display of the text.
---- In particular 'wrap' and 'linebreak' options do not take
---- effect, so the number of extra screen lines will always
---- match the size of the array. However the 'tabstop' buffer
---- option is still used for hard tabs. By default lines are
---- placed below the buffer line containing the mark.
---- • virt_lines_above: place virtual lines above instead.
---- • virt_lines_leftcol: Place extmarks in the leftmost column
---- of the window, bypassing sign and number columns.
---- • ephemeral : for use with `nvim_set_decoration_provider()`
---- callbacks. The mark will only be used for the current
---- redraw cycle, and not be permantently 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. If
---- "undo_restore" is false, the extmark is deleted instead.
---- • priority: a priority value for the highlight group or sign
---- attribute. 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. Note: ranges are unsupported and decorations
---- are only applied to start_row
---- • sign_hl_group: name of the highlight group used to
---- highlight the sign column text. Note: ranges are
---- unsupported and decorations are only applied to start_row
---- • number_hl_group: name of the highlight group used to
---- highlight the number column. Note: ranges are unsupported
---- and decorations are only applied to start_row
---- • line_hl_group: name of the highlight group used to
---- highlight the whole line. Note: ranges are unsupported and
---- decorations are only applied to start_row
---- • cursorline_hl_group: name of the highlight group used to
---- highlight the line when the cursor is on the same line as
---- the mark and 'cursorline' is enabled. Note: ranges are
---- unsupported and decorations are only applied to start_row
---- • conceal: string which 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`.
---- • 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.
+--- • id : id of the extmark to edit.
+--- • end_row : ending line of the mark, 0-based inclusive.
+--- • end_col : ending col of the mark, 0-based exclusive.
+--- • hl_group : name of the highlight group used to highlight
+--- this mark.
+--- • 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). A
+--- highlight group can be supplied either as a string or as an
+--- integer, the latter which can be obtained using
+--- `nvim_get_hl_id_by_name()`.
+--- • virt_text_pos : position of virtual text. Possible values:
+--- • "eol": right after eol character (default).
+--- • "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.
+--- • "replace": only show the virt_text color. This is the
+--- default.
+--- • "combine": combine with background text color.
+--- • "blend": blend with background text color. Not supported
+--- for "inline" virt_text.
+--- • 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, buffer
+--- and window options do not affect the display of the text. In
+--- particular 'wrap' and 'linebreak' options do not take
+--- effect, so the number of extra screen lines will always
+--- match the size of the array. However the 'tabstop' buffer
+--- option is still used for hard tabs. By default lines are
+--- placed below the buffer line containing the mark.
+--- • virt_lines_above: place virtual lines above instead.
+--- • virt_lines_leftcol: Place extmarks in the leftmost column of
+--- the window, bypassing sign and number columns.
+--- • ephemeral : for use with `nvim_set_decoration_provider()`
+--- callbacks. The mark will only be used for the current redraw
+--- cycle, and not be permantently 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: name of the highlight group used to highlight
+--- the sign column text.
+--- • number_hl_group: name of the highlight group used to
+--- highlight the number column.
+--- • line_hl_group: name of the highlight group used to highlight
+--- the whole line.
+--- • cursorline_hl_group: name of the highlight group used to
+--- highlight the sign column text when the cursor is on the
+--- same line as the mark and 'cursorline' is enabled.
+--- • conceal: string which 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`.
+--- • 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.
+--- • scoped: boolean that indicates that the extmark should only
+--- be displayed in the namespace scope. (experimental)
--- @return integer
function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end
@@ -603,11 +638,14 @@ function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end
function vim.api.nvim_buf_set_keymap(buffer, mode, lhs, rhs, opts) end
--- Sets (replaces) a line-range in the buffer.
+---
--- Indexing is zero-based, end-exclusive. Negative indices are interpreted as
--- length+1+index: -1 refers to the index past the end. So to change or
--- delete the last element use start=-2 and end=-1.
+---
--- To insert lines at a given index, set `start` and `end` to the same index.
--- To delete a range of lines, set `replacement` to an empty array.
+---
--- Out-of-bounds indices are clamped to the nearest valid value, unless
--- `strict_indexing` is set.
---
@@ -620,13 +658,14 @@ function vim.api.nvim_buf_set_lines(buffer, start, end_, strict_indexing, replac
--- Sets a named mark in the given buffer, all marks are allowed
--- file/uppercase, visual, last change, etc. See `mark-motions`.
+---
--- Marks are (1,0)-indexed. `api-indexing`
---
--- @param buffer integer Buffer to set the mark on
--- @param name string Mark name
--- @param line integer Line number
--- @param col integer Column/row number
---- @param opts table<string,any> Optional parameters. Reserved for future use.
+--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
--- @return boolean
function vim.api.nvim_buf_set_mark(buffer, name, line, col, opts) end
@@ -643,16 +682,21 @@ function vim.api.nvim_buf_set_name(buffer, name) end
function vim.api.nvim_buf_set_option(buffer, name, value) end
--- Sets (replaces) a range in the buffer
+---
--- This is recommended over `nvim_buf_set_lines()` when only modifying parts
--- of a line, as extmarks will be preserved on non-modified parts of the
--- touched lines.
+---
--- Indexing is zero-based. Row indices are end-inclusive, and column indices
--- are end-exclusive.
---- To insert text at a given `(row, column)` location, use `start_row =
---- end_row = row` and `start_col = end_col = col`. To delete the text in a
---- range, use `replacement = {}`.
+---
+--- To insert text at a given `(row, column)` location, use
+--- `start_row = end_row = row` and `start_col = end_col = col`. To delete the
+--- text in a range, use `replacement = {}`.
+---
--- Prefer `nvim_buf_set_lines()` if you are only adding or deleting entire
--- lines.
+---
--- Prefer `nvim_put()` if you want to insert text at the cursor position.
---
--- @param buffer integer Buffer handle, or 0 for current buffer
@@ -675,11 +719,12 @@ function vim.api.nvim_buf_set_var(buffer, name, value) end
--- @param src_id integer
--- @param line integer
--- @param chunks any[]
---- @param opts table<string,any>
+--- @param opts vim.api.keyset.empty
--- @return integer
function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) end
--- Calls a Vimscript `Dictionary-function` with the given arguments.
+---
--- On execution error: fails with Vimscript error, updates v:errmsg.
---
--- @param dict any Dictionary, or String evaluating to a Vimscript `self` dict
@@ -689,6 +734,7 @@ function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) e
function vim.api.nvim_call_dict_function(dict, fn, args) end
--- Calls a Vimscript function with the given arguments.
+---
--- On execution error: fails with Vimscript error, updates v:errmsg.
---
--- @param fn string Function to call
@@ -700,6 +746,7 @@ function vim.api.nvim_call_function(fn, args) end
--- process. For the stdio channel `channel-stdio`, it writes to Nvim's
--- stdout. For an internal terminal instance (`nvim_open_term()`) it writes
--- directly to terminal output. See `channel-bytes` for more information.
+---
--- This function writes raw data, not RPC messages. If the channel was
--- created with `rpc=true` then the channel expects RPC messages, use
--- `vim.rpcnotify()` and `vim.rpcrequest()` instead.
@@ -716,41 +763,41 @@ function vim.api.nvim_chan_send(chan, data) end
--- • event: "pat1"
--- • event: { "pat1" }
--- • event: { "pat1", "pat2", "pat3" }
----
--- • pattern: (string|table)
--- • pattern or patterns to match exactly.
--- • For 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.
----
--- • defaults to clearing all patterns.
--- • NOTE: Cannot be used with {buffer}
----
--- • buffer: (bufnr)
--- • clear only `autocmd-buflocal` autocommands.
--- • NOTE: Cannot be used with {pattern}
----
--- • group: (string|int) The augroup name or id.
---- • NOTE: If not passed, will only delete autocmds not in any group.
+--- • NOTE: If not passed, will only delete autocmds not in any
+--- group.
function vim.api.nvim_clear_autocmds(opts) end
--- Executes an Ex command.
+---
--- Unlike `nvim_command()` this command takes a structured Dictionary instead
--- of a String. This allows for easier construction and manipulation of an Ex
--- command. This also allows for things such as having spaces inside a
--- command argument, expanding filenames in a command that otherwise doesn't
--- expand filenames, etc. Command arguments may also be Number, Boolean or
--- String.
+---
--- The first argument may also be used instead of count for commands that
--- support it in order to make their usage simpler with `vim.cmd()`. For
--- example, instead of `vim.cmd.bdelete{ count = 2 }`, you may do
--- `vim.cmd.bdelete(2)`.
+---
--- On execution error: fails with Vimscript error, updates v:errmsg.
---
--- @param cmd vim.api.keyset.cmd Command to execute. Must be a Dictionary that can contain the
---- same values as the return value of `nvim_parse_cmd()` except
---- "addr", "nargs" and "nextcmd" which are ignored if provided.
---- All values except for "cmd" are optional.
+--- same values as the return value of `nvim_parse_cmd()` except
+--- "addr", "nargs" and "nextcmd" which are ignored if provided.
+--- All values except for "cmd" are optional.
--- @param opts vim.api.keyset.cmd_opts Optional parameters.
--- • output: (boolean, default false) Whether to return command
--- output.
@@ -758,7 +805,9 @@ function vim.api.nvim_clear_autocmds(opts) end
function vim.api.nvim_cmd(cmd, opts) end
--- Executes an Ex command.
+---
--- On execution error: fails with Vimscript error, updates v:errmsg.
+---
--- Prefer using `nvim_cmd()` or `nvim_exec2()` over this. To evaluate
--- multiple lines of Vim script or an Ex command directly, use
--- `nvim_exec2()`. To construct an Ex command using a structured format and
@@ -773,7 +822,18 @@ function vim.api.nvim_command(command) end
--- @return string
function vim.api.nvim_command_output(command) end
+--- Set info for the completion candidate index. if the info was shown in a
+--- window, then the window and buffer ids are returned for further
+--- customization. If the text was not shown, an empty dict is returned.
+---
+--- @param index integer the completion candidate index
+--- @param opts vim.api.keyset.complete_set Optional parameters.
+--- • info: (string) info text.
+--- @return table<string,any>
+function vim.api.nvim_complete_set(index, opts) end
+
--- Create or get an autocommand group `autocmd-groups`.
+---
--- To get an existing group id, do:
---
--- ```lua
@@ -782,6 +842,7 @@ function vim.api.nvim_command_output(command) end
--- })
--- ```
---
+---
--- @param name string String: The name of the group
--- @param opts vim.api.keyset.create_augroup Dictionary Parameters
--- • clear (bool) optional: defaults to true. Clear existing
@@ -789,7 +850,10 @@ function vim.api.nvim_command_output(command) end
--- @return integer
function vim.api.nvim_create_augroup(name, opts) end
---- Creates an `autocommand` event handler, defined by `callback` (Lua function or Vimscript function name string) or `command` (Ex command string).
+--- Creates an `autocommand` event handler, defined by `callback` (Lua
+--- function or Vimscript function name string) or `command` (Ex command
+--- string).
+---
--- Example using Lua callback:
---
--- ```lua
@@ -817,39 +881,39 @@ function vim.api.nvim_create_augroup(name, opts) end
--- pattern = vim.fn.expand("~") .. "/some/path/*.py"
--- ```
---
+---
--- @param event any (string|array) Event(s) that will trigger the handler
--- (`callback` or `command`).
--- @param opts vim.api.keyset.create_autocmd Options dict:
---- • group (string|integer) optional: autocommand group name or
---- id to match against.
---- • pattern (string|array) optional: pattern(s) to match
---- literally `autocmd-pattern`.
---- • buffer (integer) optional: buffer number for buffer-local
---- autocommands `autocmd-buflocal`. Cannot be used with
---- {pattern}.
---- • desc (string) optional: description (for documentation and
---- troubleshooting).
---- • callback (function|string) optional: Lua function (or
---- Vimscript function name, if string) called when the
---- event(s) is triggered. Lua callback can return true to
---- delete the autocommand, and receives a table argument with
---- these keys:
---- • id: (number) autocommand id
---- • event: (string) name of the triggered event
---- `autocmd-events`
---- • group: (number|nil) autocommand group id, if any
---- • match: (string) expanded value of `<amatch>`
---- • buf: (number) expanded value of `<abuf>`
---- • file: (string) expanded value of `<afile>`
---- • data: (any) arbitrary data passed from
---- `nvim_exec_autocmds()`
----
---- • command (string) optional: Vim command to execute on event.
---- Cannot be used with {callback}
---- • once (boolean) optional: defaults to false. Run the
---- autocommand only once `autocmd-once`.
---- • nested (boolean) optional: defaults to false. Run nested
---- autocommands `autocmd-nested`.
+--- • group (string|integer) optional: autocommand group name or
+--- id to match against.
+--- • pattern (string|array) optional: pattern(s) to match
+--- literally `autocmd-pattern`.
+--- • buffer (integer) optional: buffer number for buffer-local
+--- autocommands `autocmd-buflocal`. Cannot be used with
+--- {pattern}.
+--- • desc (string) optional: description (for documentation and
+--- troubleshooting).
+--- • callback (function|string) optional: Lua function (or
+--- Vimscript function name, if string) called when the event(s)
+--- is triggered. Lua callback can return a truthy value (not
+--- `false` or `nil`) to delete the autocommand. Receives a
+--- table argument with these keys:
+--- • id: (number) autocommand id
+--- • event: (string) name of the triggered event
+--- `autocmd-events`
+--- • group: (number|nil) autocommand group id, if any
+--- • match: (string) expanded value of <amatch>
+--- • buf: (number) expanded value of <abuf>
+--- • file: (string) expanded value of <afile>
+--- • data: (any) arbitrary data passed from
+--- `nvim_exec_autocmds()`
+--- • command (string) optional: Vim command to execute on event.
+--- Cannot be used with {callback}
+--- • once (boolean) optional: defaults to false. Run the
+--- autocommand only once `autocmd-once`.
+--- • nested (boolean) optional: defaults to false. Run nested
+--- autocommands `autocmd-nested`.
--- @return integer
function vim.api.nvim_create_autocmd(event, opts) end
@@ -862,9 +926,11 @@ function vim.api.nvim_create_autocmd(event, opts) end
--- @return integer
function vim.api.nvim_create_buf(listed, scratch) end
---- Creates a new namespace or gets an existing one. *namespace*
+--- Creates a new namespace or gets an existing one. *namespace*
+---
--- Namespaces are used for buffer highlights and virtual text, see
--- `nvim_buf_add_highlight()` and `nvim_buf_set_extmark()`.
+---
--- Namespaces can be named or anonymous. If `name` matches an existing
--- namespace, the associated id is returned. If `name` is an empty string a
--- new, anonymous namespace is created.
@@ -874,7 +940,9 @@ function vim.api.nvim_create_buf(listed, scratch) end
function vim.api.nvim_create_namespace(name) end
--- Creates a global `user-commands` command.
+---
--- For Lua usage see `lua-guide-commands-create`.
+---
--- Example:
---
--- ```vim
@@ -883,51 +951,52 @@ function vim.api.nvim_create_namespace(name) end
--- Hello world!
--- ```
---
+---
--- @param name string Name of the new user command. Must begin with an uppercase
---- letter.
+--- letter.
--- @param command any 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
---- `<args>`
+--- <args>
--- • fargs: (table) The args split by unescaped whitespace
---- (when more than one argument is allowed), if any
---- `<f-args>`
+--- (when more than one argument is allowed), if any <f-args>
--- • nargs: (string) Number of arguments `:command-nargs`
--- • bang: (boolean) "true" if the command was executed with a
---- ! modifier `<bang>`
+--- ! modifier <bang>
--- • line1: (number) The starting line of the command range
---- `<line1>`
+--- <line1>
--- • line2: (number) The final line of the command range
---- `<line2>`
+--- <line2>
--- • range: (number) The number of items in the command range:
---- 0, 1, or 2 `<range>`
---- • count: (number) Any count supplied `<count>`
---- • reg: (string) The optional register, if specified `<reg>`
---- • mods: (string) Command modifiers, if any `<mods>`
+--- 0, 1, or 2 <range>
+--- • count: (number) Any count supplied <count>
+--- • reg: (string) The optional register, if specified <reg>
+--- • mods: (string) Command modifiers, if any <mods>
--- • 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 `command-attributes`.
---- • Set boolean attributes such as `:command-bang` or
---- `:command-bar` to true (but not `:command-buffer`, use
---- `nvim_buf_create_user_command()` instead).
---- • "complete" `:command-complete` also accepts a Lua
---- function which works like
---- `:command-completion-customlist`.
---- • Other parameters:
---- • desc: (string) Used for listing the command when a Lua
---- function is used for {command}.
---- • force: (boolean, default true) Override any previous
---- definition.
---- • preview: (function) Preview callback for 'inccommand'
---- `:command-preview`
+--- • Set boolean attributes such as `:command-bang` or
+--- `:command-bar` to true (but not `:command-buffer`, use
+--- `nvim_buf_create_user_command()` instead).
+--- • "complete" `:command-complete` also accepts a Lua function
+--- which works like `:command-completion-customlist`.
+--- • Other parameters:
+--- • desc: (string) Used for listing the command when a Lua
+--- function is used for {command}.
+--- • force: (boolean, default true) Override any previous
+--- definition.
+--- • preview: (function) Preview callback for 'inccommand'
+--- `:command-preview`
function vim.api.nvim_create_user_command(name, command, opts) end
--- Delete an autocommand group by id.
+---
--- To get a group id one can use `nvim_get_autocmds()`.
+---
--- NOTE: behavior differs from `:augroup-delete`. When deleting a group,
--- autocommands contained in this group will also be deleted and cleared.
--- This group will no longer exist.
@@ -936,6 +1005,7 @@ function vim.api.nvim_create_user_command(name, command, opts) end
function vim.api.nvim_del_augroup_by_id(id) end
--- Delete an autocommand group by name.
+---
--- NOTE: behavior differs from `:augroup-delete`. When deleting a group,
--- autocommands contained in this group will also be deleted and cleared.
--- This group will no longer exist.
@@ -953,6 +1023,7 @@ function vim.api.nvim_del_autocmd(id) end
function vim.api.nvim_del_current_line() end
--- Unmaps a global `mapping` for the given mode.
+---
--- To unmap a buffer-local mapping, use `nvim_buf_del_keymap()`.
---
--- @param mode string
@@ -977,15 +1048,15 @@ function vim.api.nvim_del_var(name) end
--- Echo a message.
---
---- @param chunks any[] A list of [text, hl_group] arrays, each representing a text
---- chunk with specified highlight. `hl_group` element can be
---- omitted for no highlight.
+--- @param chunks any[] A list of `[text, hl_group]` arrays, each representing a
+--- text chunk with specified highlight. `hl_group` element can
+--- be omitted for no highlight.
--- @param history boolean if true, add to `message-history`.
--- @param opts vim.api.keyset.echo_opts Optional parameters.
---- • verbose: Message was printed as a result of 'verbose'
---- option if Nvim was invoked with -V3log_file, the message
---- will be redirected to the log_file and suppressed from
---- direct output.
+--- • verbose: Message was printed as a result of 'verbose' option
+--- if Nvim was invoked with -V3log_file, the message will be
+--- redirected to the log_file and suppressed from direct
+--- output.
function vim.api.nvim_echo(chunks, history, opts) end
--- Writes a message to the Vim error buffer. Does not append "\n", the
@@ -1002,6 +1073,7 @@ function vim.api.nvim_err_writeln(str) end
--- Evaluates a Vimscript `expression`. Dictionaries and Lists are recursively
--- expanded.
+---
--- On execution error: fails with Vimscript error, updates v:errmsg.
---
--- @param expr string Vimscript expression string
@@ -1036,8 +1108,10 @@ function vim.api.nvim_exec(src, output) end
--- Executes Vimscript (multiline block of Ex commands), like anonymous
--- `:source`.
+---
--- Unlike `nvim_command()` this function supports heredocs, script-scope
--- (s:), etc.
+---
--- On execution error: fails with Vimscript error, updates v:errmsg.
---
--- @param src string Vimscript code
@@ -1052,24 +1126,27 @@ function vim.api.nvim_exec2(src, opts) end
---
--- @param event any (String|Array) The event or events to execute
--- @param opts vim.api.keyset.exec_autocmds Dictionary of autocommand options:
---- • group (string|integer) optional: the autocommand group name
---- or id to match against. `autocmd-groups`.
---- • pattern (string|array) optional: defaults to "*"
---- `autocmd-pattern`. Cannot be used with {buffer}.
---- • buffer (integer) optional: buffer number
---- `autocmd-buflocal`. Cannot be used with {pattern}.
---- • modeline (bool) optional: defaults to true. Process the
---- modeline after the autocommands `<nomodeline>`.
---- • data (any): arbitrary data to send to the autocommand
---- callback. See `nvim_create_autocmd()` for details.
+--- • group (string|integer) optional: the autocommand group name
+--- or id to match against. `autocmd-groups`.
+--- • pattern (string|array) optional: defaults to "*"
+--- `autocmd-pattern`. Cannot be used with {buffer}.
+--- • buffer (integer) optional: buffer number `autocmd-buflocal`.
+--- Cannot be used with {pattern}.
+--- • modeline (bool) optional: defaults to true. Process the
+--- modeline after the autocommands <nomodeline>.
+--- • data (any): arbitrary data to send to the autocommand
+--- callback. See `nvim_create_autocmd()` for details.
function vim.api.nvim_exec_autocmds(event, opts) end
--- Sends input-keys to Nvim, subject to various quirks controlled by `mode`
--- flags. This is a blocking call, unlike `nvim_input()`.
+---
--- On execution error: does not fail, but updates v:errmsg.
+---
--- To input sequences like <C-o> use `nvim_replace_termcodes()` (typically
--- with escape_ks=false) to replace `keycodes`, then pass the result to
--- nvim_feedkeys().
+---
--- Example:
---
--- ```vim
@@ -1077,6 +1154,7 @@ function vim.api.nvim_exec_autocmds(event, opts) end
--- :call nvim_feedkeys(key, 'n', v:false)
--- ```
---
+---
--- @param keys string to be typed
--- @param mode string behavior flags, see `feedkeys()`
--- @param escape_ks boolean If true, escape K_SPECIAL bytes in `keys`. This should be
@@ -1085,6 +1163,7 @@ function vim.api.nvim_exec_autocmds(event, opts) end
function vim.api.nvim_feedkeys(keys, mode, escape_ks) end
--- Gets the option information for all options.
+---
--- The dictionary has the full option names as keys and option metadata
--- dictionaries as detailed at `nvim_get_option_info2()`.
---
@@ -1092,6 +1171,7 @@ function vim.api.nvim_feedkeys(keys, mode, escape_ks) end
function vim.api.nvim_get_all_options_info() end
--- Get all autocommands that match the corresponding {opts}.
+---
--- These examples will get autocommands matching ALL the given criteria:
---
--- ```lua
@@ -1121,17 +1201,18 @@ function vim.api.nvim_get_all_options_info() end
--- • buffer: Buffer number or list of buffer numbers for buffer
--- local autocommands `autocmd-buflocal`. Cannot be used with
--- {pattern}
---- @return any[]
+--- @return vim.api.keyset.get_autocmds.ret[]
function vim.api.nvim_get_autocmds(opts) end
--- Gets information about a channel.
---
---- @param chan integer
+--- @param chan integer channel_id, or 0 for current channel
--- @return table<string,any>
function vim.api.nvim_get_chan_info(chan) end
--- Returns the 24-bit RGB value of a `nvim_get_color_map()` color name or
--- "#rrggbb" hexadecimal string.
+---
--- Example:
---
--- ```vim
@@ -1139,18 +1220,21 @@ function vim.api.nvim_get_chan_info(chan) end
--- :echo nvim_get_color_by_name("#cbcbcb")
--- ```
---
+---
--- @param name string Color name or "#rrggbb" string
--- @return integer
function vim.api.nvim_get_color_by_name(name) end
--- Returns a map of color names and RGB values.
+---
--- Keys are color names (e.g. "Aqua") and values are 24-bit RGB color values
--- (e.g. 65535).
---
---- @return table<string,any>
+--- @return table<string,integer>
function vim.api.nvim_get_color_map() end
--- Gets a map of global (non-buffer-local) Ex commands.
+---
--- Currently only `user-commands` are supported, not builtin Ex commands.
---
--- @param opts vim.api.keyset.get_commands Optional parameters. Currently only supports {"builtin":false}
@@ -1191,13 +1275,13 @@ function vim.api.nvim_get_current_win() end
--- `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.
---- • 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.
---- @return table<string,any>
+--- • name: (string) Get a highlight definition by name.
+--- • 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.
+--- @return vim.api.keyset.hl_info
function vim.api.nvim_get_hl(ns_id, opts) end
--- @deprecated
@@ -1213,6 +1297,7 @@ function vim.api.nvim_get_hl_by_id(hl_id, rgb) end
function vim.api.nvim_get_hl_by_name(name, rgb) end
--- Gets a highlight group by name
+---
--- similar to `hlID()`, but allocates a new ID if not present.
---
--- @param name string
@@ -1232,28 +1317,29 @@ function vim.api.nvim_get_hl_ns(opts) end
--- Gets a list of global (non-buffer-local) `mapping` definitions.
---
--- @param mode string Mode short-name ("n", "i", "v", ...)
---- @return table<string,any>[]
+--- @return vim.api.keyset.keymap[]
function vim.api.nvim_get_keymap(mode) end
--- Returns a `(row, col, buffer, buffername)` tuple representing the position
--- of the uppercase/file named mark. "End of line" column position is
--- returned as `v:maxcol` (big number). See `mark-motions`.
+---
--- Marks are (1,0)-indexed. `api-indexing`
---
--- @param name string Mark name
---- @param opts table<string,any> Optional parameters. Reserved for future use.
---- @return any[]
+--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
+--- @return vim.api.keyset.get_mark
function vim.api.nvim_get_mark(name, opts) end
--- Gets the current mode. `mode()` "blocking" is true if Nvim is waiting for
--- input.
---
---- @return table<string,any>
+--- @return vim.api.keyset.get_mode
function vim.api.nvim_get_mode() end
--- Gets existing, non-anonymous `namespace`s.
---
---- @return table<string,any>
+--- @return table<string,integer>
function vim.api.nvim_get_namespaces() end
--- @deprecated
@@ -1263,10 +1349,11 @@ function vim.api.nvim_get_option(name) end
--- @deprecated
--- @param name string
---- @return table<string,any>
+--- @return vim.api.keyset.get_option_info
function vim.api.nvim_get_option_info(name) end
--- Gets the option information for one option from arbitrary buffer or window
+---
--- Resulting dictionary has keys:
--- • name: Name of the option (like 'filetype')
--- • shortname: Shortened name of the option (like 'ft')
@@ -1293,7 +1380,7 @@ function vim.api.nvim_get_option_info(name) end
--- • win: `window-ID`. Used for getting window local options.
--- • buf: Buffer number. Used for getting buffer local options.
--- Implies {scope} is "local".
---- @return table<string,any>
+--- @return vim.api.keyset.get_option_info
function vim.api.nvim_get_option_info2(name, opts) end
--- Gets the value of an option. The behavior of this function matches that of
@@ -1328,10 +1415,12 @@ function vim.api.nvim_get_proc(pid) end
function vim.api.nvim_get_proc_children(pid) end
--- Find files in runtime directories
+---
--- "name" can contain wildcards. For example
--- nvim_get_runtime_file("colors/*.vim", true) will return all color scheme
--- files. Always use forward slashes (/) in the search pattern for
--- subdirectories regardless of platform.
+---
--- It is not an error to not find any files. An empty array is returned then.
---
--- @param name string pattern of files to search for
@@ -1354,6 +1443,7 @@ function vim.api.nvim_get_vvar(name) end
--- Queues raw user-input. Unlike `nvim_feedkeys()`, this uses a low-level
--- input buffer and the call is non-blocking (input is processed
--- asynchronously by the eventloop).
+---
--- On execution error: does not fail, but updates v:errmsg.
---
--- @param keys string to be typed
@@ -1361,14 +1451,15 @@ function vim.api.nvim_get_vvar(name) end
function vim.api.nvim_input(keys) end
--- Send mouse event from GUI.
+---
--- Non-blocking: does not wait on any result, but queues the event to be
--- processed soon by the event loop.
---
--- @param button string Mouse button: one of "left", "right", "middle", "wheel",
---- "move".
---- @param action string For ordinary buttons, one of "press", "drag", "release".
---- For the wheel, one of "up", "down", "left", "right".
---- Ignored for "move".
+--- "move", "x1", "x2".
+--- @param action string For ordinary buttons, one of "press", "drag", "release". For
+--- the wheel, one of "up", "down", "left", "right". Ignored for
+--- "move".
--- @param modifier string String of modifiers each represented by a single char. The
--- same specifiers are used as for a key press, except that
--- the "-" separator is optional, so "C-A-", "c-a" and "CA"
@@ -1379,6 +1470,7 @@ function vim.api.nvim_input(keys) end
function vim.api.nvim_input_mouse(button, action, modifier, grid, row, col) end
--- Gets the current list of buffer handles
+---
--- Includes unlisted (unloaded/deleted) buffers, like `:ls!`. Use
--- `nvim_buf_is_loaded()` to check if a buffer is loaded.
---
@@ -1417,6 +1509,7 @@ function vim.api.nvim_list_wins() end
function vim.api.nvim_load_context(dict) end
--- Notify the user with a message
+---
--- Relays the call to vim.notify . By default forwards your message in the
--- echo area but can be overridden to trigger desktop notifications.
---
@@ -1427,10 +1520,12 @@ function vim.api.nvim_load_context(dict) end
function vim.api.nvim_notify(msg, log_level, opts) end
--- Open a terminal instance in a buffer
+---
--- By default (and currently the only option) the terminal will not be
--- connected to an external process. Instead, input send on the channel will
--- be echoed directly by the terminal. This is useful to display ANSI
--- terminal sequences returned as part of a rpc message, or similar.
+---
--- Note: to directly initiate the terminal using the right size, display the
--- buffer in a configured window before calling this. For instance, for a
--- floating display, first create an empty buffer using `nvim_create_buf()`,
@@ -1439,34 +1534,51 @@ function vim.api.nvim_notify(msg, log_level, opts) end
--- virtual terminal having the intended size.
---
--- @param buffer integer the buffer to use (expected to be empty)
---- @param opts table<string,function> Optional parameters.
---- • 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]
+--- @param opts vim.api.keyset.open_term Optional parameters.
+--- • 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
function vim.api.nvim_open_term(buffer, opts) end
---- Open a new window.
---- Currently this is used to open floating and external windows. Floats are
---- windows that are drawn above the split layout, at some anchor position in
---- some other window. Floats can be drawn internally or by external GUI with
---- the `ui-multigrid` extension. External windows are only supported with
---- multigrid GUIs, and are displayed as separate top-level windows.
+--- Opens a new split window, or a floating window if `relative` is specified,
+--- or an external window (managed by the UI) if `external` is specified.
+---
+--- Floats are windows that are drawn above the split layout, at some anchor
+--- position in some other window. Floats can be drawn internally or by
+--- external GUI with the `ui-multigrid` extension. External windows are only
+--- supported with multigrid GUIs, and are displayed as separate top-level
+--- windows.
+---
--- For a general overview of floats, see `api-floatwin`.
---- Exactly one of `external` and `relative` must be specified. The `width`
---- and `height` of the new window must be specified.
+---
+--- The `width` and `height` of the new window must be specified when opening
+--- a floating window, but are optional for normal windows.
+---
+--- If `relative` and `external` are omitted, a normal "split" window is
+--- created. The `win` property determines which window will be split. If no
+--- `win` is provided or `win == 0`, a window will be created adjacent to the
+--- current window. If -1 is provided, a top-level split will be created.
+--- `vertical` and `split` are only valid for normal windows, and are used to
+--- control split direction. For `vertical`, the exact direction is determined
+--- by `'splitright'` and `'splitbelow'`. Split windows cannot have
+--- `bufpos`/`row`/`col`/`border`/`title`/`footer` properties.
+---
--- With relative=editor (row=0,col=0) refers to the top-left corner of the
--- screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right
--- corner. Fractional values are allowed, but the builtin implementation
--- (used by non-multigrid UIs) will always round down to nearest integer.
+---
--- Out-of-bounds values, and configurations that make the float not fit
--- inside the main editor, are allowed. The builtin implementation truncates
--- values so floats are fully within the main screen grid. External GUIs
--- could let floats hover outside of the main window like a tooltip, but this
--- should not be used to specify arbitrary WM screen positions.
+---
--- Example (Lua): window-relative float
---
--- ```lua
@@ -1479,12 +1591,21 @@ function vim.api.nvim_open_term(buffer, opts) end
--- ```lua
--- vim.api.nvim_open_win(0, false,
--- {relative='win', width=12, height=3, bufpos={100,10}})
+--- ```
+---
+--- Example (Lua): vertical split left of the current window
+---
+--- ```lua
+--- vim.api.nvim_open_win(0, false, {
+--- split = 'left',
+--- win = 0
--- })
--- ```
---
+---
--- @param buffer integer Buffer to display, or 0 for current buffer
--- @param enter boolean Enter the window (make it the current window)
---- @param config vim.api.keyset.float_config Map defining the window configuration. Keys:
+--- @param config vim.api.keyset.win_config Map defining the window configuration. Keys:
--- • relative: Sets the window layout to "floating", placed at
--- (row,col) coordinates relative to:
--- • "editor" The global editor grid
@@ -1492,25 +1613,23 @@ function vim.api.nvim_open_term(buffer, opts) end
--- window.
--- • "cursor" Cursor position in current window.
--- • "mouse" Mouse position
----
---- • win: `window-ID` for relative="win".
+--- • win: `window-ID` window to split, or relative window when
+--- creating a float (relative="win").
--- • anchor: Decides which corner of the float to place at
--- (row,col):
--- • "NW" northwest (default)
--- • "NE" northeast
--- • "SW" southwest
--- • "SE" southeast
----
--- • width: Window width (in character cells). Minimum of 1.
--- • height: Window height (in character cells). Minimum of 1.
--- • bufpos: Places float relative to buffer text (only when
---- relative="win"). Takes a tuple of zero-indexed [line,
---- column]. `row` and `col` if given are applied relative to this position, else they
---- default to:
+--- relative="win"). Takes a tuple of zero-indexed
+--- `[line, column]`. `row` and `col` if given are applied
+--- relative to this position, else they default to:
--- • `row=1` and `col=0` if `anchor` is "NW" or "NE"
--- • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus
--- like a tooltip near the buffer text).
----
--- • row: Row position in units of "screen cell height", may be
--- fractional.
--- • col: Column position in units of "screen cell width", may
@@ -1521,8 +1640,9 @@ function vim.api.nvim_open_term(buffer, opts) end
--- • external: GUI should display the window as an external
--- top-level window. Currently accepts no other positioning
--- configuration together with this.
---- • zindex: Stacking order. floats with higher `zindex` go on top on floats with lower indices. Must be larger
---- than zero. The following screen elements have hard-coded
+--- • zindex: Stacking order. floats with higher `zindex` go on
+--- top on floats with lower indices. Must be larger than
+--- zero. The following screen elements have hard-coded
--- z-indices:
--- • 100: insert completion popupmenu
--- • 200: message scrollback
@@ -1530,7 +1650,6 @@ function vim.api.nvim_open_term(buffer, opts) end
--- wildoptions+=pum) The default value for floats are 50.
--- In general, values below 100 are recommended, unless
--- there is a good reason to overshadow builtin elements.
----
--- • style: (optional) Configure the appearance of the window.
--- Currently only supports one value:
--- • "minimal" Nvim will display the window with many UI
@@ -1543,14 +1662,13 @@ function vim.api.nvim_open_term(buffer, opts) end
--- empty. The end-of-buffer region is hidden by setting
--- `eob` flag of 'fillchars' to a space char, and clearing
--- the `hl-EndOfBuffer` region in 'winhighlight'.
----
--- • border: Style of (optional) window border. This can either
--- be a string or an array. The string values are
--- • "none": No border (default).
--- • "single": A single line box.
--- • "double": A double line box.
---- • "rounded": Like "single", but with rounded corners ("╭"
---- etc.).
+--- • "rounded": Like "single", but with rounded corners
+--- ("╭" etc.).
--- • "solid": Adds padding by a single whitespace cell.
--- • "shadow": A drop shadow effect by blending with the
--- background.
@@ -1558,18 +1676,35 @@ function vim.api.nvim_open_term(buffer, opts) end
--- any divisor of eight. The array will specify the eight
--- chars building up the border in a clockwise fashion
--- starting with the top-left corner. As an example, the
---- double box style could be specified as [ "╔", "═" ,"╗",
---- "║", "╝", "═", "╚", "║" ]. If the number of chars are
---- less than eight, they will be repeated. Thus an ASCII
---- border could be specified as [ "/", "-", "\\", "|" ], or
---- all chars the same as [ "x" ]. An empty string can be
---- used to turn off a specific border, for instance, [ "",
---- "", "", ">", "", "", "", "<" ] will only make vertical
---- borders but not horizontal ones. By default,
---- `FloatBorder` highlight is used, which links to
---- `WinSeparator` when not defined. It could also be
---- specified by character: [ ["+", "MyCorner"], ["x",
---- "MyBorder"] ].
+--- double box style could be specified as:
+--- ```
+--- [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ].
+--- ```
+---
+--- If the number of chars are less than eight, they will be
+--- repeated. Thus an ASCII border could be specified as
+--- ```
+--- [ "/", "-", \"\\\\\", "|" ],
+--- ```
+---
+--- or all chars the same as
+--- ```
+--- [ "x" ].
+--- ```
+---
+--- An empty string can be used to turn off a specific border,
+--- for instance,
+--- ```
+--- [ "", "", "", ">", "", "", "", "<" ]
+--- ```
+---
+--- will only make vertical borders but not horizontal ones.
+--- By default, `FloatBorder` highlight is used, which links
+--- to `WinSeparator` when not defined. It could also be
+--- specified by character:
+--- ```
+--- [ ["+", "MyCorner"], ["x", "MyBorder"] ].
+--- ```
---
--- • title: Title (optional) in window border, string or list.
--- List should consist of `[text, highlight]` tuples. If
@@ -1589,6 +1724,8 @@ function vim.api.nvim_open_term(buffer, opts) end
--- • fixed: If true when anchor is NW or SW, the float window
--- would be kept fixed even if the window would be truncated.
--- • hide: If true the floating window will be hidden.
+--- • vertical: Split vertically `:vertical`.
+--- • split: Split direction: "left", "right", "above", "below".
--- @return integer
function vim.api.nvim_open_win(buffer, enter, config) end
@@ -1599,28 +1736,29 @@ function vim.api.nvim_open_win(buffer, enter, config) end
function vim.api.nvim_out_write(str) end
--- Parse command line.
+---
--- Doesn't check the validity of command arguments.
---
--- @param str string Command line string to parse. Cannot contain "\n".
---- @param opts table<string,any> Optional parameters. Reserved for future use.
---- @return table<string,any>
+--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
+--- @return vim.api.keyset.parse_cmd
function vim.api.nvim_parse_cmd(str, opts) end
--- Parse a Vimscript expression.
---
--- @param expr string Expression to parse. Always treated as a single line.
--- @param flags string Flags:
---- • "m" if multiple expressions in a row are allowed (only
---- the first one will be parsed),
---- • "E" if EOC tokens are not allowed (determines whether
---- they will stop parsing process or be recognized as an
---- operator/space, though also yielding an error).
---- • "l" when needing to start parsing with lvalues for
---- ":let" or ":for". Common flag sets:
---- • "m" to parse like for ":echo".
---- • "E" to parse like for "<C-r>=".
---- • empty string for ":call".
---- • "lm" to parse for ":let".
+--- • "m" if multiple expressions in a row are allowed (only the
+--- first one will be parsed),
+--- • "E" if EOC tokens are not allowed (determines whether they
+--- will stop parsing process or be recognized as an
+--- operator/space, though also yielding an error).
+--- • "l" when needing to start parsing with lvalues for ":let"
+--- or ":for". Common flag sets:
+--- • "m" to parse like for `":echo"`.
+--- • "E" to parse like for `"<C-r>="`.
+--- • empty string for ":call".
+--- • "lm" to parse for ":let".
--- @param highlight boolean If true, return value will also include "highlight" key
--- containing array of 4-tuples (arrays) (Integer, Integer,
--- Integer, String), where first three numbers define the
@@ -1631,8 +1769,10 @@ function vim.api.nvim_parse_cmd(str, opts) end
function vim.api.nvim_parse_expression(expr, flags, highlight) end
--- Pastes at cursor, in any mode.
+---
--- Invokes the `vim.paste` handler, which handles each mode appropriately.
--- Sets redo/undo. Faster than `nvim_input()`. Lines break at LF ("\n").
+---
--- Errors ('nomodifiable', `vim.paste()` failure, …) are reflected in `err`
--- but do not affect the return value (which is strictly decided by
--- `vim.paste()`). On error, subsequent calls are ignored ("drained") until
@@ -1641,7 +1781,8 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end
--- @param data string Multiline input. May be binary (containing NUL bytes).
--- @param crlf boolean Also break lines at CR and CRLF.
--- @param phase integer -1: paste in a single call (i.e. without streaming). To
---- "stream" a paste, call `nvim_paste` sequentially with these `phase` values:
+--- "stream" a paste, call `nvim_paste` sequentially with these
+--- `phase` values:
--- • 1: starts the paste (exactly once)
--- • 2: continues the paste (zero or more times)
--- • 3: ends the paste (exactly once)
@@ -1649,16 +1790,16 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end
function vim.api.nvim_paste(data, crlf, phase) end
--- Puts text at cursor, in any mode.
+---
--- Compare `:put` and `p` which are always linewise.
---
--- @param lines string[] `readfile()`-style list of lines. `channel-lines`
--- @param type string Edit behavior: any `getregtype()` result, or:
---- • "b" `blockwise-visual` mode (may include width, e.g. "b3")
---- • "c" `charwise` mode
---- • "l" `linewise` mode
---- • "" guess by contents, see `setreg()`
---- @param after boolean If true insert after cursor (like `p`), or before (like
---- `P`).
+--- • "b" `blockwise-visual` mode (may include width, e.g. "b3")
+--- • "c" `charwise` mode
+--- • "l" `linewise` mode
+--- • "" guess by contents, see `setreg()`
+--- @param after boolean If true insert after cursor (like `p`), or before (like `P`).
--- @param follow boolean If true place cursor at end of inserted text.
function vim.api.nvim_put(lines, type, after, follow) end
@@ -1673,19 +1814,20 @@ function vim.api.nvim_put(lines, type, after, follow) end
function vim.api.nvim_replace_termcodes(str, from_part, do_lt, special) end
--- Selects an item in the completion popup menu.
+---
--- If neither `ins-completion` nor `cmdline-completion` popup menu is active
--- this API call is silently ignored. Useful for an external UI using
--- `ui-popupmenu` to control the popup menu with the mouse. Can also be used
--- in a mapping; use <Cmd> `:map-cmd` or a Lua mapping to ensure the mapping
--- doesn't end completion mode.
---
---- @param item integer Index (zero-based) of the item to select. Value of -1
---- selects nothing and restores the original text.
+--- @param item integer Index (zero-based) of the item to select. Value of -1 selects
+--- nothing and restores the original text.
--- @param insert boolean For `ins-completion`, whether the selection should be
--- inserted in the buffer. Ignored for `cmdline-completion`.
--- @param finish boolean Finish the completion and dismiss the popup menu. Implies
--- {insert}.
---- @param opts table<string,any> Optional parameters. Reserved for future use.
+--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
function vim.api.nvim_select_popupmenu_item(item, insert, finish, opts) end
--- Sets the current buffer.
@@ -1714,13 +1856,16 @@ function vim.api.nvim_set_current_tabpage(tabpage) end
function vim.api.nvim_set_current_win(window) end
--- Set or change decoration provider for a `namespace`
+---
--- This is a very general purpose interface for having Lua callbacks being
--- triggered during the redraw code.
+---
--- The expected usage is to set `extmarks` for the currently redrawn buffer.
--- `nvim_buf_set_extmark()` can be called to add marks on a per-window or
--- per-lines basis. Use the `ephemeral` key to only use the mark for the
--- current screen redraw (the callback will be called again for the next
--- redraw).
+---
--- Note: this function should not be called often. Rather, the callbacks
--- themselves can be used to throttle unneeded callbacks. the `on_start`
--- callback can return `false` to disable the provider until the next redraw.
@@ -1729,28 +1874,44 @@ function vim.api.nvim_set_current_win(window) end
--- plugin managing multiple sources of decoration should ideally only set one
--- provider, and merge the sources internally. You can use multiple `ns_id`
--- for the extmarks set/modified inside the callback anyway.
+---
--- Note: doing anything other than setting extmarks is considered
--- experimental. Doing things like changing options are not explicitly
--- forbidden, but is likely to have unexpected consequences (such as 100% CPU
--- consumption). doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is
--- quite dubious for the moment.
+---
--- Note: It is not allowed to remove or update extmarks in 'on_line'
--- callbacks.
---
--- @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 (before window
---- callbacks) ["buf", bufnr, tick]
---- • on_win: called when starting to redraw a specific window.
---- botline_guess is an approximation that does not exceed the
---- last line number. ["win", winid, bufnr, topline,
---- botline_guess]
---- • on_line: called for each buffer line being redrawn. (The
---- interaction with fold lines is subject to change) ["win",
---- winid, bufnr, row]
---- • on_end: called at the end of a redraw cycle ["end", tick]
+--- • on_start: called first on each screen redraw
+--- ```
+--- ["start", tick]
+--- ```
+---
+--- • on_buf: called for each buffer being redrawn (before window
+--- callbacks)
+--- ```
+--- ["buf", bufnr, tick]
+--- ```
+---
+--- • on_win: called when starting to redraw a specific window.
+--- ```
+--- ["win", winid, bufnr, topline, botline]
+--- ```
+---
+--- • on_line: called for each buffer line being redrawn. (The
+--- interaction with fold lines is subject to change)
+--- ```
+--- ["line", winid, bufnr, row]
+--- ```
+---
+--- • on_end: called at the end of a redraw cycle
+--- ```
+--- ["end", tick]
+--- ```
function vim.api.nvim_set_decoration_provider(ns_id, opts) end
--- Sets a highlight group.
@@ -1762,31 +1923,31 @@ function vim.api.nvim_set_decoration_provider(ns_id, opts) end
--- activate them.
--- @param name string Highlight group name, e.g. "ErrorMsg"
--- @param val vim.api.keyset.highlight Highlight definition map, accepts the following keys:
---- • fg (or foreground): color name or "#RRGGBB", see note.
---- • bg (or background): color name or "#RRGGBB", see note.
---- • sp (or special): color name or "#RRGGBB"
---- • blend: integer between 0 and 100
---- • bold: boolean
---- • standout: boolean
---- • underline: boolean
---- • undercurl: boolean
---- • underdouble: boolean
---- • underdotted: boolean
---- • underdashed: boolean
---- • strikethrough: boolean
---- • italic: boolean
---- • reverse: boolean
---- • nocombine: boolean
---- • link: name of another highlight group to link to, see
---- `:hi-link`.
---- • default: Don't override existing definition `:hi-default`
---- • ctermfg: Sets foreground of cterm color `ctermfg`
---- • ctermbg: Sets background of cterm color `ctermbg`
---- • cterm: cterm attribute map, like `highlight-args`. If not
---- set, cterm attributes will match those from the attribute
---- map documented above.
---- • force: if true force update the highlight group when it
---- exists.
+--- • fg: color name or "#RRGGBB", see note.
+--- • bg: color name or "#RRGGBB", see note.
+--- • sp: color name or "#RRGGBB"
+--- • blend: integer between 0 and 100
+--- • bold: boolean
+--- • standout: boolean
+--- • underline: boolean
+--- • undercurl: boolean
+--- • underdouble: boolean
+--- • underdotted: boolean
+--- • underdashed: boolean
+--- • strikethrough: boolean
+--- • italic: boolean
+--- • reverse: boolean
+--- • nocombine: boolean
+--- • link: name of another highlight group to link to, see
+--- `:hi-link`.
+--- • default: Don't override existing definition `:hi-default`
+--- • ctermfg: Sets foreground of cterm color `ctermfg`
+--- • ctermbg: Sets background of cterm color `ctermbg`
+--- • cterm: cterm attribute map, like `highlight-args`. If not
+--- set, cterm attributes will match those from the attribute map
+--- documented above.
+--- • force: if true force update the highlight group when it
+--- exists.
function vim.api.nvim_set_hl(ns_id, name, val) end
--- Set active namespace for highlights defined with `nvim_set_hl()`. This can
@@ -1797,6 +1958,7 @@ function vim.api.nvim_set_hl_ns(ns_id) end
--- Set active namespace for highlights defined with `nvim_set_hl()` while
--- redrawing.
+---
--- This function meant to be called while redrawing, primarily from
--- `nvim_set_decoration_provider()` on_win and on_line callbacks, which are
--- allowed to change the namespace during a redraw cycle.
@@ -1805,9 +1967,12 @@ function vim.api.nvim_set_hl_ns(ns_id) end
function vim.api.nvim_set_hl_ns_fast(ns_id) end
--- Sets a global `mapping` for the given mode.
+---
--- To set a buffer-local mapping, use `nvim_buf_set_keymap()`.
+---
--- Unlike `:map`, leading/trailing whitespace is accepted as part of the
---- {lhs} or {rhs}. Empty {rhs} is `<Nop>`. `keycodes` are replaced as usual.
+--- {lhs} or {rhs}. Empty {rhs} is <Nop>. `keycodes` are replaced as usual.
+---
--- Example:
---
--- ```vim
@@ -1820,14 +1985,15 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end
--- nmap <nowait> <Space><NL> <Nop>
--- ```
---
---- @param mode string Mode short-name (map command prefix: "n", "i", "v", "x", …) or
---- "!" for `:map!`, or empty string for `:map`. "ia", "ca" or
+---
+--- @param mode string Mode short-name (map command prefix: "n", "i", "v", "x", …)
+--- or "!" for `:map!`, or empty string for `:map`. "ia", "ca" or
--- "!a" for abbreviation in Insert mode, Cmdline mode, or both,
--- respectively
--- @param lhs string Left-hand-side `{lhs}` of the mapping.
--- @param rhs string Right-hand-side `{rhs}` of the mapping.
--- @param opts vim.api.keyset.keymap Optional parameters map: Accepts all `:map-arguments` as keys
---- except `<buffer>`, values are booleans (default false). Also:
+--- except <buffer>, values are booleans (default false). Also:
--- • "noremap" disables `recursive_mapping`, like `:noremap`
--- • "desc" human-readable description.
--- • "callback" Lua function called in place of {rhs}.
@@ -1845,15 +2011,16 @@ function vim.api.nvim_set_option(name, value) end
--- Sets the value of an option. The behavior of this function matches that of
--- `:set`: for global-local options, both the global and local value are set
--- unless otherwise specified with {scope}.
+---
--- Note the options {win} and {buf} cannot be used together.
---
--- @param name string Option name
--- @param value any New option value
--- @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 setting window local option.
---- • 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.
@@ -1919,11 +2086,24 @@ function vim.api.nvim_tabpage_list_wins(tabpage) end
--- @param value any Variable value
function vim.api.nvim_tabpage_set_var(tabpage, name, value) end
+--- Sets the current window in a tabpage
+---
+--- @param tabpage integer Tabpage handle, or 0 for current tabpage
+--- @param win integer Window handle, must already belong to {tabpage}
+function vim.api.nvim_tabpage_set_win(tabpage, win) end
+
+--- Adds the namespace scope to the window.
+---
+--- @param window integer Window handle, or 0 for current window
+--- @param ns_id integer the namespace to add
+--- @return boolean
+function vim.api.nvim_win_add_ns(window, ns_id) end
+
--- Calls a function with window as temporary current window.
---
--- @param window integer Window handle, or 0 for current window
--- @param fun function Function to call inside the window (currently Lua callable
---- only)
+--- only)
--- @return any
function vim.api.nvim_win_call(window, fun) end
@@ -1931,8 +2111,8 @@ function vim.api.nvim_win_call(window, fun) end
---
--- @param window integer Window handle, or 0 for current window
--- @param force boolean Behave like `:close!` The last window of a buffer with
---- unwritten changes can be closed. The buffer will become
---- hidden, even if 'hidden' is not set.
+--- unwritten changes can be closed. The buffer will become
+--- hidden, even if 'hidden' is not set.
function vim.api.nvim_win_close(window, force) end
--- Removes a window-scoped (w:) variable
@@ -1948,11 +2128,13 @@ function vim.api.nvim_win_del_var(window, name) end
function vim.api.nvim_win_get_buf(window) end
--- Gets window configuration.
+---
--- The returned value may be given to `nvim_open_win()`.
+---
--- `relative` is empty for normal windows.
---
--- @param window integer Window handle, or 0 for current window
---- @return table<string,any>
+--- @return vim.api.keyset.win_config
function vim.api.nvim_win_get_config(window) end
--- Gets the (1,0)-indexed, buffer-relative cursor position for a given window
@@ -1969,6 +2151,12 @@ function vim.api.nvim_win_get_cursor(window) end
--- @return integer
function vim.api.nvim_win_get_height(window) end
+--- Gets all the namespaces scopes associated with a window.
+---
+--- @param window integer Window handle, or 0 for current window
+--- @return integer[]
+function vim.api.nvim_win_get_ns(window) end
+
--- Gets the window number
---
--- @param window integer Window handle, or 0 for current window
@@ -2008,6 +2196,7 @@ function vim.api.nvim_win_get_width(window) end
--- Closes the window and hide the buffer it contains (like `:hide` with a
--- `window-ID`).
+---
--- Like `:hide` the buffer becomes hidden unless another window is editing
--- it, or 'bufhidden' is `unload`, `delete` or `wipe` as opposed to `:close`
--- or `nvim_win_close()`, which will close the buffer.
@@ -2021,6 +2210,13 @@ function vim.api.nvim_win_hide(window) end
--- @return boolean
function vim.api.nvim_win_is_valid(window) end
+--- Removes the namespace scope from the window.
+---
+--- @param window integer Window handle, or 0 for current window
+--- @param ns_id integer the namespace to remove
+--- @return boolean
+function vim.api.nvim_win_remove_ns(window, ns_id) end
+
--- Sets the current buffer in a window, without side effects
---
--- @param window integer Window handle, or 0 for current window
@@ -2029,11 +2225,12 @@ function vim.api.nvim_win_set_buf(window, buffer) end
--- Configures window layout. Currently only for floating and external windows
--- (including changing a split window to those layouts).
+---
--- When reconfiguring a floating window, absent option keys will not be
--- changed. `row`/`col` and `relative` must be reconfigured together.
---
--- @param window integer Window handle, or 0 for current window
---- @param config vim.api.keyset.float_config Map defining the window configuration, see `nvim_open_win()`
+--- @param config vim.api.keyset.win_config Map defining the window configuration, see `nvim_open_win()`
function vim.api.nvim_win_set_config(window, config) end
--- Sets the (1,0)-indexed cursor position in the window. `api-indexing` This
@@ -2052,6 +2249,7 @@ function vim.api.nvim_win_set_height(window, height) end
--- Set highlight namespace for a window. This will use highlights defined
--- with `nvim_set_hl()` for this namespace, but fall back to global
--- highlights (ns=0) when missing.
+---
--- This takes precedence over the 'winhighlight' option.
---
--- @param window integer
@@ -2080,23 +2278,26 @@ function vim.api.nvim_win_set_width(window, width) end
--- Computes the number of screen lines occupied by a range of text in a given
--- window. Works for off-screen text and takes folds into account.
+---
--- Diff filler or virtual lines above a line are counted as a part of that
--- line, unless the line is on "start_row" and "start_vcol" is specified.
+---
--- Diff filler or virtual lines below the last buffer line are counted in the
--- result when "end_row" is omitted.
+---
--- Line indexing is similar to `nvim_buf_get_text()`.
---
--- @param window integer Window handle, 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
---- omitted include the whole line.
+--- • 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 omitted
+--- include the whole line.
--- @return table<string,any>
function vim.api.nvim_win_text_height(window, opts) end
diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua
index f69e5a92c7..37e4372196 100644
--- a/runtime/lua/vim/_meta/api_keysets.lua
+++ b/runtime/lua/vim/_meta/api_keysets.lua
@@ -3,6 +3,19 @@
-- DO NOT EDIT
error('Cannot require a meta file')
+--- @class vim.api.keyset.buf_attach
+--- @field on_lines? function
+--- @field on_bytes? function
+--- @field on_changedtick? function
+--- @field on_detach? function
+--- @field on_reload? function
+--- @field utf_sizes? boolean
+--- @field preview? boolean
+
+--- @class vim.api.keyset.buf_delete
+--- @field force? boolean
+--- @field unload? boolean
+
--- @class vim.api.keyset.clear_autocmds
--- @field buffer? integer
--- @field event? any
@@ -55,6 +68,9 @@ error('Cannot require a meta file')
--- @class vim.api.keyset.cmd_opts
--- @field output? boolean
+--- @class vim.api.keyset.complete_set
+--- @field info? string
+
--- @class vim.api.keyset.context
--- @field types? any[]
@@ -74,6 +90,8 @@ error('Cannot require a meta file')
--- @class vim.api.keyset.echo_opts
--- @field verbose? boolean
+--- @class vim.api.keyset.empty
+
--- @class vim.api.keyset.eval_statusline
--- @field winid? integer
--- @field maxwidth? integer
@@ -93,28 +111,6 @@ error('Cannot require a meta file')
--- @class vim.api.keyset.exec_opts
--- @field output? boolean
---- @class vim.api.keyset.float_config
---- @field row? number
---- @field col? number
---- @field width? integer
---- @field height? integer
---- @field anchor? string
---- @field relative? string
---- @field win? integer
---- @field bufpos? any[]
---- @field external? boolean
---- @field focusable? boolean
---- @field zindex? integer
---- @field border? any
---- @field title? any
---- @field title_pos? string
---- @field footer? any
---- @field footer_pos? string
---- @field style? string
---- @field noautocmd? boolean
---- @field fixed? boolean
---- @field hide? boolean
-
--- @class vim.api.keyset.get_autocmds
--- @field event? any
--- @field group? any
@@ -124,6 +120,10 @@ error('Cannot require a meta file')
--- @class vim.api.keyset.get_commands
--- @field builtin? boolean
+--- @class vim.api.keyset.get_extmark
+--- @field details? boolean
+--- @field hl_name? boolean
+
--- @class vim.api.keyset.get_extmarks
--- @field limit? integer
--- @field details? boolean
@@ -170,6 +170,7 @@ error('Cannot require a meta file')
--- @field fg_indexed? boolean
--- @field bg_indexed? boolean
--- @field force? boolean
+--- @field url? string
--- @class vim.api.keyset.highlight_cterm
--- @field bold? boolean
@@ -196,6 +197,10 @@ error('Cannot require a meta file')
--- @field desc? string
--- @field replace_keycodes? boolean
+--- @class vim.api.keyset.open_term
+--- @field on_input? function
+--- @field force_crlf? boolean
+
--- @class vim.api.keyset.option
--- @field scope? string
--- @field win? integer
@@ -220,11 +225,12 @@ error('Cannot require a meta file')
--- @field end_line? integer
--- @field end_row? integer
--- @field end_col? integer
---- @field hl_group? any
+--- @field hl_group? number|string
--- @field virt_text? any[]
--- @field virt_text_pos? string
--- @field virt_text_win_col? integer
--- @field virt_text_hide? boolean
+--- @field virt_text_repeat_linebreak? boolean
--- @field hl_eol? boolean
--- @field hl_mode? string
--- @field invalidate? boolean
@@ -237,14 +243,17 @@ error('Cannot require a meta file')
--- @field virt_lines_leftcol? boolean
--- @field strict? boolean
--- @field sign_text? string
---- @field sign_hl_group? any
---- @field number_hl_group? any
---- @field line_hl_group? any
---- @field cursorline_hl_group? any
+--- @field sign_hl_group? number|string
+--- @field number_hl_group? number|string
+--- @field line_hl_group? number|string
+--- @field cursorline_hl_group? number|string
--- @field conceal? string
--- @field spell? boolean
--- @field ui_watched? boolean
--- @field undo_restore? boolean
+--- @field url? string
+--- @field scoped? boolean
+--- @field _subpriority? integer
--- @class vim.api.keyset.user_command
--- @field addr? any
@@ -260,8 +269,46 @@ error('Cannot require a meta file')
--- @field range? any
--- @field register? boolean
+--- @class vim.api.keyset.win_config
+--- @field row? number
+--- @field col? number
+--- @field width? integer
+--- @field height? integer
+--- @field anchor? string
+--- @field relative? string
+--- @field split? string
+--- @field win? integer
+--- @field bufpos? any[]
+--- @field external? boolean
+--- @field focusable? boolean
+--- @field vertical? boolean
+--- @field zindex? integer
+--- @field border? any
+--- @field title? any
+--- @field title_pos? string
+--- @field footer? any
+--- @field footer_pos? string
+--- @field style? string
+--- @field noautocmd? boolean
+--- @field fixed? boolean
+--- @field hide? boolean
+
--- @class vim.api.keyset.win_text_height
--- @field start_row? integer
--- @field end_row? integer
--- @field start_vcol? integer
--- @field end_vcol? integer
+
+--- @class vim.api.keyset.xdl_diff
+--- @field on_hunk? function
+--- @field result_type? string
+--- @field algorithm? string
+--- @field ctxlen? integer
+--- @field interhunkctxlen? integer
+--- @field linematch? any
+--- @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
diff --git a/runtime/lua/vim/_meta/api_keysets_extra.lua b/runtime/lua/vim/_meta/api_keysets_extra.lua
new file mode 100644
index 0000000000..d61dd2c02f
--- /dev/null
+++ b/runtime/lua/vim/_meta/api_keysets_extra.lua
@@ -0,0 +1,167 @@
+--- @meta _
+error('Cannot require a meta file')
+
+--- Extra types we can't generate keysets for
+
+--- @class vim.api.keyset.extmark_details
+--- @field ns_id integer
+--- @field right_gravity boolean
+---
+--- @field end_row? integer
+--- @field end_col? integer
+--- @field end_right_gravity? integer
+---
+--- @field priority? integer
+---
+--- @field undo_restore? false
+--- @field invalidate? true
+--- @field invalid? true
+---
+--- @field hl_group? string
+--- @field hl_eol? boolean
+---
+--- @field conceal? boolean
+--- @field spell? boolean
+--- @field ui_watched? boolean
+--- @field url? boolean
+--- @field hl_mode? string
+---
+--- @field virt_text? {[1]: string, [2]: string}[]
+--- @field virt_text_hide? boolean
+--- @field virt_text_repeat_linebreak? boolean
+--- @field virt_text_win_col? integer
+--- @field virt_text_pos? string
+---
+--- @field virt_lines? {[1]: string, [2]: string}[][]
+--- @field virt_lines_above? boolean
+--- @field virt_lines_leftcol? boolean
+---
+--- @field sign_text? string
+--- @field sign_name? string
+--- @field sign_hl_group? string
+--- @field number_hl_group? string
+--- @field line_hl_group? string
+--- @field cursorline_hl_group? string
+
+--- @class vim.api.keyset.get_extmark_item
+--- @field [1] integer row
+--- @field [2] integer col
+--- @field [3] vim.api.keyset.extmark_details?
+
+--- @class vim.api.keyset.get_mark
+--- @field [1] integer row
+--- @field [2] integer col
+--- @field [3] integer buffer
+--- @field [4] string buffername
+
+--- @class vim.api.keyset.get_autocmds.ret
+--- @field id? integer
+--- @field group? integer
+--- @field group_name? integer
+--- @field desc? string
+--- @field event? string
+--- @field command? string
+--- @field callback? function
+--- @field once? boolean
+--- @field pattern? string
+--- @field buflocal? boolean
+--- @field buffer? integer
+
+--- @class vim.api.keyset.command_info
+--- @field name string
+--- @field definition string
+--- @field script_id integer
+--- @field bang boolean
+--- @field bar boolean
+--- @field register boolean
+--- @field keepscript boolean
+--- @field preview boolean
+--- @field nargs string
+--- @field complete? string
+--- @field complete_arg? string
+--- @field count? string
+--- @field range? string
+--- @field addr? string
+
+--- @class vim.api.keyset.hl_info.base
+--- @field reverse? true
+--- @field bold? true
+--- @field italic? true
+--- @field underline? true
+--- @field undercurl? true
+--- @field underdouble? true
+--- @field underdotted? true
+--- @field underdashed? true
+--- @field standout? true
+--- @field strikethrough? true
+--- @field altfont? true
+--- @field nocombine? true
+
+--- @class vim.api.keyset.hl_info.cterm : vim.api.keyset.hl_info.base
+--- @field ctermfg? integer
+--- @field ctermbg? integer
+--- @field foreground? integer
+--- @field background? integer
+
+--- @class vim.api.keyset.hl_info : vim.api.keyset.hl_info.base
+--- @field fg? integer
+--- @field bg? integer
+--- @field sp? integer
+--- @field default? true
+--- @field link? string
+--- @field blend? integer
+--- @field cterm? vim.api.keyset.hl_info.cterm
+
+--- @class vim.api.keyset.get_mode
+--- @field blocking boolean
+--- @field mode string
+
+--- @class vim.api.keyset.get_option_info
+--- @field name string
+--- @field shortname string
+--- @field scope 'buf'|'win'|'global'
+--- @field global_local boolean
+--- @field commalist boolean
+--- @field flaglist boolean
+--- @field was_set boolean
+--- @field last_set_id integer
+--- @field last_set_linenr integer
+--- @field last_set_chan integer
+--- @field type 'string'|'boolean'|'number'
+--- @field default string|boolean|integer
+--- @field allows_duplicates boolean
+
+--- @class vim.api.keyset.parse_cmd.mods
+--- @field filter { force: boolean, pattern: string }
+--- @field silent boolean
+--- @field emsg_silent boolean
+--- @field unsilent boolean
+--- @field sandbox boolean
+--- @field noautocmd boolean
+--- @field tab integer
+--- @field verbose integer
+--- @field browse boolean
+--- @field confirm boolean
+--- @field hide boolean
+--- @field keepalt boolean
+--- @field keepjumps boolean
+--- @field keepmarks boolean
+--- @field keeppatterns boolean
+--- @field lockmarks boolean
+--- @field noswapfile boolean
+--- @field vertical boolean
+--- @field horizontal boolean
+--- @field split ''|'botright'|'topleft'|'belowright'|'aboveleft'
+
+--- @class vim.api.keyset.parse_cmd
+--- @field addr 'line'|'arg'|'buf'|'load'|'win'|'tab'|'qf'|'none'|'?'
+--- @field args string[]
+--- @field bang boolean
+--- @field cmd string
+--- @field magic {bar: boolean, file: boolean}
+--- @field mods vim.api.keyset.parse_cmd.mods
+--- @field nargs '0'|'1'|'?'|'+'|'*'
+--- @field nextcmd string
+--- @field range? integer[]
+--- @field count? integer
+--- @field reg? string
diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua
index eeba356672..9a67667f02 100644
--- a/runtime/lua/vim/_meta/builtin.lua
+++ b/runtime/lua/vim/_meta/builtin.lua
@@ -1,66 +1,72 @@
---@meta
-
-- luacheck: no unused args
----@defgroup vim.builtin
----
----@brief <pre>help
----vim.api.{func}({...}) *vim.api*
---- Invokes Nvim |API| function {func} with arguments {...}.
---- Example: call the "nvim_get_current_line()" API function: >lua
---- print(tostring(vim.api.nvim_get_current_line()))
----
----vim.NIL *vim.NIL*
---- Special value representing NIL in |RPC| and |v:null| in Vimscript
---- conversion, and similar cases. Lua `nil` cannot be used as part of a Lua
---- table representing a Dictionary or Array, because it is treated as
---- missing: `{"foo", nil}` is the same as `{"foo"}`.
----
----vim.type_idx *vim.type_idx*
---- Type index for use in |lua-special-tbl|. Specifying one of the values from
---- |vim.types| allows typing the empty table (it is unclear whether empty Lua
---- table represents empty list or empty array) and forcing integral numbers
---- to be |Float|. See |lua-special-tbl| for more details.
----
----vim.val_idx *vim.val_idx*
---- Value index for tables representing |Float|s. A table representing
---- floating-point value 1.0 looks like this: >lua
---- {
---- [vim.type_idx] = vim.types.float,
---- [vim.val_idx] = 1.0,
---- }
----< See also |vim.type_idx| and |lua-special-tbl|.
----
----vim.types *vim.types*
---- Table with possible values for |vim.type_idx|. Contains two sets of
---- key-value pairs: first maps possible values for |vim.type_idx| to
---- human-readable strings, second maps human-readable type names to values
---- for |vim.type_idx|. Currently contains pairs for `float`, `array` and
---- `dictionary` types.
----
---- Note: One must expect that values corresponding to `vim.types.float`,
---- `vim.types.array` and `vim.types.dictionary` fall under only two following
---- assumptions:
---- 1. Value may serve both as a key and as a value in a table. Given the
---- properties of Lua tables this basically means “value is not `nil`”.
---- 2. For each value in `vim.types` table `vim.types[vim.types[value]]` is the
---- same as `value`.
---- No other restrictions are put on types, and it is not guaranteed that
---- values corresponding to `vim.types.float`, `vim.types.array` and
---- `vim.types.dictionary` will not change or that `vim.types` table will only
---- contain values for these three types.
----
---- *log_levels* *vim.log.levels*
----Log levels are one of the values defined in `vim.log.levels`:
----
---- vim.log.levels.DEBUG
---- vim.log.levels.ERROR
---- vim.log.levels.INFO
---- vim.log.levels.TRACE
---- vim.log.levels.WARN
---- vim.log.levels.OFF
----
----</pre>
+error('Cannot require a meta file')
+
+--- @brief <pre>help
+--- vim.api.{func}({...}) *vim.api*
+--- Invokes Nvim |API| function {func} with arguments {...}.
+--- Example: call the "nvim_get_current_line()" API function: >lua
+--- print(tostring(vim.api.nvim_get_current_line()))
+---
+--- vim.NIL *vim.NIL*
+--- Special value representing NIL in |RPC| and |v:null| in Vimscript
+--- conversion, and similar cases. Lua `nil` cannot be used as part of a Lua
+--- table representing a Dictionary or Array, because it is treated as
+--- missing: `{"foo", nil}` is the same as `{"foo"}`.
+---
+--- vim.type_idx *vim.type_idx*
+--- Type index for use in |lua-special-tbl|. Specifying one of the values from
+--- |vim.types| allows typing the empty table (it is unclear whether empty Lua
+--- table represents empty list or empty array) and forcing integral numbers
+--- to be |Float|. See |lua-special-tbl| for more details.
+---
+--- vim.val_idx *vim.val_idx*
+--- Value index for tables representing |Float|s. A table representing
+--- floating-point value 1.0 looks like this: >lua
+--- {
+--- [vim.type_idx] = vim.types.float,
+--- [vim.val_idx] = 1.0,
+--- }
+--- < See also |vim.type_idx| and |lua-special-tbl|.
+---
+--- vim.types *vim.types*
+--- Table with possible values for |vim.type_idx|. Contains two sets of
+--- key-value pairs: first maps possible values for |vim.type_idx| to
+--- human-readable strings, second maps human-readable type names to values
+--- for |vim.type_idx|. Currently contains pairs for `float`, `array` and
+--- `dictionary` types.
+---
+--- Note: One must expect that values corresponding to `vim.types.float`,
+--- `vim.types.array` and `vim.types.dictionary` fall under only two following
+--- assumptions:
+--- 1. Value may serve both as a key and as a value in a table. Given the
+--- properties of Lua tables this basically means “value is not `nil`”.
+--- 2. For each value in `vim.types` table `vim.types[vim.types[value]]` is the
+--- same as `value`.
+--- No other restrictions are put on types, and it is not guaranteed that
+--- values corresponding to `vim.types.float`, `vim.types.array` and
+--- `vim.types.dictionary` will not change or that `vim.types` table will only
+--- contain values for these three types.
+---
+--- *log_levels* *vim.log.levels*
+--- Log levels are one of the values defined in `vim.log.levels`:
+---
+--- vim.log.levels.DEBUG
+--- vim.log.levels.ERROR
+--- vim.log.levels.INFO
+--- vim.log.levels.TRACE
+--- vim.log.levels.WARN
+--- vim.log.levels.OFF
+---
+--- </pre>
+
+---@nodoc
+---@class vim.NIL
+
+---@type vim.NIL
+---@nodoc
+vim.NIL = ...
--- Returns true if the code is executing as part of a "fast" event handler,
--- where most of the API is disabled. These are low-level events (e.g.
@@ -76,6 +82,7 @@ function vim.in_fast_event() end
---
--- Note: If numeric keys are present in the table, Nvim ignores the metatable
--- marker and converts the dict to a list/array anyway.
+--- @return table
function vim.empty_dict() end
--- Sends {event} to {channel} via |RPC| and returns immediately. If {channel}
@@ -84,9 +91,8 @@ function vim.empty_dict() end
--- This function also works in a fast callback |lua-loop-callbacks|.
--- @param channel integer
--- @param method string
---- @param args? any[]
--- @param ...? any
-function vim.rpcnotify(channel, method, args, ...) end
+function vim.rpcnotify(channel, method, ...) end
--- Sends a request to {channel} to invoke {method} via |RPC| and blocks until
--- a response is received.
@@ -95,9 +101,8 @@ function vim.rpcnotify(channel, method, args, ...) end
--- special value
--- @param channel integer
--- @param method string
---- @param args? any[]
--- @param ...? any
-function vim.rpcrequest(channel, method, args, ...) end
+function vim.rpcrequest(channel, method, ...) end
--- Compares strings case-insensitively.
--- @param a string
diff --git a/runtime/lua/vim/_meta/builtin_types.lua b/runtime/lua/vim/_meta/builtin_types.lua
index ef0452c649..0bbc3e9bc8 100644
--- a/runtime/lua/vim/_meta/builtin_types.lua
+++ b/runtime/lua/vim/_meta/builtin_types.lua
@@ -81,10 +81,10 @@
--- @class vim.fn.sign_getplaced.dict
--- @field group? string
--- @field id? integer
---- @field lnum? string
+--- @field lnum? string|integer
--- @class vim.fn.sign_getplaced.ret.item
---- @field buf integer
+--- @field bufnr integer
--- @field signs vim.fn.sign[]
--- @class vim.fn.sign_place.dict
@@ -118,7 +118,7 @@
--- @field topfill? integer
--- @field topline? integer
---- @class vim.fn.winsaveview.ret
+--- @class vim.fn.winsaveview.ret: vim.fn.winrestview.dict
--- @field col integer
--- @field coladd integer
--- @field curswant integer
diff --git a/runtime/lua/vim/_meta/json.lua b/runtime/lua/vim/_meta/json.lua
index e010086615..07d89aafc8 100644
--- a/runtime/lua/vim/_meta/json.lua
+++ b/runtime/lua/vim/_meta/json.lua
@@ -5,7 +5,7 @@ vim.json = {}
-- luacheck: no unused args
----@defgroup vim.json
+---@brief
---
--- This module provides encoding and decoding of Lua objects to and
--- from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua
index 42c9a6449e..1ce40f3340 100644
--- a/runtime/lua/vim/_meta/lpeg.lua
+++ b/runtime/lua/vim/_meta/lpeg.lua
@@ -1,11 +1,27 @@
--- @meta
+error('Cannot require a meta file')
--- These types were taken from https://github.com/LuaCATS/lpeg, with types being renamed to include
--- the vim namespace and with some descriptions made less verbose.
+-- These types were taken from https://github.com/LuaCATS/lpeg
+-- (based on revision e6789e28e5b91a4a277a2a03081d708c403a3e34)
+-- with types being renamed to include the vim namespace and with some descriptions made less verbose.
+
+--- @brief <pre>help
+--- LPeg is a pattern-matching library for Lua, based on
+--- Parsing Expression Grammars (https://bford.info/packrat/) (PEGs).
+---
+--- *lua-lpeg*
+--- *vim.lpeg.Pattern*
+--- The LPeg library for parsing expression grammars is included as `vim.lpeg`
+--- (https://www.inf.puc-rio.br/~roberto/lpeg/).
+---
+--- In addition, its regex-like interface is available as |vim.re|
+--- (https://www.inf.puc-rio.br/~roberto/lpeg/re.html).
+---
+--- </pre>
---- *LPeg* is a new pattern-matching library for Lua, based on [Parsing Expression Grammars](https://bford.info/packrat/) (PEGs).
vim.lpeg = {}
+--- @nodoc
--- @class vim.lpeg.Pattern
--- @operator unm: vim.lpeg.Pattern
--- @operator add(vim.lpeg.Pattern): vim.lpeg.Pattern
@@ -32,11 +48,12 @@ local Pattern = {}
--- matches anywhere.
---
--- Example:
+---
--- ```lua
---- local pattern = lpeg.R("az") ^ 1 * -1
---- assert(pattern:match("hello") == 6)
---- assert(lpeg.match(pattern, "hello") == 6)
---- assert(pattern:match("1 hello") == nil)
+--- local pattern = lpeg.R('az') ^ 1 * -1
+--- assert(pattern:match('hello') == 6)
+--- assert(lpeg.match(pattern, 'hello') == 6)
+--- assert(pattern:match('1 hello') == nil)
--- ```
---
--- @param pattern vim.lpeg.Pattern
@@ -55,11 +72,12 @@ function vim.lpeg.match(pattern, subject, init) end
--- we must either write a loop in Lua or write a pattern that matches anywhere.
---
--- Example:
+---
--- ```lua
---- local pattern = lpeg.R("az") ^ 1 * -1
---- assert(pattern:match("hello") == 6)
---- assert(lpeg.match(pattern, "hello") == 6)
---- assert(pattern:match("1 hello") == nil)
+--- local pattern = lpeg.R('az') ^ 1 * -1
+--- assert(pattern:match('hello') == 6)
+--- assert(lpeg.match(pattern, 'hello') == 6)
+--- assert(pattern:match('1 hello') == nil)
--- ```
---
--- @param subject string
@@ -69,7 +87,8 @@ function Pattern:match(subject, init) end
--- Returns the string `"pattern"` if the given value is a pattern, otherwise `nil`.
---
---- @return 'pattern'|nil
+--- @param value vim.lpeg.Pattern|string|integer|boolean|table|function
+--- @return "pattern"|nil
function vim.lpeg.type(value) end
--- Returns a string with the running version of LPeg.
@@ -85,7 +104,7 @@ function vim.lpeg.version() end
--- @param max integer
function vim.lpeg.setmaxstack(max) end
---- Converts the given value into a proper pattern. This following rules are applied:
+--- Converts the given value into a proper pattern. The following rules are applied:
--- * If the argument is a pattern, it is returned unmodified.
--- * If the argument is a string, it is translated to a pattern that matches the string literally.
--- * If the argument is a non-negative number `n`, the result is a pattern that matches exactly `n` characters.
@@ -95,7 +114,7 @@ function vim.lpeg.setmaxstack(max) end
--- * If the argument is a boolean, the result is a pattern that always succeeds or always fails
--- (according to the boolean value), without consuming any input.
--- * If the argument is a table, it is interpreted as a grammar (see Grammars).
---- * If the argument is a function, returns a pattern equivalent to a match-time captureover the empty string.
+--- * If the argument is a function, returns a pattern equivalent to a match-time capture over the empty string.
---
--- @param value vim.lpeg.Pattern|string|integer|boolean|table|function
--- @return vim.lpeg.Pattern
@@ -103,7 +122,7 @@ function vim.lpeg.P(value) end
--- Returns a pattern that matches only if the input string at the current position is preceded by `patt`.
--- Pattern `patt` must match only strings with some fixed length, and it cannot contain captures.
---- Like the and predicate, this pattern never consumes any input, independently of success or failure.
+--- Like the `and` predicate, this pattern never consumes any input, independently of success or failure.
---
--- @param pattern vim.lpeg.Pattern
--- @return vim.lpeg.Pattern
@@ -111,13 +130,14 @@ function vim.lpeg.B(pattern) end
--- Returns a pattern that matches any single character belonging to one of the given ranges.
--- Each `range` is a string `xy` of length 2, representing all characters with code between the codes of
---- `x` and `y` (both inclusive). As an example, the pattern `lpeg.R("09")` matches any digit, and
---- `lpeg.R("az", "AZ")` matches any ASCII letter.
+--- `x` and `y` (both inclusive). As an example, the pattern `lpeg.R('09')` matches any digit, and
+--- `lpeg.R('az', 'AZ')` matches any ASCII letter.
---
--- Example:
+---
--- ```lua
---- local pattern = lpeg.R("az") ^ 1 * -1
---- assert(pattern:match("hello") == 6)
+--- local pattern = lpeg.R('az') ^ 1 * -1
+--- assert(pattern:match('hello') == 6)
--- ```
---
--- @param ... string
@@ -125,9 +145,9 @@ function vim.lpeg.B(pattern) end
function vim.lpeg.R(...) end
--- Returns a pattern that matches any single character that appears in the given string (the `S` stands for Set).
---- As an example, the pattern `lpeg.S("+-*/")` matches any arithmetic operator. Note that, if `s` is a character
+--- As an example, the pattern `lpeg.S('+-*/')` matches any arithmetic operator. Note that, if `s` is a character
--- (that is, a string of length 1), then `lpeg.P(s)` is equivalent to `lpeg.S(s)` which is equivalent to
---- `lpeg.R(s..s)`. Note also that both `lpeg.S("")` and `lpeg.R()` are patterns that always fail.
+--- `lpeg.R(s..s)`. Note also that both `lpeg.S('')` and `lpeg.R()` are patterns that always fail.
---
--- @param string string
--- @return vim.lpeg.Pattern
@@ -137,8 +157,9 @@ function vim.lpeg.S(string) end
--- for a grammar. The created non-terminal refers to the rule indexed by `v` in the enclosing grammar.
---
--- Example:
+---
--- ```lua
---- local b = lpeg.P({"(" * ((1 - lpeg.S "()") + lpeg.V(1)) ^ 0 * ")"})
+--- local b = lpeg.P({'(' * ((1 - lpeg.S '()') + lpeg.V(1)) ^ 0 * ')'})
--- assert(b:match('((string))') == 11)
--- assert(b:match('(') == nil)
--- ```
@@ -147,6 +168,7 @@ function vim.lpeg.S(string) end
--- @return vim.lpeg.Pattern
function vim.lpeg.V(v) end
+--- @nodoc
--- @class vim.lpeg.Locale
--- @field alnum userdata
--- @field alpha userdata
@@ -168,14 +190,15 @@ function vim.lpeg.V(v) end
--- that table.
---
--- Example:
+---
--- ```lua
--- lpeg.locale(lpeg)
---- local space = lpeg.space^0
---- local name = lpeg.C(lpeg.alpha^1) * space
---- local sep = lpeg.S(",;") * space
---- local pair = lpeg.Cg(name * "=" * space * name) * sep^-1
---- local list = lpeg.Cf(lpeg.Ct("") * pair^0, rawset)
---- local t = list:match("a=b, c = hi; next = pi")
+--- local space = lpeg.space ^ 0
+--- local name = lpeg.C(lpeg.alpha ^ 1) * space
+--- local sep = lpeg.S(',;') * space
+--- local pair = lpeg.Cg(name * '=' * space * name) * sep ^ -1
+--- local list = lpeg.Cf(lpeg.Ct('') * pair ^ 0, rawset)
+--- local t = list:match('a=b, c = hi; next = pi')
--- assert(t.a == 'b')
--- assert(t.c == 'hi')
--- assert(t.next == 'pi')
@@ -191,11 +214,12 @@ function vim.lpeg.locale(tab) end
--- The captured value is a string. If `patt` has other captures, their values are returned after this one.
---
--- Example:
+---
--- ```lua
--- local function split (s, sep)
--- sep = lpeg.P(sep)
---- local elem = lpeg.C((1 - sep)^0)
---- local p = elem * (sep * elem)^0
+--- local elem = lpeg.C((1 - sep) ^ 0)
+--- local p = elem * (sep * elem) ^ 0
--- return lpeg.match(p, s)
--- end
--- local a, b, c = split('a,b,c', ',')
@@ -241,12 +265,13 @@ function vim.lpeg.Cc(...) end
--- becomes the captured value.
---
--- Example:
+---
--- ```lua
---- local number = lpeg.R("09") ^ 1 / tonumber
---- local list = number * ("," * number) ^ 0
+--- local number = lpeg.R('09') ^ 1 / tonumber
+--- local list = number * (',' * number) ^ 0
--- local function add(acc, newvalue) return acc + newvalue end
--- local sum = lpeg.Cf(list, add)
---- assert(sum:match("10,30,43") == 83)
+--- assert(sum:match('10,30,43') == 83)
--- ```
---
--- @param patt vim.lpeg.Pattern
@@ -267,10 +292,11 @@ function vim.lpeg.Cg(patt, name) end
--- subject where the match occurs. The captured value is a number.
---
--- Example:
+---
--- ```lua
--- local I = lpeg.Cp()
--- local function anywhere(p) return lpeg.P({I * p * I + 1 * lpeg.V(1)}) end
---- local match_start, match_end = anywhere("world"):match("hello world!")
+--- local match_start, match_end = anywhere('world'):match('hello world!')
--- assert(match_start == 7)
--- assert(match_end == 12)
--- ```
@@ -285,10 +311,11 @@ function vim.lpeg.Cp() end
--- value is the string resulting from all replacements.
---
--- Example:
+---
--- ```lua
--- local function gsub (s, patt, repl)
--- patt = lpeg.P(patt)
---- patt = lpeg.Cs((patt / repl + 1)^0)
+--- patt = lpeg.Cs((patt / repl + 1) ^ 0)
--- return lpeg.match(patt, s)
--- end
--- assert(gsub('Hello, xxx!', 'xxx', 'World') == 'Hello, World!')
@@ -312,9 +339,9 @@ function vim.lpeg.Ct(patt) end
--- and then calls `function`. The given function gets as arguments the entire subject, the current position
--- (after the match of `patt`), plus any capture values produced by `patt`. The first value returned by `function`
--- defines how the match happens. If the call returns a number, the match succeeds and the returned number
---- becomes the new current position. (Assuming a subject sand current position i, the returned number must be
---- in the range [i, len(s) + 1].) If the call returns true, the match succeeds without consuming any input
---- (so, to return true is equivalent to return i). If the call returns false, nil, or no value, the match fails.
+--- becomes the new current position. (Assuming a subject sand current position `i`, the returned number must be
+--- in the range `[i, len(s) + 1]`.) If the call returns `true`, the match succeeds without consuming any input
+--- (so, to return true is equivalent to return `i`). If the call returns `false`, `nil`, or no value, the match fails.
--- Any extra values returned by the function become the values produced by the capture.
---
--- @param patt vim.lpeg.Pattern
diff --git a/runtime/lua/vim/_meta/misc.lua b/runtime/lua/vim/_meta/misc.lua
index 0d70e16314..ab80e18434 100644
--- a/runtime/lua/vim/_meta/misc.lua
+++ b/runtime/lua/vim/_meta/misc.lua
@@ -10,6 +10,7 @@
--- vim.fn[func]({...})
--- ```
---
---- @param func fun()
+--- @param func string
--- @param ... any
+--- @return any
function vim.call(func, ...) end
diff --git a/runtime/lua/vim/_meta/mpack.lua b/runtime/lua/vim/_meta/mpack.lua
index 54e097ad97..3970341b78 100644
--- a/runtime/lua/vim/_meta/mpack.lua
+++ b/runtime/lua/vim/_meta/mpack.lua
@@ -2,14 +2,17 @@
-- luacheck: no unused args
---- @defgroup vim.mpack
+--- @brief
---
--- This module provides encoding and decoding of Lua objects to and
--- from msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
--- Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object.
--- @param str string
+--- @return any
function vim.mpack.decode(str) end
--- Encodes (or "packs") Lua object {obj} as msgpack in a Lua string.
+--- @param obj any
+--- @return string
function vim.mpack.encode(obj) end
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index d2bdab4d28..757720d8fb 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -137,8 +137,9 @@ vim.bo.ai = vim.bo.autoindent
--- `timestamp`
--- If this option has a local value, use this command to switch back to
--- using the global value:
---- ```
---- :set autoread<
+---
+--- ```vim
+--- set autoread<
--- ```
---
---
@@ -191,25 +192,22 @@ vim.go.awa = vim.go.autowriteall
--- See `:hi-normal` if you want to set the background color explicitly.
--- *g:colors_name*
--- When a color scheme is loaded (the "g:colors_name" variable is set)
---- setting 'background' will cause the color scheme to be reloaded. If
+--- changing 'background' will cause the color scheme to be reloaded. If
--- the color scheme adjusts to the value of 'background' this will work.
--- However, if the color scheme sets 'background' itself the effect may
--- be undone. First delete the "g:colors_name" variable when needed.
---
--- Normally this option would be set in the vimrc file. Possibly
--- depending on the terminal name. Example:
+---
+--- ```vim
+--- if $TERM ==# "xterm"
+--- set background=dark
+--- endif
--- ```
---- :if $TERM ==# "xterm"
---- : set background=dark
---- :endif
---- ```
---- When this option is set, the default settings for the highlight groups
+--- When this option is changed, the default settings for the highlight groups
--- will change. To use other settings, place ":highlight" commands AFTER
--- the setting of the 'background' option.
---- This option is also used in the "$VIMRUNTIME/syntax/syntax.vim" file
---- to select the colors for syntax highlighting. After changing this
---- option, you must load syntax.vim again to see the result. This can be
---- done with ":syntax on".
---
--- @type string
vim.o.background = "dark"
@@ -352,14 +350,16 @@ vim.go.bkc = vim.go.backupcopy
--- - Environment variables are expanded `:set_env`.
--- - Careful with '\' characters, type one before a space, type two to
--- get one in the option (see `option-backslash`), for example:
---- ```
---- :set bdir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces
+---
+--- ```vim
+--- set bdir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces
--- ```
---
--- See also 'backup' and 'writebackup' options.
--- If you want to hide your backup files on Unix, consider this value:
---- ```
---- :set backupdir=./.backup,~/.backup,.,/tmp
+---
+--- ```vim
+--- set backupdir=./.backup,~/.backup,.,/tmp
--- ```
--- You must create a ".backup" directory in each directory and in your
--- home directory for this to work properly.
@@ -385,8 +385,9 @@ vim.go.bdir = vim.go.backupdir
--- If you like to keep a lot of backups, you could use a BufWritePre
--- autocommand to change 'backupext' just before writing the file to
--- include a timestamp.
---- ```
---- :au BufWritePre * let &bex = '-' .. strftime("%Y%b%d%X") .. '~'
+---
+--- ```vim
+--- au BufWritePre * let &bex = '-' .. strftime("%Y%b%d%X") .. '~'
--- ```
--- Use 'backupdir' to put the backup in a different directory.
---
@@ -413,7 +414,7 @@ vim.go.bex = vim.go.backupext
--- $HOME you must expand it explicitly, e.g.:
---
--- ```vim
---- :let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*'
+--- let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*'
--- ```
--- Note that the default also makes sure that "crontab -e" works (when a
--- backup would be made by renaming the original file crontab won't see
@@ -714,8 +715,9 @@ vim.go.cdh = vim.go.cdhome
--- If the default value taken from $CDPATH is not what you want, include
--- a modified version of the following command in your vimrc file to
--- override it:
---- ```
---- :let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g')
+---
+--- ```vim
+--- let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g')
--- ```
--- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons.
@@ -731,9 +733,10 @@ vim.go.cd = vim.go.cdpath
--- Only non-printable keys are allowed.
--- The key can be specified as a single character, but it is difficult to
--- type. The preferred way is to use the <> notation. Examples:
---- ```
---- :exe "set cedit=\\<C-Y>"
---- :exe "set cedit=\\<Esc>"
+---
+--- ```vim
+--- exe "set cedit=\\<C-Y>"
+--- exe "set cedit=\\<Esc>"
--- ```
--- `Nvi` also has this option, but it only uses the first character.
--- See `cmdwin`.
@@ -767,7 +770,8 @@ vim.bo.channel = vim.o.channel
--- is done internally by Vim, 'charconvert' is not used for this.
--- Also used for Unicode conversion.
--- Example:
---- ```
+---
+--- ```vim
--- set charconvert=CharConvert()
--- fun CharConvert()
--- system("recode "
@@ -833,7 +837,8 @@ vim.bo.cino = vim.bo.cinoptions
--- Keywords that are interpreted as a C++ scope declaration by `cino-g`.
--- Useful e.g. for working with the Qt framework that defines additional
--- scope declarations "signals", "public slots" and "private slots":
---- ```
+---
+--- ```vim
--- set cinscopedecls+=signals,public\ slots,private\ slots
--- ```
---
@@ -920,10 +925,12 @@ vim.go.cwh = vim.go.cmdwinheight
--- text. Will make screen redrawing slower.
--- The screen column can be an absolute number, or a number preceded with
--- '+' or '-', which is added to or subtracted from 'textwidth'.
---- ```
---- :set cc=+1 " highlight column after 'textwidth'
---- :set cc=+1,+2,+3 " highlight three columns after 'textwidth'
---- :hi ColorColumn ctermbg=lightgrey guibg=lightgrey
+---
+--- ```vim
+---
+--- set cc=+1 " highlight column after 'textwidth'
+--- set cc=+1,+2,+3 " highlight three columns after 'textwidth'
+--- hi ColorColumn ctermbg=lightgrey guibg=lightgrey
--- ```
---
--- When 'textwidth' is zero then the items with '-' and '+' are not used.
@@ -945,8 +952,9 @@ vim.wo.cc = vim.wo.colorcolumn
--- the GUI it is always possible and Vim limits the number of columns to
--- what fits on the screen. You can use this command to get the widest
--- window possible:
---- ```
---- :set columns=9999
+---
+--- ```vim
+--- set columns=9999
--- ```
--- Minimum value is 12, maximum value is 10000.
---
@@ -989,8 +997,9 @@ vim.bo.cms = vim.bo.commentstring
--- kspell use the currently active spell checking `spell`
--- k{dict} scan the file {dict}. Several "k" flags can be given,
--- patterns are valid too. For example:
---- ```
---- :set cpt=k/usr/dict/*,k~/spanish
+---
+--- ```vim
+--- set cpt=k/usr/dict/*,k~/spanish
--- ```
--- s scan the files given with the 'thesaurus' option
--- s{tsr} scan the file {tsr}. Several "s" flags can be given, patterns
@@ -1053,14 +1062,18 @@ vim.bo.cfu = vim.bo.completefunc
--- completion in the preview window. Only works in
--- combination with "menu" or "menuone".
---
---- noinsert Do not insert any text for a match until the user selects
+--- noinsert Do not insert any text for a match until the user selects
--- a match from the menu. Only works in combination with
--- "menu" or "menuone". No effect if "longest" is present.
---
---- noselect Do not select a match in the menu, force the user to
+--- noselect Do not select a match in the menu, force the user to
--- select one from the menu. Only works in combination with
--- "menu" or "menuone".
---
+--- popup Show extra information about the currently selected
+--- completion in a popup window. Only works in combination
+--- with "menu" or "menuone". Overrides "preview".
+---
--- @type string
vim.o.completeopt = "menu,preview"
vim.o.cot = vim.o.completeopt
@@ -1283,9 +1296,6 @@ vim.bo.ci = vim.bo.copyindent
--- when it didn't exist when editing it. This is a
--- protection against a file unexpectedly created by
--- someone else. Vi didn't complain about this.
---- *cpo-p*
---- p Vi compatible Lisp indenting. When not present, a
---- slightly better algorithm is used.
--- *cpo-P*
--- P When included, a ":write" command that appends to a
--- file will set the file name for the current buffer, if
@@ -1419,7 +1429,8 @@ vim.wo.crb = vim.wo.cursorbind
--- slower.
--- If you only want the highlighting in the current window you can use
--- these autocommands:
---- ```
+---
+--- ```vim
--- au WinLeave * set nocursorline nocursorcolumn
--- au WinEnter * set cursorline cursorcolumn
--- ```
@@ -1502,7 +1513,8 @@ vim.go.debug = vim.o.debug
--- ```
--- When using the ":set" command, you need to double the backslashes!
--- To avoid that use `:let` with a single quote string:
---- ```
+---
+--- ```vim
--- let &l:define = '^\s*\ze\k\+\s*=\s*function('
--- ```
---
@@ -1681,11 +1693,12 @@ vim.go.dex = vim.go.diffexpr
--- histogram histogram diff algorithm
---
--- Examples:
---- ```
---- :set diffopt=internal,filler,context:4
---- :set diffopt=
---- :set diffopt=internal,filler,foldcolumn:3
---- :set diffopt-=internal " do NOT use the internal diff parser
+---
+--- ```vim
+--- set diffopt=internal,filler,context:4
+--- set diffopt=
+--- set diffopt=internal,filler,foldcolumn:3
+--- set diffopt-=internal " do NOT use the internal diff parser
--- ```
---
---
@@ -1736,8 +1749,9 @@ vim.go.dg = vim.go.digraph
--- - Environment variables are expanded `:set_env`.
--- - Careful with '\' characters, type one before a space, type two to
--- get one in the option (see `option-backslash`), for example:
---- ```
---- :set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces
+---
+--- ```vim
+--- set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces
--- ```
---
--- Editing the same file twice will result in a warning. Using "/tmp" on
@@ -1924,8 +1938,9 @@ vim.go.efm = vim.go.errorformat
--- When set to "all" or when "all" is one of the items, all autocommand
--- events are ignored, autocommands will not be executed.
--- Otherwise this is a comma-separated list of event names. Example:
---- ```
---- :set ei=WinEnter,WinLeave
+---
+--- ```vim
+--- set ei=WinEnter,WinLeave
--- ```
---
---
@@ -2021,7 +2036,8 @@ vim.bo.fenc = vim.bo.fileencoding
--- "ucs-bom", which requires the BOM to be present). If you prefer
--- another encoding use an BufReadPost autocommand event to test if your
--- preferred encoding is to be used. Example:
---- ```
+---
+--- ```vim
--- au BufReadPost * if search('\S', 'w') == 0 |
--- \ set fenc=iso-2022-jp | endif
--- ```
@@ -2031,8 +2047,9 @@ vim.bo.fenc = vim.bo.fileencoding
--- not used.
--- Note that 'fileencodings' is not used for a new file, the global value
--- of 'fileencoding' is used instead. You can set it with:
---- ```
---- :setglobal fenc=iso-8859-2
+---
+--- ```vim
+--- setglobal fenc=iso-8859-2
--- ```
--- This means that a non-existing file may get a different encoding than
--- an empty file.
@@ -2156,14 +2173,12 @@ vim.go.fic = vim.go.fileignorecase
--- this use the ":filetype on" command. `:filetype`
--- Setting this option to a different value is most useful in a modeline,
--- for a file for which the file type is not automatically recognized.
---- Example, for in an IDL file:
---- ```
+--- Example, for in an IDL file: >c
--- /* vim: set filetype=idl : */
--- ```
--- `FileType` `filetypes`
--- When a dot appears in the value then this separates two filetype
---- names. Example:
---- ```
+--- names. Example: >c
--- /* vim: set filetype=c.doxygen : */
--- ```
--- This will use the "c" filetype first, then the "doxygen" filetype.
@@ -2182,7 +2197,7 @@ vim.bo.ft = vim.bo.filetype
--- Characters to fill the statuslines, vertical separators and special
--- lines in the window.
--- It is a comma-separated list of items. Each item has a name, a colon
---- and the value of that item:
+--- and the value of that item: `E1511`
---
--- item default Used for ~
--- stl ' ' statusline of the current window
@@ -2216,13 +2231,14 @@ vim.bo.ft = vim.bo.filetype
--- default to single-byte alternatives.
---
--- Example:
---- ```
---- :set fillchars=stl:\ ,stlnc:\ ,vert:│,fold:·,diff:-
+---
+--- ```vim
+--- set fillchars=stl:\ ,stlnc:\ ,vert:│,fold:·,diff:-
--- ```
---
--- For the "stl", "stlnc", "foldopen", "foldclose" and "foldsep" items
--- single-byte and multibyte characters are supported. But double-width
---- characters are not supported.
+--- characters are not supported. `E1512`
---
--- The highlighting used for these items:
--- item highlight group ~
@@ -2457,6 +2473,9 @@ vim.go.fdo = vim.go.foldopen
--- It is not allowed to change text or jump to another window while
--- evaluating 'foldtext' `textlock`.
---
+--- When set to an empty string, foldtext is disabled, and the line
+--- is displayed normally with highlighting and no line wrapping.
+---
--- @type string
vim.o.foldtext = "foldtext()"
vim.o.fdt = vim.o.foldtext
@@ -2475,8 +2494,9 @@ vim.wo.fdt = vim.wo.foldtext
--- it yet!
---
--- Example:
---- ```
---- :set formatexpr=mylang#Format()
+---
+--- ```vim
+--- set formatexpr=mylang#Format()
--- ```
--- This will invoke the mylang#Format() function in the
--- autoload/mylang.vim file in 'runtimepath'. `autoload`
@@ -2492,7 +2512,8 @@ vim.wo.fdt = vim.wo.foldtext
---
--- If the expression starts with s: or `<SID>`, then it is replaced with
--- the script ID (`local-function`). Example:
---- ```
+---
+--- ```vim
--- set formatexpr=s:MyFormatExpr()
--- set formatexpr=<SID>SomeFormatExpr()
--- ```
@@ -2591,9 +2612,9 @@ vim.go.fs = vim.go.fsync
--- :s///g subst. one subst. all
--- :s///gg subst. all subst. one
---
---- DEPRECATED: Setting this option may break plugins that are not aware
---- of this option. Also, many users get confused that adding the /g flag
---- has the opposite effect of that it normally does.
+--- NOTE: Setting this option may break plugins that rely on the default
+--- behavior of the 'g' flag. This will also make the 'g' flag have the
+--- opposite effect of that documented in `:s_g`.
---
--- @type boolean
vim.o.gdefault = false
@@ -2618,8 +2639,9 @@ vim.go.gfm = vim.go.grepformat
--- `option-backslash` about including spaces and backslashes.
--- When your "grep" accepts the "-H" argument, use this to make ":grep"
--- also work well with a single file:
---- ```
---- :set grepprg=grep\ -nH
+---
+--- ```vim
+--- set grepprg=grep\ -nH
--- ```
--- Special value: When 'grepprg' is set to "internal" the `:grep` command
--- works like `:vimgrep`, `:lgrep` like `:lvimgrep`, `:grepadd` like
@@ -2641,12 +2663,14 @@ vim.go.gp = vim.go.grepprg
--- terminals. See `tui-cursor-shape`.
---
--- To disable cursor-styling, reset the option:
---- ```
---- :set guicursor=
+---
+--- ```vim
+--- set guicursor=
--- ```
--- To enable mode shapes, "Cursor" highlight, and blinking:
---- ```
---- :set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50
+---
+--- ```vim
+--- set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50
--- \,a:blinkwait700-blinkoff400-blinkon250-Cursor/lCursor
--- \,sm:block-blinkwait175-blinkoff150-blinkon175
--- ```
@@ -2680,8 +2704,9 @@ vim.go.gp = vim.go.grepprg
--- the cursor is shown and blinkoff is the time that the
--- cursor is not shown. Times are in msec. When one of
--- the numbers is zero, there is no blinking. E.g.:
---- ```
---- :set guicursor=n:blinkon0
+---
+--- ```vim
+--- set guicursor=n:blinkon0
--- ```
--- - Default is "blinkon0" for each mode.
--- {group-name}
@@ -2721,9 +2746,10 @@ vim.go.gp = vim.go.grepprg
--- blinking: "a:blinkon0"
---
--- Examples of cursor highlighting:
---- ```
---- :highlight Cursor gui=reverse guifg=NONE guibg=NONE
---- :highlight Cursor gui=NONE guifg=bg guibg=fg
+---
+--- ```vim
+--- highlight Cursor gui=reverse guifg=NONE guibg=NONE
+--- highlight Cursor gui=NONE guifg=bg guibg=fg
--- ```
---
---
@@ -2743,8 +2769,9 @@ vim.go.gcr = vim.go.guicursor
--- precede it with a backslash. Setting an option requires an extra
--- backslash before a space and a backslash. See also
--- `option-backslash`. For example:
---- ```
---- :set guifont=Screen15,\ 7x13,font\\,with\\,commas
+---
+--- ```vim
+--- set guifont=Screen15,\ 7x13,font\\,with\\,commas
--- ```
--- will make Vim try to use the font "Screen15" first, and if it fails it
--- will try to use "7x13" and then "font,with,commas" instead.
@@ -2757,16 +2784,18 @@ vim.go.gcr = vim.go.guicursor
--- will try to find the related bold and italic fonts.
---
--- For Win32 and Mac OS:
---- ```
---- :set guifont=*
+---
+--- ```vim
+--- set guifont=*
--- ```
--- will bring up a font requester, where you can pick the font you want.
---
--- The font name depends on the GUI used.
---
--- For Mac OSX you can use something like this:
---- ```
---- :set guifont=Monaco:h10
+---
+--- ```vim
+--- set guifont=Monaco:h10
--- ```
--- *E236*
--- Note that the fonts must be mono-spaced (all characters have the same
@@ -2793,9 +2822,10 @@ vim.go.gcr = vim.go.guicursor
--- - A '_' can be used in the place of a space, so you don't need to use
--- backslashes to escape the spaces.
--- - Examples:
---- ```
---- :set guifont=courier_new:h12:w5:b:cRUSSIAN
---- :set guifont=Andale_Mono:h7.5:w4.5
+---
+--- ```vim
+--- set guifont=courier_new:h12:w5:b:cRUSSIAN
+--- set guifont=Andale_Mono:h7.5:w4.5
--- ```
---
---
@@ -2949,8 +2979,9 @@ vim.go.gtl = vim.go.guitablabel
--- pages line. When empty Vim will use a default tooltip.
--- This option is otherwise just like 'guitablabel' above.
--- You can include a line break. Simplest method is to use `:let`:
---- ```
---- :let &guitabtooltip = "line one\nline two"
+---
+--- ```vim
+--- let &guitabtooltip = "line one\nline two"
--- ```
---
---
@@ -2994,8 +3025,9 @@ vim.go.hh = vim.go.helpheight
--- another language, but that will only find tags that exist in that
--- language and not in the English help.
--- Example:
---- ```
---- :set helplang=de,it
+---
+--- ```vim
+--- set helplang=de,it
--- ```
--- This will first search German, then Italian and finally English help
--- files.
@@ -3131,8 +3163,9 @@ vim.go.imd = vim.go.imdisable
--- 2 :lmap is off and IM is ON
--- To always reset the option to zero when leaving Insert mode with <Esc>
--- this can be used:
---- ```
---- :inoremap <ESC> <ESC>:set iminsert=0<CR>
+---
+--- ```vim
+--- inoremap <ESC> <ESC>:set iminsert=0<CR>
--- ```
--- This makes :lmap and IM turn off automatically when leaving Insert
--- mode.
@@ -3206,15 +3239,17 @@ vim.go.inc = vim.go.include
--- Expression to be used to transform the string found with the 'include'
--- option to a file name. Mostly useful to change "." to "/" for Java:
---- ```
---- :setlocal includeexpr=substitute(v:fname,'\\.','/','g')
+---
+--- ```vim
+--- setlocal includeexpr=substitute(v:fname,'\\.','/','g')
--- ```
--- The "v:fname" variable will be set to the file name that was detected.
--- Note the double backslash: the `:set` command first halves them, then
--- one remains in the value, where "\." matches a dot literally. For
--- simple character replacements `tr()` avoids the need for escaping:
---- ```
---- :setlocal includeexpr=tr(v:fname,'.','/')
+---
+--- ```vim
+--- setlocal includeexpr=tr(v:fname,'.','/')
--- ```
---
--- Also used for the `gf` command if an unmodified file name can't be
@@ -3223,7 +3258,8 @@ vim.go.inc = vim.go.include
---
--- If the expression starts with s: or `<SID>`, then it is replaced with
--- the script ID (`local-function`). Example:
---- ```
+---
+--- ```vim
--- setlocal includeexpr=s:MyIncludeExpr(v:fname)
--- setlocal includeexpr=<SID>SomeIncludeExpr(v:fname)
--- ```
@@ -3262,7 +3298,8 @@ vim.bo.inex = vim.bo.includeexpr
--- If you don't want to turn 'hlsearch' on, but want to highlight all
--- matches while searching, you can turn on and off 'hlsearch' with
--- autocmd. Example:
---- ```
+---
+--- ```vim
--- augroup vimrc-incsearch-highlight
--- autocmd!
--- autocmd CmdlineEnter /,\? :set hlsearch
@@ -3295,7 +3332,8 @@ vim.go.is = vim.go.incsearch
---
--- If the expression starts with s: or `<SID>`, then it is replaced with
--- the script ID (`local-function`). Example:
---- ```
+---
+--- ```vim
--- set indentexpr=s:MyIndentExpr()
--- set indentexpr=<SID>SomeIndentExpr()
--- ```
@@ -3311,8 +3349,9 @@ vim.go.is = vim.go.incsearch
--- not change the text, jump to another window, etc. Afterwards the
--- cursor position is always restored, thus the cursor may be moved.
--- Normally this option would be set to call a function:
---- ```
---- :set indentexpr=GetMyIndent()
+---
+--- ```vim
+--- set indentexpr=GetMyIndent()
--- ```
--- Error messages will be suppressed, unless the 'debug' option contains
--- "msg".
@@ -3540,9 +3579,10 @@ vim.go.km = vim.go.keymodel
--- a [count] for the "K" command to a section number.
--- See `option-backslash` about including spaces and backslashes.
--- Example:
---- ```
---- :set keywordprg=man\ -s
---- :set keywordprg=:Man
+---
+--- ```vim
+--- set keywordprg=man\ -s
+--- set keywordprg=:Man
--- ```
--- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons.
@@ -3569,12 +3609,14 @@ vim.go.kp = vim.go.keywordprg
--- security reasons.
---
--- Example (for Greek, in UTF-8): *greek*
---- ```
---- :set langmap=ΑA,ΒB,ΨC,ΔD,ΕE,ΦF,ΓG,ΗH,ΙI,ΞJ,ΚK,ΛL,ΜM,ΝN,ΟO,ΠP,QQ,ΡR,ΣS,ΤT,ΘU,ΩV,WW,ΧX,ΥY,ΖZ,αa,βb,ψc,δd,εe,φf,γg,ηh,ιi,ξj,κk,λl,μm,νn,οo,πp,qq,ρr,σs,τt,θu,ωv,ςw,χx,υy,ζz
+---
+--- ```vim
+--- set langmap=ΑA,ΒB,ΨC,ΔD,ΕE,ΦF,ΓG,ΗH,ΙI,ΞJ,ΚK,ΛL,ΜM,ΝN,ΟO,ΠP,QQ,ΡR,ΣS,ΤT,ΘU,ΩV,WW,ΧX,ΥY,ΖZ,αa,βb,ψc,δd,εe,φf,γg,ηh,ιi,ξj,κk,λl,μm,νn,οo,πp,qq,ρr,σs,τt,θu,ωv,ςw,χx,υy,ζz
--- ```
--- Example (exchanges meaning of z and y for commands):
---- ```
---- :set langmap=zy,yz,ZY,YZ
+---
+--- ```vim
+--- set langmap=zy,yz,ZY,YZ
--- ```
---
--- The 'langmap' option is a list of parts, separated with commas. Each
@@ -3607,28 +3649,32 @@ vim.go.lmap = vim.go.langmap
--- Language to use for menu translation. Tells which file is loaded
--- from the "lang" directory in 'runtimepath':
---- ```
+---
+--- ```vim
--- "lang/menu_" .. &langmenu .. ".vim"
--- ```
--- (without the spaces). For example, to always use the Dutch menus, no
--- matter what $LANG is set to:
---- ```
---- :set langmenu=nl_NL.ISO_8859-1
+---
+--- ```vim
+--- set langmenu=nl_NL.ISO_8859-1
--- ```
--- When 'langmenu' is empty, `v:lang` is used.
--- Only normal file name characters can be used, `/\*?[|<>` are illegal.
--- If your $LANG is set to a non-English language but you do want to use
--- the English menus:
---- ```
---- :set langmenu=none
+---
+--- ```vim
+--- set langmenu=none
--- ```
--- This option must be set before loading menus, switching on filetype
--- detection or syntax highlighting. Once the menus are defined setting
--- this option has no effect. But you could do this:
---- ```
---- :source $VIMRUNTIME/delmenu.vim
---- :set langmenu=de_DE.ISO_8859-1
---- :source $VIMRUNTIME/menu.vim
+---
+--- ```vim
+--- source $VIMRUNTIME/delmenu.vim
+--- set langmenu=de_DE.ISO_8859-1
+--- source $VIMRUNTIME/menu.vim
--- ```
--- Warning: This deletes all menus that you defined yourself!
---
@@ -3701,8 +3747,9 @@ vim.wo.lbr = vim.wo.linebreak
--- to use the size for the GUI, put the command in your `gvimrc` file.
--- Vim limits the number of lines to what fits on the screen. You can
--- use this command to get the tallest window possible:
---- ```
---- :set lines=999
+---
+--- ```vim
+--- set lines=999
--- ```
--- Minimum value is 2, maximum value is 1000.
---
@@ -3771,8 +3818,9 @@ vim.go.lw = vim.go.lispwords
--- The cursor is displayed at the start of the space a Tab character
--- occupies, not at the end as usual in Normal mode. To get this cursor
--- position while displaying Tabs with spaces, use:
---- ```
---- :set list lcs=tab:\ \
+---
+--- ```vim
+--- set list lcs=tab:\ \
--- ```
---
--- Note that list mode will also affect formatting (set with 'textwidth'
@@ -3784,7 +3832,7 @@ vim.o.list = false
vim.wo.list = vim.o.list
--- Strings to use in 'list' mode and for the `:list` command. It is a
---- comma-separated list of string settings.
+--- comma-separated list of string settings. *E1511*
---
--- *lcs-eol*
--- eol:c Character to show at the end of each line. When
@@ -3837,8 +3885,9 @@ vim.wo.list = vim.o.list
--- leading spaces are blank. Overrides the "space" and
--- "multispace" settings for leading spaces. You can
--- combine it with "tab:", for example:
---- ```
---- :set listchars+=tab:>-,lead:.
+---
+--- ```vim
+--- set listchars+=tab:>-,lead:.
--- ```
---
--- *lcs-leadmultispace*
@@ -3875,10 +3924,11 @@ vim.wo.list = vim.o.list
--- omitted.
---
--- The characters ':' and ',' should not be used. UTF-8 characters can
---- be used. All characters must be single width.
+--- be used. All characters must be single width. *E1512*
---
--- Each character can be specified as hex:
---- ```
+---
+--- ```vim
--- set listchars=eol:\\x24
--- set listchars=eol:\\u21b5
--- set listchars=eol:\\U000021b5
@@ -3887,10 +3937,11 @@ vim.wo.list = vim.o.list
--- must be exactly 2 for \\x, 4 for \\u and 8 for \\U.
---
--- Examples:
---- ```
---- :set lcs=tab:>-,trail:-
---- :set lcs=tab:>-,eol:<,nbsp:%
---- :set lcs=extends:>,precedes:<
+---
+--- ```vim
+--- set lcs=tab:>-,trail:-
+--- set lcs=tab:>-,eol:<,nbsp:%
+--- set lcs=extends:>,precedes:<
--- ```
--- `hl-NonText` highlighting will be used for "eol", "extends" and
--- "precedes". `hl-Whitespace` for "nbsp", "space", "tab", "multispace",
@@ -3955,8 +4006,9 @@ vim.go.mef = vim.go.makeef
--- This would be mostly useful when you use MS-Windows. If iconv is
--- enabled, setting 'makeencoding' to "char" has the same effect as
--- setting to the system locale encoding. Example:
---- ```
---- :set makeencoding=char " system locale is used
+---
+--- ```vim
+--- set makeencoding=char " system locale is used
--- ```
---
---
@@ -3977,13 +4029,15 @@ vim.go.menc = vim.go.makeencoding
--- Note that a '|' must be escaped twice: once for ":set" and once for
--- the interpretation of a command. When you use a filter called
--- "myfilter" do it like this:
---- ```
---- :set makeprg=gmake\ \\\|\ myfilter
+---
+--- ```vim
+--- set makeprg=gmake\ \\\|\ myfilter
--- ```
--- The placeholder "$*" can be given (even multiple times) to specify
--- where the arguments will be included, for example:
---- ```
---- :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
+---
+--- ```vim
+--- set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
--- ```
--- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons.
@@ -4003,13 +4057,15 @@ vim.go.mp = vim.go.makeprg
--- The characters must be separated by a colon.
--- The pairs must be separated by a comma. Example for including '<' and
--- '>' (for HTML):
---- ```
---- :set mps+=<:>
+---
+--- ```vim
+--- set mps+=<:>
--- ```
--- A more exotic example, to jump between the '=' and ';' in an
--- assignment, useful for languages like C and Java:
---- ```
---- :au FileType c,cpp,java set mps+==:;
+---
+--- ```vim
+--- au FileType c,cpp,java set mps+==:;
--- ```
--- For a more advanced way of using "%", see the matchit.vim plugin in
--- the $VIMRUNTIME/plugin directory. `add-local-help`
@@ -4037,6 +4093,7 @@ vim.go.mat = vim.go.matchtime
--- Increasing this limit above 200 also changes the maximum for Ex
--- command recursion, see `E169`.
--- See also `:function`.
+--- Also used for maximum depth of callback functions.
---
--- @type integer
vim.o.maxfuncdepth = 100
@@ -4116,8 +4173,9 @@ vim.go.mis = vim.go.menuitems
--- The languages for which these numbers are important are Italian and
--- Hungarian. The default works for when you have about 512 Mbyte. If
--- you have 1 Gbyte you could use:
---- ```
---- :set mkspellmem=900000,3000,800
+---
+--- ```vim
+--- set mkspellmem=900000,3000,800
--- ```
--- If you have less than 512 Mbyte `:mkspell` may fail for some
--- languages, no matter what you set 'mkspellmem' to.
@@ -4212,8 +4270,9 @@ vim.go.more = vim.o.more
--- Enables mouse support. For example, to enable the mouse in Normal mode
--- and Visual mode:
---- ```
---- :set mouse=nv
+---
+--- ```vim
+--- set mouse=nv
--- ```
---
--- To temporarily disable mouse support, hold the shift key while using
@@ -4305,19 +4364,20 @@ vim.go.mh = vim.go.mousehide
--- See `mouse-overview`. But mappings are NOT used for modeless selection.
---
--- Example:
---- ```
---- :map <S-LeftMouse> <RightMouse>
---- :map <S-LeftDrag> <RightDrag>
---- :map <S-LeftRelease> <RightRelease>
---- :map <2-S-LeftMouse> <2-RightMouse>
---- :map <2-S-LeftDrag> <2-RightDrag>
---- :map <2-S-LeftRelease> <2-RightRelease>
---- :map <3-S-LeftMouse> <3-RightMouse>
---- :map <3-S-LeftDrag> <3-RightDrag>
---- :map <3-S-LeftRelease> <3-RightRelease>
---- :map <4-S-LeftMouse> <4-RightMouse>
---- :map <4-S-LeftDrag> <4-RightDrag>
---- :map <4-S-LeftRelease> <4-RightRelease>
+---
+--- ```vim
+--- map <S-LeftMouse> <RightMouse>
+--- map <S-LeftDrag> <RightDrag>
+--- map <S-LeftRelease> <RightRelease>
+--- map <2-S-LeftMouse> <2-RightMouse>
+--- map <2-S-LeftDrag> <2-RightDrag>
+--- map <2-S-LeftRelease> <2-RightRelease>
+--- map <3-S-LeftMouse> <3-RightMouse>
+--- map <3-S-LeftDrag> <3-RightDrag>
+--- map <3-S-LeftRelease> <3-RightRelease>
+--- map <4-S-LeftMouse> <4-RightMouse>
+--- map <4-S-LeftDrag> <4-RightDrag>
+--- map <4-S-LeftRelease> <4-RightRelease>
--- ```
---
--- Mouse commands requiring the CTRL modifier can be simulated by typing
@@ -4357,8 +4417,9 @@ vim.go.mousemev = vim.go.mousemoveevent
--- a count of 0.
---
--- Example:
---- ```
---- :set mousescroll=ver:5,hor:2
+---
+--- ```vim
+--- set mousescroll=ver:5,hor:2
--- ```
--- Will make Nvim scroll 5 lines at a time when scrolling vertically, and
--- scroll 2 columns at a time when scrolling horizontally.
@@ -4421,8 +4482,9 @@ vim.go.mousescroll = vim.o.mousescroll
--- pointer.
---
--- Example:
---- ```
---- :set mouseshape=s:udsizing,m:no
+---
+--- ```vim
+--- set mouseshape=s:udsizing,m:no
--- ```
--- will make the mouse turn to a sizing arrow over the status lines and
--- indicate no input when the hit-enter prompt is displayed (since
@@ -4626,28 +4688,33 @@ vim.go.pm = vim.go.patchmode
--- starting with "/", "./" or "../"). The directories in the 'path'
--- option may be relative or absolute.
--- - Use commas to separate directory names:
---- ```
---- :set path=.,/usr/local/include,/usr/include
+---
+--- ```vim
+--- set path=.,/usr/local/include,/usr/include
--- ```
--- - Spaces can also be used to separate directory names. To have a
--- space in a directory name, precede it with an extra backslash, and
--- escape the space:
---- ```
---- :set path=.,/dir/with\\\ space
+---
+--- ```vim
+--- set path=.,/dir/with\\\ space
--- ```
--- - To include a comma in a directory name precede it with an extra
--- backslash:
---- ```
---- :set path=.,/dir/with\\,comma
+---
+--- ```vim
+--- set path=.,/dir/with\\,comma
--- ```
--- - To search relative to the directory of the current file, use:
---- ```
---- :set path=.
+---
+--- ```vim
+--- set path=.
--- ```
--- - To search in the current directory use an empty string between two
--- commas:
---- ```
---- :set path=,,
+---
+--- ```vim
+--- set path=,,
--- ```
--- - A directory name may end in a ':' or '/'.
--- - Environment variables are expanded `:set_env`.
@@ -4656,12 +4723,14 @@ vim.go.pm = vim.go.patchmode
--- - Search upwards and downwards in a directory tree using "*", "**" and
--- ";". See `file-searching` for info and syntax.
--- - Careful with '\' characters, type two to get one in the option:
---- ```
---- :set path=.,c:\\include
+---
+--- ```vim
+--- set path=.,c:\\include
--- ```
--- Or just use '/' instead:
---- ```
---- :set path=.,c:/include
+---
+--- ```vim
+--- set path=.,c:/include
--- ```
--- Don't forget "." or files won't even be found in the same directory as
--- the file!
@@ -4672,18 +4741,21 @@ vim.go.pm = vim.go.patchmode
--- The use of `:set+=` and `:set-=` is preferred when adding or removing
--- directories from the list. This avoids problems when a future version
--- uses another default. To remove the current directory use:
---- ```
---- :set path-=
+---
+--- ```vim
+--- set path-=
--- ```
--- To add the current directory use:
---- ```
---- :set path+=
+---
+--- ```vim
+--- set path+=
--- ```
--- To use an environment variable, you probably need to replace the
--- separator. Here is an example to append $INCL, in which directory
--- names are separated with a semi-colon:
---- ```
---- :let &path = &path .. "," .. substitute($INCL, ';', ',', 'g')
+---
+--- ```vim
+--- let &path = &path .. "," .. substitute($INCL, ';', ',', 'g')
--- ```
--- Replace the ';' with a ':' or whatever separator is used. Note that
--- this doesn't work when $INCL contains a comma or white space.
@@ -4741,9 +4813,11 @@ vim.wo.pvw = vim.wo.previewwindow
--- It is possible to override the level for individual highlights within
--- the popupmenu using `highlight-blend`. For instance, to enable
--- transparency but force the current selected element to be fully opaque:
---- ```
---- :set pumblend=15
---- :hi PmenuSel blend=0
+---
+--- ```vim
+---
+--- set pumblend=15
+--- hi PmenuSel blend=0
--- ```
---
--- UI-dependent. Works best with RGB colors. 'termguicolors'
@@ -5014,8 +5088,9 @@ vim.go.ru = vim.go.ruler
--- The default ruler width is 17 characters. To make the ruler 15
--- characters wide, put "%15(" at the start and "%)" at the end.
--- Example:
---- ```
---- :set rulerformat=%15(%c%V\ %p%%%)
+---
+--- ```vim
+--- set rulerformat=%15(%c%V\ %p%%%)
--- ```
---
---
@@ -5082,8 +5157,9 @@ vim.go.ruf = vim.go.rulerformat
--- wildcards.
--- See `:runtime`.
--- Example:
---- ```
---- :set runtimepath=~/vimruntime,/mygroup/vim,$VIMRUNTIME
+---
+--- ```vim
+--- set runtimepath=~/vimruntime,/mygroup/vim,$VIMRUNTIME
--- ```
--- This will use the directory "~/vimruntime" first (containing your
--- personal Nvim runtime files), then "/mygroup/vim", and finally
@@ -5164,7 +5240,8 @@ vim.go.sj = vim.go.scrolljump
--- when long lines wrap).
--- After using the local value, go back the global value with one of
--- these two:
---- ```
+---
+--- ```vim
--- setlocal scrolloff<
--- setlocal scrolloff=-1
--- ```
@@ -5393,8 +5470,9 @@ vim.go.ssop = vim.go.sessionoptions
--- contents size) = 10253 bytes.
---
--- Example:
---- ```
---- :set shada='50,<1000,s100,:0,n~/nvim/shada
+---
+--- ```vim
+--- set shada='50,<1000,s100,:0,n~/nvim/shada
--- ```
---
--- '50 Marks will be remembered for the last 50 files you
@@ -5445,14 +5523,16 @@ vim.go.sdf = vim.go.shadafile
---
--- If the name of the shell contains a space, you need to enclose it in
--- quotes. Example with quotes:
---- ```
---- :set shell=\"c:\program\ files\unix\sh.exe\"\ -f
+---
+--- ```vim
+--- set shell=\"c:\program\ files\unix\sh.exe\"\ -f
--- ```
--- Note the backslash before each quote (to avoid starting a comment) and
--- each space (to avoid ending the option value), so better use `:let-&`
--- like this:
---- ```
---- :let &shell='"C:\Program Files\unix\sh.exe" -f'
+---
+--- ```vim
+--- let &shell='"C:\Program Files\unix\sh.exe" -f'
--- ```
--- Also note that the "-f" is not inside the quotes, because it is not
--- part of the command name.
@@ -5477,7 +5557,8 @@ vim.go.sdf = vim.go.shadafile
--- unescaping, so to keep yourself sane use `:let-&` like shown above.
--- *shell-powershell*
--- To use PowerShell:
---- ```
+---
+--- ```vim
--- let &shell = executable('pwsh') ? 'pwsh' : 'powershell'
--- let &shellcmdflag = '-NoLogo -ExecutionPolicy RemoteSigned -Command [Console]::InputEncoding=[Console]::OutputEncoding=[System.Text.UTF8Encoding]::new();$PSDefaultParameterValues[''Out-File:Encoding'']=''utf8'';Remove-Alias -Force -ErrorAction SilentlyContinue tee;'
--- let &shellredir = '2>&1 | %%{ "$_" } | Out-File %s; exit $LastExitCode'
@@ -5602,7 +5683,8 @@ vim.go.srr = vim.go.shellredir
--- any file for best results. This might change in the future.
--- 'shellslash' only works when a backslash can be used as a path
--- separator. To test if this is so use:
---- ```
+---
+--- ```vim
--- if exists('+shellslash')
--- ```
--- Also see 'completeslash'.
@@ -5715,9 +5797,10 @@ vim.bo.sw = vim.bo.shiftwidth
--- match", "Pattern not found", "Back at original", etc.
--- C don't give messages while scanning for ins-completion *shm-C*
--- items, for instance "scanning tags"
---- q use "recording" instead of "recording @a" *shm-q*
+--- q do not show "recording @a" when recording a macro *shm-q*
--- F don't give the file info when editing a file, like *shm-F*
---- `:silent` was used for the command
+--- `:silent` was used for the command; note that this also
+--- affects messages from 'autoread' reloading
--- S do not show search count message when searching, e.g. *shm-S*
--- "[1/5]"
---
@@ -5738,9 +5821,10 @@ vim.go.shm = vim.go.shortmess
--- String to put at the start of lines that have been wrapped. Useful
--- values are "> " or "+++ ":
---- ```
---- :let &showbreak = "> "
---- :let &showbreak = '+++ '
+---
+--- ```vim
+--- let &showbreak = "> "
+--- let &showbreak = '+++ '
--- ```
--- Only printable single-cell characters are allowed, excluding <Tab> and
--- comma (in a future version the comma might be used to separate the
@@ -5751,8 +5835,9 @@ vim.go.shm = vim.go.shortmess
--- "n" flag to 'cpoptions'.
--- A window-local value overrules a global value. If the global value is
--- set and you want no value in the current window use NONE:
---- ```
---- :setlocal showbreak=NONE
+---
+--- ```vim
+--- setlocal showbreak=NONE
--- ```
---
---
@@ -5884,7 +5969,8 @@ vim.go.ss = vim.go.sidescroll
--- close to the beginning of the line.
--- After using the local value, go back the global value with one of
--- these two:
---- ```
+---
+--- ```vim
--- setlocal sidescrolloff<
--- setlocal sidescrolloff=-1
--- ```
@@ -5892,9 +5978,11 @@ vim.go.ss = vim.go.sidescroll
--- Example: Try this together with 'sidescroll' and 'listchars' as
--- in the following example to never allow the cursor to move
--- onto the "extends" character:
---- ```
---- :set nowrap sidescroll=1 listchars=extends:>,precedes:<
---- :set sidescrolloff=1
+---
+--- ```vim
+---
+--- set nowrap sidescroll=1 listchars=extends:>,precedes:<
+--- set sidescrolloff=1
--- ```
---
---
@@ -6048,7 +6136,7 @@ vim.bo.spc = vim.bo.spellcapcheck
--- Name of the word list file where words are added for the `zg` and `zw`
--- commands. It must end in ".{encoding}.add". You need to include the
--- path, otherwise the file is placed in the current directory.
---- The path may include characters from 'isfname', space, comma and '@'.
+--- The path may include characters from 'isfname', ' ', ',', '@' and ':'.
--- *E765*
--- It may also be a comma-separated list of names. A count before the
--- `zg` and `zw` commands can be used to access each. This allows using
@@ -6075,7 +6163,8 @@ vim.bo.spf = vim.bo.spellfile
--- A comma-separated list of word list names. When the 'spell' option is
--- on spellchecking will be done for these languages. Example:
---- ```
+---
+--- ```vim
--- set spelllang=en_us,nl,medical
--- ```
--- This means US English, Dutch and medical words are recognized. Words
@@ -6193,8 +6282,9 @@ vim.bo.spo = vim.bo.spelloptions
---
--- Only one of "best", "double" or "fast" may be used. The others may
--- appear several times in any order. Example:
---- ```
---- :set sps=file:~/.config/nvim/sugg,best,expr:MySuggest()
+---
+--- ```vim
+--- set sps=file:~/.config/nvim/sugg,best,expr:MySuggest()
--- ```
---
--- This option cannot be set from a `modeline` or in the `sandbox`, for
@@ -6273,9 +6363,13 @@ vim.go.sol = vim.go.startofline
--- %s sign column for currently drawn line
--- %C fold column for currently drawn line
---
---- NOTE: To draw the sign and fold columns, their items must be included in
---- 'statuscolumn'. Even when they are not included, the status column width
---- will adapt to the 'signcolumn' and 'foldcolumn' width.
+--- The 'statuscolumn' width follows that of the default columns and
+--- adapts to the `'numberwidth'`, `'signcolumn'` and `'foldcolumn'` option
+--- values (regardless of whether the sign and fold items are present).
+--- Additionally, the 'statuscolumn' grows with the size of the evaluated
+--- format string, up to a point (following the maximum size of the default
+--- fold, sign and number columns). Shrinking only happens when the number
+--- of lines in a buffer changes, or the 'statuscolumn' option is set.
---
--- The `v:lnum` variable holds the line number to be drawn.
--- The `v:relnum` variable holds the relative line number to be drawn.
@@ -6283,6 +6377,9 @@ vim.go.sol = vim.go.startofline
--- when drawing the actual buffer line, and positive when
--- drawing the wrapped part of a buffer line.
---
+--- When using `v:relnum`, keep in mind that cursor movement by itself will
+--- not cause the 'statuscolumn' to update unless `'relativenumber'` is set.
+---
--- NOTE: The %@ click execute function item is supported as well but the
--- specified function will be the same for each row in the same column.
--- It cannot be switched out through a dynamic 'statuscolumn' format, the
@@ -6292,21 +6389,21 @@ vim.go.sol = vim.go.startofline
---
--- ```vim
--- " Relative number with bar separator and click handlers:
---- :set statuscolumn=%@SignCb@%s%=%T%@NumCb@%r│%T
+--- set statuscolumn=%@SignCb@%s%=%T%@NumCb@%r│%T
---
--- " Right aligned relative cursor line number:
---- :let &stc='%=%{v:relnum?v:relnum:v:lnum} '
+--- let &stc='%=%{v:relnum?v:relnum:v:lnum} '
---
--- " Line numbers in hexadecimal for non wrapped part of lines:
---- :let &stc='%=%{v:virtnum>0?"":printf("%x",v:lnum)} '
+--- let &stc='%=%{v:virtnum>0?"":printf("%x",v:lnum)} '
---
--- " Human readable line numbers with thousands separator:
---- :let &stc='%{substitute(v:lnum,"\\d\\zs\\ze\\'
+--- let &stc='%{substitute(v:lnum,"\\d\\zs\\ze\\'
--- . '%(\\d\\d\\d\\)\\+$",",","g")}'
---
--- " Both relative and absolute line numbers with different
--- " highlighting for odd and even relative numbers:
---- :let &stc='%#NonText#%{&nu?v:lnum:""}' .
+--- let &stc='%#NonText#%{&nu?v:lnum:""}' .
--- '%=%{&rnu&&(v:lnum%2)?"\ ".v:relnum:""}' .
--- '%#LineNr#%{&rnu&&!(v:lnum%2)?"\ ".v:relnum:""}'
--- ```
@@ -6330,8 +6427,9 @@ vim.wo.stc = vim.wo.statuscolumn
---
--- When the option starts with "%!" then it is used as an expression,
--- evaluated and the result is used as the option value. Example:
---- ```
---- :set statusline=%!MyStatusLine()
+---
+--- ```vim
+--- set statusline=%!MyStatusLine()
--- ```
--- The *g:statusline_winid* variable will be set to the `window-ID` of the
--- window that the status line belongs to.
@@ -6414,7 +6512,8 @@ vim.wo.stc = vim.wo.statuscolumn
--- The expression can contain the "}" character, the end of
--- expression is denoted by "%}".
--- For example:
---- ```
+---
+--- ```vim
--- func! Stl_filename() abort
--- return "%t"
--- endfunc
@@ -6427,16 +6526,17 @@ vim.wo.stc = vim.wo.statuscolumn
--- ) - End of item group. No width fields allowed.
--- T N For 'tabline': start of tab page N label. Use %T or %X to end
--- the label. Clicking this label with left mouse button switches
---- to the specified tab page.
+--- to the specified tab page, while clicking it with middle mouse
+--- button closes the specified tab page.
--- X N For 'tabline': start of close tab N label. Use %X or %T to end
--- the label, e.g.: %3Xclose%X. Use %999X for a "close current
---- tab" label. Clicking this label with left mouse button closes
---- specified tab page.
---- @ N Start of execute function label. Use %X or %T to
---- end the label, e.g.: %10@SwitchBuffer@foo.c%X. Clicking this
---- label runs specified function: in the example when clicking once
---- using left mouse button on "foo.c" "SwitchBuffer(10, 1, 'l',
---- ' ')" expression will be run. Function receives the
+--- tab" label. Clicking this label with left mouse button closes
+--- the specified tab page.
+--- @ N Start of execute function label. Use %X or %T to end the label,
+--- e.g.: %10@SwitchBuffer@foo.c%X. Clicking this label runs the
+--- specified function: in the example when clicking once using left
+--- mouse button on "foo.c", a `SwitchBuffer(10, 1, 'l', ' ')`
+--- expression will be run. The specified function receives the
--- following arguments in order:
--- 1. minwid field value or zero if no N was specified
--- 2. number of mouse clicks to detect multiple clicks
@@ -6483,8 +6583,9 @@ vim.wo.stc = vim.wo.statuscolumn
--- not set) and a minwid is not set for the group, the whole group will
--- become empty. This will make a group like the following disappear
--- completely from the statusline when none of the flags are set.
---- ```
---- :set statusline=...%(\ [%M%R%H]%)...
+---
+--- ```vim
+--- set statusline=...%(\ [%M%R%H]%)...
--- ```
--- Beware that an expression is evaluated each and every time the status
--- line is displayed.
@@ -6517,35 +6618,42 @@ vim.wo.stc = vim.wo.statuscolumn
---
--- Examples:
--- Emulate standard status line with 'ruler' set
---- ```
---- :set statusline=%<%f\ %h%m%r%=%-14.(%l,%c%V%)\ %P
+---
+--- ```vim
+--- set statusline=%<%f\ %h%m%r%=%-14.(%l,%c%V%)\ %P
--- ```
--- Similar, but add ASCII value of char under the cursor (like "ga")
---- ```
---- :set statusline=%<%f%h%m%r%=%b\ 0x%B\ \ %l,%c%V\ %P
+---
+--- ```vim
+--- set statusline=%<%f%h%m%r%=%b\ 0x%B\ \ %l,%c%V\ %P
--- ```
--- Display byte count and byte value, modified flag in red.
---- ```
---- :set statusline=%<%f%=\ [%1*%M%*%n%R%H]\ %-19(%3l,%02c%03V%)%O'%02b'
---- :hi User1 term=inverse,bold cterm=inverse,bold ctermfg=red
+---
+--- ```vim
+--- set statusline=%<%f%=\ [%1*%M%*%n%R%H]\ %-19(%3l,%02c%03V%)%O'%02b'
+--- hi User1 term=inverse,bold cterm=inverse,bold ctermfg=red
--- ```
--- Display a ,GZ flag if a compressed file is loaded
---- ```
---- :set statusline=...%r%{VarExists('b:gzflag','\ [GZ]')}%h...
+---
+--- ```vim
+--- set statusline=...%r%{VarExists('b:gzflag','\ [GZ]')}%h...
--- ```
--- In the `:autocmd`'s:
---- ```
---- :let b:gzflag = 1
+---
+--- ```vim
+--- let b:gzflag = 1
--- ```
--- And:
---- ```
---- :unlet b:gzflag
+---
+--- ```vim
+--- unlet b:gzflag
--- ```
--- And define this function:
---- ```
---- :function VarExists(var, val)
---- : if exists(a:var) | return a:val | else | return '' | endif
---- :endfunction
+---
+--- ```vim
+--- function VarExists(var, val)
+--- if exists(a:var) | return a:val | else | return '' | endif
+--- endfunction
--- ```
---
---
@@ -6576,8 +6684,9 @@ vim.go.su = vim.go.suffixes
--- Comma-separated list of suffixes, which are used when searching for a
--- file for the "gf", "[I", etc. commands. Example:
---- ```
---- :set suffixesadd=.java
+---
+--- ```vim
+--- set suffixesadd=.java
--- ```
---
---
@@ -6662,26 +6771,26 @@ vim.bo.smc = vim.bo.synmaxcol
--- Otherwise this option does not always reflect the current syntax (the
--- b:current_syntax variable does).
--- This option is most useful in a modeline, for a file which syntax is
---- not automatically recognized. Example, in an IDL file:
---- ```
+--- not automatically recognized. Example, in an IDL file: >c
--- /* vim: set syntax=idl : */
--- ```
--- When a dot appears in the value then this separates two filetype
---- names. Example:
---- ```
+--- names. Example: >c
--- /* vim: set syntax=c.doxygen : */
--- ```
--- This will use the "c" syntax first, then the "doxygen" syntax.
--- Note that the second one must be prepared to be loaded as an addition,
--- otherwise it will be skipped. More than one dot may appear.
--- To switch off syntax highlighting for the current file, use:
---- ```
---- :set syntax=OFF
+---
+--- ```vim
+--- set syntax=OFF
--- ```
--- To switch syntax highlighting on according to the current value of the
--- 'filetype' option:
---- ```
---- :set syntax=ON
+---
+--- ```vim
+--- set syntax=ON
--- ```
--- What actually happens when setting the 'syntax' option is that the
--- Syntax autocommand event is triggered with the value as argument.
@@ -6941,6 +7050,10 @@ vim.go.tbidi = vim.go.termbidi
--- attributes instead of "cterm" attributes. `guifg`
--- Requires an ISO-8613-3 compatible terminal.
---
+--- Nvim will automatically attempt to determine if the host terminal
+--- supports 24-bit color and will enable this option if it does
+--- (unless explicitly disabled by the user).
+---
--- @type boolean
vim.o.termguicolors = false
vim.o.tgc = vim.o.termguicolors
@@ -7107,15 +7220,17 @@ vim.go.titleold = vim.o.titleold
--- This option cannot be set in a modeline when 'modelineexpr' is off.
---
--- Example:
---- ```
---- :auto BufEnter * let &titlestring = hostname() .. "/" .. expand("%:p")
---- :set title titlestring=%<%F%=%l/%L-%P titlelen=70
+---
+--- ```vim
+--- auto BufEnter * let &titlestring = hostname() .. "/" .. expand("%:p")
+--- set title titlestring=%<%F%=%l/%L-%P titlelen=70
--- ```
--- The value of 'titlelen' is used to align items in the middle or right
--- of the available space.
--- Some people prefer to have the file name first:
---- ```
---- :set titlestring=%t%(\ %M%)%(\ (%{expand(\"%:~:.:h\")})%)%(\ %a%)
+---
+--- ```vim
+--- set titlestring=%t%(\ %M%)%(\ (%{expand(\"%:~:.:h\")})%)%(\ %a%)
--- ```
--- Note the use of "%{ }" and an expression to get the path of the file,
--- without the file name. The "%( %)" constructs are used to add a
@@ -7200,7 +7315,8 @@ vim.bo.udf = vim.bo.undofile
--- Nevertheless, a single change can already use a large amount of memory.
--- Set to 0 for Vi compatibility: One level of undo and "u" undoes
--- itself:
---- ```
+---
+--- ```vim
--- set ul=0
--- ```
--- But you can also get Vi compatibility by including the 'u' flag in
@@ -7208,7 +7324,8 @@ vim.bo.udf = vim.bo.undofile
--- Also see `undo-two-ways`.
--- Set to -1 for no undo at all. You might want to do this only for the
--- current buffer:
---- ```
+---
+--- ```vim
--- setlocal ul=-1
--- ```
--- This helps when you run out of memory for a single change.
@@ -7280,8 +7397,9 @@ vim.go.ut = vim.go.updatetime
--- For example, when editing assembly language files where statements
--- start in the 9th column and comments in the 41st, it may be useful
--- to use the following:
---- ```
---- :set varsofttabstop=8,32,8
+---
+--- ```vim
+--- set varsofttabstop=8,32,8
--- ```
--- This will set soft tabstops with 8 and 8 + 32 spaces, and 8 more
--- for every column thereafter.
@@ -7298,8 +7416,9 @@ vim.bo.vsts = vim.bo.varsofttabstop
--- A list of the number of spaces that a <Tab> in the file counts for,
--- separated by commas. Each value corresponds to one tab, with the
--- final value applying to all subsequent tabs. For example:
---- ```
---- :set vartabstop=4,20,10,8
+---
+--- ```vim
+--- set vartabstop=4,20,10,8
--- ```
--- This will make the first tab 4 spaces wide, the second 20 spaces,
--- the third 10 spaces, and all following tabs 8 spaces.
@@ -7315,15 +7434,15 @@ vim.bo.vts = vim.bo.vartabstop
--- Sets the verbosity level. Also set by `-V` and `:verbose`.
---
---- Tracing of options in Lua scripts is activated at level 1; Lua scripts
---- are not traced with verbose=0, for performance.
+--- Tracing of assignments to options, mappings, etc. in Lua scripts is
+--- enabled at level 1; Lua scripts are not traced when 'verbose' is 0,
+--- for performance.
---
--- If greater than or equal to a given level, Nvim produces the following
--- messages:
---
--- Level Messages ~
--- ----------------------------------------------------------------------
---- 1 Lua assignments to options, mappings, etc.
--- 2 When a file is ":source"'ed, or `shada` file is read or written.
--- 3 UI info, terminal capabilities.
--- 4 Shell commands.
@@ -7454,8 +7573,9 @@ vim.go.warn = vim.o.warn
--- [ <Left> Insert and Replace
--- ] <Right> Insert and Replace
--- For example:
---- ```
---- :set ww=<,>,[,]
+---
+--- ```vim
+--- set ww=<,>,[,]
--- ```
--- allows wrap only when cursor keys are used.
--- When the movement keys are used in combination with a delete or change
@@ -7484,8 +7604,9 @@ vim.go.ww = vim.go.whichwrap
--- <Esc> can be used, but hitting it twice in a row will still exit
--- command-line as a failsafe measure.
--- Although 'wc' is a number option, you can set it to a special key:
---- ```
---- :set wc=<Tab>
+---
+--- ```vim
+--- set wc=<Tab>
--- ```
---
---
@@ -7500,9 +7621,10 @@ vim.go.wc = vim.go.wildchar
--- keys suitable for this option by looking at `ex-edit-index`. Normally
--- you'll never actually type 'wildcharm', just use it in mappings that
--- automatically invoke completion mode, e.g.:
---- ```
---- :set wcm=<C-Z>
---- :cnoremap ss so $vim/sessions/*.vim<C-Z>
+---
+--- ```vim
+--- set wcm=<C-Z>
+--- cnoremap ss so $vim/sessions/*.vim<C-Z>
--- ```
--- Then after typing :ss you can use CTRL-P & CTRL-N.
---
@@ -7519,8 +7641,9 @@ vim.go.wcm = vim.go.wildcharm
--- The pattern is used like with `:autocmd`, see `autocmd-pattern`.
--- Also see 'suffixes'.
--- Example:
---- ```
---- :set wildignore=*.o,*.obj
+---
+--- ```vim
+--- set wildignore=*.o,*.obj
--- ```
--- The use of `:set+=` and `:set-=` is preferred when adding or removing
--- a pattern from the list. This avoids problems when a future version
@@ -7576,9 +7699,10 @@ vim.go.wic = vim.go.wildignorecase
---
--- If you want <Left> and <Right> to move the cursor instead of selecting
--- a different match, use this:
---- ```
---- :cnoremap <Left> <Space><BS><Left>
---- :cnoremap <Right> <Space><BS><Right>
+---
+--- ```vim
+--- cnoremap <Left> <Space><BS><Left>
+--- cnoremap <Right> <Space><BS><Right>
--- ```
---
--- `hl-WildMenu` highlights the current match.
@@ -7621,24 +7745,29 @@ vim.go.wmnu = vim.go.wildmenu
--- current buffer).
---
--- Examples:
---- ```
---- :set wildmode=full
+---
+--- ```vim
+--- set wildmode=full
--- ```
--- Complete first full match, next match, etc. (the default)
---- ```
---- :set wildmode=longest,full
+---
+--- ```vim
+--- set wildmode=longest,full
--- ```
--- Complete longest common string, then each full match
---- ```
---- :set wildmode=list:full
+---
+--- ```vim
+--- set wildmode=list:full
--- ```
--- List all matches and complete each full match
---- ```
---- :set wildmode=list,full
+---
+--- ```vim
+--- set wildmode=list,full
--- ```
--- List all matches without completing, then each full match
---- ```
---- :set wildmode=longest,list
+---
+--- ```vim
+--- set wildmode=longest,list
--- ```
--- Complete longest common string, then list alternatives.
--- More info here: `cmdline-completion`.
@@ -7776,7 +7905,8 @@ vim.wo.wfw = vim.wo.winfixwidth
--- that ":all" will create only two windows. To avoid "vim -o 1 2 3 4"
--- to create only two windows, set the option after startup is done,
--- using the `VimEnter` event:
---- ```
+---
+--- ```vim
--- au VimEnter * set winheight=999
--- ```
--- Minimum value is 1.
@@ -7806,7 +7936,8 @@ vim.go.wh = vim.go.winheight
--- message area cannot be overridden.
---
--- Example: show a different color for non-current windows:
---- ```
+---
+--- ```vim
--- set winhighlight=Normal:MyNormal,NormalNC:MyNormalNC
--- ```
---
@@ -7876,9 +8007,10 @@ vim.go.wiw = vim.go.winwidth
--- The line will be broken in the middle of a word if necessary. See
--- 'linebreak' to get the break at a word boundary.
--- To make scrolling horizontally a bit more useful, try this:
---- ```
---- :set sidescroll=5
---- :set listchars+=precedes:<,extends:>
+---
+--- ```vim
+--- set sidescroll=5
+--- set listchars+=precedes:<,extends:>
--- ```
--- See 'sidescroll', 'listchars' and `wrap-off`.
--- This option can't be set from a `modeline` when the 'diff' option is
diff --git a/runtime/lua/vim/_meta/re.lua b/runtime/lua/vim/_meta/re.lua
new file mode 100644
index 0000000000..14c94c7824
--- /dev/null
+++ b/runtime/lua/vim/_meta/re.lua
@@ -0,0 +1,54 @@
+--- @meta
+error('Cannot require a meta file')
+
+-- Documentations and Lua types for vim.re (vendored re.lua, lpeg-1.1.0)
+-- https://www.inf.puc-rio.br/~roberto/lpeg/re.html
+--
+-- Copyright © 2007-2023 Lua.org, PUC-Rio.
+-- See 'lpeg.html' for license
+
+--- @brief
+--- The `vim.re` module provides a conventional regex-like syntax for pattern usage
+--- within LPeg |vim.lpeg|.
+---
+--- See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original
+--- documentation including regex syntax and more concrete examples.
+
+--- Compiles the given {string} and returns an equivalent LPeg pattern. The given string may define
+--- either an expression or a grammar. The optional {defs} table provides extra Lua values to be used
+--- by the pattern.
+--- @param string string
+--- @param defs? table
+--- @return vim.lpeg.Pattern
+function vim.re.compile(string, defs) end
+
+--- Searches the given {pattern} in the given {subject}. If it finds a match, returns the index
+--- where this occurrence starts and the index where it ends. Otherwise, returns nil.
+---
+--- An optional numeric argument {init} makes the search starts at that position in the subject
+--- string. As usual in Lua libraries, a negative value counts from the end.
+--- @param subject string
+--- @param pattern vim.lpeg.Pattern|string
+--- @param init? integer
+--- @return integer|nil the index where the occurrence starts, nil if no match
+--- @return integer|nil the index where the occurrence ends, nil if no match
+function vim.re.find(subject, pattern, init) end
+
+--- Does a global substitution, replacing all occurrences of {pattern} in the given {subject} by
+--- {replacement}.
+--- @param subject string
+--- @param pattern vim.lpeg.Pattern|string
+--- @param replacement string
+--- @return string
+function vim.re.gsub(subject, pattern, replacement) end
+
+--- Matches the given {pattern} against the given {subject}, returning all captures.
+--- @param subject string
+--- @param pattern vim.lpeg.Pattern|string
+--- @param init? integer
+--- @return integer|vim.lpeg.Capture|nil
+--- @see vim.lpeg.match()
+function vim.re.match(subject, pattern, init) end
+
+--- Updates the pre-defined character classes to the current locale.
+function vim.re.updatelocale() end
diff --git a/runtime/lua/vim/_meta/regex.lua b/runtime/lua/vim/_meta/regex.lua
index 58aa2be8c2..595ad96319 100644
--- a/runtime/lua/vim/_meta/regex.lua
+++ b/runtime/lua/vim/_meta/regex.lua
@@ -2,8 +2,6 @@
-- luacheck: no unused args
---- @defgroup vim.regex
----
--- @brief Vim regexes can be used directly from Lua. Currently they only allow
--- matching within a single line.
@@ -14,6 +12,7 @@
--- @return vim.regex
function vim.regex(re) end
+--- @nodoc
--- @class vim.regex
local regex = {} -- luacheck: no unused
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 05e5b2b871..ac25547212 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -582,7 +582,7 @@ function vim.fn.bufloaded(buf) end
--- echo bufname("file2") " name of buffer where "file2" matches.
--- <
---
---- @param buf? any
+--- @param buf? integer|string
--- @return string
function vim.fn.bufname(buf) end
@@ -599,7 +599,7 @@ function vim.fn.bufname(buf) end
--- number necessarily exist, because ":bwipeout" may have removed
--- them. Use bufexists() to test for the existence of a buffer.
---
---- @param buf? any
+--- @param buf? integer|string
--- @param create? any
--- @return integer
function vim.fn.bufnr(buf, create) end
@@ -1024,6 +1024,8 @@ function vim.fn.complete_check() end
--- no item is selected when using the <Up> or
--- <Down> keys)
--- inserted Inserted string. [NOT IMPLEMENTED YET]
+--- preview_winid Info floating preview window id.
+--- preview_bufnr Info floating preview buffer id.
---
--- *complete_info_mode*
--- mode values are:
@@ -1707,6 +1709,7 @@ function vim.fn.exepath(expr) end
--- echo exists("*strftime")
--- echo exists("*s:MyFunc")
--- echo exists("*MyFunc")
+--- echo exists("*v:lua.Func")
--- echo exists("bufcount")
--- echo exists(":Make")
--- echo exists("#CursorHold")
@@ -1841,7 +1844,13 @@ function vim.fn.exp(expr) end
---
--- @param string string
--- @param nosuf? boolean
---- @param list? any
+--- @param list? nil|false
+--- @return string
+function vim.fn.expand(string, nosuf, list) end
+
+--- @param string string
+--- @param nosuf boolean
+--- @param list true|number|string|table
--- @return string|string[]
function vim.fn.expand(string, nosuf, list) end
@@ -2300,6 +2309,45 @@ function vim.fn.foldtext() end
--- @return string
function vim.fn.foldtextresult(lnum) end
+--- {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
+--- For each item in {expr1} execute {expr2}. {expr1} is not
+--- modified; its values may be, as with |:lockvar| 1. |E741|
+--- See |map()| and |filter()| to modify {expr1}.
+---
+--- {expr2} must be a |string| or |Funcref|.
+---
+--- If {expr2} is a |string|, inside {expr2} |v:val| has the value
+--- of the current item. For a |Dictionary| |v:key| has the key
+--- of the current item and for a |List| |v:key| has the index of
+--- the current item. For a |Blob| |v:key| has the index of the
+--- current byte. For a |String| |v:key| has the index of the
+--- current character.
+--- Examples: >vim
+--- call foreach(mylist, 'let used[v:val] = v:true')
+--- <This records the items that are in the {expr1} list.
+---
+--- Note that {expr2} is the result of expression and is then used
+--- as a command. Often it is good to use a |literal-string| to
+--- avoid having to double backslashes.
+---
+--- If {expr2} is a |Funcref| it must take two arguments:
+--- 1. the key or the index of the current item.
+--- 2. the value of the current item.
+--- With a lambda you don't get an error if it only accepts one
+--- argument.
+--- If the function returns a value, it is ignored.
+---
+--- Returns {expr1} in all cases.
+--- When an error is encountered while executing {expr2} no
+--- further items in {expr1} are processed.
+--- When {expr2} is a Funcref errors inside a function are ignored,
+--- unless it was defined with the "abort" flag.
+---
+--- @param expr1 any
+--- @param expr2 any
+--- @return any
+function vim.fn.foreach(expr1, expr2) end
+
--- Get the full command name from a short abbreviated command
--- name; see |20.2| for details on command abbreviations.
---
@@ -2514,6 +2562,8 @@ function vim.fn.getbufinfo(buf) end
--- bufnr Buffer number.
--- changed TRUE if the buffer is modified.
--- changedtick Number of changes made to the buffer.
+--- command TRUE if the buffer belongs to the
+--- command-line window |cmdwin|.
--- hidden TRUE if the buffer is hidden.
--- lastused Timestamp in seconds, like
--- |localtime()|, when the buffer was
@@ -2729,7 +2779,7 @@ function vim.fn.getchar() end
--- 32 mouse double click
--- 64 mouse triple click
--- 96 mouse quadruple click (== 32 + 64)
---- 128 command (Macintosh only)
+--- 128 command (Mac) or super
--- Only the modifiers that have not been included in the
--- character itself are obtained. Thus Shift-a results in "A"
--- without a modifier. Returns 0 if no modifiers are used.
@@ -2887,6 +2937,7 @@ function vim.fn.getcmdwintype() end
--- help help subjects
--- highlight highlight groups
--- history |:history| suboptions
+--- keymap keyboard mappings
--- locale locale names (as output of locale -a)
--- mapclear buffer argument
--- mapping mapping name
@@ -3134,8 +3185,13 @@ function vim.fn.getjumplist(winnr, tabnr) end
--- <To get lines from another buffer see |getbufline()| and
--- |getbufoneline()|
---
+--- @param lnum integer|string
+--- @param end_? nil|false
+--- @return string
+function vim.fn.getline(lnum, end_) end
+
--- @param lnum integer
---- @param end_? any
+--- @param end_ true|number|string|table
--- @return string|string[]
function vim.fn.getline(lnum, end_) end
@@ -3433,7 +3489,12 @@ function vim.fn.getqflist(what) end
--- If {regname} is not specified, |v:register| is used.
---
--- @param regname? string
---- @param list? any
+--- @param list? nil|false
+--- @return string
+function vim.fn.getreg(regname, list) end
+
+--- @param regname string
+--- @param list true|number|string|table
--- @return string|string[]
function vim.fn.getreg(regname, list) end
@@ -3464,6 +3525,62 @@ function vim.fn.getreg(regname, list) end
--- @return table
function vim.fn.getreginfo(regname) end
+--- Returns the list of strings from {pos1} to {pos2} from a
+--- buffer.
+---
+--- {pos1} and {pos2} must both be |List|s with four numbers.
+--- See |getpos()| for the format of the list. It's possible
+--- to specify positions from a different buffer, but please
+--- note the limitations at |getregion-notes|.
+---
+--- The optional argument {opts} is a Dict and supports the
+--- following items:
+---
+--- type Specify the region's selection type
+--- (default: "v"):
+--- "v" for |charwise| mode
+--- "V" for |linewise| mode
+--- "<CTRL-V>" for |blockwise-visual| mode
+---
+--- exclusive If |TRUE|, use exclusive selection
+--- for the end position
+--- (default: follow 'selection')
+---
+--- You can get the last selection type by |visualmode()|.
+--- If Visual mode is active, use |mode()| to get the Visual mode
+--- (e.g., in a |:vmap|).
+--- This function is useful to get text starting and ending in
+--- different columns, such as a |charwise-visual| selection.
+---
+--- *getregion-notes*
+--- Note that:
+--- - Order of {pos1} and {pos2} doesn't matter, it will always
+--- return content from the upper left position to the lower
+--- right position.
+--- - If 'virtualedit' is enabled and the region is past the end
+--- of the lines, resulting lines are padded with spaces.
+--- - If the region is blockwise and it starts or ends in the
+--- middle of a multi-cell character, it is not included but
+--- its selected part is substituted with spaces.
+--- - If {pos1} and {pos2} are not in the same buffer, an empty
+--- list is returned.
+--- - {pos1} and {pos2} must belong to a |bufloaded()| buffer.
+--- - It is evaluated in current window context, which makes a
+--- difference if the buffer is displayed in a window with
+--- different 'virtualedit' or 'list' values.
+---
+--- Examples: >
+--- :xnoremap <CR>
+--- \ <Cmd>echom getregion(
+--- \ getpos('v'), getpos('.'), #{ type: mode() })<CR>
+--- <
+---
+--- @param pos1 table
+--- @param pos2 table
+--- @param opts? table
+--- @return string[]
+function vim.fn.getregion(pos1, pos2, opts) end
+
--- The result is a String, which is type of register {regname}.
--- The value will be one of:
--- "v" for |charwise| text
@@ -4135,7 +4252,7 @@ function vim.fn.id(expr) end
--- |getline()|.
--- When {lnum} is invalid -1 is returned.
---
---- @param lnum integer
+--- @param lnum integer|string
--- @return integer
function vim.fn.indent(lnum) end
@@ -4678,8 +4795,7 @@ function vim.fn.join(list, sep) end
--- Vim value. In the following cases it will output
--- |msgpack-special-dict|:
--- 1. Dictionary contains duplicate key.
---- 2. Dictionary contains empty key.
---- 3. String contains NUL byte. Two special dictionaries: for
+--- 2. String contains NUL byte. Two special dictionaries: for
--- dictionary and for string will be emitted in case string
--- with NUL byte was a dictionary key.
---
@@ -5065,7 +5181,14 @@ function vim.fn.map(expr1, expr2) end
--- @param name string
--- @param mode? string
--- @param abbr? boolean
---- @param dict? boolean
+--- @param dict? false
+--- @return string
+function vim.fn.maparg(name, mode, abbr, dict) end
+
+--- @param name string
+--- @param mode string
+--- @param abbr boolean
+--- @param dict true
--- @return string|table<string,any>
function vim.fn.maparg(name, mode, abbr, dict) end
@@ -5150,6 +5273,12 @@ function vim.fn.maplist() end
--- @return any
function vim.fn.mapnew(expr1, expr2) end
+--- @param mode string
+--- @param abbr? any
+--- @param dict? any
+--- @return any
+function vim.fn.mapset(mode, abbr, dict) end
+
--- Restore a mapping from a dictionary, possibly returned by
--- |maparg()| or |maplist()|. A buffer mapping, when dict.buffer
--- is true, is set on the current buffer; it is up to the caller
@@ -5185,11 +5314,9 @@ function vim.fn.mapnew(expr1, expr2) end
--- call mapset(d)
--- endfor
---
---- @param mode string
---- @param abbr? any
---- @param dict? any
+--- @param dict any
--- @return any
-function vim.fn.mapset(mode, abbr, dict) end
+function vim.fn.mapset(dict) end
--- When {expr} is a |List| then this returns the index of the
--- first item where {pat} matches. Each item is used as a
@@ -5243,6 +5370,7 @@ function vim.fn.mapset(mode, abbr, dict) end
--- Note that when {count} is added the way {start} works changes,
--- see above.
---
+--- *match-pattern*
--- See |pattern| for the patterns that are accepted.
--- The 'ignorecase' option is used to set the ignore-caseness of
--- the pattern. 'smartcase' is NOT used. The matching is always
@@ -5383,6 +5511,57 @@ function vim.fn.matchaddpos(group, pos, priority, id, dict) end
--- @return any
function vim.fn.matcharg(nr) end
+--- Returns the |List| of matches in lines from {lnum} to {end} in
+--- buffer {buf} where {pat} matches.
+---
+--- {lnum} and {end} can either be a line number or the string "$"
+--- to refer to the last line in {buf}.
+---
+--- The {dict} argument supports following items:
+--- submatches include submatch information (|/\(|)
+---
+--- For each match, a |Dict| with the following items is returned:
+--- byteidx starting byte index of the match
+--- lnum line number where there is a match
+--- text matched string
+--- Note that there can be multiple matches in a single line.
+---
+--- This function works only for loaded buffers. First call
+--- |bufload()| if needed.
+---
+--- See |match-pattern| for information about the effect of some
+--- option settings on the pattern.
+---
+--- When {buf} is not a valid buffer, the buffer is not loaded or
+--- {lnum} or {end} is not valid then an error is given and an
+--- empty |List| is returned.
+---
+--- Examples: >vim
+--- " Assuming line 3 in buffer 5 contains "a"
+--- :echo matchbufline(5, '\<\k\+\>', 3, 3)
+--- [{'lnum': 3, 'byteidx': 0, 'text': 'a'}]
+--- " Assuming line 4 in buffer 10 contains "tik tok"
+--- :echo matchbufline(10, '\<\k\+\>', 1, 4)
+--- [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}]
+--- <
+--- If {submatch} is present and is v:true, then submatches like
+--- "\1", "\2", etc. are also returned. Example: >vim
+--- " Assuming line 2 in buffer 2 contains "acd"
+--- :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2
+--- \ {'submatches': v:true})
+--- [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
+--- <The "submatches" List always contains 9 items. If a submatch
+--- is not found, then an empty string is returned for that
+--- submatch.
+---
+--- @param buf string|integer
+--- @param pat string
+--- @param lnum string|integer
+--- @param end_ string|integer
+--- @param dict? table
+--- @return any
+function vim.fn.matchbufline(buf, pat, lnum, end_, dict) end
+
--- Deletes a match with ID {id} previously defined by |matchadd()|
--- or one of the |:match| commands. Returns 0 if successful,
--- otherwise -1. See example for |matchadd()|. All matches can
@@ -5552,6 +5731,44 @@ function vim.fn.matchlist(expr, pat, start, count) end
--- @return any
function vim.fn.matchstr(expr, pat, start, count) end
+--- Returns the |List| of matches in {list} where {pat} matches.
+--- {list} is a |List| of strings. {pat} is matched against each
+--- string in {list}.
+---
+--- The {dict} argument supports following items:
+--- submatches include submatch information (|/\(|)
+---
+--- For each match, a |Dict| with the following items is returned:
+--- byteidx starting byte index of the match.
+--- idx index in {list} of the match.
+--- text matched string
+--- submatches a List of submatches. Present only if
+--- "submatches" is set to v:true in {dict}.
+---
+--- See |match-pattern| for information about the effect of some
+--- option settings on the pattern.
+---
+--- Example: >vim
+--- :echo matchstrlist(['tik tok'], '\<\k\+\>')
+--- [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}]
+--- :echo matchstrlist(['a', 'b'], '\<\k\+\>')
+--- [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}]
+--- <
+--- If "submatches" is present and is v:true, then submatches like
+--- "\1", "\2", etc. are also returned. Example: >vim
+--- :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)',
+--- \ #{submatches: v:true})
+--- [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}]
+--- <The "submatches" List always contains 9 items. If a submatch
+--- is not found, then an empty string is returned for that
+--- submatch.
+---
+--- @param list string[]
+--- @param pat string
+--- @param dict? table
+--- @return any
+function vim.fn.matchstrlist(list, pat, dict) end
+
--- Same as |matchstr()|, but return the matched string, the start
--- position and the end position of the match. Example: >vim
--- echo matchstrpos("testing", "ing")
@@ -5583,7 +5800,7 @@ function vim.fn.matchstrpos(expr, pat, start, count) end
--- it returns the maximum of all values in the Dictionary.
--- If {expr} is neither a List nor a Dictionary, or one of the
--- items in {expr} cannot be used as a Number this results in
---- an error. An empty |List| or |Dictionary| results in zero.
+--- an error. An empty |List| or |Dictionary| results in zero.
---
--- @param expr any
--- @return any
@@ -5828,8 +6045,9 @@ function vim.fn.mkdir(name, flags, prot) end
--- the leading character(s).
--- Also see |visualmode()|.
---
+--- @param expr? any
--- @return any
-function vim.fn.mode() end
+function vim.fn.mode(expr) end
--- Convert a list of Vimscript objects to msgpack. Returned value is a
--- |readfile()|-style list. When {type} contains "B", a |Blob| is
@@ -5922,7 +6140,6 @@ function vim.fn.msgpackdump(list, type) end
--- are binary strings).
--- 2. String with NUL byte inside.
--- 3. Duplicate key.
---- 4. Empty key.
--- ext |List| with two values: first is a signed integer
--- representing extension type. Second is
--- |readfile()|-style list of strings.
@@ -6158,9 +6375,9 @@ function vim.fn.prevnonblank(lnum) end
--- <This limits the length of the text used from "line" to
--- "width" bytes.
---
---- If the argument to be formatted is specified using a posional
---- argument specifier, and a '*' is used to indicate that a
---- number argument is to be used to specify the width or
+--- If the argument to be formatted is specified using a
+--- positional argument specifier, and a '*' is used to indicate
+--- that a number argument is to be used to specify the width or
--- precision, the argument(s) to be used must also be specified
--- using a {n$} positional argument specifier. See |printf-$|.
---
@@ -7969,7 +8186,7 @@ function vim.fn.setqflist(list, action, what) end
---
--- @param regname string
--- @param value any
---- @param options? table
+--- @param options? string
--- @return any
function vim.fn.setreg(regname, value, options) end
@@ -9311,7 +9528,12 @@ function vim.fn.strwidth(string) end
--- A line break is included as a newline character.
---
--- @param nr integer
---- @param list? integer
+--- @param list? nil
+--- @return string
+function vim.fn.submatch(nr, list) end
+
+--- @param nr integer
+--- @param list integer
--- @return string|string[]
function vim.fn.submatch(nr, list) end
@@ -9527,7 +9749,7 @@ function vim.fn.synIDtrans(synID) end
---
--- @param lnum integer
--- @param col integer
---- @return {[1]: integer, [2]: string, [3]: integer}[]
+--- @return {[1]: integer, [2]: string, [3]: integer}
function vim.fn.synconcealed(lnum, col) end
--- Return a |List|, which is the stack of syntax items at the
diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua
new file mode 100644
index 0000000000..ee6d8ddf35
--- /dev/null
+++ b/runtime/lua/vim/_meta/vvars.lua
@@ -0,0 +1,779 @@
+--- @meta _
+-- THIS FILE IS GENERATED
+-- DO NOT EDIT
+error('Cannot require a meta file')
+
+--- @class vim.v
+vim.v = ...
+
+--- The command line arguments Vim was invoked with. This is a
+--- list of strings. The first item is the Vim command.
+--- See `v:progpath` for the command with full path.
+--- @type string[]
+vim.v.argv = ...
+
+--- Argument for evaluating 'formatexpr' and used for the typed
+--- character when using <expr> in an abbreviation `:map-<expr>`.
+--- It is also used by the `InsertCharPre` and `InsertEnter` events.
+--- @type any
+vim.v.char = ...
+
+--- The name of the character encoding of a file to be converted.
+--- Only valid while evaluating the 'charconvert' option.
+--- @type string
+vim.v.charconvert_from = ...
+
+--- The name of the character encoding of a file after conversion.
+--- Only valid while evaluating the 'charconvert' option.
+--- @type string
+vim.v.charconvert_to = ...
+
+--- The extra arguments ("++p", "++enc=", "++ff=") given to a file
+--- read/write command. This is set before an autocommand event
+--- for a file read/write command is triggered. There is a
+--- leading space to make it possible to append this variable
+--- directly after the read/write command. Note: "+cmd" isn't
+--- included here, because it will be executed anyway.
+--- @type string
+vim.v.cmdarg = ...
+
+--- Set like v:cmdarg for a file read/write command. When a "!"
+--- was used the value is 1, otherwise it is 0. Note that this
+--- can only be used in autocommands. For user commands `<bang>`
+--- can be used.
+--- @type integer
+vim.v.cmdbang = ...
+
+--- The current locale setting for collation order of the runtime
+--- environment. This allows Vim scripts to be aware of the
+--- current locale encoding. Technical: it's the value of
+--- LC_COLLATE. When not using a locale the value is "C".
+--- This variable can not be set directly, use the `:language`
+--- command.
+--- See `multi-lang`.
+--- @type string
+vim.v.collate = ...
+
+--- Dictionary containing the most recent `complete-items` after
+--- `CompleteDone`. Empty if the completion failed, or after
+--- leaving and re-entering insert mode.
+--- Note: Plugins can modify the value to emulate the builtin
+--- `CompleteDone` event behavior.
+--- @type any
+vim.v.completed_item = ...
+
+--- The count given for the last Normal mode command. Can be used
+--- to get the count before a mapping. Read-only. Example:
+---
+--- ```vim
+--- :map _x :<C-U>echo "the count is " .. v:count<CR>
+--- ```
+---
+--- Note: The <C-U> is required to remove the line range that you
+--- get when typing ':' after a count.
+--- When there are two counts, as in "3d2w", they are multiplied,
+--- just like what happens in the command, "d6w" for the example.
+--- Also used for evaluating the 'formatexpr' option.
+--- @type integer
+vim.v.count = ...
+
+--- Just like "v:count", but defaults to one when no count is
+--- used.
+--- @type integer
+vim.v.count1 = ...
+
+--- The current locale setting for characters of the runtime
+--- environment. This allows Vim scripts to be aware of the
+--- current locale encoding. Technical: it's the value of
+--- LC_CTYPE. When not using a locale the value is "C".
+--- This variable can not be set directly, use the `:language`
+--- command.
+--- See `multi-lang`.
+--- @type any
+vim.v.ctype = ...
+
+--- Normally zero. When a deadly signal is caught it's set to
+--- one. When multiple signals are caught the number increases.
+--- Can be used in an autocommand to check if Vim didn't
+--- terminate normally.
+--- Example:
+---
+--- ```vim
+--- :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
+--- ```
+---
+--- Note: if another deadly signal is caught when v:dying is one,
+--- VimLeave autocommands will not be executed.
+--- @type integer
+vim.v.dying = ...
+
+--- Number of screen cells that can be used for an `:echo` message
+--- in the last screen line before causing the `hit-enter-prompt`.
+--- Depends on 'showcmd', 'ruler' and 'columns'. You need to
+--- check 'cmdheight' for whether there are full-width lines
+--- available above the last line.
+--- @type integer
+vim.v.echospace = ...
+
+--- Last given error message.
+--- Modifiable (can be set).
+--- Example:
+---
+--- ```vim
+--- let v:errmsg = ""
+--- silent! next
+--- if v:errmsg != ""
+--- " ... handle error
+--- ```
+--- @type string
+vim.v.errmsg = ...
+
+--- Errors found by assert functions, such as `assert_true()`.
+--- This is a list of strings.
+--- The assert functions append an item when an assert fails.
+--- The return value indicates this: a one is returned if an item
+--- was added to v:errors, otherwise zero is returned.
+--- To remove old results make it empty:
+---
+--- ```vim
+--- let v:errors = []
+--- ```
+---
+--- If v:errors is set to anything but a list it is made an empty
+--- list by the assert function.
+--- @type string[]
+vim.v.errors = ...
+
+--- Dictionary of event data for the current `autocommand`. Valid
+--- only during the event lifetime; storing or passing v:event is
+--- invalid! Copy it instead:
+---
+--- ```vim
+--- au TextYankPost * let g:foo = deepcopy(v:event)
+--- ```
+---
+--- Keys vary by event; see the documentation for the specific
+--- event, e.g. `DirChanged` or `TextYankPost`.
+--- KEY DESCRIPTION ~
+--- abort Whether the event triggered during
+--- an aborting condition (e.g. `c_Esc` or
+--- `c_CTRL-C` for `CmdlineLeave`).
+--- chan `channel-id`
+--- cmdlevel Level of cmdline.
+--- cmdtype Type of cmdline, `cmdline-char`.
+--- cwd Current working directory.
+--- inclusive Motion is `inclusive`, else exclusive.
+--- scope Event-specific scope name.
+--- operator Current `operator`. Also set for Ex
+--- commands (unlike `v:operator`). For
+--- example if `TextYankPost` is triggered
+--- by the `:yank` Ex command then
+--- `v:event.operator` is "y".
+--- regcontents Text stored in the register as a
+--- `readfile()`-style list of lines.
+--- regname Requested register (e.g "x" for "xyy)
+--- or the empty string for an unnamed
+--- operation.
+--- regtype Type of register as returned by
+--- `getregtype()`.
+--- visual Selection is visual (as opposed to,
+--- e.g., via motion).
+--- completed_item Current selected complete item on
+--- `CompleteChanged`, Is `{}` when no complete
+--- item selected.
+--- height Height of popup menu on `CompleteChanged`
+--- width Width of popup menu on `CompleteChanged`
+--- row Row count of popup menu on `CompleteChanged`,
+--- relative to screen.
+--- col Col count of popup menu on `CompleteChanged`,
+--- relative to screen.
+--- size Total number of completion items on
+--- `CompleteChanged`.
+--- scrollbar Is `v:true` if popup menu have scrollbar, or
+--- `v:false` if not.
+--- changed_window Is `v:true` if the event fired while
+--- changing window (or tab) on `DirChanged`.
+--- status Job status or exit code, -1 means "unknown". `TermClose`
+--- @type any
+vim.v.event = ...
+
+--- The value of the exception most recently caught and not
+--- finished. See also `v:throwpoint` and `throw-variables`.
+--- Example:
+---
+--- ```vim
+--- try
+--- throw "oops"
+--- catch /.*/
+--- echo "caught " .. v:exception
+--- endtry
+--- ```
+---
+--- Output: "caught oops".
+--- @type string
+vim.v.exception = ...
+
+--- Exit code, or `v:null` before invoking the `VimLeavePre`
+--- and `VimLeave` autocmds. See `:q`, `:x` and `:cquit`.
+--- Example:
+---
+--- ```vim
+--- :au VimLeave * echo "Exit value is " .. v:exiting
+--- ```
+--- @type any
+vim.v.exiting = ...
+
+--- Special value used to put "false" in JSON and msgpack. See
+--- `json_encode()`. This value is converted to "v:false" when used
+--- as a String (e.g. in `expr5` with string concatenation
+--- operator) and to zero when used as a Number (e.g. in `expr5`
+--- or `expr7` when used with numeric operators). Read-only.
+--- @type boolean
+vim.v['false'] = ...
+
+--- What should happen after a `FileChangedShell` event was
+--- triggered. Can be used in an autocommand to tell Vim what to
+--- do with the affected buffer:
+--- reload Reload the buffer (does not work if
+--- the file was deleted).
+--- edit Reload the buffer and detect the
+--- values for options such as
+--- 'fileformat', 'fileencoding', 'binary'
+--- (does not work if the file was
+--- deleted).
+--- ask Ask the user what to do, as if there
+--- was no autocommand. Except that when
+--- only the timestamp changed nothing
+--- will happen.
+--- <empty> Nothing, the autocommand should do
+--- everything that needs to be done.
+--- The default is empty. If another (invalid) value is used then
+--- Vim behaves like it is empty, there is no warning message.
+--- @type string
+vim.v.fcs_choice = ...
+
+--- The reason why the `FileChangedShell` event was triggered.
+--- Can be used in an autocommand to decide what to do and/or what
+--- to set v:fcs_choice to. Possible values:
+--- deleted file no longer exists
+--- conflict file contents, mode or timestamp was
+--- changed and buffer is modified
+--- changed file contents has changed
+--- mode mode of file changed
+--- time only file timestamp changed
+--- @type string
+vim.v.fcs_reason = ...
+
+--- When evaluating 'includeexpr': the file name that was
+--- detected. Empty otherwise.
+--- @type string
+vim.v.fname = ...
+
+--- The name of the diff (patch) file. Only valid while
+--- evaluating 'patchexpr'.
+--- @type string
+vim.v.fname_diff = ...
+
+--- The name of the input file. Valid while evaluating:
+--- option used for ~
+--- 'charconvert' file to be converted
+--- 'diffexpr' original file
+--- 'patchexpr' original file
+--- And set to the swap file name for `SwapExists`.
+--- @type string
+vim.v.fname_in = ...
+
+--- The name of the new version of the file. Only valid while
+--- evaluating 'diffexpr'.
+--- @type string
+vim.v.fname_new = ...
+
+--- The name of the output file. Only valid while
+--- evaluating:
+--- option used for ~
+--- 'charconvert' resulting converted file [1]
+--- 'diffexpr' output of diff
+--- 'patchexpr' resulting patched file
+--- [1] When doing conversion for a write command (e.g., ":w
+--- file") it will be equal to v:fname_in. When doing conversion
+--- for a read command (e.g., ":e file") it will be a temporary
+--- file and different from v:fname_in.
+--- @type string
+vim.v.fname_out = ...
+
+--- Used for 'foldtext': dashes representing foldlevel of a closed
+--- fold.
+--- Read-only in the `sandbox`. `fold-foldtext`
+--- @type string
+vim.v.folddashes = ...
+
+--- Used for 'foldtext': last line of closed fold.
+--- Read-only in the `sandbox`. `fold-foldtext`
+--- @type integer
+vim.v.foldend = ...
+
+--- Used for 'foldtext': foldlevel of closed fold.
+--- Read-only in the `sandbox`. `fold-foldtext`
+--- @type integer
+vim.v.foldlevel = ...
+
+--- Used for 'foldtext': first line of closed fold.
+--- Read-only in the `sandbox`. `fold-foldtext`
+--- @type integer
+vim.v.foldstart = ...
+
+--- Variable that indicates whether search highlighting is on.
+--- Setting it makes sense only if 'hlsearch' is enabled. Setting
+--- this variable to zero acts like the `:nohlsearch` command,
+--- setting it to one acts like
+---
+--- ```vim
+--- let &hlsearch = &hlsearch
+--- ```
+---
+--- Note that the value is restored when returning from a
+--- function. `function-search-undo`.
+--- @type integer
+vim.v.hlsearch = ...
+
+--- Used for the `InsertEnter` and `InsertChange` autocommand
+--- events. Values:
+--- i Insert mode
+--- r Replace mode
+--- v Virtual Replace mode
+--- @type string
+vim.v.insertmode = ...
+
+--- Key of the current item of a `Dictionary`. Only valid while
+--- evaluating the expression used with `map()` and `filter()`.
+--- Read-only.
+--- @type string
+vim.v.key = ...
+
+--- The current locale setting for messages of the runtime
+--- environment. This allows Vim scripts to be aware of the
+--- current language. Technical: it's the value of LC_MESSAGES.
+--- The value is system dependent.
+--- This variable can not be set directly, use the `:language`
+--- command.
+--- It can be different from `v:ctype` when messages are desired
+--- in a different language than what is used for character
+--- encoding. See `multi-lang`.
+--- @type string
+vim.v.lang = ...
+
+--- The current locale setting for time messages of the runtime
+--- environment. This allows Vim scripts to be aware of the
+--- current language. Technical: it's the value of LC_TIME.
+--- This variable can not be set directly, use the `:language`
+--- command. See `multi-lang`.
+--- @type string
+vim.v.lc_time = ...
+
+--- Line number for the 'foldexpr' `fold-expr`, 'formatexpr',
+--- 'indentexpr' and 'statuscolumn' expressions, tab page number
+--- for 'guitablabel' and 'guitabtooltip'. Only valid while one of
+--- these expressions is being evaluated. Read-only when in the
+--- `sandbox`.
+--- @type integer
+vim.v.lnum = ...
+
+--- Prefix for calling Lua functions from expressions.
+--- See `v:lua-call` for more information.
+--- @type any
+vim.v.lua = ...
+
+--- Maximum line length. Depending on where it is used it can be
+--- screen columns, characters or bytes. The value currently is
+--- 2147483647 on all systems.
+--- @type integer
+vim.v.maxcol = ...
+
+--- Column number for a mouse click obtained with `getchar()`.
+--- This is the screen column number, like with `virtcol()`. The
+--- value is zero when there was no mouse button click.
+--- @type integer
+vim.v.mouse_col = ...
+
+--- Line number for a mouse click obtained with `getchar()`.
+--- This is the text line number, not the screen line number. The
+--- value is zero when there was no mouse button click.
+--- @type integer
+vim.v.mouse_lnum = ...
+
+--- Window number for a mouse click obtained with `getchar()`.
+--- First window has number 1, like with `winnr()`. The value is
+--- zero when there was no mouse button click.
+--- @type integer
+vim.v.mouse_win = ...
+
+--- `window-ID` for a mouse click obtained with `getchar()`.
+--- The value is zero when there was no mouse button click.
+--- @type integer
+vim.v.mouse_winid = ...
+
+--- Dictionary containing msgpack types used by `msgpackparse()`
+--- and `msgpackdump()`. All types inside dictionary are fixed
+--- (not editable) empty lists. To check whether some list is one
+--- of msgpack types, use `is` operator.
+--- @type any
+vim.v.msgpack_types = ...
+
+--- Special value used to put "null" in JSON and NIL in msgpack.
+--- See `json_encode()`. This value is converted to "v:null" when
+--- used as a String (e.g. in `expr5` with string concatenation
+--- operator) and to zero when used as a Number (e.g. in `expr5`
+--- or `expr7` when used with numeric operators). Read-only.
+--- In some places `v:null` can be used for a List, Dict, etc.
+--- that is not set. That is slightly different than an empty
+--- List, Dict, etc.
+--- @type vim.NIL
+vim.v.null = ...
+
+--- Maximum value of a number.
+--- @type integer
+vim.v.numbermax = ...
+
+--- Minimum value of a number (negative).
+--- @type integer
+vim.v.numbermin = ...
+
+--- Number of bits in a Number. This is normally 64, but on some
+--- systems it may be 32.
+--- @type integer
+vim.v.numbersize = ...
+
+--- List of file names that is loaded from the `shada` file on
+--- startup. These are the files that Vim remembers marks for.
+--- The length of the List is limited by the ' argument of the
+--- 'shada' option (default is 100).
+--- When the `shada` file is not used the List is empty.
+--- Also see `:oldfiles` and `c_#<`.
+--- The List can be modified, but this has no effect on what is
+--- stored in the `shada` file later. If you use values other
+--- than String this will cause trouble.
+--- @type string[]
+vim.v.oldfiles = ...
+
+--- The last operator given in Normal mode. This is a single
+--- character except for commands starting with <g> or <z>,
+--- in which case it is two characters. Best used alongside
+--- `v:prevcount` and `v:register`. Useful if you want to cancel
+--- Operator-pending mode and then use the operator, e.g.:
+---
+--- ```vim
+--- :omap O <Esc>:call MyMotion(v:operator)<CR>
+--- ```
+---
+--- The value remains set until another operator is entered, thus
+--- don't expect it to be empty.
+--- v:operator is not set for `:delete`, `:yank` or other Ex
+--- commands.
+--- Read-only.
+--- @type string
+vim.v.operator = ...
+
+--- Command used to set the option. Valid while executing an
+--- `OptionSet` autocommand.
+--- value option was set via ~
+--- "setlocal" `:setlocal` or `:let l:xxx`
+--- "setglobal" `:setglobal` or `:let g:xxx`
+--- "set" `:set` or `:let`
+--- "modeline" `modeline`
+--- @type string
+vim.v.option_command = ...
+
+--- New value of the option. Valid while executing an `OptionSet`
+--- autocommand.
+--- @type any
+vim.v.option_new = ...
+
+--- Old value of the option. Valid while executing an `OptionSet`
+--- autocommand. Depending on the command used for setting and the
+--- kind of option this is either the local old value or the
+--- global old value.
+--- @type any
+vim.v.option_old = ...
+
+--- Old global value of the option. Valid while executing an
+--- `OptionSet` autocommand.
+--- @type any
+vim.v.option_oldglobal = ...
+
+--- Old local value of the option. Valid while executing an
+--- `OptionSet` autocommand.
+--- @type any
+vim.v.option_oldlocal = ...
+
+--- Scope of the set command. Valid while executing an
+--- `OptionSet` autocommand. Can be either "global" or "local"
+--- @type string
+vim.v.option_type = ...
+
+--- The count given for the last but one Normal mode command.
+--- This is the v:count value of the previous command. Useful if
+--- you want to cancel Visual or Operator-pending mode and then
+--- use the count, e.g.:
+---
+--- ```vim
+--- :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
+--- ```
+---
+--- Read-only.
+--- @type integer
+vim.v.prevcount = ...
+
+--- Normally zero. Set to one after using ":profile start".
+--- See `profiling`.
+--- @type integer
+vim.v.profiling = ...
+
+--- The name by which Nvim was invoked (with path removed).
+--- Read-only.
+--- @type string
+vim.v.progname = ...
+
+--- Absolute path to the current running Nvim.
+--- Read-only.
+--- @type string
+vim.v.progpath = ...
+
+--- The name of the register in effect for the current normal mode
+--- command (regardless of whether that command actually used a
+--- register). Or for the currently executing normal mode mapping
+--- (use this in custom commands that take a register).
+--- If none is supplied it is the default register '"', unless
+--- 'clipboard' contains "unnamed" or "unnamedplus", then it is
+--- "*" or '+'.
+--- Also see `getreg()` and `setreg()`
+--- @type string
+vim.v.register = ...
+
+--- Relative line number for the 'statuscolumn' expression.
+--- Read-only.
+--- @type integer
+vim.v.relnum = ...
+
+--- String describing the script or function that caused the
+--- screen to scroll up. It's only set when it is empty, thus the
+--- first reason is remembered. It is set to "Unknown" for a
+--- typed command.
+--- This can be used to find out why your script causes the
+--- hit-enter prompt.
+--- @type any
+vim.v.scrollstart = ...
+
+--- Search direction: 1 after a forward search, 0 after a
+--- backward search. It is reset to forward when directly setting
+--- the last search pattern, see `quote/`.
+--- Note that the value is restored when returning from a
+--- function. `function-search-undo`.
+--- Read-write.
+--- @type integer
+vim.v.searchforward = ...
+
+--- Primary listen-address of Nvim, the first item returned by
+--- `serverlist()`. Usually this is the named pipe created by Nvim
+--- at `startup` or given by `--listen` (or the deprecated
+--- `$NVIM_LISTEN_ADDRESS` env var).
+---
+--- See also `serverstart()` `serverstop()`.
+--- Read-only.
+---
+--- *$NVIM*
+--- $NVIM is set by `terminal` and `jobstart()`, and is thus
+--- a hint that the current environment is a subprocess of Nvim.
+--- Example:
+---
+--- ```vim
+--- if $NVIM
+--- echo nvim_get_chan_info(v:parent)
+--- endif
+--- ```
+---
+--- Note the contents of $NVIM may change in the future.
+--- @type string
+vim.v.servername = ...
+
+--- Result of the last shell command. When non-zero, the last
+--- shell command had an error. When zero, there was no problem.
+--- This only works when the shell returns the error code to Vim.
+--- The value -1 is often used when the command could not be
+--- executed. Read-only.
+--- Example:
+---
+--- ```vim
+--- !mv foo bar
+--- if v:shell_error
+--- echo 'could not rename "foo" to "bar"!'
+--- endif
+--- ```
+--- @type integer
+vim.v.shell_error = ...
+
+--- Last given status message.
+--- Modifiable (can be set).
+--- @type string
+vim.v.statusmsg = ...
+
+--- `channel-id` corresponding to stderr. The value is always 2;
+--- use this variable to make your code more descriptive.
+--- Unlike stdin and stdout (see `stdioopen()`), stderr is always
+--- open for writing. Example:
+---
+--- ```vim
+--- :call chansend(v:stderr, "error: toaster empty\n")
+--- ```
+--- @type integer
+vim.v.stderr = ...
+
+--- `SwapExists` autocommands can set this to the selected choice
+--- for handling an existing swapfile:
+--- 'o' Open read-only
+--- 'e' Edit anyway
+--- 'r' Recover
+--- 'd' Delete swapfile
+--- 'q' Quit
+--- 'a' Abort
+--- The value should be a single-character string. An empty value
+--- results in the user being asked, as would happen when there is
+--- no SwapExists autocommand. The default is empty.
+--- @type string
+vim.v.swapchoice = ...
+
+--- Normal mode command to be executed after a file has been
+--- opened. Can be used for a `SwapExists` autocommand to have
+--- another Vim open the file and jump to the right place. For
+--- example, when jumping to a tag the value is ":tag tagname\r".
+--- For ":edit +cmd file" the value is ":cmd\r".
+--- @type string
+vim.v.swapcommand = ...
+
+--- Name of the swapfile found.
+--- Only valid during `SwapExists` event.
+--- Read-only.
+--- @type string
+vim.v.swapname = ...
+
+--- Value of `Blob` type. Read-only. See: `type()`
+--- @type integer
+vim.v.t_blob = ...
+
+--- Value of `Boolean` type. Read-only. See: `type()`
+--- @type integer
+vim.v.t_bool = ...
+
+--- Value of `Dictionary` type. Read-only. See: `type()`
+--- @type integer
+vim.v.t_dict = ...
+
+--- Value of `Float` type. Read-only. See: `type()`
+--- @type integer
+vim.v.t_float = ...
+
+--- Value of `Funcref` type. Read-only. See: `type()`
+--- @type integer
+vim.v.t_func = ...
+
+--- Value of `List` type. Read-only. See: `type()`
+--- @type integer
+vim.v.t_list = ...
+
+--- Value of `Number` type. Read-only. See: `type()`
+--- @type integer
+vim.v.t_number = ...
+
+--- Value of `String` type. Read-only. See: `type()`
+--- @type integer
+vim.v.t_string = ...
+
+--- The value of the most recent OSC or DCS control sequence
+--- sent from a process running in the embedded `terminal`.
+--- This can be read in a `TermRequest` event handler to respond
+--- to queries from embedded applications.
+--- @type string
+vim.v.termrequest = ...
+
+--- The value of the most recent OSC or DCS control sequence
+--- received by Nvim from the terminal. This can be read in a
+--- `TermResponse` event handler after querying the terminal using
+--- another escape sequence.
+--- @type string
+vim.v.termresponse = ...
+
+--- Must be set before using `test_garbagecollect_now()`.
+--- @type any
+vim.v.testing = ...
+
+--- Full filename of the last loaded or saved session file.
+--- Empty when no session file has been saved. See `:mksession`.
+--- Modifiable (can be set).
+--- @type any
+vim.v.this_session = ...
+
+--- The point where the exception most recently caught and not
+--- finished was thrown. Not set when commands are typed. See
+--- also `v:exception` and `throw-variables`.
+--- Example:
+---
+--- ```vim
+--- try
+--- throw "oops"
+--- catch /.*/
+--- echo "Exception from" v:throwpoint
+--- endtry
+--- ```
+---
+--- Output: "Exception from test.vim, line 2"
+--- @type any
+vim.v.throwpoint = ...
+
+--- Special value used to put "true" in JSON and msgpack. See
+--- `json_encode()`. This value is converted to "v:true" when used
+--- as a String (e.g. in `expr5` with string concatenation
+--- operator) and to one when used as a Number (e.g. in `expr5` or
+--- `expr7` when used with numeric operators). Read-only.
+--- @type boolean
+vim.v['true'] = ...
+
+--- Value of the current item of a `List` or `Dictionary`. Only
+--- valid while evaluating the expression used with `map()` and
+--- `filter()`. Read-only.
+--- @type any
+vim.v.val = ...
+
+--- Vim version number: major version times 100 plus minor
+--- version. Vim 5.0 is 500, Vim 5.1 is 501.
+--- Read-only.
+--- Use `has()` to check the Nvim (not Vim) version:
+---
+--- ```vim
+--- :if has("nvim-0.2.1")
+--- ```
+--- @type integer
+vim.v.version = ...
+
+--- 0 during startup, 1 just before `VimEnter`.
+--- Read-only.
+--- @type integer
+vim.v.vim_did_enter = ...
+
+--- Virtual line number for the 'statuscolumn' expression.
+--- Negative when drawing the status column for virtual lines, zero
+--- when drawing an actual buffer line, and positive when drawing
+--- the wrapped part of a buffer line.
+--- Read-only.
+--- @type integer
+vim.v.virtnum = ...
+
+--- Last given warning message.
+--- Modifiable (can be set).
+--- @type string
+vim.v.warningmsg = ...
+
+--- Application-specific window "handle" which may be set by any
+--- attached UI. Defaults to zero.
+--- Note: For Nvim `windows` use `winnr()` or `win_getid()`, see
+--- `window-ID`.
+--- @type integer
+vim.v.windowid = ...
generated by cgit (git 2.34.1) at 2025-04-28 19:09:05 +0000