Replacing character / set of characters in visual mode

Help
1

I’m just starting at Kakoune (more precisely, I want to play with it more seriously after a long period of just barely touching the surface), and wondering if the following is possible:

Can a user (with a mode / leveraging something like faces / other ) replace a set of displayed character with another (only for display). I’m thinking about a mode that would let you read some content in a slightly nicer way, typically for instance, for a Markdown document:

  • Replace string [v] with unicode character ☑ or [ ] with ☐
  • Replace the first * on a line with •

Is this something that maybe already exists, or is this something that is out of scope / not well suited to achieve with Kakoune?

2

You are looking for the replace-ranges highlighter.

One weakness of this highlighter is that you can’t just say “replace [v] with :ballot_box_with_check:”, you need a hook to search the buffer for instances of [v], then collect the span of each match into a range-specs option, and then update that option whenever the buffer is modified.

1 Like
3

Thanks so much for the answer!
I am confused by that part:

then collect the span of each match into a range-specs option

Do you have an example of a hook somewhere that collect into a range-spec option?
Thank you very much!

4

If you stick this in your kakrc file (or better yet, in ~/.config/kak/autoload/char-replacement.kak) then in every buffer, the text [v] should be replaced with a check-mark emoji.

In practice, you’ll probably want to only install this hook and highlighter for particular filetypes or even particular files, rather than every buffer ever. There’s probably also smarter things you could do about not recalculating all the replacements if the buffer content hasn’t actually changed (by comparing %val{timestamp} at the time the hook executes to the %val{timestamp} stored in the option), but since I just wanted to illustrate how it works, I kept it simple.

# An option to stare character replacements
declare-option -hidden range-specs char_replacement_ranges
# Tell Kakoune to apply the replacements in every buffer where they're defined
add-highlighter global/char-replacement replace-ranges char_replacement_ranges

# Test: [v] [ ] [v] [ ]

# In every buffer, when the user stops typing for a little while...
hook global NormalIdle .* %{
    # Clear the previous replacement ranges, if any
    set-option buffer char_replacement_ranges %val{timestamp}

    # Create a draft context, so changes to the selection will be automatically
    # undone when the block finishes execution
    evaluate-commands -draft %{
        # Select all the text that matches the checked box syntax
        execute-keys <percent>s\[v\]<ret>

        # Run a shell-script to generate the command that populates the option
        evaluate-commands %sh{
            # The beginning of the generated command
            printf "set-option -add buffer char_replacement_ranges "
            # Set the replacement text for each selection.
            # $kak_selections_desc contains the list of selection ranges
            # in the right format, and printf automatically repeats its
            # pattern for each argument
            printf "%s|✅ " $kak_selections_desc
        }
    }
}
3 Likes
5

This is very useful, thank you a lot!
Your answer (which work out of the box) guided me to important part of the documentation which I’m still reading.
For people that like me may wonder where $kak_selections_desc comes from and have difficulty finding it, the closest match I saw was in :doc expansions value-expansions, where they explain %val{selections_desc}.
I wish I would know how to search for terms in the documentation and I wish there would be a book I could buy to learn Kakoune :smiley: (If you were looking for ideas of project Screwtapello :eyes:)
Anyway, thanks a lot!!

1 Like
6

There is some more relevant information on that documentation page under :doc expansions shell-expansions where it is explained where the magic $kak_ prefixed variable comes from. As you can see all kakoune internal values, options, registers and arguments get converted into shell environment variables for scripting support.

3 Likes