diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 257 |
1 files changed, 95 insertions, 162 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index c5dabeb551..92f5a261ee 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -406,18 +406,9 @@ Another use case are plugins that show output in an append-only buffer, and want to add highlights to the outputs. Highlight data cannot be preserved on writing and loading a buffer to file, nor in undo/redo cycles. -Highlights are registered using the |nvim_buf_add_highlight()| function. If an -external highlighter plugin wants to add many highlights in a batch, -performance can be improved by calling |nvim_buf_add_highlight()| as an -asynchronous notification, after first (synchronously) requesting a source id. - -|nvim_buf_add_highlight()| adds highlights as |extmarks|. If highlights need to -be tracked or manipulated after adding them, it is better to use -|nvim_buf_set_extmark()| directly, as this function returns the placed |extmark| -id. Thus, instead of >lua - vim.api.nvim_buf_add_highlight(buf, ns_id, hl_group, line, col_start, col_end) -< -use >lua +Highlights are registered using the |nvim_buf_set_extmark()| function, which +adds highlights as |extmarks|. If highlights need to be tracked or manipulated +after adding them, the returned |extmark| id can be used. >lua -- create the highlight through an extmark extid = vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = hl_group}) @@ -428,32 +419,10 @@ use >lua vim.api.nvim_buf_set_extmark(buf, ns_id, NEW_LINE, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid}) < -Example using the Python API client (|pynvim|): ->python - src = vim.new_highlight_source() - buf = vim.current.buffer - for i in range(5): - buf.add_highlight("String",i,0,-1,src_id=src) - # some time later ... - buf.clear_namespace(src) -< -If the highlights don't need to be deleted or updated, just pass -1 as -src_id (this is the default in python). Use |nvim_buf_clear_namespace()| to -clear highlights from a specific source, in a specific line range or the -entire buffer by passing in the line range 0, -1 (the latter is the default in -python as used above). - -Example using the API from Vimscript: >vim - - call nvim_buf_set_lines(0, 0, 0, v:true, ["test text"]) - let src = nvim_buf_add_highlight(0, 0, "String", 1, 0, 4) - call nvim_buf_add_highlight(0, src, "Identifier", 0, 5, -1) - " some time later ... - call nvim_buf_clear_namespace(0, src, 0, -1) - +See also |vim.hl.range()|. ============================================================================== -Floating windows *api-floatwin* +Floating windows *api-floatwin* *floating-windows* Floating windows ("floats") are displayed on top of normal windows. This is useful to implement simple widgets, such as tooltips displayed next to the @@ -654,35 +623,22 @@ nvim_del_var({name}) *nvim_del_var()* • {name} Variable name nvim_echo({chunks}, {history}, {opts}) *nvim_echo()* - Echo a message. + Prints a message given by a list of `[text, hl_group]` "chunks". + + Example: >lua + vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {}) +< Parameters: ~ - • {chunks} A list of `[text, hl_group]` arrays, each representing a - text chunk with specified highlight group name or ID. - `hl_group` element can be omitted for no highlight. + • {chunks} List of `[text, hl_group]` pairs, where each is a `text` + string highlighted by the (optional) name or ID `hl_group`. • {history} if true, add to |message-history|. • {opts} Optional parameters. - • verbose: Message is printed as a result of 'verbose' - option. If Nvim was invoked with -V3log_file, the message - will be redirected to the log_file and suppressed from - direct output. - -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. - - 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). - - Parameters: ~ - • {str} Message - - See also: ~ - • nvim_err_write() + • err: Treat the message like `:echoerr`. Sets `hl_group` + to |hl-ErrorMsg| by default. + • verbose: Message is controlled by the 'verbose' option. + Nvim invoked with `-V3log` will write the message to the + "log" file instead of standard output. nvim_eval_statusline({str}, {opts}) *nvim_eval_statusline()* Evaluates statusline string. @@ -716,7 +672,10 @@ nvim_eval_statusline({str}, {opts}) *nvim_eval_statusline()* 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. + • group: (string) Name of highlight group. May be removed in the + future, use `groups` instead. + • groups: (array) Names of stacked highlight groups (highest + priority last). nvim_exec_lua({code}, {args}) *nvim_exec_lua()* Execute Lua code. Parameters (if any) are available as `...` inside the @@ -775,6 +734,8 @@ nvim_get_api_info() *nvim_get_api_info()* nvim_get_chan_info({chan}) *nvim_get_chan_info()* Gets information about a channel. + See |nvim_list_uis()| for an example of how to get channel info. + Parameters: ~ • {chan} channel_id, or 0 for current channel @@ -796,7 +757,7 @@ nvim_get_chan_info({chan}) *nvim_get_chan_info()* 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), which it provided via |nvim_set_client_info()|. + the channel), as set by |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 @@ -1079,6 +1040,12 @@ nvim_list_tabpages() *nvim_list_tabpages()* nvim_list_uis() *nvim_list_uis()* Gets a list of dictionaries representing attached UIs. + Example: The Nvim builtin |TUI| sets its channel info as described in + |startup-tui|. In particular, it sets `client.name` to "nvim-tui". So you + can check if the TUI is running by inspecting the client name of each UI: >lua + vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name) +< + Return: ~ Array of UI dictionaries, each with these keys: • "height" Requested height of the UI @@ -1099,22 +1066,11 @@ nvim_load_context({dict}) *nvim_load_context()* Parameters: ~ • {dict} |Context| map. -nvim_notify({msg}, {log_level}, {opts}) *nvim_notify()* - 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. - - 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 + connected to an external process. Instead, input sent 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. @@ -1125,6 +1081,17 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* |nvim_chan_send()| can be called immediately to process sequences in a virtual terminal having the intended size. + Example: this `TermHl` command can be used to display and highlight raw + ANSI termcodes, so you can use Nvim as a "scrollback pager" (for terminals + like kitty): *ansi-colorize* *terminal-scrollback-pager* >lua + vim.api.nvim_create_user_command('TermHl', function() + local b = vim.api.nvim_create_buf(false, true) + local chan = vim.api.nvim_open_term(b, {}) + vim.api.nvim_chan_send(chan, table.concat(vim.api.nvim_buf_get_lines(0, 0, -1, false), '\n')) + vim.api.nvim_win_set_buf(0, b) + end, { desc = 'Highlights ANSI termcodes in curbuf' }) +< + Attributes: ~ not allowed when |textlock| is active @@ -1143,13 +1110,6 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* 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. - - Parameters: ~ - • {str} Message - nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* 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 @@ -1248,25 +1208,23 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) *nvim_set_client_info()* nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) - Self-identifies the client. + Self-identifies the client. Sets the `client` object returned by + |nvim_get_chan_info()|. - The client/plugin/application should call this after connecting, to - provide hints about its identity and purpose, for debugging and - orchestration. + Clients should call this just after connecting, to provide hints for + debugging and orchestration. (Note: Something is better than nothing! + Fields are optional, but at least set `name`.) 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 + • {name} Client short-name. Sets the `client.name` field of + |nvim_get_chan_info()|. • {version} Dict describing the version, with these (optional) keys: • "major" major version (defaults to 0 if not set, for no release yet) @@ -1636,11 +1594,9 @@ nvim_command({command}) *nvim_command()* On execution error: fails with Vimscript error, updates v:errmsg. - Prefer using |nvim_cmd()| or |nvim_exec2()| over this. To evaluate - multiple lines of Vim script or an Ex command directly, use - |nvim_exec2()|. To construct an Ex command using a structured format and - then execute it, use |nvim_cmd()|. To modify an Ex command before - evaluating it, use |nvim_parse_cmd()| in conjunction with |nvim_cmd()|. + Prefer |nvim_cmd()| or |nvim_exec2()| instead. To modify an Ex command in + a structured way before executing it, modify the result of + |nvim_parse_cmd()| then pass it to |nvim_cmd()|. Parameters: ~ • {command} Ex command string @@ -2161,12 +2117,12 @@ nvim_buf_call({buffer}, {fun}) *nvim_buf_call()* This temporarily switches current buffer to "buffer". If the current window already shows "buffer", the window is not switched. If a window inside the current tabpage (including a float) already shows the buffer, - then one of these windows will be set as current window temporarily. + then one of those 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()|. + current buffer/window currently, like `jobstart(…, {'term': v:true})`. Attributes: ~ Lua |vim.api| only @@ -2507,42 +2463,6 @@ nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* ============================================================================== 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 - *nvim_buf_clear_namespace()* nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end}) Clears |namespace|d objects (highlights, |extmarks|, virtual text) from a @@ -2676,6 +2596,8 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) and below highlight groups can be supplied either as a string or as an integer, the latter of which can be obtained using |nvim_get_hl_id_by_name()|. + Multiple highlight groups can be stacked by passing an + array (highest priority last). • 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). @@ -2687,6 +2609,13 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) last). • virt_text_pos : position of virtual text. Possible values: • "eol": right after eol character (default). + • "eol_right_align": display right aligned in the window + unless the virtual text is longer than the space + available. If the virtual text is too long, it is + truncated to fit in the window after the EOL character. + If the line is wrapped, the virtual text is shown after + the end of the line rather than the previous screen + line. • "overlay": display over the specified column, without shifting the underlying text. • "right_align": display right aligned in the window. @@ -2780,7 +2709,7 @@ nvim_create_namespace({name}) *nvim_create_namespace()* Creates a new namespace or gets an existing one. *namespace* Namespaces are used for buffer highlights and virtual text, see - |nvim_buf_add_highlight()| and |nvim_buf_set_extmark()|. + |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 @@ -2838,8 +2767,8 @@ nvim_set_decoration_provider({ns_id}, {opts}) • on_start: called first on each screen redraw > ["start", tick] < - • on_buf: called for each buffer being redrawn (before window - callbacks) > + • on_buf: called for each buffer being redrawn (once per + edit, before window callbacks) > ["buf", bufnr, tick] < • on_win: called when starting to redraw a specific window. > @@ -3166,11 +3095,13 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* • {config} Map defining the window configuration. Keys: • relative: Sets the window layout to "floating", placed at (row,col) coordinates relative to: - • "editor" The global editor grid + • "cursor" Cursor position in current window. + • "editor" The global editor grid. + • "laststatus" 'laststatus' if present, or last row. + • "mouse" Mouse position. + • "tabline" Tabline if present, or first row. • "win" Window given by the `win` field, or current window. - • "cursor" Cursor position in current window. - • "mouse" Mouse position • win: |window-ID| window to split, or relative window when creating a float (relative="win"). • anchor: Decides which corner of the float to place at @@ -3483,9 +3414,9 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* • event: (string) name of the triggered event |autocmd-events| • group: (number|nil) autocommand group id, if any - • match: (string) expanded value of <amatch> - • buf: (number) expanded value of <abuf> - • file: (string) expanded value of <afile> + • file: (string) <afile> (not expanded to a full path) + • match: (string) <amatch> (expanded to a full path) + • buf: (number) <abuf> • data: (any) arbitrary data passed from |nvim_exec_autocmds()| *event-data* • command (string) optional: Vim command to execute on event. @@ -3580,33 +3511,35 @@ nvim_get_autocmds({opts}) *nvim_get_autocmds()* Parameters: ~ • {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 + • buffer: (integer) Buffer number or list of buffer numbers + for buffer local autocommands |autocmd-buflocal|. Cannot be + used with {pattern} + • event: (string|table) event or events to match against |autocmd-events|. - • pattern (string|array): pattern or patterns to match against + • id: (integer) Autocommand ID to match. + • group: (string|table) the autocommand group name or id to + match against. + • pattern: (string|table) pattern or patterns to match against |autocmd-pattern|. Cannot be used with {buffer} - • buffer: Buffer number or list of buffer numbers for buffer - local autocommands |autocmd-buflocal|. Cannot be used with - {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 + • buffer: (integer) the buffer number. + • buflocal: (boolean) true if the autocommand is buffer local. + • 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 + • callback: (function|string|nil): Lua function or name of a Vim + script function which is executed when this autocommand is + triggered. + • desc: (string) the autocommand description. + • event: (string) the autocommand event. + • id: (integer) the autocommand id (only when defined with the API). + • group: (integer) the autocommand group id. + • group_name: (string) the autocommand group name. + • 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. ============================================================================== |