'\" t
.\"     Title: kakoune
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 11/16/2018
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH KAK_COMMANDS 1 "" "" "commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
commands \- a
.SH "PRIMITIVES"
.sp
Some commands take an exclamation mark (\fB!\fR), which can be used to force the execution of the command (i\&.e\&. to quit a modified buffer, the command \fBq!\fR has to be used)\&.
.PP
\fBcd\fR [<directory>]
.RS 4
change the current directory to
\fBdirectory\fR, or the home directory if unspecified
.RE
.PP
\fBdoc\fR <topic>
.RS 4
display documentation about a topic\&. The completion list displays the available topics
.RE
.PP
\fBe[dit][!]\fR <filename> [<line> [<column>]]
.RS 4
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
.RE
.PP
\fBw[rite]\fR [<filename>]
.RS 4
write buffer to <filename> or use it\(cqs name if filename is not given
.RE
.PP
\fBw[rite]a[ll]\fR
.RS 4
write all buffers that are associated to a file
.RE
.PP
\fBq[uit][!]\fR
.RS 4
exit Kakoune, use quit! to force quitting even if there is some unsaved buffers remaining
.RE
.PP
\fBkill\fR
.RS 4
terminate the current session, all the clients as well as the server
.RE
.PP
\fBw[a]q[!]\fR
.RS 4
write the current buffer (or all buffers when
\fBwaq\fR
is used) and quit
.RE
.PP
\fBb[uffer]\fR <name>
.RS 4
switch to buffer <name>
.RE
.PP
\fBb[uffer]n[ext]\fR
.RS 4
switch to the next buffer
.RE
.PP
\fBb[uffer]p[rev]\fR
.RS 4
switch to the previous buffer
.RE
.PP
\fBd[el]b[uf][!]\fR [<name>]
.RS 4
delete the buffer <name>
.RE
.PP
\fBsource\fR <filename>
.RS 4
execute commands in <filename>
.RE
.PP
\fBruntime\fR <filename>
.RS 4
execute commands in <filename>, <filename> is relative to kak executable path
.RE
.PP
\fBcolorscheme\fR <name>
.RS 4
load named colorscheme
.RE
.PP
\fBrename\-client\fR <name>
.RS 4
set current client name
.RE
.PP
\fBrename\-buffer\fR <name>
.RS 4
set current buffer name
.RE
.PP
\fBrename\-session\fR <name>
.RS 4
set current session name
.RE
.PP
\fBecho\fR [options] <text>
.RS 4
show
\fBtext\fR
in status line, with the following
\fBoptions\fR:
.PP
\fB\-color\fR <face>
.RS 4
print the given text with
\fBface\fR, most commonly
\fBError\fR
or
\fBInformation\fR
.RE
.PP
\fB\-markup\fR
.RS 4
expand the markup strings in
\fBtext\fR
(c\&.f\&. the
\fIexpansions\fR
documentation page)
.RE
.PP
\fB\-debug\fR
.RS 4
print the given text to the
\fB\e*debug\fR* buffer
.RE
.RE
.PP
\fBnop\fR
.RS 4
does nothing, but arguments will be evaluated (e\&.g\&. shell expansion)
.RE
.PP
\fBset\fR <scope> <name> <value>
.RS 4
change the value of an option (c\&.f\&. the
\fIoptions\fR
documentation page), note that the name of a particular buffer can be specified when the target
\fBscope\fR
is
\fIbuffer\fR, 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
.RE
.PP
\fBunset\fR <scope> <name>
.RS 4
unset the value of an option (c\&.f\&. the
\fIoptions\fR
documentation page)
.RE
.PP
\fBalias\fR <scope> <name> <command>
.RS 4
define a new alias, within the context of a scope
.RE
.PP
\fBunalias\fR <scope> <name> [<command>]
.RS 4
remove an alias if its current value is the same as the one passed as an optional parameter, remove it unconditionally otherwise
.RE
.PP
\fBdeclare\-option\fR [\-hidden] <type> <name> [<value>]
.RS 4
declare a new option, the \-hidden hides the option in completion suggestions (c\&.f\&. the
\fIoptions\fR
documentation page)
.RE
.PP
\fBface\fR <name> <facespec>
.RS 4
define a face (c\&.f\&. the
\fIfaces\fR
documentation page)
.RE
.PP
\fBexec\fR [<flags>] <key> \&...
.RS 4
execute a series of keys, as if they were hit (c\&.f\&. the
\fIexeceval\fR
documentation page)
.RE
.PP
\fBeval\fR [<flags>] <command> \&...
.RS 4
execute commands, as if they were entered in the command prompt (c\&.f\&. the
\fIexeceval\fR
documentation page)
.RE
.PP
\fBdefine\-command\fR [<flags>] <name> <command>
.RS 4
define a new command (c\&.f\&. the
\fIDeclaring new commands\fR
section below)
.RE
.PP
\fBmap\fR <scope> <mode> <key> <keys>
.RS 4
make
\fBkey\fR
behave as if
\fBkeys\fR
were typed\&. with
\fBscope\fR
being one of
\fBglobal\fR,
\fBbuffer\fR
or
\fBwindow\fR,
\fBmode\fR
being
\fBinsert\fR,
\fBnormal\fR,
\fBprompt\fR,
\fBmenu\fR
or
\fBuser\fR\&.
.sp
.if n \{\
.RS 4
.\}
.nf
*user* mode allows for user mapping behind the *,* key\&. Keys
will be executed in normal mode\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBunmap\fR <scope> <mode> <key> [<expected>]
.RS 4
remove the mapping of
\fBkey\fR
in given
\fBscope\fR
and
\fBmode\fR, if expected is specified, only remove the mapping it if matches the expected keys\&.
.RE
.PP
\fBhook\fR [\-group <group>] <scope> <hook_name> <filtering_regex> <command>
.RS 4
execute a command whenever an event is triggered (c\&.f\&. the
\fIhooks\fR
documentation page)
.RE
.PP
\fBremove\-hooks\fR <scope> <group>
.RS 4
remove every hooks in
\fBscope\fR
that are part of the given
\fBgroup\fR
(c\&.f\&. the
\fIhooks\fR
documentation page)
.RE
.PP
\fBadd\-highlighter\fR [<flags>] <highlighter_name> <highlighter_parameters> \&...
.RS 4
add a highlighter to the current window (c\&.f\&. the
\fIhighlighters\fR
documentation page)
.RE
.PP
\fBremove\-highlighter\fR <highlighter_id>
.RS 4
remove the highlighter whose id is
\fBhighlighter_id\fR
(c\&.f\&. the
\fIhighlighters\fR
documentation page)
.RE
.SH "HELPERS"
.sp
Kakoune provides some helper commands that can be used to define composite commands:
.PP
\fBprompt\fR <prompt> <command>
.RS 4
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
The *\-init <str>* switch allows setting initial content, the
*\-password* switch hides the entered text and clears the register
after command execution\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBon\-key\fR <command>
.RS 4
wait for next key from user, then execute <command>, the key is available through the
key
value, accessible through
$kak_key
in shells, or
%val{key}
in commands\&.
.RE
.PP
\fBmenu\fR <label1> <commands1> <label2> <commands2> \&...
.RS 4
display a menu using labels, the selected label\(cqs commands are executed\&. menu can take an
\fB\-auto\-single\fR
argument, to automatically run commands when only one choice is provided, and a
\fB\-select\-cmds\fR
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)
.RE
.PP
\fBinfo\fR [options] <text>
.RS 4
display text in an information box with the following
\fBoptions\fR:
.PP
\fB\-anchor\fR <line>\&.<column>
.RS 4
print the text at the given coordinates
.RE
.PP
\fB\-placement\fR {above,below}
.RS 4
set the placement relative to the anchor
.RE
.PP
\fB\-title\fR <text>
.RS 4
set the title of the message box
.RE
.RE
.PP
\fBtry\fR <commands> catch <on_error_commands>
.RS 4
prevent an error in
\fBcommands\fR
from aborting the whole commands execution, execute
\fBon_error_commands\fR
instead\&. If nothing is to be done on error, the catch part can be omitted
.RE
.PP
\fBreg\fR <name> <content>
.RS 4
set register
\fBname\fR
to
\fBcontent\fR
.RE
.PP
\fBselect\fR <anchor_line>\&.<anchor_column>,<cursor_line>\&.<cursor_column>:\&...
.RS 4
replace the current selections with the one described in the argument
.RE
.PP
\fBdebug\fR {info,buffers,options,memory,shared\-strings}
.RS 4
print some debug information in the
\fB\e*debug\fR* buffer
.RE
.sp
Note that those commands are also available in the interactive mode, but are not really useful in that context\&.
.SH "MULTIPLE COMMANDS"
.sp
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 (\e;) to be considered as a literal semicolon argument
.SH "DECLARING NEW COMMANDS"
.sp
New commands can be defined using the \fBdefine\-command\fR command:
.PP
\fBdefine\-command\fR [flags] <command_name> <commands>
.RS 4
\fBcommands\fR
is a string containing the commands to execute, and
\fBflags\fR
can be any combination of the following parameters:
.PP
\fB\-params\fR <num>
.RS 4
the command accepts a
\fBnum\fR
parameter, which can be either a number, or of the form <min>\&.\&.<max>, with both <min> and <max> omittable
.RE
.PP
\fB\-file\-completion\fR
.RS 4
try file completion on any parameter passed to this command
.RE
.PP
\fB\-client\-completion\fR
.RS 4
try client name completion on any parameter passed to this command
.RE
.PP
\fB\-buffer\-completion\fR
.RS 4
try buffer name completion on any parameter passed to this command
.RE
.PP
\fB\-shell\-completion\fR
.RS 4
following string is a shell command which takes parameters as positional params and output one completion candidate per line
.RE
.PP
\fB\-allow\-override\fR
.RS 4
allow the new command to replace an existing one with the same name
.RE
.PP
\fB\-hidden\fR
.RS 4
do not show the command in command name completions
.RE
.PP
\fB\-docstring\fR
.RS 4
define the documentation string for the command
.RE
.RE
.sp
Using shell expansion allows one to define complex commands or to access Kakoune state:
.sp
.if n \{\
.RS 4
.\}
.nf
def " print_selection %{ echo %sh{ ${kak_selection} } }"
.fi
.if n \{\
.RE
.\}