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/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
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
optsis_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 terminal 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_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
nameName of the new user command. Must begin with an uppercase letter.
commandReplacement 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>|
optsOptional 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]errError details, if any.

◆ 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 ( 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
nameMark 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
nameName of the command to delete.
[out]errError details, if any.

◆ 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'). 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]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_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
keysto be typed
modebehavior flags, see |feedkeys()|
escape_ksIf 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
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 the global value of an option.

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_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
nameOption name
optsOptional parameters
  • scope: One of 'global' or 'local'. Analogous to |:setglobal| and |:setlocal|, respectively.
[out]errError 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
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 "\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.

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,
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_idNamespace id for this highlight |nvim_create_namespace()|. Use 0 to set a highlight group globally |:highlight|.
nameHighlight group name, e.g. "ErrorMsg"
valHighlight 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]errError 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
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| 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]errError 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
nameOption name
valueNew option value
[out]errError 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
nameOption name
valueNew option value
optsOptional parameters
  • scope: One of 'global' or 'local'. Analogous to |:setglobal| and |:setlocal|, respectively.
[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:3047
LINE_BUFFER_SIZE
#define LINE_BUFFER_SIZE
Definition: vim.c:62
pos
pos_T pos
Definition: funcs.c:8312
NUL
#define NUL
Definition: ascii.h:19
NL
#define NL
Definition: ascii.h:23