<newbie> ELI5 how integration with shell works

Terminal Tools
1

Hi! I’m happy to publicly admit that, despite 30 years professional programming, it just isn’t clicking for me.

Is there a step by step guide that will take me through the workflow of interacting with the shell? I’ve read the docs, I’ve read trampoline, I’ve gone through a bunch of plugins including fzf.kak, but I’m just not "grok"ing it.

Some use cases I wanted to achieve, but the only progress I’ve made is making a head-shaped hole in the brick wall:

  • formatting the contents of the buffer (on save) by calling a Lua or SQL formatter
  • executing cargo test or cargo clippy in a new weztern split
  • executing FZF with the lines of the current buffer
  • etc.

My questions range from:

  • how does kakoune know which terminal I’m using in order to know which command to use from https://github.com/mawww/kakoune/tree/master/rc/windowing
  • how does fzf.kak manage to show FZF in the same terminal pane as kakoune given kakoune doesn’t have any native windowing capabilities? Is it Tmux specific integration?
  • I understand kakscript can do things with %sh{} but how does it interpret the results of executing that? For example, if %sh{} somehow called FZF with the contents of the buffer, how would it know to jump to the selected line? It can’t possible know unless it’s told…but how to tell it what to do with the results?

I’m not looking for somebody to do this for me, or to give me step by step instructions (although I wouldn’t say no ;-)) - I want to learn myself. I’m really just asking for any helpful resources I should look at.

Thanks!

2

The key to grokening is to understand that kak manage subprocesses (POSIX sh processes) and has way of communicating by e.g. setting environment variables in such subprocess; most notably when you … %sh{…}. You can communicate back with e.g. kak -p or more comfortably for simple cases with :eval %sh{…}.

The previous paragraph assume prerequisites: familiar with UNIXes, reading :doc execeval :doc expansions.

I suggest to use plugins you mention only if it bring immediate positive result without too much configuration. You will not be able to integrate them elegantly with your other UNIX tools and setting|getting from Kakoune client|session in general if you do not understand Kakoune architecture, which is a bit more complicated (client/server) than I vaguely described.

Another advice as learning exercise is to try to pass simple message between Kakoune and an executable with :eval %sh{…}, e.g. try to do arithmetics by calling python or lua or bc on selection content ($kak_selection) and pass the result back to Kakoune with printf in the %sh{…} block.

You should use search feature of this forum for particular goal. One of your question is basically format-on-write and has been answered in multiple threads, see :doc hooks, and for “simple” integration with linters/formatters, see the wiki

for other tutorials, see Intro to Kakoune … articles, and in particular Languages · mawww/kakoune Wiki · GitHub

have courage, it’s worth it.

3 Likes
3

Thank you! I definitely don’t want to add a bunch of plugins - that’s one of the reasons I’m not keen on neovim.

4

I use the off-the-shelf solution provided by format.kak in the Kakoune repository:

hook -group my-format global BufWritePre .*\.(?:c|cc|cpp|h)$ format-buffer
hook -group my global WinSetOption filetype=(c|cpp|java) %{
	set-option buffer formatcmd "clang-format -style=file -assume-filename=%val{buffile}"
}

If you’re curious how it’s implement, go read rc/tools/format.kak, it’s quite concise

  • executing cargo test or cargo clippy in a new weztern split

Use Screwtape / kakoune-cargo · GitLab.
There’s also a generalized way to display results of external commands in Screwtape / kakoune-repl-buffer · GitLab but I recommend you start with kakoune-cargo because it provides things like cargo-next-error

If you install Kakoune from latest git master (which is very easy, run make and run src/kak) then you can run this command to show the output of cargo test in a new (wezterm) split

map global user T %{:with-option windowing_placement vertical cargo test<ret>}

how does kakoune know which terminal I’m using in order to know which command to use from

On latest master, if I type :terminal, I get this help text:

       ╭───────────────────────────────────────────────────┤terminal├────────────────────────────────────────────────────╮
       │ terminal <program> [<arguments>]: create a new terminal using the preferred windowing environment and placement │
       │                                                                                                                 │
╭──╮   │ This executes "%opt{windowing_module}-terminal-%opt{windowing_placement}" with the given arguments.             │
│  │   │ If the windowing module is 'wayland', 'sway' or 'x11', then the 'termcmd' option is used as terminal program.   │
@  @  ╭│                                                                                                                 │
││ ││ ││ Example usage:                                                                                                  │
││ ││ ╯│                                                                                                                 │
│╰─╯│  │     terminal sh                                                                                                 │
╰───╯  │     with-option windowing_placement horizontal terminal sh                                                      │
       │                                                                                                                 │
       │ See also the 'new' command.                                                                                     │
       ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

And the windowing_module option is detected at startup with this hook from rc/windowing/detection.kak:

hook -group windowing global KakBegin .* %{
    evaluate-commands %sh{
        set -- ${kak_opt_windowing_modules}
        if [ $# -gt 0 ]; then
            echo 'try %{ '
            while [ $# -ge 1 ]; do
                echo "require-module ${1}; set-option global windowing_module ${1} } catch %{ "
                shift
            done
            echo "echo -debug 'no windowing module detected' }"
        fi
    }
}

this will succeed for wezterm.kak if this does:

# ensure that we're running under screen
evaluate-commands %sh{
    [ -z "${kak_opt_windowing_modules}" ] || [ -n "$WEZTERM_UNIX_SOCKET" ] || echo 'fail wezterm not detected'
}
  • how does fzf.kak manage to show FZF in the same terminal pane as kakoune given kakoune doesn’t have any native windowing capabilities? Is it Tmux specific integration?

yes, I think that one detects tmux and uses tmux’s popup feature (or splits I don’t remember, I haven’t used fzf.kak in years, the builtin fuzzy-finder works fine here).

1 Like
5

Thanks @krobelus! This was exactly what I needed!