Nvim :help pages, generated
from source
using the tree-sitter-vimdoc parser.
rpc key in the options dict. RPC channels can also be
opened by other processes connecting to TCP/IP sockets or named pipes listened
to by Nvim.
nvim --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 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 kvec
Dict (msgpack: map) kvec
Object any of the above
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
(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.
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, api-metadata.
opts parameter may be ADDED.
opts parameter.
{type} is a numeric id as defined by api_info().error_types, and {message} is
a string with the error message.
{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} 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}]
{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}).
true. This will detach all
callbacks attached with the same nvim_buf_attach() call.
-- 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})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]{chan}, {data}) nvim_chan_send()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} (integer) id of the channel
{data} (string) data to write. 8-bit clean: can contain NUL bytes.
{scratch} (boolean) Creates a "throwaway" scratch-buffer for
temporary work (always 'nomodified'). Also sets
'nomodeline' on the buffer.
integer) Buffer id, or 0 on error
{mode} (string)
{lhs} (string)
{name} (string) Mark name
boolean) true if the mark was deleted, else false.
{name} (string) Variable name
{chunks}, {history}, {opts}) nvim_echo()[text, hl_group] "chunks".
vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {}){chunks} ([string, integer|string?][]) List of [text, hl_group]
pairs, where each is a text string highlighted by the
(optional) name or ID hl_group.
{opts} (vim.api.keyset.echo_opts) Optional parameters.
-V3log will write the message to the
"log" file instead of standard output.
{opts} (vim.api.keyset.eval_statusline) Optional parameters.
{winid} is ignored. Mutually
exclusive with {use_winbar}.
vim.api.keyset.eval_statusline_ret) Dict containing statusline
information, with these keys:
{opts} is
true. Each element of the array is a Dict with these keys:
groups instead.
{code}, {args}) nvim_exec_lua()... inside the
chunk. The chunk can return a value.
return: return my_function(...)
{code} (string) Lua code to execute
{args} (any[]) Arguments to the code
any) Return value of Lua code if present or NIL.
{keys}, {mode}, {escape_ks}) nvim_feedkeys()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} (string) to be typed
{escape_ks} (boolean) If true, escape K_SPECIAL bytes in keys.
This should be false if you already used
nvim_replace_termcodes(), and true otherwise.
[any, any]) 2-tuple [{channel-id}, {api-metadata}]
{chan} (integer) channel_id, or 0 for current channel
table<string,any>) Channel info dict with these keys:
{name}) nvim_get_color_by_name():echo nvim_get_color_by_name("Pink")
:echo nvim_get_color_by_name("#cbcbcb"){name} (string) Color name or "#rrggbb" string
integer) 24-bit RGB value, or -1 for invalid argument.
table<string,integer>) Map of color names and RGB values.
{opts} (vim.api.keyset.context) Optional parameters.
integer) Buffer id
string) Current line string
link attribute is defined in the highlight definition map,
other attributes will not be taking effect (see :hi-link).
{ns_id} (integer) Get highlight groups for namespace ns_id
nvim_get_namespaces(). Use 0 to get global highlight groups
:highlight.
{opts} (vim.api.keyset.get_highlight) Options dict:
vim.api.keyset.get_hl_info) Highlight groups as a map from group
name to a highlight definition map as in nvim_set_hl(), or only a
single highlight definition map if requested by name or id.
{name} (string)
integer)
{opts} (vim.api.keyset.get_ns) Optional parameters
integer) Namespace id, or -1
{mode}) nvim_get_keymap(){mode} (string) Mode short-name ("n", "i", "v", ...)
vim.api.keyset.get_keymap[]) Array of maparg()-like dictionaries
describing mappings. The "buffer" key is always zero.
{name}, {opts}) nvim_get_mark()(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} (string) Mark name
{opts} (vim.api.keyset.empty) Optional parameters. Reserved for
future use.
[integer, integer, integer, string]) 4-tuple (row, col, buffer,
buffername), (0, 0, 0, '') if the mark is not set.
vim.api.keyset.get_mode) Dict { "mode": String, "blocking": Boolean
}
{pid} (integer)
any) Map of process properties, or NIL if process not found.
{pid} (integer)
any[]) Array of child process ids, empty if process not found.
{name}, {all}) nvim_get_runtime_file()nvim_get_runtime_file("colors/*.{vim,lua}", true) will return all color
scheme files. Always use forward slashes (/) in the search pattern for
subdirectories regardless of platform.
{name} (string) pattern of files to search for
{all} (boolean) whether to return all matches or only the first
string[]) list of absolute paths to the found files
{name} (string) Variable name
any) Variable value
{name} (string) Variable name
any) Variable value
{keys}) nvim_input()<LeftMouse><col,row> is deprecated since api-level 6.
{keys} (string) to be typed
integer) Number of bytes actually written (can be fewer than
requested if the buffer becomes full).
{button}, {action}, {modifier}, {grid}, {row}, {col})
Send mouse event from GUI.
<LeftMouse><col,row>) of
nvim_input() has the same limitation.
{button} (string) Mouse button: one of "left", "right", "middle",
"wheel", "move", "x1", "x2".
{action} (string) For ordinary buttons, one of "press", "drag",
"release". For the wheel, one of "up", "down", "left",
"right". Ignored for "move".
{modifier} (string) 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.
{row} (integer) Mouse row-position (zero-based, like redraw
events)
{col} (integer) Mouse column-position (zero-based, like redraw
events)
:ls!. Use
nvim_buf_is_loaded() to check if a buffer is loaded.
integer[]) List of buffer ids
table<string,any>[]) Array of Dictionaries, each describing a
channel with the format specified at nvim_get_chan_info().
string[]) List of paths
client.name to "nvim-tui". So you
can check if the TUI is running by inspecting the client name of each UI:vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name)table<string,any>[]) Array of UI dictionaries, each with these
keys:
{dict}) nvim_load_context()any)
TermHl command can be used to display and highlight raw
ANSI termcodes, so you can use Nvim as a "scrollback pager" (for terminals
like kitty): ansi-colorize terminal-scrollback-pagervim.api.nvim_create_user_command('TermHl', function()
vim.api.nvim_open_term(0, {})
end, { desc = 'Highlights ANSI termcodes in curbuf' }){buffer} (integer) Buffer to use. Buffer contents (if any) will be
written to the PTY.
{opts} (vim.api.keyset.open_term) Optional parameters.
["input", term, bufnr, data]
integer) Channel id, or 0 on error
{data}, {crlf}, {phase}) nvim_paste()vim.paste() failure, …) are reflected in err
but do not affect the return value (which is strictly decided by
vim.paste()). On error or cancel, subsequent calls are ignored
("drained") until the next paste is initiated (phase 1 or -1).
vim.keymap.set('n', 'x', function()
vim.api.nvim_paste([[
line1
line2
line3
]], false, -1)
end, { buffer = true }){data} (string) Multiline input. Lines break at LF ("\n"). May be
binary (containing NUL bytes).
{crlf} (boolean) Also break lines at CR and CRLF.
{phase} (integer) -1: paste in a single call (i.e. without
streaming). To "stream" a paste, call nvim_paste
sequentially with these phase values:
boolean)
{lines}, {type}, {after}, {follow}) nvim_put(){follow} (boolean) If true place cursor at end of inserted text.
{str}, {from_part}, {do_lt}, {special})
Replaces terminal codes and keycodes (<CR>, <Esc>, ...) in a string with
the internal representation.
{str} (string) String to be converted.
{from_part} (boolean) Legacy Vim parameter. Usually true.
{do_lt} (boolean) Also translate <lt>. Ignored if special is
false.
string)
{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} (integer) Index (zero-based) of the item to select. Value
of -1 selects nothing and restores the original text.
{insert} (boolean) For ins-completion, whether the selection
should be inserted in the buffer. Ignored for
cmdline-completion.
{finish} (boolean) Finish the completion and dismiss the popup
menu. Implies {insert}.
{opts} (vim.api.keyset.empty) Optional parameters. Reserved for
future use.
{name}, {version}, {type}, {methods}, {attributes})
Self-identifies the client, and sets optional flags on the channel.
Defines the client object returned by nvim_get_chan_info().
name.)
{version} (table<string,any>) Dict describing the version, with
these (optional) keys:
{type} (string) Must be one of the following values. Client
libraries should default to "remote" unless overridden
by the user.
{methods} (table<string,any>) 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} (table<string,any>) Arbitrary string:string map of
informal client properties. Suggested keys:
{buffer} (integer) Buffer id
{dir} (string) Directory path
{line} (string) Line contents
{window}) nvim_set_current_win():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} (integer) 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} (string) Highlight group name, e.g. "ErrorMsg"
{val} (vim.api.keyset.highlight) Highlight definition map,
accepts the following keys:
{ns_id}) nvim_set_hl_ns(){ns_id} (integer) the namespace to use
{ns_id}) nvim_set_hl_ns_fast(){ns_id} (integer) the namespace to activate
{mode}, {lhs}, {rhs}, {opts}) nvim_set_keymap(){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} (string) 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
{opts} (vim.api.keyset.keymap) Optional parameters map: Accepts all
:map-arguments as keys except <buffer>, values are booleans
(default false). Also:
{rhs}.
{name} (string) Variable name
{value} (any) Variable value
{name} (string) Variable name
{value} (any) Variable value
{text}) nvim_strwidth()text. Control
characters including <Tab> count as one cell.
{text} (string) Some text
integer) Number of cells
{index}, {opts}) nvim__complete_set(){index} (integer) Completion candidate index
{opts} (vim.api.keyset.complete_set) Optional parameters.
table<string,number>) Dict containing these keys:
{pat} (string[]) pattern of files to search for
{all} (boolean) whether to return all matches or only the first
{opts} (vim.api.keyset.runtime) is_lua: only search Lua subdirs
string[]) list of absolute paths to the found files
{obj} (any) Object to return.
any) its argument.
{arr} (any[]) Array to return.
any[]) its argument.
{dct} (table<string,any>) Dict to return.
table<string,any>) its argument.
{flt} (number) Value to return.
number) its argument.
{grid}, {row}, {col}) nvim__inspect_cell(){grid} (integer)
{row} (integer)
{col} (integer)
any[])
{opts} (vim.api.keyset.redraw) Optional parameters.
win, buf, or all windows for
redraw. When true, only redraw changed lines (useful for
decoration providers). When false, forcefully redraw.
buf, the buffer in win or the
current buffer (useful for decoration providers). Expects a
tuple [first, last] with the first and last line number of
the range, 0-based end-exclusive api-indexing.
win or the current window.
table<string,any>) Map of various internal stats.
{dict}, {fn}, {args})
Calls a Vimscript Dictionary-function with the given arguments.
{fn} (string) Name of the function defined on the Vimscript dict
{args} (any[]) Function arguments packed in an Array
any) Result of the function call
{fn}, {args}) nvim_call_function(){fn} (string) Function to call
{args} (any[]) Function arguments packed in an Array
any) Result of the function call
{command} (string) Ex command string
{expr}) nvim_eval(){expr} (string) Vimscript expression string
any) Evaluation result or expanded object
{src}, {opts}) nvim_exec2(){src} (string) Vimscript code
{opts} (vim.api.keyset.exec_opts) Optional parameters.
table<string,any>) Dict containing information about execution,
with these keys:
opts.output is true.
{expr}, {flags}, {highlight})
Parse a Vimscript expression.
{expr} (string) Expression to parse. Always treated as a
single line.
{flags} (string) Flags:
":echo".
"<C-r>=".
{highlight} (boolean) 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)).
table<string,any>)
[line, column] describing where node is
"started" where "line" is always 0 (will not be 0 if you will be
using this API on e.g. ":let", but that is not present yet).
Both elements are Integers.
{buffer}, {name}, {command}, {opts})
Creates a buffer-local command user-commands.
{buffer} (integer) Buffer id, or 0 for current buffer.
{name} (string)
{command} (any)
{opts} (vim.api.keyset.user_command)
{buffer}, {name})
Delete a buffer-local user-defined command.
{buffer} (integer) Buffer id, or 0 for current buffer.
{name} (string) Name of the command to delete.
{buffer}, {opts}) nvim_buf_get_commands(){buffer} (integer) Buffer id, or 0 for current buffer
{opts} (vim.api.keyset.get_commands) Optional parameters.
Currently not used.
vim.api.keyset.command_info) Map of maps describing commands.
vim.cmd.bdelete{ count = 2 }, you may do
vim.cmd.bdelete(2).
{cmd} (vim.api.keyset.cmd) Command to execute. Must be a Dict that
can contain the same values as the return value of
nvim_parse_cmd() except "addr", "nargs" and "nextcmd" which
are ignored if provided. All values except for "cmd" are
optional.
{opts} (vim.api.keyset.cmd_opts) Optional parameters.
{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} (string) Name of the new user command. Must begin with an
uppercase letter.
{command} (string|fun(args: vim.api.keyset.create_user_command.command_args))
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>
<f-args>
<bang>
<line1>
<line2>
<range>
<count>
<reg>
<mods>
{command}.
{name} (string) Name of the command to delete.
{opts} (vim.api.keyset.get_commands) Optional parameters. Currently
only supports {"builtin":false}
table<string,vim.api.keyset.command_info>) Map of maps describing
commands.
{str} (string) Command line string to parse. Cannot contain "\n".
{opts} (vim.api.keyset.empty) Optional parameters. Reserved for
future use.
vim.api.keyset.cmd) Dict containing command information, with these
keys:
<line1> <line2>). 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>. Omitted if command
cannot take a count.
<register>. Omitted if command
cannot take a register.
<bang> (!) modifier.
table<string,any>) dict of all options
{name}, {opts}) nvim_get_option_info2(){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} (string) Option name
{opts} (vim.api.keyset.option) Optional parameters
{scope} is "local".
vim.api.keyset.get_option_info) Option Information
{name}, {opts}) nvim_get_option_value(){opts}.
{name} (string) Option name
{opts} (vim.api.keyset.option) Optional parameters
{scope} is "local".
any) 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} (string) Option name
{value} (any) New option value
{opts} (vim.api.keyset.option) Optional parameters
{buffer}, {send_buffer}, {opts}) nvim_buf_attach()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} (integer) Buffer id, or 0 for current buffer
{send_buffer} (boolean) 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} (vim.api.keyset.buf_attach) Optional parameters.
false or nil) to detach. Args:
utf_sizes is true)
utf_sizes is true)
false or nil) to detach. Args:
on_lines.
boolean) False if attach failed (invalid parameter, or buffer isn't
loaded); otherwise True. TODO: LUA_API_NO_EVAL
{buffer}, {fun}) nvim_buf_call()jobstart(…, {'term': v:true}).
{buffer} (integer) Buffer id, or 0 for current buffer
{fun} (function) Function to call inside the buffer (currently
Lua callable only)
any) Return value of function.
{buffer}, {mode}, {lhs}) nvim_buf_del_keymap(){buffer} (integer) Buffer id, or 0 for current buffer
{mode} (string)
{lhs} (string)
{buffer}, {name}) nvim_buf_del_mark(){buffer} (integer) Buffer to set the mark on
{name} (string) Mark name
boolean) true if the mark was deleted, else false.
{buffer} (integer) Buffer id, or 0 for current buffer
{name} (string) Variable name
{buffer}, {opts}) nvim_buf_delete()unload=true:vim.bo.buflisted = false
vim.api.nvim_buf_delete(0, { unload = true }){buffer} (integer) Buffer id, or 0 for current buffer
{opts} (vim.api.keyset.buf_delete) Optional parameters. Keys:
{buffer} (integer) Buffer id, or 0 for current buffer
boolean) False if detach failed (because the buffer isn't loaded);
otherwise True.
{buffer} (integer) Buffer id, or 0 for current buffer
integer) b:changedtick value.
{buffer}, {mode}) nvim_buf_get_keymap(){buffer} (integer) Buffer id, or 0 for current buffer
{mode} (string) Mode short-name ("n", "i", "v", ...)
vim.api.keyset.get_keymap[]) Array of maparg()-like dictionaries
describing mappings. The "buffer" key holds the associated buffer id.
{buffer}, {start}, {end}, {strict_indexing})
Gets a line-range from the buffer.
strict_indexing is set.
{buffer} (integer) Buffer id, or 0 for current buffer
{start} (integer) First line index
{end} (integer) Last line index, exclusive
{strict_indexing} (boolean) Whether out-of-bounds should be an
error.
string[]) Array of lines, or empty array for unloaded buffer.
{buffer}, {name}) nvim_buf_get_mark()(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} (integer) Buffer id, or 0 for current buffer
{name} (string) Mark name
[integer, integer]) (row, col) tuple, (0, 0) if the mark is not
set, or is an uppercase/file mark set in another buffer.
{buffer} (integer) Buffer id, or 0 for current buffer
string) Buffer name
{buffer}, {index}) nvim_buf_get_offset(){buffer} (integer) Buffer id, or 0 for current buffer
{index} (integer) Line index
integer) Integer byte offset, or -1 for unloaded buffer.
{buffer}, {start_row}, {start_col}, {end_row}, {end_col},
{opts})
Gets a range from the buffer (may be partial lines, unlike
nvim_buf_get_lines()).
{buffer} (integer) Buffer id, or 0 for current buffer
{start_row} (integer) First line index
{start_col} (integer) Starting column (byte offset) on first line
{end_row} (integer) Last line index, inclusive
{end_col} (integer) Ending column (byte offset) on last line,
exclusive
{opts} (vim.api.keyset.empty) Optional parameters. Currently
unused.
string[]) Array of lines, or empty array for unloaded buffer.
{buffer} (integer) Buffer id, or 0 for current buffer
{name} (string) Variable name
any) Variable value
{buffer}) nvim_buf_is_loaded(){buffer} (integer) Buffer id, or 0 for current buffer
boolean) true if the buffer is valid and loaded, false otherwise.
{buffer} (integer) Buffer id, or 0 for current buffer
boolean) true if the buffer is valid, false otherwise.
{buffer}) nvim_buf_line_count(){buffer} (integer) Buffer id, or 0 for current buffer
{buffer}, {mode}, {lhs}, {rhs}, {opts})
Sets a buffer-local mapping for the given mode.
{buffer} (integer) Buffer id, or 0 for current buffer
{mode} (string)
{lhs} (string)
{rhs} (string)
{opts} (vim.api.keyset.keymap)
{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} (integer) Buffer id, or 0 for current buffer
{start} (integer) First line index
{end} (integer) Last line index, exclusive
{strict_indexing} (boolean) Whether out-of-bounds should be an
error.
{replacement} (string[]) Array of lines to use as replacement
{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} (integer) Buffer to set the mark on
{name} (string) Mark name
{line} (integer) Line number
{col} (integer) Column/row number
{opts} (vim.api.keyset.empty) Optional parameters. Reserved for
future use.
boolean) true if the mark was set, else false.
{buffer}, {name}) nvim_buf_set_name(){buffer} (integer) Buffer id, or 0 for current buffer
{name} (string) Buffer name
{buffer}, {start_row}, {start_col}, {end_row}, {end_col},
{replacement})
Sets (replaces) a range in the buffer
(row, column) location, use
start_row = end_row = row and start_col = end_col = col. To delete the
text in a range, use replacement = {}.
{buffer} (integer) Buffer id, or 0 for current buffer
{start_row} (integer) First line index
{start_col} (integer) Starting column (byte offset) on first line
{end_row} (integer) Last line index, inclusive
{end_col} (integer) Ending column (byte offset) on last line,
exclusive
{replacement} (string[]) Array of lines to use as replacement
{buffer} (integer) Buffer id, or 0 for current buffer
{name} (string) Variable name
{value} (any) Variable value
{buffer}, {ns_id}, {line_start}, {line_end})
Clears namespaced objects (highlights, extmarks, virtual text) from a
region.
{buffer} (integer) Buffer id, or 0 for current buffer
{ns_id} (integer) Namespace to clear, or -1 to clear all
namespaces.
{line_start} (integer) Start of range of lines to clear
{line_end} (integer) End of range of lines to clear (exclusive)
or -1 to clear to end of buffer.
{buffer} (integer) Buffer id, or 0 for current buffer
{id} (integer) Extmark id
boolean) true if the extmark was found, else false
{buffer}, {ns_id}, {id}, {opts})
Gets the position (0-indexed) of an extmark.
{buffer} (integer) Buffer id, or 0 for current buffer
{id} (integer) Extmark id
{opts} (vim.api.keyset.get_extmark) Optional parameters. Keys:
[integer, integer, vim.api.keyset.extmark_details?]) 0-indexed
(row, col) tuple or empty list () if extmark id was absent
{buffer}, {ns_id}, {start}, {end}, {opts})
Gets extmarks 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, marks are returned in reverse order.
(Useful with limit, to get the first marks prior to a given position.)
limit does not actually affect the traversed
range, just how many marks are returned
overlap option might be useful. Otherwise only the start position of
an extmark will be considered.
sign_name field.
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} (integer) Buffer id, or 0 for current buffer
{start} (any) Start of range: a 0-indexed (row, col) or valid
extmark id (whose position defines the bound).
api-indexing
{end} (any) End of range (inclusive): a 0-indexed (row, col) or
valid extmark id (whose position defines the bound).
api-indexing
{opts} (vim.api.keyset.get_extmarks) Optional parameters. Keys:
start
vim.api.keyset.get_extmark_item[]) List of [extmark_id, row, col]
tuples in "traversal order".
{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} (integer) Buffer id, or 0 for current buffer
{opts} (vim.api.keyset.set_extmark) Optional parameters.
[text, highlight] tuples, each representing a text chunk
with specified highlight. highlight element can either
be a single highlight group, or an array of multiple
highlight groups that will be stacked (highest priority
last).
hl_group in later versions.
[text, highlight] tuples. In general,
buffer and window options do not affect the display of the
text. In particular 'wrap' and 'linebreak' options do not
take effect, so the number of extra screen lines will
always match the size of the array. However the 'tabstop'
buffer option is still used for hard tabs. By default
lines are placed below the buffer line containing the
mark.
integer) Id of the created/updated extmark
{name}) nvim_create_namespace()name matches an existing
namespace, the associated id is returned. If name is an empty string a
new, anonymous namespace is created.
{name} (string) Namespace name or empty string
integer) Namespace id
table<string,integer>) dict that maps from names to namespace ids.
{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_line calls for
that window (but any extmarks set in on_win will still be used). A
plugin managing multiple sources of decoration should ideally only set one
provider, and merge the sources internally. You can use multiple ns_id
for the extmarks set/modified inside the callback anyway.
vim.rpcnotify should be OK, but vim.rpcrequest is
quite dubious for the moment.
on_line
callbacks.
{opts} (vim.api.keyset.set_decoration_provider) Table of
callbacks:
["start", tick]
["buf", bufnr, tick]
["win", winid, bufnr, toprow, botrow]
["line", winid, bufnr, row]
["end", tick]
{ns_id} (integer) Namespace
{ns_id} (integer) Namespace
{opts} (vim.api.keyset.ns_opts) Optional parameters to set:
{window}, {fun}) nvim_win_call(){fun} (function) Function to call inside the window (currently
Lua callable only)
any) Return value of function.
{window}, {force}) nvim_win_close(){force} (boolean) 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.
integer) Buffer id
{window}) nvim_win_get_cursor()[integer, integer]) (row, col) tuple
integer) Height as a count of rows
integer) Window number
{window}) nvim_win_get_position()[integer, integer]) (row, col) tuple with the window position
integer) Tabpage that contains the window
any) Variable value
integer) Width as a count of columns
{window}) nvim_win_hide()unload, delete or wipe as opposed to :close
or nvim_win_close(), which will close the buffer.
boolean) true if the window is valid, false otherwise
{window}, {buffer}) nvim_win_set_buf(){window}, {pos}) nvim_win_set_cursor(){pos} ([integer, integer]) (row, col) tuple representing the new
position
{height} (integer) Height as a count of rows
{window}, {ns_id}) nvim_win_set_hl_ns(){window} (integer)
{ns_id} (integer) the namespace to use
{name} (string) Variable name
{value} (any) Variable value
{window}, {width}) nvim_win_set_width(){width} (integer) Width as a count of columns
{window}, {opts}) nvim_win_text_height(){opts} (vim.api.keyset.win_text_height) Optional parameters:
vim.api.keyset.win_text_height_ret) Dict containing text height
information, with these keys:
{buffer}, {enter}, {config}) nvim_open_win()relative is specified,
or an external window (managed by the UI) if external is specified.
width and height of the new window must be specified when opening
a floating window, but are optional for normal windows.
relative and external are omitted, a normal "split" window is
created. The win property determines which window will be split. If no
win is provided or win == 0, a window will be created adjacent to the
current window. If -1 is provided, a top-level split will be created.
vertical and split are only valid for normal windows, and are used to
control split direction. For vertical, the exact direction is determined
by 'splitright' and 'splitbelow'. Split windows cannot have
bufpos/`row`/`col`/`border`/`title`/`footer` properties.
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}})vim.api.nvim_open_win(0, false, {
split = 'left',
win = 0
}){buffer} (integer) Buffer to display, or 0 for current buffer
{enter} (boolean) Enter the window (make it the current window)
{config} (vim.api.keyset.win_config) Map defining the window
configuration. Keys:
win field, or current
window.
[line, column]. 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).
mouse
field is set to true, by mouse events. See focusable.
focusable value.
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'.
string|string[]) (defaults to 'winborder'
option) Window border. The string form accepts the same
values as the 'winborder' option. The array form must have
a length of eight or any divisor of eight, specifying the
chars that form the border in a clockwise fashion starting
from the top-left corner. For example, the double-box
style can be specified as:[ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ].
[ "/", "-", \"\\\\\", "|" ],
[ "x" ].
[ "", "", "", ">", "", "", "", "<" ]
[ ["+", "MyCorner"], ["x", "MyBorder"] ].
[text, highlight] tuples. If
string, or a tuple lacks a highlight, 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, or a tuple lacks a highlight, the default
highlight group is FloatFooter.
footer
option. Value can be one of "left", "center", or "right".
Default is "left".
relative is empty for normal windows.
{window}, {config}) nvim_win_set_config()row/`col` and relative must be reconfigured together.
integer) Tabpage number
any) Variable value
boolean) true if the tabpage is valid, false otherwise
integer[]) List of windows in tabpage
{tabpage}, {name}, {value})
Sets a tab-scoped (t:) variable
{name} (string) Variable name
{value} (any) Variable value
{opts}) nvim_clear_autocmds(){opts}. To delete autocmds see
nvim_del_autocmd().
{opts} (vim.api.keyset.clear_autocmds) Parameters
*.py as that pattern for the
autocmd, you must pass *.py exactly to clear it.
test.py will not match the pattern.
{buffer}
{pattern}
{name}, {opts}) nvim_create_augroup()local id = vim.api.nvim_create_augroup('my.lsp.config', {
clear = false
}){name} (string) String: The name of the group
{opts} (vim.api.keyset.create_augroup) Dict Parameters
integer) Integer id of the created group.
{event}, {opts}) nvim_create_autocmd()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} (vim.api.keyset.events|vim.api.keyset.events[]) Event(s)
that will trigger the handler (callback or command).
{opts} (vim.api.keyset.create_autocmd) Options dict:
{pattern}.
false or nil) to delete the autocommand, and
receives one argument, a table with these keys:
event-args<afile> (not expanded to a full path)
<amatch> (expanded to a full path)
<abuf>
{callback}
integer) Autocommand id (number)
{id} (integer) Integer The id of the group.
{name} (string) String The name of the group.
{event}, {opts}) nvim_exec_autocmds(){event} that match the corresponding {opts}
autocmd-execute.
{event} (vim.api.keyset.events|vim.api.keyset.events[]) The event
or events to execute
{opts} (vim.api.keyset.exec_autocmds) Dict of autocommand options:
{buffer}.
{pattern}.
<nomodeline>.
{opts}) nvim_get_autocmds(){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} (vim.api.keyset.get_autocmds) Dict with at least one of the
following:
{pattern}
{buffer}
vim.api.keyset.get_autocmds.ret[]) Array of autocommands matching
the criteria, with each item containing the following fields:
{width} (integer) Requested screen columns
{height} (integer) Requested screen rows
{width}, {height}, {row}, {col})
Tells Nvim the geometry of the popupmenu, to align floating windows with
an external popup menu.
{width} (number) Popupmenu width.
{height} (number) Popupmenu height.
{row} (number) Popupmenu row.
{col} (number) Popupmenu height.
{height}) nvim_ui_pum_set_height()<PageUp> and <PageDown> movement.
{height} (integer) Popupmenu height, must be greater than zero.
{gained}) nvim_ui_set_focus(){gained} (boolean)
{name} (string)
{value} (any)
{event}, {value}) nvim_ui_term_event(){event} (string) Event name
{value} (any) Event payload
{width} (integer)
{height} (integer)
{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} (integer) The handle of the grid to be changed.
{width} (integer) The new requested width.
{height} (integer) The new requested height.