diff options
Diffstat (limited to 'runtime/lua/vim')
| -rw-r--r-- | runtime/lua/vim/_meta/api.lua | 1848 |
1 files changed, 893 insertions, 955 deletions
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 072f50e1a2..fd0b72bc00 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -20,13 +20,12 @@ function vim.api.nvim__buf_stats(buffer) end --- @private --- EXPERIMENTAL: this API may change in the future. --- ---- Sets info for the completion item at the given index. If the info text was ---- shown in a window, returns the window and buffer ids, or empty dict if not ---- shown. +--- Sets info for the completion item at the given index. If the info text was shown in a window, +--- returns the window and buffer ids, or empty dict if not shown. --- --- @param index integer Completion candidate index --- @param opts vim.api.keyset.complete_set Optional parameters. ---- • info: (string) info text. +--- - info: (string) info text. --- @return table<string,any> # Dict containing these keys: --- - winid: (number) floating window id --- - bufnr: (number) buffer id in floating window @@ -86,9 +85,7 @@ function vim.api.nvim__id_dict(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. ---- +--- NB: if your UI doesn't use hlstate, this will not return hlstate first time. --- @param grid integer --- @param row integer --- @param col integer @@ -96,9 +93,8 @@ function vim.api.nvim__id_float(flt) end function vim.api.nvim__inspect_cell(grid, row, col) end --- @private ---- For testing. The condition in schar_cache_clear_if_full is hard to reach, ---- so this function can be used to force a cache clear in a test. ---- +--- For testing. The condition in schar_cache_clear_if_full is hard to +--- reach, so this function can be used to force a cache clear in a test. function vim.api.nvim__invalidate_glyph_cache() end --- @private @@ -117,7 +113,7 @@ function vim.api.nvim__ns_get(ns_id) end --- --- @param ns_id integer Namespace --- @param opts vim.api.keyset.ns_opts Optional parameters to set: ---- • wins: a list of windows to be scoped in +--- - wins: a list of windows to be scoped in function vim.api.nvim__ns_set(ns_id, opts) end --- @private @@ -125,26 +121,27 @@ function vim.api.nvim__ns_set(ns_id, opts) end --- --- Instruct Nvim to redraw various components. --- +--- --- @see `:redraw` --- @param opts vim.api.keyset.redraw Optional parameters. ---- • win: Target a specific `window-ID` as described below. ---- • buf: Target a specific buffer number as described below. ---- • flush: Update the screen with pending updates. ---- • valid: When present mark `win`, `buf`, or all windows for ---- redraw. When `true`, only redraw changed lines (useful for ---- decoration providers). When `false`, forcefully redraw. ---- • range: Redraw a range in `buf`, the buffer in `win` or the ---- current buffer (useful for decoration providers). Expects a ---- tuple `[first, last]` with the first and last line number of ---- the range, 0-based end-exclusive `api-indexing`. ---- • cursor: Immediately update cursor position on the screen in ---- `win` or the current window. ---- • statuscolumn: Redraw the 'statuscolumn' in `buf`, `win` or ---- all windows. ---- • statusline: Redraw the 'statusline' in `buf`, `win` or all ---- windows. ---- • winbar: Redraw the 'winbar' in `buf`, `win` or all windows. ---- • tabline: Redraw the 'tabline'. +--- - win: Target a specific `window-ID` as described below. +--- - buf: Target a specific buffer number as described below. +--- - flush: Update the screen with pending updates. +--- - valid: When present mark `win`, `buf`, or all windows for +--- redraw. When `true`, only redraw changed lines (useful for +--- decoration providers). When `false`, forcefully redraw. +--- - range: Redraw a range in `buf`, the buffer in `win` or the +--- current buffer (useful for decoration providers). Expects a +--- tuple `[first, last]` with the first and last line number +--- of the range, 0-based end-exclusive `api-indexing`. +--- - cursor: Immediately update cursor position on the screen in +--- `win` or the current window. +--- - statuscolumn: Redraw the 'statuscolumn' in `buf`, `win` or +--- all windows. +--- - statusline: Redraw the 'statusline' in `buf`, `win` or all +--- windows. +--- - winbar: Redraw the 'winbar' in `buf`, `win` or all windows. +--- - tabline: Redraw the 'tabline'. function vim.api.nvim__redraw(opts) end --- @private @@ -168,18 +165,18 @@ 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. +--- 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`. +--- 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 @@ -192,23 +189,23 @@ function vim.api.nvim__unpack(str) end --- @param hl_group string Name of the highlight group to use --- @param line integer Line to highlight (zero-indexed) --- @param col_start integer Start of (byte-indexed) column range to highlight ---- @param col_end integer End of (byte-indexed) column range to highlight, or -1 to ---- highlight to end of line +--- @param col_end integer End of (byte-indexed) column range to highlight, +--- or -1 to highlight to end of line --- @return integer # The ns_id that was used 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): +--- Example (Lua): capture buffer updates in a global `events` variable +--- (use "vim.print(events)" to see its contents): --- --- ```lua ---- events = {} ---- vim.api.nvim_buf_attach(0, false, { ---- on_lines = function(...) ---- table.insert(events, {...}) ---- end, ---- }) +--- events = {} +--- vim.api.nvim_buf_attach(0, false, { +--- on_lines = function(...) +--- table.insert(events, {...}) +--- end, +--- }) --- ``` --- --- @@ -216,67 +213,66 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- @see `api-buffer-updates-lua` --- @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. +--- 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 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. +--- - 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 # False if attach failed (invalid parameter, or buffer isn't loaded); --- otherwise True. TODO: LUA_API_NO_EVAL 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, ---- then one of these windows will be set as current window temporarily. +--- This temporarily switches current buffer to "buffer". +--- If the current window already shows "buffer", the window is not switched. +--- If a window inside the current tabpage (including a float) already shows the +--- buffer, then one of these windows will be set as current window temporarily. --- Otherwise a temporary scratch window (called the "autocmd window" for --- historical reasons) will be used. --- @@ -285,7 +281,7 @@ function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end --- --- @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 # Return value of function. function vim.api.nvim_buf_call(buffer, fun) end @@ -296,17 +292,17 @@ function vim.api.nvim_buf_call(buffer, fun) end --- @param line_end integer function vim.api.nvim_buf_clear_highlight(buffer, ns_id, line_start, line_end) end ---- Clears `namespace`d objects (highlights, `extmarks`, virtual text) from a ---- region. +--- Clears `namespace`d objects (highlights, `extmarks`, virtual text) from +--- a region. --- ---- Lines are 0-indexed. `api-indexing` To clear the namespace in the entire +--- 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. +--- 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`. @@ -328,6 +324,7 @@ function vim.api.nvim_buf_del_extmark(buffer, ns_id, id) end --- Unmaps a buffer-local `mapping` for the given mode. --- +--- --- @see `nvim_del_keymap()` --- @param buffer integer Buffer handle, or 0 for current buffer --- @param mode string @@ -337,8 +334,8 @@ function vim.api.nvim_buf_del_keymap(buffer, mode, lhs) end --- Deletes a named mark in the buffer. See `mark-motions`. --- --- Note: ---- • only deletes marks set in the buffer, if the mark is not set in the ---- buffer it will return false. +--- only deletes marks set in the buffer, if the mark is not set +--- in the buffer it will return false. --- --- @see `nvim_buf_set_mark()` --- @see `nvim_del_mark()` @@ -366,8 +363,8 @@ function vim.api.nvim_buf_del_var(buffer, name) end --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @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` +--- - 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 @@ -389,9 +386,8 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end --- @param ns_id integer Namespace id from `nvim_create_namespace()` --- @param id integer Extmark id --- @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 +--- - 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_by_id # 0-indexed (row, col) tuple or empty list () if extmark id was --- absent function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end @@ -404,55 +400,51 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- respectively, thus the following are equivalent: --- --- ```lua ---- vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) ---- vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {}) +--- vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) +--- vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {}) --- ``` --- ---- If `end` is less than `start`, traversal works backwards. (Useful with ---- `limit`, to get the first marks prior to a given position.) +--- 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. +--- 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 +--- 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 ---- local api = vim.api ---- local pos = api.nvim_win_get_cursor(0) ---- local ns = api.nvim_create_namespace('my-plugin') ---- -- Create new extmark at line 1, column 1. ---- local m1 = api.nvim_buf_set_extmark(0, ns, 0, 0, {}) ---- -- Create new extmark at line 3, column 1. ---- local m2 = api.nvim_buf_set_extmark(0, ns, 2, 0, {}) ---- -- Get extmarks only from line 3. ---- local ms = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) ---- -- Get all marks in this buffer + namespace. ---- local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {}) ---- vim.print(ms) +--- local api = vim.api +--- local pos = api.nvim_win_get_cursor(0) +--- local ns = api.nvim_create_namespace('my-plugin') +--- -- Create new extmark at line 1, column 1. +--- local m1 = api.nvim_buf_set_extmark(0, ns, 0, 0, {}) +--- -- Create new extmark at line 3, column 1. +--- local m2 = api.nvim_buf_set_extmark(0, ns, 2, 0, {}) +--- -- Get extmarks only from line 3. +--- local ms = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) +--- -- Get all marks in this buffer + namespace. +--- local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {}) +--- 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 +--- @param ns_id integer Namespace id from `nvim_create_namespace()` or -1 for all 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" +--- - 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[] # List of `[extmark_id, row, col]` tuples in "traversal order". function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end @@ -466,9 +458,9 @@ 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. +--- 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. @@ -481,8 +473,8 @@ function vim.api.nvim_buf_get_keymap(buffer, mode) end 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`. +--- "End of line" column position is returned as `v:maxcol` (big number). +--- See `mark-motions`. --- --- Marks are (1,0)-indexed. `api-indexing` --- @@ -512,8 +504,8 @@ function vim.api.nvim_buf_get_number(buffer) end --- 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. +--- Unlike `line2byte()`, throws error for out-of-bounds indexing. +--- Returns -1 for unloaded buffer. --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param index integer Line index @@ -562,8 +554,9 @@ function vim.api.nvim_buf_is_loaded(buffer) end --- Checks if a buffer is valid. --- --- Note: ---- • Even if a buffer is valid it may have been unloaded. See `api-buffer` ---- for more info about unloaded buffers. +--- Even if a buffer is valid it may have been unloaded. See |api-buffer| +--- for more info about unloaded buffers. +--- --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @return boolean # true if the buffer is valid, false otherwise. @@ -577,18 +570,18 @@ 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.) +--- 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. +--- 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 +--- 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 --- range (no highlighting). --- --- @param buffer integer Buffer handle, or 0 for current buffer @@ -596,113 +589,121 @@ 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. ---- • 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. +--- - 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. --- @return integer # Id of the created/updated extmark function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end --- Sets a buffer-local `mapping` for the given mode. --- +--- --- @see `nvim_set_keymap()` --- @param buffer integer Buffer handle, or 0 for current buffer --- @param mode string @@ -713,9 +714,9 @@ 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. +--- 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. @@ -723,6 +724,7 @@ function vim.api.nvim_buf_set_keymap(buffer, mode, lhs, rhs, opts) end --- Out-of-bounds indices are clamped to the nearest valid value, unless --- `strict_indexing` is set. --- +--- --- @see `nvim_buf_set_text()` --- @param buffer integer Buffer handle, or 0 for current buffer --- @param start integer First line index @@ -737,7 +739,8 @@ function vim.api.nvim_buf_set_lines(buffer, start, end_, strict_indexing, replac --- Marks are (1,0)-indexed. `api-indexing` --- --- Note: ---- • Passing 0 as line deletes the mark +--- Passing 0 as line deletes the mark +--- --- --- @see `nvim_buf_del_mark()` --- @see `nvim_buf_get_mark()` @@ -763,22 +766,21 @@ 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. +--- 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 = r |