Skip to content

Latest commit

 

History

History
617 lines (418 loc) · 10.2 KB

manual.md

File metadata and controls

617 lines (418 loc) · 10.2 KB
Raw

Manual

Usage

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

Open Kakoune, then a connected terminal with connect terminal or connect run alacritty. Edit files with kcr edit and see them being opened in the Kakoune client. You can set your EDITOR to kcr edit and configure your graphical applications to open files with Kakoune.

Configuration

Add Kakoune definitions:

evaluate-commands %sh{
  kcr init kakoune
}

Options

  • -s, --session <name> ⇒ Session name (Default: KAKOUNE_SESSION)
  • -c, --client <name> ⇒ Client name (Default: KAKOUNE_CLIENT)
  • -b, --buffer <name> ⇒ Buffer name (can be specified multiple times)
  • -r, --raw ⇒ Use raw output
  • -l, --lines ⇒ Read input as JSON Lines
  • -d, --debug ⇒ Debug mode (Default: KCR_DEBUG, 1 for true, 0 for false)
  • -D, --log <path> ⇒ Log path (Default: stderr)
  • -v, --version ⇒ Display version
  • -V, --version-notes ⇒ Display version notes
  • -h, --help ⇒ Show help
  • -- ⇒ Stop handling options
  • - ⇒ Stop handling options and read stdin

Commands

tldr
kcr tldr

Show usage.

prompt
kcr prompt

Print prompt. Returns 1 if no session.

init
kcr init <name>

Print functions.

init kakoune
kcr init kakoune

Print Kakoune definitions.

Example – kakrc configuration:

evaluate-commands %sh{
  kcr init kakoune
}

Kakoune commands

connect
connect <command> [arguments]

Run a command as <command> sh -c {connect} -- [arguments].

Example

connect terminal sh
run
run <command> [arguments]

Run a program in a new session.

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.

env
kcr env

Print Kakoune environment information.

Output example:

{
  "KAKOUNE_SESSION": "kanto",
  "KAKOUNE_CLIENT": "main",
  "KCR_RUNTIME": "/home/red/.local/share/kcr",
  "KCR_DEBUG": "0",
  "KCR_VERSION": "nightly"
}
play
kcr play [file]

Start playground with example.kak by default.

create
kcr create [session]

Create a new session.

attach
kcr attach [session]

Connect to session.

kill
kcr kill [session]

Kill session.

list
kcr list

List sessions.

Output example:

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

Options

  • -d, --working-directory <path> ⇒ Working directory
kcr shell [flags] [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: command]

Send commands to client at session.

Example

kcr send echo pokemon

Multiple commands

It is possible to send multiple commands in a single request with pipes.

kcr echo -- echo kanto |
kcr echo - echo johto |
kcr send --lines

Nested commands

It is possible to create nested commands with {} placeholders and pipes.

kcr echo -- evaluate-commands -draft {} |
kcr echo - execute-keys '<a-i>b' 'i<backspace><esc>' 'a<del><esc>' |
kcr send --lines

The {} denotes a block for the next pipe.

In kakspeak:

evaluate-commands -draft %{
  execute-keys '<a-i>b' 'i<backspace><esc>' 'a<del><esc>'
}
echo
kcr echo [arguments]

Print arguments.

Example

kcr echo -- echo pokemon

Output:

["echo", "pokemon"]

Example – Streaming data:

kcr echo -- evaluate-commands -draft {} |
kcr echo - execute-keys '<a-i>b' 'i<backspace><esc>' 'a<del><esc>'

Output:

["evaluate-commands", "-draft", "{}"]
["execute-keys", "<a-i>b", "i<backspace><esc>", "a<del><esc>"]

Add kcr send --lines for sending the nested command.

get

Options

  • -v, --value <name> ⇒ Value name
  • -o, --option <name> ⇒ Option name
  • -r, --register <name> ⇒ Register name
  • -s, --shell <command> ⇒ Shell command
kcr get [flags] [expansions]

Get states from a client in session.

Example

kcr get --value buflist

Output:

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

Example – Streaming data:

kcr get --option pokemon |
kcr get --option regions -

Output:

[
  "Bulbasaur",
  "Charmander",
  "Squirtle"
]
[
  "Kanto",
  "Johto"
]

Add jq --slurp to read the entire input stream into a large array.

cat
kcr cat [buffers]

Print buffer content.

Example

kcr cat

Output:

["buffer content..."]

Use the --raw flag for raw output:

kcr cat --raw
pipe
kcr pipe <program> [arguments] [input: selections]

Pipe selections to a program.

Example – Sort selections:

kcr pipe jq sort

You can also finalize with a pipe:

kcr get --value selections | jq sort | kcr pipe -
escape
kcr escape [arguments] [input: arguments]

Escape arguments.

Example

kcr escape -- evaluate-commands -client main echo pokemon

Output:

'evaluate-commands' '-client' 'main' 'echo' 'pokemon'

See also Multiple commands and Nested commands.

set-completion

Options

  • --line <value> ⇒ Line number
  • --column <value> ⇒ Column number
  • --length <value> ⇒ Length value
  • --timestamp <value> ⇒ Timestamp value
kcr set-completion [flags] <name> [input: completions]

Set completion option.

Example

# Declare a new type of completion.
declare-option completions pokemon_completions

# Install the completer.
set-option global completers option=pokemon_completions %opt{completers}

# Declare Pokémon results as JSON.
# Get the first 151 Pokémon.
declare-option str pokemon_results %sh{
  curl 'https://pokeapi.co/api/v2/pokemon?limit=151'
}

# Generate completions
define-command pokemon-generate-completions -params 5 -docstring 'pokemon-generate-completions <line> <column> <length> <timestamp> <items>' %{
  connect run sh -c %{

    echo "$5" |
    jq '[.results[] | [.name, [["info", .name]], .name]]' |
    kcr set-completion pokemon_completions --line "$1" --column "$2" --length "$3" --timestamp "$4"

  } -- %arg{@}
}

# Update completions
hook -group pokemon-completion global InsertIdle '' %{
  try %{
    # Generate the completions (header and body).
    # Execute in a “draft” context, so if we move the cursor it won’t move the “real” cursor.
    evaluate-commands -draft %{
      # Try to select the entire word before the cursor,
      # putting the cursor at the left-end of the selection.
      execute-keys 'h<a-i>w<a-;>'

      # The selection’s cursor is at the anchor point for completions,
      # and the selection covers the text the completions should replace,
      # exactly the information we need for the header item.
      pokemon-generate-completions %val{cursor_line} %val{cursor_column} %val{selection_length} %val{timestamp} %opt{pokemon_results}
    }
  } catch %{
    # This is not a place to suggest completions,
    # so clear our list of completions.
    set-option window pokemon_completions
  }
}

Direct link to the first 151 Pokémon results.

See also Intro to Kakoune completions.

help
kcr help [command]

Show help.

version
kcr version

Display version.

Extending the command-line interface

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

See the shipped commands for examples.

Environment variables

  • KAKOUNE_SESSION: Kakoune session
  • KAKOUNE_CLIENT: Kakoune client
  • KCR_RUNTIME: Location of the runtime path (Default: ../share/kcr relative to the kcr binary directory)
  • KCR_DEBUG: Specifies the debug flag (1 for true, 0 for false)

Troubleshooting

Use the -d | --debug flag or set KCR_DEBUG to write a log message in the terminal and in Kakoune if available (see the *debug* buffer).

Example – with command-line flag:

kcr --debug send -- echo pokemon

Example – with environment variable:

export KCR_DEBUG=1
kcr send -- echo pokemon

Output:

{
  "session": "kanto",
  "client": "main",
  "constructor": [["echo", "pokemon"]],
  "command": "'echo' 'pokemon'"
}