#include <assert.h>
#include <inttypes.h>
#include <limits.h>
#include <stdbool.h>
#include <stdlib.h>
#include <string.h>
#include "nvim/api/buffer.h"
#include "nvim/api/deprecated.h"
#include "nvim/api/private/converter.h"
#include "nvim/api/private/defs.h"
#include "nvim/api/private/dispatch.h"
#include "nvim/api/private/helpers.h"
#include "nvim/api/vim.h"
#include "nvim/api/window.h"
#include "nvim/ascii.h"
#include "nvim/buffer.h"
#include "nvim/buffer_defs.h"
#include "nvim/charset.h"
#include "nvim/context.h"
#include "nvim/decoration.h"
#include "nvim/decoration_provider.h"
#include "nvim/edit.h"
#include "nvim/eval.h"
#include "nvim/eval/typval.h"
#include "nvim/eval/userfunc.h"
#include "nvim/ex_cmds2.h"
#include "nvim/ex_cmds_defs.h"
#include "nvim/ex_docmd.h"
#include "nvim/file_search.h"
#include "nvim/fileio.h"
#include "nvim/getchar.h"
#include "nvim/globals.h"
#include "nvim/highlight.h"
#include "nvim/highlight_defs.h"
#include "nvim/highlight_group.h"
#include "nvim/lua/executor.h"
#include "nvim/mark.h"
#include "nvim/memline.h"
#include "nvim/memory.h"
#include "nvim/message.h"
#include "nvim/move.h"
#include "nvim/msgpack_rpc/channel.h"
#include "nvim/msgpack_rpc/helpers.h"
#include "nvim/ops.h"
#include "nvim/option.h"
#include "nvim/os/input.h"
#include "nvim/os/process.h"
#include "nvim/popupmnu.h"
#include "nvim/screen.h"
#include "nvim/state.h"
#include "nvim/types.h"
#include "nvim/ui.h"
#include "nvim/vim.h"
#include "nvim/viml/parser/expressions.h"
#include "nvim/viml/parser/parser.h"
#include "nvim/window.h"

Macros
#define	LINE_BUFFER_SIZE 4096

#define	PUSH_CHAR(i, pos, line_buf, msg)

Functions
Dictionary	nvim_get_hl_by_name (String name, Boolean rgb, Error *err) FUNC_API_SINCE(3)

Dictionary	nvim_get_hl_by_id (Integer hl_id, Boolean rgb, Error *err) FUNC_API_SINCE(3)

Integer	nvim_get_hl_id_by_name (String name) FUNC_API_SINCE(7)

Dictionary	nvim__get_hl_defs (Integer ns_id, Error *err)

void	nvim_set_hl (Integer ns_id, String name, Dict(highlight) val, Error err) FUNC_API_SINCE(7)

void	nvim__set_hl_ns (Integer ns_id, Error *err) FUNC_API_FAST

void	nvim_feedkeys (String keys, String mode, Boolean escape_ks) FUNC_API_SINCE(1)

Integer	nvim_input (String keys) FUNC_API_SINCE(1) FUNC_API_FAST

void	nvim_input_mouse (String button, String action, String modifier, Integer grid, Integer row, Integer col, Error *err) FUNC_API_SINCE(6) FUNC_API_FAST

String	nvim_replace_termcodes (String str, Boolean from_part, Boolean do_lt, Boolean special) FUNC_API_SINCE(1)

Object	nvim_exec_lua (String code, Array args, Error *err) FUNC_API_REMOTE_ONLY

Object	nvim_notify (String msg, Integer log_level, Dictionary opts, Error *err) FUNC_API_SINCE(7)

Integer	nvim_strwidth (String text, Error *err) FUNC_API_SINCE(1)

	ArrayOf (String)

Array	nvim__runtime_inspect (void)

String	nvim__get_lib_dir (void)

void	nvim_set_current_dir (String dir, Error *err) FUNC_API_SINCE(1)

String	nvim_get_current_line (Error *err) FUNC_API_SINCE(1)

void	nvim_set_current_line (String line, Error *err) FUNC_API_CHECK_TEXTLOCK

void	nvim_del_current_line (Error *err) FUNC_API_CHECK_TEXTLOCK

Object	nvim_get_var (String name, Error *err) FUNC_API_SINCE(1)

void	nvim_set_var (String name, Object value, Error *err) FUNC_API_SINCE(1)

void	nvim_del_var (String name, Error *err) FUNC_API_SINCE(1)

Object	nvim_get_vvar (String name, Error *err) FUNC_API_SINCE(1)

void	nvim_set_vvar (String name, Object value, Error *err) FUNC_API_SINCE(6)

Object	nvim_get_option (String name, Error *err) FUNC_API_SINCE(1)

Object	nvim_get_option_value (String name, Dict(option) opts, Error err) FUNC_API_SINCE(9)

void	nvim_set_option_value (String name, Object value, Dict(option) opts, Error err) FUNC_API_SINCE(9)

Dictionary	nvim_get_all_options_info (Error *err) FUNC_API_SINCE(7)

Dictionary	nvim_get_option_info (String name, Error *err) FUNC_API_SINCE(7)

void	nvim_set_option (uint64_t channel_id, String name, Object value, Error *err) FUNC_API_SINCE(1)

void	nvim_echo (Array chunks, Boolean history, Dictionary opts, Error *err) FUNC_API_SINCE(7)

void	nvim_out_write (String str) FUNC_API_SINCE(1)

void	nvim_err_write (String str) FUNC_API_SINCE(1)

void	nvim_err_writeln (String str) FUNC_API_SINCE(1)

	ArrayOf (Buffer)

Buffer	nvim_get_current_buf (void)

void	nvim_set_current_buf (Buffer buffer, Error *err) FUNC_API_CHECK_TEXTLOCK

	ArrayOf (Window)

Window	nvim_get_current_win (void)

void	nvim_set_current_win (Window window, Error *err) FUNC_API_CHECK_TEXTLOCK

Buffer	nvim_create_buf (Boolean listed, Boolean scratch, Error *err) FUNC_API_SINCE(6)

Integer	nvim_open_term (Buffer buffer, DictionaryOf(LuaRef) opts, Error *err) FUNC_API_SINCE(7)

void	nvim_chan_send (Integer chan, String data, Error *err) FUNC_API_SINCE(7) FUNC_API_REMOTE_ONLY FUNC_API_LUA_ONLY

	ArrayOf (Tabpage)

Tabpage	nvim_get_current_tabpage (void)

void	nvim_set_current_tabpage (Tabpage tabpage, Error *err) FUNC_API_CHECK_TEXTLOCK

Boolean	nvim_paste (String data, Boolean crlf, Integer phase, Error *err) FUNC_API_CHECK_TEXTLOCK

void	nvim_put (ArrayOf(String) lines, String type, Boolean after, Boolean follow, Error *err) FUNC_API_CHECK_TEXTLOCK

void	nvim_subscribe (uint64_t channel_id, String event) FUNC_API_SINCE(1) FUNC_API_REMOTE_ONLY

void	nvim_unsubscribe (uint64_t channel_id, String event) FUNC_API_SINCE(1) FUNC_API_REMOTE_ONLY

Integer	nvim_get_color_by_name (String name) FUNC_API_SINCE(1)

Dictionary	nvim_get_color_map (void)

Dictionary	nvim_get_context (Dict(context) opts, Error err) FUNC_API_SINCE(6)

Object	nvim_load_context (Dictionary dict) FUNC_API_SINCE(6)

Dictionary	nvim_get_mode (void)

	ArrayOf (Dictionary)

void	nvim_set_keymap (uint64_t channel_id, String mode, String lhs, String rhs, Dict(keymap) opts, Error err) FUNC_API_SINCE(6)

void	nvim_del_keymap (uint64_t channel_id, String mode, String lhs, Error *err) FUNC_API_SINCE(6)

Dictionary	nvim_get_commands (Dict(get_commands) opts, Error err) FUNC_API_SINCE(4)

Array	nvim_get_api_info (uint64_t channel_id) FUNC_API_SINCE(1) FUNC_API_FAST FUNC_API_REMOTE_ONLY

void	nvim_set_client_info (uint64_t channel_id, String name, Dictionary version, String type, Dictionary methods, Dictionary attributes, Error *err) FUNC_API_SINCE(4) FUNC_API_REMOTE_ONLY

Dictionary	nvim_get_chan_info (Integer chan, Error *err) FUNC_API_SINCE(4)

Array	nvim_list_chans (void)

Array	nvim_call_atomic (uint64_t channel_id, Array calls, Error *err) FUNC_API_SINCE(1) FUNC_API_REMOTE_ONLY

Object	nvim__id (Object obj)

Array	nvim__id_array (Array arr)

Dictionary	nvim__id_dictionary (Dictionary dct)

Float	nvim__id_float (Float flt)

Dictionary	nvim__stats (void)

Array	nvim_list_uis (void)

Array	nvim_get_proc_children (Integer pid, Error *err) FUNC_API_SINCE(4)

Object	nvim_get_proc (Integer pid, Error *err) FUNC_API_SINCE(4)

void	nvim_select_popupmenu_item (Integer item, Boolean insert, Boolean finish, Dictionary opts, Error *err) FUNC_API_SINCE(6)

Array	nvim__inspect_cell (Integer grid, Integer row, Integer col, Error *err)
	NB: if your UI doesn't use hlstate, this will not return hlstate first time. More...

void	nvim__screenshot (String path) FUNC_API_FAST

Boolean	nvim_del_mark (String name, Error *err) FUNC_API_SINCE(8)

Array	nvim_get_mark (String name, Dictionary opts, Error *err) FUNC_API_SINCE(8)

Dictionary	nvim_eval_statusline (String str, Dict(eval_statusline) opts, Error err) FUNC_API_SINCE(8) FUNC_API_FAST

void	nvim_create_user_command (String name, Object command, Dict(user_command) opts, Error err) FUNC_API_SINCE(9)

void	nvim_del_user_command (String name, Error *err) FUNC_API_SINCE(9)

Macro Definition Documentation

◆ LINE_BUFFER_SIZE

#define LINE_BUFFER_SIZE 4096

◆ PUSH_CHAR

#define PUSH_CHAR	(	i,
		pos,
		line_buf,
		msg
	)

Value:

  if (message.data[i] == NL || pos == LINE_BUFFER_SIZE - 1) { \
    line_buf[pos] = NUL; \
    msg(line_buf); \
    pos = 0; \
    continue; \
  } \
  line_buf[pos++] = message.data[i];

Function Documentation

◆ ArrayOf() [1/5]

ArrayOf ( Buffer )

Gets the current list of buffer handles

Includes unlisted (unloaded/deleted) buffers, like :ls!. Use |nvim_buf_is_loaded()| to check if a buffer is loaded.

Returns: List of buffer handles

◆ ArrayOf() [2/5]

ArrayOf ( Dictionary )

Gets a list of global (non-buffer-local) |mapping| definitions.

Parameters

mode	Mode short-name ("n", "i", "v", ...)

Returns: Array of maparg()-like dictionaries describing mappings. The "buffer" key is always zero.

◆ ArrayOf() [3/5]

ArrayOf ( String )

Gets the paths contained in 'runtimepath'.

Returns: List of paths

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.

Parameters

name	pattern of files to search for
all	whether to return all matches or only the first

Returns: list of absolute paths to the found files

Find files in runtime directories

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

Returns: list of absolute paths to the found files

◆ ArrayOf() [4/5]

ArrayOf ( Tabpage )

Gets the current list of tabpage handles.

Returns: List of tabpage handles

◆ ArrayOf() [5/5]

ArrayOf ( Window )

Gets the current list of window handles.

Returns: List of window handles

◆ nvim__get_hl_defs()

Dictionary nvim__get_hl_defs	(	Integer	ns_id,
		Error *	err
	)

◆ nvim__get_lib_dir()

String nvim__get_lib_dir ( void )

◆ nvim__id()

Object nvim__id ( Object obj )

Returns object given as argument.

This API function is used for testing. One should not rely on its presence in plugins.

Parameters

[in] obj Object to return.

Returns: its argument.

◆ nvim__id_array()

Array nvim__id_array ( Array arr )

Returns array given as argument.

This API function is used for testing. One should not rely on its presence in plugins.

Parameters

[in] arr Array to return.

Returns: its argument.

◆ nvim__id_dictionary()

Dictionary nvim__id_dictionary ( Dictionary dct )

Returns dictionary given as argument.

This API function is used for testing. One should not rely on its presence in plugins.

Parameters

[in] dct Dictionary to return.

Returns: its argument.

◆ nvim__id_float()

Float nvim__id_float ( Float flt )

Returns floating-point value given as argument.

This API function is used for testing. One should not rely on its presence in plugins.

Parameters

[in] flt Value to return.

Returns: its argument.

◆ nvim__inspect_cell()

Array nvim__inspect_cell	(	Integer	grid,
		Integer	row,
		Integer	col,
		Error *	err
	)

NB: if your UI doesn't use hlstate, this will not return hlstate first time.

◆ nvim__runtime_inspect()

Array nvim__runtime_inspect ( void )

◆ nvim__screenshot()

void nvim__screenshot ( String path )

◆ nvim__set_hl_ns()

void nvim__set_hl_ns	(	Integer	ns_id,
		Error *	err
	)

Set active namespace for highlights.

NB: this function can be called from async contexts, but the semantics are not yet well-defined. To start with |nvim_set_decoration_provider| on_win and on_line callbacks are explicitly allowed to change the namespace during a redraw cycle.

Parameters

	ns_id	the namespace to activate
[out]	err	Error details, if any

◆ nvim__stats()

Dictionary nvim__stats ( void )

Gets internal stats.

Returns: Map of various internal stats.

◆ nvim_call_atomic()

Array nvim_call_atomic	(	uint64_t	channel_id,
		Array	calls,
		Error *	err
	)

Calls many API methods atomically.

This has two main usages:

To perform several requests from an async context atomically, i.e. without interleaving redraws, RPC requests from other clients, or user interactions (however API methods may trigger autocommands or event processing which have such side effects, e.g. |:sleep| may wake timers).
To minimize RPC overhead (roundtrips) of a sequence of many requests.

Parameters

	channel_id
	calls	an array of calls, where each call is described by an array with two elements: the request name, and an array of arguments.
[out]	err	Validation error details (malformed `calls` parameter), if any. Errors from batched calls are given in the return value.

Returns: Array of two elements. The first is an array of return values. The second is NIL if all calls succeeded. If a call resulted in an error, it is a three-element array with the zero-based index of the call which resulted in an error, the error type and the error message. If an error occurred, the values from all preceding calls will still be returned.

◆ nvim_chan_send()

void nvim_chan_send	(	Integer	chan,
		String	data,
		Error *	err
	)

This function writes raw data, not RPC messages. If the channel was created with rpc=true then the channel expects RPC messages, use |vim.rpcnotify()| and |vim.rpcrequest()| instead.

Parameters

	chan	id of the channel
	data	data to write. 8-bit clean: can contain NUL bytes.
[out]	err	Error details, if any

◆ nvim_create_buf()

Buffer nvim_create_buf	(	Boolean	listed,
		Boolean	scratch,
		Error *	err
	)

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.
[out]	err	Error details, if any

Returns: Buffer handle, or 0 on error

See also: buf_open_scratch

◆ nvim_create_user_command()

void nvim_create_user_command	(	String	name,
		Object	command,
		Dict(user_command) *	opts,
		Error *	err
	)

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 \|<args>\| fargs: (table) The args split by unescaped whitespace (when more than one argument is allowed), if any \|<f-args>\| bang: (boolean) "true" if the command was executed with a ! modifier \|<bang>\| line1: (number) The starting line of the command range \|<line1>\| line2: (number) The final line of the command range \|<line2>\| range: (number) The number of items in the command range: 0, 1, or 2 \|<range>\| count: (number) Any count supplied \|<count>\| reg: (string) The optional register, if specified \|<reg>\| mods: (string) Command modifiers, if any \|<mods>\|
	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.
[out]	err	Error details, if any.

◆ nvim_del_current_line()

void nvim_del_current_line ( Error * err )

Deletes the current line.

Parameters

[out] err Error details, if any

◆ nvim_del_keymap()

void nvim_del_keymap	(	uint64_t	channel_id,
		String	mode,
		String	lhs,
		Error *	err
	)

Unmaps a global |mapping| for the given mode.

To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|.

See also: |nvim_set_keymap()|

◆ nvim_del_mark()

Boolean nvim_del_mark	(	String	name,
		Error *	err
	)

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

Returns: true if the mark was deleted, else false.

See also: |nvim_buf_del_mark()|; |nvim_get_mark()|

◆ nvim_del_user_command()

void nvim_del_user_command	(	String	name,
		Error *	err
	)

Delete a user-defined command.

Parameters

	name	Name of the command to delete.
[out]	err	Error details, if any.

◆ nvim_del_var()

void nvim_del_var	(	String	name,
		Error *	err
	)

Removes a global (g:) variable.

Parameters

	name	Variable name
[out]	err	Error details, if any

◆ nvim_echo()

void nvim_echo	(	Array	chunks,
		Boolean	history,
		Dictionary	opts,
		Error *	err
	)

Echo a message.

Parameters

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. Reserved for future use.

◆ nvim_err_write()

void nvim_err_write ( String str )

Writes a message to the Vim error buffer. Does not append "\n", the message is buffered (won't display) until a linefeed is written.

Parameters

str Message

◆ nvim_err_writeln()

void nvim_err_writeln ( String str )

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()

◆ nvim_eval_statusline()

Dictionary nvim_eval_statusline	(	String	str,
		Dict(eval_statusline) *	opts,
		Error *	err
	)

Evaluates statusline string.

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_tabline: (boolean) Evaluate tabline instead of statusline. When \|TRUE\|, {winid} is ignored.
[out]	err	Error details, if any.

Returns

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.

◆ nvim_exec_lua()

Object nvim_exec_lua	(	String	code,
		Array	args,
		Error *	err
	)

Execute Lua code. Parameters (if any) are available as ... inside the chunk. The chunk can return a value.

Only statements are executed. To evaluate an expression, prefix it with return: return my_function(...)

Parameters

	code	Lua code to execute
	args	Arguments to the code
[out]	err	Details of an error encountered while parsing or executing the Lua code.

Returns: Return value of Lua code if present or NIL.

◆ nvim_feedkeys()

void nvim_feedkeys	(	String	keys,
		String	mode,
		Boolean	escape_ks
	)

Sends input-keys to Nvim, subject to various quirks controlled by mode flags. This is a blocking call, unlike |nvim_input()|.

On execution error: does not fail, but updates v:errmsg.

To input sequences like <C-o> use |nvim_replace_termcodes()| (typically with escape_ks=false) to replace |keycodes|, then pass the result to nvim_feedkeys().

Example:

    :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
    :call nvim_feedkeys(key, 'n', v:false)

Parameters

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.

See also: feedkeys(); vim_strsave_escape_ks

◆ nvim_get_all_options_info()

Dictionary nvim_get_all_options_info ( Error * err )

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|.

Returns: dictionary of all options

◆ nvim_get_api_info()

Array nvim_get_api_info ( uint64_t channel_id )

Returns a 2-tuple (Array), where item 0 is the current channel id and item 1 is the |api-metadata| map (Dictionary).

Returns: 2-tuple [{channel-id}, {api-metadata}]

◆ nvim_get_chan_info()

Dictionary nvim_get_chan_info	(	Integer	chan,
		Error *	err
	)

Gets information about a channel.

Returns

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()|.

◆ nvim_get_color_by_name()

Integer nvim_get_color_by_name ( String name )

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

Returns: 24-bit RGB value, or -1 for invalid argument.

◆ nvim_get_color_map()

Dictionary nvim_get_color_map ( void )

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).

Returns: Map of color names and RGB values.

◆ nvim_get_commands()

Dictionary nvim_get_commands	(	Dict(get_commands) *	opts,
		Error *	err
	)

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}
[out]	err	Error details, if any.

Returns: Map of maps describing commands.

◆ nvim_get_context()

Dictionary nvim_get_context	(	Dict(context) *	opts,
		Error *	err
	)

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".
[out]	err	Error details, if any

Returns: map of global |context|.

◆ nvim_get_current_buf()

Buffer nvim_get_current_buf ( void )

Gets the current buffer.

Returns: Buffer handle

◆ nvim_get_current_line()

String nvim_get_current_line ( Error * err )

Gets the current line.

Parameters

[out] err Error details, if any

Returns: Current line string

◆ nvim_get_current_tabpage()

Tabpage nvim_get_current_tabpage ( void )

Gets the current tabpage.

Returns: Tabpage handle

◆ nvim_get_current_win()

Window nvim_get_current_win ( void )

Gets the current window.

Returns: Window handle

◆ nvim_get_hl_by_id()

Dictionary nvim_get_hl_by_id	(	Integer	hl_id,
		Boolean	rgb,
		Error *	err
	)

Gets a highlight definition by id. |hlID()|

Parameters

	hl_id	Highlight id as returned by \|hlID()\|
	rgb	Export RGB colors
[out]	err	Error details, if any

Returns: Highlight definition map

See also: nvim_get_hl_by_name

◆ nvim_get_hl_by_name()

Dictionary nvim_get_hl_by_name	(	String	name,
		Boolean	rgb,
		Error *	err
	)

Gets a highlight definition by name.

Parameters

	name	Highlight group name
	rgb	Export RGB colors
[out]	err	Error details, if any

Returns: Highlight definition map

See also: nvim_get_hl_by_id

◆ nvim_get_hl_id_by_name()

Integer nvim_get_hl_id_by_name ( String name )

Gets a highlight group by name

similar to |hlID()|, but allocates a new ID if not present.

◆ nvim_get_mark()

Array nvim_get_mark	(	String	name,
		Dictionary	opts,
		Error *	err
	)

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.

Returns: 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is not set.

See also: |nvim_buf_set_mark()|; |nvim_del_mark()|

◆ nvim_get_mode()

Dictionary nvim_get_mode ( void )

Gets the current mode. |mode()| "blocking" is true if Nvim is waiting for input.

Returns: Dictionary { "mode": String, "blocking": Boolean }

◆ nvim_get_option()

Object nvim_get_option	(	String	name,
		Error *	err
	)

Gets the global value of an option.

Parameters

	name	Option name
[out]	err	Error details, if any

Returns: Option value (global)

◆ nvim_get_option_info()

Dictionary nvim_get_option_info	(	String	name,
		Error *	err
	)

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
[out]	err	Error details, if any

Returns: Option Information

◆ nvim_get_option_value()

Object nvim_get_option_value	(	String	name,
		Dict(option) *	opts,
		Error *	err
	)

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. To get a buffer-local or window-local option for a specific buffer or window, use |nvim_buf_get_option()| or |nvim_win_get_option()|.

Parameters

	name	Option name
	opts	Optional parameters scope: One of 'global' or 'local'. Analogous to \|:setglobal\| and \|:setlocal\|, respectively.
[out]	err	Error details, if any

Returns: Option value

◆ nvim_get_proc()

Object nvim_get_proc	(	Integer	pid,
		Error *	err
	)

Gets info describing process pid.

Returns: Map of process properties, or NIL if process not found.

◆ nvim_get_proc_children()

Array nvim_get_proc_children	(	Integer	pid,
		Error *	err
	)

Gets the immediate children of process pid.

Returns: Array of child process ids, empty if process not found.

◆ nvim_get_var()

Object nvim_get_var	(	String	name,
		Error *	err
	)

Gets a global (g:) variable.

Parameters

	name	Variable name
[out]	err	Error details, if any

Returns: Variable value

◆ nvim_get_vvar()

Object nvim_get_vvar	(	String	name,
		Error *	err
	)

Gets a v: variable.

Parameters

	name	Variable name
[out]	err	Error details, if any

Returns: Variable value

◆ nvim_input()

Integer nvim_input ( String keys )

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 <CR> are translated, so "<" is special. To input a literal "<", send <LT>.; For mouse events use |nvim_input_mouse()|. The pseudokey form "<LeftMouse><col,row>" is deprecated since |api-level| 6.

Parameters

keys	to be typed

Returns: Number of bytes actually written (can be fewer than requested if the buffer becomes full).

◆ nvim_input_mouse()

void nvim_input_mouse	(	String	button,
		String	action,
		String	modifier,
		Integer	grid,
		Integer	row,
		Integer	col,
		Error *	err
	)

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 ("<LeftMouse><col,row>") of |nvim_input()| has the same limitation.

Parameters

	button	Mouse button: one of "left", "right", "middle", "wheel".
	action	For ordinary buttons, one of "press", "drag", "release". For the wheel, one of "up", "down", "left", "right".
	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)
[out]	err	Error details, if any

◆ nvim_list_chans()

Array nvim_list_chans ( void )

Get information about all open channels.

Returns: Array of Dictionaries, each describing a channel with the format specified at |nvim_get_chan_info()|.

◆ nvim_list_uis()

Array nvim_list_uis ( void )

Gets a list of dictionaries representing attached UIs.

Returns

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)

◆ nvim_load_context()

Object nvim_load_context ( Dictionary dict )

Sets the current editor state from the given |context| map.

Parameters

dict	\|Context\| map.

◆ nvim_notify()

Object nvim_notify	(	String	msg,
		Integer	log_level,
		Dictionary	opts,
		Error *	err
	)

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.
[out]	err	Error details, if any

◆ nvim_open_term()

Integer nvim_open_term	(	Buffer	buffer,
		DictionaryOf(LuaRef)	opts,
		Error *	err
	)

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]
[out]	err	Error details, if any

Returns: Channel id, or 0 on error

◆ nvim_out_write()

void nvim_out_write ( String str )

Writes a message to the Vim output buffer. Does not append "\n", the message is buffered (won't display) until a linefeed is written.

Parameters

str Message

◆ nvim_paste()

Boolean nvim_paste	(	String	data,
		Boolean	crlf,
		Integer	phase,
		Error *	err
	)

Pastes at cursor, in any mode.

Invokes the vim.paste handler, which handles each mode appropriately. Sets redo/undo. Faster than |nvim_input()|. Lines break at LF ("\n").

Errors ('nomodifiable', vim.paste() failure, …) are reflected in err but do not affect the return value (which is strictly decided by vim.paste()). On error, subsequent calls are ignored ("drained") until the next paste is initiated (phase 1 or -1).

Parameters

	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: 1: starts the paste (exactly once) 2: continues the paste (zero or more times) 3: ends the paste (exactly once)
[out]	err	Error details, if any

Returns

true: Client may continue pasting.
false: Client must cancel the paste.

◆ nvim_put()

void nvim_put	(	ArrayOf(String)	lines,
		String	type,
		Boolean	after,
		Boolean	follow,
		Error *	err
	)

Puts text at cursor, in any mode.

Compare |:put| and |p| which are always linewise.

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.
[out]	err	Error details, if any

◆ nvim_replace_termcodes()

String nvim_replace_termcodes	(	String	str,
		Boolean	from_part,
		Boolean	do_lt,
		Boolean	special
	)

Replaces terminal codes and |keycodes| (<CR>, <Esc>, ...) in a string with the internal representation.

Parameters

str	String to be converted.
from_part	Legacy Vim parameter. Usually true.
do_lt	Also translate <lt>. Ignored if `special` is false.
special	Replace \|keycodes\|, e.g. <CR> becomes a "\r" char.

See also: replace_termcodes; cpoptions

◆ nvim_select_popupmenu_item()

void nvim_select_popupmenu_item	(	Integer	item,
		Boolean	insert,
		Boolean	finish,
		Dictionary	opts,
		Error *	err
	)

Selects an item in the completion popupmenu.

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 `insert`.
	opts	Optional parameters. Reserved for future use.
[out]	err	Error details, if any

◆ nvim_set_client_info()

void nvim_set_client_info	(	uint64_t	channel_id,
		String	name,
		Dictionary	version,
		String	type,
		Dictionary	methods,
		Dictionary	attributes,
		Error *	err
	)

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.

Parameters

	channel_id
	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.
[out]	err	Error details, if any

◆ nvim_set_current_buf()

void nvim_set_current_buf	(	Buffer	buffer,
		Error *	err
	)

Sets the current buffer.

Parameters

	buffer	Buffer handle
[out]	err	Error details, if any

◆ nvim_set_current_dir()

void nvim_set_current_dir	(	String	dir,
		Error *	err
	)

Changes the global working directory.

Parameters

	dir	Directory path
[out]	err	Error details, if any

◆ nvim_set_current_line()

void nvim_set_current_line	(	String	line,
		Error *	err
	)

Sets the current line.

Parameters

	line	Line contents
[out]	err	Error details, if any

◆ nvim_set_current_tabpage()

void nvim_set_current_tabpage	(	Tabpage	tabpage,
		Error *	err
	)

Sets the current tabpage.

Parameters

	tabpage	Tabpage handle
[out]	err	Error details, if any

◆ nvim_set_current_win()

void nvim_set_current_win	(	Window	window,
		Error *	err
	)

Sets the current window.

Parameters

	window	Window handle
[out]	err	Error details, if any

◆ nvim_set_hl()

void nvim_set_hl	(	Integer	ns_id,
		String	name,
		Dict(highlight) *	val,
		Error *	err
	)

Sets a highlight group.

Note: Unlike the :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'.

Parameters

	ns_id	Namespace id for this highlight \|nvim_create_namespace()\|. Use 0 to set a highlight group globally \|:highlight\|.
	name	Highlight group name, e.g. "ErrorMsg"
	val	Highlight definition map, like \|synIDattr()\|. In addition, the following keys are recognized: default: Don't override existing definition \|:hi-default\| ctermfg: Sets foreground of cterm color \|highlight-ctermfg\| ctermbg: Sets background of cterm color \|highlight-ctermbg\| cterm: cterm attribute map, like \|highlight-args\|. Note: Attributes default to those set for `gui` if not set.
[out]	err	Error details, if any

◆ nvim_set_keymap()

void nvim_set_keymap	(	uint64_t	channel_id,
		String	mode,
		String	lhs,
		String	rhs,
		Dict(keymap) *	opts,
		Error *	err
	)

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 |<Nop>|. |keycodes| are replaced as usual.

Example:

    call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})

is equivalent to:

    nmap <nowait> <Space><NL> <Nop>

Parameters

	channel_id
	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. Accepts all \|:map-arguments\| as keys excluding \|<buffer>\| but including \|noremap\| and "desc". "desc" can be used to give a description to keymap. When called from Lua, also accepts a "callback" key that takes a Lua function to call when the mapping is executed. Values are Booleans. Unknown key is an error.
[out]	err	Error details, if any.

◆ nvim_set_option()

void nvim_set_option	(	uint64_t	channel_id,
		String	name,
		Object	value,
		Error *	err
	)

Sets the global value of an option.

Parameters

	channel_id
	name	Option name
	value	New option value
[out]	err	Error details, if any

◆ nvim_set_option_value()

void nvim_set_option_value	(	String	name,
		Object	value,
		Dict(option) *	opts,
		Error *	err
	)

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}.

Parameters

	name	Option name
	value	New option value
	opts	Optional parameters scope: One of 'global' or 'local'. Analogous to \|:setglobal\| and \|:setlocal\|, respectively.
[out]	err	Error details, if any

◆ nvim_set_var()

void nvim_set_var	(	String	name,
		Object	value,
		Error *	err
	)

Sets a global (g:) variable.

Parameters

	name	Variable name
	value	Variable value
[out]	err	Error details, if any

◆ nvim_set_vvar()

void nvim_set_vvar	(	String	name,
		Object	value,
		Error *	err
	)

Sets a v: variable, if it is not readonly.

Parameters

	name	Variable name
	value	Variable value
[out]	err	Error details, if any

◆ nvim_strwidth()

Integer nvim_strwidth	(	String	text,
		Error *	err
	)

Calculates the number of display cells occupied by text. <Tab> counts as one cell.

Parameters

	text	Some text
[out]	err	Error details, if any

Returns: Number of cells

◆ nvim_subscribe()

void nvim_subscribe	(	uint64_t	channel_id,
		String	event
	)

Subscribes to event broadcasts.

Parameters

channel_id	Channel id (passed automatically by the dispatcher)
event	Event type string

◆ nvim_unsubscribe()

void nvim_unsubscribe	(	uint64_t	channel_id,
		String	event
	)

Unsubscribes to event broadcasts.

Parameters

channel_id	Channel id (passed automatically by the dispatcher)
event	Event type string

Macros

Functions

Macro Definition Documentation

◆ LINE_BUFFER_SIZE

◆ PUSH_CHAR

Function Documentation

◆ ArrayOf() [1/5]

◆ ArrayOf() [2/5]

◆ ArrayOf() [3/5]

◆ ArrayOf() [4/5]

◆ ArrayOf() [5/5]

◆ nvim__get_hl_defs()

◆ nvim__get_lib_dir()

◆ nvim__id()

◆ nvim__id_array()

◆ nvim__id_dictionary()

◆ nvim__id_float()

◆ nvim__inspect_cell()

◆ nvim__runtime_inspect()

◆ nvim__screenshot()

◆ nvim__set_hl_ns()

◆ nvim__stats()

◆ nvim_call_atomic()

◆ nvim_chan_send()

◆ nvim_create_buf()

◆ nvim_create_user_command()

◆ nvim_del_current_line()

◆ nvim_del_keymap()

◆ nvim_del_mark()

◆ nvim_del_user_command()

◆ nvim_del_var()

◆ nvim_echo()

◆ nvim_err_write()

◆ nvim_err_writeln()

◆ nvim_eval_statusline()

◆ nvim_exec_lua()

◆ nvim_feedkeys()

◆ nvim_get_all_options_info()

◆ nvim_get_api_info()

◆ nvim_get_chan_info()

◆ nvim_get_color_by_name()

◆ nvim_get_color_map()

◆ nvim_get_commands()

◆ nvim_get_context()

◆ nvim_get_current_buf()

◆ nvim_get_current_line()

◆ nvim_get_current_tabpage()

◆ nvim_get_current_win()

◆ nvim_get_hl_by_id()

◆ nvim_get_hl_by_name()

◆ nvim_get_hl_id_by_name()

◆ nvim_get_mark()

◆ nvim_get_mode()

◆ nvim_get_option()

◆ nvim_get_option_info()

◆ nvim_get_option_value()

◆ nvim_get_proc()

◆ nvim_get_proc_children()

◆ nvim_get_var()

◆ nvim_get_vvar()

◆ nvim_input()

◆ nvim_input_mouse()

◆ nvim_list_chans()

◆ nvim_list_uis()

◆ nvim_load_context()

◆ nvim_notify()

◆ nvim_open_term()

◆ nvim_out_write()

◆ nvim_paste()

◆ nvim_put()

◆ nvim_replace_termcodes()

◆ nvim_select_popupmenu_item()

◆ nvim_set_client_info()

◆ nvim_set_current_buf()

◆ nvim_set_current_dir()

◆ nvim_set_current_line()

◆ nvim_set_current_tabpage()

◆ nvim_set_current_win()

◆ nvim_set_hl()

◆ nvim_set_keymap()