mirror of
https://github.com/neovim/neovim.git
synced 2025-10-26 12:27:24 +00:00
cc6edfe357
It is almost never necessary to qualify documentation as "Nvim specific". The main exception to this is vim_diff.txt.
101 lines
3.9 KiB
Plaintext
101 lines
3.9 KiB
Plaintext
*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. In
|
|
the present version of Nvim the API is primarily used by external processes to
|
|
interact with Nvim using the msgpack-rpc protocol, see |msgpack-rpc|. The API
|
|
will also be used from vimscript to access new Nvim core features, but this is
|
|
not implemented yet. 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 |buffer_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 |buffer_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). |buffer_clear_highlight| can be used
|
|
to clear highligts from a specific source, in a specific line range or the
|
|
entire buffer by passing in the line range 0, -1 (the later is the default
|
|
in python as used above).
|
|
|
|
==============================================================================
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|