diff options
Diffstat (limited to 'runtime/doc')
| -rw-r--r-- | runtime/doc/api.txt | 33 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 14 | ||||
| -rw-r--r-- | runtime/doc/msgpack_rpc.txt | 38 |
3 files changed, 56 insertions, 29 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index bdeca367b1..c3d7fdb35b 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -14,13 +14,13 @@ C API for Nvim *API* *api* ============================================================================== 1. Introduction *api-intro* -Nvim exposes a public API 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 *api-types* @@ -73,10 +73,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: > @@ -91,10 +91,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: diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 03d8f84aa6..92f9a0f656 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -2009,6 +2009,7 @@ msgpackdump({list}) List dump a list of objects to msgpack msgpackparse({list}) List parse msgpack to a list of objects nextnonblank({lnum}) Number line nr of non-blank line >= {lnum} nr2char({expr}[, {utf8}]) String single char with ASCII/UTF8 value {expr} +nvim_...({args}...) any call nvim |api| functions or({expr}, {expr}) Number bitwise OR pathshorten({expr}) String shorten directory names in a path pow({x}, {y}) Float {x} to the power of {y} @@ -2208,11 +2209,9 @@ and({expr}, {expr}) *and()* Example: > :let flag = and(bits, 0x80) - api_info() *api_info()* Returns Dictionary of |api-metadata|. - append({lnum}, {expr}) *append()* When {expr} is a |List|: Append each item of the |List| as a text line below line {lnum} in the current buffer. @@ -5172,6 +5171,17 @@ nr2char({expr}[, {utf8}]) *nr2char()* characters. nr2char(0) is a real NUL and terminates the string, thus results in an empty string. +nvim_...({...}) *nvim_...()* *eval-api* + Call nvim |api| functions. The type checking of arguments will + be stricter than for most other builtins. For instance, + if Integer is expected, a |Number| must be passed in, a + |String| will not be autoconverted. + Buffer numbers, as returned by |bufnr()| could be used as + first argument to nvim_buf_... functions. All functions + expecting an object (buffer, window or tabpage) can + also take the numerical value 0 to indicate the current + (focused) object. + or({expr}, {expr}) *or()* Bitwise OR on the two arguments. The arguments are converted to a number. A List, Dict or Float argument causes an error. diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 30f68ca942..59e9e44f8f 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -47,7 +47,7 @@ instance. There are three ways to obtain API metadata: - 1. Connect to a running Nvim instance and call `vim_get_api_info` via + 1. Connect to a running Nvim instance and call `nvim_get_api_info` via msgpack-rpc. This is best for clients written in dynamic languages which can define functions at runtime. @@ -105,7 +105,7 @@ Nvim instance: require 'msgpack/rpc/transport/unix' nvim = MessagePack::RPC::Client.new(MessagePack::RPC::UNIXTransport.new, ENV['NVIM_LISTEN_ADDRESS']) - result = nvim.call(:vim_command, 'echo "hello world!"') + result = nvim.call(:nvim_command, 'echo "hello world!"') < A better way is to use the Python REPL with the `neovim` package, where API functions can be called interactively: @@ -117,9 +117,9 @@ functions can be called interactively: You can also embed an Nvim instance via |jobstart()|, and communicate using |rpcrequest()| and |rpcnotify()|: > - let vim = jobstart(['nvim', '--embed'], {'rpc': v:true}) - echo rpcrequest(vim, 'vim_eval', '"Hello " . "world!"') - call jobstop(vim) + let nvim = jobstart(['nvim', '--embed'], {'rpc': v:true}) + echo rpcrequest(nvim, 'nvim_eval', '"Hello " . "world!"') + call jobstop(nvim) < ============================================================================== 4. Implementing API clients *rpc-api-client* *api-client* @@ -177,15 +177,20 @@ contains information that makes this task easier (see also |rpc-types|): - Container types may be decorated with type/size constraints, e.g. ArrayOf(Buffer) or ArrayOf(Integer, 2). This can be useful to generate even more strongly-typed APIs. - - Methods that operate on instances of Nvim special types (msgpack EXT) are - prefixed with the type name in lower case, e.g. `buffer_get_line` - represents the `get_line` method of a Buffer instance. - - Global methods are prefixed with `vim`, e.g. `vim_get_buffers`. + - Functions that are considered to be methods that operate on instances of + Nvim special types (msgpack EXT) will have the `"method"` attribute set to + `true`. The reciever type is the type of the first argument. The method + names are prefixed with `nvim_` plus a shortened type name, e.g. + `nvim_buf_get_lines` represents the `get_lines` method of a Buffer instance. + - Global functions have `"method"` set to `false` and are prefixed with just + `nvim_`, e.g. `nvim_get_buffers`. So for an object-oriented language, an API client contains the classes representing Nvim special types, and the methods of each class could be -defined by inspecting the method name prefix. There could also be a singleton -Vim class with methods mapped to functions prefixed with `vim_`. +defined by stripping the prefix for the type as defined in the `types` metadata +(this will always be the first two "_"-separated parts of the function name). +There could also be a singleton Vim class with methods where the `nvim_` +prefix is stripped off. ============================================================================== 5. Types *rpc-types* @@ -219,18 +224,21 @@ an integer, but not a Window or Tabpage. The most reliable way of determining the type codes for the special Nvim types is to inspect the `types` key of metadata dictionary returned by the -`vim_get_api_info` method at runtime. Here's a sample JSON representation of +`nvim_get_api_info` method at runtime. Here's a sample JSON representation of the `types` object: > "types": { "Buffer": { - "id": 0 + "id": 0, + "prefix": "nvim_buf_" }, "Window": { - "id": 1 + "id": 1, + "prefix": "nvim_win_" }, "Tabpage": { - "id": 2 + "id": 2, + "prefix": "nvim_tabpage_" } } < |