326 lines
12 KiB
Plaintext
326 lines
12 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
|
|
|
|
Basic Movement
|
|
--------------
|
|
|
|
* _space_: select the character under selection end
|
|
|
|
* _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
|
|
|
|
* _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
|
|
|
|
Appending
|
|
---------
|
|
|
|
for most selection commands, using shift permits to add to 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-j_: join selected lines
|
|
|
|
* _|_: pipe each selections through the given external filter program
|
|
and replace with it's output.
|
|
|
|
Multi Selection
|
|
---------------
|
|
|
|
Kak was designed from the start to handle multiple selections.
|
|
On 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 _Alt-s_, which splits the current
|
|
selection according to the regex entered. To split a comma separated list,
|
|
use _alt-s_ then ', *'
|
|
|
|
To clear multiple selections, use _space_. To keep only the nth selection
|
|
use _n_ followed by _space_.
|
|
|
|
Object Selection
|
|
----------------
|
|
|
|
Using alt-i and alt-a, you can select some text object, the starting
|
|
point is always the last character of the selection.
|
|
|
|
* _b_, _(_ or _)_: select the enclosing parenthesis
|
|
* _B_, _{_ or _}_: select the enclosing {} block
|
|
* _[_ or _]_: select the enclosing [] block
|
|
* _<_ or _>_: select the enclosing <> block
|
|
* w: select the whole word
|
|
* W: select the whole WORD
|
|
|
|
When it makes sense, _alt-i_ selects the inner object and alt-a the whole
|
|
object. For example _alt-i_ ( will only select the inside of the parenthesis,
|
|
for words, the difference between _alt-i_ and _alt-a_ is that _alt-a_ also
|
|
selects the following blanks.
|
|
|
|
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.
|
|
|
|
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>
|
|
* source <filename>: execute commands in <filename>
|
|
* runtime <filename>: execute commands in <filename>, <filename>
|
|
is relative to kak executable path.
|
|
* exec <keys>: execute <keys> as if pressed in normal mode.
|
|
* echo <text>: show <text> in status line
|
|
* set[bwg] <option> <value>: set <option> to <value> in *b*uffer, *w*indow
|
|
or *g*lobal scope.
|
|
|
|
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 usefull when entering commands, first the '{' and '}'
|
|
delimiter is 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:
|
|
|
|
* *highlight_selections*: used to make current selection visible
|
|
* *expand_tabs*: expand tabs to next 8 multiple column (to make configurable)
|
|
* *number_lines*: show line numbers
|
|
* *group*: highlighter group, containing other highlighters. takes one
|
|
parameter, <group_name>. 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*: highlight a regex, takes the regex as first parameter, followed by
|
|
any number of color spec parameters.
|
|
color spec 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.
|
|
|
|
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
|
|
* *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_runtime*: directory containing the kak binary
|
|
* *kak_opt_name*: value of option name
|
|
* *kak_reg_x*: value of register x
|
|
|
|
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.
|
|
* *-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.
|
|
* 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 <filename>. When filename is appended 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.
|