1 Introduction
Neovim can be controlled programmatically through its RPC API (:h rpc). The processes which use this API to communicate with Neovim are called RPC clients. A client can be any Racket process, e.g. a GUI, a remote plugin, or a REPL instance.
This client library abstracts away the process of connecting to Neovim and handling RPC messages; it supports arbitrarily many concurrent connections and provides functions which mirror the Neovim API calls.
1.1 Installation
First install this library like you would install any other Racket library. The easiest option would be using raco.
raco pkg install nvim-client
If you also want to write Neovim remote plugins in Racket you need to install this library as a Neovim plugin. You can install the Git repository as a Neovim plugin, but it is recommended that you instead use the installed raco package as the source. That way your plugins will launch faster because the Racket host has been compiled.
1.2 An example session
For the example session we will connect to a running Neovim instance using Unix domain sockets. If you whish to follow along start Neovim now and get the server address (:h v:servername).
; Import the libraries first > (require nvim) ; Connect to the socket (insert your server address) > (define-values (in out) (unix-socket-connect "/var/folders/...")) ; Start the client session > (define nvim (nvim-attach in out)) ; Send a "Hello world!" command to Neovim > (send nvim command "echo 'Hello world!'")
First we connected to the Unix domain socket; the client library is ambivalent as to which transport method is being used, so you are free to use any one you want. In order to start a session we must provide an input- and output port over which communication takes place.
Once the RPC session has been intialised we get an object representing the Neovim instance. There can be multiple instances at the same time, so we need a handle to send messages to. We call the command method to display a "Hello world!" message in Neovim’s command line.