1f11529837
prompt has fuzzy filtering which is more discoverable than the menu mode's regex filtering (because that one needs / to trigger it). There are no important differences left, so replace the menu builtin with a prompt-based command. prompt does not support markup in the completion menu, so drop that feature for now.
581 lines
21 KiB
Plaintext
581 lines
21 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.
|
|
|
|
*-to-shell-script* <script>:::
|
|
execute the given shell script with the given text
|
|
written to its standard input
|
|
|
|
*-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.
|
|
|
|
*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*:::
|
|
try file completion on any parameter passed to the command
|
|
|
|
*client*:::
|
|
try client name completion on any parameter passed to the command
|
|
|
|
*buffer*:::
|
|
try buffer name completion on any parameter passed to the command
|
|
|
|
*command*:::
|
|
try command completion on any parameter passed to the command
|
|
|
|
*shell*:::
|
|
try shell command completion on any parameter passed to the command
|
|
|
|
*shell-script*:::
|
|
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>`.
|
|
|