4 Remote plugins

Remote plugins are Racket modules which are distributed as Neovim plugins. Please refer to :h remote-plugin for details. A remote plugin can contain any Racket code, which will be executed when the Racket host is launched. What you most likely will be interested in is to define functions, commands and auto-commands for Neovim in Racket. These can then be treated as if they were a regular part of Neovim.

4.1 An example remote plugin

Save the following contents as a Racket file in the rplugin/racket subdirectory of one of your runtime directories (e.g. ~/.config/nvim).

(require nvim)

(define calls 0)

(define (increment-calls!)

(cond

[(= calls 5) (raise "Too many calls!")]

[else (set! calls (add1 calls))]))

(nvim-command "Cmd" #:range "" #:nargs #\* #:sync #t

(λ (args range)

(increment-calls!)

(send (current-nvim-instance) set-current-line

(format "Command: Called ~a times, args: ~a, range ~a"

calls args range))))

(nvim-autocmd "BufEnter" #:pattern "*.rkt" #:eval "expand('<afile>')" #:sync #t

(λ (filename)

(increment-calls!)

(send (current-nvim-instance) set-current-line

(format "Autocmd: Called ~a times, file: ~a" calls filename))))

(nvim-function "Func"

(λ (args)

(increment-calls!)

(send (current-nvim-instance) set-current-line

(format "Function: Called ~a times, args: ~a" calls args))))

Now restart Neovim and execute :UpdateRemotePlugins. Restart Neovim one more time and you will be able to use the function, command and auto-command defined in this remote plugin. Notice how we use the current-nvim-instance parameter as a target for our API calls.

4.2 Defining remote plugins

A remote plugin can define functions, commands and auto-commands for Neovim. Each of these is represented by a Racket callback function which gets called with the necessary arguments applied.

Each of the following procdures takes in a name, a function and a number of keyword arguments. The name is the name under which the function or command will be registered in Neovim and the same restrictions apply as for all user-defined functions and commands in Neovim.

All procedures have a #:sync keyword argument; if it is true the remote call will be synchronous, otherwise it will be asynchronous.

I am not yet sure about the arity of callback procedures, so take that information with a grain of salt.

proc is a procedure of one or two arguments; the first argument is a vector of arguments passed to the Neovim function, the second argument (if applicable) is a vector of two integers: the first in is the first line of the range, the second one is the last line of the range. The result of proc will be returned by the RPC call.

If sync is false the function call will not block Neovim, but Neovim will not receive the return value of proc, it will use some default value like 0 instead. Asynchronous functions are only useful for their side effects.

nargs is either 0 (no arguments), 1 (exactly one argument), #\* (any number of arguments), #\? (zero or one arguments), or #\+ (at least one arguments). The arguments will be passed as a vector to proc (unless nargs is 0, in which case nothing will be passed).

complete is a string describing the completetion method (see :h :command-completetion). This argument does not affect the arity of proc.

range and count are mutually exclusive, and both increase the arity of proc by one. The range is either #f (no range) allowed, #t (range allowed), #\%, or an exact-nonnegative-integer?. The count is either #f (no count) or a exact-nonnegative-integer?. See :h :command-range for details. If count is given or range is an integer, one number representing that count is passed as an argument. For other values (#t and #\%) of range a vector of two numbers is passed, the first one being the first line, the second one the last line.

bang is either #f (no bang allowed) or #t (bang allowed). If #t, an integer will be passed to proc indicating whether the bang was specified (non-zero) or not (zero).

register is either #f (no register allowed) or #t (register allowed). If #t, a string containing the register name will be passed to proc. If no register was given that string will be empty.

The pattern is a string describing the pattern of the auto-command, see :h autocmd-patterns for details.