1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
*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:
|
