diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 1260 |
1 files changed, 922 insertions, 338 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 0daca0de53..c67187d857 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -59,7 +59,7 @@ Nvim instance: # trailing '&' which is required since Nvim won't process events while # running a blocking command): # - # :!./hello.rb & + # :!./hello.rb & # # Or from another shell by setting NVIM_LISTEN_ADDRESS: # $ NVIM_LISTEN_ADDRESS=[address] ./hello.rb @@ -148,9 +148,9 @@ indices, end-inclusive): 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 -will block. Non-deferred ({fast}) functions such as |nvim_get_mode()| and +will block. Non-deferred (fast) functions such as |nvim_get_mode()| and |nvim_input()| are served immediately (i.e. without waiting in the input -queue). Lua code can use |vim.in_fast_event()| to detect a {fast} context. +queue). Lua code can use |vim.in_fast_event()| to detect a fast context. ============================================================================== API metadata *api-metadata* @@ -186,7 +186,7 @@ About the `functions` map: a type name, e.g. `nvim_buf_get_lines` is the `get_lines` method of a Buffer instance. |dev-api| - Global functions have the "method=false" flag and are prefixed with just - `nvim_`, e.g. `nvim_get_buffers`. + `nvim_`, e.g. `nvim_list_bufs`. *api-mapping* External programs (clients) can use the metadata to discover the API, using @@ -426,6 +426,14 @@ Two ways to create a floating window: To close it use |nvim_win_close()| or a command such as |:close|. +To check whether a window is floating, check whether the `relative` option in +its config is non-empty: > + + if vim.api.nvim_win_get_config(window_id).relative ~= '' then + -- window with this window_id is floating + end +> + Buffer text can be highlighted by typical mechanisms (syntax highlighting, |api-highlights|). The |hl-NormalFloat| group highlights normal text; 'winhighlight' can be used as usual to override groups locally. Floats inherit @@ -434,6 +442,9 @@ to disable various visual features such as the 'number' column. Currently, floating windows don't support some widgets like scrollbar. +The output of |:mksession| does not include commands for restoring floating +windows. + Example: create a float with scratch buffer: > let buf = nvim_create_buf(v:false, v:true) @@ -452,7 +463,7 @@ Extended marks (extmarks) represent buffer annotations that track text changes in the buffer. They can represent cursors, folds, misspelled words, anything that needs to track a logical location in the buffer over time. |api-indexing| -Extmark position works like "bar" cursor: it exists between characters. Thus +Extmark position works like "bar" cursor: it exists between characters. Thus, the maximum extmark index on a line is 1 more than the character index: > f o o b a r line contents @@ -468,7 +479,7 @@ extmark position and enter some text, the extmark migrates forward. > f o o z|b a r line (| = cursor) 4 extmark (after typing "z") -If an extmark is on the last index of a line and you inputs a newline at that +If an extmark is on the last index of a line and you input a newline at that point, the extmark will accordingly migrate to the next line: > f o o z b a r| line (| = cursor) @@ -535,12 +546,12 @@ nvim__get_runtime({pat}, {all}, {*opts}) *nvim__get_runtime()* Find files in runtime directories Attributes: ~ - {fast} + |api-fast| Parameters: ~ - {pat} pattern of files to search for - {all} whether to return all matches or only the first - {options} is_lua: only search lua subdirs + {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 @@ -594,7 +605,8 @@ nvim__id_float({flt}) *nvim__id_float()* its argument. nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* - TODO: Documentation + NB: if your UI doesn't use hlstate, this will not return + hlstate first time. nvim__runtime_inspect() *nvim__runtime_inspect()* TODO: Documentation @@ -603,7 +615,7 @@ nvim__screenshot({path}) *nvim__screenshot()* TODO: Documentation Attributes: ~ - {fast} + |api-fast| nvim__set_hl_ns({ns_id}) *nvim__set_hl_ns()* Set active namespace for highlights. @@ -615,7 +627,7 @@ nvim__set_hl_ns({ns_id}) *nvim__set_hl_ns()* cycle. Attributes: ~ - {fast} + |api-fast| Parameters: ~ {ns_id} the namespace to activate @@ -626,58 +638,11 @@ nvim__stats() *nvim__stats()* Return: ~ Map of various internal stats. - *nvim_add_user_command()* -nvim_add_user_command({name}, {command}, {*opts}) - Create a new user command |user-commands| - - {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. - - Example: > - :call nvim_add_user_command('SayHello', 'echo "Hello world!"', {}) - :SayHello - Hello world! -< +nvim__unpack({str}) *nvim__unpack()* + TODO: Documentation - 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>| - • 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>| - {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. + Attributes: ~ + |api-fast| nvim_call_atomic({calls}) *nvim_call_atomic()* Calls many API methods atomically. @@ -691,6 +656,9 @@ nvim_call_atomic({calls}) *nvim_call_atomic()* 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, @@ -706,17 +674,21 @@ nvim_call_atomic({calls}) *nvim_call_atomic()* be returned. nvim_chan_send({chan}, {data}) *nvim_chan_send()* - Send data to channel `id` . For a job, it writes it to the + 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 terimal output. See - |channel-bytes| for more information. + (|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. + Attributes: ~ + |RPC| only + |vim.api| only + Parameters: ~ {chan} id of the channel {data} data to write. 8-bit clean: can contain NUL bytes. @@ -767,12 +739,6 @@ nvim_del_mark({name}) *nvim_del_mark()* |nvim_buf_del_mark()| |nvim_get_mark()| -nvim_del_user_command({name}) *nvim_del_user_command()* - Delete a user-defined command. - - Parameters: ~ - {name} Name of the command to delete. - nvim_del_var({name}) *nvim_del_var()* Removes a global (g:) variable. @@ -812,7 +778,7 @@ nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* Evaluates statusline string. Attributes: ~ - {fast} + |api-fast| Parameters: ~ {str} Statusline string (see 'statusline'). @@ -822,10 +788,14 @@ nvim_eval_statusline({str}, {*opts}) *nvim_eval_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 @@ -846,7 +816,10 @@ nvim_exec_lua({code}, {args}) *nvim_exec_lua()* inside the chunk. The chunk can return a value. Only statements are executed. To evaluate an expression, - prefix it with `return` : return my_function(...) + prefix it with `return`: return my_function(...) + + Attributes: ~ + |RPC| only Parameters: ~ {code} Lua code to execute @@ -855,7 +828,7 @@ nvim_exec_lua({code}, {args}) *nvim_exec_lua()* Return: ~ Return value of Lua code if present or NIL. -nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* +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()|. @@ -863,32 +836,25 @@ nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* On execution error: does not fail, but updates v:errmsg. To input sequences like <C-o> use |nvim_replace_termcodes()| - (typically with escape_csi=true) to replace |keycodes|, then + (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:true) + :call nvim_feedkeys(key, 'n', v:false) < Parameters: ~ - {keys} to be typed - {mode} behavior flags, see |feedkeys()| - {escape_csi} If true, escape K_SPECIAL/CSI bytes in - `keys` + {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_csi - -nvim_get_all_options_info() *nvim_get_all_options_info()* - 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|. - - Return: ~ - dictionary of all options + vim_strsave_escape_ks nvim_get_api_info() *nvim_get_api_info()* Returns a 2-tuple (Array), where item 0 is the current channel @@ -898,7 +864,8 @@ nvim_get_api_info() *nvim_get_api_info()* 2-tuple [{channel-id}, {api-metadata}] Attributes: ~ - {fast} + |api-fast| + |RPC| only nvim_get_chan_info({chan}) *nvim_get_chan_info()* Gets information about a channel. @@ -922,7 +889,7 @@ nvim_get_chan_info({chan}) *nvim_get_chan_info()* • "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 winpty on Windows). + is used (e.g. for conpty on Windows). • "buffer" (optional) Buffer with connected |terminal| instance. • "client" (optional) Info about the peer (client on the @@ -953,19 +920,6 @@ nvim_get_color_map() *nvim_get_color_map()* Return: ~ Map of color names and RGB values. -nvim_get_commands({*opts}) *nvim_get_commands()* - Gets a map of global (non-buffer-local) Ex commands. - - Currently only |user-commands| are supported, not builtin Ex - commands. - - Parameters: ~ - {opts} Optional parameters. Currently only supports - {"builtin":false} - - Return: ~ - Map of maps describing commands. - nvim_get_context({*opts}) *nvim_get_context()* Gets a map of the current editor state. @@ -1074,66 +1028,16 @@ nvim_get_mode() *nvim_get_mode()* Dictionary { "mode": String, "blocking": Boolean } Attributes: ~ - {fast} - -nvim_get_option({name}) *nvim_get_option()* - Gets the global value of an option. - - Parameters: ~ - {name} Option name - - 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 - -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. To get a buffer-local or window-local option for a - specific buffer or window, use |nvim_buf_get_option()| or - |nvim_win_get_option()|. - - Parameters: ~ - {name} Option name - {opts} Optional parameters - • scope: One of 'global' or 'local'. Analogous to - |:setglobal| and |:setlocal|, respectively. - - Return: ~ - Option value + |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. 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. @@ -1150,7 +1054,7 @@ nvim_get_runtime_file({name}, {all}) *nvim_get_runtime_file()* returned then. Attributes: ~ - {fast} + |api-fast| Parameters: ~ {name} pattern of files to search for @@ -1194,7 +1098,7 @@ nvim_input({keys}) *nvim_input()* |api-level| 6. Attributes: ~ - {fast} + |api-fast| Parameters: ~ {keys} to be typed @@ -1219,7 +1123,7 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) |nvim_input()| has the same limitation. Attributes: ~ - {fast} + |api-fast| Parameters: ~ {button} Mouse button: one of "left", "right", @@ -1242,8 +1146,8 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) nvim_list_bufs() *nvim_list_bufs()* 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 @@ -1352,7 +1256,7 @@ nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* 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 + is strictly decided by `vim.paste()`). On error, subsequent calls are ignored ("drained") until the next paste is initiated (phase 1 or -1). @@ -1405,7 +1309,7 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) {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 "\n" + {special} Replace |keycodes|, e.g. <CR> becomes a "\r" char. See also: ~ @@ -1429,7 +1333,7 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) {insert} Whether the selection should be inserted in the buffer. {finish} Finish the completion and dismiss the popupmenu. - Implies `insert` . + Implies `insert`. {opts} Optional parameters. Reserved for future use. *nvim_set_client_info()* @@ -1448,6 +1352,9 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) "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 @@ -1538,25 +1445,58 @@ nvim_set_current_win({window}) *nvim_set_current_win()* Parameters: ~ {window} Window handle -nvim_set_hl({ns_id}, {name}, {val}) *nvim_set_hl()* - Set a highlight group. +nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* + Sets a highlight group. - TODO: ns_id = 0, should modify :highlight namespace TODO val - should take update vs reset flag + 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'. - Parameters: ~ - {ns_id} number of namespace for this highlight - {name} highlight group name, like ErrorMsg - {val} highlight definition map, like - |nvim_get_hl_by_name|. in addition the following - keys are also recognized: `default` : don't - override existing definition, like `hi default` - `ctermfg` : sets foreground of cterm color - `ctermbg` : sets background of cterm color - `cterm` : cterm attribute map. sets attributed - for cterm colors. similer to `hi cterm` Note: by - default cterm attributes are same as attributes - of gui color + 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_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* Sets a global |mapping| for the given mode. @@ -1581,34 +1521,15 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* for |:map|. {lhs} Left-hand-side |{lhs}| of the mapping. {rhs} Right-hand-side |{rhs}| of the mapping. - {opts} Optional parameters map. Accepts all - |:map-arguments| as keys excluding |<buffer>| but - including |noremap| and "desc". |desc| can be used - to give a description to keymap. When called from - Lua, also accepts a "callback" key that takes a - Lua function to call when the mapping is executed. - Values are Booleans. Unknown key is an error. - -nvim_set_option({name}, {value}) *nvim_set_option()* - Sets the global value of an option. - - 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}. - - Parameters: ~ - {name} Option name - {value} New option value - {opts} Optional parameters - • scope: One of 'global' or 'local'. Analogous to - |:setglobal| and |:setlocal|, respectively. + {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. nvim_set_var({name}, {value}) *nvim_set_var()* Sets a global (g:) variable. @@ -1625,8 +1546,8 @@ nvim_set_vvar({name}, {value}) *nvim_set_vvar()* {value} Variable value nvim_strwidth({text}) *nvim_strwidth()* - Calculates the number of display cells occupied by `text` . - <Tab> counts as one cell. + Calculates the number of display cells occupied by `text`. + Control characters including <Tab> count as one cell. Parameters: ~ {text} Some text @@ -1637,12 +1558,18 @@ nvim_strwidth({text}) *nvim_strwidth()* nvim_subscribe({event}) *nvim_subscribe()* Subscribes to event broadcasts. + Attributes: ~ + |RPC| only + Parameters: ~ {event} Event type string nvim_unsubscribe({event}) *nvim_unsubscribe()* Unsubscribes to event broadcasts. + Attributes: ~ + |RPC| only + Parameters: ~ {event} Event type string @@ -1654,8 +1581,7 @@ Vimscript Functions *api-vimscript* nvim_call_dict_function({dict}, {fn}, {args}) Calls a VimL |Dictionary-function| with the given arguments. - On execution error: fails with VimL error, does not update - v:errmsg. + On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ {dict} Dictionary, or String evaluating to a VimL |self| @@ -1669,8 +1595,7 @@ nvim_call_dict_function({dict}, {fn}, {args}) nvim_call_function({fn}, {args}) *nvim_call_function()* Calls a VimL function with the given arguments. - On execution error: fails with VimL error, does not update - v:errmsg. + On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ {fn} Function to call @@ -1680,23 +1605,25 @@ nvim_call_function({fn}, {args}) *nvim_call_function()* 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, does not update - v:errmsg. + On execution error: fails with VimL error, updates v:errmsg. - Parameters: ~ - {command} Ex-command string + 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()|. - See also: ~ - |nvim_exec()| + Parameters: ~ + {command} Ex command string nvim_eval({expr}) *nvim_eval()* Evaluates a VimL |expression|. Dictionaries and Lists are recursively expanded. - On execution error: fails with VimL error, does not update - v:errmsg. + On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ {expr} VimL expression string @@ -1705,14 +1632,13 @@ nvim_eval({expr}) *nvim_eval()* Evaluation result or expanded object nvim_exec({src}, {output}) *nvim_exec()* - Executes Vimscript (multiline block of Ex-commands), like + Executes Vimscript (multiline block of Ex commands), like anonymous |:source|. Unlike |nvim_command()| this function supports heredocs, script-scope (s:), etc. - On execution error: fails with VimL error, does not update - v:errmsg. + On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ {src} Vimscript code @@ -1726,13 +1652,14 @@ nvim_exec({src}, {output}) *nvim_exec()* See also: ~ |execute()| |nvim_command()| + |nvim_cmd()| *nvim_parse_expression()* nvim_parse_expression({expr}, {flags}, {highlight}) Parse a VimL expression. Attributes: ~ - {fast} + |api-fast| Parameters: ~ {expr} Expression to parse. Always treated as a @@ -1827,6 +1754,358 @@ nvim_parse_expression({expr}, {flags}, {highlight}) ============================================================================== +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. + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer. + + 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. + + 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. + +nvim_buf_get_commands({buffer}, {*opts}) *nvim_buf_get_commands()* + Gets a map of buffer-local |user-commands|. + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {opts} Optional parameters. Currently not used. + + 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()| + + *nvim_create_user_command()* +nvim_create_user_command({name}, {command}, {*opts}) + Create a new user command |user-commands| + + {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. + + 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| + +nvim_del_user_command({name}) *nvim_del_user_command()* + Delete a user-defined command. + + 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. + + Currently only |user-commands| are supported, not builtin Ex + commands. + + Parameters: ~ + {opts} Optional parameters. Currently only supports + {"builtin":false} + + 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|. + + +============================================================================== +Options Functions *api-options* + +nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()* + Gets a buffer option value + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {name} Option name + + 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) + + 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. + + 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 + +nvim_get_option({name}) *nvim_get_option()* + Gets the global value of an option. + + Parameters: ~ + {name} Option name + + 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 + +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 + +nvim_set_option({name}, {value}) *nvim_set_option()* + Sets the global value of an option. + + 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. + +nvim_win_get_option({window}, {name}) *nvim_win_get_option()* + Gets a window option value + + Parameters: ~ + {window} Window handle, or 0 for current window + {name} Option name + + 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) + + Parameters: ~ + {window} Window handle, or 0 for current window + {name} Option name + {value} Option value + + +============================================================================== Buffer Functions *api-buffer* @@ -1852,16 +2131,6 @@ nvim__buf_redraw_range({buffer}, {first}, {last}) nvim__buf_stats({buffer}) *nvim__buf_stats()* TODO: Documentation - *nvim_buf_add_user_command()* -nvim_buf_add_user_command({buffer}, {name}, {command}, {*opts}) - Create a new user command |user-commands| in the given buffer. - - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer. - - See also: ~ - nvim_add_user_command - nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* Activates buffer-update events on a channel, or as Lua callbacks. @@ -1877,9 +2146,10 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* {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 + 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. @@ -1930,12 +2200,12 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* • on_reload: Lua callback invoked on reload. The entire buffer content should be considered changed. Args: - • the string "detach" + • the string "reload" • buffer handle • utf_sizes: include UTF-32 and UTF-16 size of the replaced region, as args to - `on_lines` . + `on_lines`. • preview: also attach to command preview (i.e. 'inccommand') events. @@ -1961,6 +2231,9 @@ nvim_buf_call({buffer}, {fun}) *nvim_buf_call()* This is useful e.g. to call vimL functions that only work with the current buffer/window currently, like |termopen()|. + Attributes: ~ + |vim.api| only + Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {fun} Function to call inside the buffer (currently @@ -1997,18 +2270,6 @@ nvim_buf_del_mark({buffer}, {name}) *nvim_buf_del_mark()* |nvim_buf_set_mark()| |nvim_del_mark()| - *nvim_buf_del_user_command()* -nvim_buf_del_user_command({buffer}, {name}) - Delete a buffer-local user-defined command. - - Only commands created with |:command-buffer| or - |nvim_buf_add_user_command()| can be deleted with this - function. - - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer. - {name} Name of the command to delete. - nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* Removes a buffer-scoped (b:) variable @@ -2033,6 +2294,9 @@ nvim_buf_delete({buffer}, {opts}) *nvim_buf_delete()* nvim_buf_detach({buffer}) *nvim_buf_detach()* Deactivates buffer-update events on the channel. + Attributes: ~ + |RPC| only + Parameters: ~ {buffer} Buffer handle, or 0 for current buffer @@ -2053,16 +2317,6 @@ nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()* Return: ~ `b:changedtick` value. -nvim_buf_get_commands({buffer}, {*opts}) *nvim_buf_get_commands()* - Gets a map of buffer-local |user-commands|. - - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {opts} Optional parameters. Currently not used. - - Return: ~ - Map of maps describing commands. - nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* Gets a list of buffer-local |mapping| definitions. @@ -2088,7 +2342,7 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {start} First line index - {end} Last line index (exclusive) + {end} Last line index, exclusive {strict_indexing} Whether out-of-bounds should be an error. @@ -2141,15 +2395,30 @@ nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()* Return: ~ Integer byte offset, or -1 for unloaded buffer. -nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()* - Gets a buffer option value + *nvim_buf_get_text()* +nvim_buf_get_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, + {opts}) + Gets a range from the buffer. + + This differs from |nvim_buf_get_lines()| in that it allows + retrieving only portions of a line. + + Indexing is zero-based. Row indices are end-inclusive, and + column indices are end-exclusive. + + Prefer |nvim_buf_get_lines()| when retrieving entire lines. Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {name} Option name + {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: ~ - Option value + 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. @@ -2185,7 +2454,7 @@ nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()* true if the buffer is valid, false otherwise. nvim_buf_line_count({buffer}) *nvim_buf_line_count()* - Gets the buffer line count + Returns the number of lines in the given buffer. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer @@ -2225,7 +2494,7 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement}) Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {start} First line index - {end} Last line index (exclusive) + {end} Last line index, exclusive {strict_indexing} Whether out-of-bounds should be an error. {replacement} Array of lines to use as replacement @@ -2261,40 +2530,33 @@ nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()* {buffer} Buffer handle, or 0 for current buffer {name} Buffer name -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) - - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {name} Option name - {value} Option value - *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 - This is recommended over nvim_buf_set_lines when only + 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 and end-exclusive. + Indexing is zero-based. Row indices are end-inclusive, and + column indices are end-exclusive. - To insert text at a given index, set `start` and `end` ranges - to the same index. To delete a range, set `replacement` to an - array containing an empty string, or simply an empty array. + 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 when adding or deleting entire lines - only. + 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_column} First column - {end_row} Last line index - {end_column} Last column - {replacement} Array of lines to use as replacement + {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 @@ -2327,7 +2589,7 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, {col_start}, 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` . + `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 @@ -2407,8 +2669,8 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) 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 + If `end` is less than `start`, traversal works backwards. + (Useful with `limit`, to get the first marks prior to a given position.) Example: @@ -2417,9 +2679,9 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) local pos = a.nvim_win_get_cursor(0) local ns = a.nvim_create_namespace('my-plugin') -- Create new extmark at line 1, column 1. - local m1 = a.nvim_buf_set_extmark(0, ns, 0, 0, 0, {}) + local m1 = a.nvim_buf_set_extmark(0, ns, 0, 0, {}) -- Create new extmark at line 3, column 1. - local m2 = a.nvim_buf_set_extmark(0, ns, 0, 2, 0, {}) + local m2 = a.nvim_buf_set_extmark(0, ns, 0, 2, {}) -- Get extmarks only from line 3. local ms = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) -- Get all marks in this buffer + namespace. @@ -2448,13 +2710,12 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) Creates or updates an extmark. - To create a new extmark, pass id=0. The extmark id will be - returned. To move an existing mark, pass its id. - - It is also allowed to create a new mark by passing in a - previously unused id, but the caller must then keep track of - existing and unused ids itself. (Useful over RPC, to avoid - waiting for the return value.) + By default a new extmark is created when no id is passed in, + but it is also possible to create a new mark by passing in a + previously unused id or move an existing mark by passing in + its id. The caller must then keep track of existing and unused + ids itself. (Useful over RPC, to avoid waiting for the return + value.) Using the optional arguments, it is possible to use this to highlight a range of text, and also to associate virtual text @@ -2548,6 +2809,44 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) • 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 @@ -2605,6 +2904,9 @@ nvim_set_decoration_provider({ns_id}, {opts}) `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: @@ -2628,6 +2930,9 @@ Window Functions *api-window* nvim_win_call({window}, {fun}) *nvim_win_call()* Calls a function with window as temporary current window. + Attributes: ~ + |vim.api| only + Parameters: ~ {window} Window handle, or 0 for current window {fun} Function to call inside the window (currently @@ -2698,16 +3003,6 @@ nvim_win_get_number({window}) *nvim_win_get_number()* Return: ~ Window number -nvim_win_get_option({window}, {name}) *nvim_win_get_option()* - Gets a window option value - - Parameters: ~ - {window} Window handle, or 0 for current window - {name} Option name - - Return: ~ - Option value - nvim_win_get_position({window}) *nvim_win_get_position()* Gets the window position in display cells. First position is zero. @@ -2751,7 +3046,7 @@ nvim_win_hide({window}) *nvim_win_hide()* |:hide| with a |window-ID|). Like |:hide| the buffer becomes hidden unless another window - is editing it, or 'bufhidden' is `unload` , `delete` or `wipe` + is editing it, or 'bufhidden' is `unload`, `delete` or `wipe` as opposed to |:close| or |nvim_win_close|, which will close the buffer. @@ -2782,29 +3077,20 @@ nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()* nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()* Sets the (1,0)-indexed cursor position in the window. - |api-indexing| + |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 nvim_win_set_height({window}, {height}) *nvim_win_set_height()* - Sets the window height. This will only succeed if the screen - is split horizontally. + Sets the window height. Parameters: ~ {window} Window handle, or 0 for current window {height} Height as a count of rows -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) - - Parameters: ~ - {window} Window handle, or 0 for current window - {name} Option name - {value} Option value - nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()* Sets a window-scoped (w:) variable @@ -2967,9 +3253,10 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* ">", "", "", "", "<" ] will only make vertical borders but not horizontal ones. By default, `FloatBorder` highlight is used, - which links to `VertSplit` when not defined. - It could also be specified by character: [ - {"+", "MyCorner"}, {"x", "MyBorder"} ]. + 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|, @@ -2999,7 +3286,7 @@ nvim_win_set_config({window}, {*config}) *nvim_win_set_config()* layouts). When reconfiguring a floating window, absent option keys will - not be changed. `row` / `col` and `relative` must be + not be changed. `row`/`col` and `relative` must be reconfigured together. Parameters: ~ @@ -3078,6 +3365,282 @@ nvim_tabpage_set_var({tabpage}, {name}, {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|. + + 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. + + • defaults to clearing all patterns. + • NOTE: Cannot be used with {buffer} + + • buffer: (bufnr) + • clear only |autocmd-buflocal| autocommands. + • NOTE: Cannot be used with {pattern} + + • group: (string|int) The augroup name or id. + • NOTE: If not passed, will only delete autocmds not in any group. + +nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* + 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 + }) +< + + 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. + + See also: ~ + |autocmd-groups| + +nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* + 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). + + Example using callback: > + -- Lua function + local myluafun = function() print("This buffer enters") end + + -- Vimscript function name (as a string) + local myvimfun = "g:MyVimFunction" + + 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 function with an optional parameter. + -- The autocmd callback would pass a table as argument but this + -- function expects number|nil + local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end + + vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { + pattern = {"*.c", "*.h"}, + callback = function() myluafun() end, + }) +< + + 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 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()| + +nvim_del_augroup_by_id({id}) *nvim_del_augroup_by_id()* + Delete an autocommand group by id. + + To get a group id one can use |nvim_get_autocmds()|. + + NOTE: behavior differs from |augroup-delete|. When deleting a + group, autocommands contained in this group will also be + deleted and cleared. This group will no longer exist. + + Parameters: ~ + {id} Integer The id of the group. + + 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. + + 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. + + See also: ~ + |autocommand-groups| + +nvim_del_autocmd({id}) *nvim_del_autocmd()* + Delete an autocommand by id. + + NOTE: Only autocommands created via the API have an id. + + Parameters: ~ + {id} Integer The id returned by 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| + +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", + }) +< + + 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()* @@ -3093,6 +3656,9 @@ nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()* A requests 80x40 but client B requests 200x100, the global screen has size 80x40. + Attributes: ~ + |RPC| only + Parameters: ~ {width} Requested screen columns {height} Requested screen rows @@ -3103,6 +3669,9 @@ nvim_ui_detach() *nvim_ui_detach()* Removes the client from the list of UIs. |nvim_list_uis()| + 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 @@ -3116,6 +3685,9 @@ nvim_ui_pum_set_bounds({width}, {height}, {row}, {col}) 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. @@ -3126,15 +3698,24 @@ 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. + Attributes: ~ + |RPC| only + Parameters: ~ {height} Popupmenu height, must be greater than zero. nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* TODO: Documentation + Attributes: ~ + |RPC| only + nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* TODO: Documentation + 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 @@ -3143,6 +3724,9 @@ nvim_ui_try_resize_grid({grid}, {width}, {height}) On invalid grid handle, fails with error. + Attributes: ~ + |RPC| only + Parameters: ~ {grid} The handle of the grid to be changed. {width} The new requested width. |