90043e7df0
`-atomic` becomes `-method replace` and `-method overwrite` is now supported explicitely instead of only available through the writemethod option. Fixes #3827
530 lines
19 KiB
Plaintext
530 lines
19 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[!]* [-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.
|
||
|
||
*-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-prev*::
|
||
*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`>>)
|
||
|
||
*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* [-group <group>] <scope> <hook_name> <filtering_regex> <command>::
|
||
execute *command* whenever a *hook_name* is triggered in *scope*
|
||
(See <<hooks#,`:doc hooks`>> and <<scopes#,`:doc scopes`>>)
|
||
|
||
*remove-hooks* <scope> <group>::
|
||
*alias* rmhooks +
|
||
remove every hooks in *scope* that are part of the given *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
|
||
|
||
*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
|
||
|
||
*-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*:::
|
||
try shell command completion on any parameter passed to this 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.
|
||
|
||
- *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 command which takes parameters as
|
||
positional params and outputs 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 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.
|
||
|
||
*-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:
|
||
|
||
---------------------------------------------------------------------
|
||
# create a directory for current buffer if it does not exist
|
||
define-command mkdir %{ nop %sh{ mkdir -p $(dirname $kak_buffile) } }
|
||
---------------------------------------------------------------------
|
||
|
||
== 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>`.
|
||
|