mirror of
https://github.com/neovim/neovim.git
synced 2024-12-20 19:25:11 -07:00
f25797f869
The API level is disconnected from the NVIM version. The API metadata
holds the current API level, and the lowest backwards-compatible level
supported by this instance.
Release 0.1.6 will be the first release reporting the Nvim version and
API level.
metadata['version'] = {
major: 0,
minor: 1,
patch: 6,
prerelease: true,
api_level: 1,
api_compatible: 0,
}
The API level may remain unchanged across Neovim releases if the API has
not changed.
When changing the API the CMake variable NVIM_API_PRERELEASE is set to
true, and NVIM_API_CURRENT/NVIM_API_COMPATIBILITY are incremented
accordingly.
The functional tests check the API table against fixtures of past
versions of Neovim. It compares all the functions in the old table with
the new one, it does ignore some metadata attributes that do not alter
the function signature or were removed since 0.1.5. Currently the only
fixture is 0.mpack, generated from Neovim 0.1.5 with nvim --api-info.
111 lines
4.2 KiB
Plaintext
111 lines
4.2 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 metadata about the API as a Dictionary with the following keys:
|
|
|
|
api_level API version compatibility information
|
|
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:
|