1144 lines
44 KiB
Plaintext
1144 lines
44 KiB
Plaintext
image:https://rawgit.com/mawww/kakoune/master/doc/kakoune_logo.svg[K,30,30] Kakoune image:https://travis-ci.org/mawww/kakoune.svg[link="https://travis-ci.org/mawww/kakoune"]
|
|
=============================================================================================================================================================================
|
|
|
|
TL;DR
|
|
-----
|
|
|
|
*Vim inspired* -- *Faster as in less keystrokes* --
|
|
*Multiple selections* -- *Orthogonal design*
|
|
|
|
---------------------------------------------
|
|
git clone http://github.com/mawww/kakoune.git
|
|
cd kakoune/src
|
|
make
|
|
make userconfig
|
|
./kak
|
|
---------------------------------------------
|
|
|
|
See http://github.com/mawww/golf for kakoune solutions to vimgolf challenges,
|
|
regularly beating the best vim solution.
|
|
|
|
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.
|
|
|
|
Kakoune has a strong focus on interactivity, most commands provide immediate
|
|
and incremental results, while still being competitive (as in keystroke count)
|
|
with Vim.
|
|
|
|
Kakoune works on selections, which are oriented, inclusive range of characters,
|
|
selections have an anchor and a cursor character. Most commands move both of
|
|
them, except when extending selection where the anchor character stays fixed
|
|
and the cursor one moves around.
|
|
|
|
see http://vimeo.com/82711574
|
|
|
|
Join us on freenode IRC +#Kakoune+
|
|
|
|
Features
|
|
--------
|
|
|
|
* Multiple selections as a central way of interacting
|
|
* Powerful selection manipulation primitives
|
|
- Select all regex matches in current selections
|
|
- Keep selections containing/not containing a match for a given regex
|
|
- Split current selections with a regex
|
|
- Text objects (paragraph, sentence, nestable blocks)
|
|
* Powerful text manipulation primitives
|
|
- Align selections
|
|
- Rotate selection contents
|
|
- Case manipulation
|
|
- Indentation
|
|
- Piping each selection to external filter
|
|
* Client-Server architecture
|
|
- Multiple clients on the same editing session
|
|
- Use tmux or your X11 window manager to manage windows
|
|
* Simple interaction with external programs
|
|
* Automatic contextual help
|
|
* Automatic as you type completion
|
|
* Macros
|
|
* Hooks
|
|
* Syntax Highlighting
|
|
- Supports multiple languages in the same buffer
|
|
- Highlight a buffer differently in different windows
|
|
|
|
Building
|
|
--------
|
|
|
|
Kakoune dependencies are:
|
|
|
|
* A C++11 compliant compiler (GCC >= 4.8.1 or clang >= 3.4)
|
|
* boost (>= 1.50)
|
|
* ncurses with wide-characters support (>= 5.3, generally refered as libncursesw)
|
|
|
|
To build, just type *make* in the src directory
|
|
|
|
Kakoune can be built on Linux, MacOS, and Cygwin. Due to Kakoune relying heavily
|
|
on being in an Unix like environment, no native Windows version is planned.
|
|
|
|
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.
|
|
|
|
Installing
|
|
----------
|
|
|
|
In order to install kak on your system, rather than running it directly from
|
|
it's source directory, type *make install*, you can specify the +PREFIX+ and
|
|
+DESTDIR+ if needed.
|
|
|
|
Note that by default, no script files will be read if you do not add links
|
|
to them in $XDG_CONFIG_HOME/kak/autoload. Available script files will be
|
|
installed in $PREFIX/share/kak/rc
|
|
|
|
If you want to enable all files, set $XDG_CONFIG_HOME/kak/autoload to be
|
|
a symbolic link to the $PREFIX/share/kak/rc directory.
|
|
|
|
----------------------------------------------
|
|
ln -s /usr/share/kak/rc ~/.config/kak/autoload
|
|
----------------------------------------------
|
|
|
|
Homebrew (OSX)
|
|
~~~~~~~~~~~~~~
|
|
|
|
-----------------------------------------------------------------------------------------------
|
|
brew install --HEAD https://raw.githubusercontent.com/mawww/kakoune/homebrew/contrib/kakoune.rb
|
|
-----------------------------------------------------------------------------------------------
|
|
|
|
Fedora 20/21/22/Rawhide & Epel 7
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Use created copr repository https://copr.fedoraproject.org/coprs/jkonecny/kakoune/
|
|
---------------------------------
|
|
dnf copr enable jkonecny/kakoune
|
|
dnf install kakoune
|
|
---------------------------------
|
|
|
|
Exherbo
|
|
~~~~~~~
|
|
|
|
--------------------------------
|
|
cave resolve -x repository/mawww
|
|
cave resolve -x kakoune
|
|
--------------------------------
|
|
|
|
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, sessions are unix sockets
|
|
+/tmp/kak-<session>+
|
|
* +-e <commands>+: execute commands on startup
|
|
* +-n+: ignore kakrc file
|
|
* +-s <session>+: set the session name, by default it will be the pid
|
|
of the initial kak process.
|
|
* +-d+: run Kakoune in daemon mode, without user interface. This requires
|
|
the session name to be specified with -s. In this mode, the Kakoune
|
|
server will keep running even if there is no connected client, and
|
|
will quit when receiving SIGTERM.
|
|
* +-p <session>+: read stdin, and then send its content to the given session
|
|
acting as a remote control.
|
|
* +-f <keys>+: Work as a filter, read every file given on the command line
|
|
and stdin if piped in, and apply given keys on each.
|
|
|
|
At startup, if +-n+ is not specified, Kakoune will try to source the file
|
|
../share/kak/kakrc relative to the kak binary. This kak file will then try
|
|
to source any files in $XDG_CONFIG_HOME/kak/autoload (with $XDG_CONFIG_HOME
|
|
defaulting to $HOME/.config), and finally $XDG_CONFIG_HOME/kak/kakrc.
|
|
|
|
The common pattern is to add links to $XDG_CONFIG_HOME/kak/autoload to the
|
|
scripts in $PREFIX/share/kak/rc that the user wants sourced at kak launch.
|
|
|
|
Basic Movement
|
|
--------------
|
|
|
|
* +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)
|
|
* +alt-X+: trim selections to only contain full lines (not including last
|
|
end-of-line)
|
|
|
|
* +%+: select whole buffer
|
|
|
|
* +alt-H+: select to line begin
|
|
* +alt-L+: select to line end
|
|
|
|
* +/+: search (select next match)
|
|
* +?+: search (extend to next match)
|
|
* +n+: select next match
|
|
* +N+: add a new selection with next match
|
|
* +alt-n+: select previous match
|
|
* +alt-N+: add a new selection with previous match
|
|
|
|
* +pageup+: scroll up
|
|
* +pagedown+: scroll down
|
|
|
|
* +alt-r+: rotate selections (the main selection becomes the next one)
|
|
|
|
* +;+: reduce selections to their cursor
|
|
* +alt-;+: flip the selections direction
|
|
* +alt-:+: ensure selections are in forward direction (cursor after anchor)
|
|
|
|
|
|
A word is a sequence of alphanumeric characters or underscore, a WORD is a
|
|
sequence of non whitespace characters.
|
|
|
|
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.
|
|
|
|
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
|
|
* +.+: repeat last insert mode change (+i+, +a+, or +c+, including
|
|
the inserted text)
|
|
|
|
* +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
|
|
|
|
* +y+: yank selections
|
|
* +p+: paste after current selection end
|
|
* +P+: paste before current selection begin
|
|
* +alt-p+: paste all after current selection end, and
|
|
select each pasted string.
|
|
* +alt-P+: paste all before current selection begin, and
|
|
select each pasted string.
|
|
* +R+: replace current selection with yanked text
|
|
|
|
* +r+: replace each character with the next entered one
|
|
|
|
* +alt-j+: join selected lines
|
|
* +alt-J+: join selected lines and select spaces inserted
|
|
in place of line breaks
|
|
|
|
* +>+: indent selected lines
|
|
* +<+: deindent selected lines
|
|
* +alt->+: indent selected lines, including empty lines
|
|
* +<+: deindent selected lines
|
|
* +alt-<+: deindent selected lines, do not remove incomplete
|
|
indent (3 leading spaces when indent is 4)
|
|
|
|
* +|+: pipe each selections through the given external filter program
|
|
and replace the selection with it's output.
|
|
* +alt-|+: pipe each selections through the given external filter program
|
|
and ignore its output
|
|
|
|
* +!+: insert command output before selection
|
|
* +a-!+: append command output after selection
|
|
|
|
* +u+: undo last change
|
|
* +U+: redo last change
|
|
|
|
* +&+: align selection, align the cursor of selections by inserting
|
|
spaces before the first character of the selection
|
|
* +alt-&+: copy indent, copy the indentation of the main selection
|
|
(or the count one if a count is given) to all other ones
|
|
|
|
* +`+: to lower case
|
|
* +~+: to upper case
|
|
* +alt-`+: swap case
|
|
|
|
* +@+: convert tabs to spaces in current selections, uses the buffer
|
|
tabstop option or the count parameter for tabstop.
|
|
* +alt-@+: convert spaces to tabs in current selections, uses the buffer
|
|
tabstop option or the count parameter for tabstop.
|
|
|
|
* +alt-R+: rotate selections content, if specified, the count groups
|
|
selections, so +3<a-R>+ rotate (1, 2, 3) and (3, 4, 6)
|
|
independently.
|
|
|
|
Goto Commands
|
|
-------------
|
|
|
|
Commands begining with g are used to goto certain position and or buffer:
|
|
|
|
* +gh+: select to line begin
|
|
* +gl+: select to line end
|
|
|
|
* +gg+, +gk+: go to the first line
|
|
* +gj+: go to the last line
|
|
|
|
* +gt+: go to the first displayed line
|
|
* +gc+: go to the middle displayed line
|
|
* +gb+: go to the last displayed line
|
|
|
|
* +ga+: go to the previous (alternate) buffer
|
|
* +gf+: open the file whose name is selected
|
|
|
|
* +g.+: go to last buffer modifiction position
|
|
|
|
View commands
|
|
-------------
|
|
|
|
Some commands, all begining with v permit to manipulate the current
|
|
view.
|
|
|
|
* +vv+ or +vc+: center the main selection in the window
|
|
* +vt+: scroll to put the main selection on the top line of the window
|
|
* +vb+: scroll to put the main selection on the bottom line of the window
|
|
* +vh+: scroll the window count columns left
|
|
* +vj+: scroll the window count line downward
|
|
* +vk+: scroll the window count line upward
|
|
* +vl+: scroll the window count columns right
|
|
|
|
Jump list
|
|
---------
|
|
|
|
Some commands, like the goto commands, buffer switch or search commands,
|
|
push the previous selections to the client's jump list. It is possible
|
|
to forward or backward in the jump list using:
|
|
|
|
* +control-i+: Jump forward
|
|
* +control-o+: Jump backward
|
|
* +control-s+: save current selections
|
|
|
|
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+, in order to remove a selection, use +alt-space+.
|
|
|
|
+alt-k+ allows you to enter a regex and keep only the selections that
|
|
contains a match for this regex. using +alt-K+ you can keep the selections
|
|
not containing a match.
|
|
|
|
+C+ copies the current selection to the next line (or lines if a count is given)
|
|
+alt-C+ does the same to previous lines.
|
|
|
|
+$+ allows you to enter a shell command and pipe each selections to it.
|
|
Selections whose shell command returns 0 will be kept, other will be dropped.
|
|
|
|
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
|
|
* +{+: extends selections to object start
|
|
* +}+: extends selections 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
|
|
* +r+, +[+ or +]+: select the enclosing [] block
|
|
* +a+, +<+ or +>+: select the enclosing <> block
|
|
* +"+: select the enclosing double quoted string
|
|
* +'+: select the enclosing single quoted string
|
|
* +`+: select the enclosing grave quoted string
|
|
* +w+: select the whole word
|
|
* +W+: select the whole WORD
|
|
* +s+: select the sentence
|
|
* +p+: select the paragraph
|
|
* +␣+: select the whitespaces
|
|
* +i+: select the current indentation block
|
|
* +n+: select the number
|
|
|
|
For nestable objects, a count can be used in order to specify which surrounding
|
|
level to select.
|
|
|
|
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
|
|
selections.
|
|
|
|
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.
|
|
|
|
Macros
|
|
------
|
|
|
|
Kakoune can record and replay a sequence of key press.
|
|
|
|
When pressing the +Q+ key, followed by an alphabetic key for the macro name,
|
|
Kakoune begins macro recording: every pressed keys will be added to the
|
|
macro until the +Q+ key is pressed again.
|
|
|
|
To replay a macro, use the +q+ key, followed by the macro name.
|
|
|
|
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.
|
|
|
|
with +alt-*+ you can set the search pattern to the current seletion without
|
|
Kakoune trying to be smart.
|
|
|
|
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.
|
|
* +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.
|
|
* +nameclient <name>+: set current client name
|
|
* +namebuf <name>+: set current buffer name
|
|
* +echo <text>+: show <text> in status line
|
|
* +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.
|
|
|
|
Exec and Eval
|
|
-------------
|
|
|
|
the +:exec+ and +:eval+ commands can be used for running Kakoune commands.
|
|
+:exec+ keys as if they were pressed, whereas +:eval+ executes it's given
|
|
paremeters as if they were entered in the command prompt. By default,
|
|
they do their execution in the context of the current client.
|
|
|
|
Some parameters provide a way to change the context of execution:
|
|
|
|
* +-client <name>+: execute in the context of the client named <name>
|
|
* +-try-client <name>+: execute in the context of the client named
|
|
<name> if such client exists, or else in the current context.
|
|
* +-draft+: execute in a copy of the context of the selected client
|
|
modifications to the selections or input state will not affect
|
|
the client. This permits to make some modification to the buffer
|
|
without modifying the user's selection.
|
|
* +-itersel+ (requires +-draft+): execute once per selection, in a
|
|
context with only the considered selection. This permits to avoid
|
|
cases where the selections may get merged.
|
|
* +-buffer <names>+: execute in the context of each buffers in the
|
|
comma separated list <names>
|
|
* +-no-hooks+: disable hook execution while executing the keys/commands
|
|
|
|
The execution stops when the last key/command is reached, or an error
|
|
is raised.
|
|
|
|
key parameters gets concatenated, so the following commands are equivalent.
|
|
|
|
----------------------
|
|
:exec otest<space>1
|
|
:exec o test <space> 1
|
|
----------------------
|
|
|
|
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\'+: uninterpreted strings, you can use \' to escape the separator,
|
|
every other char is itself.
|
|
|
|
* +"strings"+: expended strings, % strings (see %sh, %opt or %reg) contained
|
|
are expended. Use \% to escape a % inside them, and \\ to escape a slash.
|
|
|
|
* +%\{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 the delimiters are not escapable but are nestable.
|
|
for example +%{ roger {}; }+ is a valid string, +%{ marcel \}+ as well.
|
|
|
|
Options
|
|
-------
|
|
|
|
For user configuration, Kakoune supports options.
|
|
|
|
Options are typed, their type can be
|
|
|
|
* +int+: an integer number
|
|
* +bool+: a boolean value, +yes/true+ or +no/false+
|
|
* +yesnoask+: similar to a boolean, but the additional
|
|
value +ask+ is supported.
|
|
* +str+: a string, some freeform text
|
|
* +coord+: a line,column pair (separated by comma)
|
|
* +regex+: as a string but the +set+ commands will complain
|
|
if the entered text is not a valid regex.
|
|
* +{int,str}-list+: a list, elements are separated by a colon (:)
|
|
if an element needs to contain a colon, it can be escaped with a
|
|
backslash.
|
|
|
|
Options value can be changed using the +set+ commands:
|
|
|
|
--------------------------------------------------------------
|
|
:set [global,buffer,window] <option> <value> # buffer, window, or global scope
|
|
--------------------------------------------------------------
|
|
|
|
Option values can be different by scope, an option can have a global
|
|
value, a buffer value and a window value. The effective value of an
|
|
option depends on the current context. If we have a window in the
|
|
context (interactive edition for example), then the window value
|
|
(if any) is used, if not we try the buffer value (if we have a buffer
|
|
in the context), and if not we use the global value.
|
|
|
|
That means that two windows on the same buffer can use different options
|
|
(like different filetype, or different tabstop). However some options
|
|
might end up ignored if their scope is not in the command context:
|
|
|
|
Writing a file never uses the window options for example, so any
|
|
options related to writing wont be taken into account if set in the
|
|
window scope (+BOM+ or +eolformat+ for example).
|
|
|
|
New options can be declared using the +:decl+ command:
|
|
|
|
---------------------------------------
|
|
:decl [-hidden] <type> <name> [<value>]
|
|
---------------------------------------
|
|
|
|
the +-hidden+ parameter makes the option invisible in completion, but
|
|
still modifiable.
|
|
|
|
Some options are built in Kakoune, and can be used to control it's behaviour:
|
|
|
|
* +tabstop+ _int_: width of a tab character.
|
|
* +indentwidth+ _int_: width (in spaces) used for indentation.
|
|
0 means a tab character.
|
|
* +scrolloff+ _coord_: number of lines,columns to keep visible around
|
|
the cursor when scrolling.
|
|
* +eolformat+ _string_ ('lf' or 'crlf'): the format of end of lines when
|
|
writing a buffer, this is autodetected on load.
|
|
* +BOM+ _string_ ("no" or "utf-8"): define if the file should be written
|
|
with an unicode byte order mark.
|
|
* +complete_prefix+ _bool_: when completing in command line, and multiple
|
|
candidates exist, enable completion with common prefix.
|
|
* +incsearch+ _bool_: execute search as it is typed
|
|
* +aligntab+ _bool_: use tabs for alignement command
|
|
* +autoinfo+ _bool_: display automatic information box for certain commands.
|
|
* +autoshowcompl+ _bool_: automatically display possible completions when
|
|
editing a prompt.
|
|
* +ignored_files+ _regex_: filenames matching this regex wont be considered
|
|
as candidates on filename completion (except if the text being completed
|
|
already matches it).
|
|
* +disabled_hooks+ _regex_: hooks whose group matches this regex wont be
|
|
executed. For example indentation hooks can be disabled with '.*-indent'.
|
|
* +filetype+ _str_: arbitrary string defining the type of the file
|
|
filetype dependant actions should hook on this option changing for
|
|
activation/deactivation.
|
|
* +path+ _str-list_: directories to search for gf command.
|
|
* +completers+ _str-list_: completion systems to use for insert mode
|
|
completion. given completers are tried in order until one generate some
|
|
completion candidates. Existing completers are:
|
|
- +word=all+ or +word=buffer+ which complete using words in all buffers
|
|
(+word=all+) or only the current one (+word=buffer+)
|
|
- +filename+ which tries to detect when a filename is being entered and
|
|
provides completion based on local filesystem.
|
|
- +option=<opt-name>+ where <opt-name> is a _str-list_ option. The first
|
|
element of the list should follow the format:
|
|
_<line>.<column>[+<length>]@<timestamp>_ to define where the completion
|
|
apply in the buffer, and the other strings are the candidates.
|
|
* +autoreload+ _yesnoask_: auto reload the buffers when an external
|
|
modification is detected.
|
|
* +ui_options+: colon separated list of key=value pairs that are forwarded to
|
|
the user interface implementation. The NCurses UI support the following option:
|
|
- +ncurses_status_on_top+: if +yes+, or +true+ the status line will be placed
|
|
at the top of the terminal rather than at the bottom.
|
|
|
|
Insert mode completion
|
|
----------------------
|
|
|
|
Kakoune can propose completions while inserting text, the +completers+ option
|
|
control automatic completion, which kicks in when a certain idle timeout is
|
|
reached (100 milliseconds). Insert mode completion can be explicitely triggered
|
|
using *control-x*, followed, by:
|
|
|
|
* *f* : filename completion
|
|
* *w* : buffer word completion
|
|
* *l* : buffer line completion
|
|
* *o* : option based completion
|
|
|
|
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>
|
|
----------------------
|
|
|
|
general highlighters are:
|
|
|
|
* +regex <ex> <capture_id>:<face>...+: highlight a regex, takes the regex as
|
|
first parameter, followed by any number of face parameters.
|
|
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+: highlight every matches to the current search pattern with the
|
|
+Search+ face
|
|
* +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>.
|
|
* +show_matching+: highlight matching char of the character under the selections
|
|
cursor using +MatchingChar+ face.
|
|
* +number_lines <-relative> <-hlcursor>+: show line numbers. The -relative switch
|
|
will show line numbers to main cursor line, the -hlcursor switch will
|
|
highlight the cursor line with a separate face..
|
|
* +fill <face>+: fill using given face, mostly useful with the +regions+ highlighter
|
|
(see below)
|
|
|
|
Highlighting Groups
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
the +group+ highlighter is a container for other highlighters. You can add
|
|
a group to the current window using
|
|
|
|
------------------
|
|
addhl group <name>
|
|
------------------
|
|
|
|
and then the +-group+ switch of +addhl+ provides a mean to add highlighters
|
|
inside this group.
|
|
|
|
--------------------------------------
|
|
addhl -group <name> <type> <params>...
|
|
--------------------------------------
|
|
|
|
groups can contain other groups, the +-group+ switch can be used to define a path.
|
|
|
|
------------------------------------------------
|
|
addhl -group <name> group <subname>
|
|
addhl -group <name>/<subname> <type> <params>...
|
|
------------------------------------------------
|
|
|
|
Regions highlighters
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
A special highlighter provide a way to segment the buffer into regions, which are
|
|
to be highlighted differently.
|
|
|
|
A region is defined by 4 parametes:
|
|
|
|
------------------------------------
|
|
<name> <opening> <closing> <recurse>
|
|
------------------------------------
|
|
|
|
+name+ is user defined, +opening+, +closing+ and +recurse+ are regexes.
|
|
|
|
* +opening+ defines the region start text
|
|
* +closing+ defines the region end text
|
|
* +recurse+ defines the text that matches recursively an end token into the region.
|
|
|
|
+recurse+ is useful for regions that can be nested, for example the +%sh{ ... }+
|
|
construct in kakoune accept nested +{ ... }+ so +%sh{ ... { ... } ... }+ is valid.
|
|
this region can be defined with:
|
|
|
|
------------------------
|
|
shell_expand %sh\{ \} \{
|
|
------------------------
|
|
|
|
Regions are used in the +regions+ highlighter which can take any number
|
|
of regions.
|
|
|
|
-----------------------------------------------------------------------
|
|
addhl regions <name> <region_name1> <opening1> <closing1> <recurse1> \
|
|
<region_name2> <opening2> <closing2> <recurse2>...
|
|
-----------------------------------------------------------------------
|
|
|
|
defines multiple regions in which other highlighters can be added
|
|
|
|
-------------------------------------
|
|
addhl -group <name>/<region_name> ...
|
|
-------------------------------------
|
|
|
|
Regions are matched using the left-most rule: the left-most region opening starts
|
|
a new region. when a region closes, the closest next opening start another region.
|
|
|
|
That matches the rule governing most programming language parsing.
|
|
|
|
+regions+ also supports a +-default <default_region>+ switch to define the
|
|
default region, when no other region matches the current buffer range.
|
|
|
|
most programming languages can then be properly highlighted using a +regions+
|
|
highlighter as root:
|
|
|
|
-----------------------------------------------------------------
|
|
addhl multi_region -default code <lang> \
|
|
string <str_opening> <str_closing> <str_recurse> \
|
|
comment <comment_opening> <comment_closing> <comment_recurse>
|
|
|
|
addhl -group <lang>/code ...
|
|
addhl -group <lang>/string ...
|
|
addhl -group <lang>/comment ...
|
|
-----------------------------------------------------------------
|
|
|
|
Shared Highlighters
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
Highlighters are often defined for a specific filetype, and it makes then sense to
|
|
share the highlighters between all the windows on the same filetypes.
|
|
|
|
A shared highlighter can be defined with the +:addhl+ command
|
|
|
|
------------------------------
|
|
addhl -group /<group_name> ...
|
|
------------------------------
|
|
|
|
when the group switch values starts with a '/', it references a group in the
|
|
shared highlighters, rather than the window highlighters.
|
|
|
|
The common case would be to create a named shared group, and then fill it
|
|
with highlighters:
|
|
|
|
---------------------------
|
|
addhl -group / group <name>
|
|
addhl -group /name regex ...
|
|
---------------------------
|
|
|
|
It can then be referenced in a window using the +ref+ highlighter.
|
|
|
|
----------------
|
|
addhl ref <name>
|
|
----------------
|
|
|
|
the +ref+ can reference any named highlighter in the shared namespace.
|
|
|
|
Hooks
|
|
-----
|
|
|
|
commands can be registred to be executed when certain events arise.
|
|
to register a hook, use the hook command.
|
|
|
|
-----------------------------------------------------------------------
|
|
:hook [-group <group>] <scope> <hook_name> <filtering_regex> <commands>
|
|
-----------------------------------------------------------------------
|
|
|
|
<scope> can be either global, buffer or window (or any of their prefixes),
|
|
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 }
|
|
-----------------------------------------------------
|
|
|
|
if <group> is given, make this hook part of the named group. groups
|
|
are used for removing hooks with the +rmhooks+ command
|
|
|
|
-----------------------
|
|
rmhooks <scope> <group>
|
|
-----------------------
|
|
|
|
will remove every hooks in <scope> that are part of the given group.
|
|
|
|
existing hooks are:
|
|
|
|
* +NormalIdle+: A certain duration has passed since last key was pressed in
|
|
normal mode.
|
|
* +NormalBegin+: Entering normal mode
|
|
* +NormalEnd+: Leaving normal mode
|
|
* +NormalKey+: A key is received in normal mode, the key is used for filtering
|
|
* +InsertIdle+: A certain duration has passed since last key was pressed in
|
|
insert mode.
|
|
* +InsertBegin+: Entering insert mode
|
|
* +InsertEnd+: Leaving insert mode
|
|
* +InsertKey+: A key is received in insert mode, the key is used for filtering
|
|
* +InsertMove+: The cursor moved (without inserting) in insert mode, the key
|
|
that triggered the move is used for filtering
|
|
* +WinCreate+: A window was created, the filtering text is the buffer name
|
|
* +WinClose+: A window was detroyed, the filtering text is the buffer name
|
|
* +WinDisplay+: A window was bound a client, the filtering text is the buffer
|
|
name
|
|
* +WinSetOption+: An option was set in a window context, the filtering text
|
|
is '<option_name>=<new_value>'
|
|
* +BufSetOption+: An option was set in a buffer context, the filtering text
|
|
is '<option_name>=<new_value>'
|
|
* +BufNew+: A buffer for a new file has been created, filename is used for
|
|
filtering
|
|
* +BufOpen+: A buffer for an existing file has been created, filename is
|
|
used for filtering
|
|
* +BufCreate+: A buffer has been created, filename is used for filtering
|
|
* +BufWritePre+: Executed just before a buffer is written, filename is
|
|
used for filtering.
|
|
* +BufWritePost+: Executed just after a buffer is written, filename is
|
|
used for filtering.
|
|
* +BufClose+: Executed when a buffer is deleted, while it is still valid.
|
|
* +BufCloseFifo+: Executed when a fifo buffer closes its fifo file descriptor
|
|
either because the buffer is being deleted, or because the writing
|
|
end has been closed.
|
|
* +RuntimeError+: an error was encountered while executing an user command
|
|
the error message is used for filtering
|
|
* +KakBegin+: Kakoune started, this is called just after reading the user
|
|
configuration files
|
|
* +KakEnd+: Kakoune is quitting.
|
|
|
|
when not specified, the filtering text is an empty string.
|
|
|
|
Key Mapping
|
|
-----------
|
|
|
|
You can redefine keys meaning using the map command
|
|
|
|
------------------------------------------------------
|
|
:map <scope> <mode> <key> <keys>
|
|
------------------------------------------------------
|
|
|
|
with +scope+ being one of +global, buffer or window+ (or any prefix),
|
|
mode being +insert, normal, prompt, menu or user+ (or any prefix), +key+ being
|
|
a single key name and +keys+ a list of keys.
|
|
|
|
+user+ mode allows for user mapping behind the +,+ key. Keys will be executed in
|
|
normal mode.
|
|
|
|
Faces
|
|
-----
|
|
|
|
A Face refer the how specified text is displayed, a Face has a foreground
|
|
color, a background color, and some attributes.
|
|
|
|
Faces can be defined and modified with the face command.
|
|
|
|
-----------------------
|
|
:face <name> <facespec>
|
|
-----------------------
|
|
|
|
Any place requiring a face can take either a face name defined with the +face+
|
|
command or a direct face description (called _facespec_) with the following
|
|
syntax:
|
|
|
|
--------------------------------
|
|
fg_color[,bg_color][+attributes]
|
|
--------------------------------
|
|
|
|
fg_color and bg_color can be:
|
|
|
|
* A named color: +black, red, green, yellow, blue, magenta, cyan, white+.
|
|
* +default+, which keeps the existing color
|
|
* An rgb color: +rgb:RRGGBB+, with RRGGBB the hexadecimal value of the color.
|
|
|
|
not specifying bg_color uses +default+
|
|
|
|
attributes is a string of letters each defining an attributes:
|
|
|
|
* +u+: Underline
|
|
* +r+: Reverse
|
|
* +b+: Bold
|
|
|
|
Using named faces instead of facespec permits to change the effective faces
|
|
afterward.
|
|
|
|
there are some builtins faces used by internal Kakoune functionalities:
|
|
|
|
* +PrimarySelection+: main selection face for every selected character except
|
|
the cursor
|
|
* +SecondarySelection+: secondary selection face for every selected character
|
|
except the cursor
|
|
* +PrimaryCursor+: cursor of the primary selection
|
|
* +SecondaryCursor+: cursor of the secondary selection
|
|
* +LineNumbers+: face used by the number_lines highlighter
|
|
* +LineNumberAbsolute+: face used to highlight the line number of the main
|
|
selection
|
|
* +MenuForeground+: face for the selected element in menus
|
|
* +MenuBackground+: face for the not selected elements in menus
|
|
* +Information+: face for the informations windows and information messages
|
|
* +Error+: face of error messages
|
|
* +StatusLine+: face used for the status line
|
|
* +StatusCursor+: face used for the status line cursor
|
|
* +Prompt+: face used prompt displayed on the status line
|
|
|
|
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 main selection
|
|
* +kak_selections+: content of the selection separated by colons, colons in
|
|
the selection contents are escapted with a backslash.
|
|
* +kak_bufname+: name of the current buffer
|
|
* +kak_buflist+: the current buffer list, each buffer seperated by a colon
|
|
* +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 main selection
|
|
* +kak_cursor_column+: column of the end of the main selection (in byte)
|
|
* +kak_cursor_char_column+: column of the end of the main selection (in character)
|
|
* +kak_hook_param+: filtering text passed to the currently executing hook
|
|
|
|
Note that in order to make only needed information available, Kakoune needs
|
|
to find the environment variable reference in the shell script executed.
|
|
Hence +%sh{ ./script.sh }+ with +script.sh+ referencing an environment
|
|
variable will not work.
|
|
|
|
for example you can print informations on the current file in the status
|
|
line using:
|
|
|
|
-------------------------------
|
|
:echo %sh{ ls -l $kak_bufname }
|
|
-------------------------------
|
|
|
|
Register, Option and Value 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{/}
|
|
-------------
|
|
|
|
more generally, value accessible through shell can be accessed with
|
|
+%val{<name>}+, with <name> being the environment variable name minus
|
|
the +kak_+ prefix.
|
|
|
|
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 environment 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.
|
|
* +-hidden+: do not show the command in command name completions
|
|
* +-docstring+: define the documentation string for the command
|
|
|
|
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:
|
|
|
|
* +: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.
|
|
* +: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 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 these commands are available in interactive command mode, but are
|
|
not that useful in this context.
|
|
|
|
Aliases
|
|
-------
|
|
|
|
With +:alias+ commands can be given additional names. aliases are scoped, so
|
|
that an alias can refer to one command for a buffer, and to another for another
|
|
buffer.
|
|
|
|
--------------------------------
|
|
:alias <scope> <alias> <command>
|
|
--------------------------------
|
|
|
|
with +<scope>+ being +global+, +buffer+ or +window+, will define +<alias>+ as
|
|
an alias for +<command>+
|
|
|
|
-------------------------------------
|
|
: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>+.
|
|
|
|
FIFO Buffer
|
|
-----------
|
|
|
|
the +:edit+ command can take a -fifo parameter:
|
|
|
|
---------------------------------------------
|
|
:edit -fifo <filename> [-scroll] <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.
|
|
|
|
if the +-scroll+ switch is specified, the initial cursor position will be made
|
|
such as the window displaying the buffer will scroll as new data is read.
|
|
|
|
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/CPP 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/git-tools.kak*: provides some git integration, like +:git-blame+, +:git-show+
|
|
or +:git-diff-show+
|
|
* *rc/make.kak*: provides the +:make+ and +:errjump+ commands along with
|
|
highlighting for compiler output.
|
|
* *rc/man.kak*: provides the +:man+ command
|
|
* *rc/grep.kak*: provides the +:grep+ and +:gjump+ commands along with highlighting
|
|
for grep output.
|
|
* *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.
|
|
* *rc/clang.kak*: provides the +:clang-enable-autocomplete+ command for C/CPP
|
|
insert mode completion support. This requires the clang++ compiler to be
|
|
available. You can use the +clang_options+ option to specify switches to
|
|
be passed to the compiler.
|
|
|
|
Certain command files defines options, such as +grepcmd+ (for +:grep+) +makecmd+
|
|
(for +:make+) or +termcmd+ (for +:new+).
|
|
|
|
Some options are shared with commands. +:grep+ and +:make+ honor the +toolsclient+ option,
|
|
if specified, to open their buffer in it rather than the current client. man honor
|
|
the +docsclient+ option for the same purpose.
|