commands.asciidoc (22237B)
1 = Commands 2 3 Some commands take an exclamation mark (*!*), which can be used to force 4 the execution of the command (i.e. to quit a modified buffer, the 5 command *q!* has to be used). Aliases are mentioned below each command. 6 7 For all commands that accept switches, a parameter beginning with 8 a single dash (*-*) will be interpreted as a switch. Any unknown switches 9 will cause an error. To force the remaining parameters to not be interpreted as 10 switches even if they begin with a dash, you can pass two dashes (*--*) as a parameter. 11 12 *doc* <topic>:: 13 *alias* help + 14 display documentation about a topic. The completion list displays the 15 available topics 16 17 == Files and Buffers 18 19 For the following *write* commands, the *-sync* switch forces the synchronization 20 of the file onto the filesystem 21 22 *arrange-buffers* <buffer>...:: 23 Reorder the buffers in the buffers list. 24 The named buffers will be moved to the front of the buffer list, in the order 25 given. Buffers that do not appear in the parameters will remain at the 26 end of the list, keeping their current order. 27 28 *-back*::: 29 Move the named buffers to the back, rather than the front, of the buffer list. 30 31 *change-directory* [<directory>]:: 32 *alias* cd + 33 change the current directory to *directory*, or the home directory if 34 unspecified 35 36 *edit[!]* [<switches>] <filename> [<line> [<column>]]:: 37 *alias* e + 38 open buffer on file, go to given line and column. If file is already 39 opened, just switch to this file. Use edit! to force reloading 40 41 *-debug*::: 42 The new buffer (if any) will be created as a debug buffer. 43 (See <<buffers#debug-buffers,`:doc buffers debug-buffers`>>) 44 45 *-existing*::: 46 If the named file does not exist, fail instead of creating a new buffer. 47 48 *-readonly*::: 49 The new buffer (if any) will be set read-only. 50 51 *-fifo* <fifoname>::: 52 Creates a new scratch buffer named <filename>, and continually appends 53 data from the fifo (named pipe) <fifoname> as it arrives. 54 (See <<buffers#fifo-buffers,`:doc buffers fifo-buffers`>>) 55 56 *-scratch*::: 57 Creates a new buffer named <filename>, which doesn't correspond to any 58 file on disk. If no filename is given, the buffer name will be 59 generated based on format `\*scratch-$ID*`, where `$ID` is an 60 integer automatically incremented for new buffers. 61 (See <<buffers#scratch-buffers,`:doc buffers scratch-buffers`>>) 62 63 *-scroll*::: 64 If used with `-fifo`, when new data arrives Kakoune will scroll the 65 buffer down to make the new data visible. 66 Otherwise, does nothing. 67 68 69 *write[!]* [-force] [-sync] [-method <writemethod>] [<filename>]:: 70 *alias* w + 71 write buffer to <filename> or use its name if filename is not 72 given. If the file is write-protected, its permissions are temporarily 73 changed to allow saving the buffer and restored afterwards when 74 the write! command is used. 75 76 *-force*::: 77 Equivalent to `!`, allow overwiting existing files if `<filename>` 78 is given and set permissions temporarily if necessary. 79 80 *-sync*::: 81 Synchronise the filesystem after the write 82 83 *-method <writemethod>*::: 84 Enforce write method instead of relying on the `writemethod` option 85 86 `replace`:::: 87 Write to a temporary file then rename to the target file so that 88 the modification appears atomically. 89 90 `overwrite`:::: 91 Open the existing file and overwrite its content with the new 92 content. 93 94 (See <<options#builtin-options,`:doc options builtin-options`>>) 95 96 *write-all* [-sync] [-method <writemethod>]:: 97 *alias* wa + 98 write all changed buffers that are associated with a file 99 100 *quit[!]* [<exit status>]:: 101 *alias* q + 102 exit Kakoune, use quit! to force quitting even if there is some 103 unsaved buffer remaining. If specified, the client exit status 104 will be set to <exit status> 105 106 *write-quit[!]* [-sync] [-method <writemethod>] [<exit status>]:: 107 *alias* wq + 108 write current buffer and quit current client. If specified, the client 109 exit status will be set to <exit status> 110 111 *write-all-quit* [-sync] [-method <writemethod>] [<exit status>]:: 112 *alias* waq + 113 write all buffers and quit. If specified, the client exit status 114 will be set to <exit status> 115 116 *buffer* <name>:: 117 *alias* b + 118 switch to buffer <name> 119 120 *buffer-next*:: 121 *alias* bn + 122 switch to the next buffer. 123 Debug buffers are skipped. 124 (See <<buffers#debug-buffers,`:doc buffers debug-buffers`>>) 125 126 *buffer-previous*:: 127 *alias* bp + 128 switch to the previous buffer. 129 Debug buffers are skipped. 130 (See <<buffers#debug-buffers,`:doc buffers debug-buffers`>>) 131 132 *delete-buffer[!]* [<name>]:: 133 *alias* db + 134 delete current buffer or the buffer <name> if specified 135 136 *rename-buffer* [-file|-scratch] <name>:: 137 set current buffer name, if *-scratch* or *-file* is given, ensure 138 the buffer is set to the corresponding type. 139 140 *source* <filename> <param>...:: 141 execute commands in <filename> 142 parameters are available in the sourced script as `%arg{0}`, `%arg{1}`, … 143 144 == Clients and Sessions 145 146 *rename-client* <name>:: 147 set current client name 148 Client names may only contain letters, numbers, `-`, and `_`. 149 150 *rename-session* <name>:: 151 set current session name 152 153 *kill[!]* [<exit status>]:: 154 terminate the current session, all the clients as well as the server. 155 If specified, the server and clients exit status will be set to <exit status> 156 157 == Options 158 159 *declare-option* [<switches>] <type> <name> [<value>]:: 160 *alias* decl + 161 declare a new option, the -hidden switch hides the option in completion 162 suggestions (See <<options#declare-option,`:doc options declare-option`>>) 163 164 *set-option* [<switches>] <scope> <name> <value>:: 165 *alias* set + 166 change the value of an option in *scope* 167 (See <<options#set-option,`:doc options set-option`>> 168 and <<scopes#,`:doc scopes`>>) 169 170 *unset-option* <scope> <name>:: 171 *alias* unset + 172 unset the value of an option in *scope*, so the value from an outer scope 173 is used 174 (See <<options#unset-option,`:doc options unset-option`>> 175 and <<scopes#,`:doc scopes`>>) 176 177 *update-option* <scope> <name>:: 178 update the value of an option if its type supports that operation 179 (See <<options#update-option,`:doc options update-option`>> 180 and <<scopes#,`:doc scopes`>>) 181 182 == Commands and Keys 183 184 *define-command* [<switches>] <name> <command>:: 185 *alias* def + 186 define a new command (See <<declaring-new-commands,Declaring new commands>>) 187 188 *alias* <scope> <name> <command>:: 189 define a new alias named *name* in *scope* 190 (See <<aliases,Using aliases>> and <<scopes#,`:doc scopes`>>) 191 192 *complete-command* [<switches>] <name> <type> [<param>]:: 193 *alias* compl + 194 configure how a command completion works 195 (See <<configuring-command-completion,Configuring command completion>>) 196 197 *unalias* <scope> <name> [<command>]:: 198 remove an alias if its current value is the same as the one passed 199 as an optional parameter, remove it unconditionally otherwise 200 (See <<aliases,Using aliases>> and <<scopes#,`:doc scopes`>>) 201 202 *evaluate-commands* [<switches>] <command> ...:: 203 *alias* eval + 204 evaluate commands, as if they were entered in the command prompt 205 (See <<execeval#,`:doc execeval`>>) 206 207 *execute-keys* [<switches>] <key> ...:: 208 *alias* exec + 209 execute a series of keys, as if they were hit (See <<execeval#,`:doc execeval`>>) 210 211 *map* [<switches>] <scope> <mode> <key> <keys>:: 212 bind a list of keys to a combination (See <<mapping#,`:doc mapping`>> 213 and <<scopes#,`:doc scopes`>>) 214 215 *unmap* <scope> <mode> <key> [<expected>]:: 216 unbind a key combination (See <<mapping#,`:doc mapping`>> 217 and <<scopes#,`:doc scopes`>>) 218 219 *declare-user-mode* <name>:: 220 declare a new user keymap mode 221 222 *enter-user-mode* [<switches>] <name>:: 223 enable <name> keymap mode for next key 224 225 *-lock*::: 226 stay in mode until `<esc>` is pressed 227 228 *-count <count>*::: 229 Forward *count* to the underlying normal mode parameters 230 231 *-register <register>*::: 232 Forward *register* to the underlying normal mode parameters 233 234 == Hooks 235 236 *hook* [<switches>] <scope> <hook_name> <filtering_regex> <command>:: 237 execute *command* whenever a *hook_name* is triggered in *scope* 238 (See <<hooks#,`:doc hooks`>> and <<scopes#,`:doc scopes`>>) 239 240 *-group <groupname>*::: 241 Add this hook to the *groupname* group, so it can be removed by the 242 `remove-hooks` command (below) 243 or disabled with the `disabled_hooks` option 244 (see <<options#builtin-options,`:doc options builtin-options`>>). 245 246 *-once*::: 247 This hook will be automatically removed after it has been executed. 248 249 *-always*::: 250 This hook will run even while hooks are disabled. 251 See <<hooks#disabling-hooks,`:doc hooks disabling-hooks`>>. 252 253 *remove-hooks* <scope> <group>:: 254 *alias* rmhooks + 255 remove every hook in *scope* whose group matches the regex *group* 256 (See <<hooks#,`:doc hooks`>> and <<scopes#,`:doc scopes`>>) 257 258 *trigger-user-hook* <param>:: 259 trigger the `User` hook with the given *param* as filter string in 260 the current context. (See <<hooks#,`:doc hooks`>>) 261 262 == Display 263 264 *echo* [<switches>] <text>:: 265 show *text* in status line, with the following *switches*: 266 267 *-markup*::: 268 expand the markup strings in *text* (See 269 <<faces#markup-strings,`:doc faces markup-strings`>>) 270 271 *-debug*::: 272 print the given text to the `\*debug*` buffer 273 274 *-to-file* <filename>::: 275 write the given text to the given file on the host 276 filesystem. 277 278 *-to-shell-script* <script>::: 279 execute the given shell script with the given text 280 written to its standard input 281 282 *-quoting* <quoting>::: 283 define how arguments are quoted in echo output: 284 285 - *raw* (default):::: 286 just join each argument with a space 287 288 - *kakoune*:::: 289 also wrap each argument in single quotes, doubling-up 290 embedded quotes. 291 292 - *shell*:::: 293 also wrap each arguments in single quotes and escape 294 embedded quotes in a shell compatible way. 295 296 *set-face* <scope> <name> <facespec>:: 297 *alias* face + 298 define a face in *scope* 299 (See <<faces#,`:doc faces`>> and <<scopes#,`:doc scopes`>>) 300 301 *unset-face* <scope> <name>:: 302 Remove a face definition from *scope* 303 (See <<faces#,`:doc faces`>> and <<scopes#,`:doc scopes`>>) 304 305 *colorscheme* <name>:: 306 load named colorscheme + 307 Colorschemes are just `.kak` scripts that set faces. Colorschemes are searched for in `%val{config}/colors` and `%val{runtime}/colors`. + 308 (See <<faces#, `:doc faces`>> and <<expansions#, `:doc expansions`>>) 309 310 *add-highlighter* [<switches>] <highlighter_path> <highlighter_parameters> ...:: 311 *alias* addhl + 312 add a highlighter to the current window 313 (See <<highlighters#,`:doc highlighters`>>) 314 315 *remove-highlighter* <highlighter_path>:: 316 *alias* rmhl + 317 remove the highlighter whose id is *highlighter_id* 318 (See <<highlighters#,`:doc highlighters`>>) 319 320 == Helpers 321 322 Kakoune provides some helper commands that can be used to define composite 323 commands in scripts. They are also available in the interactive mode, 324 but not really useful in that context. 325 326 *prompt* [<switches>] <prompt> <command>:: 327 prompt the user for a string, when the user validates, executes the 328 command. The entered text is available in the `text` value accessible 329 through `$kak_text` in shells or `%val{text}` in commands. 330 331 The *-init <str>* switch allows setting initial content, the 332 *-password* switch hides the entered text and clears the register 333 after command execution. 334 335 The *-on-change* and *-on-abort* switches, followed by a command 336 will have this command executed whenever the prompt content changes 337 or the prompt is aborted, respectively. 338 339 Completion support can be controlled with the same switches provided 340 by the *define-command* command, see 341 <<declaring-new-commands,Declaring new commands>>. 342 343 For *-shell-script-completion* and *-shell-script-candidates* 344 completions, token_to_complete will always be 1, and the full 345 prompt content will be passed as a single token. In other words, 346 word splitting does not take place. 347 348 NOTE: The prompt is displayed in and receives input from the 349 current client context, so inside a draft context like 350 `evaluate-commands -draft`, it is invisible and only responds to 351 an `execute-keys` command in the same context. 352 353 *on-key* <command>:: 354 wait for next key from user, then execute <command>, the key is 355 available through the `key` value, accessible through `$kak_key` 356 in shells, or `%val{key}` in commands. 357 358 NOTE: The key press must come from the current client context, 359 so inside a draft context like `evaluate-commands -draft`, it only 360 responds to an `execute-keys` command in the same context. 361 362 *info* [<switches>] <text>:: 363 display text in an information box with the following *switches*: 364 365 *-anchor* <line>.<column>::: 366 print the text at the given coordinates 367 368 *-style* <style>::: 369 set the style and placement of the message box. 370 371 *menu*:::: 372 display the info next to the displayed menu, as documentation 373 for the currently selected entry. 374 375 *above*:::: 376 display the info above the given anchor 377 378 *below*:::: 379 display the info below the given anchor 380 381 *modal*:::: 382 display the info modally, and do not auto-close the 383 info or replace it with non modal info boxes. To hide 384 a modal info box, use `info -style modal` with no 385 arguments. 386 387 *-title* <text>::: 388 set the title of the message box 389 390 *-markup*::: 391 parse markup in both title (if provided) and text. (See 392 <<faces#markup-strings,`:doc faces markup-strings`>>) 393 394 NOTE: The info box is displayed in the current client context, 395 so inside a draft context like `eval -draft`, it is invisible. 396 397 *try* <commands> [catch <on_error_commands>]...:: 398 prevent an error in *commands* from aborting the whole command 399 execution, execute *on_error_commands* instead. If nothing is to be 400 done on error, the catch part can be omitted. If an error is raised 401 in the *on_error_commands*, that error is propagated, except if 402 another *catch* and *on_error_commands* parameter follows, in which 403 case those commands get executed, and so-on. During error commands, 404 the description of the last raised error is available as `$kak_error` 405 in the shell, or `%val{error}` in commands. 406 407 *nop*:: 408 does nothing, but arguments will be evaluated (e.g. shell expansion) 409 410 *fail* <text>:: 411 raise an error, uses <text> as its description 412 413 *set-register* <name> <contents>...:: 414 *alias* reg + 415 set register *name* to *content*, each content parameter is assigned to 416 a different string in the register. (See <<registers#,`:doc registers`>>) 417 418 *select* [<switches>] <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>...:: 419 replace the current selections with the ones described in the arguments 420 421 *-timestamp* <timestamp>::: 422 specify which buffer timestamp those coordinates apply to. Uses current 423 buffer timestamp if not specified. 424 425 *-codepoint*:: 426 provided columns are to be interpreted as codepoint counts, not byte counts. 427 428 *-display-column*:: 429 provided columns are to be interpreted as display column counts, not byte counts. 430 431 both *-codepoint* and *-display-column* are only valid if *-timestamp* 432 matches the current buffer timestamp (or is not specified). 433 434 *debug* {info,buffers,options,memory,shared-strings,profile-hash-maps,faces,mappings}:: 435 print some debug information in the `\*debug*` buffer 436 437 == Module commands 438 439 In Kakoune, modules are a grouping of stored commands to be executed the first time 440 they are needed. This allows complex configurations to be evaluated lazily, and allows 441 plugins to ensure their dependencies have been loaded before they execute. The builtin 442 filetype handling for Kakoune is implemented via modules. 443 444 *provide-module* [<switches>] <name> <commands>:: 445 declares a module *name* that is defined by *commands*. *commands* will be 446 evaluated as if by source the first time *require-module <name>* is run. 447 448 *-override*::: 449 allow the module to replace an existing one with the same name. Fails if 450 the module has already been evaluated. 451 452 *require-module* <name>:: 453 guarantees the commands associated with *name* have been evaluated before 454 continuing command execution. Fails if *name* has not been defined by a 455 *provide-module* command. Does nothing if the associated commands have 456 already been evaluated. 457 458 == Multiple commands 459 460 Commands (c.f. previous sections) can be chained, by being separated either 461 by new lines or by semicolons, as such a semicolon must be escaped with a 462 backslash (\;) to be considered as a literal semicolon argument. 463 464 To avoid trouble while writing `map` or `execute-keys` commands in scripts, 465 the alternative key namings `<semicolon>` and `<a-semicolon>` can be used. 466 467 == Declaring new commands 468 469 New commands can be defined using the *define-command* command: 470 471 *define-command* [<switches>] <command_name> <commands>:: 472 *commands* is a string containing the commands to execute, and *switches* 473 can be any combination of the following parameters: 474 475 *-params* <num>::: 476 the command accepts a *num* parameter, which can be either a number, 477 or of the form <min>..<max>, with both <min> and <max> omittable 478 479 *-override*::: 480 allow the new command to replace an existing one with the same name 481 482 *-hidden*::: 483 do not show the command in command name completions 484 485 *-docstring*::: 486 define the documentation string for the command 487 488 *-menu*::: 489 *-file-completion*::: 490 *-client-completion*::: 491 *-buffer-completion*::: 492 *-command-completion*::: 493 *-shell-completion*::: 494 *-shell-script-completion*::: 495 *-shell-script-candidates*::: 496 old-style command completion specification, function as-if 497 the switch and its eventual parameter was passed to the 498 *complete-command* command 499 (See <<configuring-command-completion,Configuring command completion>>) 500 501 The use of those switches is discouraged in favor of the 502 *complete-command* command. 503 504 Using shell expansion allows defining complex commands or accessing 505 Kakoune's state: 506 507 --------------------------------------------------------------------- 508 # create a directory for current buffer if it does not exist 509 define-command mkdir %{ nop %sh{ mkdir -p $(dirname $kak_buffile) } } 510 --------------------------------------------------------------------- 511 512 == Configuring command completion 513 514 Command completion can be configured with the *complete-command* command: 515 516 *complete-command* [<switches>] <command_name> <completion_type> [<parameter>]:: 517 *switches* can be: 518 519 *-menu*::: 520 the suggestions generated by the completion options are the only 521 permitted parameters. Kakoune will autoselect the best completion 522 candidate on command validation. 523 524 *completion_type* can be: 525 526 *file*::: 527 try file completion on any parameter passed to the command 528 529 *client*::: 530 try client name completion on any parameter passed to the command 531 532 *buffer*::: 533 try buffer name completion on any parameter passed to the command 534 535 *command*::: 536 try command completion on any parameter passed to the command 537 538 *shell*::: 539 try shell command completion on any parameter passed to the command 540 541 *shell-script*::: 542 following string is a shell command which takes parameters as 543 positional params and outputs one completion candidate per line. 544 The provided shell command will run after each keypress. 545 During the execution of the shell command, the following env vars are 546 available: 547 548 *$kak_token_to_complete*:::: 549 Index of the token being completed in the command line. 550 Note that unlike the Unix `argv` tradition, 551 0 is the first argument, not the command name itself. 552 553 *$kak_pos_in_token*:::: 554 Position of the cursor inside the token being completed, in bytes 555 from token start. 556 557 *shell-script-candidates*::: 558 following string is a shell script which takes parameters as 559 positional params and outputs one completion candidate per line. 560 The provided shell script will run once at the beginning of each 561 completion session, candidates are cached and then used by kakoune 562 internal fuzzy engine. 563 564 During the execution of the shell script, the following env vars are 565 available: 566 567 *$kak_token_to_complete*:::: 568 Index of the token being completed in the command line. 569 Note that unlike the Unix `argv` tradition, 570 0 is the first argument, not the command name itself. 571 572 == Aliases 573 574 With `:alias`, commands can be given additional names. 575 As aliases are intended to be used interactively most of the time, 576 they are often short. For example `:reg` is an alias for `:set-register`. 577 578 They are scoped, so that an alias can refer to one command for a buffer, 579 and to another for another buffer. For instance `:next` could be an alias 580 for `grep-next-match` in a `*grep*` buffer while pointing to 581 `:make-next-error` in a `*make*` buffer. 582 583 The following command defines `<alias>` as an alias for `<command>`: 584 585 -------------------------------- 586 :alias <scope> <alias> <command> 587 -------------------------------- 588 589 `<scope>` can be one of `global`, `buffer` or `window`. 590 591 ------------------------------------- 592 :unalias <scope> <alias> [<expected>] 593 ------------------------------------- 594 595 Will remove the given alias in the given scope. If `<expected>` is specified 596 the alias will only be removed if its current value is `<expected>`. 597