Plugin creation guide

Help
1

I was trying to write a plugin for myself but I found several pain points.

  • I tried to read other plugins and try the same techniques, but they differ quite a lot and it looks like there is no standar way of doing anything.
  • I struggled a lot with debugging and reloading the changes. Is there a way of working other than printing and reopening the files?

I would like to know if there is some guides, guidelines, FAQs, tips, tutorials or something that can help me with creating them and avoiding common pitfalls.

1 Like
2

I’ve developed several semi popular plugins, and that’s the steps I usually go through when developing.

Step one:
Think about what plugin should do. Define some base functions.
Step two:
Roll your face over the keyboard several times to provide clean and understandable Sh code.
Step three:
???
Step four:
Release!

On a more serious note, I often create a bunch of commands with -override switch to easier reloading, and use echo -debug to print debug messages. That’s enough for me to debug, because my main job is to write for SoC, and we have no debuggers, so printing is the only option acutally. Kakoune’s state can be expresses by printing pretty well.

Please, please don’t use aliases for builtin commands like def, set, decl e.t.c. It’s hard to read.

There is. It contains essential bits, but pretty much about overall structure.

@alexherbo2 showed me this way of evaluating buffer, or selection, which I use now instead of :source %val{buffile}

3

@xyuusha Don’t do the reloading stuff. It’s better to work with two instances: one for writing the plug-in and one other for testing it.

  1. Create a new repository to hold the plug-in’s files.
  2. Source your plug-in from your kakrc.
  3. Write some functionalities, and eventually reconfigure your kakrc.
  4. In a separate instance / window / place:
    4.1 Open a meaningful document to experiment your functionalities,
    4.2 Do some tests,
    4.3 Quit,
    4.4 Repeat.

If you want to automate Step 4, you can do:

kak document.txt -e "
  your-command
  execute-keys -with-maps -with-hooks <keys>
  …
"

If you don’t want to modify your kakrc in Step 2 and 3, you can inject the configuration in the kak command:

kak document.txt -e "
  source your-plugin.kak
  hook <scope> <event> <filter> %{
    your-command
  }
  map <scope> <mode> <key> ': your-command<ret>'
  …
"
2 Likes