= Expansions == Strings \'strings':: uninterpreted strings, use a backslash (\') to escape the separator "strings":: expanded strings, % strings (c.f. next section) contained are expended, use a backslash (\\%) to escape the separator %\{strings\}:: these strings are very useful when entering commands * the '{' and '}' delimiters are configurable, any non alphanumeric character can be used ---------------------------------------------------------- e.g. %[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. %{ roger {}; } is a valid string, %{ marcel \} as well ----------------------------------------------------------- == Typed expansions %\{strings\} can have an expansion type between the *%* and the opening character. They will be written *%\{\}*. They will be expanded according to the given ** using ** as its parameter: *sh*:: shell expansion, similar to posix shell '$(...)' construct (c.f. next section) *reg*:: register expansion, will expand to the strings stored in the register named by **. See <> *opt*:: option expansion, will expand to the value of the option named by **. See <> *val*:: value expansion, will expand to the value of the environment variables available to shell expansion. ** shall be the name of that variable without the *kak_* prefix. *arg*:: argument expansion, expand to the arguments of the current command, ** can be a number, or @ for all arguments == Shell expansions The '%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: *kak_selection*:: content of the main selection *kak_selections*:: quoted list of the contents of the selections. *kak_selection_desc*:: range of the main selection, represented as anchor,cursor; anchor and cursor are in this format: line.column *kak_selections_desc*:: unquoted list range of the selections. *kak_bufname*:: name of the current buffer *kak_buffile*:: full path of the file or same as kak_bufname when there’s no associated file *kak_buflist*:: quoted list of the currently opened buffer names *kak_buf_line_count*:: the current buffer line count *kak_timestamp*:: timestamp of the current buffer, the timestamp is an integer value which is incremented each time the buffer is modified *kak_history_id*:: history id of the current buffer, the history id is an integer value which is used to reference a specific buffer version in the undo tree *kak_runtime*:: directory containing the kak support files, determined from kakoune's binary location. *kak_config*:: directory containing the user configuration *kak_version*:: version of the current Kakoune server (git hash or release name) *kak_count*:: count parameter passed to the command, defaults to 0 if no count given *kak_register*:: register parameter passed to the command *kak_opt_*:: value of option *name* *kak_reg_*:: quoted list of value of register *r* *kak_main_reg_*:: content of register *r* associated with the main selection. *kak_session*:: name of the current session *kak_client*:: name of the current client *kak_client_pid*:: process id of the current client *kak_client_list*:: unquoted list of the names of clients connected to the current session *kak_source*:: path of the file currently getting executed (through the source command) *kak_modified*:: buffer has modifications not saved *kak_cursor_line*:: line of the end of the main selection *kak_cursor_column*:: column of the end of the main selection (in byte) *kak_cursor_char_value*:: unicode value of the codepoint under the cursor *kak_cursor_char_column*:: column of the end of the main selection (in character) *kak_cursor_byte_offset*:: Offset of the main selection from the beginning of the buffer (in bytes). *kak_window_width*:: width of the current kakoune window *kak_window_height*:: height of the current kakoune window *kak_hook_param*:: filtering text passed to the currently executing hook *kak_hook_param_capture_N*:: text captured by the hook filter regex capture N *kak_text*:: the text entered by the user at a `prompt` command, not available in other contexts *kak_client_env_*:: value of the *name* variable in the client environment (e.g. *$kak_client_env_SHELL* is the SHELL variable) *kak_user_modes*:: unquoted list of user modes. Quoted lists are separated by spaces, and each element is surrounded by `'` with contained `'` doubled. Unquoted lists are simply separated by spaces and is used for values that will not contain whitespaces. 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. Those environment variables are available in every context where Kakoune use a shell command, such as the `|`, `!` or `$` normal mode commands (See <>). == 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 precedes a '{' character shall be escaped as well ('\\').