kakoune/doc/manpages/commands.asciidoc
2016-02-10 21:03:49 +00:00

188 lines
5.7 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

KAKOUNE(1)
==========
NAME
----
commands - a
Primitives
----------
*e[dit]* <filename> [<line> [<column>]]::
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
*w[rite]* [<filename>]::
write buffer to <filename> or use it's name if filename is not given
*w[rite]a[ll]*::
write all buffers that are associated to a file
*q[uit]*::
exit Kakoune, use quit! to force quitting even if there is some
unsaved buffers remaining
*wq*::
write current buffer and quit
*b[uffer]* <name>::
switch to buffer <name>
*d[el]b[uf]* [<name>]::
delete the buffer <name>, use d[el]b[uf]! to force deleting a
modified buffer
*source* <filename>::
execute commands in <filename>
*runtime* <filename>::
execute commands in <filename>, <filename> is relative to kak
executable path
*colorscheme* <name>::
load named colorscheme
*nameclient* <name>::
set current client name
*namebuf* <name>::
set current buffer name
*echo* <text>::
show <text> in status line
*nop*::
does nothing, but arguments will be evaluated (e.g. shell expansion)
*set* <scope> <name> <value>::
change the value of an option (c.f. the 'options' documentation page)
*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
*decl* [-hidden] <type> <name> [<value>]::
declare a new option, the -hidden hides the option in completion
suggestions (c.f. the 'options' documentation page)
*face* <name> <facespec>::
define a face (c.f. the 'faces' documentation page)
*exec* [<flags>] <key> ...::
execute a series of keys, as if they were hit (c.f. the 'execeval'
documentation page)
*eval* [<flags>] <command> ...::
execute commands, as if they were entered in the command prompt
(c.f. the 'execeval' documentation page)
*def* [<flags>] <name> <command>::
define a new command (c.f. the 'Declaring new commands' section below)
*map* <scope> <mode> <key> <keys>::
bind a combination of keys to another one (c.f. the 'commands'
documentation page)
*hook* [-group <group>] <scope> <hook_name> <filtering_regex> <command>::
execute a command whenever an event is triggered (c.f. the 'hooks'
documentation page)
*rmhooks* <scope> <group>::
remove every hooks in *scope* that are part of the given *group*
(c.f. the 'hooks' documentation page)
*addhl* [<flags>] <highlighter_name> <highlighter_parameters> ...::
add a highlighter to the current window (c.f. the 'highlighters'
documentation page)
*rmhl* <highlighter_id>::
remove the highlighter whose id is *highlighter_id* (c.f. the
'highlighters' documentation page)
Helpers
-------
Kakoune provides some helper commands that can be used to define composite
commands:
*prompt* <prompt> <register> <command>::
prompt the user for a string, when the user validates, store the
result in given *register* and run *commmand*. the *-init <str>*
switch allows setting initial content
*onkey* <register> <command>::
wait for next key from user, writes it into given <register> and
execute commands
*menu* <label1> <commands1> <label2> <commands2> ...::
display a menu using labels, the selected labels commands are
executed. menu 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* <text>::
display text in an information box, at can take an *-anchor* option,
which accepts left, right and cursor as value, in order to specify
where the info box should be anchored relative to the main selection
*try* <commands> catch <on_error_commands>::
prevent an error in *commands* from aborting the whole commands
execution, execute *on_error_commands* instead. If nothing is to be
done on error, the catch part can be ommitted
*reg* <name> <content>::
set register *name* to *content*
Note that those commands are also available in the interactive mode, but
are not really useful in that context.
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 *def* command:
*def* [flags] <command_name> <commands>::
*commands* is a string containing the commands to execute, and *flags*
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
*-shell-completion*::
following string is a shell command which takes parameters as
positional params and output one completion candidate per line
*-allow-override*::
allow the new command to replace an exisiting 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 to define complex commands or to access Kakoune
state:
--------------------------------------------------------
def " print_selection %{ echo %sh{ ${kak_selection} } }"
--------------------------------------------------------