diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 99 |
1 files changed, 99 insertions, 0 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt new file mode 100644 index 0000000000..ca79465e0d --- /dev/null +++ b/runtime/doc/api.txt @@ -0,0 +1,99 @@ +*api.txt* For Nvim. {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| + +============================================================================== +1. Introduction *nvim-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. + +============================================================================== +2. API Types *nvim-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 *nvim-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 over +msgpack-api, see |msgpack-rpc-api|. + +============================================================================== +4. Buffer highlighting *nvim-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: |