diff options
Diffstat (limited to 'runtime/doc/msgpack_rpc.txt')
| -rw-r--r-- | runtime/doc/msgpack_rpc.txt | 96 |
1 files changed, 48 insertions, 48 deletions
diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 8304d79c17..d03d97ec85 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -17,22 +17,22 @@ The Msgpack-RPC Interface to Nvim *msgpack-rpc* ============================================================================== 1. Introduction *msgpack-rpc-intro* -The primary means of controlling a running Nvim instance is through +The primary way to control a running Nvim instance is through MessagePack-RPC, a messaging protocol that uses the MessagePack serialization format: https://github.com/msgpack/msgpack/blob/7498cf3/spec.md. -From now on, we'll be referring to the protocol as msgpack-rpc. +From now on, we refer to the protocol as msgpack-rpc. At this point, only plugins use msgpack-rpc, but eventually even user -interaction will be achieved through the protocol, since user interfaces will -be separate programs that control a headless Nvim instance. +interaction will happen through it, since user interfaces will be separate +programs that control a headless Nvim instance. -This is what can be achieved by connecting to the msgpack-rpc interface: +By connecting to the msgpack-rpc interface, programs can: - Call any Nvim API function - Listen for Nvim events - Receive remote calls from Nvim -Nvim's msgpack-rpc interface can be seen as a more powerful version of Vim's +Nvim's msgpack-rpc interface is like a more powerful version of Vim's `clientserver` feature. ============================================================================== @@ -45,19 +45,19 @@ 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 -metadata from a compiled nvim instance. +from programmers. The wrappers can be automatically generated by reading +bundled API metadata from a compiled Nvim instance. There are two ways to obtain API metadata: -1. By connecting to a running nvim instance and calling `vim_get_api_info` - via msgpack-rpc. This is the preferred way for clients written in - dynamically-typed languages, which can define functions at runtime. +1. By connecting to a running Nvim instance and calling `vim_get_api_info` + via msgpack-rpc. This is best for clients written in dynamically-typed + languages, which can define functions at runtime. -2. Through the `--api-info` command-line option, which makes nvim dump a - msgpack blob containing metadata to stdout and exit. This is preferred - when writing clients for statically-typed languages, which require a - separate compilation step. +2. By starting Nvim with the `--api-info` command-line option, which makes Nvim + dump a blob of msgpack metadata to standard output and exit. This is best + for clients written in statically-typed languages, which require a 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): @@ -67,37 +67,37 @@ Python and the `pyyaml`/`msgpack-python` pip packages): ============================================================================== 3. Connecting *msgpack-rpc-connecting* -There are four ways to open msgpack-rpc streams to nvim: +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 - how other programs can embed nvim. +1. Through Nvim's stdin/stdout when it's started with the `--embed` option. + This is how other programs can embed Nvim. 2. Through the stdin/stdout of a program spawned by the |rpcstart()| function. *$NVIM_LISTEN_ADDRESS* -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: +3. Through the socket automatically created with each instance. To get the + socket location for a running Nvim instance (which is random by default), + see the |$NVIM_LISTEN_ADDRESS| environment variable: > - :echo $NVIM_LISTEN_ADDRESS + :echo $NVIM_LISTEN_ADDRESS < See also |v:servername|. -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: +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: > - NVIM_LISTEN_ADDRESS=127.0.0.1:6666 nvim + NVIM_LISTEN_ADDRESS=127.0.0.1:6666 nvim < -Connecting to the socket is the easiest way a programmer can test the API, -which can be done through any msgpack-rpc client library or fully-featured -Nvim client (which we'll see below). Here's a ruby script that will print the -string 'hello world!' on the current nvim instance: +Connecting to the socket is the easiest way a programmer can test the API, which +can be done through any msgpack-rpc client library or fully-featured Nvim client +(which we'll see in the next section). Here's a Ruby script that prints 'hello +world!' in the current Nvim instance: > #!/usr/bin/env ruby # Requires msgpack-rpc: gem install msgpack-rpc # - # To run this script, execute it from a running nvim instance (notice the - # trailing '&' which is required since nvim won't process events while + # To run this script, execute it from a running Nvim instance (notice the + # trailing '&' which is required since Nvim won't process events while # running a blocking command): # # :!./hello.rb & @@ -118,7 +118,7 @@ functions can be called interactively: >>> nvim = attach('socket', path='[address]') >>> nvim.command('echo "hello world!"') < -One can also spawn and connect to an embedded nvim instance via |rpcstart()| +One can also spawn and connect to an embedded Nvim instance via |rpcstart()| > let vim = rpcstart('nvim', ['--embed']) echo rpcrequest(vim, 'vim_eval', '"Hello " . "world!"') @@ -134,9 +134,9 @@ 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 on how clients can connect to nvim. + |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. + 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. @@ -146,17 +146,17 @@ however: 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 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 (although they should probably be handled immediately anyway). Most of the complexity could be handled by a msgpack-rpc library that supports 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 +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 ============================================================================== @@ -189,10 +189,10 @@ An API method expecting one of these types may be passed an integer instead, although they are not interchangeable. For example, a Buffer may be passed as an integer, but not a Window or Tabpage. -The most reliable way of determining the type codes for the special nvim types -is at runtime by inspecting the `types` key of metadata dictionary returned by -`vim_get_api_info` method. Here's an example json representation of the -`types` object: +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 an example JSON representation of +the `types` object: > "types": { "Buffer": { @@ -207,8 +207,8 @@ is at runtime by inspecting the `types` key of metadata dictionary returned by } < Even for statically compiled clients, it's a good practice to avoid hardcoding -the type codes, because a client may build for a Nvim version and connect to -another that may have different type codes. +the type codes, because a client may be built against one Nvim version but connect +to another with different type codes. ============================================================================== 6. Wrapping methods *msgpack-rpc-wrap-methods* @@ -238,13 +238,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 in vimscript: +Four msgpack-rpc functions 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'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. + possible to process raw data to or from the process's stdin, stdout, or + 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()|. |