JSON RPC

Kakoune is able to talk to the outside world using a protocol called JSON-RPC

There's already a document describing what kind of information can transit during this discussion. I encourage you to read it first.

This wiki page will attempt to illustrate how you can use this kakoune feature.

Output: draw, draw_status

Let's start by creating a normal kakoune client. Open a terminal and run:

kak -s yolo

Here the -s flag indicates that we want to create a brand new yolo session.

Open a second terminal, this time we create a kakoune client that does not display a nice ncurses GUI on the screen but print raw JSON output.

kak -c yolo -ui json

Since we decided to connect to the same yolo session. Everything you do in the first client will be mirrored in the second one. This way you can easily discover what's going on.

Example of JSON output when the second client is launched :

{ "jsonrpc": "2.0", "method": "draw", "params": [[[{ "face": { "fg": "#303030", "bg": "#d7d7d7", "attributes": [] }, "contents": "\u000a" }, { "face": { "fg": "default", "bg": "default", "attributes": [] }, "contents": "" }]], { "fg": "#d7d7d7", "bg": "#303030", "attributes": [] }, { "fg": "#afd787", "bg": "#303030", "attributes": [] }] }
{ "jsonrpc": "2.0", "method": "menu_hide", "params": [] }
{ "jsonrpc": "2.0", "method": "info_hide", "params": [] }
{ "jsonrpc": "2.0", "method": "draw_status", "params": [[], [{ "face": { "fg": "default", "bg": "default", "attributes": [] }, "contents": "*scratch* 1:1 " }, { "face": { "fg": "default", "bg": "default", "attributes": [] }, "contents": " " }, { "face": { "fg": "#444444", "bg": "#d7d7d7", "attributes": [] }, "contents": "1 sel" }, { "face": { "fg": "default", "bg": "default", "attributes": [] }, "contents": " - unnamed1@[yolo]" }], { "fg": "#d7d7d7", "bg": "#444444", "attributes": [] }] }
{ "jsonrpc": "2.0", "method": "refresh", "params": [true] }

After typing iHello<esc> in the first client, here's what the output :

{ "jsonrpc": "2.0", "method": "draw", "params": [[[{ "face": { "fg": "default", "bg": "default", "attributes": [] }, "contents": "Hello" }, { "face": { "fg": "#303030", "bg": "#d7d7d7", "attributes": [] }, "contents": "\u000a" }, { "face": { "fg": "default", "bg": "default", "attributes": [] }, "contents": "" }]], { "fg": "#d7d7d7", "bg": "#303030", "attributes": [] }, { "fg": "#afd787", "bg": "#303030", "attributes": [] }] }
{ "jsonrpc": "2.0", "method": "draw_status", "params": [[], [{ "face": { "fg": "default", "bg": "default", "attributes": [] }, "contents": "*scratch* 1:6 " }, { "face": { "fg": "#d7d7d7", "bg": "#5f875f", "attributes": [] }, "contents": "[+]" }, { "face": { "fg": "default", "bg": "default", "attributes": [] }, "contents": " " }, { "face": { "fg": "#444444", "bg": "#d7d7d7", "attributes": [] }, "contents": "1 sel" }, { "face": { "fg": "default", "bg": "default", "attributes": [] }, "contents": " - unnamed1@[yolo]" }], { "fg": "#d7d7d7", "bg": "#444444", "attributes": [] }] }
{ "jsonrpc": "2.0", "method": "refresh", "params": [true] }

We can see the Hello contents in the draw method.

If you decide to use some commands in the first client, using the : key, kakoune gives you nice feedback in info box. (you know, the infamous Clippy thing ;)). You could expect that displaying this info box will generate JSON output in the second client. But you won't find any object with info_show method. Like menu_show, these kind of methods are local per client. In a next section will see how to get this data.

Input: keys & Output: info_show

We just discovered how to get messages from kakoune, but how do speak to it? Using stdin. To do so, we'll use a named piped (FIFO). Everything we will stream to it will be passed to the running kakoune client.

Open a new terminal and create a FIFO:

mkfifo /tmp/magritte

Start a new json kakoune client and plug in on this FIFO.

kak -c yolo -ui json -e 'set global autoinfo normal' < /tmp/magritte

Note that we also enabled a kakoune option which basically activate info all the time. You can consider it as a help++.

Now, let's talk to kakoune through JSON-RPC protocol.

echo '{ "jsonrpc": "2.0", "method": "keys", "params": ["iHello<esc>"] }' > /tmp/magritte 

If you still have your normal kakoune client running on the yolo session, you should see the word Hello appear in the buffer. On the second client, you'll see draw command.

Let's try to trigger an info box:

echo '{ "jsonrpc": "2.0", "method": "keys", "params": ["%sl<ret>d"] }' > /tmp/magritte

Here, using the d key will trigger the info box % : erase selected text, and output in the second client:

{ "jsonrpc": "2.0", "method": "info_show", "params": ["d", "erase selected text", { "line": 0, "column": 0 }, { "fg": "#d7d7d7", "bg": "#5f875f", "attributes": [] }, "prompt"] }