mirror of
https://github.com/neovim/neovim.git
synced 2025-02-25 18:55:25 -06:00
Merge pull request #1377 from Pyrohh/msgpack_rpc-doc-fixes
Misc. msgpack-rpc doc fixes
This commit is contained in:
Justin M. Keyes
commit
eeaac9f639
@ -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|.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user