diff options
Diffstat (limited to 'runtime/doc/msgpack_rpc.txt')
| -rw-r--r-- | runtime/doc/msgpack_rpc.txt | 66 |
1 files changed, 32 insertions, 34 deletions
diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 0fb419e5d5..af4ef3e132 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -4,10 +4,10 @@ NVIM REFERENCE MANUAL by Thiago de Arruda -The Msgpack-RPC Interface to Nvim *msgpack-rpc* +The Msgpack-RPC Interface to Nvim *msgpack-rpc* 1. Introduction |msgpack-rpc-intro| -2. API |msgpack-rpc-api| +2. API |msgpack-rpc-api| 3. Connecting |msgpack-rpc-connecting| 4. Clients |msgpack-rpc-clients| 5. Types |msgpack-rpc-types| @@ -40,9 +40,9 @@ Nvim's msgpack-rpc interface can be seen as a more powerful version of Vim's 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. +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, which can be automatically generated by reading bundled API @@ -60,7 +60,7 @@ There are two ways to obtain API metadata: separate compilation step. Here's a simple way to get human-readable description of the API (requires -python and the pyyaml/msgpack-python pip packages): +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 @@ -69,21 +69,19 @@ python and the pyyaml/msgpack-python pip packages): There are four ways to open msgpack-rpc streams to nvim: -1. Through nvim's stdin/stdout when started with the `--embed` option. This is +1. Through Nvim's stdin/stdout when started with the `--embed` option. This is how other programs can embed nvim. -2. Through stdin/stdout of a program spawned by the |rpcstart()| function. +2. Through the stdin/stdout of a program spawned by the |rpcstart()| function. 3. Through the socket automatically created with each instance. To find out the socket location (which is random by default) from a running nvim - instance, one can inspect the *$NVIM_LISTEN_ADDRESS* environment variable - like this: + instance, one can inspect the |$NVIM_LISTEN_ADDRESS| environment variable: > :echo $NVIM_LISTEN_ADDRESS < -4. Through a TCP/IP socket. To make nvim listen on a TCP/IP socket, you need - to set the $NVIM_LISTEN_ADDRESS environment variable before starting, like - this: +4. Through a TCP/IP socket. To make nvim listen on a TCP/IP socket, set the + |$NVIM_LISTEN_ADDRESS| environment variable in a shell before starting: > NVIM_LISTEN_ADDRESS=127.0.0.1:6666 nvim < @@ -120,34 +118,34 @@ functions can be called interactively: ============================================================================== 4. Implementing new clients *msgpack-rpc-clients* -Nvim is still alpha and there's no in-depth documentation explaining how to -properly implement a client library. The python client (neovim pip package) -will be always up-to-date with the latest API changes, so its source code is -the best documentation currently available. There are some guidelines however: +Nvim is still in alpha, so there's no in-depth documentation explaining how to +properly implement a client library yet. The python client (the pip package +"neovim") will always be up-to-date with the latest API changes, so its source +code is the best documentation currently available. There are some guidelines +however: -- Separate the transport layer from the rest of the library (see - |msgpack-rpc-connecting| for details of how a client can connect to nvim). -- Use a msgpack library that implements the spec version 5, Nvim uses the - BIN/EXT types. +- Separate the transport layer from the rest of the library. See + |msgpack-rpc-connecting| for details on how clients can connect to nvim. +- Use a MessagePack library that implements at least version 5 of the + MessagePack spec, which supports the `bin` and `ext` types used by nvim. - Read API metadata in order to create client-side wrappers for all msgpack-rpc methods. - Use a single-threaded event loop library/pattern. -- Use a fiber/coroutine library for the language you are implementing a client - for. These greatly simplify concurrency and allow the library to expose a - blocking API on top of a non-blocking event loop without the complexity - that comes with preemptive multitasking. +- Use a fiber/coroutine library for the language being used for implementing a + client. These greatly simplify concurrency and allow the library to expose a + blocking API on top of a non-blocking event loop without the complexity that + comes with preemptive multitasking. - Don't assume anything about the order that responses to msgpack-rpc requests will arrive. - Clients should expect to receive msgpack-rpc requests, which need to be handled immediately because Nvim is blocked while waiting for the client response. - Clients should expect to receive msgpack-rpc notifications, but these don't - need to be handled immediately because they won't block Nvim (though you - probably want to handle them immediately anyway). - + need to be handled immediately because they won't block Nvim (although they + should probably be handled immediately anyway). Most of the complexity could be handled by a msgpack-rpc library that supports -server->client requests and notifications, but it's not clear if this is part +server to client requests and notifications, but it's not clear if this is part of the msgpack-rpc spec. At least the ruby msgpack-rpc library does not seem to support it: https://github.com/msgpack-rpc/msgpack-rpc-ruby/blob/master/lib/msgpack/rpc/transport/tcp.rb#L150-L158 @@ -217,7 +215,7 @@ that makes this task easier: - Methods that operate instances of Nvim's types 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_list_buffers`. +- Global methods are prefixed with `vim`, e.g. `vim_list_buffers`. So, for an object-oriented language, a client library would have the classes that represent Nvim's types, and the methods of each class could be defined @@ -227,13 +225,13 @@ class with methods mapped to functions prefixed with `vim_` ============================================================================== 7. Vimscript functions *msgpack-rpc-vim-functions* -Four functions related to msgpack-rpc are available to vimscript: +Four functions related to msgpack-rpc are available in vimscript: 1. |rpcstart()|: Similarly to |jobstart()|, this will spawn a co-process with its standard handles connected to Nvim. The difference is that it's not - possible to process raw data to/from the process stdin/stdout/stderr (since - the job's stdin/stdout combo are used as a msgpack channel that is - processed directly by Nvim C code). + possible to process raw data to/from the process's stdin/stdout/stderr. + This is because the job's stdin and stdout are used as a single msgpack + channel that is processed directly by Nvim. 2. |rpcstop()|: Same as |jobstop()|, but operates on handles returned by |rpcstart()|. |