mirror of
https://github.com/mawww/kakoune.git
synced 2024-09-11 13:00:41 +03:00
Some initial thoughts on writing plugins
parent
c25893b60f
commit
c7279de8da
30
Writing-Plugins.md
Normal file
30
Writing-Plugins.md
Normal file
@ -0,0 +1,30 @@
|
||||
A Kakoune plugin is just a file with the `.kak` extension, living in the `%val{config}/autoload` directory (`~/.config/kak/autoload` by default, see [[Installing Plugins]] for details). If you have moved configuration out of your `kakrc` into the autoload directory to keep things tidy, you have already created a plugin!
|
||||
|
||||
## Naming things
|
||||
|
||||
All commands created by plugins must live together, all options created by plugins must live together, all user-modes created by plugins must live together, etc. It's a good practice to prefix everything you declare or define with your plugin's name, to reduce the chance of collision with other plugins.
|
||||
|
||||
## Do not create default mappings or hooks
|
||||
|
||||
It's tempting to add a bunch of `map` and `hook` commands to your plugin so that it automatically works from the moment it's installed. However, there's not *that* many key combinations available, and it's quite likely that you'll stomp on some other plugin, or the user's own configuration. While it's easy for the end-user to add new mappings of their own, it's difficult for them to figure out what mappings exist or which plugin introduced a mapping that broke their workflow. So don't do it.
|
||||
|
||||
Instead, your plugin should present its functionality as commands, that can be searched for with Kakoune's command-line, and with docstrings the user can read. You may also want to add a user-mode with mappings relevant to your plugin, if there's a set of very-frequently-used commands. You might also include "serving suggestion" mappings in your README or other documentation that people can paste into their `kakrc` and modify.
|
||||
|
||||
## Finding resources
|
||||
|
||||
Your plugin may rely on data from an external file, or depend on an external script written in a more convenient language. Your plugin could hard-code a specific filesystem path to that data, but if your users install your plugin in a different location, things will break.
|
||||
|
||||
Luckily, Kakoune provides a solution, in the form of the `%val{source}` expansion. Let's say you have a plugin called "MyPlugin", which requires data in a CSV file. Your plugin might wind up with a filesystem structure like this:
|
||||
|
||||
kakoune-my-plugin
|
||||
|
|
||||
+- my-plugin.kak (our plugin script)
|
||||
|
|
||||
+- data.csv (the data our plugin requires)
|
||||
|
||||
At the top of `my-plugin.kak`, declare an option to store the path to the plugin directory. We use the `-hidden` flag because end-users don't need to see or modify this option, it's purely internal:
|
||||
|
||||
declare-option -hidden str my_plugin_path %sh{ dirname "$kak_source" }
|
||||
|
||||
Now `%opt{my_plugin_path}` contains the absolute path of the plugin directory, probably something like `/home/somebody/.config/kak/autoload/kakoune-my-plugin` (but the whole point is that it can vary). When a shell block in your plugin needs to refer to the data file, it can say `$kak_opt_my_plugin_path/data.csv`.
|
||||
|
Loading…
Reference in New Issue
Block a user