7061001728
This makes it possible to change command completion in hooks and paves the way to more flexibility in how custom commands can be completed
590 lines
22 KiB
Plaintext
590 lines
22 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 mentioned below each command.
|
||
|
||
*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
|
||
|
||
*arrange-buffers* <buffer>...::
|
||
Reorder the buffers in the buffers list.
|
||
The named buffers will be moved to the front of the buffer list, in the order
|
||
given. Buffers that do not appear in the parameters will remain at the
|
||
end of the list, keeping their current order.
|
||
|
||
*change-directory* [<directory>]::
|
||
*alias* cd +
|
||
change the current directory to *directory*, or the home directory if
|
||
unspecified
|
||
|
||
*edit[!]* [<switches>] <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
|
||
|
||
*-debug*:::
|
||
The new buffer (if any) will be created as a debug buffer.
|
||
(See <<buffers#debug-buffers,`:doc buffers debug-buffers`>>)
|
||
|
||
*-existing*:::
|
||
If the named file does not exist, fail instead of creating a new buffer.
|
||
|
||
*-readonly*:::
|
||
The new buffer (if any) will be set read-only.
|
||
|
||
*-fifo* <fifoname>:::
|
||
Creates a new scratch buffer named <filename>, and continually appends
|
||
data from the fifo (named pipe) <fifoname> as it arrives.
|
||
(See <<buffers#fifo-buffers,`:doc buffers fifo-buffers`>>)
|
||
|
||
*-scratch*:::
|
||
Creates a new buffer named <filename>, which doesn't correspond to any
|
||
file on disk. If no filename is given, the buffer name will be
|
||
generated based on format `\*scratch-$ID\*`, where `$ID` is an
|
||
integer automatically incremented for new buffers.
|
||
(See <<buffers#scratch-buffers,`:doc buffers scratch-buffers`>>)
|
||
|
||
*-scroll*:::
|
||
If used with `-fifo`, when new data arrives Kakoune will scroll the
|
||
buffer down to make the new data visible.
|
||
Otherwise, does nothing.
|
||
|
||
|
||
*write[!]* [-force] [-sync] [-method <writemethod>] [<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.
|
||
|
||
*-force*:::
|
||
Equivalent to `!`, allow overwiting existing files if `<filename>`
|
||
is given and set permissions temporarily if necessary.
|
||
|
||
*-sync*:::
|
||
Synchronise the filesystem after the write
|
||
|
||
*-method <writemethod>*:::
|
||
Enforce write method instead of relying on the `writemethod` option
|
||
|
||
`replace`::::
|
||
Write to a temporary file then rename to the target file so that
|
||
the modification appears atomically.
|
||
|
||
`overwrite`::::
|
||
Open the existing file and overwrite its content with the new
|
||
content.
|
||
|
||
(See <<options#builtin-options,`:doc options builtin-options`>>)
|
||
|
||
*write-all* [-sync] [-method <writemethod>]::
|
||
*alias* wa +
|
||
write all changed buffers that are associated with a file
|
||
|
||
*quit[!]* [<exit status>]::
|
||
*alias* q +
|
||
exit Kakoune, use quit! to force quitting even if there is some
|
||
unsaved buffer remaining. If specified, the client exit status
|
||
will be set to <exit status>
|
||
|
||
*write-quit[!]* [-sync] [-method <writemethod>] [<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] [-method <writemethod>] [<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.
|
||
Debug buffers are skipped.
|
||
(See <<buffers#debug-buffers,`:doc buffers debug-buffers`>>)
|
||
|
||
*buffer-previous*::
|
||
*alias* bp +
|
||
switch to the previous buffer.
|
||
Debug buffers are skipped.
|
||
(See <<buffers#debug-buffers,`:doc buffers debug-buffers`>>)
|
||
|
||
*delete-buffer[!]* [<name>]::
|
||
*alias* db +
|
||
delete current buffer or the buffer <name> if specified
|
||
|
||
*rename-buffer* [-file|-scratch] <name>::
|
||
set current buffer name, if *-scratch* or *-file* is given, ensure
|
||
the buffer is set to the corresponding type.
|
||
|
||
*source* <filename> <param>...::
|
||
execute commands in <filename>
|
||
parameters are available in the sourced script as `%arg{0}`, `%arg{1}`, …
|
||
|
||
== Clients and Sessions
|
||
|
||
*rename-client* <name>::
|
||
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 in *scope*
|
||
(See <<options#set-option,`:doc options set-option`>>
|
||
and <<scopes#,`:doc scopes`>>)
|
||
|
||
*unset-option* <scope> <name>::
|
||
*alias* unset +
|
||
unset the value of an option in *scope*, so the value from an outer scope
|
||
is used
|
||
(See <<options#unset-option,`:doc options unset-option`>>
|
||
and <<scopes#,`:doc scopes`>>)
|
||
|
||
*update-option* <scope> <name>::
|
||
update the value of an option if its type supports that operation
|
||
(See <<options#update-option,`:doc options update-option`>>
|
||
and <<scopes#,`:doc scopes`>>)
|
||
|
||
== 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 named *name* in *scope*
|
||
(See <<aliases,Using aliases>> and <<scopes#,`:doc scopes`>>)
|
||
|
||
*complete-command* [<switches>] <name> <type> [<param>]::
|
||
*alias* compl +
|
||
configure how a command completion works
|
||
(See <<configuring-command-completion,Configuring command completion>>)
|
||
|
||
*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
|
||
(See <<aliases,Using aliases>> and <<scopes#,`:doc scopes`>>)
|
||
|
||
*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`>>
|
||
and <<scopes#,`:doc scopes`>>)
|
||
|
||
*unmap* <scope> <mode> <key> [<expected>]::
|
||
unbind a key combination (See <<mapping#,`:doc mapping`>>
|
||
and <<scopes#,`:doc scopes`>>)
|
||
|
||
*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* [<switches>] <scope> <hook_name> <filtering_regex> <command>::
|
||
execute *command* whenever a *hook_name* is triggered in *scope*
|
||
(See <<hooks#,`:doc hooks`>> and <<scopes#,`:doc scopes`>>)
|
||
|
||
*-group <groupname>*:::
|
||
Add this hook to the *groupname* group, so it can be removed by the
|
||
`remove-hooks` command (below)
|
||
or disabled with the `disabled_hooks` option
|
||
(see <<options#builtin-options,`:doc options builtin-options`>>).
|
||
|
||
*-once*:::
|
||
This hook will be automatically removed after it has been executed.
|
||
|
||
*-always*:::
|
||
This hook will run even while hooks are disabled.
|
||
See <<hooks#disabling-hooks,`:doc hooks disabling-hooks`>>.
|
||
|
||
*remove-hooks* <scope> <group>::
|
||
*alias* rmhooks +
|
||
remove every hook in *scope* whose group matches the regex *group*
|
||
(See <<hooks#,`:doc hooks`>> and <<scopes#,`:doc scopes`>>)
|
||
|
||
*trigger-user-hook* <param>::
|
||
trigger the `User` hook with the given *param* as filter string in
|
||
the current context. (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
|
||
|
||
*-to-file* <filename>:::
|
||
write the given text to the given file on the host
|
||
filesystem.
|
||
|
||
*-quoting* <quoting>:::
|
||
define how arguments are quoted in echo output:
|
||
|
||
- *raw* (default)::::
|
||
just join each argument with a space
|
||
|
||
- *kakoune*::::
|
||
also wrap each argument in single quotes, doubling-up
|
||
embedded quotes.
|
||
|
||
- *shell*::::
|
||
also wrap each arguments in single quotes and escape
|
||
embedded quotes in a shell compatible way.
|
||
|
||
*set-face* <scope> <name> <facespec>::
|
||
*alias* face +
|
||
define a face in *scope*
|
||
(See <<faces#,`:doc faces`>> and <<scopes#,`:doc scopes`>>)
|
||
|
||
*unset-face* <scope> <name>::
|
||
Remove a face definition from *scope*
|
||
(See <<faces#,`:doc faces`>> and <<scopes#,`:doc scopes`>>)
|
||
|
||
*colorscheme* <name>::
|
||
load named colorscheme
|
||
|
||
*add-highlighter* [<switches>] <highlighter_path> <highlighter_parameters> ...::
|
||
*alias* addhl +
|
||
add a highlighter to the current window
|
||
(See <<highlighters#,`:doc highlighters`>>)
|
||
|
||
*remove-highlighter* <highlighter_path>::
|
||
*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.
|
||
|
||
Completion support can be controlled with the same switches provided
|
||
by the *define-command* command, see
|
||
<<declaring-new-commands,Declaring new commands>>.
|
||
|
||
For *-shell-script-completion* and *-shell-script-candidates*
|
||
completions, token_to_complete will always be 1, and the full
|
||
prompt content will be passed as a single token. In other words,
|
||
word splitting does not take place.
|
||
|
||
NOTE: The prompt is displayed in and receives input from the
|
||
current client context, so inside a draft context like
|
||
`evaluate-commands -draft`, it is invisible and only responds to
|
||
an `execute-keys` command in the same context.
|
||
|
||
*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.
|
||
|
||
NOTE: The key press must come from the current client context,
|
||
so inside a draft context like `evaluate-commands -draft`, it only
|
||
responds to an `execute-keys` command in the same context.
|
||
|
||
*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)
|
||
|
||
NOTE: The menu is displayed in and receives input from the
|
||
current client context, so inside a draft context like
|
||
`evaluate-commands -draft`, it is invisible and only responds to
|
||
an `execute-keys` command in the same context.
|
||
|
||
*info* [<switches>] <text>::
|
||
display text in an information box with the following *switches*:
|
||
|
||
*-anchor* <line>.<column>:::
|
||
print the text at the given coordinates
|
||
|
||
*-style* <style>:::
|
||
set the style and placement of the message box.
|
||
|
||
*menu*::::
|
||
display the info next to the displayed menu, as documentation
|
||
for the currently selected entry.
|
||
|
||
*above*::::
|
||
display the info above the given anchor
|
||
|
||
*below*::::
|
||
display the info below the given anchor
|
||
|
||
*modal*::::
|
||
display the info modally, and do not auto-close the
|
||
info or replace it with non modal info boxes. To hide
|
||
a modal info box, use `info -style modal` with no
|
||
arguments.
|
||
|
||
*-title* <text>:::
|
||
set the title of the message box
|
||
|
||
*-markup*:::
|
||
parse markup in both title (if provided) and text. (See
|
||
<<faces#markup-strings,`:doc faces markup-strings`>>)
|
||
|
||
NOTE: The info box is displayed in the current client context,
|
||
so inside a draft context like `eval -draft`, it is invisible.
|
||
|
||
*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. During error commands,
|
||
the description of the last raised error is available as `$kak_error`
|
||
in the shell, or `%val{error}` in commands.
|
||
|
||
*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* [<switches>] <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>...::
|
||
replace the current selections with the ones described in the arguments
|
||
|
||
*-timestamp* <timestamp>:::
|
||
specify which buffer timestamp those coordinates apply to. Uses current
|
||
buffer timestamp if not specified.
|
||
|
||
*-codepoint*::
|
||
provided columns are to be interpreted as codepoint counts, not byte counts.
|
||
|
||
*-display-column*::
|
||
provided columns are to be interpreted as display column counts, not byte counts.
|
||
|
||
both *-codepoint* and *-display-column* are only valid if *-timestamp*
|
||
matches the current buffer timestamp (or is not specified).
|
||
|
||
*debug* {info,buffers,options,memory,shared-strings,profile-hash-maps,faces,mappings}::
|
||
print some debug information in the *\*debug** buffer
|
||
|
||
== Module commands
|
||
|
||
In Kakoune, modules are a grouping of stored commands to be executed the first time
|
||
they are needed. This allows complex configurations to be evaluated lazily, and allows
|
||
plugins to ensure their dependencies have been loaded before they execute. The builtin
|
||
filetype handling for Kakoune is implemented via modules.
|
||
|
||
*provide-module* [<switches>] <name> <commands>::
|
||
declares a module *name* that is defined by *commands*. *commands* will be
|
||
evaluated as if by source the first time *require-module <name>* is run.
|
||
|
||
*-override*:::
|
||
allow the module to replace an existing one with the same name. Fails if
|
||
the module has already been evaluated.
|
||
|
||
*require-module* <name>::
|
||
guarantees the commands associated with *name* have been evaluated before
|
||
continuing command execution. Fails if *name* has not been defined by a
|
||
*provide-module* command. Does nothing if the associated commands have
|
||
already been evaluated.
|
||
|
||
== 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.
|
||
|
||
To avoid trouble while writing `map` or `execute-keys` commands in scripts,
|
||
the alternative key namings `<semicolon>` and `<a-semicolon>` can be used.
|
||
|
||
== 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
|
||
|
||
*-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
|
||
|
||
*-menu*:::
|
||
*-file-completion*:::
|
||
*-client-completion*:::
|
||
*-buffer-completion*:::
|
||
*-command-completion*:::
|
||
*-shell-completion*:::
|
||
*-shell-script-completion*:::
|
||
*-shell-script-candidates*:::
|
||
old-style command completion specification, function as-if
|
||
the switch and its eventual parameter was passed to the
|
||
*complete-command* command
|
||
(See <<configuring-command-completion,Configuring command completion>>)
|
||
|
||
The use of those switches is discouraged in favor of the
|
||
*complete-command* command.
|
||
|
||
Using shell expansion allows defining complex commands or accessing
|
||
Kakoune's state:
|
||
|
||
---------------------------------------------------------------------
|
||
# create a directory for current buffer if it does not exist
|
||
define-command mkdir %{ nop %sh{ mkdir -p $(dirname $kak_buffile) } }
|
||
---------------------------------------------------------------------
|
||
|
||
== Configuring command completion
|
||
|
||
Command completion can be configured with the *complete-command* command:
|
||
|
||
*complete-command* [<switches>] <command_name> <completion_type> [<parameter>]::
|
||
*switches* can be:
|
||
|
||
*-menu*:::
|
||
the suggestions generated by the completion options are the only
|
||
permitted parameters. Kakoune will autoselect the best completion
|
||
candidate on command validation.
|
||
|
||
*completion_type* can be:
|
||
|
||
*file-completion*:::
|
||
try file completion on any parameter passed to the command
|
||
|
||
*client-completion*:::
|
||
try client name completion on any parameter passed to the command
|
||
|
||
*buffer-completion*:::
|
||
try buffer name completion on any parameter passed to the command
|
||
|
||
*command-completion*:::
|
||
try command completion on any parameter passed to the command
|
||
|
||
*shell-completion*:::
|
||
try shell command completion on any parameter passed to the command
|
||
|
||
*shell-script-completion*:::
|
||
following string is a shell command which takes parameters as
|
||
positional params and outputs one completion candidate per line.
|
||
The provided shell command will run after each keypress.
|
||
During the execution of the shell command, the following env vars are
|
||
available:
|
||
|
||
*$kak_token_to_complete*::::
|
||
Index of the token being completed in the command line.
|
||
Note that unlike the Unix `argv` tradition,
|
||
0 is the first argument, not the command name itself.
|
||
|
||
*$kak_pos_in_token*::::
|
||
Position of the cursor inside the token being completed, in bytes
|
||
from token start.
|
||
|
||
*shell-script-candidates*:::
|
||
following string is a shell script which takes parameters as
|
||
positional params and outputs one completion candidate per line.
|
||
The provided shell script will run once at the beginning of each
|
||
completion session, candidates are cached and then used by kakoune
|
||
internal fuzzy engine.
|
||
|
||
During the execution of the shell script, the following env vars are
|
||
available:
|
||
|
||
*$kak_token_to_complete*::::
|
||
Index of the token being completed in the command line.
|
||
Note that unlike the Unix `argv` tradition,
|
||
0 is the first argument, not the command name itself.
|
||
|
||
== Aliases
|
||
|
||
With `:alias`, commands can be given additional names.
|
||
As aliases are intended to be used interactively most of the time,
|
||
they are often short. For example `:reg` is an alias for `:set-register`.
|
||
|
||
They are scoped, so that an alias can refer to one command for a buffer,
|
||
and to another for another buffer. For instance `:next` could be an alias
|
||
for `grep-next-match` in a `*grep*` buffer while pointing to
|
||
`:make-next-error` in a `*make*` buffer.
|
||
|
||
The following command defines `<alias>` as an alias for `<command>`:
|
||
|
||
--------------------------------
|
||
:alias <scope> <alias> <command>
|
||
--------------------------------
|
||
|
||
`<scope>` can be one of `global`, `buffer` or `window`.
|
||
|
||
-------------------------------------
|
||
:unalias <scope> <alias> [<expected>]
|
||
-------------------------------------
|
||
|
||
Will remove the given alias in the given scope. If `<expected>` is specified
|
||
the alias will only be removed if its current value is `<expected>`.
|
||
|