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.