kakoune.cr

Installation | Usage | Configuration | Commands | Extending kcr | Writing plugins

kakoune.cr (kcr) is a command-line tool for Kakoune.

Dependencies

• Crystal
• jq

Installation

Run the following in your terminal:

make install

Add the Kakoune definitions to your kakrc.

evaluate-commands %sh{
  kcr init kakoune
}

Usage

kcr [-s, --session <name>] [-c, --client <name>] [-r, --raw] <command> [arguments]

Configuration

Kakoune example configuration:

~/.config/kak/kakrc

map -docstring 'New client' global normal <c-t> ': new<ret>'
map -docstring 'New terminal' global normal <c-n> ': connect-terminal<ret>'
map -docstring 'New popup' global normal + ': connect-popup<ret>'
map -docstring 'Open Dolphin' global normal <c-o> ': $ dolphin .<ret>'
map -docstring 'Open files' global normal <c-f> ': + kcr-fzf-files<ret>'
map -docstring 'Open buffers' global normal <c-b> ': + kcr-fzf-buffers<ret>'
map -docstring 'Open files by content' global normal <c-g> ': + kcr-fzf-grep<ret>'
map -docstring 'Open lazygit' global normal <c-l> ': + lazygit<ret>'

Bash example configuration:

~/.bashrc

EDITOR='kcr edit'

alias k='kcr edit'
alias K='kcr-fzf-shell'
alias ks='kcr shell --session'
alias a='kcr attach'
alias :='kcr send'

XDG MIME Applications example configuration:

~/.config/mimeapps.list

[Default Applications]
text/plain=kakoune.desktop

You can get the MIME type with:

file -b -i -L <file>

Commands

Options

-s, --session <name> ⇒ Session name
-c, --client <name> ⇒ Client name
-r, --raw ⇒ Use raw output
-h, --help ⇒ Show help

Commands

kcr init <name> ⇒ Print functions
kcr init kakoune ⇒ Print Kakoune definitions
kcr init starship ⇒ Print Starship configuration
kcr install <name> ⇒ Install files
kcr install commands ⇒ Install commands
kcr install desktop ⇒ Install desktop application
kcr create [session] ⇒ Create a new session
kcr attach [session] ⇒ Connect to session
kcr list ⇒ List sessions
kcr shell [command] [arguments] ⇒ Start an interactive shell
kcr edit [files] [input: fifo] ⇒ Edit files
kcr open [files] [input: fifo] ⇒ Open files
kcr send <command> [arguments] [input: json-commands] ⇒ Send commands to client at session
kcr get [expansions] [input: data-stream] ⇒ Get states from a client in session
kcr escape [arguments] [input: json-arguments] ⇒ Escape arguments
kcr help [command] ⇒ Show help

init

kcr init <name>

Print functions.

init kakoune

kcr init kakoune

Print Kakoune definitions.

Example – kakrc configuration:

evaluate-commands %sh{
  kcr init kakoune
}

Commands

connect <command> [arguments] ⇒ Run a command as <command> sh -c {connect} -- [arguments].  Example: connect terminal sh.
run <command> [arguments] ⇒ Run a program in a new session
[$] connect-program <command> [arguments] ⇒ Connect a program
[>] connect-terminal [command] [arguments] ⇒ Connect a terminal
[+] connect-popup [command] [arguments] ⇒ Connect a popup

init starship

kcr init starship

Print 🚀 Starship configuration.

install

kcr install <name>

Install files.

install commands

kcr install commands

Install commands.

install desktop

kcr install desktop

Install desktop application.

create

kcr create [session]

Create a new session.

attach

kcr attach [session]

Connect to session.

list

kcr list

List sessions.

Output example:

[
  {
    "session": "kanto",
    "client": "main",
    "buffer_name": "pokemon.json",
    "working_directory": "/home/red/kanto"
  }
]

shell

kcr shell [command] [arguments]

Start an interactive shell.

Example

kcr shell kcr attach

edit

kcr edit [files] [input: fifo]

Edit files.

open

kcr open [files] [input: fifo]

Open files.

send

kcr send <command> [arguments] [input: json-commands]

Send commands to client at session.

Example

kcr send echo tchou

Example – Send commands from stdin:

kcr get -- echo %val{bufname} |
kcr get -- echo %val{buflist} |
jq --slurp |
kcr send

get

kcr get [expansions] [input: data-stream]

Get states from a client in session.

Example

kcr get %val{buflist}

Output:

[
  "kanto.json",
  "johto.json"
]

Example – Streaming data:

kcr get %val{bufname} |
kcr get %val{buflist} |
jq --slurp

Output:

[
  [
    "kanto.json"
  ],
  [
    "kanto.json",
    "johto.json"
  ]
]

escape

kcr escape [arguments] [input: json-arguments]

Escape arguments.

Example

kcr escape -- evaluate-commands -try-client main echo tchou

Output:

'evaluate-commands' '-try-client' 'main' 'echo' 'tchou'

Example – Escape arguments from stdin:

kcr get -- echo %val{buflist} |
kcr escape

Output:

'echo' 'kanto.json' 'johto.json'

help

kcr help [command]

Show help.

Extending kcr

Like Git, kcr allows you to define custom functions and run them as subcommands.

See the shipped commands for examples.

Writing plugins

Example – Escape arguments:

evaluate-commands %sh{
  kcr escape -- echo "maïs'mélange'bientôt"
}

Example – Async communication (1):

$ sh -c %{
  kcr send -- echo tchou
}

Example – Async communication (2):

$ sh -c %{
  kcr send -- echo "$1" and "$2"
} -- %val{session} %val{client}

Example – Async communication (3):

$ sh -c %{
  kcr get -- echo %val{bufname} |
  kcr get -- echo %val{buflist} |
  jq --slurp |
  kcr send
}