Kakscript for the first time is hard, documenting my journey

lobre · May 20, 2025, 4:30pm

Hey,

I have been using Kakoune for a few years already. But I came to realize recently that I did not do much of kakscript. I just adapted a few configurations that I found, and I kept my kakrc very minimalist, trying to learn what the default experience could bring me. And this has been very valuable.

However, recently, I decided that I would like to take inspiration from the Plan9 Acme editor (which I really like) and bring them into Kakoune. Maybe not everything, but small bits that I could incorporate and that would turn my experience with Kakoune into a more personal story. But before doing that, I had to overcome something that I did not think would be much of a challenge: kakscript.

Effectively, even if I have dug many parts of Kakoune extensively, going so far as to read a lot of its internal source code, surprisingly, I never took much time writing kakscript. I mostly read what was inside the internal rc (which is super valuable already). I am rather familiar with POSIX shell (if you are not, I recommend reading POSIX Shell Tutorial). But trying to write kakscript was a different story. I think this is a hard task for someone that starts doing it for the first time.

This is hard mostly because there is no material to learn it. You just read the docs, pick some bits from rc and start adapting and writing yours. And you start hitting some walls. And I realized those walls were mostly related to the lack of understanding on how kakscript was parsed and evaluated. So a few weeks ago, I decided to stop the implementation of my kak plugin and start writing a blog post that would explain what I understood from learning the parsing and evaluation of kakscript.

I have been helped a lot by @alexherbo2 , so thank you a lot for the time you spent with me.

And now I would like to share my post here. I am aware that this can says things that may be wrong, and I would love to have feedback so that I can improve it. I haven’t seen any guide like that, so I really hope that it can help beginners to get up to speed rapidly. When those concepts are understood, kakscript becomes fun to write!

Have a good read and thank you in advance for any feedback that you can give me, including corrections, reorganisations or just your feelings about whether such a guide can be useful or not.

Here is the link below. Note that I don’t have a personal blog. I don’t write that much and I like the convenience of gist for my writing. The style might not be super pretty, but it is effective…

gist.github.com

https://gist.github.com/lobre/4838c6859ff7d89e43447f07432cba7d

README.md

# Understanding Kakoune’s Command Language: Parsing, Evaluations, and Beyond

Kakoune is a modal editor. That means when you’re editing text, you’re constantly interacting with the editor using a powerful language of keystrokes — moving around, selecting text, transforming content, all through short, expressive commands typed directly in the editing interface. This is the **core editing experience**, and it’s what gives Kakoune its speed and fluidity.

But this isn’t the only way to interact with Kakoune.

There’s another side to Kakoune — a more structural, programmable one — which lets you interact with the editor through **commands**. These commands can be used to configure Kakoune, automate behavior, and define complex workflows. Commands can be written in configuration files, invoked via custom keybindings, or typed directly into the command prompt.

This document focuses on that second side: the **command interface**. We will explore how commands work, how they are built, and how Kakoune interprets them. We’ll define the basic building blocks — strings, words, parsing, expansions — and build up to understand how Kakoune processes scripts and configurations written in what is often called **kakscript**.

This file has been truncated. show original

Thank you!

possumvibes · May 21, 2025, 3:08am

This was an excellent read and really helped me wrap my head around some aspects of kak scripting I’ve been a bit overwhelmed trying to understand! Thank you for putting the time into writing this. The quiz examples in particular really helped to clarify everything you’d discussed, especially the way the registers quizzes built on each other!

In my opinion, this would be an excellent addition to the kakoune wiki!

hpf · May 21, 2025, 5:50am

Thank you, so timely! Just yesterday I resolved to have another more serious attempt at configuring Kakoune, after letting it slide for a while precisely because of the lack of clear documentation. I’ll let you know how I fare with your article.

Screwtapello · May 21, 2025, 8:30am

This is really well-written and comprehensive! Good work! I do have some notes, however.

Under “How Kakoune loads configuration”, the text kind of implies without stating outright that Kakoune will load the standard library then load user configuration. This is generally true, but a bit misleading. If you look at the standard kakrc file the process runs like this:

Load everything from the user’s autoload directory
If and only if that doesn’t exist, load everything from the system autoload directory
Load the per-system kakrc.local file
Load the user’s kakrc

One of the most common questions we get from new users is “I installed a plugin and now my syntax highlighting stopped working”, because they created the autoload directory to put the plugin into, and that disabled loading of the standard library. I think it’s worth calling out this quirk for prospective new users.

In “A Better Way: Store State First”, the example uses $kak_client_list to get a list from Kakoune into the shell, and later $kak_quoted_reg_c to get another list from Kakoune into the shell, but you don’t describe the difference between those two, or how to distinguish one from the other. It might be worth having an earlier section about communication between Kakoune and the shell, to cover *_quoted_* expansions, and Kakoune-quoting in shell.

In “Use Kakoune Quotes in Shell Blocks When Possible”, it suggests that Kakoune always provides handy environment variables like $kak_client or $kak_opt_filetype to shell blocks. This is not true! Kakoune only exports environment variables mentioned in the text of the block or (in recent versions) in command-line arguments.

So:

echo %sh{ env | grep kak_ }

…will print nothing, but:

echo %sh{ env | grep kak_ # kak_client }

…will print the name of the current client, and so will:

def -params 1 checkvars %{ echo %sh{ env | grep kak_ } }
checkvars kak_client

There’s scope for a follow-up post with advanced topics like $kak_command_fifo, but since this is just focussing on the layers of evaluation and expansion, that’s fine — you address those topics well.