Using Conjure programatically (API)

Since Conjure is just a Lua program (compiled from Fennel) running within Neovim we can require the Conjure’s modules directly into other plugins or scripts. This allows you to build more tools atop of Conjure that get to take advantage of all of Conjure’s supported language clients.

The best documentation for this is the source itself, so please have a look around for public functions you’d like to use. Feel free to get in touch with me (Olical) if you have any questions around something specific.

Now let’s dive into some of the most common and useful functions in the API that you’ll probably want to use. I’ll show how to use them from Lua but it’ll be easy to take the leap into Vim Script or Fennel.

Using the right client

When a user interacts with Conjure using mappings they’ll be in the buffer they’re interested in already which will have a filetype of clojure or janet for example. When your plugin runs the user may have a completely different buffer in focus, imagine a callback being executed at some point in the future, the filetype of the current user buffer could be anything!

So when calling any (well, only some, but it’s best to be on the safe side) Conjure API functions, be sure to wrap them in a call to with-filetype as shown below. You don’t have to do this is you know the call was invoked while the user was in the buffer you’re interested in with no callbacks or delays in the way (such as from a mapping or command they invoked).

local client = require("conjure.client")

client["with-filetype"]("janet", my_awesome_function, 10, 20)

The arguments are the filetype you want, the function to be called and then any optional trailing arguments you would like to be passed to your function when it’s called.

Appending to the log

Every Conjure client has it’s own log buffer, here’s how we can append to it.

local client = require("conjure.client")
local log = require("conjure.log")

-- Append to the log of the client for the current buffer's filetype.
log.append([";; Hello, World!"])

-- With the filetype enforced, just in case you're calling this from a callback.
client["with-filetype"]("janet", log.append, [";; Hello, World!"])

append does take a second opts argument but that’s less important, here’s a rough overview of those options.

• break? will insert a break line of -------…​ to separate log entries.

• suppress-hud? will avoid showing the HUD.

• join-first? will join the first line of your new lines onto the current last line of the log.