kakoune/doc/manpages/commands.asciidoc

251 lines
7.9 KiB
Plaintext
Raw Normal View History

KAKOUNE(1)
==========
NAME
----
commands - a
Primitives
----------
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
command *q!* has to be used).
*cd* [<directory>]::
change the current directory to *directory*, or the home directory if
unspecified
2016-12-13 19:11:45 +01:00
*doc* <topic>::
display documentation about a topic. The completion list displays the
available topics
*e[dit][!]* <filename> [<line> [<column>]]::
2016-02-10 22:03:49 +01:00
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][!]*::
2016-02-10 22:03:49 +01:00
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>
*colorscheme* <name>::
load named colorscheme
2016-11-14 01:27:14 +01:00
*rename-client* <name>::
set current client name
2016-11-14 01:27:14 +01:00
*rename-buffer* <name>::
set current buffer name
2016-11-14 01:27:14 +01:00
*rename-session* <name>::
2016-07-28 01:17:55 +02:00
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),
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* <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>]::
2016-02-10 22:03:49 +01:00
remove an alias if its current value is the same as the one passed
as an optional parameter, remove it unconditionally otherwise
2016-11-14 01:27:14 +01:00
*declare-option* [-hidden] <type> <name> [<value>]::
2016-02-10 22:03:49 +01:00
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> ...::
2016-02-10 22:03:49 +01:00
execute a series of keys, as if they were hit (c.f. the 'execeval'
documentation page)
*eval* [<flags>] <command> ...::
2016-02-10 22:03:49 +01:00
execute commands, as if they were entered in the command prompt
(c.f. the 'execeval' documentation page)
2016-11-14 01:27:14 +01:00
*define-command* [<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>::
2016-02-10 22:03:49 +01:00
execute a command whenever an event is triggered (c.f. the 'hooks'
documentation page)
2016-11-14 01:27:14 +01:00
*remove-hooks* <scope> <group>::
2016-02-10 22:03:49 +01:00
remove every hooks in *scope* that are part of the given *group*
(c.f. the 'hooks' documentation page)
2016-11-14 01:27:14 +01:00
*add-highlighter* [<flags>] <highlighter_name> <highlighter_parameters> ...::
2016-02-10 22:03:49 +01:00
add a highlighter to the current window (c.f. the 'highlighters'
documentation page)
2016-11-14 01:27:14 +01:00
*remove-highlighter* <highlighter_id>::
2016-02-10 22:03:49 +01:00
remove the highlighter whose id is *highlighter_id* (c.f. the
'highlighters' documentation page)
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>::
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.
*on-key* <command>::
wait for next key from user, then execute <command>, the key is
2016-12-01 21:14:31 +01:00
available through the `key` value, accessible through `$kak_key`
in shells, or `%val{key}` in commands.
*menu* <label1> <commands1> <label2> <commands2> ...::
2016-02-10 22:03:49 +01:00
display a menu using labels, the selected labels 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>::
2016-02-10 22:03:49 +01:00
prevent an error in *commands* from aborting the whole commands
execution, execute *on_error_commands* instead. If nothing is to be
2016-04-08 18:00:24 +02:00
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
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>::
2016-02-10 22:03:49 +01:00
*commands* is a string containing the commands to execute, and *flags*
can be any combination of the following parameters:
*-params* <num>:::
2016-02-10 22:03:49 +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*:::
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*:::
2016-02-10 22:03:49 +01:00
following string is a shell command which takes parameters as
positional params and output one completion candidate per line
*-allow-override*:::
2016-04-08 18:00:24 +02:00
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
2016-02-10 22:03:49 +01:00
Using shell expansion allows to define complex commands or to access Kakoune
state:
--------------------------------------------------------
def " print_selection %{ echo %sh{ ${kak_selection} } }"
--------------------------------------------------------