Nvim :help pages, generated
from source
using the tree-sitter-vimdoc parser.
api
msgpack-rpc
RPC is the main way to control Nvim programmatically. Nvim implements the
MessagePack-RPC protocol with these extra (out-of-spec) constraints:
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.
nvim --listen 127.0.0.1:6666More endpoints can be started with serverstart().
#!/usr/bin/env ruby
# Requires msgpack-rpc: gem install msgpack-rpc
#
# To run this script, execute it from a running Nvim instance (notice the
# trailing '&' which is required since Nvim won't process events while
# running a blocking command):
#
# :!./hello.rb &
#
# Or from another shell by setting NVIM_LISTEN_ADDRESS:
# $ NVIM_LISTEN_ADDRESS=[address] ./hello.rb
require 'msgpack/rpc'
require 'msgpack/rpc/transport/unix'
nvim = MessagePack::RPC::Client.new(MessagePack::RPC::UNIXTransport.new, ENV['NVIM_LISTEN_ADDRESS'])
result = nvim.call(:nvim_command, 'echo "hello world!"')>>> from pynvim import attach
>>> nvim = attach('socket', path='[address]')
>>> nvim.command('echo "hello world!"')
let nvim = jobstart(['nvim', '--embed'], {'rpc': v:true})
echo rpcrequest(nvim, 'nvim_eval', '"Hello " . "world!"')
call jobstop(nvim)api-types
The Nvim C API defines custom types for all function parameters. Some are just
typedefs around C99 standard types, others are Nvim-defined data structures.
API Type C type
------------------------------------------------------------------------
Nil
Boolean bool
Integer (signed 64-bit integer) int64_t
Float (IEEE 754 double precision) double
String {char* data, size_t size} struct
Array
Dictionary (msgpack: map)
Object
types key are stable: they will not change and are
thus forward-compatible.
EXT Type C type Data ------------------------------------------------------------------------ Buffer enum value kObjectTypeBuffer |bufnr()| Window enum value kObjectTypeWindow |window-ID| Tabpage enum value kObjectTypeTabpage internal handle
api-indexing
Most of the API uses 0-based indices, and ranges are end-exclusive. For the
end of a range, -1 denotes the last line/column.
api-fast
Most API functions are "deferred": they are queued on the main loop and
processed sequentially with normal input. So if the editor is waiting for
user input in a "modal" fashion (e.g. the hit-enter-prompt), the request
will block. Non-deferred (fast) functions such as nvim_get_mode() and
nvim_input() are served immediately (i.e. without waiting in the input
queue). Lua code can use vim.in_fast_event() to detect a fast context.
api-level
(version.api_prerelease && fn.since == version.api_level)
{fn}.since API level where function {fn} was introduced
{fn}.deprecated_since API level where function {fn} was deprecated
functions map:
nvim_ plus
a type name, e.g. nvim_buf_get_lines is the get_lines method of
a Buffer instance. dev-api
nvim_, e.g. nvim_list_bufs.
api-mapping
External programs (clients) can use the metadata to discover the API, using
any of these approaches:
nvim --api-info | python -c 'import msgpack, sys, yaml; yaml.dump(msgpack.unpackb(sys.stdin.buffer.read()), sys.stdout)'
:lua vim.print(vim.fn.api_info()):new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')api_prerelease, etc. api-metadata)
{type} is a numeric id as defined by api_info().error_types, and {message} is
a string with the error message.
nvim_buf_lines_event
nvim_buf_lines_event[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}, {more}]
{firstline} and {lastline} (end-exclusive,
zero-indexed) were changed to the new text in the {linedata} list. The
granularity is a line, i.e. if a single character is changed in the
editor, the entire line is sent.
{changedtick} is v:null this means the screen lines (display)
changed but not the buffer contents. {linedata} contains the changed
screen lines. This happens when 'inccommand' shows a buffer preview.
{buf} API buffer handle (buffer number)
{changedtick} value of b:changedtick for the buffer. If you send an
API command back to nvim you can check the value of b:changedtick as
part of your request to ensure that no other changes have been made.
{firstline} integer line number of the first line that was replaced.
Zero-indexed: if line 1 was replaced then {firstline} will be 0, not
1. {firstline} is always less than or equal to the number of lines
that were in the buffer before the lines were replaced.
{lastline} integer line number of the first line that was not replaced
(i.e. the range {firstline}, {lastline} is end-exclusive).
Zero-indexed: if line numbers 2 to 5 were replaced, this will be 5
instead of 6. {lastline} is always be less than or equal to the number
of lines that were in the buffer before the lines were replaced.
{lastline} will be -1 if the event is part of the initial update after
attaching.
{linedata} list of strings containing the contents of the new buffer
lines. Newline characters are omitted; empty lines are sent as empty
strings.
{more} boolean, true for a "multipart" change notification: the
current change was chunked into multiple nvim_buf_lines_event
notifications (e.g. because it was too big).
{buf} API buffer handle (buffer number)
{changedtick} new value of b:changedtick for the buffer
{buf}] nvim_buf_detach_event
{buf} API buffer handle (buffer number)
nvim_buf_lines_event[{buf}, {changedtick}, 0, -1, [""], v:false]
User adds two lines to the buffer, emits:nvim_buf_lines_event[{buf}, {changedtick}, 0, 0, ["line1", "line2"], v:false]
User moves to a line containing the text "Hello world" and inserts "!", emits:nvim_buf_lines_event[{buf}, {changedtick}, {linenr}, {linenr} + 1,
["Hello world!"], v:false]
User moves to line 3 and deletes 20 lines using "20dd", emits:nvim_buf_lines_event[{buf}, {changedtick}, 2, 22, [], v:false]
User selects lines 3-5 using linewise-visual mode and then types "p" to
paste a block of 6 lines, emits:nvim_buf_lines_event[{buf}, {changedtick}, 2, 5,
['pasted line 1', 'pasted line 2', 'pasted line 3', 'pasted line 4',
'pasted line 5', 'pasted line 6'],
v:false
]
User reloads the buffer with ":edit", emits:nvim_buf_detach_event[{buf}]
api-buffer-updates-lua
In-process Lua plugins can receive buffer updates in the form of Lua
callbacks. These callbacks are called frequently in various contexts;
textlock prevents changing buffer contents and window layout (use
vim.schedule() to defer such operations to the main loop instead).
Moving the cursor is allowed, but it is restored afterwards.
{buf}, {changedtick}, {firstline}, {lastline},
{new_lastline}, {old_byte_size} [, {old_utf32_size}, {old_utf16_size}]).
Unlike remote channel events the text contents are not passed. The new text can
be accessed inside the callback asvim.api.nvim_buf_get_lines(buf, firstline, new_lastline, true){old_byte_size} is the total size of the replaced region {firstline} to
{lastline} in bytes, including the final newline after {lastline}. if
utf_sizes is set to true in nvim_buf_attach() keyword args, then the
UTF-32 and UTF-16 sizes of the deleted region is also passed as additional
arguments {old_utf32_size} and {old_utf16_size}.
{buf}, {changedtick}).
api-lua-detach
In-process Lua callbacks can detach by returning true. This will detach all
callbacks attached with the same nvim_buf_attach() call.
vim.api.nvim_buf_add_highlight(buf, ns_id, hl_group, line, col_start, col_end)-- 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})
-- example: modify the extmark's highlight group
vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid})
-- example: change the highlight's position
vim.api.nvim_buf_set_extmark(buf, ns_id, NEW_LINE, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid})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)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)relative option in
its config is non-empty:if vim.api.nvim_win_get_config(window_id).relative ~= '' then
-- window with this window_id is floating
endstyle=minimal in nvim_open_win()
to disable various visual features such as the 'number' column.
let buf = nvim_create_buf(v:false, v:true)
call nvim_buf_set_lines(buf, 0, -1, v:true, ["test", "text"])
let opts = {'relative': 'cursor', 'width': 10, 'height': 2, 'col': 0,
\ 'row': 1, 'anchor': 'NW', 'style': 'minimal'}
let win = nvim_open_win(buf, 0, opts)
" optional: change highlight, otherwise Pmenu is used
call nvim_set_option_value('winhl', 'Normal:MyHighlight', {'win': win})f o o b a r line contents 0 1 2 3 4 5 character positions (0-based) 0 1 2 3 4 5 6 extmark positions (0-based)Extmarks have "forward gravity": if you place the cursor directly on an extmark position and enter some text, the extmark migrates forward.
f o o|b a r line (| = cursor)
3 extmark
f o o z|b a r line (| = cursor)
4 extmark (after typing "z")
If an extmark is on the last index of a line and you input a newline at that
point, the extmark will accordingly migrate to the next line:f o o z b a r| line (| = cursor)
7 extmark
f o o z b a r first line
extmarks (none present)
| second line (| = cursor)
0 extmark (after typing <CR>)
Example:
01 2345678
0 ex|ample..
^ extmark position
let g:mark_ns = nvim_create_namespace('myplugin')
let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 2, {})echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id, {})
" => [0, 2]echo nvim_buf_get_extmarks(0, g:mark_ns, 0, -1, {})
" => [[1, 0, 2]]0 12345678 0 e|ample.. ^ extmark position
echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id, {})
" => [0, 1]{pat} pattern of files to search for
{all} whether to return all matches or only the first
{opts} is_lua: only search Lua subdirs
{obj}) nvim__id()
Returns object given as argument.
{obj} Object to return.
{arr}) nvim__id_array()
Returns array given as argument.
{arr} Array to return.
{dct}) nvim__id_dictionary()
Returns dictionary given as argument.
{dct} Dictionary to return.
{flt}) nvim__id_float()
Returns floating-point value given as argument.
{flt} Value to return.
{grid}, {row}, {col}) nvim__inspect_cell()
NB: if your UI doesn't use hlstate, this will not return hlstate first
time.
nvim__invalidate_glyph_cache()
For testing. The condition in schar_cache_clear_if_full is hard to reach,
so this function can be used to force a cache clear in a test.
nvim__stats()
Gets internal stats.
{calls}) nvim_call_atomic()
Calls many API methods atomically.
{calls} an array of calls, where each call is described by an array
with two elements: the request name, and an array of
arguments.
{chan}, {data}) nvim_chan_send()
Send data to channel id. For a job, it writes it to the stdin of the
process. For the stdio channel channel-stdio, it writes to Nvim's
stdout. For an internal terminal instance (nvim_open_term()) it writes
directly to terminal output. See channel-bytes for more information.
rpc=true then the channel expects RPC messages, use
vim.rpcnotify() and vim.rpcrequest() instead.
{chan} id of the channel
{data} data to write. 8-bit clean: can contain NUL bytes.
{listed} Sets 'buflisted'
{scratch} Creates a "throwaway" scratch-buffer for temporary work
(always 'nomodified'). Also sets 'nomodeline' on the
buffer.
nvim_del_current_line()
Deletes the current line.
{name} Mark name
{name}) nvim_del_var()
Removes a global (g:) variable.
{name} Variable name
{chunks} A list of [text, hl_group] arrays, each representing a text
chunk with specified highlight. hl_group element can be
omitted for no highlight.
{history} if true, add to message-history.
{opts} Optional parameters.
{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.
{str} Message
{str}) nvim_err_writeln()
Writes a message to the Vim error buffer. Appends "\n", so the buffer is
flushed (and displayed).
{str} Message
{str} Statusline string (see 'statusline').
{opts} Optional parameters.
{winid} is ignored. Mutually
exclusive with {use_winbar}.
{opts} is
true. Each element of the array is a Dictionary with these keys:
{code}, {args}) nvim_exec_lua()
Execute Lua code. Parameters (if any) are available as ... inside the
chunk. The chunk can return a value.
return: return my_function(...)
{code} Lua code to execute
{args} Arguments to the code
{keys}, {mode}, {escape_ks}) nvim_feedkeys()
Sends input-keys to Nvim, subject to various quirks controlled by mode
flags. This is a blocking call, unlike nvim_input().
<C-o> use nvim_replace_termcodes() (typically
with escape_ks=false) to replace keycodes, then pass the result to
nvim_feedkeys().
:let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
:call nvim_feedkeys(key, 'n', v:false){keys} to be typed
{mode} behavior flags, see feedkeys()
{escape_ks} If true, escape K_SPECIAL bytes in keys. This should be
false if you already used nvim_replace_termcodes(), and
true otherwise.
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).
{channel-id}, {api-metadata}]
{chan}) nvim_get_chan_info()
Gets information about a channel.
{name}) nvim_get_color_by_name()
Returns the 24-bit RGB value of a nvim_get_color_map() color name or
"#rrggbb" hexadecimal string.
:echo nvim_get_color_by_name("Pink")
:echo nvim_get_color_by_name("#cbcbcb"){name} Color name or "#rrggbb" string
nvim_get_color_map()
Returns a map of color names and RGB values.
{*opts}) nvim_get_context()
Gets a map of the current editor state.
{opts} Optional parameters.
nvim_get_current_buf()
Gets the current buffer.
nvim_get_current_line()
Gets the current line.
nvim_get_current_tabpage()
Gets the current tabpage.
nvim_get_current_win()
Gets the current window.
link attribute is defined in the highlight definition map,
other attributes will not be taking effect (see :hi-link).
{ns_id} Get highlight groups for namespace ns_id
nvim_get_namespaces(). Use 0 to get global highlight groups
:highlight.
{opts} Options dict:
{name}) nvim_get_hl_id_by_name()
Gets a highlight group by name
{*opts}) nvim_get_hl_ns()
Gets the active highlight namespace.
{opts} Optional parameters
{mode}) nvim_get_keymap()
Gets a list of global (non-buffer-local) mapping definitions.
{mode} Mode short-name ("n", "i", "v", ...)
{name}, {opts}) nvim_get_mark()
Returns a (row, col, buffer, buffername) tuple representing the position
of the uppercase/file named mark. "End of line" column position is
returned as v:maxcol (big number). See mark-motions.
{name} Mark name
{opts} Optional parameters. Reserved for future use.
nvim_get_mode()
Gets the current mode. mode() "blocking" is true if Nvim is waiting for
input.
{name} pattern of files to search for
{all} whether to return all matches or only the first
{name}) nvim_get_var()
Gets a global (g:) variable.
{name} Variable name
{name}) nvim_get_vvar()
Gets a v: variable.
{name} Variable name
{keys}) nvim_input()
Queues raw user-input. Unlike nvim_feedkeys(), this uses a low-level
input buffer and the call is non-blocking (input is processed
asynchronously by the eventloop).
{keys} to be typed
nvim_input_mouse()
nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col})
Send mouse event from GUI.
{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)
nvim_list_bufs()
Gets the current list of buffer handles
:ls!. Use
nvim_buf_is_loaded() to check if a buffer is loaded.
nvim_list_chans()
Get information about all open channels.
nvim_list_runtime_paths()
Gets the paths contained in runtime-search-path.
nvim_list_tabpages()
Gets the current list of tabpage handles.
nvim_list_uis()
Gets a list of dictionaries representing attached UIs.
nvim_list_wins()
Gets the current list of window handles.
{dict}) nvim_load_context()
Sets the current editor state from the given context map.
{dict} Context map.
{msg} Message to display to the user
{log_level} The log level
{opts} Reserved for future use.
{buffer} the buffer to use (expected to be empty)
{opts} Optional parameters.
{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.
{str} Message
vim.paste handler, which handles each mode appropriately.
Sets redo/undo. Faster than nvim_input(). Lines break at LF ("\n").
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).
{data} Multiline input. May be binary (containing NUL bytes).
{crlf} Also break lines at CR and CRLF.
{phase} -1: paste in a single call (i.e. without streaming). To
"stream" a paste, call nvim_paste sequentially with these phase values:
{type} Edit behavior: any getregtype() result, or:
{follow} If true place cursor at end of inserted text.
nvim_replace_termcodes()
nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
Replaces terminal codes and keycodes (<CR>, <Esc>, ...) in a string with
the internal representation.
{str} String to be converted.
{from_part} Legacy Vim parameter. Usually true.
{do_lt} Also translate <lt>. Ignored if special is false.
nvim_select_popupmenu_item()
nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts})
Selects an item in the completion popup menu.
<Cmd> :map-cmd or a Lua mapping to ensure the mapping
doesn't end completion mode.
{item} Index (zero-based) of the item to select. Value of -1
selects nothing and restores the original text.
{insert} For ins-completion, whether the selection should be
inserted in the buffer. Ignored for cmdline-completion.
{finish} Finish the completion and dismiss the popup menu. Implies
{insert}.
{opts} Optional parameters. Reserved for future use.
nvim_set_client_info()
nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
Self-identifies the client.
{name} Short name for the connected client
{version} Dictionary describing the version, with these (optional)
keys:
{type} Must be one of the following values. Client libraries
should default to "remote" unless overridden by the
user.
{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):
{attributes} Arbitrary string:string map of informal client
properties. Suggested keys:
{buffer}) nvim_set_current_buf()
Sets the current buffer.
{buffer} Buffer handle
{dir}) nvim_set_current_dir()
Changes the global working directory.
{dir} Directory path
{line}) nvim_set_current_line()
Sets the current line.
{line} Line contents
{tabpage}) nvim_set_current_tabpage()
Sets the current tabpage.
{tabpage} Tabpage handle
{window}) nvim_set_current_win()
Sets the current window.
{window} Window handle
:highlight command which can update a highlight group, this
function completely replaces the definition. For example:
nvim_set_hl(0, 'Visual', {}) will clear the highlight group
'Visual'.
"fg" or "bg" which
act as aliases to the corresponding foreground and background values
of the Normal group. If the Normal group has not been defined, using
these values results in an error.
link is used in combination with other attributes; only the link
will take effect (see :hi-link).
{ns_id} Namespace id for this highlight nvim_create_namespace().
Use 0 to set a highlight group globally :highlight.
Highlights from non-global namespaces are not active by
default, use nvim_set_hl_ns() or nvim_win_set_hl_ns() to
activate them.
{name} Highlight group name, e.g. "ErrorMsg"
{val} Highlight definition map, accepts the following keys:
{ns_id}) nvim_set_hl_ns()
Set active namespace for highlights defined with nvim_set_hl(). This can
be set for a single window, see nvim_win_set_hl_ns().
{ns_id} the namespace to use
{ns_id}) nvim_set_hl_ns_fast()
Set active namespace for highlights defined with nvim_set_hl() while
redrawing.
{ns_id} the namespace to activate
{mode}, {lhs}, {rhs}, {*opts}) nvim_set_keymap()
Sets a global mapping for the given mode.
{lhs} or {rhs}. Empty {rhs} is <Nop>. keycodes are replaced as usual.
call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})nmap <nowait> <Space><NL> <Nop>{mode} Mode short-name (map command prefix: "n", "i", "v", "x", …) or
"!" for :map!, or empty string for :map. "ia", "ca" or
"!a" for abbreviation in Insert mode, Cmdline mode, or both,
respectively
{lhs} Left-hand-side {lhs} of the mapping.
{rhs} Right-hand-side {rhs} of the mapping.
{opts} Optional parameters map: Accepts all :map-arguments as keys
except <buffer>, values are booleans (default false). Also:
{rhs}.
{name} Variable name
{value} Variable value
{name} Variable name
{value} Variable value
{text}) nvim_strwidth()
Calculates the number of display cells occupied by text. Control
characters including <Tab> count as one cell.
{text} Some text
{event}) nvim_subscribe()
Subscribes to event broadcasts.
{event} Event type string
{event}) nvim_unsubscribe()
Unsubscribes to event broadcasts.
{event} Event type string
nvim_call_dict_function()
nvim_call_dict_function({dict}, {fn}, {args})
Calls a Vimscript Dictionary-function with the given arguments.
{dict} Dictionary, 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
{fn}, {args}) nvim_call_function()
Calls a Vimscript function with the given arguments.
{fn} Function to call
{args} Function arguments packed in an Array
{command}) nvim_command()
Executes an Ex command.
{command} Ex command string
{expr}) nvim_eval()
Evaluates a Vimscript expression. Dictionaries and Lists are recursively
expanded.
{expr} Vimscript expression string
{src}, {*opts}) nvim_exec2()
Executes Vimscript (multiline block of Ex commands), like anonymous
:source.
{src} Vimscript code
{opts} Optional parameters.
opts.output is true.
nvim_parse_expression()
nvim_parse_expression({expr}, {flags}, {highlight})
Parse a Vimscript expression.
{expr} Expression to parse. Always treated as a single line.
{flags} Flags:
{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)).
nvim_buf_create_user_command()
nvim_buf_create_user_command({buffer}, {name}, {command}, {*opts})
Creates a buffer-local command user-commands.
{buffer} Buffer handle, or 0 for current buffer.
nvim_buf_del_user_command()
nvim_buf_del_user_command({buffer}, {name})
Delete a buffer-local user-defined command.
{buffer} Buffer handle, or 0 for current buffer.
{name} Name of the command to delete.
{buffer}, {*opts}) nvim_buf_get_commands()
Gets a map of buffer-local user-commands.
{buffer} Buffer handle, or 0 for current buffer
{opts} Optional parameters. Currently not used.
vim.cmd.bdelete{ count = 2 }, you may do
vim.cmd.bdelete(2).
{cmd} Command to execute. Must be a Dictionary that can contain the
same values as the return value of nvim_parse_cmd() except
"addr", "nargs" and "nextcmd" which are ignored if provided.
All values except for "cmd" are optional.
{opts} Optional parameters.
nvim_create_user_command()
nvim_create_user_command({name}, {command}, {*opts})
Creates a global user-commands command.
:call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
:SayHello
Hello world!{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:
{opts} Optional command-attributes.
{command}.
{name}) nvim_del_user_command()
Delete a user-defined command.
{name} Name of the command to delete.
{*opts}) nvim_get_commands()
Gets a map of global (non-buffer-local) Ex commands.
{opts} Optional parameters. Currently only supports {"builtin":false}
{str} Command line string to parse. Cannot contain "\n".
{opts} Optional parameters. Reserved for future use.
nvim_get_all_options_info()
Gets the option information for all options.
{name}, {*opts}) nvim_get_option_info2()
Gets the option information for one option from arbitrary buffer or window
{scope} is not provided, the last set information applies to the
local value in the current buffer or window if it is available, otherwise
the global value information is returned. This behavior can be disabled by
explicitly specifying {scope} in the {opts} table.
{name} Option name
{opts} Optional parameters
{scope} is "local".
{name}, {*opts}) nvim_get_option_value()
Gets the value of an option. The behavior of this function matches that of
:set: the local value of an option is returned if it exists; otherwise,
the global value is returned. Local values always correspond to the
current buffer or window, unless "buf" or "win" is set in {opts}.
{name} Option name
{opts} Optional parameters
{scope} is "local".
nvim_set_option_value()
nvim_set_option_value({name}, {value}, {*opts})
Sets the value of an option. The behavior of this function matches that of
:set: for global-local options, both the global and local value are set
unless otherwise specified with {scope}.
{win} and {buf} cannot be used together.
{name} Option name
{value} New option value
{opts} Optional parameters
{buffer}, {send_buffer}, {opts}) nvim_buf_attach()
Activates buffer-update events on a channel, or as Lua callbacks.
events variable (use
"vim.print(events)" to see its contents):events = {}
vim.api.nvim_buf_attach(0, false, {
on_lines = function(...)
table.insert(events, {...})
end,
}){buffer} Buffer handle, or 0 for current buffer
{send_buffer} True if the initial notification should contain the
whole buffer: first notification will be
nvim_buf_lines_event. Else the first notification
will be nvim_buf_changedtick_event. Not for Lua
callbacks.
{opts} Optional parameters.
true to detach. Args:
utf_sizes is true)
utf_sizes is true)
true to detach. Args:
on_lines.
{buffer}, {fun}) nvim_buf_call()
call a function with buffer as temporary current buffer
{buffer} Buffer handle, or 0 for current buffer
{fun} Function to call inside the buffer (currently Lua callable
only)
{buffer}, {mode}, {lhs}) nvim_buf_del_keymap()
Unmaps a buffer-local mapping for the given mode.
{buffer} Buffer handle, or 0 for current buffer
{buffer}, {name}) nvim_buf_del_mark()
Deletes a named mark in the buffer. See mark-motions.
{buffer} Buffer to set the mark on
{name} Mark name
{buffer} Buffer handle, or 0 for current buffer
{name} Variable name
{buffer} Buffer handle, or 0 for current buffer
{opts} Optional parameters. Keys:
{buffer}) nvim_buf_detach()
Deactivates buffer-update events on the channel.
{buffer} Buffer handle, or 0 for current buffer
{buffer}) nvim_buf_get_changedtick()
Gets a changed tick of a buffer
{buffer} Buffer handle, or 0 for current buffer
b:changedtick value.
{buffer}, {mode}) nvim_buf_get_keymap()
Gets a list of buffer-local mapping definitions.
{mode} Mode short-name ("n", "i", "v", ...)
{buffer} Buffer handle, or 0 for current buffer
nvim_buf_get_lines()
nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
Gets a line-range from the buffer.
strict_indexing is set.
{buffer} Buffer handle, or 0 for current buffer
{start} First line index
{end} Last line index, exclusive
{strict_indexing} Whether out-of-bounds should be an error.
{buffer}, {name}) nvim_buf_get_mark()
Returns a (row,col) tuple representing the position of the named mark.
"End of line" column position is returned as v:maxcol (big number). See
mark-motions.
{buffer} Buffer handle, or 0 for current buffer
{name} Mark name
{buffer}) nvim_buf_get_name()
Gets the full file name for the buffer
{buffer} Buffer handle, or 0 for current buffer
{buffer}, {index}) nvim_buf_get_offset()
Returns the byte offset of a line (0-indexed). api-indexing
{buffer} Buffer handle, or 0 for current buffer
{index} Line index
nvim_buf_get_text()
nvim_buf_get_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
{opts})
Gets a range from the buffer.
{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.
{buffer} Buffer handle, or 0 for current buffer
{name} Variable name
{buffer}) nvim_buf_is_loaded()
Checks if a buffer is valid and loaded. See api-buffer for more info
about unloaded buffers.
{buffer} Buffer handle, or 0 for current buffer
{buffer}) nvim_buf_is_valid()
Checks if a buffer is valid.
{buffer} Buffer handle, or 0 for current buffer
{buffer}) nvim_buf_line_count()
Returns the number of lines in the given buffer.
{buffer} Buffer handle, or 0 for current buffer
nvim_buf_set_keymap()
nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {*opts})
Sets a buffer-local mapping for the given mode.
{buffer} Buffer handle, or 0 for current buffer
nvim_buf_set_lines()
nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement})
Sets (replaces) a line-range in the buffer.
start and end to the same index.
To delete a range of lines, set replacement to an empty array.
strict_indexing is set.
{buffer} Buffer handle, or 0 for current buffer
{start} First line index
{end} Last line index, exclusive
{strict_indexing} Whether out-of-bounds should be an error.
{replacement} Array of lines to use as replacement
nvim_buf_set_mark()
nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {opts})
Sets a named mark in the given buffer, all marks are allowed
file/uppercase, visual, last change, etc. See mark-motions.
{buffer} Buffer to set the mark on
{name} Mark name
{line} Line number
{col} Column/row number
{opts} Optional parameters. Reserved for future use.
{buffer} Buffer handle, or 0 for current buffer
{name} Buffer name
nvim_buf_set_text()
nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
{replacement})
Sets (replaces) a range in the buffer
(row, column) location, usestart_row =
end_row = row` and start_col = end_col = col. To delete the text in a
range, use replacement = {}.
{buffer} Buffer handle, or 0 for current buffer
{start_row} First line index
{start_col} Starting column (byte offset) on first line
{end_row} Last line index, inclusive
{end_col} Ending column (byte offset) on last line, exclusive
{replacement} Array of lines to use as replacement
{buffer} Buffer handle, or 0 for current buffer
{name} Variable name
{value} Variable value
nvim_buf_add_highlight()
nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, {col_start},
{col_end})
Adds a highlight to buffer.
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.
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.
{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
nvim_buf_clear_namespace()
nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end})
Clears namespaced objects (highlights, extmarks, virtual text) from a
region.
{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.
{buffer} Buffer handle, or 0 for current buffer
{ns_id} Namespace id from nvim_create_namespace()
{id} Extmark id
nvim_buf_get_extmark_by_id()
nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts})
Gets the position (0-indexed) of an extmark.
{buffer} Buffer handle, or 0 for current buffer
{ns_id} Namespace id from nvim_create_namespace()
{id} Extmark id
{opts} Optional parameters. Keys:
nvim_buf_get_extmarks()
nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {*opts})
Gets extmarks (including signs) in "traversal order" from a charwise
region defined by buffer positions (inclusive, 0-indexed api-indexing).
vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {})end is less than start, traversal works backwards. (Useful with
limit, to get the first marks prior to a given position.)
overlap option might be useful. Otherwise only the start position of
an extmark will be considered.
local api = vim.api
local pos = api.nvim_win_get_cursor(0)
local ns = api.nvim_create_namespace('my-plugin')
-- Create new extmark at line 1, column 1.
local m1 = api.nvim_buf_set_extmark(0, ns, 0, 0, {})
-- Create new extmark at line 3, column 1.
local m2 = api.nvim_buf_set_extmark(0, ns, 2, 0, {})
-- Get extmarks only from line 3.
local ms = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
-- Get all marks in this buffer + namespace.
local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {})
vim.print(ms){buffer} Buffer handle, or 0 for current buffer
{ns_id} Namespace id from nvim_create_namespace() or -1 for all
namespaces
{start} Start of range: a 0-indexed (row, col) or valid extmark id
(whose position defines the bound). api-indexing
{end} End of range (inclusive): a 0-indexed (row, col) or valid
extmark id (whose position defines the bound).
api-indexing
{opts} Optional parameters. Keys:
start
nvim_buf_set_extmark()
nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts})
Creates or updates an extmark.
end_col and end_row should be
after the start position in order for the extmark to cover a range. An
earlier end position is not an error, but then it behaves like an empty
range (no highlighting).
{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.
highlight element can either
be a single highlight group, or an array of multiple
highlight groups that will be stacked (highest priority
last). A highlight group can be supplied either as a
string or as an integer, the latter which can be obtained
using nvim_get_hl_id_by_name().
hl_group in later versions.
{name}) nvim_create_namespace()
Creates a new namespace or gets an existing one. namespace
name matches an existing
namespace, the associated id is returned. If name is an empty string a
new, anonymous namespace is created.
{name} Namespace name or empty string
nvim_get_namespaces()
Gets existing, non-anonymous namespaces.
nvim_set_decoration_provider()
nvim_set_decoration_provider({ns_id}, {*opts})
Set or change decoration provider for a namespace
ephemeral key to only use the mark for the
current screen redraw (the callback will be called again for the next
redraw).
on_start
callback can return false to disable the provider until the next redraw.
Similarly, return false in on_win will skip the on_lines calls for
that window (but any extmarks set in on_win will still be used). A
plugin managing multiple sources of decoration should ideally only set one
provider, and merge the sources internally. You can use multiple ns_id
for the extmarks set/modified inside the callback anyway.
vim.rpcnotify should be OK, but vim.rpcrequest is
quite dubious for the moment.
{ns_id} Namespace id from nvim_create_namespace()
{opts} Table of callbacks:
{window}, {fun}) nvim_win_call()
Calls a function with window as temporary current window.
{window} Window handle, or 0 for current window
{fun} Function to call inside the window (currently Lua callable
only)
{window}, {force}) nvim_win_close()
Closes the window (like :close with a window-ID).
{window} Window handle, or 0 for current window
{force} Behave like :close! The last window of a buffer with
unwritten changes can be closed. The buffer will become
hidden, even if 'hidden' is not set.
{window} Window handle, or 0 for current window
{name} Variable name
{window}) nvim_win_get_buf()
Gets the current buffer in a window
{window} Window handle, or 0 for current window
{window}) nvim_win_get_cursor()
Gets the (1,0)-indexed, buffer-relative cursor position for a given window
(different windows showing the same buffer have independent cursor
positions). api-indexing
{window} Window handle, or 0 for current window
{window}) nvim_win_get_height()
Gets the window height
{window} Window handle, or 0 for current window
{window}) nvim_win_get_number()
Gets the window number
{window} Window handle, or 0 for current window
{window}) nvim_win_get_position()
Gets the window position in display cells. First position is zero.
{window} Window handle, or 0 for current window
{window}) nvim_win_get_tabpage()
Gets the window tabpage
{window} Window handle, or 0 for current window
{window} Window handle, or 0 for current window
{name} Variable name
{window}) nvim_win_get_width()
Gets the window width
{window} Window handle, or 0 for current window
{window}) nvim_win_hide()
Closes the window and hide the buffer it contains (like :hide with a
window-ID).
unload, delete or wipe as opposed to :close
or nvim_win_close(), which will close the buffer.
{window} Window handle, or 0 for current window
{window}) nvim_win_is_valid()
Checks if a window is valid
{window} Window handle, or 0 for current window
{window}, {buffer}) nvim_win_set_buf()
Sets the current buffer in a window, without side effects
{window} Window handle, or 0 for current window
{buffer} Buffer handle
{window}, {pos}) nvim_win_set_cursor()
Sets the (1,0)-indexed cursor position in the window. api-indexing This
scrolls the window even if it is not the current one.
{window} Window handle, or 0 for current window
{pos} (row, col) tuple representing the new position
{window} Window handle, or 0 for current window
{height} Height as a count of rows
{window}, {ns_id}) nvim_win_set_hl_ns()
Set highlight namespace for a window. This will use highlights defined
with nvim_set_hl() for this namespace, but fall back to global
highlights (ns=0) when missing.
{ns_id} the namespace to use
{window} Window handle, or 0 for current window
{name} Variable name
{value} Variable value
{window}, {width}) nvim_win_set_width()
Sets the window width. This will only succeed if the screen is split
vertically.
{window} Window handle, or 0 for current window
{width} Width as a count of columns
{window}, {*opts}) nvim_win_text_height()
Computes the number of screen lines occupied by a range of text in a given
window. Works for off-screen text and takes folds into account.
{window} Window handle, or 0 for current window.
{opts} Optional parameters:
external and relative must be specified. The width
and height of the new window must be specified.
vim.api.nvim_open_win(0, false,
{relative='win', row=3, col=3, width=12, height=3})vim.api.nvim_open_win(0, false,
{relative='win', width=12, height=3, bufpos={100,10}})
}){buffer} Buffer to display, or 0 for current buffer
{enter} Enter the window (make it the current window)
{config} Map defining the window configuration. Keys:
win field, or current
window.
row and col if given are applied relative to this position, else they
default to:
row=1 and col=0 if anchor is "NW" or "NE"
row=0 and col=0 if anchor is "SW" or "SE" (thus
like a tooltip near the buffer text).
zindex go on top on floats with lower indices. Must be larger
than zero. The following screen elements have hard-coded
z-indices:
auto and
'colorcolumn' is cleared. 'statuscolumn' is changed to
empty. The end-of-buffer region is hidden by setting
eob flag of 'fillchars' to a space char, and clearing
the hl-EndOfBuffer region in 'winhighlight'.
FloatBorder highlight is used, which links to
WinSeparator when not defined. It could also be
specified by character: [ ["+", "MyCorner"], ["x",
"MyBorder"] ].
[text, highlight] tuples. If
string, the default highlight group is FloatTitle.
title
option. Value can be one of "left", "center", or "right".
Default is "left".
[text, highlight] tuples.
If string, the default highlight group is FloatFooter.
footer
option. Value can be one of "left", "center", or "right".
Default is "left".
{window}) nvim_win_get_config()
Gets window configuration.
relative is empty for normal windows.
{window} Window handle, or 0 for current window
{window}, {*config}) nvim_win_set_config()
Configures window layout. Currently only for floating and external windows
(including changing a split window to those layouts).
row/`col` and relative must be reconfigured together.
{window} Window handle, or 0 for current window
{config} Map defining the window configuration, see nvim_open_win()
{tabpage} Tabpage handle, or 0 for current tabpage
{name} Variable name
{tabpage}) nvim_tabpage_get_number()
Gets the tabpage number
{tabpage} Tabpage handle, or 0 for current tabpage
{tabpage} Tabpage handle, or 0 for current tabpage
{name} Variable name
{tabpage}) nvim_tabpage_get_win()
Gets the current window in a tabpage
{tabpage} Tabpage handle, or 0 for current tabpage
{tabpage}) nvim_tabpage_is_valid()
Checks if a tabpage is valid
{tabpage} Tabpage handle, or 0 for current tabpage
{tabpage}) nvim_tabpage_list_wins()
Gets the windows in a tabpage
{tabpage} Tabpage handle, or 0 for current tabpage
tabpage
nvim_tabpage_set_var()
nvim_tabpage_set_var({tabpage}, {name}, {value})
Sets a tab-scoped (t:) variable
{tabpage} Tabpage handle, or 0 for current tabpage
{name} Variable name
{value} Variable value
{*opts}) nvim_clear_autocmds()
Clears all autocommands selected by {opts}. To delete autocmds see
nvim_del_autocmd().
{opts} Parameters
*.py as that pattern for the
autocmd, you must pass *.py exactly to clear it.
test.py will not match the pattern.
{buffer}
{name}, {*opts}) nvim_create_augroup()
Create or get an autocommand group autocmd-groups.
local id = vim.api.nvim_create_augroup("MyGroup", {
clear = false
}){name} String: The name of the group
{opts} Dictionary Parameters
{event}, {*opts}) nvim_create_autocmd()
Creates an autocommand event handler, defined by callback (Lua function or Vimscript function name string) or command (Ex command string).
vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
pattern = {"*.c", "*.h"},
callback = function(ev)
print(string.format('event fired: %s', vim.inspect(ev)))
end
})vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
pattern = {"*.c", "*.h"},
command = "echo 'Entering a C or C++ file'",
})pattern is NOT automatically expanded (unlike with :autocmd),
thus names like "$HOME" and "~" must be expanded explicitly:pattern = vim.fn.expand("~") .. "/some/path/*.py"{event} (string|array) Event(s) that will trigger the handler
(callback or command).
{opts} Options dict:
{pattern}.
{callback}
{id}) nvim_del_augroup_by_id()
Delete an autocommand group by id.
{id} Integer The id of the group.
{name}) nvim_del_augroup_by_name()
Delete an autocommand group by name.
{name} String The name of the group.
{id}) nvim_del_autocmd()
Deletes an autocommand by id.
{id} Integer Autocommand id returned by nvim_create_autocmd()
{event}, {*opts}) nvim_exec_autocmds()
Execute all autocommands for {event} that match the corresponding {opts}
autocmd-execute.
{event} (String|Array) The event or events to execute
{opts} Dictionary of autocommand options:
{buffer}.
{pattern}.
{*opts}) nvim_get_autocmds()
Get all autocommands that match the corresponding {opts}.
-- 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",
}){opts} Dictionary with at least one of the following:
{buffer}
{pattern}
nvim_ui_detach()
Deactivates UI events on the channel.
nvim_ui_pum_set_bounds()
nvim_ui_pum_set_bounds({width}, {height}, {row}, {col})
Tells Nvim the geometry of the popupmenu, to align floating windows with
an external popup menu.
{width} Popupmenu width.
{height} Popupmenu height.
{row} Popupmenu row.
{col} Popupmenu height.
{height}) nvim_ui_pum_set_height()
Tells Nvim the number of elements displaying in the popupmenu, to decide
<PageUp> and <PageDown> movement.
{height} Popupmenu height, must be greater than zero.
{gained}) nvim_ui_set_focus()
Tells the nvim server if focus was gained or lost by the GUI.
{event}, {value}) nvim_ui_term_event()
Tells Nvim when a terminal event has occurred
{event} Event name
{payload} Event payload
nvim_ui_try_resize_grid()
nvim_ui_try_resize_grid({grid}, {width}, {height})
Tell Nvim to resize a grid. Triggers a grid_resize event with the
requested grid size or the maximum size if it exceeds size limits.
{grid} The handle of the grid to be changed.
{width} The new requested width.
{height} The new requested height.