mirror of
https://github.com/mawww/kakoune.git
synced 2024-12-24 12:02:15 +03:00
1499 lines
57 KiB
Plaintext
1499 lines
57 KiB
Plaintext
= image:{logo}[K,30,30,link="{website}"] Kakoune image:{travis-img}[link="{travis-url}"]
|
|
:logo: https://rawgit.com/mawww/kakoune/master/doc/kakoune_logo.svg
|
|
:website: http://kakoune.org
|
|
:travis-img: https://travis-ci.org/mawww/kakoune.svg?branch=master
|
|
:travis-url: https://travis-ci.org/mawww/kakoune
|
|
:icons: font
|
|
:toc: right
|
|
|
|
TL;DR
|
|
-----
|
|
|
|
{website}
|
|
|
|
*Vim inspired* -- *Faster as in less keystrokes* --
|
|
*Multiple selections* -- *Orthogonal design*
|
|
|
|
---------------------------------------------
|
|
git clone http://github.com/mawww/kakoune.git
|
|
cd kakoune/src
|
|
make
|
|
./kak
|
|
---------------------------------------------
|
|
|
|
See http://github.com/mawww/golf for kakoune solutions to vimgolf challenges,
|
|
regularly beating the best vim solution.
|
|
|
|
See the link:doc/design.asciidoc[design document] for more information on
|
|
Kakoune philosophy and design.
|
|
|
|
:numbered:
|
|
|
|
Introduction
|
|
------------
|
|
|
|
Kakoune is a code editor heavily inspired by Vim, as such most of its
|
|
commands are similar to vi's ones, and it shares Vi's "keystrokes as
|
|
a text editing language" model.
|
|
|
|
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
|
|
|
|
Screenshots
|
|
~~~~~~~~~~~
|
|
|
|
[[screenshot-i3]]
|
|
.Kakoune in i3
|
|
image::doc/screenshot-i3.gif[Kakoune in i3]
|
|
|
|
[[screenshot-tmux]]
|
|
.Kakoune in tmux
|
|
image::doc/screenshot-tmux.gif[Kakoune in tmux]
|
|
|
|
Getting started
|
|
---------------
|
|
|
|
Building
|
|
~~~~~~~~
|
|
|
|
Kakoune dependencies are:
|
|
|
|
* A C++11 compliant compiler (GCC >= 4.8 or clang >= 3.4)
|
|
* boost (>= 1.50)
|
|
* ncurses with wide-characters support (>= 5.3, generally referred to as libncursesw)
|
|
* asciidoc (for the `a2k` tool), to generate man pages
|
|
|
|
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 a Unix-like environment, no native Windows version is planned.
|
|
|
|
Installing
|
|
~~~~~~~~~~
|
|
|
|
In order to install kak on your system, rather than running it directly from
|
|
its source directory, type *make install*, you can specify the `PREFIX` and
|
|
`DESTDIR` if needed.
|
|
|
|
[TIP]
|
|
.Homebrew (OSX)
|
|
====
|
|
NOTE: The ncurses library that comes with OSX is not new enough to support some of the mouse based features of Kakoune
|
|
(only tested on OSX 10.11.3, where the packaged ncurses library is version 5.4, whereas the latest version is 6.0).
|
|
Currently, a fresh Kakoune install requires that you install ncurses 6.0. You can install ncurses 6.0 via Homebrew,
|
|
-----------------------------------------------------------------------------------------------
|
|
brew tap homebrew/dupes
|
|
brew install homebrew/dupes/ncurses
|
|
-----------------------------------------------------------------------------------------------
|
|
|
|
Then, to install,
|
|
-----------------------------------------------------------------------------------------------
|
|
brew install --HEAD https://raw.githubusercontent.com/mawww/kakoune/master/contrib/kakoune.rb
|
|
-----------------------------------------------------------------------------------------------
|
|
|
|
To update kakoune,
|
|
-----------------------------------------------------------------------------------------------
|
|
brew reinstall --HEAD https://raw.githubusercontent.com/mawww/kakoune/master/contrib/kakoune.rb
|
|
-----------------------------------------------------------------------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Fedora 22/23/24/Rawhide
|
|
====
|
|
Use the https://copr.fedoraproject.org/coprs/jkonecny/kakoune/[copr] repository.
|
|
|
|
---------------------------------
|
|
dnf copr enable jkonecny/kakoune
|
|
dnf install kakoune
|
|
---------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Arch Linux
|
|
====
|
|
A PKGBUILD https://aur.archlinux.org/packages/kakoune-git[kakoune-git]
|
|
to install Kakoune is available in the https://wiki.archlinux.org/index.php/Arch_User_Repository[AUR].
|
|
|
|
--------------------------------
|
|
# For example build and install Kakoune via yaourt
|
|
yaourt -Sy kakoune-git
|
|
--------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Gentoo
|
|
====
|
|
Kakoune is found in portage as
|
|
https://packages.gentoo.org/packages/app-editors/kakoune[app-editors/kakoune]
|
|
====
|
|
|
|
[TIP]
|
|
.Exherbo
|
|
====
|
|
--------------------------------
|
|
cave resolve -x repository/mawww
|
|
cave resolve -x kakoune
|
|
--------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.openSUSE
|
|
====
|
|
kakoune can be found in the https://build.opensuse.org/package/show/editors/kakoune[editors] devel project.
|
|
Make sure to adjust the link below to point to the repository of your openSUSE version.
|
|
|
|
--------------------------------
|
|
#Example for Tumbleweed:
|
|
sudo zypper addrepo http://download.opensuse.org/repositories/editors/openSUSE_Factory/editors.repo
|
|
sudo zypper refresh
|
|
sudo zypper install kakoune
|
|
--------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Debian
|
|
====
|
|
There is a script in https://github.com/mawww/kakoune/blob/master/contrib/make_deb.bash[contrib/make_deb.bash] that can be used to generate a debian package for kakoune.
|
|
You can then install the generated .deb package with the dpkg tool.
|
|
|
|
--------------------------------
|
|
./make_bash.bash -e "your_email" -f "your_username"
|
|
sudo dpkg -i thePackageName.deb
|
|
--------------------------------
|
|
|
|
====
|
|
|
|
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.
|
|
* `-ui <userinterface>`: use given user interface, `<userinterface>` can be
|
|
- `ncurses`: default terminal user interface
|
|
- `dummy`: empty user interface not displaying anything
|
|
- `json`: json-rpc based user interface that writes json on stdout and
|
|
read keystrokes as json on stdin.
|
|
* `-l`: list existing sessions, and check the dead ones
|
|
* `-clear`: clear dead sessions socket files
|
|
|
|
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 recursively source any files in `$XDG_CONFIG_HOME/kak/autoload` (with
|
|
`$XDG_CONFIG_HOME` defaulting to `$HOME/.config`, and falling back to
|
|
`../share/kak/autoload/` if that autoload directory does not exists), then
|
|
`../share/kak/kakrc.local` if it exists, and finally `$XDG_CONFIG_HOME/kak/kakrc`.
|
|
|
|
That leads to the following behaviour: by default, with no user autoload
|
|
directory, the system wide autoload directory is used, once the user wants
|
|
control on autoloading, they can create an autoload directory and eventually
|
|
symlink individual scripts, or the whole system wide autoload directory. They
|
|
can as well add any new scripts not provided with Kakoune.
|
|
|
|
Basic Interaction
|
|
-----------------
|
|
|
|
Selections
|
|
~~~~~~~~~~
|
|
|
|
The main concept in Kakoune is the selection. A selection is an inclusive,
|
|
directed range of character. A selection has two ends, the anchor and the
|
|
cursor.
|
|
|
|
There is always at least one selection, and a selection is always at least
|
|
one character (in which case the anchor and cursor of the selections are
|
|
on the same character).
|
|
|
|
Normal Mode
|
|
~~~~~~~~~~~
|
|
|
|
In normal mode, keys are not inserted directly inside the buffer, but are editing
|
|
commands. These commands provides ways to manipulate either the selections themselves,
|
|
or the selected text.
|
|
|
|
Insert Mode
|
|
~~~~~~~~~~~
|
|
|
|
When entering insert mode, keys are now directly inserted before each selections
|
|
cursor. Some additional keys are recognised in insert mode:
|
|
|
|
* `<esc>`: leave insert mode
|
|
* `<backspace>`: delete characters before cursors
|
|
* `<del>`: delete characters under cursors
|
|
* `<left>, <right>, <up>, <down>`: move the cursors in given direction
|
|
* `<home>`: move cursors to line begin
|
|
* `<end>`: move cursors to end of line
|
|
|
|
* `<c-n>`: select next completion candidate
|
|
* `<c-p>`: select previous completion candidate
|
|
* `<c-x>`: explicit insert completion query, followed by:
|
|
- `f`: explicit file completion
|
|
- `w`: explicit word completion
|
|
- `l`: explicit line completion
|
|
* `<c-o>`: disable automatic completion for this insert session
|
|
|
|
* `<c-r>`: insert contents of the register given by next key
|
|
* `<c-v>`: insert next keystroke directly into the buffer,
|
|
without interpreting it.
|
|
|
|
* `<c-u>`: commit changes up to now as a single undo group.
|
|
|
|
* `<a-;>`: escape to normal mode for a single command
|
|
|
|
Movement
|
|
~~~~~~~~
|
|
|
|
* `h`: select the character on the left 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 right 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
|
|
|
|
* `f`: select to the next occurence of given character
|
|
* `t`: select until the next occurence of given character
|
|
* `<alt-[ft]>`: same as [ft] but in the other direction
|
|
|
|
* `m`: select to matching character
|
|
* `M`: extend selection to matching character
|
|
|
|
* `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)
|
|
* `alt-/`: search (select previous match)
|
|
* `?`: search (extend to next match)
|
|
* `alt-?`: search (extend to previous 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
|
|
|
|
* `'`: 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`: enter insert mode before current selection
|
|
* `a`: enter insert mode after current selection
|
|
* `d`: yank and delete current selection
|
|
* `c`: yank and delete current selection and enter insert mode
|
|
* `.`: repeat last insert mode change (`i`, `a`, or `c`, including
|
|
the inserted text)
|
|
|
|
* `I`: enter insert mode at current selection begin line start
|
|
* `A`: enter insert mode at current selection end line end
|
|
* `o`: enter insert mode in a new line below current selection end
|
|
* `O`: enter insert mode 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
|
|
* `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-'`: rotate selections content, if specified, the count groups
|
|
selections, so `3<a-'>` rotate (1, 2, 3) and (3, 4, 6)
|
|
independently.
|
|
|
|
Goto Commands
|
|
~~~~~~~~~~~~~
|
|
|
|
Commands beginning 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
|
|
* `ge`: go to last char of 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 modification position
|
|
|
|
If a count is given prior to hitting `g`, `g` will jump to the given line.
|
|
Using `G` will extend the selection rather than jump.
|
|
|
|
View commands
|
|
~~~~~~~~~~~~~
|
|
|
|
Some commands, all beginning 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
|
|
|
|
Using `V` will lock view mode until `<esc>` is hit
|
|
|
|
Marks
|
|
~~~~~
|
|
|
|
Current selections position can be saved in a register and restored later on.
|
|
By default, marks use the '^' register, but using the register can be set
|
|
using `"<reg>` prefix.
|
|
|
|
`Z` will save the current selections to the register.
|
|
`z` will restore the selections from the register.
|
|
`alt-z` will add the selections from the register to the existing ones.
|
|
|
|
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 occurrences 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 ', *'
|
|
|
|
The regex syntax supported by Kakoune is the Perl one and is describe
|
|
here <<Regex syntax>>.
|
|
|
|
`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
|
|
* `"` or `Q`: select the enclosing double quoted string
|
|
* `'` or `q`: select the enclosing single quoted string
|
|
* ``` or `g`: 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
|
|
* `u`: select the argument
|
|
* `:`: select user defined object, will prompt
|
|
for open and close text.
|
|
|
|
For nestable objects, a count can be used in order to specify which surrounding
|
|
level to select.
|
|
|
|
Commands
|
|
--------
|
|
|
|
When pressing `:` in normal mode, Kakoune will open a prompt to enter a command.
|
|
|
|
Commands are used for non editing tasks, such as opening a buffer, writing the
|
|
current one, quitting, etc.
|
|
|
|
A few keys are recognized by prompt mode to help editing a command:
|
|
|
|
* `<ret>`: validate prompt
|
|
* `<esc>`: abandon without
|
|
|
|
* `<left> or <a-h>`: move cursor to previous character
|
|
* `<right> or <a-l>`: move cursor to previous character
|
|
* `<home>`: move cursor to first character
|
|
* `<end>`: move cursor to passed last character
|
|
* `<backspace> or <a-x>`: erase character before cursor
|
|
* `<del> or <a-d>`: erase character under cursor
|
|
|
|
* `<c-w>`: advance to next word begin
|
|
* `<c-a-w>`: advance to next WORD begin
|
|
* `<c-b>`: go back to previous word begin
|
|
* `<c-a-b>`: go back to previous WORD begin
|
|
* `<c-e>`: advance to next word end
|
|
* `<c-a-e>`: advance to next word end
|
|
|
|
* `<up> or <c-p>`: select previous entry in history
|
|
* `<down> or <c-n>`: select next entry in history
|
|
|
|
* `<tab>`: select next completion candidate
|
|
* `<backtab>`: select previous completion candidate
|
|
|
|
* `<c-r>`: insert then content of the register given by next key.
|
|
* `<c-v>`: insert next keystroke without interpreting it
|
|
|
|
* `<c-o>`: disable auto completion for this prompt
|
|
|
|
|
|
Commands starting with horizontal whitespace (e.g. a space) will not be
|
|
saved in the command history.
|
|
|
|
Basic Commands
|
|
~~~~~~~~~~~~~~
|
|
|
|
Some commands take an exclamation mark (`!`), which can be used to force
|
|
the execution of the command (i.e. to quit a modified buffer, the
|
|
command `q!` has to be used).
|
|
|
|
* `cd <directory>`: change the current directory to the one passed
|
|
* `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.
|
|
* `kill[!]`: terminate the current session, all the clients as well as the server,
|
|
use kill! to ignore unsaved buffers
|
|
* `w[a]q[!]`: write the current buffer (or all buffers when `waq` is used) and quit
|
|
* `b[uffer] <name>`: switch to buffer <name>
|
|
* `b[uffer]n[ext]`: switch to the next buffer
|
|
* `b[uffer]p[rev]`: switch to the previous buffer
|
|
* `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.
|
|
* `colorscheme <name>`: load named colorscheme.
|
|
* `nameclient <name>`: set current client name
|
|
* `namebuf <name>`: set current buffer name
|
|
* `echo [options] <text>`: show <text> in status line, with the following options:
|
|
** `-color` <face>: print the given text with <face>, most commonly `Error` or `Information`
|
|
** `-markup`: expand the markup strings in <text>
|
|
** `-debug`: print the given text to the `\*debug*` buffer
|
|
* `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.
|
|
|
|
Multiple commands
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
Multiple commands can be separated either by new lines or by semicolons,
|
|
as such a semicolon must be escaped with `\;` to be considered as a literal
|
|
semicolon argument.
|
|
|
|
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"`: expanded strings, % strings (see <<Expansions>>) 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 `}` delimiters 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.
|
|
|
|
Expansions
|
|
^^^^^^^^^^
|
|
|
|
A special kind of `%{strings}` can be used, with a type between
|
|
`%` and the opening delimiter (which cannot be alphanumeric). These
|
|
strings are expanded according to their type.
|
|
|
|
For example `%opt{autoinfo}` is of type 'opt'. opt expansions are replaced
|
|
by the value of the given option (here `autoinfo`).
|
|
|
|
Supported types are:
|
|
|
|
* `sh`: shell expansion, similar to posix shell $(...) construct, see
|
|
<<Shell expansion>> for more details.
|
|
* `reg`: register expansion, will be replaced by the content of the given
|
|
register.
|
|
* `opt`: option expansion, will be replaced with the value of the given
|
|
option
|
|
* `val`: value expansion, gives access to the environment variable available
|
|
to the Shell expansion. The `kak_` prefix is not used there.
|
|
* `arg`: argument expansion, gives access to the arguments of the current
|
|
command, the content can be a number, or `@` for all arguments.
|
|
|
|
for example you can display last search pattern with
|
|
|
|
-------------
|
|
:echo %reg{/}
|
|
-------------
|
|
|
|
Shell expansion
|
|
^^^^^^^^^^^^^^^
|
|
|
|
The `%sh{...}` expansion replaces its 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 escaped with a backslash.
|
|
* `kak_selection_desc`: range of the main selection, represented as `anchor,cursor`;
|
|
anchor and cursor are in this format: `line.column`
|
|
* `kak_selections_desc`: range of the selecations separated by colons
|
|
* `kak_bufname`: name of the current buffer
|
|
* `kak_buffile`: full path of the file or same as `kak_bufname` when
|
|
there's no associated file
|
|
* `kak_buflist`: the current buffer list, each buffer separated 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_session`: name of the current 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_cursor_byte_offset`: offset of the main selection from the beginning of the buffer (in byte).
|
|
* `kak_window_width`: width of the current kakoune window
|
|
* `kak_window_height`: height of the current kakoune window
|
|
* `kak_hook_param`: filtering text passed to the currently executing hook
|
|
* `kak_client_env_<name>`: value of the <name> variable in the client environment.
|
|
Example: $kak_client_env_SHELL is the SHELL variable
|
|
|
|
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 }
|
|
-------------------------------
|
|
|
|
Markup strings
|
|
^^^^^^^^^^^^^^
|
|
|
|
In certain context, kakoune can take a markup string, which is a string containing
|
|
formatting informations. In these strings, syntax `{facename}` will enable the
|
|
face _facename_ until another face gets activated (or the end of the string.
|
|
Literal `{` shall be written `\{`, and literal `\` that precede a `{` shall
|
|
be written `\\`
|
|
|
|
Configuration & Autoloading
|
|
---------------------------
|
|
|
|
Kakrc
|
|
~~~~~
|
|
|
|
If not launched with the `-n` switch, Kakoune will source the
|
|
`../share/kak/kakrc` file relative to the `kak` binary, which
|
|
will source additional files:
|
|
|
|
If the `$XDG_CONFIG_HOME/kak/autoload` directory exists, load every
|
|
`*.kak` files in it, and load recursively any subdirectory.
|
|
|
|
If it does not exists, falls back to the site wide autoload directory
|
|
in `../share/kak/autoload/`.
|
|
|
|
After that, if it exists, source the `$XDG_CONFIG_HOME/kak/kakrc` file
|
|
which should be used for user configuration.
|
|
|
|
In order to continue autoloading site-wide files with a local autoload
|
|
directory, just add a symbolic link to `../share/kak/autoload/` into
|
|
your local autoload directory.
|
|
|
|
Color Schemes
|
|
~~~~~~~~~~~~~
|
|
|
|
Kakoune ships with some color schemes that are installed to
|
|
`../share/kak/colors/`. If `$XDG_CONFIG_HOME/kak/colors/` is present
|
|
the builtin command `colorscheme` will offer completion for those
|
|
color schemes. If a scheme is duplicated in userspace it will take
|
|
precedence.
|
|
|
|
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`
|
|
* `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.
|
|
* `enum(value1|value2|...)`: an enum, taking on of the given values
|
|
* `flags(value1|value2|...)`: a set of flags, taking a combination
|
|
of the given values joined by `|`.
|
|
|
|
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` _enum(lf|crlf)_: the format of end of lines when
|
|
writing a buffer, this is autodetected on load.
|
|
* `BOM` _enum(none|utf8)_: define if the file should be written
|
|
with an unicode byte order mark.
|
|
* `incsearch` _bool_: execute search as it is typed
|
|
* `aligntab` _bool_: use tabs for alignment command
|
|
* `autoinfo` _flags(command|onkey|normal)_: display automatic information
|
|
box in the enabled contexts.
|
|
* `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.
|
|
* `static_words` _str-list_: list of words that are always added to completion
|
|
candidates when completing words in insert mode.
|
|
* `autoreload` _enum(yes|no|ask)_: auto reload the buffers when an external
|
|
modification is detected.
|
|
* `debug` _flags(hooks|shell|profile)_: dump various debug information in
|
|
the `*debug*` buffer.
|
|
* `modelinefmt` _string_: A format string used to generate the mode line, that
|
|
string is first expanded as a command line would be (expanding `%...{...}`
|
|
strings), then markup tags are applied (see <<Markup strings>>).
|
|
* `ui_options`: colon separated list of key=value pairs that are forwarded to
|
|
the user interface implementation. The NCurses UI support the following options:
|
|
- `ncurses_set_title`: if `yes` or `true`, the terminal emulator title will
|
|
be changed.
|
|
- `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.
|
|
- `ncurses_assistant`: specify the nice assistant you get in info boxes, can
|
|
be 'clippy' (the default), 'cat' or 'none'
|
|
- `ncurses_wheel_down_button` and `ncurses_wheel_up_button`: specify which
|
|
button send for wheel down/up events.
|
|
|
|
Faces
|
|
-----
|
|
|
|
A Face refers how the 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
|
|
* `B`: Blink
|
|
* `d`: Dim
|
|
* `i`: Italic
|
|
* `e`: Exclusive, override previous faces instead of merging with them
|
|
|
|
Using named faces instead of facespec permits to change the effective faces
|
|
afterwards.
|
|
|
|
There are some builtins faces used by internal Kakoune functionalities:
|
|
|
|
* `Default`: default colors
|
|
* `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
|
|
* `MatchingChar`: face used by the show_matching highlighter
|
|
* `Search`: face used to highlight search results
|
|
* `BufferPadding`: face applied on the characters that follow the last line of a buffer
|
|
|
|
Advanced topics
|
|
---------------
|
|
|
|
Registers
|
|
~~~~~~~~~
|
|
|
|
Registers are named lists of text. They are used for various purposes, like
|
|
storing the last yanked test, or the captured groups associated with the
|
|
selections.
|
|
|
|
Yanking and pasting uses the register `"`, however most commands using a register
|
|
can have their default register overridden by using the `"` key followed by the
|
|
register. For example `"sy` will yank (`y` command) in the `s` register. `"sp`
|
|
will paste from the `s` register.
|
|
|
|
While in insert mode or in a prompt, `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 has its own captures or yank buffer.
|
|
|
|
Special registers
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
Some registers are not general purposes, they cannot be written to, but they
|
|
contain some special data:
|
|
|
|
* `%`: current buffer name
|
|
* `.`: current selection contents
|
|
* `#`: selection indices (first selection has 1, second has 2, ...)
|
|
* `_`: null register, always empty
|
|
|
|
Default registers
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
Most commands using a register default to a specific one if not specified:
|
|
|
|
* `"`: default yank, used by yanking and pasting commands like `y`, `p` and `R`
|
|
* `/`: default search register, used by regex based commands like `s`, `*` or `/`
|
|
* `@`: default macro register, used by `q` and `Q`
|
|
* `^`: default mark register, used by `z` and `Z`
|
|
* `|`: default shell command register, used by command that spawn a subshell such as `|`, `<a-|>`, `!` or `<a-!>`
|
|
|
|
Macros
|
|
~~~~~~
|
|
|
|
Kakoune can record and replay a sequence of key presses.
|
|
|
|
Macros are recorded with the `Q` key, and are stored by default in the `@`
|
|
register. Another register can be chosen by with hitting `"<reg>` before
|
|
the `Q` key.
|
|
|
|
To replay a macro, use the `q` key.
|
|
|
|
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 the current selection
|
|
begins and/or ends at word boundaries and set the search pattern accordingly.
|
|
|
|
with `alt-*` you can set the search pattern to the current selection without
|
|
Kakoune trying to be smart.
|
|
|
|
Regex syntax
|
|
~~~~~~~~~~~~
|
|
|
|
The regex syntax supported by Kakoune is the Perl syntax currently provided
|
|
by Boost :
|
|
http://www.boost.org/doc/libs/release/libs/regex/doc/html/boost_regex/syntax/perl_syntax.html[Perl Regular Expression Syntax].
|
|
|
|
Exec and Eval
|
|
~~~~~~~~~~~~~
|
|
|
|
the `:exec` and `:eval` commands can be used for running Kakoune commands.
|
|
`:exec` runs keys as if they were pressed, whereas `:eval` executes its given
|
|
paremeters as if they were entered in the command prompt. By default,
|
|
they do their execution in the context of the current client.
|
|
|
|
These two commands also save the following registers, who are then restored
|
|
when the commands have been executed: `/`, `"`, `|`, `^`, `@`.
|
|
|
|
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>, '*' as a name can be used to iterate
|
|
on all buffers.
|
|
* `-no-hooks`: disable hook execution while executing the keys/commands
|
|
* `-with-maps`: use user key mapping in `:exec` instead of built in keys.
|
|
* `-save-regs <regs>`: regs is a string of registers to be restored after
|
|
execution (overwrites the list of registers saved by default)
|
|
|
|
The execution stops when the last key/command is reached, or an error
|
|
is raised.
|
|
|
|
Key parameters get concatenated, so the following commands are equivalent:
|
|
|
|
----------------------
|
|
:exec otest<space>1
|
|
:exec o test <space> 1
|
|
----------------------
|
|
|
|
Insert mode completion
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Kakoune can propose completions while inserting text, the `completers` option
|
|
controls automatic completion, which kicks in when a certain idle timeout is
|
|
reached (100 milliseconds). Insert mode completion can be explicitly triggered
|
|
using *control-x*, followed, by:
|
|
|
|
* *f* : filename completion
|
|
* *w* : buffer word completion
|
|
* *l* : buffer line completion
|
|
|
|
Completion candidates can be selected using `ctrl-n` and `ctrl-p`.
|
|
|
|
Escape to normal mode
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
From insert mode, pressing `<a-;>` allows you to execute a single normal mode
|
|
command. This provides a few advantages:
|
|
|
|
* The selections are not modified: when leaving insert mode using `<esc>` the
|
|
selections can change, for example when insert mode was entered with `a` the
|
|
cursor will go back one char. Or if on an end of line the cursor will go back
|
|
left (if possible).
|
|
|
|
* The modes are nested: that means the normal mode can enter prompt (with `:`),
|
|
or any other modes (using `:onkey` or `:menu` for example), and these modes
|
|
will get back to the insert mode afterwards.
|
|
|
|
This feature is tailored for scripting/macros, as it provides a more predictable
|
|
behaviour than leaving insert mode with `<esc>`, executing normal mode command
|
|
and entering back insert mode (with which binding ?)
|
|
|
|
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>
|
|
----------------------
|
|
|
|
`highlighter_id` is a name generated by the highlighter specified with `highlighter_name`,
|
|
possibly dependent on the parameters. Use command completion on rmhl to see the existing
|
|
highlighters 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 (\hTODO:)?[^\n] 0:cyan 1:yellow,red`
|
|
will highlight C++ style comments in cyan, with an eventual 'TODO:' in
|
|
yellow on red background.
|
|
* `dynregex`: Similar to regex, but expand (like a command parameter would) the
|
|
given expression before building a regex from the result.
|
|
* `flag_lines <flag> <option_name>`: add a column in front of text, and display the
|
|
given flag in it for everly line 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> \<-separator <separator text> >`: show line numbers.
|
|
The -relative switch will show line numbers relative to the main cursor line, the
|
|
-hlcursor switch will highlight the cursor line with a separate face. With the
|
|
-separator switch one can specify a string to separate the line numbers column with
|
|
the rest of the buffer, default is `|`.
|
|
* `fill <face>`: fill using given face, mostly useful with <<regions-highlighters,Regions highlighters>>
|
|
|
|
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]]
|
|
Regions highlighters
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
A special highlighter provides a way to segment the buffer into regions, which are
|
|
to be highlighted differently.
|
|
|
|
A region is defined by 4 parameters:
|
|
|
|
------------------------------------
|
|
<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 regions -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 registered 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).
|
|
Scopes are hierarchical, meaning that a Window calling a hook will
|
|
execute its 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 destroyed, the filtering text is the buffer name
|
|
* `WinDisplay`: A window was bound a client, the filtering text is the buffer
|
|
name
|
|
* `WinResize`: A window resized, the filtering text is '<line>.<column>'
|
|
* `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.
|
|
* `BufOpenFifo`: Executed when a buffer opens a fifo.
|
|
* `BufReadFifo`: Executed after some data has been red from a fifo and
|
|
inserted in the buffer.
|
|
* `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.
|
|
* `FocusIn`: On supported clients, triggered when the client gets focused.
|
|
the filtering text is the client name.
|
|
* `FocusOut`: On supported clients, triggered when the client gets unfocused.
|
|
the filtering text is the client name.
|
|
|
|
When not specified, the filtering text is an empty string.
|
|
|
|
Key Mapping
|
|
~~~~~~~~~~~
|
|
|
|
You can redefine a key's 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.
|
|
|
|
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:
|
|
|
|
* `-params <num>`: the command accept <num> parameters, with <num>
|
|
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 existing 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 and -password allow
|
|
not to show the entered text (and clears the register after command execution).
|
|
* `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 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>
|
|
* `select <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>:...`:
|
|
replace the current selections with the one described in the argument
|
|
* `debug {info,buffers,options,memory,shared-strings}`: print some debug
|
|
information in the `*debug*` buffer
|
|
|
|
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`, `<ctrl-n>` or `<tab>` to select the next
|
|
entry, and `k`, `<ctrl-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.
|