diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 204 |
1 files changed, 102 insertions, 102 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 2aa147770d..dee0324a5b 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -42,9 +42,9 @@ The RPC API is like a more powerful version of Vim's "clientserver" feature. 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 -be opened by other processes connecting to TCP/IP sockets or named pipes -listened to by Nvim. +functions take an `rpc` key in the options dict. RPC channels can also be +opened by other processes connecting to TCP/IP sockets or named pipes listened +to by Nvim. Nvim creates a default RPC socket at |startup|, given by |v:servername|. To start with a TCP/IP socket instead, use |--listen| with a TCP-style address: > @@ -108,9 +108,9 @@ Basic types ~ 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 + Array kvec + Dict (msgpack: map) kvec + Object any of the above < Note: - Empty Array is accepted as a valid Dictionary parameter. @@ -708,12 +708,12 @@ nvim_eval_statusline({str}, {opts}) *nvim_eval_statusline()* line number instead of statusline. Return: ~ - Dictionary containing statusline information, with these keys: + Dict 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: + true. Each element of the array is a |Dict| with these keys: • start: (number) Byte index (0-based) of first character that uses the highlight. • group: (string) Name of highlight group. @@ -763,7 +763,7 @@ nvim_feedkeys({keys}, {mode}, {escape_ks}) *nvim_feedkeys()* 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). + 1 is the |api-metadata| map (Dict). Attributes: ~ |api-fast| @@ -779,7 +779,7 @@ nvim_get_chan_info({chan}) *nvim_get_chan_info()* • {chan} channel_id, or 0 for current channel Return: ~ - Dictionary describing a channel, with these keys: + Channel info dict with these keys: • "id" Channel id. • "argv" (optional) Job arguments list. • "stream" Stream underlying the channel. @@ -792,11 +792,11 @@ nvim_get_chan_info({chan}) *nvim_get_chan_info()* • "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. + device path like "/dev/pts/1". If unknown, the key will still be + present if a pty is used (e.g. for conpty on Windows). + • "buffer" (optional) Buffer connected to |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()|. + the RPC channel), which it provided 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 @@ -939,7 +939,7 @@ nvim_get_mode() *nvim_get_mode()* |api-fast| Return: ~ - Dictionary { "mode": String, "blocking": Boolean } + Dict { "mode": String, "blocking": Boolean } nvim_get_proc({pid}) *nvim_get_proc()* Gets info describing process `pid`. @@ -954,11 +954,11 @@ nvim_get_proc_children({pid}) *nvim_get_proc_children()* 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 + Finds files in runtime directories, in 'runtimepath' order. "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 + `nvim_get_runtime_file("colors/*.{vim,lua}", 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. @@ -996,6 +996,9 @@ nvim_input({keys}) *nvim_input()* input buffer and the call is non-blocking (input is processed asynchronously by the eventloop). + To input blocks of text, |nvim_paste()| is much faster and should be + preferred. + On execution error: does not fail, but updates v:errmsg. Note: ~ @@ -1148,21 +1151,35 @@ nvim_out_write({str}) *nvim_out_write()* • {str} Message nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* - Pastes at cursor, in any mode. + Pastes at cursor (in any mode), and sets "redo" so dot (|.|) will repeat + the input. UIs call this to implement "paste", but it's also intended for + use by scripts to input large, dot-repeatable blocks of text (as opposed + to |nvim_input()| which is subject to mappings/events and is thus much + slower). - 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. 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). + `vim.paste()`). On error or cancel, subsequent calls are ignored + ("drained") until the next paste is initiated (phase 1 or -1). + + Useful in mappings and scripts to insert multiline text. Example: >lua + vim.keymap.set('n', 'x', function() + vim.api.nvim_paste([[ + line1 + line2 + line3 + ]], false, -1) + end, { buffer = true }) +< Attributes: ~ not allowed when |textlock| is active Parameters: ~ - • {data} Multiline input. May be binary (containing NUL bytes). + • {data} Multiline input. Lines break at LF ("\n"). 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 @@ -1173,10 +1190,11 @@ nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* Return: ~ • true: Client may continue pasting. - • false: Client must cancel the paste. + • false: Client should cancel the paste. nvim_put({lines}, {type}, {after}, {follow}) *nvim_put()* - Puts text at cursor, in any mode. + Puts text at cursor, in any mode. For dot-repeatable input, use + |nvim_paste()|. Compare |:put| and |p| which are always linewise. @@ -1249,8 +1267,7 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) Parameters: ~ • {name} Short name for the connected client - • {version} Dictionary describing the version, with these (optional) - keys: + • {version} Dict describing the version, with these (optional) keys: • "major" major version (defaults to 0 if not set, for no release yet) • "minor" minor version @@ -1285,6 +1302,7 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) inclusive. • {attributes} Arbitrary string:string map of informal client properties. Suggested keys: + • "pid": Process id. • "website": Client homepage URL (e.g. GitHub repository) • "license": License description ("Apache 2", "GPLv3", @@ -1474,7 +1492,7 @@ nvim__complete_set({index}, {opts}) *nvim__complete_set()* • info: (string) info text. Return: ~ - Dictionary containing these keys: + Dict containing these keys: • winid: (number) floating window id • bufnr: (number) buffer id in floating window @@ -1516,14 +1534,14 @@ nvim__id_array({arr}) *nvim__id_array()* Return: ~ its argument. -nvim__id_dictionary({dct}) *nvim__id_dictionary()* - Returns dictionary given as argument. +nvim__id_dict({dct}) *nvim__id_dict()* + Returns dict given as argument. This API function is used for testing. One should not rely on its presence in plugins. Parameters: ~ - • {dct} Dictionary to return. + • {dct} Dict to return. Return: ~ its argument. @@ -1594,7 +1612,7 @@ nvim_call_dict_function({dict}, {fn}, {args}) On execution error: fails with Vimscript error, updates v:errmsg. Parameters: ~ - • {dict} Dictionary, or String evaluating to a Vimscript |self| dict + • {dict} Dict, or String evaluating to a Vimscript |self| dict • {fn} Name of the function defined on the Vimscript dict • {args} Function arguments packed in an Array @@ -1628,7 +1646,7 @@ nvim_command({command}) *nvim_command()* • {command} Ex command string nvim_eval({expr}) *nvim_eval()* - Evaluates a Vimscript |expression|. Dictionaries and Lists are recursively + Evaluates a Vimscript |expression|. Dicts and Lists are recursively expanded. On execution error: fails with Vimscript error, updates v:errmsg. @@ -1655,7 +1673,7 @@ nvim_exec2({src}, {opts}) *nvim_exec2()* return all (non-error, non-shell |:!|) output. Return: ~ - Dictionary containing information about execution, with these keys: + Dict containing information about execution, with these keys: • output: (string|nil) Output if `opts.output` is true. See also: ~ @@ -1692,9 +1710,9 @@ nvim_parse_expression({expr}, {flags}, {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: + • AST: top-level dict with these keys: + • "error": Dict 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. @@ -1702,7 +1720,7 @@ nvim_parse_expression({expr}, {flags}, {highlight}) 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: + • "ast": AST, either nil or a dict 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 @@ -1778,8 +1796,8 @@ nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_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 + Unlike |nvim_command()| this command takes a structured Dict instead of a + String. This allows for easier construction and manipulation of an Ex command. This also allows for things such as having spaces inside a command argument, expanding filenames in a command that otherwise doesn't expand filenames, etc. Command arguments may also be Number, Boolean or @@ -1793,8 +1811,8 @@ nvim_cmd({cmd}, {opts}) *nvim_cmd()* On execution error: fails with Vimscript 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 + • {cmd} Command to execute. Must be a Dict 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. @@ -1896,7 +1914,7 @@ nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* • {opts} Optional parameters. Reserved for future use. Return: ~ - Dictionary containing command information, with these keys: + Dict containing command information, with these keys: • cmd: (string) Command name. • range: (array) (optional) Command range (<line1> <line2>). Omitted if command doesn't accept a range. Otherwise, has no elements if no @@ -1913,15 +1931,15 @@ nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* • 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. + • magic: (dict) 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|. + • mods: (dict) |:command-modifiers|. + • filter: (dict) |:filter|. • pattern: (string) Filter pattern. Empty string if there is no filter. • force: (boolean) Whether filter is inverted or not. @@ -1958,11 +1976,11 @@ Options Functions *api-options* 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_info2()|. + The dict has the full option names as keys and option metadata dicts as + detailed at |nvim_get_option_info2()|. Return: ~ - dictionary of all options + dict of all options See also: ~ • |nvim_get_commands()| @@ -1970,7 +1988,7 @@ nvim_get_all_options_info() *nvim_get_all_options_info()* nvim_get_option_info2({name}, {opts}) *nvim_get_option_info2()* Gets the option information for one option from arbitrary buffer or window - Resulting dictionary has keys: + Resulting dict 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") @@ -2138,14 +2156,14 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* • |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. + window already shows "buffer", the window is not switched. If a window + inside the current tabpage (including a float) already shows the buffer, + then one of these windows will be set as current window temporarily. + Otherwise a temporary scratch window (called the "autocmd window" for + historical reasons) will be used. This is useful e.g. to call Vimscript functions that only work with the current buffer/window currently, like |termopen()|. @@ -2460,10 +2478,11 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, `start_row = end_row = row` and `start_col = end_col = col`. To delete the text in a range, use `replacement = {}`. - Prefer |nvim_buf_set_lines()| if you are only adding or deleting entire - lines. - - Prefer |nvim_put()| if you want to insert text at the cursor position. + Note: ~ + • Prefer |nvim_buf_set_lines()| (for performance) to add or delete + entire lines. + • Prefer |nvim_paste()| or |nvim_put()| to insert (instead of replace) + text at cursor. Attributes: ~ not allowed when |textlock| is active @@ -2476,10 +2495,6 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, • {end_col} Ending column (byte offset) on last line, exclusive • {replacement} Array of lines to use as replacement - See also: ~ - • |nvim_buf_set_lines()| - • |nvim_put()| - nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* Sets a buffer-scoped (b:) variable @@ -2758,8 +2773,6 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) • url: A URL to associate with this extmark. In the TUI, the OSC 8 control sequence is used to generate a clickable hyperlink to this URL. - • scoped: boolean (EXPERIMENTAL) enables "scoping" for the - extmark. See |nvim__win_add_ns()| Return: ~ Id of the created/updated extmark @@ -2802,7 +2815,7 @@ nvim_set_decoration_provider({ns_id}, {opts}) 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 + Similarly, return `false` in `on_win` will skip the `on_line` 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` @@ -2811,10 +2824,10 @@ nvim_set_decoration_provider({ns_id}, {opts}) Note: doing anything other than setting extmarks is considered experimental. Doing things like changing options are not explicitly forbidden, but is likely to have unexpected consequences (such as 100% CPU - consumption). doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is + consumption). Doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is quite dubious for the moment. - Note: It is not allowed to remove or update extmarks in 'on_line' + Note: It is not allowed to remove or update extmarks in `on_line` callbacks. Attributes: ~ @@ -2831,7 +2844,7 @@ nvim_set_decoration_provider({ns_id}, {opts}) ["buf", bufnr, tick] < • on_win: called when starting to redraw a specific window. > - ["win", winid, bufnr, topline, botline] + ["win", winid, bufnr, toprow, botrow] < • on_line: called for each buffer line being redrawn. (The interaction with fold lines is subject to change) > @@ -2841,41 +2854,26 @@ nvim_set_decoration_provider({ns_id}, {opts}) ["end", tick] < -nvim__win_add_ns({window}, {ns_id}) *nvim__win_add_ns()* +nvim__ns_get({ns_id}) *nvim__ns_get()* EXPERIMENTAL: this API will change in the future. - Scopes a namespace to the a window, so extmarks in the namespace will be - active only in the given window. + Get the properties for namespace Parameters: ~ - • {window} Window handle, or 0 for current window - • {ns_id} Namespace + • {ns_id} Namespace Return: ~ - true if the namespace was added, else false + Map defining the namespace properties, see |nvim__ns_set()| -nvim__win_del_ns({window}, {ns_id}) *nvim__win_del_ns()* +nvim__ns_set({ns_id}, {opts}) *nvim__ns_set()* EXPERIMENTAL: this API will change in the future. - Unscopes a namespace (un-binds it from the given scope). + Set some properties for namespace Parameters: ~ - • {window} Window handle, or 0 for current window - • {ns_id} the namespace to remove - - Return: ~ - true if the namespace was removed, else false - -nvim__win_get_ns({window}) *nvim__win_get_ns()* - EXPERIMENTAL: this API will change in the future. - - Gets the namespace scopes for a given window. - - Parameters: ~ - • {window} Window handle, or 0 for current window - - Return: ~ - a list of namespaces ids + • {ns_id} Namespace + • {opts} Optional parameters to set: + • wins: a list of windows to be scoped in ============================================================================== @@ -3097,7 +3095,7 @@ nvim_win_text_height({window}, {opts}) *nvim_win_text_height()* omitted include the whole line. Return: ~ - Dictionary containing text height information, with these keys: + Dict containing text height information, with these keys: • all: The total number of screen lines occupied by the range. • fill: The number of diff filler or virtual lines among them. @@ -3259,13 +3257,15 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* < • title: Title (optional) in window border, string or list. List should consist of `[text, highlight]` tuples. If - string, the default highlight group is `FloatTitle`. + string, or a tuple lacks a highlight, the default + highlight group is `FloatTitle`. • title_pos: Title position. Must be set with `title` option. Value can be one of "left", "center", or "right". Default is `"left"`. • footer: Footer (optional) in window border, string or list. List should consist of `[text, highlight]` tuples. - If string, the default highlight group is `FloatFooter`. + If string, or a tuple lacks a highlight, the default + highlight group is `FloatFooter`. • footer_pos: Footer position. Must be set with `footer` option. Value can be one of "left", "center", or "right". Default is `"left"`. @@ -3419,7 +3419,7 @@ nvim_create_augroup({name}, {opts}) *nvim_create_augroup()* Parameters: ~ • {name} String: The name of the group - • {opts} Dictionary Parameters + • {opts} Dict Parameters • clear (bool) optional: defaults to true. Clear existing commands if the group already exists |autocmd-groups|. @@ -3538,7 +3538,7 @@ nvim_exec_autocmds({event}, {opts}) *nvim_exec_autocmds()* Parameters: ~ • {event} (String|Array) The event or events to execute - • {opts} Dictionary of autocommand options: + • {opts} Dict of autocommand options: • group (string|integer) optional: the autocommand group name or id to match against. |autocmd-groups|. • pattern (string|array) optional: defaults to "*" @@ -3574,7 +3574,7 @@ nvim_get_autocmds({opts}) *nvim_get_autocmds()* autocommands that match any combination of them. Parameters: ~ - • {opts} Dictionary with at least one of the following: + • {opts} Dict 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 |