xenia/kakoune
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Reorganize README

Browse Source
This commit is contained in:
Maxime Coste 2015-04-03 18:42:12 +01:00
parent 04a922fe1a
commit bd30df58bf
1 changed files with 346 additions and 279 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

625
README.asciidoc
View File

@ -2,6 +2,8 @@
:logo: https://rawgit.com/mawww/kakoune/master/doc/kakoune_logo.svg :logo: https://rawgit.com/mawww/kakoune/master/doc/kakoune_logo.svg
:travis-img: https://travis-ci.org/mawww/kakoune.svg :travis-img: https://travis-ci.org/mawww/kakoune.svg
:travis-url: https://travis-ci.org/mawww/kakoune :travis-url: https://travis-ci.org/mawww/kakoune
:icons: font
:toc: right
TL;DR TL;DR
----- -----
@ -46,7 +48,7 @@ see http://vimeo.com/82711574
Join us on freenode IRC +#Kakoune+ Join us on freenode IRC +#Kakoune+
Features Features
-------- ~~~~~~~~
* Multiple selections as a central way of interacting * Multiple selections as a central way of interacting
* Powerful selection manipulation primitives * Powerful selection manipulation primitives
@ -72,8 +74,11 @@ Features
- Supports multiple languages in the same buffer - Supports multiple languages in the same buffer
- Highlight a buffer differently in different windows - Highlight a buffer differently in different windows
Getting started
---------------
Building Building
-------- ~~~~~~~~
Kakoune dependencies are: Kakoune dependencies are:
@ -91,7 +96,7 @@ src directory, this will setup an initial $XDG_CONFIG_HOME/kak directory. See
the _Kakrc_ section for more information. the _Kakrc_ section for more information.
Installing Installing
---------- ~~~~~~~~~~
In order to install kak on your system, rather than running it directly from 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 it's source directory, type *make install*, you can specify the +PREFIX+ and
@ -108,26 +113,28 @@ a symbolic link to the $PREFIX/share/kak/rc directory.
ln -s /usr/share/kak/rc ~/.config/kak/autoload ln -s /usr/share/kak/rc ~/.config/kak/autoload
---------------------------------------------- ----------------------------------------------
Homebrew (OSX) [TIP]
~~~~~~~~~~~~~~ .Homebrew (OSX)
====
----------------------------------------------------------------------------------------------- -----------------------------------------------------------------------------------------------
brew install --HEAD https://raw.githubusercontent.com/mawww/kakoune/homebrew/contrib/kakoune.rb brew install --HEAD https://raw.githubusercontent.com/mawww/kakoune/homebrew/contrib/kakoune.rb
----------------------------------------------------------------------------------------------- -----------------------------------------------------------------------------------------------
====
Fedora 20/21/22/Rawhide & Epel 7 [TIP]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .Fedora 20/21/22/Rawhide & Epel 7
====
Use the https://copr.fedoraproject.org/coprs/jkonecny/kakoune/[copr] repository. Use the https://copr.fedoraproject.org/coprs/jkonecny/kakoune/[copr] repository.
--------------------------------- ---------------------------------
dnf copr enable jkonecny/kakoune dnf copr enable jkonecny/kakoune
dnf install kakoune dnf install kakoune
--------------------------------- ---------------------------------
====
Arch Linux [TIP]
~~~~~~~~~ .Arch Linux
====
A PKGBUILD https://aur.archlinux.org/packages/kakoune-git[kakoune-git] 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]. to install Kakoune is available in the https://wiki.archlinux.org/index.php/Arch_User_Repository[AUR].
@ -135,17 +142,19 @@ to install Kakoune is available in the https://wiki.archlinux.org/index.php/Arch
# For example build and install Kakoune via yaourt # For example build and install Kakoune via yaourt
yaourt -Sy kakoune-git yaourt -Sy kakoune-git
-------------------------------- --------------------------------
====
Exherbo [TIP]
~~~~~~~ .Exherbo
====
-------------------------------- --------------------------------
cave resolve -x repository/mawww cave resolve -x repository/mawww
cave resolve -x kakoune cave resolve -x kakoune
-------------------------------- --------------------------------
====
Running Running
------- ~~~~~~~
Just running *kak* launch a new kak session with a client on local terminal. Just running *kak* launch a new kak session with a client on local terminal.
*kak* accepts some switches: *kak* accepts some switches:
@ -173,8 +182,37 @@ 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 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. scripts in $PREFIX/share/kak/rc that the user wants sourced at kak launch.
Basic Movement 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. A few additional keys are supported, like arrow keys to move around, however
their use is not encouraged. You can go back to normal mode by pressing the +<esc>+
key.
Movement
~~~~~~~~
* +h+: select the character on the right of selection end * +h+: select the character on the right of selection end
* +j+: select the character below the selection end * +j+: select the character below the selection end
@ -218,13 +256,13 @@ A word is a sequence of alphanumeric characters or underscore, a WORD is a
sequence of non whitespace characters. sequence of non whitespace characters.
Appending Appending
--------- ~~~~~~~~~
for most selection commands, using shift permits to extend current selection for most selection commands, using shift permits to extend current selection
instead of replacing it. for example, +wWW+ selects 3 consecutive words instead of replacing it. for example, +wWW+ selects 3 consecutive words
Using Counts Using Counts
------------ ~~~~~~~~~~~~
Most selection commands also support counts, which are entered before the Most selection commands also support counts, which are entered before the
command itself. command itself.
@ -233,19 +271,19 @@ for example, +3W+ selects 3 consecutive words and +3w+ select the third word on
the right of selection end. the right of selection end.
Changes Changes
------- ~~~~~~~
* +i+: insert before current selection * +i+: enter insert mode before current selection
* +a+: insert after current selection * +a+: enter insert mode after current selection
* +d+: yank and delete current selection * +d+: yank and delete current selection
* +c+: yank and delete current selection and insert * +c+: yank and delete current selection and enter insert mode
* +.+: repeat last insert mode change (+i+, +a+, or +c+, including * +.+: repeat last insert mode change (+i+, +a+, or +c+, including
the inserted text) the inserted text)
* +I+: insert at current selection begin line start * +I+: enter insert mode at current selection begin line start
* +A+: insert at current selection end line end * +A+: enter insert mode at current selection end line end
* +o+: insert in a new line below current selection end * +o+: enter insert mode in a new line below current selection end
* +O+: insert in a new line above current selection begin * +O+: enter insert mode in a new line above current selection begin
* +y+: yank selections * +y+: yank selections
* +p+: paste after current selection end * +p+: paste after current selection end
@ -299,7 +337,7 @@ Changes
independently. independently.
Goto Commands Goto Commands
------------- ~~~~~~~~~~~~~
Commands begining with g are used to goto certain position and or buffer: Commands begining with g are used to goto certain position and or buffer:
@ -319,7 +357,7 @@ Commands begining with g are used to goto certain position and or buffer:
* +g.+: go to last buffer modifiction position * +g.+: go to last buffer modifiction position
View commands View commands
------------- ~~~~~~~~~~~~~
Some commands, all begining with v permit to manipulate the current Some commands, all begining with v permit to manipulate the current
view. view.
@ -333,7 +371,7 @@ view.
* +vl+: scroll the window count columns right * +vl+: scroll the window count columns right
Jump list Jump list
--------- ~~~~~~~~~
Some commands, like the goto commands, buffer switch or search commands, Some commands, like the goto commands, buffer switch or search commands,
push the previous selections to the client's jump list. It is possible push the previous selections to the client's jump list. It is possible
@ -344,7 +382,7 @@ to forward or backward in the jump list using:
* +control-s+: save current selections * +control-s+: save current selections
Multi Selection Multi Selection
--------------- ~~~~~~~~~~~~~~~
Kak was designed from the start to handle multiple selections. Kak was designed from the start to handle multiple selections.
One way to get a multiselection is via the +s+ key. One way to get a multiselection is via the +s+ key.
@ -380,7 +418,7 @@ not containing a match.
Selections whose shell command returns 0 will be kept, other will be dropped. Selections whose shell command returns 0 will be kept, other will be dropped.
Object Selection Object Selection
---------------- ~~~~~~~~~~~~~~~~
Some keys allow you to select a text object: Some keys allow you to select a text object:
@ -414,48 +452,16 @@ object you want.
For nestable objects, a count can be used in order to specify which surrounding For nestable objects, a count can be used in order to specify which surrounding
level to select. level to select.
Registers Commands
--------- --------
registers are named list of text. They are used for various purpose, like When pressing +:+ in normal mode, Kakoune will open a prompt to enter a command.
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) Commands are used for non editing tasks, such as opening a buffer, writing the
inserts it. current one, quitting, etc...
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 Basic Commands
-------------- ~~~~~~~~~~~~~~
Commands are entered using +:+.
* +e[dit] <filename> [<line> [<column>]]+: open buffer on file, go to given * +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. line and column. If file is already opened, just switch to this file.
@ -482,42 +488,8 @@ Commands are entered using +:+.
+:nop %sh{ echo echo tchou }+ will not, but both will execute the +:nop %sh{ echo echo tchou }+ will not, but both will execute the
shell command. 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 String syntax
------------- ~~~~~~~~~~~~~
When entering a command, parameters are separated by whitespace (shell like), When entering a command, parameters are separated by whitespace (shell like),
if you want to give parameters with spaces, you should quote them. if you want to give parameters with spaces, you should quote them.
@ -527,7 +499,7 @@ Kakoune support three string syntax:
* +\'strings\'+: uninterpreted strings, you can use \' to escape the separator, * +\'strings\'+: uninterpreted strings, you can use \' to escape the separator,
every other char is itself. every other char is itself.
* +"strings"+: expended strings, % strings (see %sh, %opt or %reg) contained * +"strings"+: expanded strings, % strings (see %sh, %opt or %reg) contained
are expended. Use \% to escape a % inside them, and \\ to escape a slash. are expended. Use \% to escape a % inside them, and \\ to escape a slash.
* +%\{strings\}+: these strings are very useful when entering commands * +%\{strings\}+: these strings are very useful when entering commands
@ -539,6 +511,121 @@ Kakoune support three string syntax:
the matching }])> and the delimiters are not escapable but are nestable. the matching }])> and the delimiters are not escapable but are nestable.
for example +%{ roger {}; }+ is a valid string, +%{ marcel \}+ as well. 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 the
Shell expansion section 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.
for example you can display last search pattern with
-------------
:echo %reg{/}
-------------
Shell expansion
^^^^^^^^^^^^^^^
The +%sh{...}+ expansion replaces 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 }
-------------------------------
Kakrc
-----
The kakrc file in +../share/kak/kakrc+ (relative to the +kak+ binary)
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 +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.
Options Options
------- -------
@ -560,9 +647,9 @@ Options are typed, their type can be
Options value can be changed using the +set+ commands: Options value can be changed using the +set+ commands:
-------------------------------------------------------------- ------------------------------------------------------------------------------
:set [global,buffer,window] <option> <value> # buffer, window, or global scope :set [global,buffer,window] <option> <value> # buffer, window, or global scope
-------------------------------------------------------------- ------------------------------------------------------------------------------
Option values can be different by scope, an option can have a global 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 value, a buffer value and a window value. The effective value of an
@ -633,8 +720,147 @@ Some options are built in Kakoune, and can be used to control it's behaviour:
- +ncurses_status_on_top+: if +yes+, or +true+ the status line will be placed - +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. at the top of the terminal rather than at the bottom.
Insert mode completion 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
Advanced topics
---------------
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.
Yanking and pasting uses the register +"+, however most commands using register
can have their default register overriden 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 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.
macros are actually stored as a key sequence into a register, a macro name
is a register 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.
Exec and Eval
~~~~~~~~~~~~~
the +:exec+ and +:eval+ commands can be used for running Kakoune commands.
+:exec+ run 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
----------------------
Insert mode completion
~~~~~~~~~~~~~~~~~~~~~~
Kakoune can propose completions while inserting text, the +completers+ option Kakoune can propose completions while inserting text, the +completers+ option
control automatic completion, which kicks in when a certain idle timeout is control automatic completion, which kicks in when a certain idle timeout is
@ -647,7 +873,7 @@ using *control-x*, followed, by:
* *o* : option based completion * *o* : option based completion
Highlighters Highlighters
------------ ~~~~~~~~~~~~
Manipulation of the displayed text is done through highlighters, which can be added Manipulation of the displayed text is done through highlighters, which can be added
or removed with the command or removed with the command
@ -683,7 +909,7 @@ general highlighters are:
(see below) (see below)
Highlighting Groups Highlighting Groups
~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^
the +group+ highlighter is a container for other highlighters. You can add the +group+ highlighter is a container for other highlighters. You can add
a group to the current window using a group to the current window using
@ -707,7 +933,7 @@ addhl -group <name>/<subname> <type> <params>...
------------------------------------------------ ------------------------------------------------
Regions highlighters Regions highlighters
~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^
A special highlighter provide a way to segment the buffer into regions, which are A special highlighter provide a way to segment the buffer into regions, which are
to be highlighted differently. to be highlighted differently.
@ -768,7 +994,7 @@ addhl -group <lang>/comment ...
----------------------------------------------------------------- -----------------------------------------------------------------
Shared Highlighters Shared Highlighters
~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^
Highlighters are often defined for a specific filetype, and it makes then sense to 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. share the highlighters between all the windows on the same filetypes.
@ -799,7 +1025,7 @@ addhl ref <name>
the +ref+ can reference any named highlighter in the shared namespace. the +ref+ can reference any named highlighter in the shared namespace.
Hooks Hooks
----- ~~~~~
commands can be registred to be executed when certain events arise. commands can be registred to be executed when certain events arise.
to register a hook, use the hook command. to register a hook, use the hook command.
@ -875,7 +1101,7 @@ existing hooks are:
when not specified, the filtering text is an empty string. when not specified, the filtering text is an empty string.
Key Mapping Key Mapping
----------- ~~~~~~~~~~~
You can redefine keys meaning using the map command You can redefine keys meaning using the map command
@ -890,119 +1116,8 @@ a single key name and +keys+ a list of keys.
+user+ mode allows for user mapping behind the +,+ key. Keys will be executed in +user+ mode allows for user mapping behind the +,+ key. Keys will be executed in
normal mode. 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 Defining Commands
----------------- ~~~~~~~~~~~~~~~~~
new commands can be defined using the +:def+ command. new commands can be defined using the +:def+ command.
@ -1058,7 +1173,7 @@ Note that these commands are available in interactive command mode, but are
not that useful in this context. not that useful in this context.
Aliases Aliases
------- ~~~~~~~
With +:alias+ commands can be given additional names. aliases are scoped, so 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 that an alias can refer to one command for a buffer, and to another for another
@ -1079,7 +1194,7 @@ 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>+. the alias will only be removed if its current value is +<expected>+.
FIFO Buffer FIFO Buffer
----------- ~~~~~~~~~~~
the +:edit+ command can take a -fifo parameter: the +:edit+ command can take a -fifo parameter:
@ -1102,58 +1217,10 @@ to it will receive SIGPIPE. This is usefull as it permits to stop the writing
program when the buffer is deleted. program when the buffer is deleted.
Menus Menus
----- ~~~~~
When a menu is displayed, you can use *j*, *control-n* or *tab* to select the next 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. 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 Using the */* key, you can enter some regex in order to restrict available choices
to the matching ones. 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.