mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-11-07 19:24:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: msgpack_rpc: De-emphasize the transport protocol.

Browse Source 
Tighten our jargon, avoid mentioning "msgpack" everywhere we mention the
RPC API. Prefer "RPC API" when speaking about the remote API.

Though it's conceivable that we may one day support some protocol other
than msgpack, that isn't relevant to most of our discussion of the API,
including this document.

The file name msgpack_rpc.txt is preserved to avoid totally breaking
URLs.
This commit is contained in:
Justin M. Keyes
2016-06-13 02:11:12 -04:00
parent bd20892bdf
commit 23a3e58f02
7 changed files with 198 additions and 210 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
runtime/doc/api.txt
View File

@@ -14,7 +14,7 @@ The C API of Nvim *nvim-api*
1. Introduction *nvim-api-intro* 1. Introduction *nvim-api-intro*
Nvim defines a C API as the primary way for external code to interact with Nvim defines a C API as the primary way for external code to interact with
the NVim core. In the present version of Nvim the API is primarily used by 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 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 |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 features, but this is not implemented yet. Later on, Nvim might be embeddable
@@ -54,8 +54,8 @@ functions calling signature of the API functions
types The custom handle types defined by Nvim types The custom handle types defined by Nvim
error_types The possible kinds of errors an API function can exit with. error_types The possible kinds of errors an API function can exit with.
This metadata is mostly useful for external programs accessing the api over This metadata is mostly useful for external programs accessing the API via
msgpack-api, see |msgpack-rpc-api|. RPC, see |rpc-api|.
============================================================================== ==============================================================================
4. Buffer highlighting *nvim-api-highlights* 4. Buffer highlighting *nvim-api-highlights*

37
runtime/doc/develop.txt
View File

@@ -1,23 +1,19 @@
*develop.txt* For Vim version 7.4. Last change: 2016 Jan 31 *develop.txt*
VIM REFERENCE MANUAL by Bram Moolenaar NVIM REFERENCE MANUAL
Development of Vim. *development* Development of Nvim. *development*
This text is important for those who want to be involved in further developing
Vim.
1. Design goals |design-goals| 1. Design goals |design-goals|
2. Design decisions |design-decisions| 2. Design decisions |design-decisions|
See the file "src/nvim/README.md" for a high-level overview of the source See src/nvim/README.md for a high-level overview of the source code:
code. https://github.com/neovim/neovim/blob/master/src/nvim/README.md
Vim is open source software. Everybody is encouraged to contribute to help Nvim is open source software. Everybody is encouraged to contribute.
improving Vim. For sending patches a context diff "diff -c" is preferred. https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
Also see http://vim.wikia.com/wiki/How_to_make_and_submit_a_patch.
============================================================================== ==============================================================================
1. Design goals *design-goals* 1. Design goals *design-goals*
@@ -28,7 +24,7 @@ Note that quite a few items are contradicting. This is intentional. A
balance must be found between them. balance must be found between them.
VIM IS... IMPROVED *design-improved* NVIM IS... IMPROVED *design-improved*
The IMproved bits of Vim should make it a better Vi, without becoming a The IMproved bits of Vim should make it a better Vi, without becoming a
completely different editor. Extensions are done with a "Vi spirit". completely different editor. Extensions are done with a "Vi spirit".
@@ -49,7 +45,7 @@ completely different editor. Extensions are done with a "Vi spirit".
implement and (3) someone actually implementing it. implement and (3) someone actually implementing it.
VIM IS... MULTI PLATFORM *design-multi-platform* NVIM IS... MULTI PLATFORM *design-multi-platform*
Vim tries to help as many users on as many platforms as possible. Vim tries to help as many users on as many platforms as possible.
- Support many kinds of terminals. The minimal demands are cursor positioning - Support many kinds of terminals. The minimal demands are cursor positioning
@@ -68,7 +64,7 @@ Vim tries to help as many users on as many platforms as possible.
contradicts the previous item, these two must be balanced.] contradicts the previous item, these two must be balanced.]
VIM IS... WELL DOCUMENTED *design-documented* NVIM IS... WELL DOCUMENTED *design-documented*
- A feature that isn't documented is a useless feature. A patch for a new - A feature that isn't documented is a useless feature. A patch for a new
feature must include the documentation. feature must include the documentation.
@@ -78,7 +74,7 @@ VIM IS... WELL DOCUMENTED *design-documented*
item is easier to find. item is easier to find.
VIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size* NVIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size*
Using Vim must not be a big attack on system resources. Keep it small and Using Vim must not be a big attack on system resources. Keep it small and
fast. fast.
@@ -95,7 +91,7 @@ fast.
application, but have it work well together with other programs. application, but have it work well together with other programs.
VIM IS... MAINTAINABLE *design-maintain* NVIM IS... MAINTAINABLE *design-maintain*
- The source code should not become a mess. It should be reliable code. - The source code should not become a mess. It should be reliable code.
- Use comments in a useful way! Quoting the function name and argument names - Use comments in a useful way! Quoting the function name and argument names
@@ -106,7 +102,7 @@ VIM IS... MAINTAINABLE *design-maintain*
knowledge spread to other parts of the code. knowledge spread to other parts of the code.
VIM IS... FLEXIBLE *design-flexible* NVIM IS... FLEXIBLE *design-flexible*
Vim should make it easy for users to work in their preferred styles rather Vim should make it easy for users to work in their preferred styles rather
than coercing its users into particular patterns of work. This can be for than coercing its users into particular patterns of work. This can be for
@@ -117,10 +113,9 @@ be used to adjust Vim to the desire of the user and its environment.
NVIM IS... NOT *design-not* NVIM IS... NOT *design-not*
Nvim is not an Operating System; instead it should be composed with other Nvim is not an operating system—instead it should be composed with other tools
tools, or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not
not attempt to include everything but the kitchen sink, but some people use it include the kitchen sink... but you can use it for plumbing."
for plumbing."
============================================================================== ==============================================================================

32
runtime/doc/eval.txt
View File

@@ -1653,9 +1653,9 @@ v:scrollstart String describing the script or function that caused the
hit-enter prompt. hit-enter prompt.
*v:servername* *servername-variable* *v:servername* *servername-variable*
*$NVIM_LISTEN_ADDRESS*
v:servername Default {Nvim} server address. Equivalent to v:servername Default {Nvim} server address. Equivalent to
|$NVIM_LISTEN_ADDRESS| on startup, but may differ if the |$NVIM_LISTEN_ADDRESS| on startup. |serverstop()|
latter is modified or unset. |serverstop()|
Read-only. Read-only.
@@ -2030,11 +2030,11 @@ resolve({filename}) String get filename a shortcut points to
reverse({list}) List reverse {list} in-place reverse({list}) List reverse {list} in-place
round({expr}) Float round off {expr} round({expr}) Float round off {expr}
rpcnotify({channel}, {event}[, {args}...]) rpcnotify({channel}, {event}[, {args}...])
Sends a |msgpack-rpc| notification to {channel} Sends a |rpc| notification to {channel}
rpcrequest({channel}, {method}[, {args}...]) rpcrequest({channel}, {method}[, {args}...])
Sends a |msgpack-rpc| request to {channel} Sends a |rpc| request to {channel}
rpcstart({prog}[, {argv}]) Spawns {prog} and opens a |msgpack-rpc| channel rpcstart({prog}[, {argv}]) Spawns {prog} and opens a |rpc| channel
rpcstop({channel}) Closes a |msgpack-rpc| {channel} rpcstop({channel}) Closes a |rpc| {channel}
screenattr({row}, {col}) Number attribute at screen position screenattr({row}, {col}) Number attribute at screen position
screenchar({row}, {col}) Number character at screen position screenchar({row}, {col}) Number character at screen position
screencol() Number current cursor column screencol() Number current cursor column
@@ -5525,31 +5525,31 @@ round({expr}) *round()*
< -5.0 < -5.0
rpcnotify({channel}, {event}[, {args}...]) {Nvim} *rpcnotify()* rpcnotify({channel}, {event}[, {args}...]) {Nvim} *rpcnotify()*
Sends {event} to {channel} via |msgpack-rpc| and returns Sends {event} to {channel} via |rpc| and returns immediately.
immediately. If {channel} is 0, the event is broadcast to all If {channel} is 0, the event is broadcast to all channels.
channels. Example: > Example: >
:au VimLeave call rpcnotify(0, "leaving") :au VimLeave call rpcnotify(0, "leaving")
rpcrequest({channel}, {method}[, {args}...]) {Nvim} *rpcrequest()* rpcrequest({channel}, {method}[, {args}...]) {Nvim} *rpcrequest()*
Sends a request to {channel} to invoke {method} via Sends a request to {channel} to invoke {method} via
|msgpack-rpc| and blocks until a response is received. |rpc| and blocks until a response is received.
Example: > Example: >
:let result = rpcrequest(rpc_chan, "func", 1, 2, 3) :let result = rpcrequest(rpc_chan, "func", 1, 2, 3)
rpcstart({prog}[, {argv}]) {Nvim} *rpcstart()* rpcstart({prog}[, {argv}]) {Nvim} *rpcstart()*
Spawns {prog} as a job (optionally passing the list {argv}), Spawns {prog} as a job (optionally passing the list {argv}),
and opens a |msgpack-rpc| channel with the spawned process's and opens an |rpc| channel with the spawned process's
stdin/stdout. It returns: stdin/stdout. Returns:
- The channel id on success, which is used by |rpcrequest()|, - channel id on success, which is used by |rpcrequest()|,
|rpcnotify()| and |rpcstop()| |rpcnotify()| and |rpcstop()|
- 0 on failure. - 0 on failure
Example: > Example: >
:let rpc_chan = rpcstart('prog', ['arg1', 'arg2']) :let rpc_chan = rpcstart('prog', ['arg1', 'arg2'])
rpcstop({channel}) {Nvim} *rpcstop()* rpcstop({channel}) {Nvim} *rpcstop()*
Closes a |msgpack-rpc| {channel}, possibly created via Closes an |rpc| {channel}, possibly created via
|rpcstart()|. Also closes channels created by connections to |rpcstart()|. Also closes channels created by connections to
|$NVIM_LISTEN_ADDRESS|. |v:servername|.
screenattr(row, col) *screenattr()* screenattr(row, col) *screenattr()*
Like screenchar(), but return the attribute. This is a rather Like screenchar(), but return the attribute. This is a rather

306
runtime/doc/msgpack_rpc.txt
View File

@@ -1,97 +1,88 @@
*msgpack_rpc.txt* For Nvim. {Nvim} *msgpack_rpc.txt* {Nvim}
NVIM REFERENCE MANUAL by Thiago de Arruda NVIM REFERENCE MANUAL by Thiago de Arruda
The Msgpack-RPC Interface to Nvim *msgpack-rpc* RPC API for Nvim *rpc* *msgpack-rpc*
1. Introduction |msgpack-rpc-intro| 1. Introduction |rpc-intro|
2. API mapping |msgpack-rpc-api| 2. API mapping |rpc-api|
3. Connecting |msgpack-rpc-connecting| 3. Connecting |rpc-connecting|
4. Clients |msgpack-rpc-clients| 4. Clients |rpc-client|
5. Types |msgpack-rpc-types| 5. Types |rpc-types|
6. Wrapping methods |msgpack-rpc-wrap-methods| 6. Vimscript functions |rpc-vim-functions|
7. Vimscript functions |msgpack-rpc-vim-functions|
============================================================================== ==============================================================================
1. Introduction *msgpack-rpc-intro* 1. Introduction *rpc-intro*
The primary way to control a running Nvim instance is through The primary way to control Nvim programmatically is the RPC API, which speaks
MessagePack-RPC, a messaging protocol that uses the MessagePack serialization MessagePack-RPC ("msgpack-rpc"), a messaging protocol that uses the
format: https://github.com/msgpack/msgpack/blob/7498cf3/spec.md. MessagePack serialization format:
From now on, we refer to the protocol as msgpack-rpc. https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md
At this point, only plugins use msgpack-rpc, but eventually even user All kinds of Nvim "clients" use the RPC API: user interfaces (GUIs), remote
interaction will happen through it, since user interfaces will be separate plugins, scripts like "nvr" (https://github.com/mhinz/neovim-remote), and even
programs that control a headless Nvim instance. `nvim` itself can control other `nvim` instances. By connecting to the RPC API
programs can:
By connecting to the msgpack-rpc interface, programs can: - Call any API function
- Listen for events
- Receive remote calls from Nvim
- Call any Nvim API function The RPC API is like a more powerful version of Vim's `clientserver` feature.
- Listen for Nvim events
- Receive remote calls from Nvim
Nvim's msgpack-rpc interface is like a more powerful version of Vim's
`clientserver` feature.
============================================================================== ==============================================================================
2. API mapping *msgpack-rpc-api* 2. API mapping *rpc-api*
The Nvim C API, see |nvim-api|, is automatically exposed to the msgpack-rpc The Nvim C API, see |nvim-api|, is automatically exposed to the RPC API by the
interface by the build system, which parses headers at src/nvim/api from the build system, which parses headers at src/nvim/api/*. A dispatch function is
project root. A dispatch function is generated, which matches msgpack-rpc method generated which matches RPC API method names with public API functions,
names with non-static API functions, converting/validating arguments and return converting/validating arguments and return values back to msgpack.
values back to msgpack.
Client libraries will normally provide wrappers that hide msgpack-rpc details Client libraries (|api-client|s) normally provide wrappers that hide
from programmers. The wrappers can be automatically generated by reading msgpack-rpc details from application developers. The wrappers can be
bundled API metadata from a compiled Nvim instance. automatically generated by reading bundled API metadata from a compiled Nvim
instance.
There are two ways to obtain API metadata: There are two ways to obtain API metadata:
1. By connecting to a running Nvim instance and calling `vim_get_api_info` 1. Connect to a running Nvim instance and call `vim_get_api_info` via
via msgpack-rpc. This is best for clients written in dynamically-typed msgpack-rpc. This is best for clients written in dynamic languages which
languages, which can define functions at runtime. can define functions at runtime.
2. By starting Nvim with the `--api-info` command-line option, which makes Nvim 2. Start Nvim with the `--api-info` command-line option, which dumps a blob
dump a blob of msgpack metadata to standard output and exit. This is best of msgpack metadata to standard output. This is useful for clients
for clients written in statically-typed languages, which require a separate written in statically-compiled languages.
compilation step.
Here's a simple way to get human-readable description of the API (requires To get a human-readable list of API functions: >
Python and the `pyyaml`/`msgpack-python` pip packages): :new|put =map(msgpackparse(systemlist('nvim --api-info'))[0].functions, 'v:val.name._VAL[0]')
> <
nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' > api.yaml To get a formatted dump of the API using python (requires the `pyyaml` and
`msgpack-python` packages): >
nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))'
< <
============================================================================== ==============================================================================
3. Connecting *msgpack-rpc-connecting* 3. Connecting *rpc-connecting*
There are four ways to open msgpack-rpc streams to Nvim: There are several ways to open a msgpack-rpc stream to an Nvim server:
1. Through Nvim's stdin/stdout when it's started with the `--embed` option. 1. Through stdin/stdout when `nvim` is started with `--embed`. This is how
This is how other programs can embed Nvim. applications can embed Nvim.
2. Through the stdin/stdout of a program spawned by the |rpcstart()| function. 2. Through stdin/stdout of some other process spawned by |rpcstart()|.
*$NVIM_LISTEN_ADDRESS* 3. Through the socket automatically created with each instance. The socket
3. Through the socket automatically created with each instance. To get the location is stored in |v:servername|.
socket location for a running Nvim instance (which is random by default),
see the |$NVIM_LISTEN_ADDRESS| environment variable:
>
: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 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| environment variable 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 Connecting to the socket is the easiest way a programmer can test the API,
can be done through any msgpack-rpc client library or fully-featured Nvim client which can be done through any msgpack-rpc client library or full-featured
(which we'll see in the next section). Here's a Ruby script that prints 'hello |api-client|. Here's a Ruby script that prints 'hello world!' in the current
world!' in the current Nvim instance: Nvim instance:
> >
#!/usr/bin/env ruby #!/usr/bin/env ruby
# Requires msgpack-rpc: gem install msgpack-rpc # Requires msgpack-rpc: gem install msgpack-rpc
@@ -118,72 +109,103 @@ functions can be called interactively:
>>> nvim = attach('socket', path='[address]') >>> nvim = attach('socket', path='[address]')
>>> nvim.command('echo "hello world!"') >>> nvim.command('echo "hello world!"')
< <
One can also spawn and connect to an embedded Nvim instance via |rpcstart()| You can also embed an Nvim instance via |rpcstart()|
> >
let vim = rpcstart('nvim', ['--embed']) let vim = rpcstart('nvim', ['--embed'])
echo rpcrequest(vim, 'vim_eval', '"Hello " . "world!"') echo rpcrequest(vim, 'vim_eval', '"Hello " . "world!"')
call rpcstop(vim) call rpcstop(vim)
< <
============================================================================== ==============================================================================
4. Implementing new clients *msgpack-rpc-clients* 4. Implementing API clients *rpc-api-client* *api-client*
Nvim is still in alpha, so there's no in-depth documentation explaining how to All external UIs and remote plugins (as opposed to regular Vim plugins) are
properly implement a client library yet. The Python client (the pip package "clients" in general; but we call something an "API client" if its purpose is
"neovim") will always be up-to-date with the latest API changes, so its source to abstract or wrap the RPC API for the convenience of other applications
code is the best documentation currently available. There are some guidelines (just like a REST client or SDK such as boto3 for AWS: you can speak AWS REST
however: using an HTTP client like curl, but boto3 wraps that in a convenient python
interface). For example, the lua-client is an API client:
https://github.com/neovim/lua-client
- Separate the transport layer from the rest of the library. See The Python client (pip package "neovim") is the reference implementation of an
|msgpack-rpc-connecting| for details on how clients can connect to Nvim. API client. It is always up-to-date with the Nvim API, so its source code and
- Use a MessagePack library that implements at least version 5 of the test suite are an authoritative reference.
MessagePack spec, which supports the `bin` and `ext` types used by Nvim. https://github.com/neovim/python-client
- 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 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 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 API client implementation guidelines ~
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:
- Separate the transport layer from the rest of the library. See
|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 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 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).
Note: 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 to support it:
https://github.com/msgpack-rpc/msgpack-rpc-ruby/blob/master/lib/msgpack/rpc/transport/tcp.rb#L150-L158 https://github.com/msgpack-rpc/msgpack-rpc-ruby/blob/master/lib/msgpack/rpc/transport/tcp.rb#L150-L158
API metadata object ~
API clients exist to hide msgpack-rpc details. The API metadata object
contains information that makes this task easier (see also |rpc-types|):
- The "functions" key contains a list of metadata objects for individual
functions.
- Each function metadata object has |rpc-types| 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, 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`.
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_`.
============================================================================== ==============================================================================
5. Types *msgpack-rpc-types* 5. Types *rpc-types*
Nvim's C API uses custom types for all functions, se |nvim-api-types|. The Nvim C API uses custom types for all functions. |nvim-api-types|
For the purpose of mapping to msgpack, he types can be split into two groups: For the purpose of mapping to msgpack, 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) representation in msgpack-supported programming languages)
- Special Nvim types that map to msgpack EXT with custom type codes. - Special Nvim types that map to msgpack EXT with custom type codes.
Basic type mapping: Basic types ~
Nil -> msgpack nil Nil -> msgpack nil
Boolean -> msgpack boolean Boolean -> msgpack boolean
Integer (signed 64-bit integer) -> msgpack integer Integer (signed 64-bit integer) -> msgpack integer
Float (IEEE 754 double precision) -> msgpack float Float (IEEE 754 double precision) -> msgpack float
String -> msgpack string String -> msgpack string
Array -> msgpack array Array -> msgpack array
Dictionary -> msgpack map Dictionary -> msgpack map
Special Nvim types that use msgpack EXT: Special types (msgpack EXT) ~
Buffer -> enum value kObjectTypeBuffer Buffer -> enum value kObjectTypeBuffer
Window -> enum value kObjectTypeWindow Window -> enum value kObjectTypeWindow
Tabpage -> enum value kObjectTypeTabpage Tabpage -> enum value kObjectTypeTabpage
An API method expecting one of these types may be passed an integer instead, 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 although they are not interchangeable. For example, a Buffer may be passed as
@@ -191,7 +213,7 @@ an integer, but not a Window or Tabpage.
The most reliable way of determining the type codes for the special Nvim types 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 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 `vim_get_api_info` method at runtime. Here's a sample JSON representation of
the `types` object: the `types` object:
> >
"types": { "types": {
@@ -206,55 +228,27 @@ the `types` object:
} }
} }
< <
Even for statically compiled clients, it's a good practice to avoid hardcoding Even for statically compiled clients it is good practice to avoid hardcoding
the type codes, because a client may be built against one Nvim version but connect the type codes, because a client may be built against one Nvim version but
to another with different type codes. connect to another with different type codes.
============================================================================== ==============================================================================
6. Wrapping methods *msgpack-rpc-wrap-methods* 6. Vimscript functions *rpc-vim-functions*
As mentioned before, clients should provide an API that hides msgpack-rpc RPC functions are available in Vimscript:
details from programmers, and the API metadata object contains information
that makes this task easier:
- The "functions" key contains a list of metadata objects for individual 1. |rpcstart()|: Similarly to |jobstart()|, this will spawn a co-process
functions. with its standard handles connected to Nvim. The difference is that it's
- Each function metadata object has type information about the return value not possible to process raw data to or from the process's stdin, stdout,
and parameters. These can be used for generating strongly-typed APIs in or stderr. This is because the job's stdin and stdout are used as
static languages. a single msgpack channel that is processed directly by Nvim.
- Container types may be decorated with type/size constraints, e.g. 2. |rpcstop()|: Same as |jobstop()|, but operates on handles returned by
ArrayOf(Buffer) or ArrayOf(Integer, 2). This can be useful to generate even |rpcstart()|.
more strongly-typed APIs. 3. |rpcrequest()|: Sends a msgpack-rpc request to the process.
- Methods that operate instances of Nvim's types are prefixed with the type 4. |rpcnotify()|: Sends a msgpack-rpc notification to the process.
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`.
So, for an object-oriented language, a client library would have the classes |rpcrequest()| and |rpcnotify()| can also be used with channels connected to
that represent Nvim's types, and the methods of each class could be defined a nvim server. |v:servername|
by inspecting the method name prefix. There could also be a singleton Vim
class with methods mapped to functions prefixed with `vim_`
==============================================================================
7. Vimscript functions *msgpack-rpc-vim-functions*
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 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()|.
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|.
============================================================================== ==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl: vim:tw=78:ts=8:noet:ft=help:norl:

11
runtime/doc/nvim_provider.txt
View File

@@ -6,10 +6,9 @@
Nvim provider infrastructure *nvim-provider* Nvim provider infrastructure *nvim-provider*
First of all, this document is meant to be read by developers interested in This document is written for developers. If you are a normal user or plugin
contributing to the refactoring effort. If you are a normal user or plugin developer looking to learn about Nvim |rpc| infrastructure for implementing
developer looking to learn about Nvim |msgpack-rpc| infrastructure for plugins in other programming languages, see |remote-plugin|.
implementing plugins in other programming languages, see |remote-plugin|.
For instructions on how to enable Python plugins, see |nvim-python|. For For instructions on how to enable Python plugins, see |nvim-python|. For
clipboard, see |nvim-clipboard|. clipboard, see |nvim-clipboard|.
@@ -58,8 +57,8 @@ What these functions do is simple:
features are available. features are available.
The basic idea is that the provider#(name)#Call function should implement The basic idea is that the provider#(name)#Call function should implement
integration with an external system, because calling shell commands and integration with an external system, because calling shell commands and |rpc|
|msgpack-rpc| clients (Nvim only) is easier to do in vimscript. clients (Nvim only) is easier to do in vimscript.
Now, back to the Python example. Instead of modifying vimscript to allow for Now, back to the Python example. Instead of modifying vimscript to allow for
the definition of lowercase functions and commands (for the |:python|, the definition of lowercase functions and commands (for the |:python|,

6
runtime/doc/nvim_python.txt
View File

@@ -13,10 +13,10 @@ Python plugins and scripting in Nvim *nvim-python*
============================================================================== ==============================================================================
1. Introduction *nvim-python-intro* 1. Introduction *nvim-python-intro*
Through external Python 2/3 interpreters connected via |msgpack-rpc|, Nvim Through external Python interpreters connected via |rpc|, Nvim supports the
offers some support for the legacy |python-vim| and |python3| interfaces. legacy |python-vim| and |python3| interfaces.
Note: For now only the old Vim 7.3 API is supported. Note: Only the Vim 7.3 API is supported; bindeval (Vim 7.4) is not.
============================================================================== ==============================================================================
2. Quickstart *nvim-python-quickstart* 2. Quickstart *nvim-python-quickstart*

10
runtime/doc/remote_plugin.txt
View File

@@ -16,8 +16,8 @@ Nvim support for remote plugins *remote-plugin*
Extensibility is a primary goal of Nvim. Any programming language may be used Extensibility is a primary goal of Nvim. Any programming language may be used
to extend Nvim without changes to Nvim itself. This is achieved with remote to extend Nvim without changes to Nvim itself. This is achieved with remote
plugins, coprocesses that have a direct communication channel (via plugins, coprocesses that have a direct communication channel (via |rpc|) with
|msgpack-rpc|) with the Nvim process. the Nvim process.
Even though these plugins run in separate processes they can call, be called, Even though these plugins run in separate processes they can call, be called,
and receive events just as if the plugin's code were executed in the main and receive events just as if the plugin's code were executed in the main
@@ -33,9 +33,9 @@ check whether a plugin host is available for their chosen programming language.
Plugin hosts are programs that provide a high-level environment for plugins, Plugin hosts are programs that provide a high-level environment for plugins,
taking care of most boilerplate involved in defining commands, autocmds, and taking care of most boilerplate involved in defining commands, autocmds, and
functions that are implemented over |msgpack-rpc| connections. Hosts are functions that are implemented over |rpc| connections. Hosts are loaded only
loaded only when one of their registered plugins require it, keeping Nvim's when one of their registered plugins require it, keeping Nvim's startup as
startup as fast as possible, even if many plugins/hosts are installed. fast as possible, even if many plugins/hosts are installed.
============================================================================== ==============================================================================
3. Example *remote-plugin-example* 3. Example *remote-plugin-example*