vim.c File Reference

#include <assert.h>
#include <inttypes.h>
#include <stdbool.h>
#include <stdlib.h>
#include <string.h>
#include <limits.h>
#include "nvim/api/vim.h"
#include "nvim/ascii.h"
#include "nvim/api/private/helpers.h"
#include "nvim/api/private/defs.h"
#include "nvim/api/private/dispatch.h"
#include "nvim/api/buffer.h"
#include "nvim/api/window.h"
#include "nvim/msgpack_rpc/channel.h"
#include "nvim/msgpack_rpc/helpers.h"
#include "nvim/lua/executor.h"
#include "nvim/vim.h"
#include "nvim/buffer.h"
#include "nvim/context.h"
#include "nvim/file_search.h"
#include "nvim/highlight.h"
#include "nvim/window.h"
#include "nvim/types.h"
#include "nvim/ex_cmds2.h"
#include "nvim/ex_docmd.h"
#include "nvim/screen.h"
#include "nvim/memline.h"
#include "nvim/mark.h"
#include "nvim/memory.h"
#include "nvim/message.h"
#include "nvim/popupmnu.h"
#include "nvim/edit.h"
#include "nvim/eval.h"
#include "nvim/eval/typval.h"
#include "nvim/fileio.h"
#include "nvim/ops.h"
#include "nvim/option.h"
#include "nvim/state.h"
#include "nvim/extmark.h"
#include "nvim/syntax.h"
#include "nvim/getchar.h"
#include "nvim/os/input.h"
#include "nvim/os/process.h"
#include "nvim/viml/parser/expressions.h"
#include "nvim/viml/parser/parser.h"
#include "nvim/ui.h"

Data Structures
struct	ExprASTConvStackItem

Macros
#define	LINE_BUFFER_SIZE   4096
#define	PUSH_CHAR(i, pos, line_buf, msg)

Functions
void	api_vim_init (void)
void	api_vim_free_all_mem (void)
String	nvim_exec (String src, Boolean output, Error *err) FUNC_API_SINCE(7)
void	nvim_command (String command, Error *err) FUNC_API_SINCE(1)
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)
void	nvim_feedkeys (String keys, String mode, Boolean escape_csi) 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)
String	nvim_command_output (String command, Error *err) FUNC_API_DEPRECATED_SINCE(7)
Object	nvim_eval (String expr, Error *err) FUNC_API_SINCE(1)
Object	nvim_execute_lua (String code, Array args, Error *err) FUNC_API_REMOTE_ONLY
Object	nvim_exec_lua (String code, Array args, Error *err) FUNC_API_REMOTE_ONLY
Object	nvim_call_function (String fn, Array args, Error *err) FUNC_API_SINCE(1)
Object	nvim_call_dict_function (Object dict, String fn, Array args, Error *err) FUNC_API_SINCE(4)
Integer	nvim_strwidth (String text, Error *err) FUNC_API_SINCE(1)
	ArrayOf (String)
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_SINCE(1)
void	nvim_del_current_line (Error *err) FUNC_API_SINCE(1)
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	vim_set_var (String name, Object value, Error *err)
Object	vim_del_var (String name, Error *err)
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)
void	nvim_set_option (uint64_t channel_id, String name, Object value, Error *err) FUNC_API_SINCE(1)
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_SINCE(1)
	ArrayOf (Window)
Window	nvim_get_current_win (void)
void	nvim_set_current_win (Window window, Error *err) FUNC_API_SINCE(1)
Buffer	nvim_create_buf (Boolean listed, Boolean scratch, Error *err) FUNC_API_SINCE(6)
Window	nvim_open_win (Buffer buffer, Boolean enter, Dictionary config, Error *err) FUNC_API_SINCE(6)
	ArrayOf (Tabpage)
Tabpage	nvim_get_current_tabpage (void)
void	nvim_set_current_tabpage (Tabpage tabpage, Error *err) FUNC_API_SINCE(1)
Integer	nvim_create_namespace (String name) FUNC_API_SINCE(5)
Dictionary	nvim_get_namespaces (void)
Boolean	nvim_paste (String data, Boolean crlf, Integer phase, Error *err) FUNC_API_SINCE(6)
void	nvim_put (ArrayOf(String) lines, String type, Boolean after, Boolean follow, Error *err) FUNC_API_SINCE(6)
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 (Dictionary 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 (String mode, String lhs, String rhs, Dictionary opts, Error *err) FUNC_API_SINCE(6)
void	nvim_del_keymap (String mode, String lhs, Error *err) FUNC_API_SINCE(6)
Dictionary	nvim_get_commands (Dictionary 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
Dictionary	nvim_parse_expression (String expr, String flags, Boolean highlight, Error *err) FUNC_API_SINCE(4) FUNC_API_FAST
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__put_attr (Integer id, Integer start_row, Integer start_col, Integer end_row, Integer end_col) FUNC_API_LUA_ONLY

Macro Definition Documentation

#define LINE_BUFFER_SIZE   4096

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

Value:

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

Function Documentation

void api_vim_free_all_mem

(

void

)

void api_vim_init

(

void

)

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.

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

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

(

Window

)

Gets the current list of window handles.

Returns

List of window handles

ArrayOf

(

Tabpage

)

Gets the current list of tabpage handles.

Returns

List of tabpage handles

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.

String nvim__get_lib_dir

(

void

)

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.

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.

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.

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.

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.

void nvim__put_attr	(	Integer	id,
		Integer	start_row,
		Integer	start_col,
		Integer	end_row,
		Integer	end_col
	)

Set attrs in nvim__buf_set_lua_hl callbacks

TODO(bfredl): This is rather pedestrian. The final interface should probably be derived from a reformed bufhl/virttext interface with full support for multi-line ranges etc

Dictionary nvim__stats

(

void

)

Gets internal stats.

Returns

Map of various internal stats.

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

Calls many API methods atomically.

This has two main usages:

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

Object nvim_call_dict_function	(	Object	dict,
		String	fn,
		Array	args,
		Error *	err
	)

Calls a VimL |Dictionary-function| with the given arguments.

On execution error: fails with VimL error, does not update v:errmsg.

Parameters

	dict	Dictionary, or String evaluating to a VimL |self| dict
	fn	Name of the function defined on the VimL dict
	args	Function arguments packed in an Array
[out]	err	Error details, if any

Returns

Result of the function call

Object nvim_call_function	(	String	fn,
		Array	args,
		Error *	err
	)

Calls a VimL function with the given arguments.

On execution error: fails with VimL error, does not update v:errmsg.

Parameters

	fn	Function to call
	args	Function arguments packed in an Array
[out]	err	Error details, if any

Returns

Result of the function call

void nvim_command	(	String	command,
		Error *	err
	)

Executes an ex-command.

On execution error: fails with VimL error, does not update v:errmsg.

See also

|nvim_exec()|

Parameters

	command	Ex-command string
[out]	err	Error details (Vim error), if any

String nvim_command_output	(	String	command,
		Error *	err
	)

Deprecated:

See also

nvim_exec

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

Returns

Buffer handle, or 0 on error

See also

buf_open_scratch

Integer nvim_create_namespace

(

String

name

)

Creates a new namespace, or gets an existing one.

Namespaces are used for buffer highlights and virtual text, see |nvim_buf_add_highlight()| and |nvim_buf_set_virtual_text()|.

Namespaces can be named or anonymous. If name matches an existing namespace, the associated id is returned. If name is an empty string a new, anonymous namespace is created.

Parameters

name	Namespace name or empty string

Returns

Namespace id

void nvim_del_current_line

(

Error *

err

)

Deletes the current line.

Parameters

[out]

err

Error details, if any

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

void nvim_del_var	(	String	name,
		Error *	err
	)

Removes a global (g:) variable.

Parameters

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

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

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

Object nvim_eval	(	String	expr,
		Error *	err
	)

Evaluates a VimL |expression|. Dictionaries and Lists are recursively expanded.

On execution error: fails with VimL error, does not update v:errmsg.

Parameters

	expr	VimL expression string
[out]	err	Error details, if any

Returns

Evaluation result or expanded object

String nvim_exec	(	String	src,
		Boolean	output,
		Error *	err
	)

Executes Vimscript (multiline block of Ex-commands), like anonymous |:source|.

Unlike |nvim_command()| this function supports heredocs, script-scope (s:), etc.

On execution error: fails with VimL error, does not update v:errmsg.

See also

|execute()|

|nvim_command()|

Parameters

	src	Vimscript code
	output	Capture and return all (non-error, non-shell |:!|) output
[out]	err	Error details (Vim error), if any

Returns

Output (non-error, non-shell |:!|) if output is true, else empty string.

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.

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

Deprecated:

Use nvim_exec_lua() instead.

See also

nvim_exec_lua

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

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.

Parameters

keys	to be typed
mode	behavior flags, see |feedkeys()|
escape_csi	If true, escape K_SPECIAL/CSI bytes in keys

See also

feedkeys()

vim_strsave_escape_csi

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

Dictionary nvim_get_chan_info	(	Integer	chan,
		Error *	err
	)

Get information about a channel.

Returns

Dictionary describing a channel, with these keys:

• "stream" the 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" a |terminal| instance interprets ASCII sequences
  • "rpc" |RPC| communication on the channel is active
• "pty" Name of pseudoterminal, if one is used (optional). On a POSIX system, this will be a device path like /dev/pts/1. Even if the name is unknown, the key will still be present to indicate a pty is used. This is currently the case when using winpty on windows.
• "buffer" buffer with connected |terminal| instance (optional)
• "client" information about the client on the other end of the RPC channel, if it has added it using |nvim_set_client_info()|. (optional)

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.

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.

Dictionary nvim_get_commands	(	Dictionary	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.

Dictionary nvim_get_context	(	Dictionary	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|.

Buffer nvim_get_current_buf

(

void

)

Gets the current buffer.

Returns

Buffer handle

String nvim_get_current_line

(

Error *

err

)

Gets the current line.

Parameters

[out]

err

Error details, if any

Returns

Current line string

Tabpage nvim_get_current_tabpage

(

void

)

Gets the current tabpage.

Returns

Tabpage handle

Window nvim_get_current_win

(

void

)

Gets the current window.

Returns

Window handle

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

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

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.

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 }

Dictionary nvim_get_namespaces

(

void

)

Gets existing, non-anonymous namespaces.

Returns

dict that maps from names to namespace ids.

Object nvim_get_option	(	String	name,
		Error *	err
	)

Gets an option value string.

Parameters

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

Returns

Option value (global)

Object nvim_get_proc	(	Integer	pid,
		Error *	err
	)

Gets info describing process pid.

Returns

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

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.

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

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

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

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

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

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

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)

Object nvim_load_context

(

Dictionary

dict

)

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

Parameters

dict	|Context| map.

Window nvim_open_win	(	Buffer	buffer,
		Boolean	enter,
		Dictionary	config,
		Error *	err
	)

Open a new window.

Currently this is used to open floating and external windows. Floats are windows that are drawn above the split layout, at some anchor position in some other window. Floats can be drawn internally or by external GUI with the |ui-multigrid| extension. External windows are only supported with multigrid GUIs, and are displayed as separate top-level windows.

For a general overview of floats, see |api-floatwin|.

Exactly one of external and relative must be specified. The width and height of the new window must be specified.

With relative=editor (row=0,col=0) refers to the top-left corner of the screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right corner. Fractional values are allowed, but the builtin implementation (used by non-multigrid UIs) will always round down to nearest integer.

Out-of-bounds values, and configurations that make the float not fit inside the main editor, are allowed. The builtin implementation truncates values so floats are fully within the main screen grid. External GUIs could let floats hover outside of the main window like a tooltip, but this should not be used to specify arbitrary WM screen positions.

Example (Lua): window-relative float

    vim.api.nvim_open_win(0, false,
      {relative='win', row=3, col=3, width=12, height=3})

Example (Lua): buffer-relative float (travels as buffer is scrolled)

    vim.api.nvim_open_win(0, false,
      {relative='win', width=12, height=3, bufpos={100,10}})

Parameters

	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: relative: Sets the window layout to "floating", placed at (row,col) coordinates relative to: "editor" The global editor grid "win" Window given by the win field, or current window. "cursor" Cursor position in current window. win: |window-ID| for relative="win". anchor: Decides which corner of the float to place at (row,col): "NW" northwest (default) "NE" northeast "SW" southwest "SE" southeast width: Window width (in character cells). Minimum of 1. height: Window height (in character cells). Minimum of 1. bufpos: Places float relative to buffer text (only when relative="win"). Takes a tuple of zero-indexed [line, column]. row and col if given are applied relative to this position, else they default to row=1 and col=0 (thus like a tooltip near the buffer text). row: Row position in units of "screen cell height", may be fractional. col: Column position in units of "screen cell width", may be fractional. focusable: Enable focus by user actions (wincmds, mouse events). Defaults to true. Non-focusable windows can be entered by |nvim_set_current_win()|. external: GUI should display the window as an external top-level window. Currently accepts no other positioning configuration together with this. style: Configure the appearance of the window. Currently only takes one non-empty value: "minimal" Nvim will display the window with many UI options disabled. This is useful when displaying a temporary float where the text should not be edited. Disables 'number', 'relativenumber', 'cursorline', 'cursorcolumn', 'foldcolumn', 'spell' and 'list' options. 'signcolumn' is changed to auto and 'colorcolumn' is cleared. The end-of-buffer region is hidden by setting eob flag of 'fillchars' to a space char, and clearing the |EndOfBuffer| region in 'winhighlight'.
[out]	err	Error details, if any

Returns

Window handle, or 0 on error

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

Dictionary nvim_parse_expression	(	String	expr,
		String	flags,
		Boolean	highlight,
		Error *	err
	)

Parse a VimL expression.

Parameters

[in]	expr	Expression to parse. Always treated as a single line.
[in]	flags	Flags: "m" if multiple expressions in a row are allowed (only the first one will be parsed), "E" if EOC tokens are not allowed (determines whether they will stop parsing process or be recognized as an operator/space, though also yielding an error). "l" when needing to start parsing with lvalues for ":let" or ":for". Common flag sets: "m" to parse like for ":echo". "E" to parse like for "<C-r>=". empty string for ":call". "lm" to parse for ":let".
[in]	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)).

Returns

• AST: top-level dictionary with these keys:
  • "error": Dictionary with error, present only if parser saw some error. Contains the following keys:
    • "message": String, error message in printf format, translated. Must contain exactly one "%.*s".
    • "arg": String, error message argument.
  • "len": Amount of bytes successfully parsed. With flags equal to "" that should be equal to the length of expr string. (“Sucessfully parsed” here means “participated in AST creation”, not “till the first error”.)
  • "ast": AST, either nil or a dictionary with these keys:
    • "type": node type, one of the value names from ExprASTNodeType stringified without "kExprNode" prefix.
    • "start": a pair [line, column] describing where node is "started" where "line" is always 0 (will not be 0 if you will be using nvim_parse_viml() on e.g. ":let", but that is not present yet). Both elements are Integers.
    • "len": “length” of the node. This and "start" are there for debugging purposes primary (debugging parser and providing debug information).
    • "children": a list of nodes described in top/"ast". There always is zero, one or two children, key will not be present if node has no children. Maximum number of children may be found in node_maxchildren array.
• Local values (present only for certain nodes):
  • "scope": a single Integer, specifies scope for "Option" and "PlainIdentifier" nodes. For "Option" it is one of ExprOptScope values, for "PlainIdentifier" it is one of ExprVarScope values.
  • "ident": identifier (without scope, if any), present for "Option", "PlainIdentifier", "PlainKey" and "Environment" nodes.
  • "name": Integer, register name (one character) or -1. Only present for "Register" nodes.
  • "cmp_type": String, comparison type, one of the value names from ExprComparisonType, stringified without "kExprCmp" prefix. Only present for "Comparison" nodes.
  • "ccs_strategy": String, case comparison strategy, one of the value names from ExprCaseCompareStrategy, stringified without "kCCStrategy" prefix. Only present for "Comparison" nodes.
  • "augmentation": String, augmentation type for "Assignment" nodes. Is either an empty string, "Add", "Subtract" or "Concat" for "=", "+=", "-=" or ".=" respectively.
  • "invert": Boolean, true if result of comparison needs to be inverted. Only present for "Comparison" nodes.
  • "ivalue": Integer, integer value for "Integer" nodes.
  • "fvalue": Float, floating-point value for "Float" nodes.
  • "svalue": String, value for "SingleQuotedString" and "DoubleQuotedString" nodes.

Parameters

[out]

err

Error details, if any

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.

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	Insert after cursor (like |p|), or before (like |P|).
	follow	Place cursor at end of inserted text.
[out]	err	Error details, if any

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 "\n" char.

See also

replace_termcodes

cpoptions

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

Selects an item in the completion popupmenu.

If |ins-completion| is not active this API call is silently ignored. Useful for an external UI using |ui-popupmenu| to control the popupmenu with the mouse. Can also be used in a mapping; use <cmd> |:map-cmd| to ensure the mapping doesn't end completion mode.

Parameters

	item	Index (zero-based) of the item to select. Value of -1 selects nothing and restores the original text.
	insert	Whether the selection should be inserted in the buffer.
	finish	Finish the completion and dismiss the popupmenu. Implies insert.
	opts	Optional parameters. Reserved for future use.
[out]	err	Error details, if any

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

void nvim_set_current_buf	(	Buffer	buffer,
		Error *	err
	)

Sets the current buffer.

Parameters

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

void nvim_set_current_dir	(	String	dir,
		Error *	err
	)

Changes the global working directory.

Parameters

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

void nvim_set_current_line	(	String	line,
		Error *	err
	)

Sets the current line.

Parameters

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

void nvim_set_current_tabpage	(	Tabpage	tabpage,
		Error *	err
	)

Sets the current tabpage.

Parameters

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

void nvim_set_current_win	(	Window	window,
		Error *	err
	)

Sets the current window.

Parameters

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

void nvim_set_keymap	(	String	mode,
		String	lhs,
		String	rhs,
		Dictionary	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

	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|. Values are Booleans. Unknown key is an error.
[out]	err	Error details, if any.

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

Sets an option value.

Parameters

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

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

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

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

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

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

Object vim_del_var	(	String	name,
		Error *	err
	)

Deprecated:

See also

nvim_del_var

Object vim_set_var	(	String	name,
		Object	value,
		Error *	err
	)

Deprecated:

See also

nvim_set_var

Warning

May return nil if there was no previous value OR if previous value was v:null.

Returns

Old value or nil if there was no previous value.