508 lines
19 KiB
Plaintext
508 lines
19 KiB
Plaintext
Kakoune
|
|
=======
|
|
|
|
Introduction:
|
|
-------------
|
|
|
|
Kakoune is a code editor heavily inspired by vim, as such most of it's
|
|
commands are similar to vi's ones.
|
|
|
|
Kakoune can operate in two modes, normal and insertion. In insertion mode,
|
|
keys are directly inserted into the current buffer. In normal mode, keys
|
|
are used to manipulate the current selection and to enter insertion mode.
|
|
|
|
There is no concept of cursor in kakoune, only selections, a single character
|
|
selection can be seen as a cursor but there is no difference internally.
|
|
|
|
Building
|
|
--------
|
|
|
|
Kakoune dependencies are:
|
|
|
|
* GCC >= 4.7
|
|
* boost
|
|
* ncurses
|
|
|
|
To build, just type *make* in the src directory
|
|
|
|
To setup a basic configuration on your account, type *make userconfig* in the
|
|
src directory, this will setup an initial $XDG_CONFIG_HOME/kak directory. See
|
|
the _Kakrc_ section for more information.
|
|
|
|
Running
|
|
-------
|
|
|
|
Just running *kak* launch a new kak session with a client on local terminal.
|
|
*kak* accepts some switches:
|
|
|
|
* +-c <session>+: connect to given session (which is the pid of the
|
|
initial kak process), sessions are unix sockets +/tmp/kak-<session>+
|
|
* +-e <commands>+: execute commands on startup
|
|
* +-n+: ignore kakrc file
|
|
|
|
Basic Movement
|
|
--------------
|
|
|
|
* _space_: select the character under selection end
|
|
* _alt-space_: flip the selections
|
|
|
|
* _h_: select the character on the right of selection end
|
|
* _j_: select the character below the selection end
|
|
* _k_: select the character above the selection end
|
|
* _l_: select the character on the left of selection end
|
|
|
|
* _w_: select the word and following whitespaces on the right of selection end
|
|
* _b_: select preceding whitespaces and the word on the left of selection end
|
|
* _e_: select preceding whitespaces and the word on the right of selection end
|
|
* _alt-[wbe]_: same as [wbe] but select WORD instead of word
|
|
|
|
* _x_: select line on which selection end lies (or next line when end lies on
|
|
an end-of-line)
|
|
* _alt-x_: expand selections to contain full lines (including end-of-lines)
|
|
|
|
* _%_: select whole buffer
|
|
|
|
* _gh_, _alt-H_: select to line begin
|
|
* _gl_, _alt-L_: select to line end
|
|
|
|
* _gg_, _gt_: go to the first line
|
|
* _gb_: go to the last line
|
|
|
|
* _/_: search (select next match)
|
|
* _?_: search (extend to next match)
|
|
* _n_: select next match
|
|
* _N_: add a new selection with next match
|
|
* _alt-n_: replace last selection with next match (preserving the others)
|
|
|
|
* _alt-c_: center last selection in current window
|
|
* _pageup_: scroll up
|
|
* _pagedown_: scroll down
|
|
|
|
Appending
|
|
---------
|
|
|
|
for most selection commands, using shift permits to extend current selection
|
|
instead of replacing it. for example, _wWW_ selects 3 consecutive words
|
|
|
|
Using Counts
|
|
------------
|
|
|
|
Most selection commands also support counts, which are entered before the
|
|
command itself.
|
|
|
|
for example, _3W_ selects 3 consecutive words and _3w_ select the third word on
|
|
the right of selection end.
|
|
|
|
* _space_: when used with count, keep only the counth selection
|
|
* _alt-space_: when used with count, remove the counth selection
|
|
|
|
Changes
|
|
-------
|
|
|
|
* _i_: insert before current selection
|
|
* _a_: insert after current selection
|
|
* _d_: yank and delete current selection
|
|
* _c_: yank and delete current selection and insert
|
|
|
|
* _I_: insert at current selection begin line start
|
|
* _A_: insert at current selection end line end
|
|
* _o_: insert in a new line below current selection end
|
|
* _O_: insert in a new line above current selection begin
|
|
|
|
* _p_: paste after current selection end
|
|
* _P_: paste before current selection begin
|
|
* _alt-p_: replace current selection with yanked text
|
|
|
|
* _alt-j_: join selected lines
|
|
|
|
* _>_: indent selected lines
|
|
* _<_: deindent selected lines
|
|
|
|
* _|_: pipe each selections through the given external filter program
|
|
and replace with it's output.
|
|
|
|
* _u_: undo last change
|
|
* _U_: redo last change
|
|
|
|
Multi Selection
|
|
---------------
|
|
|
|
Kak was designed from the start to handle multiple selections.
|
|
One way to get a multiselection is via the _s_ key.
|
|
|
|
For example, to change all occurences of word 'roger' to word 'marcel'
|
|
in a paragraph, here is what can be done:
|
|
|
|
select the paragraph with enough _x_. press _s_ and enter roger then enter.
|
|
now paragraph selection was replaced with multiselection of each roger in
|
|
the paragraph. press _c_ and marcel<esc> to replace rogers with marcels.
|
|
|
|
A multiselection can also be obtained with _S_, which splits the current
|
|
selection according to the regex entered. To split a comma separated list,
|
|
use _S_ then ', *'
|
|
|
|
_s_ and _S_ share the search pattern with _/_, and hence entering an empty
|
|
pattern uses the last one.
|
|
|
|
As a convenience, _alt-s_ allows you to split the current selections on
|
|
line boundaries.
|
|
|
|
To clear multiple selections, use _space_. To keep only the nth selection
|
|
use _n_ followed by _space_, to remove only the nth selection, use _n_
|
|
followed by _alt-space_.
|
|
|
|
Object Selection
|
|
----------------
|
|
|
|
Some keys allow you to select a text object:
|
|
|
|
* _alt-a_: selects the whole object
|
|
* _alt-i_: selects the inner object, that is the object excluding it's surrounder.
|
|
for example, for a quoted string, this will not select the quote, and
|
|
for a word this will not select trailing spaces.
|
|
* _[_: selects to object start
|
|
* _]_: selects to object end
|
|
|
|
After this key, you need to enter a second key in order to specify which
|
|
object you want.
|
|
|
|
* _b_, _(_ or _)_: select the enclosing parenthesis
|
|
* _B_, _{_ or _}_: select the enclosing {} block
|
|
* _[_ or _]_: select the enclosing [] block
|
|
* _<_ or _>_: select the enclosing <> block
|
|
* _"_: select the enclosing double quoted string
|
|
* _'_: select the enclosing single quoted string
|
|
* _w_: select the whole word
|
|
* _W_: select the whole WORD
|
|
|
|
Registers
|
|
---------
|
|
|
|
registers are named list of text. They are used for various purpose, like
|
|
storing the last yanked test, or the captures groups associated with the
|
|
last selection.
|
|
|
|
While in insert mode, ctrl-r followed by a register name (one character)
|
|
inserts it.
|
|
|
|
For example, ctrl-r followed by " will insert the currently yanked text.
|
|
ctrl-r followed by 2 will insert the second capture group from the last regex
|
|
selection.
|
|
|
|
Registers are lists, instead of simply text in order to interact well with
|
|
multiselection. Each selection have it's own captures, or yank buffer.
|
|
|
|
Search selection
|
|
----------------
|
|
|
|
Using the _*_ key, you can set the search pattern to the current selection.
|
|
This tries to be intelligent. It will for example detect if current selection
|
|
begins and/or end at word boundaries, and set the search pattern accordingly.
|
|
|
|
Basic Commands
|
|
--------------
|
|
|
|
Commands are entered using +:+.
|
|
|
|
* +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.
|
|
* +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.
|
|
* +name <name>+: set current client name
|
|
* +exec [-client <name>] <keys>+: execute <keys> as if pressed in normal mode.
|
|
if client if specified, exec keys in the named client context.
|
|
* +eval [-client <name>] <command>+: execute <command> as if entered in command line
|
|
if client if specified, exec command in the named client context.
|
|
* +echo <text>+: show <text> in status line
|
|
* +decl <type> <name> [<value>]+: declare an option, type can be int, str, int-list
|
|
and str-list.
|
|
* +set{b,w,g} <option> <value>+: set <option> to <value> in *b*uffer, *w*indow
|
|
or *g*lobal scope.
|
|
* +name <name>+: sets current client name to name
|
|
* +c[ol]a[lias] <name> <colspec>+: define a color alias, so that name can be
|
|
used instead of colspec in contexts where a color is needed.
|
|
* +nop+: does nothing, but as with every other commands, arguments may be
|
|
evaluated. So nop can be used for example to execute a shell command
|
|
while being sure that it's output will not be interpreted by kak.
|
|
+:%sh{ echo echo tchou }+ will echo tchou in kakoune, whereas
|
|
+:nop %sh{ echo echo tchou }+ will not, but both will execute the
|
|
shell command.
|
|
|
|
String syntax
|
|
-------------
|
|
|
|
When entering a command, parameters are separated by whitespace (shell like),
|
|
if you want to give parameters with spaces, you should quote them.
|
|
|
|
Kakoune support three string syntax:
|
|
|
|
* +"strings" and \'strings\'+: classic strings, use \' or \" to escape the
|
|
separator.
|
|
|
|
* +%\{strings\}+: these strings are very useful when entering commands
|
|
|
|
- the '{' and '}' delimiter are configurable: you can use any non
|
|
alphanumeric character. like %[string], %<string>, %(string), %~string~
|
|
or %!string!...
|
|
- if the character following the % is one of {[(<, then
|
|
the closing one is the matching }])>, and these delimiters in the string
|
|
need not to be escaped if the contained delimiters are balanced.
|
|
for example +%{ roger {}; }+ is a valid string.
|
|
|
|
Highlighters
|
|
------------
|
|
|
|
Manipulation of the displayed text is done through highlighters, which can be added
|
|
or removed with the command
|
|
|
|
-----------------------------------------------------
|
|
:addhl <highlighter_name> <highlighter_parameters...>
|
|
-----------------------------------------------------
|
|
|
|
and
|
|
|
|
----------------------
|
|
:rmhl <highlighter_id>
|
|
----------------------
|
|
|
|
existing highlighters are:
|
|
|
|
* +number_lines+: show line numbers
|
|
* +group <group_name>+: highlighter group, containing other highlighters.
|
|
useful when multiple highlighters work together and need to be
|
|
removed as one. Adding and removing from a group can be done using
|
|
`:addhl -group <group> <highlighter_name> <highlighter_parameters...>`
|
|
`:rmhl -group <group> <highlighter_name>`
|
|
* +regex <ex> <color>...+: highlight a regex, takes the regex as first parameter,
|
|
followed by any number of color parameters. color format is:
|
|
<capture_id>:<fg_color>[,<bg_color>]
|
|
For example: `:addhl regex //(\h+TODO:)?[^\n]+ 0:cyan 1:yellow,red`
|
|
will highlight C++ style comments in cyan, with an eventual 'TODO:' in
|
|
yellow on red background.
|
|
* +search <color>+: highlight every matches to the current search pattern. takes
|
|
one parameter for the color to apply to highlighted elements.
|
|
* +flag_lines <flag> <option_name>+: add a column in front of text, and display the
|
|
given flag in it for everly lines contained in the int-list option named
|
|
<option_name>.
|
|
|
|
Filters
|
|
-------
|
|
|
|
Filters can be installed to interact with buffer modifications. They can be
|
|
added or removed with
|
|
|
|
-----------------------------------------------
|
|
:addfilter <filter_name> <filter_parameters...>
|
|
-----------------------------------------------
|
|
|
|
and
|
|
|
|
---------------------
|
|
:rmfilter <filter_id>
|
|
---------------------
|
|
|
|
exisiting filters are:
|
|
|
|
* +preserve_indent+: insert previous line indent when inserting a newline
|
|
* +cleanup_whitespaces+: remove trailing whitespaces on the previous line
|
|
when inserting an end-of-line.
|
|
* +expand_tabulations+: insert spaces instead of tab characters
|
|
* +regex <line_regex> <insert_regex> <replacement>+: when the current line regex
|
|
and inserted text regex matches, replace insereted text with the
|
|
replacement text. Capture groups are available through $[0-9] escape
|
|
sequence, and cursor position can be specified with $c.
|
|
* +group+: same as highlighters group
|
|
|
|
Hooks
|
|
-----
|
|
|
|
commands can be registred to be executed when certain events arise.
|
|
to register a hook, use the hook command.
|
|
|
|
------------------------------------------------------
|
|
:hook <scope> <hook_name> <filtering_regex> <commands>
|
|
------------------------------------------------------
|
|
|
|
<scope> can be either global, buffer or window, the scope are hierarchical,
|
|
meaning that a Window calling a hook will execute it's own, the buffer ones
|
|
and the global ones.
|
|
|
|
<command> is a string containing the commands to execute when the hook is
|
|
called.
|
|
|
|
for example, to automatically use line numbering with .cc files,
|
|
use the following command:
|
|
|
|
-----------------------------------------------------
|
|
:hook global WinCreate .*\.cc %{ addhl number_lines }
|
|
-----------------------------------------------------
|
|
|
|
Shell expansion
|
|
---------------
|
|
|
|
A special string syntax is supported which replace it's content with the
|
|
output of the shell commands in it, it is similar to the shell $(...)
|
|
syntax and is evaluated only when needed.
|
|
for example: %sh{ ls } is replaced with the output of the ls command.
|
|
|
|
Some of kakoune state is available through environment variables:
|
|
|
|
* +kak_selection+: content of the last selection
|
|
* +kak_bufname+: name of the current buffer
|
|
* +kak_timestamp+: timestamp of the current buffer, the timestamp is an
|
|
integer value which is incremented each time the buffer is modified.
|
|
* +kak_runtime+: directory containing the kak binary
|
|
* +kak_opt_<name>+: value of option <name>
|
|
* +kak_reg_<r>+: value of register <r>
|
|
* +kak_socket+: filename of session socket (/tmp/kak-<session>)
|
|
* +kak_client+: name of current client
|
|
* +kak_cursor_line+: line of the end of the last selection
|
|
* +kak_cursor_cursor+: cursor of the end of the last selection
|
|
|
|
for example you can print informations on the current file in the status
|
|
line using:
|
|
|
|
-------------------------------
|
|
:echo %sh{ ls -l $kak_bufname }
|
|
-------------------------------
|
|
|
|
Register and Option expansion
|
|
-----------------------------
|
|
|
|
Similar to shell expansion, register contents and options values can be
|
|
accessed through %reg{<register>} and %opt{<option>} syntax.
|
|
|
|
for example you can display last search pattern with
|
|
|
|
-------------
|
|
:echo %reg{/}
|
|
-------------
|
|
|
|
Defining Commands
|
|
-----------------
|
|
|
|
new commands can be defined using the +def+ command.
|
|
|
|
------------------------------
|
|
:def <command_name> <commands>
|
|
------------------------------
|
|
|
|
<commands> is a string containing the commands to execute
|
|
|
|
def can also takes some flags:
|
|
|
|
* +-env-params+: pass parameters given to commands in the environement as
|
|
kak_paramN with N the parameter number
|
|
* +-shell-params+: pass parameters given to commands as positional parameters
|
|
to any shell expansions used in the command.
|
|
* +-file-completion+: try file 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.
|
|
|
|
Using shell expansion permits to define complex commands or to access
|
|
kakoune state:
|
|
|
|
------------------------------------------------------
|
|
:def print_selection %{ echo %sh{ ${kak_selection} } }
|
|
------------------------------------------------------
|
|
|
|
Some helper commands can be used to define composite commands:
|
|
|
|
* +menu <label1> <commands1> <label2> <commands2>...+: display a menu using
|
|
labels, the selected label's commands are executed.
|
|
+menu+ can take a -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 a -anchor
|
|
option, which accepts +left+, +right+ and +cursor+ as value, in order to
|
|
specify where the info box should be anchored relative to the last selection.
|
|
* +try <commands> catch <on_error_commands>+: prevent an error in <commands>
|
|
from aborting the whole commands execution, execute <on_error_commands>
|
|
instead.
|
|
|
|
Note that these commands are available in interactive command mode, but are
|
|
not that useful in this context.
|
|
|
|
FIFO Buffer
|
|
-----------
|
|
|
|
the +edit+ command can take a -fifo parameter:
|
|
|
|
-----------------------------------
|
|
:edit -fifo <filename> <buffername>
|
|
-----------------------------------
|
|
|
|
in this case, a buffer named +<buffername>+ is created which reads its content
|
|
from fifo +<filename>+. When the fifo is written to, the buffer is automatically
|
|
updated.
|
|
|
|
This is very useful for running some commands asynchronously while displaying
|
|
their result in a buffer. See rc/make.kak and rc/grep.kak for examples.
|
|
|
|
When the buffer is deleted, the fifo will be closed, so any program writing
|
|
to it will receive SIGPIPE. This is usefull as it permits to stop the writing
|
|
program when the buffer is deleted.
|
|
|
|
Menus
|
|
-----
|
|
|
|
When a menu is displayed, you can use *j*, *control-n* or *tab* to select the next
|
|
entry, and *k*, *control-p* or *shift-tab* to select the previous one.
|
|
|
|
Using the */* key, you can enter some regex in order to restrict available choices
|
|
to the matching ones.
|
|
|
|
Kakrc
|
|
-----
|
|
|
|
The kakrc file next to the kak binary (in the src directory for the moment)
|
|
is a list of kak commands to be executed at startup.
|
|
|
|
The current behaviour is to execute local user commands in the file
|
|
$HOME/.config/kak/kakrc and in all files in $HOME/.config/kak/autoload
|
|
directory
|
|
|
|
Place links to the files in src/rc/ in your autoload directory in order to
|
|
execute them on startup, or use the runtime command (which sources relative
|
|
to the kak binary) to load them on demand.
|
|
|
|
Existing commands files are:
|
|
|
|
* *rc/kakrc.kak*: provides kak commands files autodetection and highlighting
|
|
* *rc/cpp.kak*: provides c/c++ files autodetection and highlighting and the +alt+
|
|
command for switching from c/cpp file to h/hpp one.
|
|
* *rc/asciidoc.kak*: provides asciidoc files autodetection and highlighting
|
|
* *rc/diff.kak*: provides patches/diff files autodetection and highlighting
|
|
* *rc/git.kak*: provides various git format highlighting (commit message editing,
|
|
interactive rebase)
|
|
* *rc/make.kak*: provides the +make+ and +errjump+ commands along with highlighting
|
|
for compiler output.
|
|
* *rc/grep.kak*: provides the +grep+ and +gjump+ commands along with highlighting
|
|
for grep output.
|
|
* *rc/global.kak*: provides the +tag+ command to jump on a tag definition using
|
|
gnu global tagging system.
|
|
* *rc/ctags.kak*: provides the +tag+ command to jump on a tag definition using
|
|
exuberant ctags files, this script requires the *readtags* binary, available
|
|
in the exuberant ctags package but not installed by default.
|
|
* *rc/client.kak*: provides the +new+ command to launch a new client on the current
|
|
session, if tmux is detected, launch the client in a new tmux split, else
|
|
launch in a new terminal emulator.
|
|
|
|
Certain command files defines options, such as grepcmd (for :grep) or
|
|
termcmd (for :new).
|