1
*api.txt* For Nvim. {Nvim}
4
NVIM REFERENCE MANUAL by Thiago de Arruda
6
The C API of Nvim *nvim-api*
8
1. Introduction |nvim-api-intro|
9
2. API Types |nvim-api-types|
10
3. API metadata |nvim-api-metadata|
11
4. Buffer highlighting |nvim-api-highlights|
13
==============================================================================
14
1. Introduction *nvim-api-intro*
16
Nvim defines a C API as the primary way for external code to interact with
17
the NVim core. In the present version of Nvim the API is primarily used by
18
external processes to interact with Nvim using the msgpack-rpc protocol, see
19
|msgpack-rpc|. The API will also be used from vimscript to access new Nvim core
20
features, but this is not implemented yet. Later on, Nvim might be embeddable
21
in C applications as libnvim, and the application will then control the
22
embedded instance by calling the C API directly.
24
==============================================================================
25
2. API Types *nvim-api-types*
27
Nvim's C API uses custom types for all functions. Some are just typedefs
28
around C99 standard types, and some are Nvim defined data structures.
31
Integer (signed 64-bit integer) -> int64_t
32
Float (IEEE 754 double precision) -> double
33
String -> {char* data, size_t size} struct
35
Additionally, the following data structures are defined:
41
The following handle types are defined as integer typedefs, but are
42
discriminated as separate types in an Object:
44
Buffer -> enum value kObjectTypeBuffer
45
Window -> enum value kObjectTypeWindow
46
Tabpage -> enum value kObjectTypeTabpage
48
==============================================================================
49
3. API metadata *nvim-api-metadata*
51
Nvim exposes metadata about the API as a Dictionary with the following keys:
53
functions calling signature of the API functions
54
types The custom handle types defined by Nvim
55
error_types The possible kinds of errors an API function can exit with.
57
This metadata is mostly useful for external programs accessing the api over
58
msgpack-api, see |msgpack-rpc-api|.
60
==============================================================================
61
4. Buffer highlighting *nvim-api-highlights*
63
Nvim allows plugins to add position-based highlights to buffers. This is
64
similar to |matchaddpos()| but with some key differences. The added highlights
65
are associated with a buffer and adapts to line insertions and deletions,
66
similar to signs. It is also possible to manage a set of highlights as a group
67
and delete or replace all at once.
69
The intended use case are linter or semantic highlighter plugins that monitor
70
a buffer for changes, and in the background compute highlights to the buffer.
71
Another use case are plugins that show output in an append-only buffer, and
72
want to add highlights to the outputs. Highlight data cannot be preserved
73
on writing and loading a buffer to file, nor in undo/redo cycles.
75
Highlights are registered using the |buffer_add_highlight| function, see the
76
generated API documentation for details. If an external highlighter plugin is
77
adding a large number of highlights in a batch, performance can be improved by
78
calling |buffer_add_highlight| as an asynchronous notification, after first
79
(synchronously) reqesting a source id. Here is an example using wrapper
80
functions in the python client:
82
src = vim.new_highlight_source()
84
buf = vim.current.buffer
86
buf.add_highlight("String",i,0,-1,src_id=src)
90
buf.clear_highlight(src)
92
If the highlights don't need to be deleted or updated, just pass -1 as
93
src_id (this is the default in python). |buffer_clear_highlight| can be used
94
to clear highligts from a specific source, in a specific line range or the
95
entire buffer by passing in the line range 0, -1 (the later is the default
96
in python as used above).
98
==============================================================================
99
vim:tw=78:ts=8:noet:ft=help:norl:
added
removed
runtime/doc/api.txt
