Zach's Overengineered Kakoune Plugins

They say that for any given job, if Python isn't the best tool for the job, then it's the second-best tool for the job.

Kakoune has a lot of amazing plugins and user-modes, and they're usually not written in Python.

So, since I must be working with the second-best tool for the job, I thought I would go the whole 9 yards and overengineer the h*ck out of it 😉. In true abstractlyZach fashion, this project includes:

• reimplementations of awesome scripts that could be one-liners in bash with, like, 5 pipes
• dependency injection
• readability as a priority
• composition over inheritance
• rigorous testing
• helpful command-line menus
• milliseconds of extra run-time! Python is an interpreted language!
• intense CI practices
• linting and autoformatting
• lots of documentation
• minimal use of Mocks, maximal use of better test doubles like Fakes and Stubs
• robust error-handling
• fine-grained logging options

Also, I was pretty excited about kakoune.cr, but I was super fuzzy on how to actually use it. Hopefully these plugins will serve as living documentation on some good ways to leverage this tool.

Installation

as a user

I recommend using pipx for installation. It allows you to install python packages on your machine in separate virtual environments without having to manage the virtual environments yourself. pip also works if you prefer that.

pipx install kak-plugins

as a developer

We use poetry to do package and dependency management. For bonus points, install it using pipx instead of their recommended method.

pipx install poetry

git clone https://github.com/abstractlyZach/kak_plugins.git
cd kak_plugins

poetry install

Dependencies

• Kakoune, of course 😄
• kakoune.cr
  • enables us to retrieve info from Kakoune
  • provides an interface to control Kakoune
• A clipboard command-line utility. I use these:
  • pbcopy for OSX
  • xclip for Linux
  • wl-clipboard for Wayland (if you don't know what this is and you use Linux, you'll probably use xclip)

Setup

There are some environment varibles you will need to define in order to use these plugins. You would probably define these in your ~/.bashrc, zshrc, or ~/.profile. I define mine here

# program that reads stdin and writes to your system clipboard
export CLIPBOARD="pbcopy"

Plugins

github-permalink

Create a permalink to a file on GitHub with lines pre-selected. Example. The selected line or range of lines matches your current selection in Kakoune and will be copied to your clipboard program.

github-permalink --help

in kak

This method is great for using in your everyday editing

1. open a file in Kakoune
2. make a selection
3. in normal mode, use :$ github-permalink
4. you now have a permalink to your kakoune selection. it should look something like this https://github.com/abstractlyZach/kak_plugins/blob/write-readme/README.md#L40

I like binding this command to hotkeys so I can hit 2 buttons and then paste the link into Slack or something.

in a terminal

This method is great for learning, development, and debugging

1. open a file in kakoune
2. make a selection
3. open a connected terminal. there are a couple of recommended methods
   • use :> in normal mode
   • kcr-fzf-shell
4. github-permalink --help