diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 4682 |
1 files changed, 2228 insertions, 2454 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index be42b7c14e..a388592981 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1,10 +1,10 @@ -*api.txt* Nvim +*api.txt* Nvim - NVIM REFERENCE MANUAL by Thiago de Arruda + NVIM REFERENCE MANUAL by Thiago de Arruda -Nvim API *API* *api* +Nvim API *API* *api* Nvim exposes a powerful API that can be used by plugins and external processes via |RPC|, |Lua| and VimL (|eval-api|). @@ -14,9 +14,9 @@ Applications can also embed libnvim to work with the C API directly. Type |gO| to see the table of contents. ============================================================================== -API Usage *api-rpc* *RPC* *rpc* +API Usage *api-rpc* *RPC* *rpc* - *msgpack-rpc* + *msgpack-rpc* RPC is the typical way to control Nvim programmatically. Nvim implements the MessagePack-RPC protocol: https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md @@ -32,7 +32,7 @@ other Nvim instances. API clients can: The RPC API is like a more powerful version of Vim's "clientserver" feature. -CONNECTING *rpc-connecting* +CONNECTING *rpc-connecting* See |channel-intro| for various ways to open a channel. Channel-opening functions take an `rpc` key in the options dictionary. RPC channels can also @@ -85,21 +85,21 @@ and |rpcnotify()|: call jobstop(nvim) ============================================================================== -API Definitions *api-definitions* +API Definitions *api-definitions* - *api-types* + *api-types* The Nvim C API defines custom types for all function parameters. Some are just typedefs around C99 standard types, others are Nvim-defined data structures. Basic types ~ - API Type C type + API Type C type ------------------------------------------------------------------------ Nil - Boolean bool - Integer (signed 64-bit integer) int64_t - Float (IEEE 754 double precision) double - String {char* data, size_t size} struct + Boolean bool + Integer (signed 64-bit integer) int64_t + Float (IEEE 754 double precision) double + String {char* data, size_t size} struct Array Dictionary (msgpack: map) Object @@ -116,14 +116,14 @@ Special types (msgpack EXT) ~ in the |api-metadata| `types` key are stable: they will not change and are thus forward-compatible. - EXT Type C type Data + EXT Type C type Data ------------------------------------------------------------------------ - Buffer enum value kObjectTypeBuffer |bufnr()| - Window enum value kObjectTypeWindow |window-ID| - Tabpage enum value kObjectTypeTabpage internal handle + Buffer enum value kObjectTypeBuffer |bufnr()| + Window enum value kObjectTypeWindow |window-ID| + Tabpage enum value kObjectTypeTabpage internal handle - *api-indexing* + *api-indexing* Most of the API uses 0-based indices, and ranges are end-exclusive. For the end of a range, -1 denotes the last line/column. @@ -144,7 +144,7 @@ indices, end-inclusive): |nvim_buf_get_extmarks()| |nvim_buf_set_extmark()| - *api-fast* + *api-fast* Most API functions are "deferred": they are queued on the main loop and processed sequentially with normal input. So if the editor is waiting for user input in a "modal" fashion (e.g. the |hit-enter-prompt|), the request @@ -153,7 +153,7 @@ will block. Non-deferred (fast) functions such as |nvim_get_mode()| and queue). Lua code can use |vim.in_fast_event()| to detect a fast context. ============================================================================== -API metadata *api-metadata* +API metadata *api-metadata* The Nvim C API is automatically exposed to RPC by the build system, which parses headers in src/nvim/api/* and generates dispatch-functions mapping RPC @@ -162,19 +162,19 @@ and return values. Nvim exposes its API metadata as a Dictionary with these items: -version Nvim version, API level/compatibility -version.api_level API version integer *api-level* -version.api_compatible API is backwards-compatible with this level -version.api_prerelease Declares the API as unstable/unreleased > - (version.api_prerelease && fn.since == version.api_level) -functions API function signatures, containing |api-types| info +version Nvim version, API level/compatibility +version.api_level API version integer *api-level* +version.api_compatible API is backwards-compatible with this level +version.api_prerelease Declares the API as unstable/unreleased > + (version.api_prerelease && fn.since == version.api_level) +functions API function signatures, containing |api-types| info describing the return value and parameters. -ui_events |UI| event signatures -ui_options Supported |ui-option|s -{fn}.since API level where function {fn} was introduced -{fn}.deprecated_since API level where function {fn} was deprecated -types Custom handle types defined by Nvim -error_types Possible error types returned by API functions +ui_events |UI| event signatures +ui_options Supported |ui-option|s +{fn}.since API level where function {fn} was introduced +{fn}.deprecated_since API level where function {fn} was deprecated +types Custom handle types defined by Nvim +error_types Possible error types returned by API functions About the `functions` map: @@ -188,7 +188,7 @@ About the `functions` map: - Global functions have the "method=false" flag and are prefixed with just `nvim_`, e.g. `nvim_list_bufs`. - *api-mapping* + *api-mapping* External programs (clients) can use the metadata to discover the API, using any of these approaches: @@ -231,7 +231,7 @@ As Nvim evolves the API may change in compliance with this CONTRACT: - Deprecated functions will not be removed until Nvim version 2.0 ============================================================================== -Global events *api-global-events* +Global events *api-global-events* When a client invokes an API request as an async notification, it is not possible for Nvim to send an error response. Instead, in case of error, the @@ -244,7 +244,7 @@ nvim_error_event[{type}, {message}] a string with the error message. ============================================================================== -Buffer update events *api-buffer-updates* +Buffer update events *api-buffer-updates* API clients can "attach" to Nvim buffers to subscribe to buffer update events. This is similar to |TextChanged| but more powerful and granular. @@ -254,89 +254,90 @@ Call |nvim_buf_attach()| to receive these events on the channel: *nvim_buf_lines_event* nvim_buf_lines_event[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}, {more}] - When the buffer text between {firstline} and {lastline} (end-exclusive, - zero-indexed) were changed to the new text in the {linedata} list. The - granularity is a line, i.e. if a single character is changed in the editor, - the entire line is sent. + When the buffer text between {firstline} and {lastline} (end-exclusive, + zero-indexed) were changed to the new text in the {linedata} list. The + granularity is a line, i.e. if a single character is changed in the + editor, the entire line is sent. - When {changedtick} is |v:null| this means the screen lines (display) changed - but not the buffer contents. {linedata} contains the changed screen lines. - This happens when 'inccommand' shows a buffer preview. + When {changedtick} is |v:null| this means the screen lines (display) + changed but not the buffer contents. {linedata} contains the changed + screen lines. This happens when 'inccommand' shows a buffer preview. - Properties:~ - {buf} API buffer handle (buffer number) + Properties:~ + {buf} API buffer handle (buffer number) - {changedtick} value of |b:changedtick| for the buffer. If you send an API - command back to nvim you can check the value of |b:changedtick| as part of - your request to ensure that no other changes have been made. + {changedtick} value of |b:changedtick| for the buffer. If you send an + API command back to nvim you can check the value of |b:changedtick| as + part of your request to ensure that no other changes have been made. - {firstline} integer line number of the first line that was replaced. - Zero-indexed: if line 1 was replaced then {firstline} will be 0, not 1. - {firstline} is always less than or equal to the number of lines that were - in the buffer before the lines were replaced. + {firstline} integer line number of the first line that was replaced. + Zero-indexed: if line 1 was replaced then {firstline} will be 0, not + 1. {firstline} is always less than or equal to the number of lines + that were in the buffer before the lines were replaced. - {lastline} integer line number of the first line that was not replaced - (i.e. the range {firstline}, {lastline} is end-exclusive). - Zero-indexed: if line numbers 2 to 5 were replaced, this will be 5 instead - of 6. {lastline} is always be less than or equal to the number of lines - that were in the buffer before the lines were replaced. {lastline} will be - -1 if the event is part of the initial update after attaching. + {lastline} integer line number of the first line that was not replaced + (i.e. the range {firstline}, {lastline} is end-exclusive). + Zero-indexed: if line numbers 2 to 5 were replaced, this will be 5 + instead of 6. {lastline} is always be less than or equal to the number + of lines that were in the buffer before the lines were replaced. + {lastline} will be -1 if the event is part of the initial update after + attaching. - {linedata} list of strings containing the contents of the new buffer - lines. Newline characters are omitted; empty lines are sent as empty - strings. + {linedata} list of strings containing the contents of the new buffer + lines. Newline characters are omitted; empty lines are sent as empty + strings. - {more} boolean, true for a "multipart" change notification: the current - change was chunked into multiple |nvim_buf_lines_event| notifications - (e.g. because it was too big). + {more} boolean, true for a "multipart" change notification: the + current change was chunked into multiple |nvim_buf_lines_event| + notifications (e.g. because it was too big). nvim_buf_changedtick_event[{buf}, {changedtick}] *nvim_buf_changedtick_event* - When |b:changedtick| was incremented but no text was changed. Relevant for - undo/redo. + When |b:changedtick| was incremented but no text was changed. Relevant for + undo/redo. - Properties:~ - {buf} API buffer handle (buffer number) - {changedtick} new value of |b:changedtick| for the buffer + Properties:~ + {buf} API buffer handle (buffer number) + {changedtick} new value of |b:changedtick| for the buffer nvim_buf_detach_event[{buf}] *nvim_buf_detach_event* - When buffer is detached (i.e. updates are disabled). Triggered explicitly by - |nvim_buf_detach()| or implicitly in these cases: - - Buffer was |abandon|ed and 'hidden' is not set. - - Buffer was reloaded, e.g. with |:edit| or an external change triggered - |:checktime| or 'autoread'. - - Generally: whenever the buffer contents are unloaded from memory. + When buffer is detached (i.e. updates are disabled). Triggered explicitly by + |nvim_buf_detach()| or implicitly in these cases: + - Buffer was |abandon|ed and 'hidden' is not set. + - Buffer was reloaded, e.g. with |:edit| or an external change triggered + |:checktime| or 'autoread'. + - Generally: whenever the buffer contents are unloaded from memory. - Properties:~ - {buf} API buffer handle (buffer number) + Properties:~ + {buf} API buffer handle (buffer number) EXAMPLE ~ Calling |nvim_buf_attach()| with send_buffer=true on an empty buffer, emits: > - nvim_buf_lines_event[{buf}, {changedtick}, 0, -1, [""], v:false] + nvim_buf_lines_event[{buf}, {changedtick}, 0, -1, [""], v:false] User adds two lines to the buffer, emits: > - nvim_buf_lines_event[{buf}, {changedtick}, 0, 0, ["line1", "line2"], v:false] + nvim_buf_lines_event[{buf}, {changedtick}, 0, 0, ["line1", "line2"], v:false] User moves to a line containing the text "Hello world" and inserts "!", emits: > - nvim_buf_lines_event[{buf}, {changedtick}, {linenr}, {linenr} + 1, - ["Hello world!"], v:false] + nvim_buf_lines_event[{buf}, {changedtick}, {linenr}, {linenr} + 1, + ["Hello world!"], v:false] User moves to line 3 and deletes 20 lines using "20dd", emits: > - nvim_buf_lines_event[{buf}, {changedtick}, 2, 22, [], v:false] + nvim_buf_lines_event[{buf}, {changedtick}, 2, 22, [], v:false] User selects lines 3-5 using |linewise-visual| mode and then types "p" to paste a block of 6 lines, emits: > - nvim_buf_lines_event[{buf}, {changedtick}, 2, 5, - ['pasted line 1', 'pasted line 2', 'pasted line 3', 'pasted line 4', - 'pasted line 5', 'pasted line 6'], - v:false - ] + nvim_buf_lines_event[{buf}, {changedtick}, 2, 5, + ['pasted line 1', 'pasted line 2', 'pasted line 3', 'pasted line 4', + 'pasted line 5', 'pasted line 6'], + v:false + ] User reloads the buffer with ":edit", emits: > - nvim_buf_detach_event[{buf}] + nvim_buf_detach_event[{buf}] < LUA ~ @@ -369,7 +370,7 @@ callbacks attached with the same |nvim_buf_attach()| call. ============================================================================== -Buffer highlighting *api-highlights* +Buffer highlighting *api-highlights* Nvim allows plugins to add position-based highlights to buffers. This is similar to |matchaddpos()| but with some key differences. The added highlights @@ -413,7 +414,7 @@ Example using the API from Vimscript: > ============================================================================== -Floating windows *api-floatwin* +Floating windows *api-floatwin* Floating windows ("floats") are displayed on top of normal windows. This is useful to implement simple widgets, such as tooltips displayed next to the @@ -457,7 +458,7 @@ Example: create a float with scratch buffer: > > ============================================================================== -Extended marks *api-extended-marks* *extmarks* +Extended marks *api-extended-marks* *extmarks* Extended marks (extmarks) represent buffer annotations that track text changes in the buffer. They can represent cursors, folds, misspelled words, anything @@ -537,1025 +538,961 @@ created for extmark changes. Global Functions *api-global* nvim__get_runtime({pat}, {all}, {*opts}) *nvim__get_runtime()* - Find files in runtime directories + Find files in runtime directories - Attributes: ~ - |api-fast| + Attributes: ~ + |api-fast| - Parameters: ~ - {pat} pattern of files to search for - {all} whether to return all matches or only the first - {opts} is_lua: only search lua subdirs + Parameters: ~ + {pat} pattern of files to search for + {all} whether to return all matches or only the first + {opts} is_lua: only search lua subdirs - Return: ~ - list of absolute paths to the found files + Return: ~ + list of absolute paths to the found files nvim__id({obj}) *nvim__id()* - Returns object given as argument. + Returns object given as argument. - This API function is used for testing. One should not rely on - its presence in plugins. + This API function is used for testing. One should not rely on its presence + in plugins. - Parameters: ~ - {obj} Object to return. + Parameters: ~ + {obj} Object to return. - Return: ~ - its argument. + Return: ~ + its argument. nvim__id_array({arr}) *nvim__id_array()* - Returns array given as argument. + Returns array given as argument. - This API function is used for testing. One should not rely on - its presence in plugins. + This API function is used for testing. One should not rely on its presence + in plugins. - Parameters: ~ - {arr} Array to return. + Parameters: ~ + {arr} Array to return. - Return: ~ - its argument. + Return: ~ + its argument. nvim__id_dictionary({dct}) *nvim__id_dictionary()* - Returns dictionary given as argument. + Returns dictionary given as argument. - This API function is used for testing. One should not rely on - its presence in plugins. + This API function is used for testing. One should not rely on its presence + in plugins. - Parameters: ~ - {dct} Dictionary to return. + Parameters: ~ + {dct} Dictionary to return. - Return: ~ - its argument. + Return: ~ + its argument. nvim__id_float({flt}) *nvim__id_float()* - Returns floating-point value given as argument. + Returns floating-point value given as argument. - This API function is used for testing. One should not rely on - its presence in plugins. + This API function is used for testing. One should not rely on its presence + in plugins. - Parameters: ~ - {flt} Value to return. + Parameters: ~ + {flt} Value to return. - Return: ~ - its argument. + Return: ~ + its argument. nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* - NB: if your UI doesn't use hlstate, this will not return - hlstate first time. - -nvim__set_hl_ns({ns_id}) *nvim__set_hl_ns()* - Set active namespace for highlights. - - NB: this function can be called from async contexts, but the - semantics are not yet well-defined. To start with - |nvim_set_decoration_provider| on_win and on_line callbacks - are explicitly allowed to change the namespace during a redraw - cycle. - - Attributes: ~ - |api-fast| - - Parameters: ~ - {ns_id} the namespace to activate + NB: if your UI doesn't use hlstate, this will not return hlstate first + time. nvim__stats() *nvim__stats()* - Gets internal stats. + Gets internal stats. - Return: ~ - Map of various internal stats. + Return: ~ + Map of various internal stats. nvim_call_atomic({calls}) *nvim_call_atomic()* - Calls many API methods atomically. - - This has two main usages: - 1. To perform several requests from an async context - atomically, i.e. without interleaving redraws, RPC requests - from other clients, or user interactions (however API - methods may trigger autocommands or event processing which - have such side effects, e.g. |:sleep| may wake timers). - 2. To minimize RPC overhead (roundtrips) of a sequence of many - requests. - - Attributes: ~ - |RPC| only - - Parameters: ~ - {calls} an array of calls, where each call is described - by an array with two elements: the request name, - and an array of arguments. - - Return: ~ - Array of two elements. The first is an array of return - values. The second is NIL if all calls succeeded. If a - call resulted in an error, it is a three-element array - with the zero-based index of the call which resulted in an - error, the error type and the error message. If an error - occurred, the values from all preceding calls will still - be returned. + Calls many API methods atomically. + + This has two main usages: + 1. To perform several requests from an async context atomically, i.e. + without interleaving redraws, RPC requests from other clients, or user + interactions (however API methods may trigger autocommands or event + processing which have such side effects, e.g. |:sleep| may wake + timers). + 2. To minimize RPC overhead (roundtrips) of a sequence of many requests. + + Attributes: ~ + |RPC| only + + Parameters: ~ + {calls} an array of calls, where each call is described by an array + with two elements: the request name, and an array of + arguments. + + Return: ~ + Array of two elements. The first is an array of return values. The + second is NIL if all calls succeeded. If a call resulted in an error, + it is a three-element array with the zero-based index of the call + which resulted in an error, the error type and the error message. If + an error occurred, the values from all preceding calls will still be + returned. nvim_chan_send({chan}, {data}) *nvim_chan_send()* - Send data to channel `id`. For a job, it writes it to the - stdin of the 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. + Send data to channel `id`. For a job, it writes it to the stdin of the + 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. + 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. - Attributes: ~ - |RPC| only - |vim.api| only + Attributes: ~ + |RPC| only + |vim.api| only - Parameters: ~ - {chan} id of the channel - {data} data to write. 8-bit clean: can contain NUL bytes. + Parameters: ~ + {chan} id of the channel + {data} data to write. 8-bit clean: can contain NUL bytes. nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* - Creates a new, empty, unnamed buffer. + Creates a new, empty, unnamed buffer. - Parameters: ~ - {listed} Sets 'buflisted' - {scratch} Creates a "throwaway" |scratch-buffer| for - temporary work (always 'nomodified'). Also sets - 'nomodeline' on the buffer. + Parameters: ~ + {listed} Sets 'buflisted' + {scratch} Creates a "throwaway" |scratch-buffer| for temporary work + (always 'nomodified'). Also sets 'nomodeline' on the + buffer. - Return: ~ - Buffer handle, or 0 on error + Return: ~ + Buffer handle, or 0 on error - See also: ~ - buf_open_scratch + See also: ~ + buf_open_scratch nvim_del_current_line() *nvim_del_current_line()* - Deletes the current line. + Deletes the current line. - Attributes: ~ - not allowed when |textlock| is active + Attributes: ~ + not allowed when |textlock| is active nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()* - Unmaps a global |mapping| for the given mode. + Unmaps a global |mapping| for the given mode. - To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|. + To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|. - See also: ~ - |nvim_set_keymap()| + See also: ~ + |nvim_set_keymap()| nvim_del_mark({name}) *nvim_del_mark()* - Deletes an uppercase/file named mark. See |mark-motions|. + Deletes an uppercase/file named mark. See |mark-motions|. - Note: - fails with error if a lowercase or buffer local named mark - is used. + Note: + fails with error if a lowercase or buffer local named mark is used. - Parameters: ~ - {name} Mark name + Parameters: ~ + {name} Mark name - Return: ~ - true if the mark was deleted, else false. + Return: ~ + true if the mark was deleted, else false. - See also: ~ - |nvim_buf_del_mark()| - |nvim_get_mark()| + See also: ~ + |nvim_buf_del_mark()| + |nvim_get_mark()| nvim_del_var({name}) *nvim_del_var()* - Removes a global (g:) variable. + Removes a global (g:) variable. - Parameters: ~ - {name} Variable name + Parameters: ~ + {name} Variable name nvim_echo({chunks}, {history}, {opts}) *nvim_echo()* - Echo a message. + Echo a message. - Parameters: ~ - {chunks} A list of [text, hl_group] arrays, each - representing a text chunk with specified - highlight. `hl_group` element can be omitted - for no highlight. - {history} if true, add to |message-history|. - {opts} Optional parameters. Reserved for future use. + Parameters: ~ + {chunks} A list of [text, hl_group] arrays, each representing a text + chunk with specified highlight. `hl_group` element can be + omitted for no highlight. + {history} if true, add to |message-history|. + {opts} Optional parameters. Reserved for future use. nvim_err_write({str}) *nvim_err_write()* - Writes a message to the Vim error buffer. Does not append - "\n", the message is buffered (won't display) until a linefeed - is written. + Writes a message to the Vim error buffer. Does not append "\n", the + message is buffered (won't display) until a linefeed is written. - Parameters: ~ - {str} Message + Parameters: ~ + {str} Message nvim_err_writeln({str}) *nvim_err_writeln()* - Writes a message to the Vim error buffer. Appends "\n", so the - buffer is flushed (and displayed). + Writes a message to the Vim error buffer. Appends "\n", so the buffer is + flushed (and displayed). - Parameters: ~ - {str} Message + Parameters: ~ + {str} Message - See also: ~ - nvim_err_write() + See also: ~ + nvim_err_write() nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* - Evaluates statusline string. - - Attributes: ~ - |api-fast| - - Parameters: ~ - {str} Statusline string (see 'statusline'). - {opts} Optional parameters. - • winid: (number) |window-ID| of the window to use - as context for statusline. - • maxwidth: (number) Maximum width of statusline. - • fillchar: (string) Character to fill blank - spaces in the statusline (see 'fillchars'). - Treated as single-width even if it isn't. - • highlights: (boolean) Return highlight - information. - • use_winbar: (boolean) Evaluate winbar instead of - statusline. - • use_tabline: (boolean) Evaluate tabline instead - of statusline. When |TRUE|, {winid} is ignored. - Mutually exclusive with {use_winbar}. - - Return: ~ - Dictionary containing statusline information, with these - keys: - • str: (string) Characters that will be displayed on the - statusline. - • width: (number) Display width of the statusline. - • highlights: Array containing highlight information of - the statusline. Only included when the "highlights" key - in {opts} is |TRUE|. Each element of the array is a - |Dictionary| with these keys: - • start: (number) Byte index (0-based) of first - character that uses the highlight. - • group: (string) Name of highlight group. + Evaluates statusline string. + + Attributes: ~ + |api-fast| + + Parameters: ~ + {str} Statusline string (see 'statusline'). + {opts} Optional parameters. + • winid: (number) |window-ID| of the window to use as context + for statusline. + • maxwidth: (number) Maximum width of statusline. + • fillchar: (string) Character to fill blank spaces in the + statusline (see 'fillchars'). Treated as single-width even + if it isn't. + • highlights: (boolean) Return highlight information. + • use_winbar: (boolean) Evaluate winbar instead of statusline. + • use_tabline: (boolean) Evaluate tabline instead of + statusline. When |TRUE|, {winid} is ignored. Mutually + exclusive with {use_winbar}. + + Return: ~ + Dictionary containing statusline information, with these keys: + • str: (string) Characters that will be displayed on the statusline. + • width: (number) Display width of the statusline. + • highlights: Array containing highlight information of the + statusline. Only included when the "highlights" key in {opts} is + |TRUE|. Each element of the array is a |Dictionary| with these keys: + • start: (number) Byte index (0-based) of first character that uses + the highlight. + • group: (string) Name of highlight group. nvim_exec_lua({code}, {args}) *nvim_exec_lua()* - Execute Lua code. Parameters (if any) are available as `...` - inside the chunk. The chunk can return a value. + Execute Lua code. Parameters (if any) are available as `...` inside the + chunk. The chunk can return a value. - Only statements are executed. To evaluate an expression, - prefix it with `return`: return my_function(...) + Only statements are executed. To evaluate an expression, prefix it with + `return`: return my_function(...) - Attributes: ~ - |RPC| only + Attributes: ~ + |RPC| only - Parameters: ~ - {code} Lua code to execute - {args} Arguments to the code + Parameters: ~ + {code} Lua code to execute + {args} Arguments to the code - Return: ~ - Return value of Lua code if present or NIL. + Return: ~ + Return value of Lua code if present or NIL. nvim_feedkeys({keys}, {mode}, {escape_ks}) *nvim_feedkeys()* - Sends input-keys to Nvim, subject to various quirks controlled - by `mode` flags. This is a blocking call, unlike - |nvim_input()|. + 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. + 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(). + 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: > - :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true) - :call nvim_feedkeys(key, 'n', v:false) + Example: > + :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true) + :call nvim_feedkeys(key, 'n', v:false) < - Parameters: ~ - {keys} to be typed - {mode} behavior flags, see |feedkeys()| - {escape_ks} If true, escape K_SPECIAL bytes in `keys` - This should be false if you already used - |nvim_replace_termcodes()|, and true - otherwise. + Parameters: ~ + {keys} to be typed + {mode} behavior flags, see |feedkeys()| + {escape_ks} If true, escape K_SPECIAL bytes in `keys` This should be + false if you already used |nvim_replace_termcodes()|, and + true otherwise. - See also: ~ - feedkeys() - vim_strsave_escape_ks + See also: ~ + feedkeys() + vim_strsave_escape_ks nvim_get_api_info() *nvim_get_api_info()* - Returns a 2-tuple (Array), where item 0 is the current channel - id and item 1 is the |api-metadata| map (Dictionary). + Returns a 2-tuple (Array), where item 0 is the current channel id and item + 1 is the |api-metadata| map (Dictionary). - Return: ~ - 2-tuple [{channel-id}, {api-metadata}] + Return: ~ + 2-tuple [{channel-id}, {api-metadata}] - Attributes: ~ - |api-fast| - |RPC| only + Attributes: ~ + |api-fast| + |RPC| only nvim_get_chan_info({chan}) *nvim_get_chan_info()* - Gets information about a channel. - - Return: ~ - Dictionary describing a channel, with these keys: - • "id" Channel id. - • "argv" (optional) Job arguments list. - • "stream" Stream underlying the channel. - • "stdio" stdin and stdout of this Nvim instance - • "stderr" stderr of this Nvim instance - • "socket" TCP/IP socket or named pipe - • "job" Job with communication over its stdio. - - • "mode" How data received on the channel is interpreted. - • "bytes" Send and receive raw bytes. - • "terminal" |terminal| instance interprets ASCII - sequences. - • "rpc" |RPC| communication on the channel is active. - - • "pty" (optional) Name of pseudoterminal. On a POSIX - system this is a device path like "/dev/pts/1". If the - name is unknown, the key will still be present if a pty - is used (e.g. for conpty on Windows). - • "buffer" (optional) Buffer with connected |terminal| - instance. - • "client" (optional) Info about the peer (client on the - other end of the RPC channel), if provided by it via - |nvim_set_client_info()|. + Gets information about a channel. + + Return: ~ + Dictionary describing a channel, with these keys: + • "id" Channel id. + • "argv" (optional) Job arguments list. + • "stream" Stream underlying the channel. + • "stdio" stdin and stdout of this Nvim instance + • "stderr" stderr of this Nvim instance + • "socket" TCP/IP socket or named pipe + • "job" Job with communication over its stdio. + + • "mode" How data received on the channel is interpreted. + • "bytes" Send and receive raw bytes. + • "terminal" |terminal| instance interprets ASCII sequences. + • "rpc" |RPC| communication on the channel is active. + + • "pty" (optional) Name of pseudoterminal. On a POSIX system this is a + device path like "/dev/pts/1". If the name is unknown, the key will + still be present if a pty is used (e.g. for conpty on Windows). + • "buffer" (optional) Buffer with connected |terminal| instance. + • "client" (optional) Info about the peer (client on the other end of + the RPC channel), if provided by it via |nvim_set_client_info()|. nvim_get_color_by_name({name}) *nvim_get_color_by_name()* - Returns the 24-bit RGB value of a |nvim_get_color_map()| color - name or "#rrggbb" hexadecimal string. + Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or + "#rrggbb" hexadecimal string. - Example: > - :echo nvim_get_color_by_name("Pink") - :echo nvim_get_color_by_name("#cbcbcb") + Example: > + :echo nvim_get_color_by_name("Pink") + :echo nvim_get_color_by_name("#cbcbcb") < - Parameters: ~ - {name} Color name or "#rrggbb" string + Parameters: ~ + {name} Color name or "#rrggbb" string - Return: ~ - 24-bit RGB value, or -1 for invalid argument. + Return: ~ + 24-bit RGB value, or -1 for invalid argument. nvim_get_color_map() *nvim_get_color_map()* - Returns a map of color names and RGB values. + 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). + Keys are color names (e.g. "Aqua") and values are 24-bit RGB color values + (e.g. 65535). - Return: ~ - Map of color names and RGB values. + Return: ~ + Map of color names and RGB values. nvim_get_context({*opts}) *nvim_get_context()* - Gets a map of the current editor state. + Gets a map of the current editor state. - Parameters: ~ - {opts} Optional parameters. - • types: List of |context-types| ("regs", "jumps", - "bufs", "gvars", …) to gather, or empty for - "all". + Parameters: ~ + {opts} Optional parameters. + • types: List of |context-types| ("regs", "jumps", "bufs", + "gvars", …) to gather, or empty for "all". - Return: ~ - map of global |context|. + Return: ~ + map of global |context|. nvim_get_current_buf() *nvim_get_current_buf()* - Gets the current buffer. + Gets the current buffer. - Return: ~ - Buffer handle + Return: ~ + Buffer handle nvim_get_current_line() *nvim_get_current_line()* - Gets the current line. + Gets the current line. - Return: ~ - Current line string + Return: ~ + Current line string nvim_get_current_tabpage() *nvim_get_current_tabpage()* - Gets the current tabpage. + Gets the current tabpage. - Return: ~ - Tabpage handle + Return: ~ + Tabpage handle nvim_get_current_win() *nvim_get_current_win()* - Gets the current window. + Gets the current window. - Return: ~ - Window handle + Return: ~ + Window handle nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()* - Gets a highlight definition by id. |hlID()| + Gets a highlight definition by id. |hlID()| - Parameters: ~ - {hl_id} Highlight id as returned by |hlID()| - {rgb} Export RGB colors + Parameters: ~ + {hl_id} Highlight id as returned by |hlID()| + {rgb} Export RGB colors - Return: ~ - Highlight definition map + Return: ~ + Highlight definition map - See also: ~ - nvim_get_hl_by_name + See also: ~ + nvim_get_hl_by_name nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()* - Gets a highlight definition by name. + Gets a highlight definition by name. - Parameters: ~ - {name} Highlight group name - {rgb} Export RGB colors + Parameters: ~ + {name} Highlight group name + {rgb} Export RGB colors - Return: ~ - Highlight definition map + Return: ~ + Highlight definition map - See also: ~ - nvim_get_hl_by_id + See also: ~ + nvim_get_hl_by_id nvim_get_hl_id_by_name({name}) *nvim_get_hl_id_by_name()* - Gets a highlight group by name + Gets a highlight group by name - similar to |hlID()|, but allocates a new ID if not present. + similar to |hlID()|, but allocates a new ID if not present. nvim_get_keymap({mode}) *nvim_get_keymap()* - Gets a list of global (non-buffer-local) |mapping| - definitions. + Gets a list of global (non-buffer-local) |mapping| definitions. - Parameters: ~ - {mode} Mode short-name ("n", "i", "v", ...) + Parameters: ~ + {mode} Mode short-name ("n", "i", "v", ...) - Return: ~ - Array of |maparg()|-like dictionaries describing mappings. - The "buffer" key is always zero. + Return: ~ + Array of |maparg()|-like dictionaries describing mappings. The + "buffer" key is always zero. nvim_get_mark({name}, {opts}) *nvim_get_mark()* - Return a tuple (row, col, buffer, buffername) representing the - position of the uppercase/file named mark. See |mark-motions|. + Return a tuple (row, col, buffer, buffername) representing the position of + the uppercase/file named mark. See |mark-motions|. - Marks are (1,0)-indexed. |api-indexing| + Marks are (1,0)-indexed. |api-indexing| - Note: - fails with error if a lowercase or buffer local named mark - is used. + Note: + fails with error if a lowercase or buffer local named mark is used. - Parameters: ~ - {name} Mark name - {opts} Optional parameters. Reserved for future use. + Parameters: ~ + {name} Mark name + {opts} Optional parameters. Reserved for future use. - Return: ~ - 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if - the mark is not set. + Return: ~ + 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is + not set. - See also: ~ - |nvim_buf_set_mark()| - |nvim_del_mark()| + See also: ~ + |nvim_buf_set_mark()| + |nvim_del_mark()| nvim_get_mode() *nvim_get_mode()* - Gets the current mode. |mode()| "blocking" is true if Nvim is - waiting for input. + Gets the current mode. |mode()| "blocking" is true if Nvim is waiting for + input. - Return: ~ - Dictionary { "mode": String, "blocking": Boolean } + Return: ~ + Dictionary { "mode": String, "blocking": Boolean } - Attributes: ~ - |api-fast| + Attributes: ~ + |api-fast| nvim_get_proc({pid}) *nvim_get_proc()* - Gets info describing process `pid`. + Gets info describing process `pid`. - Return: ~ - Map of process properties, or NIL if process not found. + Return: ~ + Map of process properties, or NIL if process not found. nvim_get_proc_children({pid}) *nvim_get_proc_children()* - Gets the immediate children of process `pid`. + Gets the immediate children of process `pid`. - Return: ~ - Array of child process ids, empty if process not found. + Return: ~ + Array of child process ids, empty if process not found. nvim_get_runtime_file({name}, {all}) *nvim_get_runtime_file()* - Find files in runtime directories + 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. + '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. + It is not an error to not find any files. An empty array is returned then. - Attributes: ~ - |api-fast| + Attributes: ~ + |api-fast| - Parameters: ~ - {name} pattern of files to search for - {all} whether to return all matches or only the first + Parameters: ~ + {name} pattern of files to search for + {all} whether to return all matches or only the first - Return: ~ - list of absolute paths to the found files + Return: ~ + list of absolute paths to the found files nvim_get_var({name}) *nvim_get_var()* - Gets a global (g:) variable. + Gets a global (g:) variable. - Parameters: ~ - {name} Variable name + Parameters: ~ + {name} Variable name - Return: ~ - Variable value + Return: ~ + Variable value nvim_get_vvar({name}) *nvim_get_vvar()* - Gets a v: variable. + Gets a v: variable. - Parameters: ~ - {name} Variable name + Parameters: ~ + {name} Variable name - Return: ~ - Variable value + Return: ~ + Variable value nvim_input({keys}) *nvim_input()* - 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). + 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. + On execution error: does not fail, but updates v:errmsg. - Note: - |keycodes| like <CR> are translated, so "<" is special. To - input a literal "<", send <LT>. + Note: + |keycodes| like <CR> are translated, so "<" is special. To input a + literal "<", send <LT>. - Note: - For mouse events use |nvim_input_mouse()|. The pseudokey - form "<LeftMouse><col,row>" is deprecated since - |api-level| 6. + Note: + For mouse events use |nvim_input_mouse()|. The pseudokey form + "<LeftMouse><col,row>" is deprecated since |api-level| 6. - Attributes: ~ - |api-fast| + Attributes: ~ + |api-fast| - Parameters: ~ - {keys} to be typed + Parameters: ~ + {keys} to be typed - Return: ~ - Number of bytes actually written (can be fewer than - requested if the buffer becomes full). + Return: ~ + Number of bytes actually written (can be fewer than requested if the + buffer becomes full). *nvim_input_mouse()* nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) - 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. - - Note: - Currently this doesn't support "scripting" multiple mouse - events by calling it multiple times in a loop: the - intermediate mouse positions will be ignored. It should be - used to implement real-time mouse input in a GUI. The - deprecated pseudokey form ("<LeftMouse><col,row>") of - |nvim_input()| has the same limitation. - - Attributes: ~ - |api-fast| - - Parameters: ~ - {button} Mouse button: one of "left", "right", - "middle", "wheel". - {action} For ordinary buttons, one of "press", "drag", - "release". For the wheel, one of "up", "down", - "left", "right". - {modifier} 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" can all - be used to specify Ctrl+Alt+click. - {grid} Grid number if the client uses |ui-multigrid|, - else 0. - {row} Mouse row-position (zero-based, like redraw - events) - {col} Mouse column-position (zero-based, like redraw - events) + 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. + + Note: + Currently this doesn't support "scripting" multiple mouse events by + calling it multiple times in a loop: the intermediate mouse positions + will be ignored. It should be used to implement real-time mouse input + in a GUI. The deprecated pseudokey form ("<LeftMouse><col,row>") of + |nvim_input()| has the same limitation. + + Attributes: ~ + |api-fast| + + Parameters: ~ + {button} Mouse button: one of "left", "right", "middle", "wheel". + {action} For ordinary buttons, one of "press", "drag", "release". + For the wheel, one of "up", "down", "left", "right". + {modifier} 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" + can all be used to specify Ctrl+Alt+click. + {grid} Grid number if the client uses |ui-multigrid|, else 0. + {row} Mouse row-position (zero-based, like redraw events) + {col} Mouse column-position (zero-based, like redraw events) nvim_list_bufs() *nvim_list_bufs()* - Gets the current list of buffer handles + 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. + Includes unlisted (unloaded/deleted) buffers, like `:ls!`. Use + |nvim_buf_is_loaded()| to check if a buffer is loaded. - Return: ~ - List of buffer handles + Return: ~ + List of buffer handles nvim_list_chans() *nvim_list_chans()* - Get information about all open channels. + Get information about all open channels. - Return: ~ - Array of Dictionaries, each describing a channel with the - format specified at |nvim_get_chan_info()|. + Return: ~ + Array of Dictionaries, each describing a channel with the format + specified at |nvim_get_chan_info()|. nvim_list_runtime_paths() *nvim_list_runtime_paths()* - Gets the paths contained in 'runtimepath'. + Gets the paths contained in 'runtimepath'. - Return: ~ - List of paths + Return: ~ + List of paths nvim_list_tabpages() *nvim_list_tabpages()* - Gets the current list of tabpage handles. + Gets the current list of tabpage handles. - Return: ~ - List of tabpage handles + Return: ~ + List of tabpage handles nvim_list_uis() *nvim_list_uis()* - Gets a list of dictionaries representing attached UIs. + Gets a list of dictionaries representing attached UIs. - Return: ~ - Array of UI dictionaries, each with these keys: - • "height" Requested height of the UI - • "width" Requested width of the UI - • "rgb" true if the UI uses RGB colors (false implies - |cterm-colors|) - • "ext_..." Requested UI extensions, see |ui-option| - • "chan" Channel id of remote UI (not present for TUI) + Return: ~ + Array of UI dictionaries, each with these keys: + • "height" Requested height of the UI + • "width" Requested width of the UI + • "rgb" true if the UI uses RGB colors (false implies |cterm-colors|) + • "ext_..." Requested UI extensions, see |ui-option| + • "chan" Channel id of remote UI (not present for TUI) nvim_list_wins() *nvim_list_wins()* - Gets the current list of window handles. + Gets the current list of window handles. - Return: ~ - List of window handles + Return: ~ + List of window handles nvim_load_context({dict}) *nvim_load_context()* - Sets the current editor state from the given |context| map. + Sets the current editor state from the given |context| map. - Parameters: ~ - {dict} |Context| map. + Parameters: ~ + {dict} |Context| map. nvim_notify({msg}, {log_level}, {opts}) *nvim_notify()* - Notify the user with a message + 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. + Relays the call to vim.notify . By default forwards your message in the + echo area but can be overridden to trigger desktop notifications. - Parameters: ~ - {msg} Message to display to the user - {log_level} The log level - {opts} Reserved for future use. + Parameters: ~ + {msg} Message to display to the user + {log_level} The log level + {opts} Reserved for future use. nvim_open_term({buffer}, {opts}) *nvim_open_term()* - 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()|, then display it using - |nvim_open_win()|, and then call this function. Then - |nvim_chan_send()| can be called immediately to process - sequences in a virtual terminal having the intended size. - - Parameters: ~ - {buffer} the buffer to use (expected to be empty) - {opts} 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] - - Return: ~ - Channel id, or 0 on error + 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()|, + then display it using |nvim_open_win()|, and then call this function. Then + |nvim_chan_send()| can be called immediately to process sequences in a + virtual terminal having the intended size. + + Parameters: ~ + {buffer} the buffer to use (expected to be empty) + {opts} 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] + + Return: ~ + Channel id, or 0 on error nvim_out_write({str}) *nvim_out_write()* - Writes a message to the Vim output buffer. Does not append - "\n", the message is buffered (won't display) until a linefeed - is written. + Writes a message to the Vim output buffer. Does not append "\n", the + message is buffered (won't display) until a linefeed is written. - Parameters: ~ - {str} Message + Parameters: ~ + {str} Message nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* - Pastes at cursor, in any mode. + 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"). + 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 the next paste is - initiated (phase 1 or -1). + 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 + the next paste is initiated (phase 1 or -1). - Attributes: ~ - not allowed when |textlock| is active + Attributes: ~ + not allowed when |textlock| is active - Parameters: ~ - {data} Multiline input. May be binary (containing NUL - bytes). - {crlf} Also break lines at CR and CRLF. - {phase} -1: paste in a single call (i.e. without - streaming). To "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) + Parameters: ~ + {data} Multiline input. May be binary (containing NUL bytes). + {crlf} Also break lines at CR and CRLF. + {phase} -1: paste in a single call (i.e. without streaming). To + "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) - Return: ~ + Return: ~ - • true: Client may continue pasting. - • false: Client must cancel the paste. + • true: Client may continue pasting. + • false: Client must cancel the paste. nvim_put({lines}, {type}, {after}, {follow}) *nvim_put()* - Puts text at cursor, in any mode. - - Compare |:put| and |p| which are always linewise. - - Attributes: ~ - not allowed when |textlock| is active - - Parameters: ~ - {lines} |readfile()|-style list of lines. - |channel-lines| - {type} 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()| - {after} If true insert after cursor (like |p|), or - before (like |P|). - {follow} If true place cursor at end of inserted text. + Puts text at cursor, in any mode. + + Compare |:put| and |p| which are always linewise. + + Attributes: ~ + not allowed when |textlock| is active + + Parameters: ~ + {lines} |readfile()|-style list of lines. |channel-lines| + {type} 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()| + {after} If true insert after cursor (like |p|), or before (like + |P|). + {follow} If true place cursor at end of inserted text. *nvim_replace_termcodes()* nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) - Replaces terminal codes and |keycodes| (<CR>, <Esc>, ...) in a - string with the internal representation. + Replaces terminal codes and |keycodes| (<CR>, <Esc>, ...) in a string with + the internal representation. - Parameters: ~ - {str} String to be converted. - {from_part} Legacy Vim parameter. Usually true. - {do_lt} Also translate <lt>. Ignored if `special` is - false. - {special} Replace |keycodes|, e.g. <CR> becomes a "\r" - char. + Parameters: ~ + {str} String to be converted. + {from_part} Legacy Vim parameter. Usually true. + {do_lt} Also translate <lt>. Ignored if `special` is false. + {special} Replace |keycodes|, e.g. <CR> becomes a "\r" char. - See also: ~ - replace_termcodes - cpoptions + See also: ~ + replace_termcodes + cpoptions *nvim_select_popupmenu_item()* nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) - Selects an item in the completion popupmenu. - - If |ins-completion| is not active this API call is silently - ignored. Useful for an external UI using |ui-popupmenu| to - control the popupmenu with the mouse. Can also be used in a - mapping; use <cmd> |:map-cmd| to ensure the mapping doesn't - end completion mode. - - Parameters: ~ - {item} Index (zero-based) of the item to select. Value - of -1 selects nothing and restores the original - text. - {insert} Whether the selection should be inserted in the - buffer. - {finish} Finish the completion and dismiss the popupmenu. - Implies `insert`. - {opts} Optional parameters. Reserved for future use. + Selects an item in the completion popupmenu. + + If |ins-completion| is not active this API call is silently ignored. + Useful for an external UI using |ui-popupmenu| to control the popupmenu + with the mouse. Can also be used in a mapping; use <cmd> |:map-cmd| to + ensure the mapping doesn't end completion mode. + + Parameters: ~ + {item} Index (zero-based) of the item to select. Value of -1 + selects nothing and restores the original text. + {insert} Whether the selection should be inserted in the buffer. + {finish} Finish the completion and dismiss the popupmenu. Implies + `insert`. + {opts} Optional parameters. Reserved for future use. *nvim_set_client_info()* nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) - Self-identifies the client. - - The client/plugin/application should call this after - connecting, to provide hints about its identity and purpose, - for debugging and orchestration. - - Can be called more than once; the caller should merge old info - if appropriate. Example: library first identifies the channel, - then a plugin using that library later identifies itself. - - Note: - "Something is better than nothing". You don't need to - include all the fields. - - Attributes: ~ - |RPC| only - - Parameters: ~ - {name} Short name for the connected client - {version} Dictionary describing the version, with - these (optional) keys: - • "major" major version (defaults to 0 if - not set, for no release yet) - • "minor" minor version - • "patch" patch number - • "prerelease" string describing a - prerelease, like "dev" or "beta1" - • "commit" hash or similar identifier of - commit - {type} Must be one of the following values. Client - libraries should default to "remote" unless - overridden by the user. - • "remote" remote client connected to Nvim. - • "ui" gui frontend - • "embedder" application using Nvim as a - component (for example, IDE/editor - implementing a vim mode). - • "host" plugin host, typically started by - nvim - • "plugin" single plugin, started by nvim - {methods} Builtin methods in the client. For a host, - this does not include plugin methods which - will be discovered later. The key should be - the method name, the values are dicts with - these (optional) keys (more keys may be - added in future versions of Nvim, thus - unknown keys are ignored. Clients must only - use keys defined in this or later versions - of Nvim): - • "async" if true, send as a notification. - If false or unspecified, use a blocking - request - • "nargs" Number of arguments. Could be a - single integer or an array of two - integers, minimum and maximum inclusive. - {attributes} Arbitrary string:string map of informal - client properties. Suggested keys: - • "website": Client homepage URL (e.g. - GitHub repository) - • "license": License description ("Apache - 2", "GPLv3", "MIT", …) - • "logo": URI or path to image, preferably - small logo or icon. .png or .svg format is - preferred. + Self-identifies the client. + + The client/plugin/application should call this after connecting, to + provide hints about its identity and purpose, for debugging and + orchestration. + + Can be called more than once; the caller should merge old info if + appropriate. Example: library first identifies the channel, then a plugin + using that library later identifies itself. + + Note: + "Something is better than nothing". You don't need to include all the + fields. + + Attributes: ~ + |RPC| only + + Parameters: ~ + {name} Short name for the connected client + {version} Dictionary describing the version, with these (optional) + keys: + • "major" major version (defaults to 0 if not set, for + no release yet) + • "minor" minor version + • "patch" patch number + • "prerelease" string describing a prerelease, like + "dev" or "beta1" + • "commit" hash or similar identifier of commit + {type} Must be one of the following values. Client libraries + should default to "remote" unless overridden by the + user. + • "remote" remote client connected to Nvim. + • "ui" gui frontend + • "embedder" application using Nvim as a component (for + example, IDE/editor implementing a vim mode). + • "host" plugin host, typically started by nvim + • "plugin" single plugin, started by nvim + {methods} Builtin methods in the client. For a host, this does not + include plugin methods which will be discovered later. + The key should be the method name, the values are dicts + with these (optional) keys (more keys may be added in + future versions of Nvim, thus unknown keys are ignored. + Clients must only use keys defined in this or later + versions of Nvim): + • "async" if true, send as a notification. If false or + unspecified, use a blocking request + • "nargs" Number of arguments. Could be a single integer + or an array of two integers, minimum and maximum + inclusive. + {attributes} Arbitrary string:string map of informal client + properties. Suggested keys: + • "website": Client homepage URL (e.g. GitHub + repository) + • "license": License description ("Apache 2", "GPLv3", + "MIT", …) + • "logo": URI or path to image, preferably small logo or + icon. .png or .svg format is preferred. nvim_set_current_buf({buffer}) *nvim_set_current_buf()* - Sets the current buffer. + Sets the current buffer. - Attributes: ~ - not allowed when |textlock| is active + Attributes: ~ + not allowed when |textlock| is active - Parameters: ~ - {buffer} Buffer handle + Parameters: ~ + {buffer} Buffer handle nvim_set_current_dir({dir}) *nvim_set_current_dir()* - Changes the global working directory. + Changes the global working directory. - Parameters: ~ - {dir} Directory path + Parameters: ~ + {dir} Directory path nvim_set_current_line({line}) *nvim_set_current_line()* - Sets the current line. + Sets the current line. - Attributes: ~ - not allowed when |textlock| is active + Attributes: ~ + not allowed when |textlock| is active - Parameters: ~ - {line} Line contents + Parameters: ~ + {line} Line contents nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* - Sets the current tabpage. + Sets the current tabpage. - Attributes: ~ - not allowed when |textlock| is active + Attributes: ~ + not allowed when |textlock| is active - Parameters: ~ - {tabpage} Tabpage handle + Parameters: ~ + {tabpage} Tabpage handle nvim_set_current_win({window}) *nvim_set_current_win()* - Sets the current window. + Sets the current window. - Attributes: ~ - not allowed when |textlock| is active + Attributes: ~ + not allowed when |textlock| is active - Parameters: ~ - {window} Window handle + Parameters: ~ + {window} Window handle nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* - Sets a highlight group. - - Note: - Unlike the `:highlight` command which can update a - highlight group, this function completely replaces the - definition. For example: `nvim_set_hl(0, 'Visual', {})` - will clear the highlight group 'Visual'. - - Note: - The fg and bg keys also accept the string values `"fg"` or - `"bg"` which act as aliases to the corresponding - foreground and background values of the Normal group. If - the Normal group has not been defined, using these values - results in an error. - - Parameters: ~ - {ns_id} Namespace id for this highlight - |nvim_create_namespace()|. Use 0 to set a - highlight group globally |:highlight|. - {name} Highlight group name, e.g. "ErrorMsg" - {val} 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 - |highlight-ctermfg| - • ctermbg: Sets background of cterm color - |highlight-ctermbg| - • cterm: cterm attribute map, like - |highlight-args|. If not set, cterm attributes - will match those from the attribute map - documented above. + Sets a highlight group. + + Note: + Unlike the `:highlight` command which can update a highlight group, + this function completely replaces the definition. For example: + `nvim_set_hl(0, 'Visual', {})` will clear the highlight group + 'Visual'. + + Note: + The fg and bg keys also accept the string values `"fg"` or `"bg"` + which act as aliases to the corresponding foreground and background + values of the Normal group. If the Normal group has not been defined, + using these values results in an error. + + Parameters: ~ + {ns_id} Namespace id for this highlight |nvim_create_namespace()|. + Use 0 to set a highlight group globally |:highlight|. + {name} Highlight group name, e.g. "ErrorMsg" + {val} 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 |highlight-ctermfg| + • ctermbg: Sets background of cterm color |highlight-ctermbg| + • cterm: cterm attribute map, like |highlight-args|. If not + set, cterm attributes will match those from the attribute + map documented above. + +nvim_set_hl_ns({ns_id}) *nvim_set_hl_ns()* + Set active namespace for highlights. This can be set for a single window, + see |nvim_win_set_hl_ns|. + + Parameters: ~ + {ns_id} the namespace to use + +nvim_set_hl_ns_fast({ns_id}) *nvim_set_hl_ns_fast()* + Set active namespace for highlights 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. + + Attributes: ~ + |api-fast| + + Parameters: ~ + {ns_id} the namespace to activate nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* - Sets a global |mapping| for the given mode. + Sets a global |mapping| for the given mode. - To set a buffer-local mapping, use |nvim_buf_set_keymap()|. + 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. + Unlike |:map|, leading/trailing whitespace is accepted as part of the + {lhs} or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual. - Example: > - call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true}) + Example: > + call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true}) < - is equivalent to: > - nmap <nowait> <Space><NL> <Nop> + is equivalent to: > + nmap <nowait> <Space><NL> <Nop> < - Parameters: ~ - {mode} Mode short-name (map command prefix: "n", "i", - "v", "x", …) or "!" for |:map!|, or empty string - for |:map|. - {lhs} Left-hand-side |{lhs}| of the mapping. - {rhs} Right-hand-side |{rhs}| of the mapping. - {opts} Optional parameters map: keys are - |:map-arguments|, values are booleans (default - false). Accepts all |:map-arguments| as keys - excluding |<buffer>| but including |noremap| and - "desc". Unknown key is an error. "desc" can be - used to give a description to the mapping. When - called from Lua, also accepts a "callback" key - that takes a Lua function to call when the mapping - is executed. When "expr" is true, - "replace_keycodes" (boolean) can be used to - replace keycodes in the resulting string (see - |nvim_replace_termcodes()|), and a Lua callback - returning `nil` is equivalent to returning an - empty string. + Parameters: ~ + {mode} Mode short-name (map command prefix: "n", "i", "v", "x", …) or + "!" for |:map!|, or empty string for |:map|. + {lhs} Left-hand-side |{lhs}| of the mapping. + {rhs} Right-hand-side |{rhs}| of the mapping. + {opts} Optional parameters map: keys are |:map-arguments|, values are + booleans (default false). Accepts all |:map-arguments| as keys + excluding |<buffer>| but including |noremap| and "desc". + Unknown key is an error. "desc" can be used to give a + description to the mapping. When called from Lua, also accepts + a "callback" key that takes a Lua function to call when the + mapping is executed. When "expr" is true, "replace_keycodes" + (boolean) can be used to replace keycodes in the resulting + string (see |nvim_replace_termcodes()|), and a Lua callback + returning `nil` is equivalent to returning an empty string. nvim_set_var({name}, {value}) *nvim_set_var()* - Sets a global (g:) variable. + Sets a global (g:) variable. - Parameters: ~ - {name} Variable name - {value} Variable value + Parameters: ~ + {name} Variable name + {value} Variable value nvim_set_vvar({name}, {value}) *nvim_set_vvar()* - Sets a v: variable, if it is not readonly. + Sets a v: variable, if it is not readonly. - Parameters: ~ - {name} Variable name - {value} Variable value + Parameters: ~ + {name} Variable name + {value} Variable value nvim_strwidth({text}) *nvim_strwidth()* - Calculates the number of display cells occupied by `text`. - Control characters including <Tab> count as one cell. + Calculates the number of display cells occupied by `text`. Control + characters including <Tab> count as one cell. - Parameters: ~ - {text} Some text + Parameters: ~ + {text} Some text - Return: ~ - Number of cells + Return: ~ + Number of cells nvim_subscribe({event}) *nvim_subscribe()* - Subscribes to event broadcasts. + Subscribes to event broadcasts. - Attributes: ~ - |RPC| only + Attributes: ~ + |RPC| only - Parameters: ~ - {event} Event type string + Parameters: ~ + {event} Event type string nvim_unsubscribe({event}) *nvim_unsubscribe()* - Unsubscribes to event broadcasts. + Unsubscribes to event broadcasts. - Attributes: ~ - |RPC| only + Attributes: ~ + |RPC| only - Parameters: ~ - {event} Event type string + Parameters: ~ + {event} Event type string ============================================================================== @@ -1563,178 +1500,157 @@ Vimscript Functions *api-vimscript* *nvim_call_dict_function()* nvim_call_dict_function({dict}, {fn}, {args}) - Calls a VimL |Dictionary-function| with the given arguments. + Calls a VimL |Dictionary-function| with the given arguments. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with VimL error, updates v:errmsg. - Parameters: ~ - {dict} Dictionary, or String evaluating to a VimL |self| - dict - {fn} Name of the function defined on the VimL dict - {args} Function arguments packed in an Array + Parameters: ~ + {dict} Dictionary, or String evaluating to a VimL |self| dict + {fn} Name of the function defined on the VimL dict + {args} Function arguments packed in an Array - Return: ~ - Result of the function call + Return: ~ + Result of the function call nvim_call_function({fn}, {args}) *nvim_call_function()* - Calls a VimL function with the given arguments. + Calls a VimL function with the given arguments. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with VimL error, updates v:errmsg. - Parameters: ~ - {fn} Function to call - {args} Function arguments packed in an Array + Parameters: ~ + {fn} Function to call + {args} Function arguments packed in an Array - Return: ~ - Result of the function call + Return: ~ + Result of the function call nvim_command({command}) *nvim_command()* - Executes an Ex command. + Executes an Ex command. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with VimL error, updates v:errmsg. - Prefer using |nvim_cmd()| or |nvim_exec()| over this. To - evaluate multiple lines of Vim script or an Ex command - directly, use |nvim_exec()|. To construct an Ex command using - a structured format and then execute it, use |nvim_cmd()|. To - modify an Ex command before evaluating it, use - |nvim_parse_cmd()| in conjunction with |nvim_cmd()|. + Prefer using |nvim_cmd()| or |nvim_exec()| over this. To evaluate multiple + lines of Vim script or an Ex command directly, use |nvim_exec()|. To + construct an Ex command using a structured format and then execute it, use + |nvim_cmd()|. To modify an Ex command before evaluating it, use + |nvim_parse_cmd()| in conjunction with |nvim_cmd()|. - Parameters: ~ - {command} Ex command string + Parameters: ~ + {command} Ex command string nvim_eval({expr}) *nvim_eval()* - Evaluates a VimL |expression|. Dictionaries and Lists are - recursively expanded. + Evaluates a VimL |expression|. Dictionaries and Lists are recursively + expanded. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with VimL error, updates v:errmsg. - Parameters: ~ - {expr} VimL expression string + Parameters: ~ + {expr} VimL expression string - Return: ~ - Evaluation result or expanded object + Return: ~ + Evaluation result or expanded object nvim_exec({src}, {output}) *nvim_exec()* - Executes Vimscript (multiline block of Ex commands), like - anonymous |:source|. + Executes Vimscript (multiline block of Ex commands), like anonymous + |:source|. - Unlike |nvim_command()| this function supports heredocs, - script-scope (s:), etc. + Unlike |nvim_command()| this function supports heredocs, script-scope + (s:), etc. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with VimL error, updates v:errmsg. - Parameters: ~ - {src} Vimscript code - {output} Capture and return all (non-error, non-shell - |:!|) output + Parameters: ~ + {src} Vimscript code + {output} Capture and return all (non-error, non-shell |:!|) output - Return: ~ - Output (non-error, non-shell |:!|) if `output` is true, - else empty string. + Return: ~ + Output (non-error, non-shell |:!|) if `output` is true, else empty + string. - See also: ~ - |execute()| - |nvim_command()| - |nvim_cmd()| + See also: ~ + |execute()| + |nvim_command()| + |nvim_cmd()| *nvim_parse_expression()* nvim_parse_expression({expr}, {flags}, {highlight}) - Parse a VimL expression. - - Attributes: ~ - |api-fast| - - Parameters: ~ - {expr} Expression to parse. Always treated as a - single line. - {flags} 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". - {highlight} 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 - highlighted region and represent line, - starting column and ending column (latter - exclusive: one should highlight region - [start_col, end_col)). - - Return: ~ - - • AST: top-level dictionary with these keys: - • "error": Dictionary with error, present only if parser - saw some error. Contains the following keys: - • "message": String, error message in printf format, - translated. Must contain exactly one "%.*s". - • "arg": String, error message argument. - - • "len": Amount of bytes successfully parsed. With flags - equal to "" that should be equal to the length of expr - string. (“Successfully parsed” here means - “participated in AST creation”, not “till the first - error”.) - • "ast": AST, either nil or a dictionary with these - keys: - • "type": node type, one of the value names from - ExprASTNodeType stringified without "kExprNode" - prefix. - • "start": a pair [line, column] describing where node - is "started" where "line" is always 0 (will not be 0 - if you will be using nvim_parse_viml() on e.g. - ":let", but that is not present yet). Both elements - are Integers. - • "len": “length” of the node. This and "start" are - there for debugging purposes primary (debugging - parser and providing debug information). - • "children": a list of nodes described in top/"ast". - There always is zero, one or two children, key will - not be present if node has no children. Maximum - number of children may be found in node_maxchildren - array. - - • Local values (present only for certain nodes): - • "scope": a single Integer, specifies scope for - "Option" and "PlainIdentifier" nodes. For "Option" it - is one of ExprOptScope values, for "PlainIdentifier" - it is one of ExprVarScope values. - • "ident": identifier (without scope, if any), present - for "Option", "PlainIdentifier", "PlainKey" and - "Environment" nodes. - • "name": Integer, register name (one character) or -1. - Only present for "Register" nodes. - • "cmp_type": String, comparison type, one of the value - names from ExprComparisonType, stringified without - "kExprCmp" prefix. Only present for "Comparison" - nodes. - • "ccs_strategy": String, case comparison strategy, one - of the value names from ExprCaseCompareStrategy, - stringified without "kCCStrategy" prefix. Only present - for "Comparison" nodes. - • "augmentation": String, augmentation type for - "Assignment" nodes. Is either an empty string, "Add", - "Subtract" or "Concat" for "=", "+=", "-=" or ".=" - respectively. - • "invert": Boolean, true if result of comparison needs - to be inverted. Only present for "Comparison" nodes. - • "ivalue": Integer, integer value for "Integer" nodes. - • "fvalue": Float, floating-point value for "Float" - nodes. - • "svalue": String, value for "SingleQuotedString" and - "DoubleQuotedString" nodes. + Parse a VimL expression. + + Attributes: ~ + |api-fast| + + Parameters: ~ + {expr} Expression to parse. Always treated as a single line. + {flags} 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". + {highlight} 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 + highlighted region and represent line, starting column + and ending column (latter exclusive: one should highlight + region [start_col, end_col)). + + Return: ~ + + • AST: top-level dictionary with these keys: + • "error": Dictionary with error, present only if parser saw some + error. Contains the following keys: + • "message": String, error message in printf format, translated. + Must contain exactly one "%.*s". + • "arg": String, error message argument. + + • "len": Amount of bytes successfully parsed. With flags equal to "" + that should be equal to the length of expr string. (“Successfully + parsed” here means “participated in AST creation”, not “till the + first error”.) + • "ast": AST, either nil or a dictionary with these keys: + • "type": node type, one of the value names from ExprASTNodeType + stringified without "kExprNode" prefix. + • "start": a pair [line, column] describing where node is + "started" where "line" is always 0 (will not be 0 if you will be + using nvim_parse_viml() on e.g. ":let", but that is not present + yet). Both elements are Integers. + • "len": “length” of the node. This and "start" are there for + debugging purposes primary (debugging parser and providing debug + information). + • "children": a list of nodes described in top/"ast". There always + is zero, one or two children, key will not be present if node + has no children. Maximum number of children may be found in + node_maxchildren array. + + • Local values (present only for certain nodes): + • "scope": a single Integer, specifies scope for "Option" and + "PlainIdentifier" nodes. For "Option" it is one of ExprOptScope + values, for "PlainIdentifier" it is one of ExprVarScope values. + • "ident": identifier (without scope, if any), present for "Option", + "PlainIdentifier", "PlainKey" and "Environment" nodes. + • "name": Integer, register name (one character) or -1. Only present + for "Register" nodes. + • "cmp_type": String, comparison type, one of the value names from + ExprComparisonType, stringified without "kExprCmp" prefix. Only + present for "Comparison" nodes. + • "ccs_strategy": String, case comparison strategy, one of the value + names from ExprCaseCompareStrategy, stringified without + "kCCStrategy" prefix. Only present for "Comparison" nodes. + • "augmentation": String, augmentation type for "Assignment" nodes. + Is either an empty string, "Add", "Subtract" or "Concat" for "=", + "+=", "-=" or ".=" respectively. + • "invert": Boolean, true if result of comparison needs to be + inverted. Only present for "Comparison" nodes. + • "ivalue": Integer, integer value for "Integer" nodes. + • "fvalue": Float, floating-point value for "Float" nodes. + • "svalue": String, value for "SingleQuotedString" and + "DoubleQuotedString" nodes. ============================================================================== @@ -1742,351 +1658,328 @@ Command Functions *api-command* *nvim_buf_create_user_command()* nvim_buf_create_user_command({buffer}, {name}, {command}, {*opts}) - Create a new user command |user-commands| in the given buffer. + Create a new user command |user-commands| in the given buffer. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer. + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer. - See also: ~ - nvim_create_user_command + See also: ~ + nvim_create_user_command *nvim_buf_del_user_command()* nvim_buf_del_user_command({buffer}, {name}) - Delete a buffer-local user-defined command. + 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. + Only commands created with |:command-buffer| or + |nvim_buf_create_user_command()| can be deleted with this function. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer. - {name} Name of the command to delete. + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer. + {name} Name of the command to delete. nvim_buf_get_commands({buffer}, {*opts}) *nvim_buf_get_commands()* - Gets a map of buffer-local |user-commands|. + Gets a map of buffer-local |user-commands|. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {opts} Optional parameters. Currently not used. + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {opts} Optional parameters. Currently not used. - Return: ~ - Map of maps describing commands. + Return: ~ + Map of maps describing commands. nvim_cmd({*cmd}, {*opts}) *nvim_cmd()* - 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. - - On execution error: fails with VimL error, updates v:errmsg. - - Parameters: ~ - {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. - {opts} Optional parameters. - • output: (boolean, default false) Whether to - return command output. - - Return: ~ - Command output (non-error, non-shell |:!|) if `output` is - true, else empty string. - - See also: ~ - |nvim_exec()| - |nvim_command()| + 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. + + On execution error: fails with VimL error, updates v:errmsg. + + Parameters: ~ + {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. + {opts} Optional parameters. + • output: (boolean, default false) Whether to return command + output. + + Return: ~ + Command output (non-error, non-shell |:!|) if `output` is true, else + empty string. + + See also: ~ + |nvim_exec()| + |nvim_command()| *nvim_create_user_command()* nvim_create_user_command({name}, {command}, {*opts}) - Create a new user command |user-commands| + Create a new user command |user-commands| - {name} is the name of the new command. The name must begin - with an uppercase letter. + {name} is the name of the new command. The name must begin with an + uppercase letter. - {command} is the replacement text or Lua function to execute. + {command} is the replacement text or Lua function to execute. - Example: > - :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {}) - :SayHello - Hello world! + Example: > + :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {}) + :SayHello + Hello world! < - Parameters: ~ - {name} Name of the new user command. Must begin with - an uppercase letter. - {command} 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: - • args: (string) The args passed to the - command, if any |<args>| - • fargs: (table) The args split by unescaped - whitespace (when more than one argument is - allowed), if any |<f-args>| - • bang: (boolean) "true" if the command was - executed with a ! modifier |<bang>| - • line1: (number) The starting line of the - command range |<line1>| - • line2: (number) The final line of the command - range |<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>| - • smods: (table) Command modifiers in a - structured format. Has the same structure as - the "mods" key of |nvim_parse_cmd()|. - {opts} Optional command attributes. See - |command-attributes| for more details. To use - boolean attributes (such as |:command-bang| or - |:command-bar|) set the value to "true". In - addition to the string options listed in - |:command-complete|, the "complete" key also - accepts a Lua function which works like the - "customlist" completion mode - |:command-completion-customlist|. Additional - 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| + Parameters: ~ + {name} Name of the new user command. Must begin with an uppercase + letter. + {command} 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: + • args: (string) The args passed to the command, if any + |<args>| + • fargs: (table) The args split by unescaped whitespace + (when more than one argument is allowed), if any + |<f-args>| + • bang: (boolean) "true" if the command was executed with a + ! modifier |<bang>| + • line1: (number) The starting line of the command range + |<line1>| + • line2: (number) The final line of the command range + |<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>| + • smods: (table) Command modifiers in a structured format. + Has the same structure as the "mods" key of + |nvim_parse_cmd()|. + {opts} Optional command attributes. See |command-attributes| for + more details. To use boolean attributes (such as + |:command-bang| or |:command-bar|) set the value to "true". + In addition to the string options listed in + |:command-complete|, the "complete" key also accepts a Lua + function which works like the "customlist" completion mode + |:command-completion-customlist|. Additional 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| nvim_del_user_command({name}) *nvim_del_user_command()* - Delete a user-defined command. + Delete a user-defined command. - Parameters: ~ - {name} Name of the command to delete. + Parameters: ~ + {name} Name of the command to delete. nvim_get_commands({*opts}) *nvim_get_commands()* - Gets a map of global (non-buffer-local) Ex commands. + Gets a map of global (non-buffer-local) Ex commands. - Currently only |user-commands| are supported, not builtin Ex - commands. + Currently only |user-commands| are supported, not builtin Ex commands. - Parameters: ~ - {opts} Optional parameters. Currently only supports - {"builtin":false} + Parameters: ~ + {opts} Optional parameters. Currently only supports {"builtin":false} - Return: ~ - Map of maps describing commands. + Return: ~ + Map of maps describing commands. nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* - Parse command line. - - Doesn't check the validity of command arguments. - - Attributes: ~ - |api-fast| - - Parameters: ~ - {str} Command line string to parse. Cannot contain "\n". - {opts} Optional parameters. Reserved for future use. - - Return: ~ - Dictionary containing command information, with these - keys: - • cmd: (string) Command name. - • range: (array) Command <range>. Can have 0-2 elements - depending on how many items the range contains. Has no - elements if command doesn't accept a range or if no - range was specified, one element if only a single range - item was specified and two elements if both range items - were specified. - • count: (number) Any |<count>| that was supplied to the - command. -1 if command cannot take a count. - • reg: (number) The optional command |<register>|, if - specified. Empty string if not specified or if command - cannot take a register. - • bang: (boolean) Whether command contains a |<bang>| (!) - modifier. - • args: (array) Command arguments. - • addr: (string) Value of |:command-addr|. Uses short - name. - • nargs: (string) Value of |:command-nargs|. - • nextcmd: (string) Next command if there are multiple - commands separated by a |:bar|. Empty if there isn't a - next command. - • magic: (dictionary) Which characters have special - meaning in the command arguments. - • file: (boolean) The command expands filenames. Which - means characters such as "%", "#" and wildcards are - expanded. - • bar: (boolean) The "|" character is treated as a - command separator and the double quote character (") - is treated as the start of a comment. - - • mods: (dictionary) |:command-modifiers|. - • filter: (dictionary) |:filter|. - • pattern: (string) Filter pattern. Empty string if - there is no filter. - • force: (boolean) Whether filter is inverted or not. - - • silent: (boolean) |:silent|. - • emsg_silent: (boolean) |:silent!|. - • unsilent: (boolean) |:unsilent|. - • sandbox: (boolean) |:sandbox|. - • noautocmd: (boolean) |:noautocmd|. - • browse: (boolean) |:browse|. - • confirm: (boolean) |:confirm|. - • hide: (boolean) |:hide|. - • keepalt: (boolean) |:keepalt|. - • keepjumps: (boolean) |:keepjumps|. - • keepmarks: (boolean) |:keepmarks|. - • keeppatterns: (boolean) |:keeppatterns|. - • lockmarks: (boolean) |:lockmarks|. - • noswapfile: (boolean) |:noswapfile|. - • tab: (integer) |:tab|. - • verbose: (integer) |:verbose|. -1 when omitted. - • vertical: (boolean) |:vertical|. - • split: (string) Split modifier string, is an empty - string when there's no split modifier. If there is a - split modifier it can be one of: - • "aboveleft": |:aboveleft|. - • "belowright": |:belowright|. - • "topleft": |:topleft|. - • "botright": |:botright|. + Parse command line. + + Doesn't check the validity of command arguments. + + Attributes: ~ + |api-fast| + + Parameters: ~ + {str} Command line string to parse. Cannot contain "\n". + {opts} Optional parameters. Reserved for future use. + + Return: ~ + Dictionary containing command information, with these keys: + • cmd: (string) Command name. + • range: (array) Command <range>. Can have 0-2 elements depending on + how many items the range contains. Has no elements if command + doesn't accept a range or if no range was specified, one element if + only a single range item was specified and two elements if both + range items were specified. + • count: (number) Any |<count>| that was supplied to the command. -1 + if command cannot take a count. + • reg: (number) The optional command |<register>|, if specified. Empty + string if not specified or if command cannot take a register. + • bang: (boolean) Whether command contains a |<bang>| (!) modifier. + • args: (array) Command arguments. + • addr: (string) Value of |:command-addr|. Uses short name. + • nargs: (string) Value of |:command-nargs|. + • nextcmd: (string) Next command if there are multiple commands + separated by a |:bar|. Empty if there isn't a next command. + • magic: (dictionary) Which characters have special meaning in the + command arguments. + • file: (boolean) The command expands filenames. Which means + characters such as "%", "#" and wildcards are expanded. + • bar: (boolean) The "|" character is treated as a command separator + and the double quote character (") is treated as the start of a + comment. + + • mods: (dictionary) |:command-modifiers|. + • filter: (dictionary) |:filter|. + • pattern: (string) Filter pattern. Empty string if there is no + filter. + • force: (boolean) Whether filter is inverted or not. + + • silent: (boolean) |:silent|. + • emsg_silent: (boolean) |:silent!|. + • unsilent: (boolean) |:unsilent|. + • sandbox: (boolean) |:sandbox|. + • noautocmd: (boolean) |:noautocmd|. + • browse: (boolean) |:browse|. + • confirm: (boolean) |:confirm|. + • hide: (boolean) |:hide|. + • keepalt: (boolean) |:keepalt|. + • keepjumps: (boolean) |:keepjumps|. + • keepmarks: (boolean) |:keepmarks|. + • keeppatterns: (boolean) |:keeppatterns|. + • lockmarks: (boolean) |:lockmarks|. + • noswapfile: (boolean) |:noswapfile|. + • tab: (integer) |:tab|. + • verbose: (integer) |:verbose|. -1 when omitted. + • vertical: (boolean) |:vertical|. + • split: (string) Split modifier string, is an empty string when + there's no split modifier. If there is a split modifier it can be + one of: + • "aboveleft": |:aboveleft|. + • "belowright": |:belowright|. + • "topleft": |:topleft|. + • "botright": |:botright|. ============================================================================== Options Functions *api-options* nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()* - Gets a buffer option value + Gets a buffer option value - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {name} Option name + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {name} Option name - Return: ~ - Option value + Return: ~ + Option value nvim_buf_set_option({buffer}, {name}, {value}) *nvim_buf_set_option()* - Sets a buffer option value. Passing `nil` as value deletes the - option (only works if there's a global fallback) + Sets a buffer option value. Passing `nil` as value deletes the option + (only works if there's a global fallback) - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {name} Option name - {value} Option value + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {name} Option name + {value} Option value nvim_get_all_options_info() *nvim_get_all_options_info()* - Gets the option information for all options. + 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_info|. + The dictionary has the full option names as keys and option metadata + dictionaries as detailed at |nvim_get_option_info|. - Return: ~ - dictionary of all options + Return: ~ + dictionary of all options nvim_get_option({name}) *nvim_get_option()* - Gets the global value of an option. + Gets the global value of an option. - Parameters: ~ - {name} Option name + Parameters: ~ + {name} Option name - Return: ~ - Option value (global) + Return: ~ + Option value (global) nvim_get_option_info({name}) *nvim_get_option_info()* - Gets the option information for one option - - Resulting dictionary has keys: - • name: Name of the option (like 'filetype') - • shortname: Shortened name of the option (like 'ft') - • type: type of option ("string", "number" or "boolean") - • default: The default value for the option - • was_set: Whether the option was set. - • last_set_sid: Last set script id (if any) - • last_set_linenr: line number where option was set - • last_set_chan: Channel where option was set (0 for local) - • scope: one of "global", "win", or "buf" - • global_local: whether win or buf option has a global value - • commalist: List of comma separated values - • flaglist: List of single char flags - - Parameters: ~ - {name} Option name - - Return: ~ - Option Information + Gets the option information for one option + + Resulting dictionary has keys: + • name: Name of the option (like 'filetype') + • shortname: Shortened name of the option (like 'ft') + • type: type of option ("string", "number" or "boolean") + • default: The default value for the option + • was_set: Whether the option was set. + • last_set_sid: Last set script id (if any) + • last_set_linenr: line number where option was set + • last_set_chan: Channel where option was set (0 for local) + • scope: one of "global", "win", or "buf" + • global_local: whether win or buf option has a global value + • commalist: List of comma separated values + • flaglist: List of single char flags + + Parameters: ~ + {name} Option name + + Return: ~ + Option Information nvim_get_option_value({name}, {*opts}) *nvim_get_option_value()* - Gets the value of an option. The behavior of this function - matches that of |:set|: the local value of an option is - returned if it exists; otherwise, the global value is - returned. Local values always correspond to the current buffer - or window, unless "buf" or "win" is set in {opts}. - - Parameters: ~ - {name} Option name - {opts} Optional parameters - • scope: One of "global" or "local". Analogous to - |:setglobal| and |:setlocal|, respectively. - • win: |window-ID|. Used for getting window local - options. - • buf: Buffer number. Used for getting buffer - local options. Implies {scope} is "local". - - Return: ~ - Option value + Gets the value of an option. The behavior of this function matches that of + |:set|: the local value of an option is returned if it exists; otherwise, + the global value is returned. Local values always correspond to the + current buffer or window, unless "buf" or "win" is set in {opts}. + + Parameters: ~ + {name} Option name + {opts} Optional parameters + • scope: One of "global" or "local". Analogous to |:setglobal| + and |:setlocal|, respectively. + • win: |window-ID|. Used for getting window local options. + • buf: Buffer number. Used for getting buffer local options. + Implies {scope} is "local". + + Return: ~ + Option value nvim_set_option({name}, {value}) *nvim_set_option()* - Sets the global value of an option. + Sets the global value of an option. - Parameters: ~ - {name} Option name - {value} New option value + Parameters: ~ + {name} Option name + {value} New option value *nvim_set_option_value()* nvim_set_option_value({name}, {value}, {*opts}) - 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. - - Parameters: ~ - {name} Option name - {value} New option value - {opts} 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. + 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. + + Parameters: ~ + {name} Option name + {value} New option value + {opts} 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. nvim_win_get_option({window}, {name}) *nvim_win_get_option()* - Gets a window option value + Gets a window option value - Parameters: ~ - {window} Window handle, or 0 for current window - {name} Option name + Parameters: ~ + {window} Window handle, or 0 for current window + {name} Option name - Return: ~ - Option value + Return: ~ + Option value nvim_win_set_option({window}, {name}, {value}) *nvim_win_set_option()* - Sets a window option value. Passing `nil` as value deletes the - option (only works if there's a global fallback) + Sets a window option value. Passing `nil` as value deletes the option + (only works if there's a global fallback) - Parameters: ~ - {window} Window handle, or 0 for current window - {name} Option name - {value} Option value + Parameters: ~ + {window} Window handle, or 0 for current window + {name} Option name + {value} Option value ============================================================================== @@ -2097,451 +1990,427 @@ For more information on buffers, see |buffers|. Unloaded Buffers:~ -Buffers may be unloaded by the |:bunload| command or the -buffer's |'bufhidden'| option. When a buffer is unloaded its -file contents are freed from memory and vim cannot operate on -the buffer lines until it is reloaded (usually by opening the -buffer again in a new window). API methods such as -|nvim_buf_get_lines()| and |nvim_buf_line_count()| will be +Buffers may be unloaded by the |:bunload| command or the buffer's +|'bufhidden'| option. When a buffer is unloaded its file contents are +freed from memory and vim cannot operate on the buffer lines until it is +reloaded (usually by opening the buffer again in a new window). API +methods such as |nvim_buf_get_lines()| and |nvim_buf_line_count()| will be affected. -You can use |nvim_buf_is_loaded()| or |nvim_buf_line_count()| -to check whether a buffer is loaded. +You can use |nvim_buf_is_loaded()| or |nvim_buf_line_count()| to check +whether a buffer is loaded. nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* - Activates buffer-update events on a channel, or as Lua - callbacks. - - Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its - contents): > - events = {} - vim.api.nvim_buf_attach(0, false, { - on_lines=function(...) table.insert(events, {...}) end}) + Activates buffer-update events on a channel, or as Lua callbacks. + + Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): > + events = {} + vim.api.nvim_buf_attach(0, false, { + on_lines=function(...) table.insert(events, {...}) end}) < - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {send_buffer} 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. - {opts} 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. - - Return: ~ - False if attach failed (invalid parameter, or buffer isn't - loaded); otherwise True. TODO: LUA_API_NO_EVAL - - See also: ~ - |nvim_buf_detach()| - |api-buffer-updates-lua| + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {send_buffer} 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. + {opts} 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. + + Return: ~ + False if attach failed (invalid parameter, or buffer isn't loaded); + otherwise True. TODO: LUA_API_NO_EVAL + + See also: ~ + |nvim_buf_detach()| + |api-buffer-updates-lua| nvim_buf_call({buffer}, {fun}) *nvim_buf_call()* - call a function with buffer as temporary current buffer + 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 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 vimL functions that only work with - the current buffer/window currently, like |termopen()|. + This is useful e.g. to call vimL functions that only work with the current + buffer/window currently, like |termopen()|. - Attributes: ~ - |vim.api| only + Attributes: ~ + |vim.api| only - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {fun} Function to call inside the buffer (currently - lua callable only) + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {fun} Function to call inside the buffer (currently lua callable + only) - Return: ~ - Return value of function. NB: will deepcopy lua values - currently, use upvalues to send lua references in and out. + Return: ~ + Return value of function. NB: will deepcopy lua values currently, use + upvalues to send lua references in and out. nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()* - Unmaps a buffer-local |mapping| for the given mode. + Unmaps a buffer-local |mapping| for the given mode. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer - See also: ~ - |nvim_del_keymap()| + See also: ~ + |nvim_del_keymap()| nvim_buf_del_mark({buffer}, {name}) *nvim_buf_del_mark()* - Deletes a named mark in the buffer. See |mark-motions|. + 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. + Note: + only deletes marks set in the buffer, if the mark is not set in the + buffer it will return false. - Parameters: ~ - {buffer} Buffer to set the mark on - {name} Mark name + Parameters: ~ + {buffer} Buffer to set the mark on + {name} Mark name - Return: ~ - true if the mark was deleted, else false. + Return: ~ + true if the mark was deleted, else false. - See also: ~ - |nvim_buf_set_mark()| - |nvim_del_mark()| + See also: ~ + |nvim_buf_set_mark()| + |nvim_del_mark()| nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* - Removes a buffer-scoped (b:) variable + Removes a buffer-scoped (b:) variable - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {name} Variable name + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {name} Variable name nvim_buf_delete({buffer}, {opts}) *nvim_buf_delete()* - Deletes the buffer. See |:bwipeout| + Deletes the buffer. See |:bwipeout| - Attributes: ~ - not allowed when |textlock| is active + Attributes: ~ + not allowed when |textlock| is active - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {opts} Optional parameters. Keys: - • force: Force deletion and ignore unsaved - changes. - • unload: Unloaded only, do not delete. See - |:bunload| + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {opts} Optional parameters. Keys: + • force: Force deletion and ignore unsaved changes. + • unload: Unloaded only, do not delete. See |:bunload| nvim_buf_detach({buffer}) *nvim_buf_detach()* - Deactivates buffer-update events on the channel. + Deactivates buffer-update events on the channel. - Attributes: ~ - |RPC| only + Attributes: ~ + |RPC| only - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer - Return: ~ - False if detach failed (because the buffer isn't loaded); - otherwise True. + Return: ~ + False if detach failed (because the buffer isn't loaded); otherwise + True. - See also: ~ - |nvim_buf_attach()| - |api-lua-detach| for detaching Lua callbacks + See also: ~ + |nvim_buf_attach()| + |api-lua-detach| for detaching Lua callbacks nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()* - Gets a changed tick of a buffer + Gets a changed tick of a buffer - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer - Return: ~ - `b:changedtick` value. + Return: ~ + `b:changedtick` value. nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* - Gets a list of buffer-local |mapping| definitions. + Gets a list of buffer-local |mapping| definitions. - Parameters: ~ - {mode} Mode short-name ("n", "i", "v", ...) - {buffer} Buffer handle, or 0 for current buffer + Parameters: ~ + {mode} Mode short-name ("n", "i", "v", ...) + {buffer} Buffer handle, or 0 for current buffer - Return: ~ - Array of |maparg()|-like dictionaries describing mappings. - The "buffer" key holds the associated buffer handle. + Return: ~ + Array of |maparg()|-like dictionaries describing mappings. The + "buffer" key holds the associated buffer handle. *nvim_buf_get_lines()* nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) - Gets a line-range from the buffer. + 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. + Out-of-bounds indices are clamped to the nearest valid value, unless + `strict_indexing` is set. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {start} First line index - {end} Last line index, exclusive - {strict_indexing} Whether out-of-bounds should be an - error. + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {start} First line index + {end} Last line index, exclusive + {strict_indexing} Whether out-of-bounds should be an error. - Return: ~ - Array of lines, or empty array for unloaded buffer. + Return: ~ + Array of lines, or empty array for unloaded buffer. nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* - Returns a tuple (row,col) representing the position of the - named mark. See |mark-motions|. + Returns a tuple (row,col) representing the position of the named mark. See + |mark-motions|. - Marks are (1,0)-indexed. |api-indexing| + Marks are (1,0)-indexed. |api-indexing| - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {name} Mark name + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {name} Mark name - Return: ~ - (row, col) tuple, (0, 0) if the mark is not set, or is an - uppercase/file mark set in another buffer. + Return: ~ + (row, col) tuple, (0, 0) if the mark is not set, or is an + uppercase/file mark set in another buffer. - See also: ~ - |nvim_buf_set_mark()| - |nvim_buf_del_mark()| + See also: ~ + |nvim_buf_set_mark()| + |nvim_buf_del_mark()| nvim_buf_get_name({buffer}) *nvim_buf_get_name()* - Gets the full file name for the buffer + Gets the full file name for the buffer - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer - Return: ~ - Buffer name + Return: ~ + Buffer name nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()* - Returns the byte offset of a line (0-indexed). |api-indexing| + 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'. + 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. + Unlike |line2byte()|, throws error for out-of-bounds indexing. Returns -1 + for unloaded buffer. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {index} Line index + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {index} Line index - Return: ~ - Integer byte offset, or -1 for unloaded buffer. + Return: ~ + Integer byte offset, or -1 for unloaded buffer. *nvim_buf_get_text()* nvim_buf_get_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, {opts}) - Gets a range from the buffer. + Gets a range from the buffer. - This differs from |nvim_buf_get_lines()| in that it allows - retrieving only portions of a line. + 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. + Indexing is zero-based. Row indices are end-inclusive, and column indices + are end-exclusive. - Prefer |nvim_buf_get_lines()| when retrieving entire lines. + Prefer |nvim_buf_get_lines()| when retrieving entire lines. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {start_row} First line index - {start_col} Starting column (byte offset) on first line - {end_row} Last line index, inclusive - {end_col} Ending column (byte offset) on last line, - exclusive - {opts} Optional parameters. Currently unused. + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {start_row} First line index + {start_col} Starting column (byte offset) on first line + {end_row} Last line index, inclusive + {end_col} Ending column (byte offset) on last line, exclusive + {opts} Optional parameters. Currently unused. - Return: ~ - Array of lines, or empty array for unloaded buffer. + Return: ~ + Array of lines, or empty array for unloaded buffer. nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()* - Gets a buffer-scoped (b:) variable. + Gets a buffer-scoped (b:) variable. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {name} Variable name + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {name} Variable name - Return: ~ - Variable value + Return: ~ + Variable value nvim_buf_is_loaded({buffer}) *nvim_buf_is_loaded()* - Checks if a buffer is valid and loaded. See |api-buffer| for - more info about unloaded buffers. + Checks if a buffer is valid and loaded. See |api-buffer| for more info + about unloaded buffers. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer - Return: ~ - true if the buffer is valid and loaded, false otherwise. + Return: ~ + true if the buffer is valid and loaded, false otherwise. nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()* - Checks if a buffer is valid. + 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. + Note: + Even if a buffer is valid it may have been unloaded. See |api-buffer| + for more info about unloaded buffers. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer - Return: ~ - true if the buffer is valid, false otherwise. + Return: ~ + true if the buffer is valid, false otherwise. nvim_buf_line_count({buffer}) *nvim_buf_line_count()* - Returns the number of lines in the given buffer. + Returns the number of lines in the given buffer. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer - Return: ~ - Line count, or 0 for unloaded buffer. |api-buffer| + Return: ~ + Line count, or 0 for unloaded buffer. |api-buffer| *nvim_buf_set_keymap()* nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {*opts}) - Sets a buffer-local |mapping| for the given mode. + Sets a buffer-local |mapping| for the given mode. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer - See also: ~ - |nvim_set_keymap()| + See also: ~ + |nvim_set_keymap()| *nvim_buf_set_lines()* nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement}) - Sets (replaces) a line-range in the buffer. + 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. + 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. + Out-of-bounds indices are clamped to the nearest valid value, unless + `strict_indexing` is set. - Attributes: ~ - not allowed when |textlock| is active + Attributes: ~ + not allowed when |textlock| is active - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {start} First line index - {end} Last line index, exclusive - {strict_indexing} Whether out-of-bounds should be an - error. - {replacement} Array of lines to use as replacement + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {start} First line index + {end} Last line index, exclusive + {strict_indexing} Whether out-of-bounds should be an error. + {replacement} Array of lines to use as replacement *nvim_buf_set_mark()* nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {opts}) - Sets a named mark in the given buffer, all marks are allowed - file/uppercase, visual, last change, etc. See |mark-motions|. + 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| + Marks are (1,0)-indexed. |api-indexing| - Note: - Passing 0 as line deletes the mark + Note: + Passing 0 as line deletes the mark - Parameters: ~ - {buffer} Buffer to set the mark on - {name} Mark name - {line} Line number - {col} Column/row number - {opts} Optional parameters. Reserved for future use. + Parameters: ~ + {buffer} Buffer to set the mark on + {name} Mark name + {line} Line number + {col} Column/row number + {opts} Optional parameters. Reserved for future use. - Return: ~ - true if the mark was set, else false. + Return: ~ + true if the mark was set, else false. - See also: ~ - |nvim_buf_del_mark()| - |nvim_buf_get_mark()| + See also: ~ + |nvim_buf_del_mark()| + |nvim_buf_get_mark()| nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()* - Sets the full file name for a buffer + Sets the full file name for a buffer - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {name} Buffer name + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {name} Buffer name *nvim_buf_set_text()* nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, {replacement}) - Sets (replaces) a range in the buffer + 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. + 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_buf_set_lines()| if you are only adding or deleting entire + lines. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {start_row} First line index - {start_col} Starting column (byte offset) on first line - {end_row} Last line index, inclusive - {end_col} Ending column (byte offset) on last line, - exclusive - {replacement} Array of lines to use as replacement + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {start_row} First line index + {start_col} Starting column (byte offset) on first line + {end_row} Last line index, inclusive + {end_col} Ending column (byte offset) on last line, exclusive + {replacement} Array of lines to use as replacement nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* - Sets a buffer-scoped (b:) variable + Sets a buffer-scoped (b:) variable - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {name} Variable name - {value} Variable value + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {name} Variable name + {value} Variable value ============================================================================== @@ -2550,107 +2419,96 @@ Extmark Functions *api-extmark* *nvim_buf_add_highlight()* nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, {col_start}, {col_end}) - Adds a highlight to buffer. - - Useful for plugins that dynamically generate highlights to a - buffer (like a semantic highlighter or linter). The function - adds a single highlight to a buffer. Unlike |matchaddpos()| - highlights follow changes to line numbering (as lines are - inserted/removed above the highlighted line), like signs and - marks do. - - Namespaces are used for batch deletion/updating of a set of - highlights. To create a namespace, use - |nvim_create_namespace()| which returns a namespace id. Pass - it in to this function as `ns_id` to add highlights to the - namespace. All highlights in the same namespace can then be - cleared with single call to |nvim_buf_clear_namespace()|. If - the highlight never will be deleted by an API call, pass - `ns_id = -1`. - - As a shorthand, `ns_id = 0` can be used to create a new - namespace for the highlight, the allocated id is then - returned. If `hl_group` is the empty string no highlight is - added, but a new `ns_id` is still returned. This is supported - for backwards compatibility, new code should use - |nvim_create_namespace()| to create a new empty namespace. - - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {ns_id} namespace to use or -1 for ungrouped - highlight - {hl_group} Name of the highlight group to use - {line} Line to highlight (zero-indexed) - {col_start} Start of (byte-indexed) column range to - highlight - {col_end} End of (byte-indexed) column range to - highlight, or -1 to highlight to end of line - - Return: ~ - The ns_id that was used + Adds a highlight to buffer. + + Useful for plugins that dynamically generate highlights to a buffer (like + a semantic highlighter or linter). The function adds a single highlight to + a buffer. Unlike |matchaddpos()| highlights follow changes to line + numbering (as lines are inserted/removed above the highlighted line), like + signs and marks do. + + Namespaces are used for batch deletion/updating of a set of highlights. To + create a namespace, use |nvim_create_namespace()| which returns a + namespace id. Pass it in to this function as `ns_id` to add highlights to + the namespace. All highlights in the same namespace can then be cleared + with single call to |nvim_buf_clear_namespace()|. If the highlight never + will be deleted by an API call, pass `ns_id = -1`. + + As a shorthand, `ns_id = 0` can be used to create a new namespace for the + highlight, the allocated id is then returned. If `hl_group` is the empty + string no highlight is added, but a new `ns_id` is still returned. This is + supported for backwards compatibility, new code should use + |nvim_create_namespace()| to create a new empty namespace. + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {ns_id} namespace to use or -1 for ungrouped highlight + {hl_group} Name of the highlight group to use + {line} Line to highlight (zero-indexed) + {col_start} Start of (byte-indexed) column range to highlight + {col_end} End of (byte-indexed) column range to highlight, or -1 to + highlight to end of line + + Return: ~ + The ns_id that was used *nvim_buf_clear_namespace()* nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end}) - Clears namespaced objects (highlights, extmarks, virtual text) - from a region. + Clears namespaced 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. + Lines are 0-indexed. |api-indexing| To clear the namespace in the entire + buffer, specify line_start=0 and line_end=-1. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {ns_id} Namespace to clear, or -1 to clear all - namespaces. - {line_start} Start of range of lines to clear - {line_end} End of range of lines to clear (exclusive) - or -1 to clear to end of buffer. + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {ns_id} Namespace to clear, or -1 to clear all namespaces. + {line_start} Start of range of lines to clear + {line_end} End of range of lines to clear (exclusive) or -1 to + clear to end of buffer. nvim_buf_del_extmark({buffer}, {ns_id}, {id}) *nvim_buf_del_extmark()* - Removes an extmark. + Removes an extmark. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {ns_id} Namespace id from |nvim_create_namespace()| - {id} Extmark id + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {ns_id} Namespace id from |nvim_create_namespace()| + {id} Extmark id - Return: ~ - true if the extmark was found, else false + Return: ~ + true if the extmark was found, else false *nvim_buf_get_extmark_by_id()* nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts}) - Gets the position (0-indexed) of an extmark. + Gets the position (0-indexed) of an extmark. - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {ns_id} Namespace id from |nvim_create_namespace()| - {id} Extmark id - {opts} Optional parameters. Keys: - • details: Whether to include the details dict + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {ns_id} Namespace id from |nvim_create_namespace()| + {id} Extmark id + {opts} Optional parameters. Keys: + • details: Whether to include the details dict - Return: ~ - 0-indexed (row, col) tuple or empty list () if extmark id - was absent + Return: ~ + 0-indexed (row, col) tuple or empty list () if extmark id was absent *nvim_buf_get_extmarks()* nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) - 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: + 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: > nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) 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.) - Example: + Example: > local a = vim.api local pos = a.nvim_win_get_cursor(0) @@ -2666,759 +2524,694 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) print(vim.inspect(ms)) < - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {ns_id} Namespace id from |nvim_create_namespace()| - {start} Start of range: a 0-indexed (row, col) or valid - extmark id (whose position defines the bound). - |api-indexing| - {end} End of range (inclusive): a 0-indexed (row, col) - or valid extmark id (whose position defines the - bound). |api-indexing| - {opts} Optional parameters. Keys: - • limit: Maximum number of marks to return - • details Whether to include the details dict - - Return: ~ - List of [extmark_id, row, col] tuples in "traversal - order". + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {ns_id} Namespace id from |nvim_create_namespace()| + {start} Start of range: a 0-indexed (row, col) or valid extmark id + (whose position defines the bound). |api-indexing| + {end} End of range (inclusive): a 0-indexed (row, col) or valid + extmark id (whose position defines the bound). + |api-indexing| + {opts} Optional parameters. Keys: + • limit: Maximum number of marks to return + • details Whether to include the details dict + + Return: ~ + List of [extmark_id, row, col] tuples in "traversal order". *nvim_buf_set_extmark()* nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) - 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. - - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {ns_id} Namespace id from |nvim_create_namespace()| - {line} Line where to place the mark, 0-based. - |api-indexing| - {col} Column where to place the mark, 0-based. - |api-indexing| - {opts} 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 - 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. - - • virt_text_win_col : position the virtual text - at a fixed window column (starting from the - first text column) - • virt_text_hide : hide the virtual text when - the background text is selected or hidden due - to horizontal scroll 'nowrap' - • 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. - - • 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. - • priority: a priority value for the highlight - group. 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|. - • 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. - - Return: ~ - Id of the created/updated extmark + 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. + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {ns_id} Namespace id from |nvim_create_namespace()| + {line} Line where to place the mark, 0-based. |api-indexing| + {col} Column where to place the mark, 0-based. |api-indexing| + {opts} 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 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. + + • virt_text_win_col : position the virtual text at a fixed + window column (starting from the first text column) + • virt_text_hide : hide the virtual text when the background + text is selected or hidden due to horizontal scroll + 'nowrap' + • 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. + + • 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. + • 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|. + • 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. + + Return: ~ + Id of the created/updated extmark nvim_create_namespace({name}) *nvim_create_namespace()* - Creates a new *namespace* or gets an existing one. + Creates a new *namespace* or gets an existing one. - Namespaces are used for buffer highlights and virtual text, - see |nvim_buf_add_highlight()| and |nvim_buf_set_extmark()|. + 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. + 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. - Parameters: ~ - {name} Namespace name or empty string + Parameters: ~ + {name} Namespace name or empty string - Return: ~ - Namespace id + Return: ~ + Namespace id nvim_get_namespaces() *nvim_get_namespaces()* - Gets existing, non-anonymous namespaces. + Gets existing, non-anonymous namespaces. - Return: ~ - dict that maps from names to namespace ids. + Return: ~ + dict that maps from names to namespace ids. *nvim_set_decoration_provider()* nvim_set_decoration_provider({ns_id}, {opts}) - 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. Similarly, return - `false` in `on_win` will skip the `on_lines` calls for that - window (but any extmarks set in `on_win` will still be used). - A 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 - expliticly 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. - - Attributes: ~ - |vim.api| only - - Parameters: ~ - {ns_id} Namespace id from |nvim_create_namespace()| - {opts} Callbacks invoked during redraw: - • 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_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] + 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. + Similarly, return `false` in `on_win` will skip the `on_lines` calls for + that window (but any extmarks set in `on_win` will still be used). A + 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 expliticly + 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. + + Attributes: ~ + |vim.api| only + + Parameters: ~ + {ns_id} Namespace id from |nvim_create_namespace()| + {opts} Callbacks invoked during redraw: + • 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_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] ============================================================================== Window Functions *api-window* nvim_win_call({window}, {fun}) *nvim_win_call()* - Calls a function with window as temporary current window. + Calls a function with window as temporary current window. - Attributes: ~ - |vim.api| only + Attributes: ~ + |vim.api| only - Parameters: ~ - {window} Window handle, or 0 for current window - {fun} Function to call inside the window (currently - lua callable only) + Parameters: ~ + {window} Window handle, or 0 for current window + {fun} Function to call inside the window (currently lua callable + only) - Return: ~ - Return value of function. NB: will deepcopy lua values - currently, use upvalues to send lua references in and out. + Return: ~ + Return value of function. NB: will deepcopy lua values currently, use + upvalues to send lua references in and out. - See also: ~ - |win_execute()| - |nvim_buf_call()| + See also: ~ + |win_execute()| + |nvim_buf_call()| nvim_win_close({window}, {force}) *nvim_win_close()* - Closes the window (like |:close| with a |window-ID|). + Closes the window (like |:close| with a |window-ID|). - Attributes: ~ - not allowed when |textlock| is active + Attributes: ~ + not allowed when |textlock| is active - Parameters: ~ - {window} Window handle, or 0 for current window - {force} 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. + Parameters: ~ + {window} Window handle, or 0 for current window + {force} 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. nvim_win_del_var({window}, {name}) *nvim_win_del_var()* - Removes a window-scoped (w:) variable + Removes a window-scoped (w:) variable - Parameters: ~ - {window} Window handle, or 0 for current window - {name} Variable name + Parameters: ~ + {window} Window handle, or 0 for current window + {name} Variable name nvim_win_get_buf({window}) *nvim_win_get_buf()* - Gets the current buffer in a window + Gets the current buffer in a window - Parameters: ~ - {window} Window handle, or 0 for current window + Parameters: ~ + {window} Window handle, or 0 for current window - Return: ~ - Buffer handle + Return: ~ + Buffer handle nvim_win_get_cursor({window}) *nvim_win_get_cursor()* - Gets the (1,0)-indexed cursor position in the window. - |api-indexing| + Gets the (1,0)-indexed cursor position in the window. |api-indexing| - Parameters: ~ - {window} Window handle, or 0 for current window + Parameters: ~ + {window} Window handle, or 0 for current window - Return: ~ - (row, col) tuple + Return: ~ + (row, col) tuple nvim_win_get_height({window}) *nvim_win_get_height()* - Gets the window height + Gets the window height - Parameters: ~ - {window} Window handle, or 0 for current window + Parameters: ~ + {window} Window handle, or 0 for current window - Return: ~ - Height as a count of rows + Return: ~ + Height as a count of rows nvim_win_get_number({window}) *nvim_win_get_number()* - Gets the window number + Gets the window number - Parameters: ~ - {window} Window handle, or 0 for current window + Parameters: ~ + {window} Window handle, or 0 for current window - Return: ~ - Window number + Return: ~ + Window number nvim_win_get_position({window}) *nvim_win_get_position()* - Gets the window position in display cells. First position is - zero. + Gets the window position in display cells. First position is zero. - Parameters: ~ - {window} Window handle, or 0 for current window + Parameters: ~ + {window} Window handle, or 0 for current window - Return: ~ - (row, col) tuple with the window position + Return: ~ + (row, col) tuple with the window position nvim_win_get_tabpage({window}) *nvim_win_get_tabpage()* - Gets the window tabpage + Gets the window tabpage - Parameters: ~ - {window} Window handle, or 0 for current window + Parameters: ~ + {window} Window handle, or 0 for current window - Return: ~ - Tabpage that contains the window + Return: ~ + Tabpage that contains the window nvim_win_get_var({window}, {name}) *nvim_win_get_var()* - Gets a window-scoped (w:) variable + Gets a window-scoped (w:) variable - Parameters: ~ - {window} Window handle, or 0 for current window - {name} Variable name + Parameters: ~ + {window} Window handle, or 0 for current window + {name} Variable name - Return: ~ - Variable value + Return: ~ + Variable value nvim_win_get_width({window}) *nvim_win_get_width()* - Gets the window width + Gets the window width - Parameters: ~ - {window} Window handle, or 0 for current window + Parameters: ~ + {window} Window handle, or 0 for current window - Return: ~ - Width as a count of columns + Return: ~ + Width as a count of columns nvim_win_hide({window}) *nvim_win_hide()* - Closes the window and hide the buffer it contains (like - |:hide| with a |window-ID|). + 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. + 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. - Attributes: ~ - not allowed when |textlock| is active + Attributes: ~ + not allowed when |textlock| is active - Parameters: ~ - {window} Window handle, or 0 for current window + Parameters: ~ + {window} Window handle, or 0 for current window nvim_win_is_valid({window}) *nvim_win_is_valid()* - Checks if a window is valid + Checks if a window is valid - Parameters: ~ - {window} Window handle, or 0 for current window + Parameters: ~ + {window} Window handle, or 0 for current window - Return: ~ - true if the window is valid, false otherwise + Return: ~ + true if the window is valid, false otherwise nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()* - Sets the current buffer in a window, without side effects + Sets the current buffer in a window, without side effects - Attributes: ~ - not allowed when |textlock| is active + Attributes: ~ + not allowed when |textlock| is active - Parameters: ~ - {window} Window handle, or 0 for current window - {buffer} Buffer handle + Parameters: ~ + {window} Window handle, or 0 for current window + {buffer} Buffer handle nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()* - Sets the (1,0)-indexed cursor position in the window. - |api-indexing| This scrolls the window even if it is not the - current one. + Sets the (1,0)-indexed cursor position in the window. |api-indexing| This + scrolls the window even if it is not the current one. - Parameters: ~ - {window} Window handle, or 0 for current window - {pos} (row, col) tuple representing the new position + Parameters: ~ + {window} Window handle, or 0 for current window + {pos} (row, col) tuple representing the new position nvim_win_set_height({window}, {height}) *nvim_win_set_height()* - Sets the window height. + Sets the window height. + + Parameters: ~ + {window} Window handle, or 0 for current window + {height} Height as a count of rows - Parameters: ~ - {window} Window handle, or 0 for current window - {height} Height as a count of rows +nvim_win_set_hl_ns({window}, {ns_id}) *nvim_win_set_hl_ns()* + Set highlight namespace for a window. This will use highlights defined in + this namespace, but fall back to global highlights (ns=0) when missing. + + This takes predecence over the 'winhighlight' option. + + Parameters: ~ + {ns_id} the namespace to use nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()* - Sets a window-scoped (w:) variable + Sets a window-scoped (w:) variable - Parameters: ~ - {window} Window handle, or 0 for current window - {name} Variable name - {value} Variable value + Parameters: ~ + {window} Window handle, or 0 for current window + {name} Variable name + {value} Variable value nvim_win_set_width({window}, {width}) *nvim_win_set_width()* - Sets the window width. This will only succeed if the screen is - split vertically. + Sets the window width. This will only succeed if the screen is split + vertically. - Parameters: ~ - {window} Window handle, or 0 for current window - {width} Width as a count of columns + Parameters: ~ + {window} Window handle, or 0 for current window + {width} Width as a count of columns ============================================================================== Win_Config Functions *api-win_config* nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* - 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. - - 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. - - 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 > - vim.api.nvim_open_win(0, false, - {relative='win', row=3, col=3, width=12, height=3}) + 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. + + 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. + + 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 > + vim.api.nvim_open_win(0, false, + {relative='win', row=3, col=3, width=12, height=3}) < - Example (Lua): buffer-relative float (travels as buffer is - scrolled) > - vim.api.nvim_open_win(0, false, - {relative='win', width=12, height=3, bufpos={100,10}}) + Example (Lua): buffer-relative float (travels as buffer is scrolled) > + vim.api.nvim_open_win(0, false, + {relative='win', width=12, height=3, bufpos={100,10}}) < - Attributes: ~ - not allowed when |textlock| is active - - Parameters: ~ - {buffer} Buffer to display, or 0 for current buffer - {enter} Enter the window (make it the current window) - {config} Map defining the window configuration. Keys: - • relative: Sets the window layout to - "floating", placed at (row,col) coordinates - relative to: - • "editor" The global editor grid - • "win" Window given by the `win` field, or - current window. - • "cursor" Cursor position in current window. - - • win: |window-ID| for 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: - • `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 be fractional. - • focusable: Enable focus by user actions - (wincmds, mouse events). Defaults to true. - Non-focusable windows can be entered by - |nvim_set_current_win()|. - • 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 z-indices: - • 100: insert completion popupmenu - • 200: message scrollback - • 250: cmdline completion popupmenu (when - 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: Configure the appearance of the window. - Currently only takes one non-empty value: - • "minimal" Nvim will display the window with - many UI options disabled. This is useful - when displaying a temporary float where the - text should not be edited. Disables - 'number', 'relativenumber', 'cursorline', - 'cursorcolumn', 'foldcolumn', 'spell' and - 'list' options. 'signcolumn' is changed to - `auto` and 'colorcolumn' is cleared. The - end-of-buffer region is hidden by setting - `eob` flag of 'fillchars' to a space char, - and clearing the |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.). - • "solid": Adds padding by a single whitespace - cell. - • "shadow": A drop shadow effect by blending - with the background. - • If it is an array, it should have a length - of eight or any divisor of eight. The array - will specifify 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"} ]. - - • noautocmd: If true then no buffer-related - autocommand events such as |BufEnter|, - |BufLeave| or |BufWinEnter| may fire from - calling this function. - - Return: ~ - Window handle, or 0 on error + Attributes: ~ + not allowed when |textlock| is active + + Parameters: ~ + {buffer} Buffer to display, or 0 for current buffer + {enter} Enter the window (make it the current window) + {config} Map defining the window configuration. Keys: + • relative: Sets the window layout to "floating", placed at + (row,col) coordinates relative to: + • "editor" The global editor grid + • "win" Window given by the `win` field, or current + window. + • "cursor" Cursor position in current window. + + • win: |window-ID| for 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: + • `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 + be fractional. + • focusable: Enable focus by user actions (wincmds, mouse + events). Defaults to true. Non-focusable windows can be + entered by |nvim_set_current_win()|. + • 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 + z-indices: + • 100: insert completion popupmenu + • 200: message scrollback + • 250: cmdline completion popupmenu (when + 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: Configure the appearance of the window. Currently + only takes one non-empty value: + • "minimal" Nvim will display the window with many UI + options disabled. This is useful when displaying a + temporary float where the text should not be edited. + Disables 'number', 'relativenumber', 'cursorline', + 'cursorcolumn', 'foldcolumn', 'spell' and 'list' + options. 'signcolumn' is changed to `auto` and + 'colorcolumn' is cleared. The end-of-buffer region is + hidden by setting `eob` flag of 'fillchars' to a space + char, and clearing the |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.). + • "solid": Adds padding by a single whitespace cell. + • "shadow": A drop shadow effect by blending with the + background. + • If it is an array, it should have a length of eight or + any divisor of eight. The array will specifify 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"} ]. + + • noautocmd: If true then no buffer-related autocommand + events such as |BufEnter|, |BufLeave| or |BufWinEnter| may + fire from calling this function. + + Return: ~ + Window handle, or 0 on error nvim_win_get_config({window}) *nvim_win_get_config()* - Gets window configuration. + Gets window configuration. - The returned value may be given to |nvim_open_win()|. + The returned value may be given to |nvim_open_win()|. - `relative` is empty for normal windows. + `relative` is empty for normal windows. - Parameters: ~ - {window} Window handle, or 0 for current window + Parameters: ~ + {window} Window handle, or 0 for current window - Return: ~ - Map defining the window configuration, see - |nvim_open_win()| + Return: ~ + Map defining the window configuration, see |nvim_open_win()| nvim_win_set_config({window}, {*config}) *nvim_win_set_config()* - Configures window layout. Currently only for floating and - external windows (including changing a split window to those - layouts). + 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. + When reconfiguring a floating window, absent option keys will not be + changed. `row`/`col` and `relative` must be reconfigured together. - Parameters: ~ - {window} Window handle, or 0 for current window - {config} Map defining the window configuration, see - |nvim_open_win()| + Parameters: ~ + {window} Window handle, or 0 for current window + {config} Map defining the window configuration, see |nvim_open_win()| - See also: ~ - |nvim_open_win()| + See also: ~ + |nvim_open_win()| ============================================================================== Tabpage Functions *api-tabpage* nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()* - Removes a tab-scoped (t:) variable + Removes a tab-scoped (t:) variable - Parameters: ~ - {tabpage} Tabpage handle, or 0 for current tabpage - {name} Variable name + Parameters: ~ + {tabpage} Tabpage handle, or 0 for current tabpage + {name} Variable name nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()* - Gets the tabpage number + Gets the tabpage number - Parameters: ~ - {tabpage} Tabpage handle, or 0 for current tabpage + Parameters: ~ + {tabpage} Tabpage handle, or 0 for current tabpage - Return: ~ - Tabpage number + Return: ~ + Tabpage number nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()* - Gets a tab-scoped (t:) variable + Gets a tab-scoped (t:) variable - Parameters: ~ - {tabpage} Tabpage handle, or 0 for current tabpage - {name} Variable name + Parameters: ~ + {tabpage} Tabpage handle, or 0 for current tabpage + {name} Variable name - Return: ~ - Variable value + Return: ~ + Variable value nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()* - Gets the current window in a tabpage + Gets the current window in a tabpage - Parameters: ~ - {tabpage} Tabpage handle, or 0 for current tabpage + Parameters: ~ + {tabpage} Tabpage handle, or 0 for current tabpage - Return: ~ - Window handle + Return: ~ + Window handle nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()* - Checks if a tabpage is valid + Checks if a tabpage is valid - Parameters: ~ - {tabpage} Tabpage handle, or 0 for current tabpage + Parameters: ~ + {tabpage} Tabpage handle, or 0 for current tabpage - Return: ~ - true if the tabpage is valid, false otherwise + Return: ~ + true if the tabpage is valid, false otherwise nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()* - Gets the windows in a tabpage + Gets the windows in a tabpage - Parameters: ~ - {tabpage} Tabpage handle, or 0 for current tabpage + Parameters: ~ + {tabpage} Tabpage handle, or 0 for current tabpage - Return: ~ - List of windows in `tabpage` + Return: ~ + List of windows in `tabpage` *nvim_tabpage_set_var()* nvim_tabpage_set_var({tabpage}, {name}, {value}) - Sets a tab-scoped (t:) variable + Sets a tab-scoped (t:) variable - Parameters: ~ - {tabpage} Tabpage handle, or 0 for current tabpage - {name} Variable name - {value} Variable value + Parameters: ~ + {tabpage} Tabpage handle, or 0 for current tabpage + {name} Variable name + {value} Variable value ============================================================================== Autocmd Functions *api-autocmd* nvim_clear_autocmds({*opts}) *nvim_clear_autocmds()* - Clear all autocommands that match the corresponding {opts}. To - delete a particular autocmd, see |nvim_del_autocmd|. + Clear all autocommands that match the corresponding {opts}. To delete a + particular autocmd, see |nvim_del_autocmd|. - Parameters: ~ - {opts} Parameters - • event: (string|table) Examples: - • event: "pat1" - • event: { "pat1" } - • event: { "pat1", "pat2", "pat3" } + Parameters: ~ + {opts} Parameters + • event: (string|table) Examples: + • 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. + • 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} + • defaults to clearing all patterns. + • NOTE: Cannot be used with {buffer} - • buffer: (bufnr) - • clear only |autocmd-buflocal| autocommands. - • NOTE: Cannot be used with {pattern} + • 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. + • group: (string|int) The augroup name or id. + • NOTE: If not passed, will only delete autocmds not in any group. nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* - Create or get an autocommand group |autocmd-groups|. + Create or get an autocommand group |autocmd-groups|. - To get an existing group id, do: > - local id = vim.api.nvim_create_augroup("MyGroup", { - clear = false - }) + To get an existing group id, do: > + local id = vim.api.nvim_create_augroup("MyGroup", { + clear = false + }) < - Parameters: ~ - {name} String: The name of the group - {opts} Dictionary Parameters - • clear (bool) optional: defaults to true. Clear - existing commands if the group already exists - |autocmd-groups|. + Parameters: ~ + {name} String: The name of the group + {opts} Dictionary Parameters + • clear (bool) optional: defaults to true. Clear existing + commands if the group already exists |autocmd-groups|. - Return: ~ - Integer id of the created group. + Return: ~ + Integer id of the created group. - See also: ~ - |autocmd-groups| + See also: ~ + |autocmd-groups| nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* - Create an |autocommand| + Create an |autocommand| - The API allows for two (mutually exclusive) types of actions - to be executed when the autocommand triggers: a callback - function (Lua or Vimscript), or a command (like regular - autocommands). + The API allows for two (mutually exclusive) types of actions to be + executed when the autocommand triggers: a callback function (Lua or + Vimscript), or a command (like regular autocommands). - Example using callback: > - -- Lua function - local myluafun = function() print("This buffer enters") end + Example using callback: > + -- Lua function + local myluafun = function() print("This buffer enters") end - -- Vimscript function name (as a string) - local myvimfun = "g:MyVimFunction" + -- Vimscript function name (as a string) + local myvimfun = "g:MyVimFunction" - vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { - pattern = {"*.c", "*.h"}, - callback = myluafun, -- Or myvimfun - }) + vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { + pattern = {"*.c", "*.h"}, + callback = myluafun, -- Or myvimfun + }) < - Lua functions receive a table with information about the - autocmd event as an argument. To use a function which itself - accepts another (optional) parameter, wrap the function in a - lambda: + Lua functions receive a table with information about the autocmd event as + an argument. To use a function which itself accepts another (optional) + parameter, wrap the function in a lambda: > -- Lua function with an optional parameter. -- The autocmd callback would pass a table as argument but this @@ -3431,282 +3224,263 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* }) < - Example using command: > - vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { - pattern = {"*.c", "*.h"}, - command = "echo 'Entering a C or C++ file'", - }) + Example using command: > + vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { + pattern = {"*.c", "*.h"}, + command = "echo 'Entering a C or C++ file'", + }) < - Example values for pattern: > - pattern = "*.py" - pattern = { "*.py", "*.pyi" } + Example values for pattern: > + pattern = "*.py" + pattern = { "*.py", "*.pyi" } < - Example values for event: > - "BufWritePre" - {"CursorHold", "BufWritePre", "BufWritePost"} + Example values for event: > + "BufWritePre" + {"CursorHold", "BufWritePre", "BufWritePost"} < - Parameters: ~ - {event} (string|array) The event or events to register - this autocommand - {opts} Dictionary of autocommand options: - • group (string|integer) optional: the - autocommand group name or id to match against. - • pattern (string|array) optional: pattern or - patterns to match against |autocmd-pattern|. - • buffer (integer) optional: buffer number for - buffer local autocommands |autocmd-buflocal|. - Cannot be used with {pattern}. - • desc (string) optional: description of the - autocommand. - • callback (function|string) optional: if a - string, the name of a Vimscript function to - call when this autocommand is triggered. - Otherwise, a Lua function which is called when - this autocommand is triggered. Cannot be used - with {command}. Lua callbacks can return true - to delete the autocommand; in addition, they - accept a single table argument with the - following keys: - • id: (number) the autocommand id - • event: (string) the name of the event that - triggered the autocommand |autocmd-events| - • group: (number|nil) the autocommand group id, - if it exists - • match: (string) the expanded value of - |<amatch>| - • buf: (number) the expanded value of |<abuf>| - • file: (string) the expanded value of - |<afile>| - • data: (any) arbitrary data passed to - |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 id of the created autocommand. - - See also: ~ - |autocommand| - |nvim_del_autocmd()| + Parameters: ~ + {event} (string|array) The event or events to register this + autocommand + {opts} Dictionary of autocommand options: + • group (string|integer) optional: the autocommand group name + or id to match against. + • pattern (string|array) optional: pattern or patterns to + match against |autocmd-pattern|. + • buffer (integer) optional: buffer number for buffer local + autocommands |autocmd-buflocal|. Cannot be used with + {pattern}. + • desc (string) optional: description of the autocommand. + • callback (function|string) optional: if a string, the name + of a Vimscript function to call when this autocommand is + triggered. Otherwise, a Lua function which is called when + this autocommand is triggered. Cannot be used with + {command}. Lua callbacks can return true to delete the + autocommand; in addition, they accept a single table + argument with the following keys: + • id: (number) the autocommand id + • event: (string) the name of the event that triggered the + autocommand |autocmd-events| + • group: (number|nil) the autocommand group id, if it + exists + • match: (string) the expanded value of |<amatch>| + • buf: (number) the expanded value of |<abuf>| + • file: (string) the expanded value of |<afile>| + • data: (any) arbitrary data passed to + |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 id of the created autocommand. + + See also: ~ + |autocommand| + |nvim_del_autocmd()| nvim_del_augroup_by_id({id}) *nvim_del_augroup_by_id()* - Delete an autocommand group by id. + Delete an autocommand group by id. - To get a group id one can use |nvim_get_autocmds()|. + 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. + 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. - Parameters: ~ - {id} Integer The id of the group. + Parameters: ~ + {id} Integer The id of the group. - See also: ~ - |nvim_del_augroup_by_name()| - |nvim_create_augroup()| + See also: ~ + |nvim_del_augroup_by_name()| + |nvim_create_augroup()| nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()* - Delete an autocommand group by name. + 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. + 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. - Parameters: ~ - {name} String The name of the group. + Parameters: ~ + {name} String The name of the group. - See also: ~ - |autocommand-groups| + See also: ~ + |autocommand-groups| nvim_del_autocmd({id}) *nvim_del_autocmd()* - Delete an autocommand by id. + Delete an autocommand by id. - NOTE: Only autocommands created via the API have an id. + NOTE: Only autocommands created via the API have an id. - Parameters: ~ - {id} Integer The id returned by nvim_create_autocmd + Parameters: ~ + {id} Integer The id returned by nvim_create_autocmd - See also: ~ - |nvim_create_autocmd()| + See also: ~ + |nvim_create_autocmd()| nvim_exec_autocmds({event}, {*opts}) *nvim_exec_autocmds()* - Execute all autocommands for {event} that match the - corresponding {opts} |autocmd-execute|. - - Parameters: ~ - {event} (String|Array) The event or events to execute - {opts} 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. - - See also: ~ - |:doautocmd| + Execute all autocommands for {event} that match the corresponding {opts} + |autocmd-execute|. + + Parameters: ~ + {event} (String|Array) The event or events to execute + {opts} 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. + + See also: ~ + |:doautocmd| nvim_get_autocmds({*opts}) *nvim_get_autocmds()* - Get all autocommands that match the corresponding {opts}. - - These examples will get autocommands matching ALL the given - criteria: > - -- Matches all criteria - autocommands = vim.api.nvim_get_autocmds({ - group = "MyGroup", - event = {"BufEnter", "BufWinEnter"}, - pattern = {"*.c", "*.h"} - }) - - -- All commands from one group - autocommands = vim.api.nvim_get_autocmds({ - group = "MyGroup", - }) + Get all autocommands that match the corresponding {opts}. + + These examples will get autocommands matching ALL the given criteria: > + -- Matches all criteria + autocommands = vim.api.nvim_get_autocmds({ + group = "MyGroup", + event = {"BufEnter", "BufWinEnter"}, + pattern = {"*.c", "*.h"} + }) + + -- All commands from one group + autocommands = vim.api.nvim_get_autocmds({ + group = "MyGroup", + }) < - NOTE: When multiple patterns or events are provided, it will - find all the autocommands that match any combination of them. - - Parameters: ~ - {opts} Dictionary with at least one of the following: - • group (string|integer): the autocommand group - name or id to match against. - • event (string|array): event or events to match - against |autocmd-events|. - • pattern (string|array): pattern or patterns to - match against |autocmd-pattern|. - - Return: ~ - Array of autocommands matching the criteria, with each - item containing the following fields: - • id (number): the autocommand id (only when defined with - the API). - • group (integer): the autocommand group id. - • group_name (string): the autocommand group name. - • desc (string): the autocommand description. - • event (string): the autocommand event. - • command (string): the autocommand command. Note: this - will be empty if a callback is set. - • callback (function|string|nil): Lua function or name of - a Vim script function which is executed when this - autocommand is triggered. - • once (boolean): whether the autocommand is only run - once. - • pattern (string): the autocommand pattern. If the - autocommand is buffer local |autocmd-buffer-local|: - • buflocal (boolean): true if the autocommand is buffer - local. - • buffer (number): the buffer number. + NOTE: When multiple patterns or events are provided, it will find all the + autocommands that match any combination of them. + + Parameters: ~ + {opts} Dictionary with at least one of the following: + • group (string|integer): the autocommand group name or id to + match against. + • event (string|array): event or events to match against + |autocmd-events|. + • pattern (string|array): pattern or patterns to match against + |autocmd-pattern|. + + Return: ~ + Array of autocommands matching the criteria, with each item containing + the following fields: + • id (number): the autocommand id (only when defined with the API). + • group (integer): the autocommand group id. + • group_name (string): the autocommand group name. + • desc (string): the autocommand description. + • event (string): the autocommand event. + • command (string): the autocommand command. Note: this will be empty + if a callback is set. + • callback (function|string|nil): Lua function or name of a Vim script + function which is executed when this autocommand is triggered. + • once (boolean): whether the autocommand is only run once. + • pattern (string): the autocommand pattern. If the autocommand is + buffer local |autocmd-buffer-local|: + • buflocal (boolean): true if the autocommand is buffer local. + • buffer (number): the buffer number. ============================================================================== UI Functions *api-ui* nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()* - Activates UI events on the channel. + Activates UI events on the channel. - Entry point of all UI clients. Allows |--embed| to continue - startup. Implies that the client is ready to show the UI. Adds - the client to the list of UIs. |nvim_list_uis()| + Entry point of all UI clients. Allows |--embed| to continue startup. + Implies that the client is ready to show the UI. Adds the client to the + list of UIs. |nvim_list_uis()| - Note: - If multiple UI clients are attached, the global screen - dimensions degrade to the smallest client. E.g. if client - A requests 80x40 but client B requests 200x100, the global - screen has size 80x40. + Note: + If multiple UI clients are attached, the global screen dimensions + degrade to the smallest client. E.g. if client A requests 80x40 but + client B requests 200x100, the global screen has size 80x40. - Attributes: ~ - |RPC| only + Attributes: ~ + |RPC| only - Parameters: ~ - {width} Requested screen columns - {height} Requested screen rows - {options} |ui-option| map + Parameters: ~ + {width} Requested screen columns + {height} Requested screen rows + {options} |ui-option| map nvim_ui_detach() *nvim_ui_detach()* - Deactivates UI events on the channel. + Deactivates UI events on the channel. - Removes the client from the list of UIs. |nvim_list_uis()| + Removes the client from the list of UIs. |nvim_list_uis()| - Attributes: ~ - |RPC| only + Attributes: ~ + |RPC| only *nvim_ui_pum_set_bounds()* nvim_ui_pum_set_bounds({width}, {height}, {row}, {col}) - Tells Nvim the geometry of the popumenu, to align floating - windows with an external popup menu. - - Note that this method is not to be confused with - |nvim_ui_pum_set_height()|, which sets the number of visible - items in the popup menu, while this function sets the bounding - box of the popup menu, including visual elements such as - borders and sliders. Floats need not use the same font size, - nor be anchored to exact grid corners, so one can set - floating-point numbers to the popup menu geometry. - - Attributes: ~ - |RPC| only - - Parameters: ~ - {width} Popupmenu width. - {height} Popupmenu height. - {row} Popupmenu row. - {col} Popupmenu height. + Tells Nvim the geometry of the popumenu, to align floating windows with an + external popup menu. + + Note that this method is not to be confused with + |nvim_ui_pum_set_height()|, which sets the number of visible items in the + popup menu, while this function sets the bounding box of the popup menu, + including visual elements such as borders and sliders. Floats need not use + the same font size, nor be anchored to exact grid corners, so one can set + floating-point numbers to the popup menu geometry. + + Attributes: ~ + |RPC| only + + Parameters: ~ + {width} Popupmenu width. + {height} Popupmenu height. + {row} Popupmenu row. + {col} Popupmenu height. nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* - Tells Nvim the number of elements displaying in the popumenu, - to decide <PageUp> and <PageDown> movement. + Tells Nvim the number of elements displaying in the popumenu, to decide + <PageUp> and <PageDown> movement. - Attributes: ~ - |RPC| only + Attributes: ~ + |RPC| only - Parameters: ~ - {height} Popupmenu height, must be greater than zero. + Parameters: ~ + {height} Popupmenu height, must be greater than zero. nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* - TODO: Documentation + TODO: Documentation - Attributes: ~ - |RPC| only + Attributes: ~ + |RPC| only nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* - TODO: Documentation + TODO: Documentation - Attributes: ~ - |RPC| only + Attributes: ~ + |RPC| only *nvim_ui_try_resize_grid()* nvim_ui_try_resize_grid({grid}, {width}, {height}) - Tell Nvim to resize a grid. Triggers a grid_resize event with - the requested grid size or the maximum size if it exceeds size - limits. + Tell Nvim to resize a grid. Triggers a grid_resize event with the + requested grid size or the maximum size if it exceeds size limits. - On invalid grid handle, fails with error. + On invalid grid handle, fails with error. - Attributes: ~ - |RPC| only + Attributes: ~ + |RPC| only - Parameters: ~ - {grid} The handle of the grid to be changed. - {width} The new requested width. - {height} The new requested height. + Parameters: ~ + {grid} The handle of the grid to be changed. + {width} The new requested width. + {height} The new requested height. - vim:tw=78:ts=8:ft=help:norl: + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: |