Description
Commands can be registered to be executed when certain events arise. To
register a hook use the following command:
hook [-group <group> | -once] <scope> <hook_name> <filtering_regex> <commands>
scope can be one of global, buffer or window (See
:doc scopes).
hook_name must be one of the hook names in the list below, like
InsertKey or BufSetOption.
filtering_regex must match the entire parameter string in order for
the commands to be executed.
command is a string containing the commands to execute when the hook
is called.
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 hook in scope whose
group matches the given group regex.
If -once is given, the hook is automatically removed after running.
For example to automatically use line numbering with .cc files, use the
following command:
hook global WinCreate .*\.cc %{ add-highlighter number-lines }
Default hooks
The parameter string associated with each hook is described after the
hook name. Hooks with no description will always use an empty string.
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. This hook is executed in draft context, so any a
changes to selections or input state will be discarded.
WinClose buffer name
a window was destroyed. This hook is executed in a draft context, so any
changes to selections or input state will be discarded.
WinResize <line>.<column>
a window was resized. This hook is executed in a draft context, so any
changes to selections or input state will be discarded.
WinDisplay buffer name
a client switched to displaying the given buffer.
WinSetOption <option_name>=<new_value>
an option was set in a window context. This hook is executed in a draft
acontext, so any changes to selections or input state will be discarded.
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
BufReload filename
executed after a buffer reload has been triggered by an external
modification to its file
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 <start line>.<start column>,<end line>.<end column>
executed after some data has been read from a fifo and inserted in the
buffer. The hook param contains the range of text that was just
inserted, in a format compatible with the select command.
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
ClientCreate client name
executed when a new client is created.
ClientClose client name
executed when a client is closed, after it was removed from the client
list.
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 completion
Triggered when the insert completion menu gets hidden, the inserted
completion text is passed as filtering text.
RawKey key
Triggered whenever a key is pressed by the user
ModuleLoad module
Triggered when a module is evaluated by the first require-module call
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
capturing group N, N can either be the capturing group number, or
its name (See:doc regex groups).
Disabling Hooks
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)
As an exception to these rules, hooks declared with the -always switch
are triggered no matter what. A good use case is doing some cleanup on
BufCloseFifo.