home/doc/pages/hooks.asciidoc

= Hooks

== 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
<<scopes#,`: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.

*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

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 <<regex#groups,`: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 <<execeval#,`: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`.