KAKOUNE(1) ========== 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* <directory>:: change the current directory to the one passed *e[dit][!]* <filename> [<line> [<column>]]:: 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]* [<filename>]:: write buffer to <filename> 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]* <name>:: switch to buffer <name> *b[uffer]n[ext]*:: switch to the next buffer *b[uffer]p[rev]*:: switch to the previous buffer *d[el]b[uf][!]* [<name>]:: delete the buffer <name> *source* <filename>:: execute commands in <filename> *runtime* <filename>:: execute commands in <filename>, <filename> is relative to kak executable path *colorscheme* <name>:: load named colorscheme *nameclient* <name>:: set current client name *namebuf* <name>:: set current buffer name *namesession* <name>:: set current session name *echo* [options] <text>:: show *text* in status line, with the following *options*: *-color* <face>::: 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* <scope> <name> <value>:: change the value of an option (c.f. the 'options' documentation page) *unset* <scope> <name>:: unset the value of an option (c.f. the 'options' documentation page) *alias* <scope> <name> <command>:: define a new alias, within the context of a scope *unalias* <scope> <name> [<command>]:: remove an alias if its current value is the same as the one passed as an optional parameter, remove it unconditionally otherwise *decl* [-hidden] <type> <name> [<value>]:: declare a new option, the -hidden hides the option in completion suggestions (c.f. the 'options' documentation page) *face* <name> <facespec>:: define a face (c.f. the 'faces' documentation page) *exec* [<flags>] <key> ...:: execute a series of keys, as if they were hit (c.f. the 'execeval' documentation page) *eval* [<flags>] <command> ...:: execute commands, as if they were entered in the command prompt (c.f. the 'execeval' documentation page) *def* [<flags>] <name> <command>:: define a new command (c.f. the 'Declaring new commands' section below) *map* <scope> <mode> <key> <keys>:: 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* <scope> <mode> <key> [<expected>]:: 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 <group>] <scope> <hook_name> <filtering_regex> <command>:: execute a command whenever an event is triggered (c.f. the 'hooks' documentation page) *rmhooks* <scope> <group>:: remove every hooks in *scope* that are part of the given *group* (c.f. the 'hooks' documentation page) *addhl* [<flags>] <highlighter_name> <highlighter_parameters> ...:: add a highlighter to the current window (c.f. the 'highlighters' documentation page) *rmhl* <highlighter_id>:: 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> <register> <command>:: prompt the user for a string, when the user validates, store the result in given *register* and run *commmand*. the *-init <str>* switch allows setting initial content, the *-password* switch hides the entered text and clears the register after command execution. *onkey* <register> <command>:: wait for next key from user, writes it into given <register> and execute commands *menu* <label1> <commands1> <label2> <commands2> ...:: 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] <text>:: display text in an information box with the following *options*: *-anchor* <line>.<column>::: print the text at the given coordinates *-placement* {above,below}::: set the placement relative to the anchor *-title* <text>::: set the title of the message box *try* <commands> catch <on_error_commands>:: 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* <name> <content>:: set register *name* to *content* *select* <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>:...:: 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 *def* command: *def* [flags] <command_name> <commands>:: *commands* is a string containing the commands to execute, and *flags* can be any combination of the following parameters: *-params* <num>::: the command accepts a *num* parameter, which can be either a number, or of the form <min>..<max>, with both <min> and <max> 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 to define complex commands or to access Kakoune state: -------------------------------------------------------- def " print_selection %{ echo %sh{ ${kak_selection} } }" --------------------------------------------------------