Documentation on plugin development

Help
1

I have been looking around the kakoune website for any documention on the language / details of writing plugins for this editor. Could someone kindly point me in the right direction. Not fond of the idea of having to look at existing plugins written to reverse engineer how it works. Is there an api?

2

There’s not a lot of documentation on plugin development because there’s not a lot in Kakoune that’s specific to plugins.

A plugin is just a file with the .kak extension, containing the same commands you’d type at the : prompt, so you’ll first want to investigate :doc commands. The two most important commands, :evaluate-commands and :execute-keys, have a lot in common and don’t fit neatly into the regular commands documentation, so they’re documented separately under :doc execeval.

Scripting actual editing operations is done by giving :execute-keys a sequence of normal-mode commands, most of which you probably already know from using Kakoune interactively, but there’s a lot of lesser-known keys that come in handy for scripting, so you’ll want to read :doc keys too.

Often while scripting you’ll want to examine some part of Kakoune’s state, like “what are the coordinates of the current selection”, or “what arguments were given to this function”, or “what’s the current value of this option”. For this kind of thing, you’ll need to read :doc expansions. In particular, note the %sh{} shell-script expansion — it’s the only sensible way to do things like conditions or loops. It’s a pretty common idiom to invoke :evaluate-commands with a shell-expansion that generates the commands to be evaluated, like this:

evaluate-commands %sh{
    case "$kak_selection" in
        *x*)
            echo info -anchor "$kak_cursor_line.$kak_cursor_column" \
                selection contains an x
            ;;
        *)
            echo info -anchor "$kak_cursor_line.$kak_cursor_column" \
                selection does not contain x
            ;;
    esac
}

One part of Kakoune that technically can be used interactively but almost never is, is the “hook” system, which lets you run commands when some particular event occurs. Check out :doc hooks, and because hooks are installed in scopes you’ll want to read :doc scopes too.

Apart from that, learning Kakoune scripting is really just about learning how to combine these somewhat-unusually-shaped puzzle-pieces to create the particular shape you want. For that, poking at existing plugins that do something similar is a good way to learn. Note that Kakoune plugins can do a lot with only a little code, so it probably won’t be as daunting as you expect.

Remember, if you hit something weird you can always ask more questions here, or drop by the IRC channel!

7 Likes
3

@Screwtapello I genuinely thank you for this perfect answer. This explains what I need to know and where to find more pertinent information. While waiting for an answer I did happen to stumble upon :doc execeval as well I noticed that evaluate-commands %sh was popularly used. I wonder though if I can use zsh scripting in the same %sh block. I know python but if doing stuff like if statements, conditionals and that sort of thing, I would rather learn some zsh as opposed to sh though I honestly have not investigated this I will do so now to see what the differences are. I will be reading each of those documentions you pointed out and I feel that what you have provided is a complete answer. Thank you.

I have not been using kakoune, I have previously been using vim and was looking for other options. It was a toss-up between Kakoune and Vis both of which I am up to the challenge of learning. It seems now my answer is Kakoune because of the documentation, and the scripting versus using lua for Vis. However, I do wonder if there is an option to debug kak scripts.

Much appreciation.

4

:echo -debug 'my debug message'
will print ‘my debug message’ to the debug buffer which you can edit with
:b *debug*
you can also just send messages to a scratch buffer or append it to a file by echoing it from a shell.

1 Like
5

There’s a couple of options here:

  • zsh is a command-line tool just like awk or sed or python, so you can run it inside a %sh{} block quite happily
  • zsh is (mostly, I think) an expanded and extended implementation of POSIX shell, so basic things like if statements work exactly the same way — learning POSIX shell is learning (part of) zsh, much like learning C is learning (part of) C++
  • If you set the $KAKOUNE_POSIX_SHELL environment variable to point at zsh before starting Kakoune, it will run every %sh{} block through zsh… but I’m not sure zsh is 100% compatible with basic POSIX shell, so I can’t guarantee Kakoune would still work correctly afterward

As well as :echo -debug that prion mentioned, the stderr of any %sh{} block gets sent to the *debug* buffer, so when things don’t work as you expect that can be very helpful.

1 Like
6

Thank you both. I am very greatful for the answers provided and feel that I am ready to start using Kakoune. I feel prepared to write Kakoune scripts and have the documentation and tools (evaluate-commands, expansions, echo and the *debug* buffer) to handle any use case I encounter not already covered by the bundled autoload scripts and user contributed plugins / extensions. Thank you also for being not only very though and knowledgeable but also welcoming to a newcomer.

7

there’s also this document that has a little info and general ideas behind scriptin Kakoune

1 Like
8

Just in reply to Andrey’s

I found the link bellow solved a missing piece of the puzzle for me when I first started with Kakoune. An Illustrated Redirection Tutorial.

1 Like