Macros | Functions
vim.c File Reference
#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/context.h"
#include "nvim/decoration.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_docmd.h"
#include "nvim/file_search.h"
#include "nvim/fileio.h"
#include "nvim/getchar.h"
#include "nvim/highlight.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/syntax.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, Dictionary 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_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)
 
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)
 
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 (String mode, String lhs, String rhs, Dict(keymap) *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 (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
 

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
modeMode 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
namepattern of files to search for
allwhether to return all matches or only the first
Returns
list of absolute paths to the found files

Find files in runtime directories

Parameters
patpattern of files to search for
allwhether to return all matches or only the first
optionsis_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]objObject 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]arrArray 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]dctDictionary 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]fltValue 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_idthe namespace to activate
[out]errError 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:

  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
callsan array of calls, where each call is described by an array with two elements: the request name, and an array of arguments.
[out]errValidation 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 
)

Send data to channel id. For a job, it writes it to the stdin of the process. For the stdio channel |channel-stdio|, it writes to Nvim's stdout. For an internal terminal instance (|nvim_open_term()|) it writes directly to terimal output. See |channel-bytes| for more information.

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
chanid of the channel
datadata to write. 8-bit clean: can contain NUL bytes.
[out]errError details, if any

◆ nvim_create_buf()

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

Creates a new, empty, unnamed buffer.

Parameters
listedSets 'buflisted'
scratchCreates a "throwaway" |scratch-buffer| for temporary work (always 'nomodified'). Also sets 'nomodeline' on the buffer.
[out]errError details, if any
Returns
Buffer handle, or 0 on error
See also
buf_open_scratch

◆ nvim_del_current_line()

void nvim_del_current_line ( Error err)

Deletes the current line.

Parameters
[out]errError details, if any

◆ nvim_del_keymap()

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

◆ nvim_del_mark()

Boolean nvim_del_mark ( String  name,
Error err 
)

Deletes a uppercase/file named mark. See |mark-motions|.

Note
fails with error if a lowercase or buffer local named mark is used.
Parameters
nameMark name
Returns
true if the mark was deleted, else false.
See also
|nvim_buf_del_mark()|
|nvim_get_mark()|

◆ nvim_del_var()

void nvim_del_var ( String  name,
Error err 
)

Removes a global (g:) variable.

Parameters
nameVariable name
[out]errError details, if any

◆ nvim_echo()

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

Echo a message.

Parameters
chunksA list of [text, hl_group] arrays, each representing a text chunk with specified highlight. hl_group element can be omitted for no highlight.
historyif true, add to |message-history|.
optsOptional 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
strMessage

◆ 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
strMessage
See also
nvim_err_write()

◆ nvim_eval_statusline()

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

Evaluates statusline string.

Parameters
strStatusline string (see 'statusline').
optsOptional 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').
  • highlights: (boolean) Return highlight information.
  • use_tabline: (boolean) Evaluate tabline instead of statusline. When |TRUE|, {winid} is ignored.
[out]errError 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
codeLua code to execute
argsArguments to the code
[out]errDetails 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_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.

To input sequences like <C-o> use |nvim_replace_termcodes()| (typically with escape_csi=true) 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:true)
Parameters
keysto be typed
modebehavior flags, see |feedkeys()|
escape_csiIf true, escape K_SPECIAL/CSI bytes in keys
See also
feedkeys()
vim_strsave_escape_csi

◆ 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 winpty 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
nameColor 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
optsOptional parameters. Currently only supports {"builtin":false}
[out]errError 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
optsOptional parameters.
  • types: List of |context-types| ("regs", "jumps", "bufs", "gvars", …) to gather, or empty for "all".
[out]errError 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]errError 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_idHighlight id as returned by |hlID()|
rgbExport RGB colors
[out]errError 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
nameHighlight group name
rgbExport RGB colors
[out]errError 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
nameMark name
optsOptional 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 an option value string.

Parameters
nameOption name
[out]errError 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
nameOption name
[out]errError details, if any
Returns
Option Information

◆ 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
nameVariable name
[out]errError details, if any
Returns
Variable value

◆ nvim_get_vvar()

Object nvim_get_vvar ( String  name,
Error err 
)

Gets a v: variable.

Parameters
nameVariable name
[out]errError 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
keysto 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
buttonMouse button: one of "left", "right", "middle", "wheel".
actionFor ordinary buttons, one of "press", "drag", "release". For the wheel, one of "up", "down", "left", "right".
modifierString 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.
gridGrid number if the client uses |ui-multigrid|, else 0.
rowMouse row-position (zero-based, like redraw events)
colMouse column-position (zero-based, like redraw events)
[out]errError 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
msgMessage to display to the user
log_levelThe log level
optsReserved for future use.
[out]errError 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
bufferthe buffer to use (expected to be empty)
optsOptional 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]errError 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
strMessage

◆ 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
dataMultiline input. May be binary (containing NUL bytes).
crlfAlso 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]errError 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|
typeEdit 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()|
afterIf true insert after cursor (like |p|), or before (like |P|).
followIf true place cursor at end of inserted text.
[out]errError 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
strString to be converted.
from_partLegacy Vim parameter. Usually true.
do_ltAlso translate <lt>. Ignored if special is false.
specialReplace |keycodes|, e.g. <CR> becomes a "\n" 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.

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
itemIndex (zero-based) of the item to select. Value of -1 selects nothing and restores the original text.
insertWhether the selection should be inserted in the buffer.
finishFinish the completion and dismiss the popupmenu. Implies insert.
optsOptional parameters. Reserved for future use.
[out]errError 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
nameShort name for the connected client
versionDictionary 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
typeMust 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
methodsBuiltin 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.
attributesArbitrary 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]errError details, if any

◆ nvim_set_current_buf()

void nvim_set_current_buf ( Buffer  buffer,
Error err 
)

Sets the current buffer.

Parameters
bufferBuffer handle
[out]errError details, if any

◆ nvim_set_current_dir()

void nvim_set_current_dir ( String  dir,
Error err 
)

Changes the global working directory.

Parameters
dirDirectory path
[out]errError details, if any

◆ nvim_set_current_line()

void nvim_set_current_line ( String  line,
Error err 
)

Sets the current line.

Parameters
lineLine contents
[out]errError details, if any

◆ nvim_set_current_tabpage()

void nvim_set_current_tabpage ( Tabpage  tabpage,
Error err 
)

Sets the current tabpage.

Parameters
tabpageTabpage handle
[out]errError details, if any

◆ nvim_set_current_win()

void nvim_set_current_win ( Window  window,
Error err 
)

Sets the current window.

Parameters
windowWindow handle
[out]errError details, if any

◆ nvim_set_hl()

void nvim_set_hl ( Integer  ns_id,
String  name,
Dictionary  val,
Error err 
)

Set a highlight group.

Parameters
ns_idnumber of namespace for this highlight
namehighlight group name, like ErrorMsg
valhighlight definition map, like |nvim_get_hl_by_name|. in addition the following keys are also recognized: default: don't override existing definition, like hi default ctermfg: sets foreground of cterm color ctermbg: sets background of cterm color cterm : cterm attribute map. sets attributed for cterm colors. similer to hi cterm Note: by default cterm attributes are same as attributes of gui color
[out]errError details, if any

TODO: ns_id = 0, should modify :highlight namespace TODO val should take update vs reset flag

◆ nvim_set_keymap()

void nvim_set_keymap ( 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
modeMode short-name (map command prefix: "n", "i", "v", "x", …) or "!" for |:map!|, or empty string for |:map|.
lhsLeft-hand-side |{lhs}| of the mapping.
rhsRight-hand-side |{rhs}| of the mapping.
optsOptional parameters map. Accepts all |:map-arguments| as keys excluding |<buffer>| but including |noremap|. Values are Booleans. Unknown key is an error.
[out]errError details, if any.

◆ nvim_set_option()

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

Sets an option value.

Parameters
channel_id
nameOption name
valueNew option value
[out]errError details, if any

◆ nvim_set_var()

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

Sets a global (g:) variable.

Parameters
nameVariable name
valueVariable value
[out]errError 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
nameVariable name
valueVariable value
[out]errError 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
textSome text
[out]errError details, if any
Returns
Number of cells

◆ nvim_subscribe()

void nvim_subscribe ( uint64_t  channel_id,
String  event 
)

Subscribes to event broadcasts.

Parameters
channel_idChannel id (passed automatically by the dispatcher)
eventEvent type string

◆ nvim_unsubscribe()

void nvim_unsubscribe ( uint64_t  channel_id,
String  event 
)

Unsubscribes to event broadcasts.

Parameters
channel_idChannel id (passed automatically by the dispatcher)
eventEvent type string
message
Definition: defs.h:10
i
static void int i
Definition: edit.c:2997
LINE_BUFFER_SIZE
#define LINE_BUFFER_SIZE
Definition: vim.c:57
pos
pos_T pos
Definition: funcs.c:8557
NUL
#define NUL
Definition: ascii.h:19
NL
#define NL
Definition: ascii.h:23