import * as denopsStd from "https://deno.land/x/denops_std@v4.1.3/function/nvim/mod.ts";
A module to provide functions of Neovim native functions.
import { Denops } from "../../mod.ts";
import * as nvimFn from "../../function/nvim/mod.ts";
export async function main(denops: Denops): Promise<void> {
// nvimFn holds functions exists only in Neovim
console.log(nvimFn.api_info(denops));
}
Functions
Returns Dictionary of |api-metadata|. View it in a nice human-readable format: :lua print(vim.inspect(vim.fn.api_info())) | |
Close a channel or a specific stream associated with it.
For a job, {stream} can be one of "stdin", "stdout",
"stderr" or "rpc" (closes stdin/stdout for a job started
with | |
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. Returns the number of bytes
written if the write succeeded, 0 otherwise.
See |channel-bytes| for more information.
{data} may be a string, string convertible, |Blob|, or a list.
If {data} is a list, the items will be joined by newlines; any
newlines in an item will be sent as NUL. To send a final
newline, include a final empty string. Example:
:call chansend(id, ["abc", "123\n456", ""])
will send "abc123456".
chansend() writes raw data, not RPC messages. If the channel
was created with | |
Returns a |Dictionary| representing the |context| at {index} from the top of the |context-stack| (see |context-dict|). If {index} is not given, it is assumed to be 0 (i.e.: top). | |
Pops and restores the |context| at the top of the |context-stack|. | |
Pushes the current editor state (|context|) on the |context-stack|. If {types} is given and is a |List| of |String|s, it specifies which |context-types| to include in the pushed context. Otherwise, all context types are included. | |
Sets the |context| at {index} from the top of the |context-stack| to that represented by {context}. {context} is a Dictionary with context data (|context-dict|). If {index} is not given, it is assumed to be 0 (i.e.: top). | |
Returns the size of the |context-stack|. | |
Adds a watcher to a dictionary. A dictionary watcher is identified by three components:
| |
Removes a watcher added with |dictwatcheradd()|. All three arguments must match the ones passed to |dictwatcheradd()| in order for the watcher to be successfully deleted. | |
f id | Returns a |String| which is a unique identifier of the
container type (|List|, |Dict|, |Blob| and |Partial|). It is
guaranteed that for the mentioned types |
Return the PID (process id) of |job-id| {job}. | |
Resize the pseudo terminal window of |job-id| {job} to {width}
columns and {height} rows.
Fails if the job was not started with | |
Spawns {cmd} as a job. If {cmd} is a List it runs directly (no 'shell'). If {cmd} is a String it runs in the 'shell', like this: :call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}']) (See |shell-unquoting| for details.) Example: :call jobstart('nvim -h', {'on_stdout':{j,d,e->append(line('.'),d)}}) Returns |job-id| on success, 0 on invalid arguments (or job table is full), -1 if {cmd}[0] or 'shell' is not executable. The returned job-id is a valid |channel-id| representing the job's stdio streams. Use |chansend()| (or |rpcnotify()| and |rpcrequest()| if "rpc" was enabled) to send data to stdin and |chanclose()| to close the streams without stopping the job. See |job-control| and |RPC|. NOTE: on Windows if {cmd} is a List:
| |
Stop |job-id| {id} by sending SIGTERM to the job process. If the process does not terminate after a timeout then SIGKILL will be sent. When the job terminates its |on_exit| handler (if any) will be invoked. See |job-control|. Returns 1 for valid job id, 0 for invalid id, including jobs have exited or stopped. | |
Waits for jobs and their |on_exit| handlers to complete. {jobs} is a List of |job-id|s to wait for. {timeout} is the maximum waiting time in milliseconds. If omitted or -1, wait forever. Timeout of 0 can be used to check the status of a job: let running = jobwait([{job-id}], 0)[0] == -1 During jobwait() callbacks for jobs not in the {jobs} list may be invoked. The screen will not redraw unless |:redraw| is invoked by a callback. Returns a list of len({jobs}) integers, where each integer is the status of the corresponding job: Exit-code, if the job exited -1 if the timeout was exceeded -2 if the job was interrupted (by |CTRL-C|) -3 if the job-id is invalid | |
Returns a |List| of |Dictionaries| describing |menus| (defined by |:menu|, |:amenu|, …), including |hidden-menus|. {path} matches a menu by name, or all menus if {path} is an empty string. Example: :echo menu_get('File','') :echo menu_get('') {modes} is a string of zero or more modes (see |maparg()| or |creating-menus| for the list of modes). "a" means "all". Example: nnoremenu &Test.Test inormal inoremenu Test.Test insert vnoremenu Test.Test x echo menu_get("") returns something like this: [ { "hidden": 0, "name": "Test", "priority": 500, "shortcut": 84, "submenus": [ { "hidden": 0, "mappings": { i": { "enabled": 1, "noremap": 1, "rhs": "insert", "sid": 1, "silent": 0 }, n": { ... }, s": { ... }, v": { ... } }, "name": "Test", "priority": 500, "shortcut": 0 } ] } ] | |
Convert a list of VimL objects to msgpack. Returned value is a
|readfile()|-style list. When {type} contains "B", a |Blob| is
returned instead. Example:
call writefile(msgpackdump([{}]), 'fname.mpack', 'b')
or, using a |Blob|:
call writefile(msgpackdump([{}], 'B'), 'fname.mpack')
This will write the single 0x80 byte to a
| |
Convert a |readfile()|-style list or a |Blob| to a list of
VimL objects.
Example:
let fname = expand('~/.config/nvim/shada/main.shada')
let mpack = readfile(fname, 'b')
let shada_objects = msgpackparse(mpack)
This will read ~/.config/nvim/shada/main.shada file to
| |
Find files in runtime directories Attributes: ~ |api-fast| Parameters: ~ {pat} pattern of files to search for {all} whether to return all matches or only the first {opts} is_lua: only search lua subdirs Return: ~ list of absolute paths to the found files | |
Returns object given as argument. This API function is used for testing. One should not rely on its presence in plugins. Parameters: ~ {obj} Object to return. Return: ~ its argument. | |
Returns array given as argument. This API function is used for testing. One should not rely on its presence in plugins. Parameters: ~ {arr} Array to return. Return: ~ its argument. | |
Returns dictionary given as argument. This API function is used for testing. One should not rely on its presence in plugins. Parameters: ~ {dct} Dictionary to return. Return: ~ its argument. | |
Returns floating-point value given as argument. This API function is used for testing. One should not rely on its presence in plugins. Parameters: ~ {flt} Value to return. Return: ~ its argument. | |
NB: if your UI doesn't use hlstate, this will not return hlstate first time. | |
Gets internal stats. Return: ~ Map of various internal stats. | |
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 | |
Activates buffer-update events on a channel, or as Lua callbacks.
Example (Lua): capture buffer updates in a global | |
call a function with buffer as temporary current buffer This temporarily switches current buffer to "buffer". If the current window already shows "buffer", the window is not switched If a window inside the current tabpage (including a float) already shows the buffer One of these windows will be set as current window temporarily. Otherwise a temporary scratch window (called the "autocmd window" for historical reasons) will be used. This 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 lua callable only) Return: ~ Return value of function. NB: will deepcopy lua values currently, use upvalues to send lua references in and out. | |
Clears namespaced objects (highlights, extmarks, virtual text) from a region. Lines are 0-indexed. |api-indexing| To clear the namespace in the entire buffer, specify line_start=0 and line_end=-1. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {ns_id} Namespace to clear, or -1 to clear all namespaces. {line_start} Start of range of lines to clear {line_end} End of range of lines to clear (exclusive) or -1 to clear to end of buffer. | |
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 | |
Removes an extmark. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {ns_id} Namespace id from |nvim_create_namespace()| {id} Extmark id Return: ~ true if the extmark was found, else false | |
Unmaps a buffer-local |mapping| for the given mode. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer See also: ~ |nvim_del_keymap()| | |
Deletes a named mark in the buffer. See |mark-motions|. Note: only deletes marks set in the buffer, if the mark is not set in the buffer it will return false. Parameters: ~ {buffer} Buffer to set the mark on {name} Mark name Return: ~ true if the mark was deleted, else false. See also: ~ |nvim_buf_set_mark()| |nvim_del_mark()| | |
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. | |
Removes a buffer-scoped (b:) variable Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {name} Variable name | |
Deletes the buffer. See |:bwipeout| Attributes: ~ not allowed when |textlock| is active Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {opts} Optional parameters. Keys: • force: Force deletion and ignore unsaved changes. • unload: Unloaded only, do not delete. See |:bunload| | |
Deactivates buffer-update events on the channel. Attributes: ~ |RPC| only Parameters: ~ {buffer} Buffer handle, or 0 for current buffer Return: ~ False if detach failed (because the buffer isn't loaded); otherwise True. See also: ~ |nvim_buf_attach()| |api-lua-detach| for detaching Lua callbacks | |
Gets a changed tick of a buffer
Parameters: ~
{buffer} Buffer handle, or 0 for current buffer
Return: ~
| |
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. | |
Gets the position (0-indexed) of an extmark. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {ns_id} Namespace id from |nvim_create_namespace()| {id} Extmark id {opts} Optional parameters. Keys: • details: Whether to include the details dict Return: ~ 0-indexed (row, col) tuple or empty list () if extmark id was absent | |
Gets extmarks in "traversal order" from a |charwise| region defined by
buffer positions (inclusive, 0-indexed |api-indexing|).
Region can be given as (row,col) tuples, or valid extmark ids (whose
positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
respectively, thus the following are equivalent:
nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
If | |
Gets a list of buffer-local |mapping| definitions. Parameters: ~ {mode} Mode short-name ("n", "i", "v", ...) {buffer} Buffer handle, or 0 for current buffer Return: ~ Array of |maparg()|-like dictionaries describing mappings. The "buffer" key holds the associated buffer handle. | |
Gets a line-range from the buffer.
Indexing is zero-based, end-exclusive. Negative indices are interpreted as
length+1+index: -1 refers to the index past the end. So to get the last
element use start=-2 and end=-1.
Out-of-bounds indices are clamped to the nearest valid value, unless
| |
Returns a tuple (row,col) representing the position of the named mark. See |mark-motions|. Marks are (1,0)-indexed. |api-indexing| Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {name} Mark name Return: ~ (row, col) tuple, (0, 0) if the mark is not set, or is an uppercase/file mark set in another buffer. See also: ~ |nvim_buf_set_mark()| |nvim_buf_del_mark()| | |
Gets the full file name for the buffer Parameters: ~ {buffer} Buffer handle, or 0 for current buffer Return: ~ Buffer name | |
Returns the byte offset of a line (0-indexed). |api-indexing| Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is one byte. 'fileformat' and 'fileencoding' are ignored. The line index just after the last line gives the total byte-count of the buffer. A final EOL byte is counted if it would be written, see 'eol'. Unlike |line2byte()|, throws error for out-of-bounds indexing. Returns -1 for unloaded buffer. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {index} Line index Return: ~ Integer byte offset, or -1 for unloaded buffer. | |
Gets a buffer option value Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {name} Option name Return: ~ Option value | |
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 {start_row} First line index {start_col} Starting column (byte offset) on first line {end_row} Last line index, inclusive {end_col} Ending column (byte offset) on last line, exclusive {opts} Optional parameters. Currently unused. Return: ~ Array of lines, or empty array for unloaded buffer. | |
Gets a buffer-scoped (b:) variable. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {name} Variable name Return: ~ Variable value | |
Checks if a buffer is valid and loaded. See |api-buffer| for more info about unloaded buffers. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer Return: ~ true if the buffer is valid and loaded, false otherwise. | |
Checks if a buffer is valid. Note: Even if a buffer is valid it may have been unloaded. See |api-buffer| for more info about unloaded buffers. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer Return: ~ true if the buffer is valid, false otherwise. | |
Returns the number of lines in the given buffer. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer Return: ~ Line count, or 0 for unloaded buffer. |api-buffer| | |
Creates or updates an extmark.
By default a new extmark is created when no id is passed in, but it is
also possible to create a new mark by passing in a previously unused id or
move an existing mark by passing in its id. The caller must then keep
track of existing and unused ids itself. (Useful over RPC, to avoid
waiting for the return value.)
Using the optional arguments, it is possible to use this to highlight a
range of text, and also to associate virtual text to the mark.
Parameters: ~
{buffer} Buffer handle, or 0 for current buffer
{ns_id} Namespace id from |nvim_create_namespace()|
{line} Line where to place the mark, 0-based. |api-indexing|
{col} Column where to place the mark, 0-based. |api-indexing|
{opts} Optional parameters.
• id : id of the extmark to edit.
• end_row : ending line of the mark, 0-based inclusive.
• end_col : ending col of the mark, 0-based exclusive.
• hl_group : name of the highlight group used to highlight
this mark.
• hl_eol : when true, for a multiline highlight covering the
EOL of a line, continue the highlight for the rest of the
screen line (just like for diff and cursorline highlight).
• virt_text : virtual text to link to this mark. A list of
[text, highlight] tuples, each representing a text chunk
with specified highlight. | |
Sets a buffer-local |mapping| for the given mode. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer See also: ~ |nvim_set_keymap()| | |
Sets (replaces) a line-range in the buffer.
Indexing is zero-based, end-exclusive. Negative indices are interpreted as
length+1+index: -1 refers to the index past the end. So to change or
delete the last element use start=-2 and end=-1.
To insert lines at a given index, set | |
Sets a named mark in the given buffer, all marks are allowed file/uppercase, visual, last change, etc. See |mark-motions|. Marks are (1,0)-indexed. |api-indexing| Note: Passing 0 as line deletes the mark Parameters: ~ {buffer} Buffer to set the mark on {name} Mark name {line} Line number {col} Column/row number {opts} Optional parameters. Reserved for future use. Return: ~ true if the mark was set, else false. See also: ~ |nvim_buf_del_mark()| |nvim_buf_get_mark()| | |
Sets the full file name for a buffer Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {name} Buffer name | |
Sets a buffer option value. Passing | |
Sets (replaces) a range in the buffer
This is recommended over |nvim_buf_set_lines()| when only modifying parts
of a line, as extmarks will be preserved on non-modified parts of the
touched lines.
Indexing is zero-based. Row indices are end-inclusive, and column indices
are end-exclusive.
To insert text at a given | |
Sets a buffer-scoped (b:) variable Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {name} Variable name {value} Variable value | |
Calls many API methods atomically. This has two main usages:
| |
Calls a VimL |Dictionary-function| with the given arguments. On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ {dict} Dictionary, or String evaluating to a VimL |self| dict {fn} Name of the function defined on the VimL dict {args} Function arguments packed in an Array Return: ~ Result of the function call | |
Calls a VimL function with the given arguments. On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ {fn} Function to call {args} Function arguments packed in an Array Return: ~ Result of the function call | |
Send data to channel | |
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 | |
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. Command arguments may also be Number, Boolean or
String.
The first argument may also be used instead of count for commands that
support it in order to make their usage simpler with |vim.cmd()|. For
example, instead of | |
Executes an Ex command. On execution error: fails with VimL error, updates v:errmsg. Prefer using |nvim_cmd()| or |nvim_exec()| over this. To evaluate multiple lines of Vim script or an Ex command directly, use |nvim_exec()|. To construct an Ex command using a structured format and then execute it, use |nvim_cmd()|. To modify an Ex command before evaluating it, use |nvim_parse_cmd()| in conjunction with |nvim_cmd()|. Parameters: ~ {command} Ex command string | |
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| | |
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 || • buf: (number) the expanded value of || • file: (string) the expanded value of || • 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()| | |
Creates a new, empty, unnamed buffer. Parameters: ~ {listed} Sets 'buflisted' {scratch} Creates a "throwaway" |scratch-buffer| for temporary work (always 'nomodified'). Also sets 'nomodeline' on the buffer. Return: ~ Buffer handle, or 0 on error See also: ~ buf_open_scratch | |
Creates a new or gets an existing one.
Namespaces are used for buffer highlights and virtual text, see
|nvim_buf_add_highlight()| and |nvim_buf_set_extmark()|.
Namespaces can be named or anonymous. If | |
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 || • fargs: (table) The args split by unescaped whitespace (when more than one argument is allowed), if any || • bang: (boolean) "true" if the command was executed with a ! modifier || • line1: (number) The starting line of the command range || • line2: (number) The final line of the command range || • range: (number) The number of items in the command range: 0, 1, or 2 || • count: (number) Any count supplied || • reg: (string) The optional register, if specified || • mods: (string) Command modifiers, if any || • 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| | |
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()| | |
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: ~ |autocmd-groups| | |
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()| | |
Deletes the current line. Attributes: ~ not allowed when |textlock| is active | |
Unmaps a global |mapping| for the given mode. To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|. See also: ~ |nvim_set_keymap()| | |
Deletes an uppercase/file named mark. See |mark-motions|. Note: fails with error if a lowercase or buffer local named mark is used. Parameters: ~ {name} Mark name Return: ~ true if the mark was deleted, else false. See also: ~ |nvim_buf_del_mark()| |nvim_get_mark()| | |
Delete a user-defined command. Parameters: ~ {name} Name of the command to delete. | |
Removes a global (g:) variable. Parameters: ~ {name} Variable name | |
Echo a message.
Parameters: ~
{chunks} A list of [text, hl_group] arrays, each representing a text
chunk with specified highlight. | |
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 | |
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() | |
Evaluates a VimL |expression|. Dictionaries and Lists are recursively expanded. On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ {expr} VimL expression string Return: ~ Evaluation result or expanded object | |
Evaluates statusline string. Attributes: ~ |api-fast| Parameters: ~ {str} Statusline string (see 'statusline'). {opts} Optional parameters. • winid: (number) |window-ID| of the window to use as context for statusline. • maxwidth: (number) Maximum width of statusline. • fillchar: (string) Character to fill blank spaces in the statusline (see 'fillchars'). Treated as single-width even if it isn't. • highlights: (boolean) Return highlight information. • use_winbar: (boolean) Evaluate winbar instead of statusline. • use_tabline: (boolean) Evaluate tabline instead of statusline. When true, {winid} is ignored. Mutually exclusive with {use_winbar}. Return: ~ Dictionary containing statusline information, with these keys: • str: (string) Characters that will be displayed on the statusline. • width: (number) Display width of the statusline. • highlights: Array containing highlight information of the statusline. Only included when the "highlights" key in {opts} is true. Each element of the array is a |Dictionary| with these keys: • start: (number) Byte index (0-based) of first character that uses the highlight. • group: (string) Name of highlight group. | |
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, updates v:errmsg.
Parameters: ~
{src} Vimscript code
{output} Capture and return all (non-error, non-shell |:!|) output
Return: ~
Output (non-error, non-shell |:!|) if | |
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 ||. • data (any): arbitrary data to send to the autocommand callback. See |nvim_create_autocmd()| for details. See also: ~ |:doautocmd| | |
Execute Lua code. Parameters (if any) are available as | |
Sends input-keys to Nvim, subject to various quirks controlled by | |
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 | |
Returns a 2-tuple (Array), where item 0 is the current channel id and item 1 is the |api-metadata| map (Dictionary). Return: ~ 2-tuple [{channel-id}, {api-metadata}] Attributes: ~ |api-fast| |RPC| only | |
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|. 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 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. | |
Gets information about a channel. Return: ~ Dictionary describing a channel, with these keys: • "id" Channel id. • "argv" (optional) Job arguments list. • "stream" Stream underlying the channel. • "stdio" stdin and stdout of this Nvim instance • "stderr" stderr of this Nvim instance • "socket" TCP/IP socket or named pipe • "job" Job with communication over its stdio. • "mode" How data received on the channel is interpreted. • "bytes" Send and receive raw bytes. • "terminal" |terminal| instance interprets ASCII sequences. • "rpc" |RPC| communication on the channel is active. • "pty" (optional) Name of pseudoterminal. On a POSIX system this is a device path like "/dev/pts/1". If the name is unknown, the key will still be present if a pty is used (e.g. for conpty on Windows). • "buffer" (optional) Buffer with connected |terminal| instance. • "client" (optional) Info about the peer (client on the other end of the RPC channel), if provided by it via |nvim_set_client_info()|. | |
Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or "#rrggbb" hexadecimal string. Example: :echo nvim_get_color_by_name("Pink") :echo nvim_get_color_by_name("#cbcbcb") Parameters: ~ {name} Color name or "#rrggbb" string Return: ~ 24-bit RGB value, or -1 for invalid argument. | |
Returns a map of color names and RGB values. Keys are color names (e.g. "Aqua") and values are 24-bit RGB color values (e.g. 65535). Return: ~ Map of color names and RGB values. | |
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. | |
Gets a map of the current editor state. Parameters: ~ {opts} Optional parameters. • types: List of |context-types| ("regs", "jumps", "bufs", "gvars", …) to gather, or empty for "all". Return: ~ map of global |context|. | |
Gets the current buffer. Return: ~ Buffer handle | |
Gets the current line. Return: ~ Current line string | |
Gets the current tabpage. Return: ~ Tabpage handle | |
Gets the current window. Return: ~ Window handle | |
Gets a highlight definition by id. |hlID()| Parameters: ~ {hl_id} Highlight id as returned by |hlID()| {rgb} Export RGB colors Return: ~ Highlight definition map See also: ~ nvim_get_hl_by_name | |
Gets a highlight definition by name. Parameters: ~ {name} Highlight group name {rgb} Export RGB colors Return: ~ Highlight definition map See also: ~ nvim_get_hl_by_id | |
Gets a highlight group by name similar to |hlID()|, but allocates a new ID if not present. | |
Gets a list of global (non-buffer-local) |mapping| definitions. Parameters: ~ {mode} Mode short-name ("n", "i", "v", ...) Return: ~ Array of |maparg()|-like dictionaries describing mappings. The "buffer" key is always zero. | |
Return a tuple (row, col, buffer, buffername) representing the position of the uppercase/file named mark. See |mark-motions|. Marks are (1,0)-indexed. |api-indexing| Note: fails with error if a lowercase or buffer local named mark is used. Parameters: ~ {name} Mark name {opts} Optional parameters. Reserved for future use. Return: ~ 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is not set. See also: ~ |nvim_buf_set_mark()| |nvim_del_mark()| | |
Gets the current mode. |mode()| "blocking" is true if Nvim is waiting for input. Return: ~ Dictionary { "mode": String, "blocking": Boolean } Attributes: ~ |api-fast| | |
Gets existing, non-anonymous namespaces. Return: ~ dict that maps from names to namespace ids. | |
Gets the global value of an option. Parameters: ~ {name} Option name Return: ~ Option value (global) | |
Gets the option information for one option Resulting dictionary has keys: • name: Name of the option (like 'filetype') • shortname: Shortened name of the option (like 'ft') • type: type of option ("string", "number" or "boolean") • default: The default value for the option • was_set: Whether the option was set. • last_set_sid: Last set script id (if any) • last_set_linenr: line number where option was set • last_set_chan: Channel where option was set (0 for local) • scope: one of "global", "win", or "buf" • global_local: whether win or buf option has a global value • commalist: List of comma separated values • flaglist: List of single char flags Parameters: ~ {name} Option name Return: ~ Option Information | |
Gets the value of an option. The behavior of this function matches that of |:set|: the local value of an option is returned if it exists; otherwise, the global value is returned. Local values always correspond to the current buffer or window, unless "buf" or "win" is set in {opts}. Parameters: ~ {name} Option name {opts} Optional parameters • scope: One of "global" or "local". Analogous to |:setglobal| and |:setlocal|, respectively. • win: |window-ID|. Used for getting window local options. • buf: Buffer number. Used for getting buffer local options. Implies {scope} is "local". Return: ~ Option value | |
Gets info describing process | |
Gets the immediate children of process | |
Find files in runtime directories "name" can contain wildcards. For example nvim_get_runtime_file("colors/*.vim", true) will return all color scheme files. Always use forward slashes (/) in the search pattern for subdirectories regardless of platform. It is not an error to not find any files. An empty array is returned then. Attributes: ~ |api-fast| Parameters: ~ {name} pattern of files to search for {all} whether to return all matches or only the first Return: ~ list of absolute paths to the found files | |
Gets a global (g:) variable. Parameters: ~ {name} Variable name Return: ~ Variable value | |
Gets a v: variable. Parameters: ~ {name} Variable name Return: ~ Variable value | |
Queues raw user-input. Unlike |nvim_feedkeys()|, this uses a low-level input buffer and the call is non-blocking (input is processed asynchronously by the eventloop). On execution error: does not fail, but updates v:errmsg. Note: |keycodes| like are translated, so "<" is special. To input a literal "<", send . Note: For mouse events use |nvim_input_mouse()|. The pseudokey form "<col,row>" is deprecated since |api-level| 6. Attributes: ~ |api-fast| Parameters: ~ {keys} to be typed Return: ~ Number of bytes actually written (can be fewer than requested if the buffer becomes full). | |
Send mouse event from GUI. Non-blocking: does not wait on any result, but queues the event to be processed soon by the event loop. Note: Currently this doesn't support "scripting" multiple mouse events by calling it multiple times in a loop: the intermediate mouse positions will be ignored. It should be used to implement real-time mouse input in a GUI. The deprecated pseudokey form ("<col,row>") of |nvim_input()| has the same limitation. Attributes: ~ |api-fast| Parameters: ~ {button} Mouse button: one of "left", "right", "middle", "wheel", "move". {action} For ordinary buttons, one of "press", "drag", "release". For the wheel, one of "up", "down", "left", "right". Ignored for "move". {modifier} String of modifiers each represented by a single char. The same specifiers are used as for a key press, except that the "-" separator is optional, so "C-A-", "c-a" and "CA" can all be used to specify Ctrl+Alt+click. {grid} Grid number if the client uses |ui-multigrid|, else 0. {row} Mouse row-position (zero-based, like redraw events) {col} Mouse column-position (zero-based, like redraw events) | |
Gets the current list of buffer handles
Includes unlisted (unloaded/deleted) buffers, like | |
Get information about all open channels. Return: ~ Array of Dictionaries, each describing a channel with the format specified at |nvim_get_chan_info()|. | |
Gets the paths contained in 'runtimepath'. Return: ~ List of paths | |
Gets the current list of tabpage handles. Return: ~ List of tabpage handles | |
Gets a list of dictionaries representing attached UIs. Return: ~ Array of UI dictionaries, each with these keys: • "height" Requested height of the UI • "width" Requested width of the UI • "rgb" true if the UI uses RGB colors (false implies |cterm-colors|) • "ext_..." Requested UI extensions, see |ui-option| • "chan" Channel id of remote UI (not present for TUI) | |
Gets the current list of window handles. Return: ~ List of window handles | |
Sets the current editor state from the given |context| map. Parameters: ~ {dict} |Context| map. | |
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. | |
Open a terminal instance in a buffer By default (and currently the only option) the terminal will not be connected to an external process. Instead, input send on the channel will be echoed directly by the terminal. This is useful to display ANSI terminal sequences returned as part of a rpc message, or similar. Note: to directly initiate the terminal using the right size, display the buffer in a configured window before calling this. For instance, for a floating display, first create an empty buffer using |nvim_create_buf()|, then display it using |nvim_open_win()|, and then call this function. Then |nvim_chan_send()| can be called immediately to process sequences in a virtual terminal having the intended size. Parameters: ~ {buffer} the buffer to use (expected to be empty) {opts} Optional parameters. • on_input: lua callback for input sent, i e keypresses in terminal mode. Note: keypresses are sent raw as they would be to the pty master end. For instance, a carriage return is sent as a "\r", not as a "\n". |textlock| applies. It is possible to call |nvim_chan_send()| directly in the callback however. ["input", term, bufnr, data] Return: ~ Channel id, or 0 on error | |
Open a new window.
Currently this is used to open floating and external windows. Floats are
windows that are drawn above the split layout, at some anchor position in
some other window. Floats can be drawn internally or by external GUI with
the |ui-multigrid| extension. External windows are only supported with
multigrid GUIs, and are displayed as separate top-level windows.
For a general overview of floats, see |api-floatwin|.
Exactly one of | |
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 | |
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) (optional) Command range (|| ||). Omitted if command doesn't accept a range. Otherwise, has no elements if no range was specified, one element if only a single range item was specified, or two elements if both range items were specified. • count: (number) (optional) Command ||. Omitted if command cannot take a count. • reg: (string) (optional) Command ||. Omitted if command cannot take a register. • bang: (boolean) Whether command contains a || (!) 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|. • horizontal: (boolean) |:horizontal|. • keepalt: (boolean) |:keepalt|. • keepjumps: (boolean) |:keepjumps|. • keepmarks: (boolean) |:keepmarks|. • keeppatterns: (boolean) |:keeppatterns|. • lockmarks: (boolean) |:lockmarks|. • noswapfile: (boolean) |:noswapfile|. • tab: (integer) |:tab|. -1 when omitted. • verbose: (integer) |:verbose|. -1 when omitted. • vertical: (boolean) |:vertical|. • split: (string) Split modifier string, is an empty string when there's no split modifier. If there is a split modifier it can be one of: • "aboveleft": |:aboveleft|. • "belowright": |:belowright|. • "topleft": |:topleft|. • "botright": |:botright|. | |
Parse a VimL expression. Attributes: ~ |api-fast| Parameters: ~ {expr} Expression to parse. Always treated as a single line. {flags} Flags: • "m" if multiple expressions in a row are allowed (only the first one will be parsed), • "E" if EOC tokens are not allowed (determines whether they will stop parsing process or be recognized as an operator/space, though also yielding an error). • "l" when needing to start parsing with lvalues for ":let" or ":for". Common flag sets: • "m" to parse like for ":echo". • "E" to parse like for "=". • empty string for ":call". • "lm" to parse for ":let". {highlight} If true, return value will also include "highlight" key containing array of 4-tuples (arrays) (Integer, Integer, Integer, String), where first three numbers define the highlighted region and represent line, starting column and ending column (latter exclusive: one should highlight region [start_col, end_col)). Return: ~ • AST: top-level dictionary with these keys: • "error": Dictionary with error, present only if parser saw some error. Contains the following keys: • "message": String, error message in printf format, translated. Must contain exactly one "%.*s". • "arg": String, error message argument. • "len": Amount of bytes successfully parsed. With flags equal to "" that should be equal to the length of expr string. (“Successfully parsed” here means “participated in AST creation”, not “till the first error”.) • "ast": AST, either nil or a dictionary with these keys: • "type": node type, one of the value names from ExprASTNodeType stringified without "kExprNode" prefix. • "start": a pair [line, column] describing where node is "started" where "line" is always 0 (will not be 0 if you will be using nvim_parse_viml() on e.g. ":let", but that is not present yet). Both elements are Integers. • "len": “length” of the node. This and "start" are there for debugging purposes primary (debugging parser and providing debug information). • "children": a list of nodes described in top/"ast". There always is zero, one or two children, key will not be present if node has no children. Maximum number of children may be found in node_maxchildren array. • Local values (present only for certain nodes): • "scope": a single Integer, specifies scope for "Option" and "PlainIdentifier" nodes. For "Option" it is one of ExprOptScope values, for "PlainIdentifier" it is one of ExprVarScope values. • "ident": identifier (without scope, if any), present for "Option", "PlainIdentifier", "PlainKey" and "Environment" nodes. • "name": Integer, register name (one character) or -1. Only present for "Register" nodes. • "cmp_type": String, comparison type, one of the value names from ExprComparisonType, stringified without "kExprCmp" prefix. Only present for "Comparison" nodes. • "ccs_strategy": String, case comparison strategy, one of the value names from ExprCaseCompareStrategy, stringified without "kCCStrategy" prefix. Only present for "Comparison" nodes. • "augmentation": String, augmentation type for "Assignment" nodes. Is either an empty string, "Add", "Subtract" or "Concat" for "=", "+=", "-=" or ".=" respectively. • "invert": Boolean, true if result of comparison needs to be inverted. Only present for "Comparison" nodes. • "ivalue": Integer, integer value for "Integer" nodes. • "fvalue": Float, floating-point value for "Float" nodes. • "svalue": String, value for "SingleQuotedString" and "DoubleQuotedString" nodes. | |
Pastes at cursor, in any mode.
Invokes the | |
Puts text at cursor, in any mode. Compare |:put| and |p| which are always linewise. Attributes: ~ not allowed when |textlock| is active Parameters: ~ {lines} |readfile()|-style list of lines. |channel-lines| {type} Edit behavior: any |getregtype()| result, or: • "b" |blockwise-visual| mode (may include width, e.g. "b3") • "c" |charwise| mode • "l" |linewise| mode • "" guess by contents, see |setreg()| {after} If true insert after cursor (like |p|), or before (like |P|). {follow} If true place cursor at end of inserted text. | |
Replaces terminal codes and |keycodes| (, , ...) in a string with
the internal representation.
Parameters: ~
{str} String to be converted.
{from_part} Legacy Vim parameter. Usually true.
{do_lt} Also translate . Ignored if | |
Selects an item in the completion popupmenu.
If |ins-completion| is not active this API call is silently ignored.
Useful for an external UI using |ui-popupmenu| to control the popupmenu
with the mouse. Can also be used in a mapping; use |:map-cmd| to
ensure the mapping doesn't end completion mode.
Parameters: ~
{item} Index (zero-based) of the item to select. Value of -1
selects nothing and restores the original text.
{insert} Whether the selection should be inserted in the buffer.
{finish} Finish the completion and dismiss the popupmenu. Implies
| |
Self-identifies the client. The client/plugin/application should call this after connecting, to provide hints about its identity and purpose, for debugging and orchestration. Can be called more than once; the caller should merge old info if appropriate. Example: library first identifies the channel, then a plugin using that library later identifies itself. Note: "Something is better than nothing". You don't need to include all the fields. Attributes: ~ |RPC| only Parameters: ~ {name} Short name for the connected client {version} Dictionary describing the version, with these (optional) keys: • "major" major version (defaults to 0 if not set, for no release yet) • "minor" minor version • "patch" patch number • "prerelease" string describing a prerelease, like "dev" or "beta1" • "commit" hash or similar identifier of commit {type} Must be one of the following values. Client libraries should default to "remote" unless overridden by the user. • "remote" remote client connected to Nvim. • "ui" gui frontend • "embedder" application using Nvim as a component (for example, IDE/editor implementing a vim mode). • "host" plugin host, typically started by nvim • "plugin" single plugin, started by nvim {methods} Builtin methods in the client. For a host, this does not include plugin methods which will be discovered later. The key should be the method name, the values are dicts with these (optional) keys (more keys may be added in future versions of Nvim, thus unknown keys are ignored. Clients must only use keys defined in this or later versions of Nvim): • "async" if true, send as a notification. If false or unspecified, use a blocking request • "nargs" Number of arguments. Could be a single integer or an array of two integers, minimum and maximum inclusive. {attributes} Arbitrary string:string map of informal client properties. Suggested keys: • "website": Client homepage URL (e.g. GitHub repository) • "license": License description ("Apache 2", "GPLv3", "MIT", …) • "logo": URI or path to image, preferably small logo or icon. .png or .svg format is preferred. | |
Sets the current buffer. Attributes: ~ not allowed when |textlock| is active Parameters: ~ {buffer} Buffer handle | |
Changes the global working directory. Parameters: ~ {dir} Directory path | |
Sets the current line. Attributes: ~ not allowed when |textlock| is active Parameters: ~ {line} Line contents | |
Sets the current tabpage. Attributes: ~ not allowed when |textlock| is active Parameters: ~ {tabpage} Tabpage handle | |
Sets the current window. Attributes: ~ not allowed when |textlock| is active Parameters: ~ {window} Window handle | |
Set or change decoration provider for a namespace
This is a very general purpose interface for having lua callbacks being
triggered during the redraw code.
The expected usage is to set extmarks for the currently redrawn buffer.
|nvim_buf_set_extmark()| can be called to add marks on a per-window or
per-lines basis. Use the | |
Sets a highlight group.
Note:
Unlike the | |
Set active namespace for highlights. This can be set for a single window, see |nvim_win_set_hl_ns()|. Parameters: ~ {ns_id} the namespace to use | |
Set active namespace for highlights while redrawing. This function meant to be called while redrawing, primarily from |nvim_set_decoration_provider()| on_win and on_line callbacks, which are allowed to change the namespace during a redraw cycle. Attributes: ~ |api-fast| Parameters: ~ {ns_id} the namespace to activate | |
Sets a global |mapping| for the given mode.
To set a buffer-local mapping, use |nvim_buf_set_keymap()|.
Unlike |:map|, leading/trailing whitespace is accepted as part of the
{lhs} or {rhs}. Empty {rhs} is ||. |keycodes| are replaced as usual.
Example:
call nvim_set_keymap('n', ' ', '', {'nowait': v:true})
is equivalent to:
nmap <Nop
Parameters: ~
{mode} Mode short-name (map command prefix: "n", "i", "v", "x", …) or
"!" for |:map!|, or empty string for |:map|.
{lhs} Left-hand-side |{lhs}| of the mapping.
{rhs} Right-hand-side |{rhs}| of the mapping.
{opts} Optional parameters map: keys are |:map-arguments|, values are
booleans (default false). Accepts all |:map-arguments| as keys
excluding || but including |:noremap| and "desc".
Unknown key is an error. "desc" can be used to give a
description to the mapping. When called from Lua, also accepts
a "callback" key that takes a Lua function to call when the
mapping is executed. When "expr" is true, "replace_keycodes"
(boolean) can be used to replace keycodes in the resulting
string (see |nvim_replace_termcodes()|), and a Lua callback
returning | |
Sets the global value of an option. Parameters: ~ {name} Option name {value} New option value | |
Sets the value of an option. The behavior of this function matches that of |:set|: for global-local options, both the global and local value are set unless otherwise specified with {scope}. Note the options {win} and {buf} cannot be used together. Parameters: ~ {name} Option name {value} New option value {opts} Optional parameters • scope: One of "global" or "local". Analogous to |:setglobal| and |:setlocal|, respectively. • win: |window-ID|. Used for setting window local option. • buf: Buffer number. Used for setting buffer local option. | |
Sets a global (g:) variable. Parameters: ~ {name} Variable name {value} Variable value | |
Sets a v: variable, if it is not readonly. Parameters: ~ {name} Variable name {value} Variable value | |
Calculates the number of display cells occupied by | |
Subscribes to event broadcasts. Attributes: ~ |RPC| only Parameters: ~ {event} Event type string | |
Removes a tab-scoped (t:) variable Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage {name} Variable name | |
Gets the tabpage number Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage Return: ~ Tabpage number | |
Gets a tab-scoped (t:) variable Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage {name} Variable name Return: ~ Variable value | |
Gets the current window in a tabpage Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage Return: ~ Window handle | |
Checks if a tabpage is valid Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage Return: ~ true if the tabpage is valid, false otherwise | |
Gets the windows in a tabpage
Parameters: ~
{tabpage} Tabpage handle, or 0 for current tabpage
Return: ~
List of windows in | |
Sets a tab-scoped (t:) variable Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage {name} Variable name {value} Variable value | |
Activates UI events on the channel. Entry point of all UI clients. Allows |--embed| to continue startup. Implies that the client is ready to show the UI. Adds the client to the list of UIs. |nvim_list_uis()| Note: If multiple UI clients are attached, the global screen dimensions degrade to the smallest client. E.g. if client A requests 80x40 but client B requests 200x100, the global screen has size 80x40. Attributes: ~ |RPC| only Parameters: ~ {width} Requested screen columns {height} Requested screen rows {options} |ui-option| map | |
Deactivates UI events on the channel. Removes the client from the list of UIs. |nvim_list_uis()| Attributes: ~ |RPC| only | |
Tells Nvim the geometry of the popupmenu, to align floating windows with an external popup menu. Note that this method is not to be confused with |nvim_ui_pum_set_height()|, which sets the number of visible items in the popup menu, while this function sets the bounding box of the popup menu, including visual elements such as borders and sliders. Floats need not use the same font size, nor be anchored to exact grid corners, so one can set floating-point numbers to the popup menu geometry. Attributes: ~ |RPC| only Parameters: ~ {width} Popupmenu width. {height} Popupmenu height. {row} Popupmenu row. {col} Popupmenu height. | |
Tells Nvim the number of elements displaying in the popupmenu, to decide and movement. Attributes: ~ |RPC| only Parameters: ~ {height} Popupmenu height, must be greater than zero. | |
TODO: Documentation Attributes: ~ |RPC| only | |
TODO: Documentation Attributes: ~ |RPC| only | |
Tell Nvim to resize a grid. Triggers a grid_resize event with the requested grid size or the maximum size if it exceeds size limits. On invalid grid handle, fails with error. Attributes: ~ |RPC| only Parameters: ~ {grid} The handle of the grid to be changed. {width} The new requested width. {height} The new requested height. | |
Unsubscribes to event broadcasts. Attributes: ~ |RPC| only Parameters: ~ {event} Event type string | |
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 lua callable only) Return: ~ Return value of function. NB: will deepcopy lua values currently, use upvalues to send lua references in and out. See also: ~ |win_execute()| |nvim_buf_call()| | |
Closes the window (like |:close| with a |window-ID|).
Attributes: ~
not allowed when |textlock| is active
Parameters: ~
{window} Window handle, or 0 for current window
{force} Behave like | |
Removes a window-scoped (w:) variable Parameters: ~ {window} Window handle, or 0 for current window {name} Variable name | |
Gets the current buffer in a window Parameters: ~ {window} Window handle, or 0 for current window Return: ~ Buffer handle | |
Gets window configuration.
The returned value may be given to |nvim_open_win()|.
| |
Gets the (1,0)-indexed cursor position in the window. |api-indexing| Parameters: ~ {window} Window handle, or 0 for current window Return: ~ (row, col) tuple | |
Gets the window height Parameters: ~ {window} Window handle, or 0 for current window Return: ~ Height as a count of rows | |
Gets the window number Parameters: ~ {window} Window handle, or 0 for current window Return: ~ Window number | |
Gets a window option value Parameters: ~ {window} Window handle, or 0 for current window {name} Option name Return: ~ Option value | |
Gets the window position in display cells. First position is zero. Parameters: ~ {window} Window handle, or 0 for current window Return: ~ (row, col) tuple with the window position | |
Gets the window tabpage Parameters: ~ {window} Window handle, or 0 for current window Return: ~ Tabpage that contains the window | |
Gets a window-scoped (w:) variable Parameters: ~ {window} Window handle, or 0 for current window {name} Variable name Return: ~ Variable value | |
Gets the window width Parameters: ~ {window} Window handle, or 0 for current window Return: ~ Width as a count of columns | |
Closes the window and hide the buffer it contains (like |:hide| with a
|window-ID|).
Like |:hide| the buffer becomes hidden unless another window is editing
it, or 'bufhidden' is | |
Checks if a window is valid Parameters: ~ {window} Window handle, or 0 for current window Return: ~ true if the window is valid, false otherwise | |
Sets the current buffer in a window, without side effects Attributes: ~ not allowed when |textlock| is active Parameters: ~ {window} Window handle, or 0 for current window {buffer} Buffer handle | |
Configures window layout. Currently only for floating and external windows
(including changing a split window to those layouts).
When reconfiguring a floating window, absent option keys will not be
changed. | |
Sets the (1,0)-indexed cursor position in the window. |api-indexing| This scrolls the window even if it is not the current one. Parameters: ~ {window} Window handle, or 0 for current window {pos} (row, col) tuple representing the new position | |
Sets the window height. Parameters: ~ {window} Window handle, or 0 for current window {height} Height as a count of rows | |
Set highlight namespace for a window. This will use highlights defined in this namespace, but fall back to global highlights (ns=0) when missing. This takes precedence over the 'winhighlight' option. Parameters: ~ {ns_id} the namespace to use | |
Sets a window option value. Passing | |
Sets a window-scoped (w:) variable Parameters: ~ {window} Window handle, or 0 for current window {name} Variable name {value} Variable value | |
Sets the window width. This will only succeed if the screen is split vertically. Parameters: ~ {window} Window handle, or 0 for current window {width} Width as a count of columns | |
Returns the single letter name of the last recorded register. Returns an empty string when nothing was recorded yet. See |q| and |Q|. | |
Sends {event} to {channel} via |RPC| and returns immediately. If {channel} is 0, the event is broadcast to all channels. Example: :au VimLeave call rpcnotify(0, "leaving") | |
Sends a request to {channel} to invoke {method} via |RPC| and blocks until a response is received. Example: :let result = rpcrequest(rpc_chan, "func", 1, 2, 3) | |
Deprecated. Replace :let id = rpcstart('prog', ['arg1', 'arg2']) with :let id = jobstart(['prog', 'arg1', 'arg2'], {'rpc': v:true}) | |
Opens a socket or named pipe at {address} and listens for |RPC| messages. Clients can send |API| commands to the returned address to control Nvim. Returns the address string (may differ from the requested {address}).
| |
Closes the pipe or socket at {address}. Returns TRUE if {address} is valid, else FALSE. If |v:servername| is stopped it is set to the next available address in |serverlist()|. | |
Connect a socket to an address. If {mode} is "pipe" then {address} should be the path of a named pipe. If {mode} is "tcp" then {address} should be of the form "host:port" where the host should be an ip adderess or host name, and port the port number. Returns a |channel| ID. Close the socket with |chanclose()|. Use |chansend()| to send data over a bytes socket, and |rpcrequest()| and |rpcnotify()| to communicate with a RPC socket. {opts} is an optional dictionary with these keys: |on_data| : callback invoked when data was read from socket data_buffered : read socket data in |channel-buffered| mode. rpc : If set, |msgpack-rpc| will be used to communicate over the socket. Returns:
| |
With |--headless| this opens stdin and stdout as a |channel|. May be called only once. See |channel-stdio|. stderr is not handled by this function, see |v:stderr|. Close the stdio handles with |chanclose()|. Use |chansend()| to send data to stdout, and |rpcrequest()| and |rpcnotify()| to communicate over RPC. {opts} is a dictionary with these keys: |on_stdin| : callback invoked when stdin is written to. on_print : callback invoked when Nvim needs to print a message, with the message (whose type is string) as sole argument. stdin_buffered : read stdin in |channel-buffered| mode. rpc : If set, |msgpack-rpc| will be used to communicate over stdio Returns:
| |
Returns |standard-path| locations of various default files and directories. {what} Type Description ~ cache String Cache directory: arbitrary temporary storage for plugins, etc. config String User configuration directory. |init.vim| is stored here. config_dirs List Other configuration directories. data String User data directory. data_dirs List Other data directories. log String Logs directory (for use by plugins too). run String Run directory: temporary, local storage for sockets, named pipes, etc. state String Session state directory: storage for file drafts, undo, |shada|, etc. Example: :echo stdpath("config") | |
Spawns {cmd} in a new pseudo-terminal session connected to the current (unmodified) buffer. Parameters and behavior are the same as |jobstart()| except "pty", "width", "height", and "TERM" are ignored: "height" and "width" are taken from the current window. Returns the same values as |jobstart()|. Terminal environment is initialized as in ||jobstart-env|, except $TERM is set to "xterm-256color". Full behavior is described in |terminal|. | |
f wait | Waits until {condition} evaluates to |TRUE|, where {condition} is a |Funcref| or |string| containing an expression. {timeout} is the maximum waiting time in milliseconds, -1 means forever. Condition is evaluated on user events, internal events, and every {interval} milliseconds (default: 200). Returns a status integer: 0 if the condition was satisfied before timeout -1 if the timeout was exceeded -2 if the function was interrupted (by |CTRL-C|) -3 if an error occurred |