neovim/runtime/doc/api.txt

*api.txt*		 						{Nvim}


		 NVIM REFERENCE MANUAL    by Thiago de Arruda


C API for Nvim							   *API* *api*

1. Introduction			|api-intro|
2. API Types			|api-types|
3. API metadata			|api-metadata|
4. Buffer highlighting		|api-highlights|

==============================================================================
1. Introduction							   *api-intro*

Nvim exposes a public API for external code to interact with the Nvim core.
The API is used by external processes to interact with Nvim using the
msgpack-rpc protocol, see |msgpack-rpc|. The API is used from vimscript to
access some new Nvim core features. See |eval-api| for how api functions are
called from vimscript. Later on, Nvim might be embeddable in C applications as
libnvim, and the application will then control the embedded instance by calling
the C API directly.

==============================================================================
2. API Types							   *api-types*

Nvim's C API uses custom types for all functions. Some are just typedefs
around C99 standard types, and some are Nvim-defined data structures.

Boolean				  -> bool
Integer (signed 64-bit integer)	  -> int64_t
Float (IEEE 754 double precision) -> double
String				  -> {char* data, size_t size} struct

Additionally, the following data structures are defined:

Array
Dictionary
Object

The following handle types are defined as integer typedefs, but are
discriminated as separate types in an Object:

Buffer				  -> enum value kObjectTypeBuffer
Window				  -> enum value kObjectTypeWindow
Tabpage				  -> enum value kObjectTypeTabpage

==============================================================================
3. API metadata							 *api-metadata*

Nvim exposes API metadata as a Dictionary. Some items are described below:

version			Nvim version, API level/compatibility
version.api_level	Current API level
version.api_compatible	API is backwards-compatible with this level
version.api_prerelease	Declares the current API level as unstable >
			(version.api_prerelease && fn.since == version.api_level)
functions		API function signatures
{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

External programs ("clients") can use the metadata to discover the |rpc-api|.

==============================================================================
4. Buffer highlighting					       *api-highlights*

Nvim allows plugins to add position-based highlights to buffers. This is
similar to |matchaddpos()| but with some key differences. The added highlights
are associated with a buffer and adapts to line insertions and deletions,
similar to signs. It is also possible to manage a set of highlights as a group
and delete or replace all at once.

The intended use case are linter or semantic highlighter plugins that monitor
a buffer for changes, and in the background compute highlights to the buffer.
Another use case are plugins that show output in an append-only buffer, and
want to add highlights to the outputs. Highlight data cannot be preserved
on writing and loading a buffer to file, nor in undo/redo cycles.

Highlights are registered using the |nvim_buf_add_highlight| function, see the
generated API documentation for details. If an external highlighter plugin is
adding a large number of highlights in a batch, performance can be improved by
calling |nvim_buf_add_highlight| as an asynchronous notification, after first
(synchronously) reqesting a source id. Here is an example using wrapper
functions in the python client:
>
    src = vim.new_highlight_source()

    buf = vim.current.buffer
    for i in range(5):
        buf.add_highlight("String",i,0,-1,src_id=src)

    # some time later

    buf.clear_highlight(src)
<
If the highlights don't need to be deleted or updated, just pass -1 as
src_id (this is the default in python). |nvim_buf_clear_highlight| can be used
to clear highlights from a specific source, in a specific line range or the
entire buffer by passing in the line range 0, -1 (the latter is the default
in python as used above).

An example of calling the api from vimscript: >

    call nvim_buf_set_lines(0, 0, 0, v:true, ["test text"])
    let src = nvim_buf_add_highlight(0, 0, "String", 1, 0, 4)
    call nvim_buf_add_highlight(0, src, "Identifier", 0, 5, -1)

    " later
    call nvim_buf_clear_highlight(0, src, 0, -1)
>
==============================================================================
 vim:tw=78:ts=8:noet:ft=help:norl: