diff options
| -rw-r--r-- | runtime/doc/msgpack_rpc.txt | 89 |
1 files changed, 46 insertions, 43 deletions
diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 8567f4a00e..800ab08ce3 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -38,27 +38,28 @@ Nvim's msgpack-rpc interface can be seen as a more powerful version of Vim's ============================================================================== 2. API *msgpack-rpc-api* -Nvim C API is automatically exposed to the msgpack-rpc interface by the +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, and it will match msgpack-rpc method names +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 +from programmers, which can be automatically generated by reading bundled API metadata from a compiled nvim instance. There are two ways to obtain API metadata: -- By connecting to a running nvim instance and calling `vim_get_api_metadata` - via msgpack-rpc. This is the preferred way for clients written in - dynamically-typed languages, which can define functions at runtime. -- Through the `--api-info` command-line option, which makes nvim to dump a - msgpack blob containing the metadata to stdout and exit. This is preferred - when writing clients for statically-typed languages, which require a - separate compilation step. +1. By connecting to a running nvim instance and calling `vim_get_api_metadata` + via msgpack-rpc. This is the preferred way for clients written in + dynamically-typed languages, which can define functions at runtime. -Here's a simple way to get human-readable description of the API(requires +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. + +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 @@ -66,7 +67,6 @@ python and the pyyaml/msgpack-python pip packages): ============================================================================== 3. Connecting *msgpack-rpc-connecting* - 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 @@ -74,31 +74,31 @@ There are four ways to open msgpack-rpc streams to nvim: 2. Through stdin/stdout of a program spawned by the |rpcstart()| function. -3. Through the socket automatically created with every instance. To find out - the socket location(which is random by default) from a running nvim +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: > :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 +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: > 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 a fully-featured -Nvim client(which we'll see below). Here's a ruby script that will print the +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: > #!/usr/bin/env ruby # Requires msgpack-rpc: gem install msgpack-rpc - # - # To run this script, execute it from a running nvim instance(notice the + # + # 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 & # # Or from another shell by setting NVIM_LISTEN_ADDRESS: @@ -120,15 +120,15 @@ 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 it's source code is +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: -- Separate the transport layer from the rest of the library(See +- 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. -- Read api metadata in order to create client-side wrappers for all +- 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 @@ -138,10 +138,10 @@ the best documentation currently available. There are some guidelines however: - 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 since Nvim is blocked while waiting for the client + 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 + need to be handled immediately because they won't block Nvim (though you probably want to handle them immediately anyway). @@ -154,14 +154,14 @@ 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 +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: -- Basic types that map natively to msgpack(and probably have a default +- Basic types that map natively to msgpack (and probably have a default representation in msgpack-supported programming languages) - Special Nvim types that map to msgpack EXT with custom type codes. -Basic type mapping: +Basic type mapping: Nil -> msgpack nil Boolean -> msgpack boolean @@ -210,15 +210,15 @@ that makes this task easier: - Each function metadata object has type information about the return value and parameters. These can be used for generating strongly-typed APIs in static languages. -- Container types may be decorated with type/size constraints, eg: +- 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 instances of Nvim's types are prefixed with the type - name in lower case. Eg: `buffer_get_line` represents the `get_line` method + name in lower case, e.g. `buffer_get_line` represents the `get_line` method of a Buffer instance. -- Global methods are prefixed with `vim`. Eg: `vim_list_buffers` +- Global methods are prefixed with `vim`, e.g.`vim_list_buffers`. -So, for a object-oriented language, a client library would have the classes +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 by inspecting the method name prefix. There could also be a singleton Vim class with methods mapped to functions prefixed with `vim_` @@ -228,15 +228,18 @@ class with methods mapped to functions prefixed with `vim_` Four functions related to msgpack-rpc are available to vimscript: -- |rpcstart()|: Similarly to |jobstart()|, this will spawn a co-process with - it's 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). -- |rpcstop()|: Same as |jobstop()|, but operates on handles returned by - |rpcstart()|. -- |rpcrequest()|: Sends a msgpack-rpc request to the process. -- |rpcnotify()|: Sends a msgpack-rpc notification to the process. +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). + +2. |rpcstop()|: Same as |jobstop()|, but operates on handles returned by + |rpcstart()|. + +3. |rpcrequest()|: Sends a msgpack-rpc request to the process. + +4. |rpcnotify()|: Sends a msgpack-rpc notification to the process. The last two functions may also be used with channels created from connections to |$NVIM_LISTEN_ADDRESS|. |