kakoune/doc/pages/commands.asciidoc

286 lines
9.5 KiB
Plaintext
Raw Normal View History

= Commands
== Builtins
2016-04-08 18:00:24 +02:00
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
2017-09-09 13:47:45 +02:00
command *q!* has to be used). Aliases are mentionned below each commands.
2017-09-09 13:47:45 +02:00
*change-directory* [<directory>]::
2017-11-02 10:37:39 +01:00
*alias* cd +
change the current directory to *directory*, or the home directory if
unspecified
2016-12-13 19:11:45 +01:00
*doc* <topic>::
2017-11-02 10:37:39 +01:00
*alias* help +
display documentation about a topic. The completion list displays the
available topics
2016-12-13 19:11:45 +01:00
2017-09-09 13:47:45 +02:00
*edit[!]* <filename> [<line> [<column>]]::
2017-11-02 10:37:39 +01:00
*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
2017-09-09 13:47:45 +02:00
*write[!]* [<filename>]::
2017-11-02 10:37:39 +01:00
*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.
2017-09-09 13:47:45 +02:00
*write-all*::
2017-11-02 10:37:39 +01:00
*alias* wa +
write all buffers that are associated to a file
2017-09-09 13:47:45 +02:00
*quit!* [<exit status>]::
2017-11-02 10:37:39 +01:00
*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>
2017-09-09 13:47:45 +02:00
*write-all-quit* [<exit status>]::
2017-11-02 10:37:39 +01:00
*alias* waq +
write all buffers and quit. If specified, the client exit status
will be set to <exit status>
2017-09-09 13:47:45 +02:00
*kill[!]*::
2017-11-02 10:37:39 +01:00
terminate the current session, all the clients as well as the server
2017-09-09 13:47:45 +02:00
*buffer* <name>::
2017-11-02 10:37:39 +01:00
*alias* b +
switch to buffer <name>
2017-09-09 13:47:45 +02:00
*buffer-next*::
2017-11-02 10:37:39 +01:00
*alias* bn +
switch to the next buffer
2017-09-09 13:47:45 +02:00
*buffer-prev*::
2017-11-02 10:37:39 +01:00
*alias* bp +
switch to the previous buffer
2017-09-09 13:47:45 +02:00
*delete-buffer[!]* [<name>]::
2017-11-02 10:37:39 +01:00
*alias* db +
delete the buffer <name>
*source* <filename>::
2017-11-02 10:37:39 +01:00
execute commands in <filename>
*colorscheme* <name>::
2017-11-02 10:37:39 +01:00
load named colorscheme
2016-11-14 01:27:14 +01:00
*rename-client* <name>::
2017-11-02 10:37:39 +01:00
*alias* nc +
set current client name
2016-11-14 01:27:14 +01:00
*rename-buffer* <name>::
2017-11-02 10:37:39 +01:00
set current buffer name
2016-11-14 01:27:14 +01:00
*rename-session* <name>::
2017-11-02 10:37:39 +01:00
set current session name
2016-07-28 01:17:55 +02:00
*echo* [options] <text>::
2017-11-02 10:37:39 +01:00
show *text* in status line, with the following *options*:
2017-11-02 10:37:39 +01:00
*-markup*:::
expand the markup strings in *text* (See
<<expansions#markup-strings,`:doc expansions markup-strings`>>)
2017-11-02 10:37:39 +01:00
*-debug*:::
print the given text to the *\*debug** buffer
*nop*::
2017-11-02 10:37:39 +01:00
does nothing, but arguments will be evaluated (e.g. shell expansion)
*fail* <text>::
2017-11-02 10:37:39 +01:00
raise an error, uses <text> as its description
2017-05-25 10:02:10 +02:00
*declare-option* [-hidden] <type> <name> [<value>]::
2017-11-02 10:37:39 +01:00
*alias* decl +
declare a new option, the -hidden hides the option in completion
suggestions (See <<options#declare-option,`:doc options declare-option`>>)
2017-05-25 10:02:10 +02:00
*set-option* <scope> <name> <value>::
2017-11-02 10:37:39 +01:00
*alias* set +
2017-11-06 10:08:59 +01:00
change the value of an option
2017-11-02 10:37:39 +01:00
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`>>)
2017-05-25 10:02:10 +02:00
*unset-option* <scope> <name>::
2017-11-02 10:37:39 +01:00
*alias* unset +
unset the value of an option (See <<options#unset-option,`:doc options unset-option`>>)
2017-05-25 10:02:10 +02:00
*update-option* <scope> <name>::
2017-11-02 10:37:39 +01:00
update the value of an option if its type supports that operation
(See <<options#update-option,`:doc options update-option`>>)
2017-05-25 10:02:10 +02:00
*alias* <scope> <name> <command>::
2017-11-02 10:37:39 +01:00
define a new alias, within the context of a scope
*unalias* <scope> <name> [<command>]::
2017-11-02 10:37:39 +01:00
remove an alias if its current value is the same as the one passed
as an optional parameter, remove it unconditionally otherwise
2017-09-09 13:47:45 +02:00
*set-face* <name> <facespec>::
2017-11-02 10:37:39 +01:00
*alias* face +
2017-11-06 10:08:59 +01:00
define a face (See <<faces#,`:doc faces`>>)
2017-11-06 10:08:59 +01:00
*execute-keys* [<flags>] <key> ...::
*alias* exec +
execute a series of keys, as if they were hit (See <<execeval#,`:doc execeval`>>)
2017-11-06 10:08:59 +01:00
*evaluate-commands* [<flags>] <command> ...::
*alias* eval +
evaluate commands, as if they were entered in the command prompt
(See <<execeval#,`:doc execeval`>>)
2016-11-14 01:27:14 +01:00
*define-command* [<flags>] <name> <command>::
2017-11-02 10:37:39 +01:00
*alias* def +
define a new command (See <<declaring-new-commands,Declaring new commands>>)
*map* <scope> <mode> <key> <keys>::
2017-11-06 10:08:59 +01:00
bind a list of keys to a combination (See <<mapping#,`:doc mapping`>>)
*unmap* <scope> <mode> <key> [<expected>]::
2017-11-06 10:08:59 +01:00
unbind a key combination (See <<mapping#,`:doc mapping`>>)
*hook* [-group <group>] <scope> <hook_name> <filtering_regex> <command>::
2017-11-06 10:08:59 +01:00
execute a command whenever an event is triggered
(See <<hooks#,`:doc hooks`>>)
2016-11-14 01:27:14 +01:00
*remove-hooks* <scope> <group>::
2017-11-02 10:37:39 +01:00
*alias* rmhooks +
remove every hooks in *scope* that are part of the given *group*
2017-11-06 10:08:59 +01:00
(See <<hooks#,`:doc hooks`>>)
2016-11-14 01:27:14 +01:00
*add-highlighter* [<flags>] <highlighter_name> <highlighter_parameters> ...::
2017-11-02 10:37:39 +01:00
*alias* addhl +
2017-11-06 10:08:59 +01:00
add a highlighter to the current window
(See <<highlighters#,`:doc highlighters`>>)
2016-11-14 01:27:14 +01:00
*remove-highlighter* <highlighter_id>::
2017-11-02 10:37:39 +01:00
*alias* rmhl +
2017-11-06 10:08:59 +01:00
remove the highlighter whose id is *highlighter_id*
(See <<highlighters#,`:doc highlighters`>>)
== Helpers
2016-02-10 22:03:49 +01:00
Kakoune provides some helper commands that can be used to define composite
commands:
*prompt* <prompt> <command>::
2017-11-02 10:37:39 +01:00
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.
2017-11-02 10:37:39 +01:00
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>::
2017-11-02 10:37:39 +01:00
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> ...::
2017-11-02 10:37:39 +01:00
display a menu using labels, the selected labels 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>::
2017-11-02 10:37:39 +01:00
display text in an information box with the following *options*:
2017-11-02 10:37:39 +01:00
*-anchor* <line>.<column>:::
print the text at the given coordinates
2017-11-02 10:37:39 +01:00
*-placement* {above,below}:::
set the placement relative to the anchor
2017-11-02 10:37:39 +01:00
*-title* <text>:::
set the title of the message box
*try* <commands> catch <on_error_commands>::
2017-11-02 10:37:39 +01:00
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
2017-09-09 13:47:45 +02:00
*set-register* <name> <content>::
2017-11-02 10:37:39 +01:00
*alias* reg +
set register *name* to *content*
*select* <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>:...::
2017-11-02 10:37:39 +01:00
replace the current selections with the one described in the argument
2017-10-03 23:00:08 +02:00
*debug* {info,buffers,options,memory,shared-strings,profile-hash-maps,faces,mappings}::
2017-11-02 10:37:39 +01:00
print some debug information in the *\*debug** buffer
2016-02-10 22:03:49 +01:00
Note that those commands are also available in the interactive mode, but
are not really useful in that context.
== Multiple commands
2016-02-10 22:03:49 +01:00
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
2016-11-14 01:27:14 +01:00
New commands can be defined using the *define-command* command:
2016-11-14 01:27:14 +01:00
*define-command* [flags] <command_name> <commands>::
2017-11-02 10:37:39 +01:00
*commands* is a string containing the commands to execute, and *flags*
can be any combination of the following parameters:
*-params* <num>:::
2017-11-02 10:37:39 +01:00
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*:::
2017-11-02 10:37:39 +01:00
try file completion on any parameter passed to this command
*-client-completion*:::
2017-11-02 10:37:39 +01:00
try client name completion on any parameter passed to this command
*-buffer-completion*:::
2017-11-02 10:37:39 +01:00
try buffer name completion on any parameter passed to this command
*-command-completion*:::
2017-11-02 10:37:39 +01:00
try command completion on any parameter passed to this command
*-shell-completion*:::
2017-11-02 10:37:39 +01:00
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*:::
2017-11-02 10:37:39 +01:00
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*:::
2017-11-02 10:37:39 +01:00
allow the new command to replace an existing one with the same name
*-hidden*:::
2017-11-02 10:37:39 +01:00
do not show the command in command name completions
*-docstring*:::
2017-11-02 10:37:39 +01:00
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} } }"
--------------------------------------------------------