--- name: "kak_commands" section: "1" platform: "linux" package: "kakoune" version: "0~2016.12.20.1.3a6167ae-1" release: "Debian 9 (Stretch)" platforms: ["linux"] url: "https://new.carta.tech/kak_commands" --- # kak\_commands(1) a ## NAME commands - a ## PRIMITIVES Some commands take an exclamation mark (**!**), which can be used to force the execution of the command (i.e. to quit a modified buffer, the command **q!** has to be used). **cd** \[\\] change the current directory to **directory**, or the home directory if unspecified **doc** \ display documentation about a topic. The completion list displays the available topics **e\[dit\]\[!\]** \ \[\ \[\\]\] open buffer on file, go to given line and column. If file is already opened, just switch to this file. Use edit! to force reloading **w\[rite\]** \[\\] write buffer to \ or use it’s name if filename is not given **w\[rite\]a\[ll\]** write all buffers that are associated to a file **q\[uit\]\[!\]** exit Kakoune, use quit! to force quitting even if there is some unsaved buffers remaining **kill** terminate the current session, all the clients as well as the server **w\[a\]q\[!\]** write the current buffer (or all buffers when **waq** is used) and quit **b\[uffer\]** \ switch to buffer \ **b\[uffer\]n\[ext\]** switch to the next buffer **b\[uffer\]p\[rev\]** switch to the previous buffer **d\[el\]b\[uf\]\[!\]** \[\\] delete the buffer \ **source** \ execute commands in \ **runtime** \ execute commands in \, \ is relative to kak executable path **colorscheme** \ load named colorscheme **rename-client** \ set current client name **rename-buffer** \ set current buffer name **rename-session** \ set current session name **echo** \[options\] \ show **text** in status line, with the following **options**: **-color** \ print the given text with **face**, most commonly **Error** or **Information** **-markup** expand the markup strings in **text** (c.f. the *expansions* documentation page) **-debug** print the given text to the **\\\*debug**\* buffer **nop** does nothing, but arguments will be evaluated (e.g. shell expansion) **set** \ \ \ change the value of an option (c.f. the *options* documentation page), note that the name of a particular buffer can be specified when the target **scope** is *buffer*, e.g. set buffer=/path/to/buffer foo "bar"; the scope can also take the current special value, which will automatically point to the narrowest scope available in the current context **unset** \ \ unset the value of an option (c.f. the *options* documentation page) **alias** \ \ \ define a new alias, within the context of a scope **unalias** \ \ \[\\] remove an alias if its current value is the same as the one passed as an optional parameter, remove it unconditionally otherwise **declare-option** \[-hidden\] \ \ \[\\] declare a new option, the -hidden hides the option in completion suggestions (c.f. the *options* documentation page) **face** \ \ define a face (c.f. the *faces* documentation page) **exec** \[\\] \ ... execute a series of keys, as if they were hit (c.f. the *execeval* documentation page) **eval** \[\\] \ ... execute commands, as if they were entered in the command prompt (c.f. the *execeval* documentation page) **define-command** \[\\] \ \ define a new command (c.f. the *Declaring new commands* section below) **map** \ \ \ \ make **key** behave as if **keys** were typed. with **scope** being one of **global**, **buffer** or **window**, **mode** being **insert**, **normal**, **prompt**, **menu** or **user**. ``` *user* mode allows for user mapping behind the *,* key. Keys will be executed in normal mode. ``` **unmap** \ \ \ \[\\] remove the mapping of **key** in given **scope** and **mode**, if expected is specified, only remove the mapping it if matches the expected keys. **hook** \[-group \\] \ \ \ \ execute a command whenever an event is triggered (c.f. the *hooks* documentation page) **remove-hooks** \ \ remove every hooks in **scope** that are part of the given **group** (c.f. the *hooks* documentation page) **add-highlighter** \[\\] \ \ ... add a highlighter to the current window (c.f. the *highlighters* documentation page) **remove-highlighter** \ remove the highlighter whose id is **highlighter\_id** (c.f. the *highlighters* documentation page) ## HELPERS Kakoune provides some helper commands that can be used to define composite commands: **prompt** \ \ prompt the user for a string, when the user validates, executes the command. The entered text is available in the text value accessible through $kak\_text in shells or %val{text} in commands. ``` The *-init * switch allows setting initial content, the *-password* switch hides the entered text and clears the register after command execution. ``` **on-key** \ wait for next key from user, then execute \, the key is available through the key value, accessible through $kak\_key in shells, or %val{key} in commands. **menu** \ \ \ \ ... display a menu using labels, the selected label’s commands are executed. menu can take an **-auto-single** argument, to automatically run commands when only one choice is provided, and a **-select-cmds** argument, in which case menu takes three argument per item, the last one being a command to execute when the item is selected (but not validated) **info** \[options\] \ display text in an information box with the following **options**: **-anchor** \.\ print the text at the given coordinates **-placement** {above,below} set the placement relative to the anchor **-title** \ set the title of the message box **try** \ catch \ prevent an error in **commands** from aborting the whole commands execution, execute **on\_error\_commands** instead. If nothing is to be done on error, the catch part can be omitted **reg** \ \ set register **name** to **content** **select** \.\,\.\:... replace the current selections with the one described in the argument **debug** {info,buffers,options,memory,shared-strings} print some debug information in the **\\\*debug**\* buffer Note that those commands are also available in the interactive mode, but are not really useful in that context. ## MULTIPLE COMMANDS Commands (c.f. previous sections) can be chained, by being separated either by new lines or by semicolons, as such a semicolon must be escaped with a backslash (\\;) to be considered as a literal semicolon argument ## DECLARING NEW COMMANDS New commands can be defined using the **define-command** command: **define-command** \[flags\] \ \ **commands** is a string containing the commands to execute, and **flags** can be any combination of the following parameters: **-params** \ the command accepts a **num** parameter, which can be either a number, or of the form \..\, with both \ and \ omittable **-file-completion** try file completion on any parameter passed to this command **-client-completion** try client name completion on any parameter passed to this command **-buffer-completion** try buffer name completion on any parameter passed to this command **-shell-completion** following string is a shell command which takes parameters as positional params and output one completion candidate per line **-allow-override** allow the new command to replace an existing one with the same name **-hidden** do not show the command in command name completions **-docstring** define the documentation string for the command Using shell expansion allows one to define complex commands or to access Kakoune state: ``` def " print_selection %{ echo %sh{ ${kak_selection} } }" ```