Nvim API: Examples, Definitions, and Metadata

MessagePack::RPC::Client.new(MessagePack::RPC::UNIXTransport.new, ENV['NVIM_LISTEN_ADDRESS']) result = nvim.call(:nvim_command, 'echo "hello world!"') < A better way is to use the Python REPL with the "pynvim" package, where API functions can be called interactively: > >>> from pynvim import attach >>> nvim = attach('socket', path='[address]') >>> nvim.command('echo "hello world!"') < You can also embed Nvim via |jobstart()|, and communicate using |rpcrequest()| and |rpcnotify()|: >vim let nvim = jobstart(['nvim', '--embed'], {'rpc': v:true}) echo rpcrequest(nvim, 'nvim_eval', '"Hello " . "world!"') call jobstop(nvim) < ============================================================================== API Definitions *api-definitions* *api-types* The Nvim C API defines custom types for all function parameters. Some are just typedefs around C99 standard types, others are Nvim-defined data structures. Basic types ~ > API Type C type ------------------------------------------------------------------------ Nil Boolean bool Integer (signed 64-bit integer) int64_t Float (IEEE 754 double precision) double String {char* data, size_t size} struct Array kvec Dict (msgpack: map) kvec Object any of the above < Note: - Empty Array is accepted as a valid Dictionary parameter. - Functions cannot cross RPC boundaries. But API functions (e.g. |nvim_create_autocmd()|) may support Lua function parameters for non-RPC invocations. Special types (msgpack EXT) ~ These are integer typedefs discriminated as separate Object subtypes. They can be treated as opaque integers, but are mutually incompatible: Buffer may be passed as an integer but not as Window or Tabpage. The EXT object data is the (integer) object handle. The EXT type codes given in the |api-metadata| `types` key are stable: they will not change and are thus forward-compatible. > EXT Type C type Data ------------------------------------------------------------------------ Buffer enum value kObjectTypeBuffer |bufnr()| Window enum value kObjectTypeWindow |window-ID| Tabpage enum value kObjectTypeTabpage internal handle < *api-indexing* Most of the API uses 0-based indices, and ranges are end-exclusive. For the end of a range, -1 denotes the last line/column. Exception: the following API functions use "mark-like" indexing (1-based lines, 0-based columns): - |nvim_get_mark()| - |nvim_buf_get_mark()| - |nvim_buf_set_mark()| - |nvim_win_get_cursor()| - |nvim_win_set_cursor()| Exception: the following API functions use |extmarks| indexing (0-based indices, end-inclusive): - |nvim_buf_del_extmark()| - |nvim_buf_get_extmark_by_id()| - |nvim_buf_get_extmarks()| - |nvim_buf_set_extmark()| *api-fast* Most API functions are "deferred": they are queued on the main loop and processed sequentially with normal input. So if the editor is waiting for user input in a "modal" fashion (e.g. the |hit-enter-prompt|), the request will block. Non-deferred (fast) functions such as |nvim_get_mode()| and |nvim_input()| are served immediately (i.e. without waiting in the input queue). Lua code can use |vim.in_fast_event()| to detect a fast context. ============================================================================== API metadata *api-metadata* The Nvim C API is automatically exposed to RPC by the build system, which parses headers in src/nvim/api/* and generates dispatch-functions mapping RPC API

This section provides code examples in Python and VimL for interacting with the Nvim API. It then delves into API definitions, detailing the C API types used for function parameters, including basic types like Integer, String, and Array, and special types like Buffer, Window, and Tabpage. It explains API indexing conventions, noting exceptions for mark-like and extmark indexing. Finally, it touches on the concept of deferred and fast API functions, and introduces the API metadata, which is automatically generated from C headers.