This type defines a request handler, using a Handler function, the request type, a name, and whether it should block Neovim while executing. It can be constructed from handler functions using rpcFunction, rpcCommand and rpcAutocmd.

A list of RpcHandlers can be used as a Neovim plugin by passing them to runNvimHandlersIO.

A request handler function is a Sem with arbitrary stack that has an error of type Report at its head.

These error messages are reported to the user by return value for synchronous requests and via echo for asynchronous ones, provided that the severity specified in the error is greater than the log level set in UserError.

If the plugin was started with --log-file, it is also written to the file log. Additionally, reports are stored in memory by the effect Reports.

For an explanation of Stop, see Errors.

This name is used for the function or command registered in Neovim as well as to internally identify a handler.

Create an RpcHandler that is triggered by a Neovim function of the specified name.

The handler can take arbitrary parameters, as long as they are instances of MsgpackDecode (or more specifically, HandlerArg), just like the return type.

When invoking the function from Neovim, a value must be passed for each of the handler function's parameters, except for some special cases, like a number of successive Maybe parameters at the tail of the parameter list.

The function is converted to use messagepack types by the class HandlerCodec.

For easier type inference, it is advisable to use Handler r a for the return type of the handler instead of using Member (Stop LogReport) r.

Example:

import Ribosome

ping :: Int -> Handler r Int
ping 0 = basicLogReport "Invalid ping number!" ["This is written to the log"]
ping i = pure i

rpcFunction "Ping" Sync ping

Create an RpcHandler that is triggered by a Neovim command of the specified name.

The handler can take arbitrary parameters, as long as they are instances of MsgpackDecode (or more specifically, HandlerArg), just like the return type. The function is converted to use messagepack types by the class HandlerCodec.

Commands have an (open) family of special parameter types that will be translated into command options, like Range for the line range specified to the command. See command params.

For easier type inference, it is advisable to use Handler r a for the return type of the handler instead of using Member (Stop Report) r.

Create an RpcHandler that is triggered by a Neovim autocommand for the specified event. For a user autocommand, specify User for the event and the event name for the file pattern in AutocmdOptions.

For easier type inference, it is advisable to use Handler r a for the return type of the handler instead of using Member (Stop Report) r.

Convenience function for creating a handler that is triggered by both a function and a command of the same name. See rpcFunction and rpcCommand.

This type indicates the execution style that Neovim should be instructed to use for RPC messages – synchronous requests that block Neovim until a result is returned and asynchronous notifications.

Run a Neovim plugin using a set of handlers and configuration, with an arbitrary stack of custom effects placed between the handlers and the Ribosome stack. This is important, because the custom effects may want to use the Neovim API, while the handlers want to use both Neovim and the custom effects.

Example:

data Numbers :: Effect where
  Number :: Int -> Sem r Int

makeSem ''Numbers

runNumbers :: Member (Rpc !! RpcError) r => InterpreterFor Numbers r
runNumbers = \case
  Number i -> (-1) <! nvimGetVar ("number_" <> show i)

type CustomStack = [AtomicState Int, Numbers]

currentNumber :: Handler r Int
currentNumber = number =<< atomicGet

setNumber :: Int -> Handler r ()
setNumber = atomicPut

runCustomStack :: InterpretersFor CustomStack r
runCustomStack = interpretAtomic . runNumbers

main :: IO ()
main = runNvimPluginIO @CustomStack "numbers" runCustomStack [
  rpcFunction "CurrentNumber" Sync currentNumber,
  rpcFunction "SetNumber" Async setNumber
  ]

Note:

• PluginConfig is being constructed via OverloadedStrings
• CustomStack has to be specified as a type application, because GHC cannot figure it out on its own.
• For an explanation of Rpc !! RpcError, see Errors

This runs the entire stack to completion, so it can be used in the app's main function.

For more flexibility and less type inference noise, this can be inlined as:

runRemoteStack conf $ runCustomStack $ withHandlers handlers remotePlugin

Run a Neovim plugin using a set of handlers and configuration.

This function does not allow additional effects to be used. See runNvimPluginIO for that purpose.

This runs the entire stack to completion, so it can be used in the app's main function.

Run a Neovim plugin using a set of handlers and configuration, with an arbitrary stack of custom effects placed between the handlers and the Ribosome stack.

Like runNvimPluginIO, but allows the PluginConfig to contain a CLI parser for an arbitrary type c that is then provided in a Reader c to the plugin.

This is separate from runNvimPluginIO because it requires a type hint when using OverloadedStrings or def to construct the config without an option parser.

Add a set of RpcHandlers to the plugin.

This can be used multiple times and has to be terminated by interpretHandlersNull, which is done automatically when using the plugin main functions.

Run the main loop for a remote plugin.

The complete stack of a Neovim plugin.

Run plugin internals and IO effects for a remote plugin, reading options from the CLI.

Run plugin internals and IO effects for a remote plugin, reading options from the CLI.

Like runRemoteStack, but allows the CLI option parser to be specified.

Run plugin internals without IO effects.

The effects that are shared by all variants (like embedded, remote, socket) of main functions.

Contains logging effects, IO related stuff and the plugin's name in a Reader.

Execute the basic plugin stack all the way to an IO, given the plugin name and logging settings.

Execute the basic plugin stack all the way to an IO like runBasicPluginStack, reading config overrides from command line options.

The set of core effects that handlers and API functions commonly use.

This effect abstracts interaction with the Neovim RPC API. An RPC call can either be a request or a notification, where the former expects a response to be sent while the latter returns immediately.

For requests, the constructor sync blocks the current thread while async takes a callback that is called from a new thread.

The constructor notify sends a notification.

The module Ribosome.Api.Data contains RpcCalls for the entire Neovim API, generated by calling neovim --api-info during compilation from Template Haskell.

The module Ribosome.Api contains functions that call sync with those RpcCalls, converting the input and return values to and from msgpack.

These functions have signatures like:

nvimGetVar :: ∀ a r . Member Rpc r => MsgpackDecode a => Text -> Sem r a

A manual call would be constructed like this:

Ribosome.sync (RpcCallRequest (Request "nvim_get_option" [toMsgpack "textwidth"]))

RPC calls may be batched and sent via nvim_call_atomic, see RpcCall.

This effect's default interpreter uses Resumable for error tracking. See Errors.

The payload of an RPC request.

A wrapper for Request that allows applicative sequencing of calls for batch processing, used for a declarative representation of the Neovim API.

Neovim has an API function named nvim_call_atomic that makes it possible to send multiple RPC requests at once, reducing the communcation overhead. Applicative sequences of RpcCalls are automatically batched into a single call by Rpc.

This can be combined neatly with ApplicativeDo:

import Ribosome
import qualified Ribosome.Api.Data as Api

sync do
  a :: Int <- Api.nvimGetVar "number1"
  b :: Int <- Api.nvimGetVar "number2"
  pure (a + b)

Block the current thread while sending an RPC request.

Send an RPC request and pass the result to the continuation on a new thread.

Send an RPC notification and return immediately.

The Neovim RPC channel ID

An event is an RPC notification sent by Neovim that is not intended to be dispatched to a named handler, but consumed in a broadcasting fashion.

Since they aren't marked as such, the host treats any notification with an unknown method name as an event.

Events can be consumed with Consume and subscribe.

The name of an event, which corresponds to the RPC method in the payload.

This is a reactive system that is triggered by several frequently sent autocommands to inspect a user-defined set of Neovim variables for changes. When a variable's value has been observed to have changed from the previously recorded state, the associated handler is executed.

This handler has to be passed to runNvimPluginIO or similar as part of the custom effect stack, like:

runNvimPluginIO "my-plugin" (watchVariables [("variable_name", handler)]) mempty

This does not remove VariableWatcher from the stack, but intercepts and resends it, to make it simpler to use with the plugin runners.

The name of a variable that Ribosome should watch for changes.

Run a Sem in an embedded plugin context by starting a Neovim subprocess, forking the Ribosome main loop and registering the supplied handlers, using the supplied custom effect stack.

This is a basic version of what ribosome-test provides, which uses polysemy-test and hedgehog for a comprehensive testing framework.

The parameters have the same meaning as for remote plugins.

Run a Sem in an embedded plugin context by starting a Neovim subprocess, forking the Ribosome main loop and registering the supplied handlers.

Like runEmbedPluginIO, but without extra effects.

Run a Sem in an embedded plugin context by starting a Neovim subprocess, forking the Ribosome main loop and registering the supplied handlers, using the supplied custom effect stack.

Like runEmbedPluginIO, but allows the PluginConfig to contain a CLI parser for an arbitrary type c that is then provided in a Reader c to the plugin.

This is separate from runEmbedPluginIO because it requires a type hint when using OverloadedStrings or def to construct the config without an option parser.

Fork the main loop for a plugin connected to an embedded Neovim.

Run an embedded Neovim, plugin internals and IO effects, reading options from the CLI.

Run an embedded Neovim, plugin internals and IO effects, reading options from the CLI.

Like runEmbedStack, but allows the CLI option parser to be specified.

Run the internal stack for an embedded Neovim test, without IO effects.

Class of values that can be decoded from MessagePack Objects.

Class of values that can be encoded to MessagePack Objects.

Pattern synonym for decoding an Object.

Encode an arbitrary number of heterogeneously typed values to a single MessagePack array. This function is variadic, meaning that it takes an arbitrary number of arguments:

>>> msgpackArray (5 :: Int) ("error" :: Text) (3.14 :: Double) :: Object
ObjectArray [ObjectInt 5, ObjectString "error", ObjectFloat 3.14]

This avoids the need to call toMsgpack once for each element and then once more for the array.

Encode an arbitrary number of heterogeneously typed values to a single MessagePack map. This function is variadic, meaning that it takes an arbitrary number of arguments:

>>> msgpackMap ("number", 5 :: Int) ("status", "error" :: Text) ("intensity", 3.14 :: Double) :: Object
ObjectMap (Map.fromList [(ObjectString "number", ObjectInt 5), (ObjectString "status", ObjectString "error"), (ObjectString "intensity", ObjectFloat 3.14)])

This avoids the need to call toMsgpack once for each element and then once more for the map.

This effects abstracts Neovim variables with associated defaults.

This type is used by the effect Settings, representing a Neovim variable associated with a plugin.

It has a name, can optionally prefixed by the plugin's name and may define a default value that is used when the variable is undefined.

The type parameter determines how the Neovim value is decoded.

The errors emitted by the effect Settings.

Interpret Settings natively, using Neovim variables.

This effect manages scratch buffers, that is, transient buffers displaying text not associated with a file. See ScratchOptions for configuration.

Configure the visual properties of a scratch buffer. If the option float is specified, the buffer will be opened in a floating window.

The default configuration, setting all flags to False except for $sel:resize:ScratchOptions and $sel:bottom:ScratchOptions, and everything else to mempty.

The set of options accepted by the float key of the argument to nvim_open_win, configuring the appearance and geometry of a floating window.

The ID type used to store active scratch buffers.