expansions.asciidoc

Expansions

While parsing a command (see :doc command-parsing), Kakoune recognises certain patterns and will replace them with their associated value before executing the command. These patterns are called expansions.

Every expansion consists of a %, followed by the expansion type (one or more alphabetic characters), a quoting character, and then all the text up to and including its matching character.

If a nestable punctuation character ((, [, {, or <) is used as the opening quoting character, the expansion will end at its matching opposite (), ], }, or >). Nested pairs of the braces used in the expansion are allowed, but they must be balanced. Braces other than the ones used in the expansion need not be balanced, however. For example, %{nest{ed} non[nested} is valid and expands to nest{ed} non[nested.

If any other character is used, the expansion will end at the next occurrence of that character. The quoting character can be escaped inside the expansion if it is doubled-up. For example, %|abc||def| expands to the text abc|def.

It doesn’t matter which character is used, but {} are most common.

There are 2 types of quoting which can be used to group together words separated by whitespace into a single argument or prevent expansions from expanding:

"double quoted strings"

Double quoted strings are mainly for grouping multiple % expansions or % expansions and regular text as a single argument. % and " can be escaped by doubling the characters (i.e. %% and "").

'single quoted strings'

Expansions are not processed inside single quoted strings. Single quotes can be escaped by doubling up (i.e. '').

Expansions are processed when unquoted and anywhere inside double-quoted strings, but not inside unquoted words, inside single-quoted strings, or inside %-strings or other expansions (see :doc command-parsing typed-expansions for full details). For example:

• echo %val{session} echoes the current session ID

• echo x%val{session}x echoes the literal text x%val{session}x

• echo '%val{session}' echoes the literal text %val{session}

• echo "x%val{session}x" echoes the current session ID, surrounded by x

• echo %{%val{session}} echoes the the literal text %val{session}

• echo %sh{ echo %val{session} } echoes the literal text %val{session}

Like "variable expansion" and "command substitution" in shell programming, Kakoune expansions can expand to multiple "words" - that is, separate arguments on the resulting command-line. However, unlike shell programming, Kakoune expansions cannot accidentally expand to multiple words because they contain whitespace or other special characters. Only expansions which semantically contain a list of values (list-type options, registers, selections, etc.) expand to multiple arguments. While in shell-programming it’s good practice to always wrap expansions in double-quotes, in Kakoune it’s perfectly safe to leave expansions unquoted.

Argument expansions

Expansions with the type arg can only be used inside the "commands" parameter of the define-command command (See :doc commands declaring-new-commands).

The following expansions are available:

%arg{n}

(where n is a decimal number)
expands to argument number n of the current command

%arg{@}

expands to all the arguments of the current command, as individual words

Option expansions

Expansions with the type opt expand to the value associated with the named option in the current scope (See :doc options).

For example, %opt{BOM} expands to utf8 or to none, according to the current state of the BOM option.

Register expansions

Expansions with the type reg expand to the contents of the named register. For registers named after symbols (like the search register /), the expansion can use either the symbol or the alphabetic name (See :doc registers).

For example, %reg{/} expands to the content of the / register, and so does %reg{slash}.

Shell expansions

Expansions with the type sh are executed as shell-scripts, and whatever the script prints to standard output replaces the expansion. For example, the command echo %sh{date} will echo the output of the date command.

Tip	If a shell expansion writes to standard error, that output is appended to Kakoune’s *debug* buffer. If you’re trying to debug a shell expansion, check the debug buffer with :buffer *debug* to see if anything shows up.

Because Kakoune does not expand expansions inside the text of an expansion, you can’t use normal expansions inside %sh{}. Instead, Kakoune can export expansions as environment variables to make them available to the shell. Here’s how expansion patterns map to variable names:

%arg{n}

(where n is a decimal number)
becomes $n. For example, %arg{3} becomes $3.

%arg{@}

becomes $@

%opt{x}

becomes $kak_opt_x

%reg{x}

(where x is the alphabetic name of a register)
$kak_reg_x contains all the selections in register x
$kak_main_reg_x contains only the main selection

%val{x}

becomes $kak_x

Values can be quoted with a shell compatible quoting by using $kak_quoted_ as a prefix, this is mostly useful for list-type options and registers, as it allows to correctly work with lists where elements might contains whitespaces:

eval set -- "$kak_quoted_selections"
while [ $# -gt 0 ]; do
    # ... do a thing with $1 ...
    shift
done

The eval command will take the expanded $kak_quoted_selections and unquote them, then execute the resulting set command, which sets the shell’s argument variables to the items from $kak_selections. The while loop with shift iterates through the arguments one by one.

Only variables actually mentioned in the body of the shell expansion or in passed arguments will be exported into the shell’s environment.

For example:

echo %sh{ env | grep ^kak_ }

1. will not find any of Kakoune’s special environment variables, but:

echo %sh{ env | grep ^kak_ # kak_session }

1. will find the $kak_session variable because it was mentioned by name in a comment, even though it wasn’t directly used.

define-command -params .. eval-shell %{ echo %sh{ eval "$@" } }
eval-shell 'echo $kak_session'

1. will also find the $kak_session variable because it was mentioned by name in the command arguments, which are automatically made available to shell blocks as "$@"

Tip	These environment variables are also available in other contexts where Kakoune uses a shell command, such as the |, ! or $ normal mode commands (See :doc keys).

Command and Response fifo

Inside shell expansions, $kak_command_fifo refers to a named pipe that accepts Kakoune commands to be executed as soon as the fifo is closed. This named pipe can be opened and closed multiple times which makes it possible to interleave shell and Kakoune commands. $kak_response_fifo refers to a named pipe that can be used to return data from Kakoune.

%sh{
    echo "write $kak_response_fifo" > $kak_command_fifo
    content="$(cat $kak_response_fifo)"
}

This also makes it possible to pass data bigger than the system environment size limit.

File expansions

Expansions with the type file will expand to the content of the filename given in argument as read from the host filesystem.

For example, this command stores the entire content of /etc/passwd into the a register.

set-register a %file{/etc/passwd}

Value expansions

Expansions with the type val give access to Kakoune internal data that is not stored in an option or a register. Some value expansions can only be used in certain contexts, like %val{hook_param} that expands to the parameter string of the currently-executing hook, and is not available outside a hook.

The following expansions are supported (with required context in italics):

%val{buffile}

in buffer, window scope
full path of the file or same as %val{bufname} when there’s no associated file

%val{buf_line_count}

in buffer, window scope
number of lines in the current buffer

%val{buflist}

list of the names of currently-open buffers (as seen in %val{bufname})

%val{bufname}

in buffer, window scope
name of the current buffer

%val{client_env_X}

in window scope
value of the $X environment variable in the client displaying the current window (e.g. %val{client_env_SHELL} is $SHELL in the client’s environment)

%val{client_list}

unquoted list of the names of clients (as seen in %val{client}) connected to the current session

%val{client}

in window scope
name of the client displaying the current window

%val{client_pid}

in window scope
process id of the client displaying the current window

%val{config}

directory containing the user configuration

%val{count}

in map command <keys> parameter and <a-;> from object menu
current count when the mapping was triggered, defaults to 0 if no count given

%val{cursor_byte_offset}

in window scope
offset of the main cursor from the beginning of the buffer (in bytes)

%val{cursor_char_column}

in window scope
1-based offset from the start of the line to the cursor position in Unicode codepoints, which may differ from visible columns if the document contains full-width codepoints (which occupy two columns) or zero-width codepoints

%val{cursor_display_column}

in window scope
1-based offset from the start of the line to the cursor position in display column, taking into account tabs and character width.

%val{cursor_char_value}

in window scope
unicode value of the codepoint under the main cursor

%val{cursor_column}

in window scope
1-based offset from the start of the line to the first byte of the character under the main cursor (in bytes), the fourth component of %val{selection_desc}

%val{cursor_line}

in window scope
line of the main cursor, the third component of %val{selection_desc}

%val{error}

in try command’s <on_error_commands> parameter
the text of the error that cancelled execution of the <commands> parameter (or the previous <on_error_commands> parameter)

%val{history}

in buffer, window scope
the full change history of the buffer, including undo forks, in terms of parent committed redo_child modification0 modification1 …​ entries, where parent is the index of the entry’s predecessor (entry 0, which is the root of the history tree, will always have - here), committed is a count in seconds from Kakoune’s steady clock’s epoch of the creation of the history entry, redo_child is the index of the child which will be visited for U (always - at the leaves of the history), and each modification is presented as in %val{uncommitted_modifications}.

%val{history_id}

in buffer, window scope
history id of the current buffer, an integer value which refers to a specific buffer version in the undo tree (see also %val{timestamp})

%val{hook_param_capture_n}

in hook command <command> parameter
text captured by capture group n, if the executing hook’s filter regex used capture groups

%val{hook_param}

in hook command <command> parameter
the complete parameter string of the executing hook

%val{modified}

in buffer, window scope
true if the buffer has modifications not saved, otherwise false

%val{object_flags}

for commands executed from the object menu’s <a-;> only
a pipe-separted list of words including inner if the user wants an inner selection, to_begin if the user wants to select to the beginning, and to_end if the user wants to select to the end

%val{register}

in map command <keys> parameter and <a-;> from the object menu
current register when the mapping was triggered

%val{runtime}

the directory containing the kak support files, which is determined from Kakoune’s binary location if $KAKOUNE_RUNTIME is not set

%val{select_mode}

for commands executed from the object menu’s <a-;> only
replace if the new selection should replace the existing, extend otherwise

%val{selection}

in window scope
content of the main selection

%val{selections}

in window scope
quoted list of the contents of all selections

%val{selection_desc}

in window scope
range of the main selection, represented as a.b,c.d where a is the anchor line, b is the number of bytes from the start of the line to the anchor, c is the cursor line (like %val{cursor_line}), d is the number of bytes from the start of the line to the cursor (like %val{cursor_column}), and all are 1-based decimal integers

%val{selections_char_desc}

in window scope
unquoted list of the ranges of all selections, in the same format as %val{selection_desc}, except that the columns are in codepoints rather than bytes

%val{selections_display_column_desc}

in window scope
unquoted list of the ranges of all selections, in the same format as %val{selection_desc}, except that the columns are in display columns rather than bytes

%val{selections_desc}

in window scope
unquoted list of the ranges of all selections, in the same format as %val{selection_desc}

%val{selection_length}

in window scope
length (in codepoints) of the main selection

%val{selections_length}

in window scope
unquoted list of the lengths (in codepoints) of the selections

%val{selection_count}

in window scope
the number of selections

%val{session}

name of the current session

%val{source}

in .kak file
path of the file currently getting executed (through the source command)

%val{text}

in prompt command <command> parameter
the text entered by the user in response to the prompt command

%val{timestamp}

in buffer, window scope
timestamp of the current buffer, an integer that increments each time the buffer is modified, including undoing and redoing previous modifications (see also %val{history_id})

%val{uncommitted_modifications}

in buffer, window scope
a list of quoted insertions (in the format +line.column|text) and deletions (-line.column|text) not yet saved to the history (e.g. typing in insert mode before pressing <esc>), where line is the 1-based line of the change, column is the 1-based byte of the change start (see %val{cursor_column}), and text is the content of the insertion or deletion (see also %val{history})

%val{user_modes}

unquoted list of user modes.

%val{version}

version of the current Kakoune server (git hash or release name)

%val{window_height}

in window scope
height of the current Kakoune window

%val{window_width}

in window scope
width of the current Kakoune window

%val{window_range}

in window scope
list of coordinates and dimensions of the buffer-space available on the current window, in the following format: <coord_y> <coord_x> <height> <width>

Values in the above list that do not mention a context are available everywhere.

A value described as a "quoted list" will follow the rules of Kakoune string quoting (See :doc command-parsing). An "unquoted list" cannot contain any special characters that would require quoting.

Recursive Expansions

Expansions with the type exp expand their content, the same way doubly quoted strings do except that double quotes don’t need to be escaped.