Nvim API: Indexing, Metadata, and Contract

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 method names to public C API functions, converting/validating arguments and return values. Nvim exposes its API metadata as a Dictionary with these items: - version Nvim version, API level/compatibility - version.api_level API version integer *api-level* - version.api_compatible API is backwards-compatible with this level - version.api_prerelease Declares the API as unstable/unreleased `(version.api_prerelease && fn.since == version.api_level)` - functions API function signatures, containing |api-types| info describing the return value and parameters. - ui_events |UI| event signatures - ui_options Supported |ui-option|s - {fn}.since API level where function {fn} was introduced - {fn}.deprecated_since API level where function {fn} was deprecated - types Custom handle types defined by Nvim - error_types Possible error types returned by API functions About the `functions` map: - Container types may be decorated with type/size constraints, e.g. ArrayOf(Buffer) or ArrayOf(Integer, 2). - Functions considered to be methods that operate on instances of Nvim special types (msgpack EXT) have the "method=true" flag. The receiver type is that of the first argument. Method names are prefixed with `nvim_` plus a type name, e.g. `nvim_buf_get_lines` is the `get_lines` method of a Buffer instance. |dev-api| - Global functions have the "method=false" flag and are prefixed with just `nvim_`, e.g. `nvim_list_bufs`. *api-mapping* External programs (clients) can use the metadata to discover the API, using any of these approaches: 1. Connect to a running Nvim instance and call |nvim_get_api_info()| via msgpack-RPC. This is best for clients written in dynamic languages which can define functions at runtime. 2. Start Nvim with |--api-info|. Useful for statically-compiled clients. Example (requires Python "pyyaml" and "msgpack-python" modules): > nvim --api-info | python -c 'import msgpack, sys, yaml; yaml.dump(msgpack.unpackb(sys.stdin.buffer.read()), sys.stdout)' < 3. Use the |api_info()| Vimscript function. >vim :lua vim.print(vim.fn.api_info()) < Example using |filter()| to exclude non-deprecated API functions: >vim :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name') ============================================================================== API contract *api-contract* The Nvim API is composed of functions and events. - Clients call functions like those described at |api-global|. - Clients can subscribe to |ui-events|, |api-buffer-updates|, etc. - API function names are prefixed with "nvim_". - API event names are prefixed with "nvim_" and suffixed with "_event". As Nvim evolves

This section elaborates on API indexing, differentiating between general 0-based indices and exceptions for extmarks. It details API function execution as 'deferred' or 'fast' and introduces API metadata, outlining its structure and contents. The metadata is accessible through various methods, including the `--api-info` flag and functions like `nvim_get_api_info()` and `api_info()`. Finally, it describes the API contract, composed of functions and events with the 'nvim_' prefix.