diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 74 |
1 files changed, 45 insertions, 29 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index ca79465e0d..171b0124f6 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1,31 +1,32 @@ -*api.txt* For Nvim. {Nvim} +*api.txt* {Nvim} NVIM REFERENCE MANUAL by Thiago de Arruda -The C API of Nvim *nvim-api* -1. Introduction |nvim-api-intro| -2. API Types |nvim-api-types| -3. API metadata |nvim-api-metadata| -4. Buffer highlighting |nvim-api-highlights| +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 *nvim-api-intro* +1. Introduction *api-intro* -Nvim defines a C API as the primary way 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. +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 *nvim-api-types* +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. +around C99 standard types, and some are Nvim-defined data structures. Boolean -> bool Integer (signed 64-bit integer) -> int64_t @@ -46,19 +47,25 @@ Window -> enum value kObjectTypeWindow Tabpage -> enum value kObjectTypeTabpage ============================================================================== -3. API metadata *nvim-api-metadata* +3. API metadata *api-metadata* -Nvim exposes metadata about the API as a Dictionary with the following keys: +Nvim exposes API metadata as a Dictionary. Some items are described below: -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. +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 -This metadata is mostly useful for external programs accessing the api over -msgpack-api, see |msgpack-rpc-api|. +External programs ("clients") can use the metadata to discover the |rpc-api|. ============================================================================== -4. Buffer highlighting *nvim-api-highlights* +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 @@ -72,10 +79,10 @@ 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 +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 |buffer_add_highlight| as an asynchronous notification, after first +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: > @@ -90,10 +97,19 @@ functions in the python client: 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 +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: |