8aa35c0724
Convert session names to lowercase and replace spaces with minus to generate anchor names.
286 lines
9.5 KiB
Plaintext
286 lines
9.5 KiB
Plaintext
= Commands
|
||
|
||
== Builtins
|
||
|
||
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). Aliases are mentionned below each commands.
|
||
|
||
*change-directory* [<directory>]::
|
||
*alias* cd +
|
||
change the current directory to *directory*, or the home directory if
|
||
unspecified
|
||
|
||
*doc* <topic>::
|
||
*alias* help +
|
||
display documentation about a topic. The completion list displays the
|
||
available topics
|
||
|
||
*edit[!]* <filename> [<line> [<column>]]::
|
||
*alias* e +
|
||
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
|
||
|
||
*write[!]* [<filename>]::
|
||
*alias* w +
|
||
write buffer to <filename> or use its name if filename is not
|
||
given. If the file is write-protected, its permissions are temporarily
|
||
changed to allow saving the buffer and restored afterwards when
|
||
the write! command is used.
|
||
|
||
*write-all*::
|
||
*alias* wa +
|
||
write all buffers that are associated to a file
|
||
|
||
*quit!* [<exit status>]::
|
||
*alias* q +
|
||
exit Kakoune, use quit! to force quitting even if there is some
|
||
unsaved buffers remaining. If specified, the client exit status
|
||
will be set to <exit status>
|
||
|
||
*write-all-quit* [<exit status>]::
|
||
*alias* waq +
|
||
write all buffers and quit. If specified, the client exit status
|
||
will be set to <exit status>
|
||
|
||
*kill[!]*::
|
||
terminate the current session, all the clients as well as the server
|
||
|
||
*buffer* <name>::
|
||
*alias* b +
|
||
switch to buffer <name>
|
||
|
||
*buffer-next*::
|
||
*alias* bn +
|
||
switch to the next buffer
|
||
|
||
*buffer-prev*::
|
||
*alias* bp +
|
||
switch to the previous buffer
|
||
|
||
*delete-buffer[!]* [<name>]::
|
||
*alias* db +
|
||
delete the buffer <name>
|
||
|
||
*source* <filename>::
|
||
execute commands in <filename>
|
||
|
||
*colorscheme* <name>::
|
||
load named colorscheme
|
||
|
||
*rename-client* <name>::
|
||
*alias* nc +
|
||
set current client name
|
||
|
||
*rename-buffer* <name>::
|
||
set current buffer name
|
||
|
||
*rename-session* <name>::
|
||
set current session name
|
||
|
||
*echo* [options] <text>::
|
||
show *text* in status line, with the following *options*:
|
||
|
||
*-markup*:::
|
||
expand the markup strings in *text* (See
|
||
<<expansions#markup-strings,`:doc expansions markup-strings`>>)
|
||
|
||
*-debug*:::
|
||
print the given text to the *\*debug** buffer
|
||
|
||
*nop*::
|
||
does nothing, but arguments will be evaluated (e.g. shell expansion)
|
||
|
||
*fail* <text>::
|
||
raise an error, uses <text> as its description
|
||
|
||
*declare-option* [-hidden] <type> <name> [<value>]::
|
||
*alias* decl +
|
||
declare a new option, the -hidden hides the option in completion
|
||
suggestions (See <<options#declare-option,`:doc options declare-option`>>)
|
||
|
||
*set-option* <scope> <name> <value>::
|
||
*alias* set +
|
||
change the value of an option
|
||
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
|
||
(See <<options#set-option,`:doc options set-option`>>)
|
||
|
||
*unset-option* <scope> <name>::
|
||
*alias* unset +
|
||
unset the value of an option (See <<options#unset-option,`:doc options unset-option`>>)
|
||
|
||
*update-option* <scope> <name>::
|
||
update the value of an option if its type supports that operation
|
||
(See <<options#update-option,`:doc options update-option`>>)
|
||
|
||
*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
|
||
|
||
*set-face* <name> <facespec>::
|
||
*alias* face +
|
||
define a face (See <<faces#,`:doc faces`>>)
|
||
|
||
*execute-keys* [<flags>] <key> ...::
|
||
*alias* exec +
|
||
execute a series of keys, as if they were hit (See <<execeval#,`:doc execeval`>>)
|
||
|
||
*evaluate-commands* [<flags>] <command> ...::
|
||
*alias* eval +
|
||
evaluate commands, as if they were entered in the command prompt
|
||
(See <<execeval#,`:doc execeval`>>)
|
||
|
||
*define-command* [<flags>] <name> <command>::
|
||
*alias* def +
|
||
define a new command (See <<declaring-new-commands,Declaring new commands>>)
|
||
|
||
*map* <scope> <mode> <key> <keys>::
|
||
bind a list of keys to a combination (See <<mapping#,`:doc mapping`>>)
|
||
|
||
*unmap* <scope> <mode> <key> [<expected>]::
|
||
unbind a key combination (See <<mapping#,`:doc mapping`>>)
|
||
|
||
*hook* [-group <group>] <scope> <hook_name> <filtering_regex> <command>::
|
||
execute a command whenever an event is triggered
|
||
(See <<hooks#,`:doc hooks`>>)
|
||
|
||
*remove-hooks* <scope> <group>::
|
||
*alias* rmhooks +
|
||
remove every hooks in *scope* that are part of the given *group*
|
||
(See <<hooks#,`:doc hooks`>>)
|
||
|
||
*add-highlighter* [<flags>] <highlighter_name> <highlighter_parameters> ...::
|
||
*alias* addhl +
|
||
add a highlighter to the current window
|
||
(See <<highlighters#,`:doc highlighters`>>)
|
||
|
||
*remove-highlighter* <highlighter_id>::
|
||
*alias* rmhl +
|
||
remove the highlighter whose id is *highlighter_id*
|
||
(See <<highlighters#,`:doc highlighters`>>)
|
||
|
||
== Helpers
|
||
|
||
Kakoune provides some helper commands that can be used to define composite
|
||
commands:
|
||
|
||
*prompt* <prompt> <command>::
|
||
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 <str>* switch allows setting initial content, the
|
||
*-password* switch hides the entered text and clears the register
|
||
after command execution.
|
||
|
||
The *-on-change* and *-on-abort* switches, followed by a command
|
||
will have this command executed whenever the prompt content changes
|
||
or the prompt is aborted, respectively.
|
||
|
||
*on-key* <command>::
|
||
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.
|
||
|
||
*menu* <label1> <commands1> <label2> <commands2> ...::
|
||
display a menu using labels, the selected label’s commands are
|
||
executed. The *menu* command 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 command
|
||
execution, execute *on_error_commands* instead. If nothing is to be
|
||
done on error, the catch part can be omitted
|
||
|
||
*set-register* <name> <content>::
|
||
*alias* reg +
|
||
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,profile-hash-maps,faces,mappings}::
|
||
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] <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
|
||
|
||
*-command-completion*:::
|
||
try command 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.
|
||
The provided shell command will run after each keypress
|
||
|
||
*-shell-candidates*:::
|
||
following string is a shell command which takes parameters as
|
||
positional params and output one completion candidate per line.
|
||
The provided shell command will run once at the beginning of each
|
||
completion session, candidates are cached and then used by kakoune
|
||
internal fuzzy engine
|
||
|
||
*-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 defining complex commands or accessing
|
||
Kakoune's state:
|
||
|
||
--------------------------------------------------------
|
||
def " print_selection %{ echo %sh{ ${kak_selection} } }"
|
||
--------------------------------------------------------
|