159 lines
9.1 KiB
Markdown
159 lines
9.1 KiB
Markdown
|
|
# vim-hug-neovim-rpc
|
|
|
|
This is an **experimental project**, trying to build a compatibility layer for
|
|
[neovim rpc client](https://github.com/neovim/python-client) working on vim8.
|
|
I started this project because I want to fix the [vim8
|
|
support](https://github.com/roxma/nvim-completion-manager/issues/14) issue for
|
|
[nvim-completion-manager](https://github.com/roxma/nvim-completion-manager).
|
|
|
|
Since this is a general purpose module, other plugins needing rpc support may
|
|
benefit from this project. However, there're many neovim rpc methods I haven't
|
|
implemented yet, which make this an experimental plugin. **Please fork and
|
|
open a PR if you get any idea on improving it**.
|
|
|
|
***Tip: for porting neovim rplugin to vim8, you might need
|
|
[roxma/nvim-yarp](https://github.com/roxma/nvim-yarp)***
|
|
|
|
|
|
|
|
## Requirements
|
|
|
|
|
|
1. vim8
|
|
2. If `has('pythonx')` and `set pyxversion=3`
|
|
- same requirements as `4. has('python3')`
|
|
2. Else if `has('pythonx')` and `set pyxversion=2`
|
|
- same requirements as `5. has('python')`
|
|
4. Else if `has('python3')`
|
|
- [neovim/python-client](https://github.com/neovim/python-client). (`pip3
|
|
install neovim`). There should be no error when you execute `:python3
|
|
import neovim`
|
|
5. Else if `has('python')`
|
|
- [neovim/python-client](https://github.com/neovim/python-client). (`pip
|
|
install neovim`). There should be no error when you execute `:python
|
|
import neovim`
|
|
6. `set encoding=utf-8` in your vimrc.
|
|
|
|
***Use `:echo neovim_rpc#serveraddr()` to test the installation***. It should print
|
|
something like `127.0.0.1:51359`.
|
|
|
|
## API
|
|
|
|
| Function | Similar to neovim's |
|
|
|----------------------------------------------|------------------------------------------------|
|
|
| `neovim_rpc#serveraddr()` | `v:servername` |
|
|
| `neovim_rpc#jobstart(cmd,...)` | `jobstart({cmd}[, {opts}])` |
|
|
| `neovim_rpc#jobstop(jobid)` | `jobstop({job})` |
|
|
| `neovim_rpc#rpcnotify(channel,event,...)` | `rpcnotify({channel}, {event}[, {args}...])` |
|
|
| `neovim_rpc#rpcrequest(channel, event, ...)` | `rpcrequest({channel}, {method}[, {args}...])` |
|
|
|
|
Note that `neovim_rpc#jobstart` only support these options:
|
|
|
|
- `on_stdout`
|
|
- `on_stderr`
|
|
- `on_exit`
|
|
- `detach`
|
|
|
|
## Incompatibility issues
|
|
|
|
- Cannot pass `Funcref` object to python client. Pass function name instead.
|
|
- Python `None` will be converted to `''` instead of `v:null` into vimscript.
|
|
See [vim#2246](https://github.com/vim/vim/issues/2246)
|
|
- The following neovim-only API will be ignored quietly:
|
|
- `nvim_buf_add_highlight`
|
|
- `nvim_buf_clear_highlight`
|
|
|
|
## Overall Implementation
|
|
|
|
```
|
|
"vim-hug-neovim-rpc - Sequence Diagram"
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
┌───┐ ┌──────────┐ ┌───────────┐ ┌──────┐
|
|
│VIM│ │VIM Server│ │NVIM Server│ │Client│
|
|
└─┬─┘ └────┬─────┘ └─────┬─────┘ └──┬───┘
|
|
│ Launch thread │ │ │
|
|
│───────────────────> │ │
|
|
│ │ │ │
|
|
│ Launch thread │ │
|
|
│─────────────────────────────────────────────────>│ │
|
|
│ │ │ │
|
|
│ `ch_open` connect │ │ │
|
|
│───────────────────> │ │
|
|
│ │ │ │
|
|
│ │────┐ │ │
|
|
│ │ │ Launch VimHandler thread│ │
|
|
│ │<───┘ │ │
|
|
│ │ │ │
|
|
│ │ │ Connect │
|
|
│ │ │<─────────────────────────────
|
|
│ │ │ │
|
|
│ │ ────┐
|
|
│ │ │ Launch NvimHandler thread
|
|
│ │ <───┘
|
|
│ │ │ │
|
|
│ │ │ Request (msgpack rpc) │
|
|
│ │ │<─────────────────────────────
|
|
│ │ │ │
|
|
│ │ ────┐ │
|
|
│ │ │ Request enqueue │
|
|
│ │ <───┘ │
|
|
│ │ │ │
|
|
│ │ notify (method call) │ │
|
|
│ │ <────────────────────────────│ │
|
|
│ │ │ │
|
|
│ notify (json rpc) │ │ │
|
|
│<─────────────────── │ │
|
|
│ │ │ │
|
|
────┐ │ │
|
|
│ Request dequeue │ │
|
|
<───┘ │ │
|
|
│ │ │ │
|
|
────┐ │ │ │
|
|
│ Process │ │ │
|
|
<───┘ │ │ │
|
|
│ │ │ │
|
|
│ │ Send response (msgpack rpc) │
|
|
│────────────────────────────────────────────────────────────────────────────────>
|
|
┌─┴─┐ ┌────┴─────┐ ┌─────┴─────┐ ┌──┴───┐
|
|
│VIM│ │VIM Server│ │NVIM Server│ │Client│
|
|
└───┘ └──────────┘ └───────────┘ └──────┘
|
|
```
|
|
|
|
<!--
|
|
@startuml
|
|
|
|
title "vim-hug-neovim-rpc - Sequence Diagram"
|
|
|
|
VIM -> "VIM Server": Launch thread
|
|
VIM -> "NVIM Server": Launch thread
|
|
VIM -> "VIM Server": `ch_open` connect
|
|
"VIM Server" -> "VIM Server": Launch VimHandler thread
|
|
|
|
Client-> "NVIM Server": Connect
|
|
"NVIM Server" -> "NVIM Server": Launch NvimHandler thread
|
|
Client -> "NVIM Server": Request (msgpack rpc)
|
|
"NVIM Server" -> "NVIM Server": Request enqueue
|
|
"NVIM Server" -> "VIM Server": notify (method call)
|
|
"VIM Server" -> VIM: notify (json rpc)
|
|
VIM -> VIM: Request dequeue
|
|
VIM -> VIM: Process
|
|
VIM -> Client: Send response (msgpack rpc)
|
|
|
|
@enduml
|
|
-->
|
|
|
|
## Debugging
|
|
|
|
Add logging settigns to your vimrc. Log files will be generated with prefix
|
|
`/tmp/nvim_log`. An alternative is to export environment variables before
|
|
starting vim/nvim.
|
|
|
|
```vim
|
|
let $NVIM_PYTHON_LOG_FILE="/tmp/nvim_log"
|
|
let $NVIM_PYTHON_LOG_LEVEL="DEBUG"
|
|
```
|
|
|