2017-11-02 03:03:24 +01:00
|
|
|
|
= Commands
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2016-04-08 18:00:24 +02:00
|
|
|
|
Some commands take an exclamation mark (*!*), which can be used to force
|
2016-03-12 10:13:49 +01:00
|
|
|
|
the execution of the command (i.e. to quit a modified buffer, the
|
2017-09-09 13:47:45 +02:00
|
|
|
|
command *q!* has to be used). Aliases are mentionned below each commands.
|
2016-03-12 10:13:49 +01:00
|
|
|
|
|
2016-12-13 19:11:45 +01:00
|
|
|
|
*doc* <topic>::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* help +
|
|
|
|
|
display documentation about a topic. The completion list displays the
|
|
|
|
|
available topics
|
2016-12-13 19:11:45 +01:00
|
|
|
|
|
2017-11-07 08:29:08 +01:00
|
|
|
|
== Files and Buffers
|
|
|
|
|
|
2018-08-29 19:22:46 +02:00
|
|
|
|
For the following *write* commands, the *-sync* switch forces the synchronization
|
|
|
|
|
of the file onto the filesystem
|
|
|
|
|
|
2017-11-07 08:29:08 +01:00
|
|
|
|
*change-directory* [<directory>]::
|
|
|
|
|
*alias* cd +
|
|
|
|
|
change the current directory to *directory*, or the home directory if
|
|
|
|
|
unspecified
|
|
|
|
|
|
2019-02-15 10:04:27 +01:00
|
|
|
|
*edit[!]* [<switches>] <filename> [<line> [<column>]]::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*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
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2019-02-15 10:04:27 +01:00
|
|
|
|
*-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.
|
|
|
|
|
(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.
|
|
|
|
|
|
|
|
|
|
|
2018-08-29 19:22:46 +02:00
|
|
|
|
*write[!]* [-sync] [<filename>]::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*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.
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2018-08-29 19:22:46 +02:00
|
|
|
|
*write-all* [-sync]::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* wa +
|
2019-02-24 23:20:12 +01:00
|
|
|
|
write all changed buffers that are associated to a file
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2018-08-23 18:53:15 +02:00
|
|
|
|
*quit[!]* [<exit status>]::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*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>
|
2017-08-23 08:22:23 +02:00
|
|
|
|
|
2018-08-29 19:22:46 +02:00
|
|
|
|
*write-quit[!]* [-sync] [<exit status>]::
|
2018-08-23 18:53:15 +02:00
|
|
|
|
*alias* wq +
|
|
|
|
|
write current buffer and quit current client. If specified, the client
|
|
|
|
|
exit status will be set to <exit status>
|
|
|
|
|
|
2018-08-29 19:22:46 +02:00
|
|
|
|
*write-all-quit* [-sync] [<exit status>]::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* waq +
|
|
|
|
|
write all buffers and quit. If specified, the client exit status
|
|
|
|
|
will be set to <exit status>
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2017-09-09 13:47:45 +02:00
|
|
|
|
*buffer* <name>::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* b +
|
|
|
|
|
switch to buffer <name>
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2017-09-09 13:47:45 +02:00
|
|
|
|
*buffer-next*::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* bn +
|
2019-02-15 10:04:27 +01:00
|
|
|
|
switch to the next buffer.
|
|
|
|
|
Debug buffers are skipped.
|
|
|
|
|
(See <<buffers#debug-buffers,`:doc buffers debug-buffers`>>)
|
2016-03-12 10:13:49 +01:00
|
|
|
|
|
2017-09-09 13:47:45 +02:00
|
|
|
|
*buffer-prev*::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* bp +
|
2019-02-15 10:04:27 +01:00
|
|
|
|
switch to the previous buffer.
|
|
|
|
|
Debug buffers are skipped.
|
|
|
|
|
(See <<buffers#debug-buffers,`:doc buffers debug-buffers`>>)
|
2016-03-12 10:13:49 +01:00
|
|
|
|
|
2017-09-09 13:47:45 +02:00
|
|
|
|
*delete-buffer[!]* [<name>]::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* db +
|
2018-08-29 19:22:46 +02:00
|
|
|
|
delete current buffer or the buffer <name> if specified
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2017-11-07 08:29:08 +01:00
|
|
|
|
*rename-buffer* <name>::
|
|
|
|
|
set current buffer name
|
|
|
|
|
|
2018-05-23 23:22:40 +02:00
|
|
|
|
*source* <filename> <param>...::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
execute commands in <filename>
|
2018-11-09 08:39:00 +01:00
|
|
|
|
parameters are available in the sourced script as `%arg{0}`, `%arg{1}`, …
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2017-11-07 08:29:08 +01:00
|
|
|
|
== Clients and Sessions
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2016-11-14 01:27:14 +01:00
|
|
|
|
*rename-client* <name>::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* nc +
|
|
|
|
|
set current client name
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2016-11-14 01:27:14 +01:00
|
|
|
|
*rename-session* <name>::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
set current session name
|
2016-07-28 01:17:55 +02:00
|
|
|
|
|
2018-08-29 19:22:46 +02:00
|
|
|
|
*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>
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2017-11-07 08:29:08 +01:00
|
|
|
|
== Options
|
2017-10-17 04:02:11 +02:00
|
|
|
|
|
2018-03-17 15:41:56 +01:00
|
|
|
|
*declare-option* [<switches>] <type> <name> [<value>]::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* decl +
|
2018-03-17 15:41:56 +01:00
|
|
|
|
declare a new option, the -hidden switch hides the option in completion
|
2017-11-08 09:32:49 +01:00
|
|
|
|
suggestions (See <<options#declare-option,`:doc options declare-option`>>)
|
2017-05-25 10:02:10 +02:00
|
|
|
|
|
2018-03-17 15:41:56 +01:00
|
|
|
|
*set-option* [<switches>] <scope> <name> <value>::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* set +
|
2019-01-23 02:34:02 +01:00
|
|
|
|
change the value of an option in *scope*
|
|
|
|
|
(See <<options#set-option,`:doc options set-option`>>
|
|
|
|
|
and <<scopes#,`:doc scopes`>>)
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2017-05-25 10:02:10 +02:00
|
|
|
|
*unset-option* <scope> <name>::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* unset +
|
2019-01-23 02:34:02 +01:00
|
|
|
|
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`>>)
|
2016-03-12 10:13:49 +01:00
|
|
|
|
|
2017-05-25 10:02:10 +02:00
|
|
|
|
*update-option* <scope> <name>::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
update the value of an option if its type supports that operation
|
2019-01-23 02:34:02 +01:00
|
|
|
|
(See <<options#update-option,`:doc options update-option`>>
|
|
|
|
|
and <<scopes#,`:doc scopes`>>)
|
2017-05-25 10:02:10 +02:00
|
|
|
|
|
2017-11-07 08:29:08 +01:00
|
|
|
|
== Commands and Keys
|
|
|
|
|
|
2018-03-17 15:41:56 +01:00
|
|
|
|
*define-command* [<switches>] <name> <command>::
|
2017-11-07 08:29:08 +01:00
|
|
|
|
*alias* def +
|
|
|
|
|
define a new command (See <<declaring-new-commands,Declaring new commands>>)
|
|
|
|
|
|
2016-02-03 18:15:35 +01:00
|
|
|
|
*alias* <scope> <name> <command>::
|
2019-01-23 02:34:02 +01:00
|
|
|
|
define a new alias named *name* in *scope*
|
2019-04-19 23:13:23 +02:00
|
|
|
|
(See <<aliases,Using aliases>> and <<scopes#,`:doc scopes`>>)
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
|
|
|
|
*unalias* <scope> <name> [<command>]::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
remove an alias if its current value is the same as the one passed
|
|
|
|
|
as an optional parameter, remove it unconditionally otherwise
|
2019-04-19 23:13:23 +02:00
|
|
|
|
(See <<aliases,Using aliases>> and <<scopes#,`:doc scopes`>>)
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2018-03-17 15:41:56 +01:00
|
|
|
|
*evaluate-commands* [<switches>] <command> ...::
|
2017-11-06 10:08:59 +01:00
|
|
|
|
*alias* eval +
|
|
|
|
|
evaluate commands, as if they were entered in the command prompt
|
|
|
|
|
(See <<execeval#,`:doc execeval`>>)
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2018-03-17 15:41:56 +01:00
|
|
|
|
*execute-keys* [<switches>] <key> ...::
|
2017-11-07 08:29:08 +01:00
|
|
|
|
*alias* exec +
|
|
|
|
|
execute a series of keys, as if they were hit (See <<execeval#,`:doc execeval`>>)
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2018-03-17 15:41:56 +01:00
|
|
|
|
*map* [<switches>] <scope> <mode> <key> <keys>::
|
2019-01-23 02:34:02 +01:00
|
|
|
|
bind a list of keys to a combination (See <<mapping#,`:doc mapping`>>
|
|
|
|
|
and <<scopes#,`:doc scopes`>>)
|
2017-03-05 23:47:16 +01:00
|
|
|
|
|
2016-09-19 10:10:41 +02:00
|
|
|
|
*unmap* <scope> <mode> <key> [<expected>]::
|
2019-01-23 02:34:02 +01:00
|
|
|
|
unbind a key combination (See <<mapping#,`:doc mapping`>>
|
|
|
|
|
and <<scopes#,`:doc scopes`>>)
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2018-03-02 07:45:04 +01:00
|
|
|
|
*declare-user-mode* <name>::
|
|
|
|
|
declare a new user keymap mode
|
2018-01-18 09:57:14 +01:00
|
|
|
|
|
2018-03-17 15:41:56 +01:00
|
|
|
|
*enter-user-mode* [<switches>] <name>::
|
2018-01-18 09:57:14 +01:00
|
|
|
|
enable <name> keymap mode for next key
|
|
|
|
|
|
2018-02-25 16:16:25 +01:00
|
|
|
|
*-lock*:::
|
|
|
|
|
stay in mode until `<esc>` is pressed
|
|
|
|
|
|
2017-11-07 08:29:08 +01:00
|
|
|
|
== Hooks
|
|
|
|
|
|
2016-02-03 18:15:35 +01:00
|
|
|
|
*hook* [-group <group>] <scope> <hook_name> <filtering_regex> <command>::
|
2019-01-23 02:34:02 +01:00
|
|
|
|
execute *command* whenever an *hook_name* is triggered in *scope*
|
|
|
|
|
(See <<hooks#,`:doc hooks`>> and <<scopes#,`:doc scopes`>>)
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2016-11-14 01:27:14 +01:00
|
|
|
|
*remove-hooks* <scope> <group>::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* rmhooks +
|
|
|
|
|
remove every hooks in *scope* that are part of the given *group*
|
2019-01-23 02:34:02 +01:00
|
|
|
|
(See <<hooks#,`:doc hooks`>> and <<scopes#,`:doc scopes`>>)
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2017-11-07 08:29:08 +01:00
|
|
|
|
== Display
|
|
|
|
|
|
2018-03-17 15:41:56 +01:00
|
|
|
|
*echo* [<switches>] <text>::
|
|
|
|
|
show *text* in status line, with the following *switches*:
|
2017-11-07 08:29:08 +01:00
|
|
|
|
|
|
|
|
|
*-markup*:::
|
|
|
|
|
expand the markup strings in *text* (See
|
2018-09-25 08:41:53 +02:00
|
|
|
|
<<faces#markup-strings,`:doc faces markup-strings`>>)
|
2017-11-07 08:29:08 +01:00
|
|
|
|
|
|
|
|
|
*-debug*:::
|
|
|
|
|
print the given text to the *\*debug** buffer
|
|
|
|
|
|
2019-04-07 01:31:36 +02:00
|
|
|
|
*-to-file* <filename>:::
|
|
|
|
|
write the given text to the given file on the host
|
|
|
|
|
filesystem.
|
|
|
|
|
|
2019-06-23 01:58:31 +02:00
|
|
|
|
*-quoting* <quoting>:::
|
|
|
|
|
define how each 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.
|
|
|
|
|
|
2018-04-07 07:36:39 +02:00
|
|
|
|
*set-face* <scope> <name> <facespec>::
|
2017-11-07 08:29:08 +01:00
|
|
|
|
*alias* face +
|
2019-01-23 02:34:02 +01:00
|
|
|
|
define a face in *scope*
|
|
|
|
|
(See <<faces#,`:doc faces`>> and <<scopes#,`:doc scopes`>>)
|
2018-04-07 07:36:39 +02:00
|
|
|
|
|
|
|
|
|
*unset-face* <scope> <name>::
|
2019-01-23 02:34:02 +01:00
|
|
|
|
Remove a face definition from *scope*
|
|
|
|
|
(See <<faces#,`:doc faces`>> and <<scopes#,`:doc scopes`>>)
|
2017-11-07 08:29:08 +01:00
|
|
|
|
|
|
|
|
|
*colorscheme* <name>::
|
|
|
|
|
load named colorscheme
|
|
|
|
|
|
2018-03-17 15:41:56 +01:00
|
|
|
|
*add-highlighter* <highlighter_name> <highlighter_parameters> ...::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* addhl +
|
2017-11-06 10:08:59 +01:00
|
|
|
|
add a highlighter to the current window
|
|
|
|
|
(See <<highlighters#,`:doc highlighters`>>)
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2016-11-14 01:27:14 +01:00
|
|
|
|
*remove-highlighter* <highlighter_id>::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* rmhl +
|
2017-11-06 10:08:59 +01:00
|
|
|
|
remove the highlighter whose id is *highlighter_id*
|
|
|
|
|
(See <<highlighters#,`:doc highlighters`>>)
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2017-11-02 03:03:24 +01:00
|
|
|
|
== Helpers
|
|
|
|
|
|
2016-02-10 22:03:49 +01:00
|
|
|
|
Kakoune provides some helper commands that can be used to define composite
|
2017-11-07 08:29:08 +01:00
|
|
|
|
commands in scripts. They are also available in the interactive mode,
|
|
|
|
|
but not really useful in that context.
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2018-03-17 15:41:56 +01:00
|
|
|
|
*prompt* [<switches>] <prompt> <command>::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
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.
|
2016-11-27 21:57:04 +01:00
|
|
|
|
|
2017-11-02 10:37:39 +01:00
|
|
|
|
The *-init <str>* switch allows setting initial content, the
|
|
|
|
|
*-password* switch hides the entered text and clears the register
|
|
|
|
|
after command execution.
|
2016-11-27 21:57:04 +01:00
|
|
|
|
|
2017-11-07 08:29:08 +01:00
|
|
|
|
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.
|
2017-02-12 13:51:58 +01:00
|
|
|
|
|
2019-03-24 09:20:29 +01:00
|
|
|
|
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-completions* 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.
|
|
|
|
|
|
2016-11-27 21:57:04 +01:00
|
|
|
|
*on-key* <command>::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
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.
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2018-03-17 15:41:56 +01:00
|
|
|
|
*menu* [<switches>] <label1> <commands1> <label2> <commands2> ...::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
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)
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2018-03-17 15:41:56 +01:00
|
|
|
|
*info* [<switches>] <text>::
|
|
|
|
|
display text in an information box with the following *switches*:
|
2016-03-12 10:13:49 +01:00
|
|
|
|
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*-anchor* <line>.<column>:::
|
|
|
|
|
print the text at the given coordinates
|
2016-03-12 10:13:49 +01:00
|
|
|
|
|
2019-04-17 08:31:06 +02:00
|
|
|
|
*-style* <style>:::
|
|
|
|
|
set the style and placement of the message box.
|
2019-04-15 17:22:48 +02:00
|
|
|
|
|
|
|
|
|
*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
|
2016-03-12 10:13:49 +01:00
|
|
|
|
|
2019-04-17 08:31:06 +02:00
|
|
|
|
*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.
|
|
|
|
|
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*-title* <text>:::
|
|
|
|
|
set the title of the message box
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2018-05-19 06:03:32 +02:00
|
|
|
|
*try* <commands> [catch <on_error_commands>]...::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
prevent an error in *commands* from aborting the whole command
|
|
|
|
|
execution, execute *on_error_commands* instead. If nothing is to be
|
2018-05-19 06:03:32 +02:00
|
|
|
|
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
|
2019-03-05 10:46:23 +01:00
|
|
|
|
case those commands get executed, and so-on. During error commands,
|
2019-03-05 11:07:49 +01:00
|
|
|
|
the description of the last raised error is available as `$kak_error`
|
2019-03-05 10:46:23 +01:00
|
|
|
|
in the shell, or `%val{error}` in commands.
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2017-11-07 08:29:08 +01:00
|
|
|
|
*nop*::
|
|
|
|
|
does nothing, but arguments will be evaluated (e.g. shell expansion)
|
|
|
|
|
|
|
|
|
|
*fail* <text>::
|
|
|
|
|
raise an error, uses <text> as its description
|
|
|
|
|
|
2018-06-03 06:16:19 +02:00
|
|
|
|
*set-register* <name> <contents>...::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
*alias* reg +
|
2018-06-03 06:16:19 +02:00
|
|
|
|
set register *name* to *content*, each content parameter is assigned to
|
|
|
|
|
a different string in the register. (See <<registers#,`:doc registers`>>)
|
2016-02-02 20:15:12 +01:00
|
|
|
|
|
2018-05-31 13:14:21 +02:00
|
|
|
|
*select* <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>...::
|
|
|
|
|
replace the current selections with the ones described in the arguments
|
2016-03-12 10:13:49 +01:00
|
|
|
|
|
2017-10-03 23:00:08 +02:00
|
|
|
|
*debug* {info,buffers,options,memory,shared-strings,profile-hash-maps,faces,mappings}::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
print some debug information in the *\*debug** buffer
|
2016-03-12 10:13:49 +01:00
|
|
|
|
|
2019-03-15 19:52:33 +01:00
|
|
|
|
== Module commands
|
|
|
|
|
|
|
|
|
|
*provide-module* [<switches>] <name> <commands>::
|
2019-03-16 09:09:42 +01:00
|
|
|
|
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*:::
|
2019-04-15 21:53:45 +02:00
|
|
|
|
allow the module to replace an existing one with the same name. Fails if
|
|
|
|
|
the module has already been evaluated.
|
2019-03-15 19:52:33 +01:00
|
|
|
|
|
|
|
|
|
*require-module* <name>::
|
2019-03-16 09:09:42 +01:00
|
|
|
|
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.
|
2019-03-15 19:52:33 +01:00
|
|
|
|
|
2017-11-02 03:03:24 +01:00
|
|
|
|
== 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
|
2019-10-28 22:18:55 +01:00
|
|
|
|
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.
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2017-11-02 03:03:24 +01:00
|
|
|
|
== Declaring new commands
|
|
|
|
|
|
2016-11-14 01:27:14 +01:00
|
|
|
|
New commands can be defined using the *define-command* command:
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2018-03-17 15:41:56 +01:00
|
|
|
|
*define-command* [<switches>] <command_name> <commands>::
|
|
|
|
|
*commands* is a string containing the commands to execute, and *switches*
|
2017-11-02 10:37:39 +01:00
|
|
|
|
can be any combination of the following parameters:
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2016-03-12 10:13:49 +01:00
|
|
|
|
*-params* <num>:::
|
2017-11-02 10:37:39 +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
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2016-03-12 10:13:49 +01:00
|
|
|
|
*-file-completion*:::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
try file completion on any parameter passed to this command
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2016-03-12 10:13:49 +01:00
|
|
|
|
*-client-completion*:::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
try client name completion on any parameter passed to this command
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2016-03-12 10:13:49 +01:00
|
|
|
|
*-buffer-completion*:::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
try buffer name completion on any parameter passed to this command
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2017-09-28 15:16:46 +02:00
|
|
|
|
*-command-completion*:::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
try command completion on any parameter passed to this command
|
2017-09-28 15:16:46 +02:00
|
|
|
|
|
2016-03-12 10:13:49 +01:00
|
|
|
|
*-shell-completion*:::
|
2018-09-26 23:42:01 +02:00
|
|
|
|
try shell command completion on any parameter passed to this command
|
|
|
|
|
|
|
|
|
|
*-shell-script-completion*:::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
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
|
2017-09-28 15:16:46 +02:00
|
|
|
|
|
2018-02-22 12:46:35 +01:00
|
|
|
|
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.
|
|
|
|
|
|
2018-09-26 23:42:01 +02:00
|
|
|
|
*-shell-script-candidates*:::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
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
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2018-02-22 12:46:35 +01:00
|
|
|
|
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.
|
|
|
|
|
|
2018-05-19 02:54:24 +02:00
|
|
|
|
*-override*:::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
allow the new command to replace an existing one with the same name
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2016-03-12 10:13:49 +01:00
|
|
|
|
*-hidden*:::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
do not show the command in command name completions
|
2016-02-03 18:15:35 +01:00
|
|
|
|
|
2016-03-12 10:13:49 +01:00
|
|
|
|
*-docstring*:::
|
2017-11-02 10:37:39 +01:00
|
|
|
|
define the documentation string for the command
|
2016-02-02 20:15:12 +01:00
|
|
|
|
|
2017-04-21 12:32:47 +02:00
|
|
|
|
Using shell expansion allows defining complex commands or accessing
|
|
|
|
|
Kakoune's state:
|
2016-02-02 20:15:12 +01:00
|
|
|
|
|
2016-02-03 18:15:35 +01:00
|
|
|
|
--------------------------------------------------------
|
|
|
|
|
def " print_selection %{ echo %sh{ ${kak_selection} } }"
|
|
|
|
|
--------------------------------------------------------
|
2019-04-19 23:13:23 +02:00
|
|
|
|
|
|
|
|
|
== 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>`.
|
|
|
|
|
|