Repository files navigation

Archive note: the projet was moved tohttps://git.sr.ht/~hadronized/hop.kak.

Table of content:

• Install
• Configuration
  • Kakoune options
  • hop-kak options
• Usage
• Workflow examples
  • Default keyset
  • Better selections
  • Select and hint visible words

This binary is intended to be used with theKakoune editor, and provideshinting capabilitiesbased on the current selections of the user. The workflow is simple:

1. Make a selection in your buffer.
2. Call the binary by providing the selections in%sh{} block — via$kak_selections_desc, typically.
3. Hints appear. You can press the keys in order of each hint to reduce the hints.
4. You typically reduce until only one hint remains; in such case, hinting is disabled and you are left with the soleselection. However, you are free to leave hinting at any reduction step by pressing the<esc> key.

Currently, the only installation channel ishttps://crates.io. It requirescargo to be installed.

cargo install hop-kak

You must include thehop.kak file before trying to use Hop. It contains:

• Thehop_ranges option. Used to highlight your buffer with the labels.
• Thehop_label face definition. Feel free to override the default.

Another approach is to usehop-kak --init inside yourkakrc to automatically inject the of thehop.kak file:

evaluate-commands%sh{ hop-kak --init }

--init is only available ifhop-kak is compiled with theinit features, which is enabled by default.

hop-kak — the built binary — doesn’t have any configuration file. Instead, it is configured by passing CLI arguments:

• -k --keyset: the keyset to use. This depends on your keyboard layout. Choose it wisely! It must not have anyduplicate key, and keys are ordered by importance; i.e. the keys that are easier to reach should appear first.
  • For QWERTY, we recommendTODO.
  • For AZERTY, we recommendTODO.
  • For BÉPO, we recommendetisura,cnovpdélxqygàhfbjz.
• -s --sels: selections to hint. You should always pass$kak_selections_desc here.
• -l --labels: previous generated labels. You should never need to use that argument.
• -z --key: key for reduction. You should never need to use that argument.
• --handle: which part of a selection to put the cursor on; theanchor, or thecursor. Default to the anchor.

The binary was made with few responsibilities, so that people can use it in a wider variety of situations. For thisreason, you will have to build a bit aroundhop-kak.hop-kak works by reading selections in, highlighting them andmaking Kakoune wait for a key press to either abort, or reduce the hints. If you decide to reduce the hints,hop-kakwill filter your selections and reduce them to map the new set of hints. Hence,hop-kak can basically be seen as atrie reducer for Kakoune selections. It is then very composable. You pass it initial selections, and it interactivelyfilters them.

Whatever your selections, you will always want to start a hopping session with the following command:

eval -no-hooks --%sh{ hop-kak --keyset"<YOUR_KEYSET_HERE>" --sels"$kak_selections_desc" }

For instance, with the bépo keyboard layout, you could map theè key to start hopping with your current selections:

mapglobal normal è':eval -no-hooks -- %sh{ hop-kak --keyset "etisura,cnovpdélxqygàhfbjz" --sels "$kak_selections_desc" }<ret>'

Then, it’s up to you to come up with your own workflow!

You should have an option to set your keyset if you intend on having several workflows. For instance, for bépo:

declare-option str hop_kak_keyset 'etisura,cnovpdélxqygàhfbjz'

Something that is pretty useful is to map a key to select the visible part of the buffer.<a-%> is a good candidate,as it’s not mapped by Kakoune for now:

map global normal <a-%> ':execute-keys gtGbx<ret>'

This will help with creating selections. We assume you have this binding below. You can also make a command for that:

define-command hop-kak %{eval -no-hooks --%sh{ hop-kak --keyset"$kak_opt_hop_kak_keyset" --sels"$kak_selections_desc" }}

With the<a-%> mapping, you canselect words with<a-%>s\w+, and then press your mapping to start hopping around.

A slightly better approach to reduce the number of keys and control keys to type is to create a small functionlike this:

define-command -override hop-kak-words %{exec'gtGbxs\w+<ret>:eval -no-hooks -- %sh{ hop-kak --keyset "$kak_opt_hop_kak_keyset" --sels "$kak_selections_desc" }<ret>'}

And mapping it to your key; e.g.SPC è:

mapglobal user è :hop-kak-words<ret>