*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 metadata about the API as a Dictionary with the following keys:

functions  	calling signature of the API functions
types		The custom handle types defined by Nvim
error_types	The possible kinds of errors an API function can exit with.

This metadata is mostly useful for external programs accessing the API via
RPC, see |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:
