Hooks

#1

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.

Scopes