Commands can be registered to be executed when certain events arise. To register a hook use the following command:
hook [-group <group>] <scope> <hook_name> <filtering_regex> <commands>
scope can be one of global, buffer or window (See
:doc scopes).
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 %{ add-highlighter number_lines }
If group is given, make this hook part of the named group. Groups are used for removing hooks with the following command:
remove-hooks <scope> <group>
A call to the command above will remove every hooks in scope that are part of the given group.
- NormalIdle
-
a certain duration has passed since last key was pressed in normal mode
- NormalBegin
-
entering normal mode
- NormalEnd
-
leaving normal mode
- NormalKey
key -
a key is received in normal mode
- InsertIdle
-
a certain duration has passed since last key was pressed in insert mode
- InsertBegin
-
entering insert mode
- InsertEnd
-
leaving insert mode
- InsertKey
key -
a key is received in insert mode
- InsertChar
char -
a character is received in insert mode
- InsertDelete
deleted char -
a character is deleted in insert mode
- InsertMove
move key -
the cursor moved (without inserting) in insert mode
- PromptIdle
-
a certain duration has passed since last key was pressed in prompt mode
- WinCreate
buffer name -
a window was created
- WinClose
buffer name -
a window was destroyed
- WinResize
<line>.<column> -
a window was resized
- WinDisplay
buffer name -
a window was bound a client
- WinSetOption
<option_name>=<new_value> -
an option was set in a window context
- GlobalSetOption
<option_name>=<new_value> -
an option was set at the global scope
- BufSetOption
<option_name>=<new_value> -
an option was set in a buffer context
- BufNewFile
filename -
a buffer for a new file has been created
- BufOpenFile
filename -
a buffer for an existing file has been created
- BufCreate
filename -
a buffer has been created
- BufWritePre
filename -
executed just before a buffer is written
- BufWritePost
filename -
executed just after a buffer is written
- BufClose
buffer name -
executed when a buffer is deleted, while it is still valid
- BufOpenFifo
buffer name -
executed when a buffer opens a fifo
- BufReadFifo
buffer name -
executed after some data has been read 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 the writing end has been closed
- RuntimeError
error message -
an error was encountered while executing a user command
- ModeChange
<old mode>:<new mode> -
Triggered whenever the current input mode changes
- KakBegin
session name -
kakoune has started, this hook is called just after reading the user configuration files
- KakEnd
-
kakoune is quitting
- FocusIn
client name -
on supported clients, triggered when the client gets focused
- FocusOut
client name -
on supported clients, triggered when the client gets unfocused
- InsertCompletionShow
-
Triggered when the insert completion menu gets displayed
- InsertCompletionHide
-
Triggered when the insert completion menu gets hidden
- InsertCompletionSelect
selected completion -
Triggered when an entry is selected in the insert completion menu. The filtering text is the selected completion text or the empty string if the original text was selected back.
- RawKey
key -
Triggered whenever a key is pressed by the user
When not specified, the filtering text is an empty string. Note that
some hooks will not consider underlying scopes depending on what context
they are bound to be run into, e.g. the BufWritePost hook is a buffer
hook, and will not consider the window scope.
While defining hook commands with a %sh{} block, some additional env
vars are available:
-
kak_hook_param: filtering text passed to the currently executing hook -
kak_hook_param_capture_N: text captured by the hook filter regex capture N
Any normal mode command can be prefixed with \ ` which will disable hook
execution for the duration for the command (including the duration of modes
the command could move to, so `\i will disable hooks for the whole insert
session).
As autoindentation is implemented in terms of hooks, this can be used to disable it when pasting text.
A less temporary alternative is to set the disabled_hooks option which
accepts a regex describing which hooks won’t be executed.
For example indentation hooks can be disabled with '.*-indent'.
Finally, hook execution can be disabled while using the execute-keys or
evaluate-commands commands by using the -no-hooks switch.
(See :doc execeval)