Short Example(s)

[smolck]

I'd like to use this API, but without clear documentation or examples I'm having a hard time. Is there any way you could add a simple example (or post one here) that shows how to connect to a Neovim instance (over Unix socket for example) and call some API functions?

It would also be nice to see examples of the differences between the types in Client.Connection_type.

[TyOverby]

We're working on some examples that are open-sourcable, but I don't have anything for you right now. I'll update this issue when we do though!

As for Connection_type, the three kinds are these:

• Unix (string): neovim opens up a unix pipe that plugins can connect to, so vcaml (when given a path to this pipe), can connect and start talking to neovim
• Embed (embed parameters): VCaml spawns a neovim instance with all of the parameters provided in the embed parameters and then communicates with that process with that processes stdin and stdout
• Child : The Vcaml program is running as a child of neovim, and communicates with neovim via its own stdin and stdout

[TyOverby]

I've added this description to the MLI file. It'll be pushed to github within the next few days.

[smolck]

@TyOverby Thanks for the info!

Knowing about the connection types (and also w/understanding about monads, Async, and Or_error, which I didn’t have when making this issue), I was able to get a working neovim connection over a Unix socket which I can communicate with. Nothing super complex or anything, but I was able to connect and call the out_write function, which is way further than I got originally.

Now that I have an idea about how to do this, I was wondering if some examples would be accepted in a PR? I could probably just model them after examples from another library like pynvim if necessary. I was thinking having at least one example for each connection type would be ideal, and also having one in the README. What do you think?

[foleyfactor]

Hey @smolck! I'm an intern at Jane Street working on Vcaml.

I've been working on adding some examples which we're hoping to be able to share shortly. Here's a quick idea for where we're at right now and what's in the pipeline, so that we don't end up duplicating each other's work.

We've defined three basic kinds of plugins that we think will be common in the world of Vcaml and have created an example of each kind. The three kinds and their examples are:

• One-shot plugins: plugins that are kicked off by neovim and just run once and complete. The example we have for this is just a classic "echo hello world" which prints to the neovim messages list.

• RPC plugins: plugins that can register handlers for RPC requests over neovim and respond accordingly (in this case, the plugin runs for much longer, handling requests as they arise). The example we have for this is a plugin which can take an RPC request with a name and send back "Hello, {name}!".

• Buffer plugins: plugins that are concerned with a buffer and which react to changes in buffers. The example for this is a "clock" which opens a new buffer, splits it into a new window, and displays the time which updates every second.

I'm also working on an API to be able to create plugins of these types which abstracts away creating the connection to the client and the structure of programs for each of the different plugin types. That's a little bit further out, but is actively being pursued.

Did you have any specific pynvim examples in mind that you think would be good examples to have in Vcaml? We’re always interested in having more sample plugins!

[foleyfactor]

The examples have been pushed, hopefully they give you an idea for how to get started with VCaml/the general pattern of the plugins (setting up the client connection, interacting with neovim, etc.).

As I mentioned briefly in my previous comment, part of the motivation behind these examples was finding the correct levels of abstraction for making an API for creating these plugins. The API is in progress right now and handles things like client acquisition so that developers don't have to duplicate that code every time. As a slight amendment to my previous comment, the new breakdown of plugins that we are working with is:

• One-shot plugins: same as before; run once and complete.

• Persistent plugins: this is a little bit more abstract than the previously mentioned RPC and buffer plugins, and encapsulates all plugins that are meant to run for a longer period of time. Both the greetings example and the buffer_clock example are examples of persistent plugins.