kakoune/doc/manpages/expansions

.TH KAKOUNE 1 "" "" "EXPANSIONS"

.SS Strings
.TP
.BR 'strings'
uninterpreted strings, use a backslash (\\') to escape the separator
.TP
.BR "strings"
expanded strings, % strings (c.f. next section) contained are expended, use a backslash (\\%) to escape the separator
.TP
.BR %{strings}
these strings are very useful when entering commands the
.IR { " and " }
delimiters are configurable, you can use any non alphanumeric character
e.g. %[string], %<string>, %(string), %~string~, %!string!
if the character following '%' is one of '{[(<', then the closing one is the matching '}])>' and the delimiters are not escapable but are nestable
e.g.
.IR %{\ roger\ {};\ } " is a valid string

.SS Typed expansions
.TP
.BR sh
shell expansion, similar to posix shell $(…) construct (c.f. next section)
.TP
.BR reg
register expansion, will be replaced by the content of the given register
.TP
.BR opt
option expansion, will be replaced with the value of the given option
.TP
.BR val
value expansion, gives access to the environment variable available to the Shell expansion. The kak_ prefix is not used there
.TP
.BR arg
argument expansion, gives access to the arguments of the current command, the content can be a number, or @ for all arguments

.SS Shell expansions
The
.IR %sh{…}
expansion replaces its content with the output of the shell commands in it. The following environment variables are used to pass informations about Kakoune's state:

.TP
.BR kak_selection
content of the main selection
.TP
.BR kak_selections
content of the selection separated by colons, colons in the selection contents are escapted with a backslash.
.TP
.BR kak_selection_desc
range of the main selection, represented as anchor,cursor; anchor and cursor are in this format: line.column
.TP
.BR kak_selections_desc
range of the selecations separated by colons
.TP
.BR kak_bufname
name of the current buffer
.TP
.BR kak_buffile
full path of the file or same as kak_bufname when there’s no associated file
.TP
.BR kak_buflist
the current buffer list, each buffer seperated by a colon
.TP
.BR kak_timestamp
timestamp of the current buffer, the timestamp is an integer value which is incremented each time the buffer is modified.
.TP
.BR kak_runtime
directory containing the kak binary
.TP
.BR kak_opt_<name>
value of option
.IR <name>
.TP
.BR kak_reg_<r>
value of register
.IR <r>
.TP
.BR kak_socket
filename of session socket (/tmp/kak-<session>)
.TP
.BR kak_session
name of the current session
.TP
.BR kak_client
name of current client
.TP
.BR kak_cursor_line
line of the end of the main selection
.TP
.BR kak_cursor_column
column of the end of the main selection (in byte)
.TP
.BR kak_cursor_char_column
column of the end of the main selection (in character)
.TP
.BR kak_window_width
width of the current kakoune window
.TP
.BR kak_window_height
height of the current kakoune window
.TP
.BR kak_hook_param
filtering text passed to the currently executing hook
.TP
.BR kak_client_env_<name>
value of the
.IR <name>
variable in the client environment (e.g. $kak_client_env_SHELL is the SHELL variable)

Note that in order for Kakoune to pass a value in the environment, the variable has to be spelled out within the body of the expansion

.SS Markup strings
In certain contexts, Kakoune can take a markup string, which is a string containing formatting informations.
In these strings, the {facename} syntax will enable the face facename until another face gets activated, or the end of the string is reached.
Literal '{' characters shall be written '\\{', and a literal backslash ('\\') that preceeds a '{' character shall be escaped as well ('\\\\')