mirror of
https://github.com/neovim/neovim.git
synced 2024-12-20 03:05:11 -07:00
116 lines
4.5 KiB
Plaintext
116 lines
4.5 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.
|
|
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:
|