diff options
| -rw-r--r-- | runtime/doc/api.txt | 99 | ||||
| -rw-r--r-- | runtime/doc/msgpack_rpc.txt | 20 |
2 files changed, 109 insertions, 10 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: diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index d732e7f818..bafb9dfc2c 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -7,7 +7,7 @@ The Msgpack-RPC Interface to Nvim *msgpack-rpc* 1. Introduction |msgpack-rpc-intro| -2. API |msgpack-rpc-api| +2. API mapping |msgpack-rpc-api| 3. Connecting |msgpack-rpc-connecting| 4. Clients |msgpack-rpc-clients| 5. Types |msgpack-rpc-types| @@ -36,13 +36,13 @@ Nvim's msgpack-rpc interface is like a more powerful version of Vim's `clientserver` feature. ============================================================================== -2. API *msgpack-rpc-api* +2. API mapping *msgpack-rpc-api* -The Nvim C API is automatically exposed to the msgpack-rpc interface by the -build system, which parses headers at src/nvim/api from the project root. A -dispatch function is generated, which matches msgpack-rpc method names with -non-static API functions, converting/validating arguments and return values -back to msgpack. +The Nvim C API, see |nvim-api|, is automatically exposed to the msgpack-rpc +interface by the build system, which parses headers at src/nvim/api from the +project root. A dispatch function is generated, which matches msgpack-rpc method +names with non-static API functions, converting/validating arguments and return +values back to msgpack. Client libraries will normally provide wrappers that hide msgpack-rpc details from programmers. The wrappers can be automatically generated by reading @@ -63,7 +63,7 @@ Here's a simple way to get human-readable description of the API (requires Python and the `pyyaml`/`msgpack-python` pip packages): > nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' > api.yaml - +< ============================================================================== 3. Connecting *msgpack-rpc-connecting* @@ -162,8 +162,8 @@ https://github.com/msgpack-rpc/msgpack-rpc-ruby/blob/master/lib/msgpack/rpc/tran ============================================================================== 5. Types *msgpack-rpc-types* -Nvim's C API uses custom types for all functions (some are just typedefs -around C99 standard types). The types can be split into two groups: +Nvim's C API uses custom types for all functions, se |nvim-api-types|. +For the purpose of mapping to msgpack, he types can be split into two groups: - Basic types that map natively to msgpack (and probably have a default representation in msgpack-supported programming languages) |