kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

expansions.asciidoc (16789B)


      1 = Expansions
      2 
      3 While parsing a command (see <<command-parsing#,`:doc command-parsing`>>),
      4 Kakoune recognises certain patterns and will replace them with their
      5 associated value before executing the command. These patterns are called
      6 expansions.
      7 
      8 Every expansion consists of a `%`, followed by the expansion _type_ (one
      9 or more alphabetic characters), a quoting character, and then all the text
     10 up to and including its matching character.
     11 
     12 If a nestable punctuation character (`(`, `[`, `{`, or `<`) is used as the
     13 opening quoting character, the expansion will end at its matching opposite
     14 (`)`, `]`, `}`, or `>`). Nested pairs of the braces used in the expansion are
     15 allowed, but they must be balanced. Braces other than the ones used in the
     16 expansion need not be balanced, however. For example, `%{nest{ed} non[nested}`
     17 is valid and expands to `nest{ed} non[nested`.
     18 
     19 If any other character is used, the expansion will end at the next occurrence of
     20 that character. The quoting character can be escaped inside the expansion if it
     21 is doubled-up. For example, `%|abc||def|` expands to the text `abc|def`.
     22 
     23 It doesn't matter which character is used, but `{}` are most common.
     24 
     25 There are 2 types of quoting which can be used to group together words separated
     26 by whitespace into a single argument or prevent expansions from expanding:
     27 
     28 "double quoted strings"::
     29     Double quoted strings are mainly for grouping multiple `%` expansions or
     30     `%` expansions and regular text as a single argument. `%` and `"` can be
     31     escaped by doubling the characters (i.e. `%%` and `""`).
     32 
     33 'single quoted strings'::
     34     Expansions are not processed inside single quoted strings. Single quotes can
     35     be escaped by doubling up (i.e. `''`).
     36 
     37 Expansions are processed when unquoted and anywhere inside double-quoted
     38 strings, but not inside unquoted words, inside single-quoted strings, or
     39 inside %-strings or other expansions (see
     40 <<command-parsing#typed-expansions, `:doc command-parsing typed-expansions`>>
     41 for full details). For example:
     42 
     43 * `echo %val{session}` echoes the current session ID
     44 
     45 * `echo x%val{session}x` echoes the literal text `x%val{session}x`
     46 
     47 * `echo '%val{session}'` echoes the literal text `%val{session}`
     48 
     49 * `echo "x%val{session}x"` echoes the current session ID, surrounded by `x`
     50 
     51 * `echo %{%val{session}}` echoes the the literal text `%val{session}`
     52 
     53 * `echo %sh{ echo %val{session} }` echoes the literal text `%val{session}`
     54 
     55 Like "variable expansion" and "command substitution" in shell programming,
     56 Kakoune expansions can expand to multiple "words" - that is, separate
     57 arguments on the resulting command-line. However, unlike shell programming,
     58 Kakoune expansions cannot _accidentally_ expand to multiple words because they
     59 contain whitespace or other special characters. Only expansions which
     60 semantically contain a list of values (list-type options, registers, selections,
     61 etc.) expand to multiple arguments. While in shell-programming it's good
     62 practice to always wrap expansions in double-quotes, in Kakoune it's perfectly
     63 safe to leave expansions unquoted.
     64 
     65 == Argument expansions
     66 
     67 Expansions with the type `arg` can only be used inside the "commands" parameter
     68 of the `define-command` command (See <<commands#declaring-new-commands,`:doc
     69 commands declaring-new-commands`>>).
     70 
     71 The following expansions are available:
     72 
     73 *%arg{n}*::
     74      (where _n_ is a decimal number) +
     75      expands to argument number _n_ of the current command
     76 
     77 *%arg{@}*::
     78     expands to all the arguments of the current command, as individual words
     79 
     80 == Option expansions
     81 
     82 Expansions with the type `opt` expand to the value associated with the named
     83 option in the current scope (See <<options#,`:doc options`>>).
     84 
     85 For example, `%opt{BOM}` expands to `utf8` or to `none`, according to the
     86 current state of the `BOM` option.
     87 
     88 == Register expansions
     89 
     90 Expansions with the type `reg` expand to the contents of the named
     91 register. For registers named after symbols (like the search register
     92 `/`), the expansion can use either the symbol or the alphabetic name (See
     93 <<registers#,`:doc registers`>>).
     94 
     95 For example, `%reg{/}` expands to the content of the `/` register, and so does
     96 `%reg{slash}`.
     97 
     98 == Shell expansions
     99 
    100 Expansions with the type `sh` are executed as shell-scripts, and whatever
    101 the script prints to standard output replaces the expansion. For example,
    102 the command `echo %sh{date}` will echo the output of the `date` command.
    103 
    104 Kakoune will block user input until the script is complete. If you want to
    105 run a process in the background, note that Kakoune will also wait for the
    106 script's stdout and stderr to be closed. You can redirect stdout and stderr
    107 of your long running background process to avoid blocking.
    108 
    109 TIP: If a shell expansion writes to standard error, that output is appended to
    110 Kakoune's `\*debug*` buffer. If you're trying to debug a shell expansion,
    111 check the debug buffer with `:buffer \*debug*` to see if anything shows up.
    112 
    113 Because Kakoune does not expand expansions inside the text of an expansion,
    114 you can't use normal expansions inside `%sh{}`. Instead, Kakoune can export
    115 expansions as environment variables to make them available to the shell.
    116 Here's how expansion patterns map to variable names:
    117 
    118 *%arg{n}*::
    119     (where _n_ is a decimal number) +
    120     becomes `$_n_`. For example, `%arg{3}` becomes `$3`.
    121 
    122 *%arg{@}*::
    123     becomes `$@`
    124 
    125 *%opt{x}*::
    126     becomes `$kak_opt_x`
    127 
    128 *%reg{x}*::
    129     (where _x_ is the alphabetic name of a register) +
    130     `$kak_reg_x` contains all the selections in register _x_ +
    131     `$kak_main_reg_x` contains only the main selection
    132 
    133 *%val{x}*::
    134     becomes `$kak_x`
    135 
    136 Values can be quoted with a shell compatible quoting by using `$kak_quoted_`
    137 as a prefix, this is mostly useful for list-type options and registers, as
    138 it allows to correctly work with lists where elements might contains
    139 whitespaces:
    140 
    141 ----
    142 eval set -- "$kak_quoted_selections"
    143 while [ $# -gt 0 ]; do
    144     # ... do a thing with $1 ...
    145     shift
    146 done
    147 ----
    148 
    149 The `eval` command will take the expanded `$kak_quoted_selections`
    150 and unquote them, then execute the resulting `set` command, which sets
    151 the shell's argument variables to the items from `$kak_selections`. The
    152 `while` loop with `shift` iterates through the arguments one by one.
    153 
    154 Only variables actually mentioned in the body of the shell expansion or
    155 in passed arguments will be exported into the shell's environment.
    156 
    157 For example:
    158 
    159 ----
    160 echo %sh{ env | grep ^kak_ }
    161 ----
    162 
    163 ... will not find any of Kakoune's special environment variables, but:
    164 
    165 ----
    166 echo %sh{ env | grep ^kak_ # kak_session }
    167 ----
    168 
    169 ... will find the `$kak_session` variable because it was mentioned by name
    170 in a comment, even though it wasn't directly used.
    171 
    172 ----
    173 define-command -params .. eval-shell %{ echo %sh{ eval "$@" } }
    174 eval-shell 'echo $kak_session'
    175 ----
    176 
    177 ... will also find the `$kak_session` variable because it was mentioned by name
    178 in the command arguments, which are automatically made available to shell blocks
    179 as "$@"
    180 
    181 TIP: These environment variables are also available in other contexts where
    182 Kakoune uses a shell command, such as the `|`, `!` or `$` normal mode commands
    183 (See <<keys#,`:doc keys`>>).
    184 
    185 === Command and Response fifo
    186 
    187 Inside shell expansions, `$kak_command_fifo` refers to a named pipe that
    188 accepts Kakoune commands to be executed as soon as the fifo is closed. This
    189 named pipe can be opened and closed multiple times which makes it possible
    190 to interleave shell and Kakoune commands. `$kak_response_fifo` refers to
    191 a named pipe that can be used to return data from Kakoune.
    192 
    193 ----
    194 %sh{
    195     echo "write $kak_response_fifo" > $kak_command_fifo
    196     content="$(cat $kak_response_fifo)"
    197 }
    198 ----
    199 
    200 This also makes it possible to pass data bigger than the system environment
    201 size limit.
    202 
    203 == File expansions
    204 
    205 Expansions with the type `file` will expand to the content of the filename
    206 given in argument as read from the host filesystem.
    207 
    208 For example, this command stores the entire content of `/etc/passwd` into the
    209 `a` register.
    210 
    211 ----
    212 set-register a %file{/etc/passwd}
    213 ----
    214 
    215 == Value expansions
    216 
    217 Expansions with the type `val` give access to Kakoune internal data that is
    218 not stored in an option or a register. Some value expansions can only be used
    219 in certain contexts, like `%val{hook_param}` that expands to the parameter
    220 string of the currently-executing hook, and is not available outside a hook.
    221 
    222 The following expansions are supported (with required context _in italics_):
    223 
    224 *%val{buffile}*::
    225     _in buffer, window scope_ +
    226     full path of the file or same as `%val{bufname}` when there’s no
    227     associated file
    228 
    229 *%val{buf_line_count}*::
    230     _in buffer, window scope_ +
    231     number of lines in the current buffer
    232 
    233 *%val{buflist}*::
    234     list of the names of currently-open buffers (as seen in %val{bufname})
    235 
    236 *%val{bufname}*::
    237     _in buffer, window scope_ +
    238     name of the current buffer
    239 
    240 *%val{client_env_X}*::
    241     _in window scope_ +
    242     value of the `$X` environment variable in the client displaying the current
    243     window (e.g. `%val{client_env_SHELL}` is `$SHELL` in the client's
    244     environment)
    245 
    246 *%val{client_list}*::
    247     unquoted list of the names of clients (as seen in `%val{client}`)
    248     connected to the current session
    249 
    250 *%val{client}*::
    251     _in window scope_ +
    252     name of the client displaying the current window
    253 
    254 *%val{client_pid}*::
    255     _in window scope_ +
    256     process id of the client displaying the current window
    257 
    258 *%val{config}*::
    259     directory containing the user configuration
    260 
    261 *%val{count}*::
    262     _in `map` command <keys> parameter and `<a-;>` from object menu_ +
    263     current count when the mapping was triggered, defaults to 0 if no
    264     count given
    265 
    266 *%val{cursor_byte_offset}*::
    267     _in window scope_ +
    268     offset of the main cursor from the beginning of the buffer (in bytes)
    269 
    270 *%val{cursor_char_column}*::
    271     _in window scope_ +
    272     1-based offset from the start of the line to the cursor position in
    273     Unicode codepoints, which may differ from visible columns if the document
    274     contains full-width codepoints (which occupy two columns) or zero-width
    275     codepoints
    276 
    277 *%val{cursor_display_column}*::
    278     _in window scope_ +
    279     1-based offset from the start of the line to the cursor position in
    280     display column, taking into account tabs and character width.
    281 
    282 *%val{cursor_char_value}*::
    283     _in window scope_ +
    284     unicode value of the codepoint under the main cursor
    285 
    286 *%val{cursor_column}*::
    287     _in window scope_ +
    288     1-based offset from the start of the line to the first byte of the
    289     character under the main cursor (in bytes), the fourth component of
    290     `%val{selection_desc}`
    291 
    292 *%val{cursor_line}*::
    293     _in window scope_ +
    294     line of the main cursor, the third component of `%val{selection_desc}`
    295 
    296 *%val{error}*::
    297     _in `try` command's <on_error_commands> parameter_ +
    298     the text of the error that cancelled execution of the <commands> parameter
    299     (or the previous <on_error_commands> parameter)
    300 
    301 *%val{history}*::
    302     _in buffer, window scope_ +
    303     the full change history of the buffer, including undo forks, in terms
    304     of `parent committed redo_child modification0 modification1 ...`
    305     entries, where _parent_ is the index of the entry's predecessor (entry
    306     0, which is the root of the history tree, will always have `-` here),
    307     _committed_ is a count in seconds from Kakoune's steady clock's epoch
    308     of the  creation of the history entry, _redo_child_ is the index of the
    309     child which will be visited for `U` (always `-` at the leaves of the
    310     history), and each _modification_ is presented as in
    311     `%val{uncommitted_modifications}`.
    312 
    313 *%val{history_since_id}*::
    314     _in buffer, window scope_ +
    315     a partial history of the buffer in the same format as `%val{history}`
    316     starting after entry _id_
    317 
    318 *%val{history_id}*::
    319     _in buffer, window scope_ +
    320     history id of the current buffer, an integer value which refers to a
    321     specific buffer version in the undo tree (see also `%val{timestamp}`)
    322 
    323 *%val{hook_param_capture_n}*::
    324     _in `hook` command <command> parameter_ +
    325     text captured by capture group _n_, if the executing hook's filter regex
    326     used capture groups
    327 
    328 *%val{hook_param}*::
    329     _in `hook` command <command> parameter_ +
    330     the complete parameter string of the executing hook
    331 
    332 *%val{modified}*::
    333     _in buffer, window scope_ +
    334     `true` if the buffer has modifications not saved, otherwise `false`
    335 
    336 *%val{object_flags}*::
    337     _for commands executed from the object menu's `<a-;>` only_ +
    338     a pipe-separted list of words including `inner` if the user wants
    339     an inner selection, `to_begin` if the user wants to select to the
    340     beginning, and `to_end` if the user wants to select to the end
    341 
    342 *%val{recording_register}*::
    343     the register being recorded to if currently recording a macro, empty when not recording
    344 
    345 *%val{register}*::
    346     _in `map` command <keys> parameter and `<a-;>` from the object menu_ +
    347     current register when the mapping was triggered
    348 
    349 *%val{runtime}*::
    350     the directory containing the kak support files, which is determined from
    351     Kakoune's binary location if `$KAKOUNE_RUNTIME` is not set
    352 
    353 *%val{select_mode}*::
    354     _for commands executed from the object menu's `<a-;>` only_ +
    355     `replace` if the new selection should replace the existing, `extend`
    356     otherwise
    357 
    358 *%val{selection}*::
    359     _in window scope_ +
    360     content of the main selection
    361 
    362 *%val{selections}*::
    363     _in window scope_ +
    364     quoted list of the contents of all selections
    365 
    366 *%val{selection_desc}*::
    367     _in window scope_ +
    368     range of the main selection, represented as `a.b,c.d` where _a_ is the
    369     anchor line, _b_ is the number of bytes from the start of the line to the
    370     anchor, _c_ is the cursor line (like `%val{cursor_line}`), _d_ is
    371     the number of bytes from the start of the line to the cursor (like
    372     `%val{cursor_column}`), and all are 1-based decimal integers
    373 
    374 *%val{selections_char_desc}*::
    375     _in window scope_ +
    376     unquoted list of the ranges of all selections, in the same format as
    377     `%val{selection_desc}`, except that the columns are in codepoints rather
    378     than bytes
    379 
    380 *%val{selections_display_column_desc}*::
    381     _in window scope_ +
    382     unquoted list of the ranges of all selections, in the same format as
    383     `%val{selection_desc}`, except that the columns are in display columns rather
    384     than bytes
    385 
    386 *%val{selections_desc}*::
    387     _in window scope_ +
    388     unquoted list of the ranges of all selections, in the same format as
    389     `%val{selection_desc}`
    390 
    391 *%val{selection_length}*::
    392     _in window scope_ +
    393     length (in codepoints) of the main selection
    394 
    395 *%val{selections_length}*::
    396     _in window scope_ +
    397     unquoted list of the lengths (in codepoints) of the selections
    398 
    399 *%val{selection_count}*::
    400     _in window scope_ +
    401     the number of selections
    402 
    403 *%val{session}*::
    404     name of the current session
    405 
    406 *%val{source}*::
    407     _in `.kak` file_ +
    408     path of the file currently getting executed (through the source command)
    409 
    410 *%val{text}*::
    411     _in `prompt` command <command> parameter_ +
    412     the text entered by the user in response to the `prompt` command
    413 
    414 *%val{timestamp}*::
    415     _in buffer, window scope_ +
    416     timestamp of the current buffer, an integer that increments each time the
    417     buffer is modified, including undoing and redoing previous modifications
    418     (see also `%val{history_id}`)
    419 
    420 *%val{uncommitted_modifications}*::
    421     _in buffer, window scope_ +
    422     a list of quoted insertions (in the format `+line.column|text`) and
    423     deletions (`-line.column|text`) not yet saved to the history (e.g. typing
    424     in insert mode before pressing `<esc>`), where _line_ is the 1-based line
    425     of the change, _column_ is the 1-based _byte_ of the change start (see
    426     `%val{cursor_column}`), and _text_ is the content of the insertion or
    427     deletion (see also `%val{history}`)
    428 
    429 *%val{user_modes}*::
    430     unquoted list of user modes.
    431 
    432 *%val{version}*::
    433     version of the current Kakoune server (git hash or release name)
    434 
    435 *%val{window_height}*::
    436     _in window scope_ +
    437     height of the current Kakoune window
    438 
    439 *%val{window_width}*::
    440     _in window scope_ +
    441     width of the current Kakoune window
    442 
    443 *%val{window_range}*::
    444     _in window scope_ +
    445     list of coordinates and dimensions of the buffer-space
    446     available on the current window, in the following format:
    447     `<coord_y> <coord_x> <height> <width>`
    448 
    449 Values in the above list that do not mention a context are available
    450 everywhere.
    451 
    452 A value described as a "quoted list" will follow the rules of Kakoune string
    453 quoting (See <<command-parsing#,`:doc command-parsing`>>). An "unquoted list"
    454 cannot contain any special characters that would require quoting.
    455 
    456 == Recursive Expansions
    457 
    458 Expansions with the type `exp` expand their content, the same way doubly
    459 quoted strings do except that double quotes don't need to be escaped.