e493eba46d
Also, moved the "Markup strings" section to faces.asciidoc, since it wasn't anything to do with expansions, and updated various hyperlinks to point at the new location.
336 lines
11 KiB
Plaintext
336 lines
11 KiB
Plaintext
= Commands
|
||
|
||
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.
|
||
|
||
*doc* <topic>::
|
||
*alias* help +
|
||
display documentation about a topic. The completion list displays the
|
||
available topics
|
||
|
||
== Files and Buffers
|
||
|
||
For the following *write* commands, the *-sync* switch forces the synchronization
|
||
of the file onto the filesystem
|
||
|
||
*change-directory* [<directory>]::
|
||
*alias* cd +
|
||
change the current directory to *directory*, or the home directory if
|
||
unspecified
|
||
|
||
*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[!]* [-sync] [<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* [-sync]::
|
||
*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-quit[!]* [-sync] [<exit status>]::
|
||
*alias* wq +
|
||
write current buffer and quit current client. If specified, the client
|
||
exit status will be set to <exit status>
|
||
|
||
*write-all-quit* [-sync] [<exit status>]::
|
||
*alias* waq +
|
||
write all buffers and quit. If specified, the client exit status
|
||
will be set to <exit status>
|
||
|
||
*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 current buffer or the buffer <name> if specified
|
||
|
||
*rename-buffer* <name>::
|
||
set current buffer name
|
||
|
||
*source* <filename> <param>...::
|
||
execute commands in <filename>
|
||
parameters are avilable in the sourced script through the `arg` values
|
||
|
||
== Clients and Sessions
|
||
|
||
*rename-client* <name>::
|
||
*alias* nc +
|
||
set current client name
|
||
|
||
*rename-session* <name>::
|
||
set current session name
|
||
|
||
*kill[!]* [<exit status>]::
|
||
terminate the current session, all the clients as well as the server.
|
||
If specified, the server and clients exit status will be set to <exit status>
|
||
|
||
== Options
|
||
|
||
*declare-option* [<switches>] <type> <name> [<value>]::
|
||
*alias* decl +
|
||
declare a new option, the -hidden switch hides the option in completion
|
||
suggestions (See <<options#declare-option,`:doc options declare-option`>>)
|
||
|
||
*set-option* [<switches>] <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`>>)
|
||
|
||
== Commands and Keys
|
||
|
||
*define-command* [<switches>] <name> <command>::
|
||
*alias* def +
|
||
define a new command (See <<declaring-new-commands,Declaring new commands>>)
|
||
|
||
*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
|
||
|
||
*evaluate-commands* [<switches>] <command> ...::
|
||
*alias* eval +
|
||
evaluate commands, as if they were entered in the command prompt
|
||
(See <<execeval#,`:doc execeval`>>)
|
||
|
||
*execute-keys* [<switches>] <key> ...::
|
||
*alias* exec +
|
||
execute a series of keys, as if they were hit (See <<execeval#,`:doc execeval`>>)
|
||
|
||
*map* [<switches>] <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`>>)
|
||
|
||
*declare-user-mode* <name>::
|
||
declare a new user keymap mode
|
||
|
||
*enter-user-mode* [<switches>] <name>::
|
||
enable <name> keymap mode for next key
|
||
|
||
*-lock*:::
|
||
stay in mode until `<esc>` is pressed
|
||
|
||
== Hooks
|
||
|
||
*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`>>)
|
||
|
||
== Display
|
||
|
||
*echo* [<switches>] <text>::
|
||
show *text* in status line, with the following *switches*:
|
||
|
||
*-markup*:::
|
||
expand the markup strings in *text* (See
|
||
<<faces#markup-strings,`:doc faces markup-strings`>>)
|
||
|
||
*-debug*:::
|
||
print the given text to the *\*debug** buffer
|
||
|
||
*set-face* <scope> <name> <facespec>::
|
||
*alias* face +
|
||
define a face in *scope* (See <<faces#,`:doc faces`>>)
|
||
|
||
*unset-face* <scope> <name>::
|
||
Remove a face definition from *scope* (See <<faces#,`:doc faces`>>)
|
||
|
||
*colorscheme* <name>::
|
||
load named colorscheme
|
||
|
||
*add-highlighter* <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 in scripts. They are also available in the interactive mode,
|
||
but not really useful in that context.
|
||
|
||
*prompt* [<switches>] <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* [<switches>] <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* [<switches>] <text>::
|
||
display text in an information box with the following *switches*:
|
||
|
||
*-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. If an error is raised
|
||
in the *on_error_commands*, that error is propagated, except if
|
||
another *catch* and *on_error_commands* parameter follows, in which
|
||
case those commands get executed, and so-on.
|
||
|
||
*nop*::
|
||
does nothing, but arguments will be evaluated (e.g. shell expansion)
|
||
|
||
*fail* <text>::
|
||
raise an error, uses <text> as its description
|
||
|
||
*set-register* <name> <contents>...::
|
||
*alias* reg +
|
||
set register *name* to *content*, each content parameter is assigned to
|
||
a different string in the register. (See <<registers#,`:doc registers`>>)
|
||
|
||
*select* <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>...::
|
||
replace the current selections with the ones described in the arguments
|
||
|
||
*debug* {info,buffers,options,memory,shared-strings,profile-hash-maps,faces,mappings}::
|
||
print some debug information in the *\*debug** buffer
|
||
|
||
== 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* [<switches>] <command_name> <commands>::
|
||
*commands* is a string containing the commands to execute, and *switches*
|
||
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
|
||
|
||
during the executing of the shell command, the following env vars are
|
||
available:
|
||
|
||
- *kak_token_to_complete*::::
|
||
Index of the token being completed in the command line.
|
||
|
||
- *kak_pos_in_token*::::
|
||
Position of the cursor inside the token being completed, in bytes
|
||
from token start.
|
||
|
||
*-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
|
||
|
||
during the executing of the shell command, the following env vars are
|
||
available:
|
||
|
||
- *kak_token_to_complete*::::
|
||
Index of the token being completed in the command line.
|
||
|
||
*-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} } }"
|
||
--------------------------------------------------------
|