= Hooks == Description Commands can be registered to be executed when certain events arise. To register a hook use the following command: ------------------------------------------------------------------------------ hook [-group | -once] ------------------------------------------------------------------------------ *scope* can be one of *global*, *buffer* or *window* (See <>). *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 ---------------------------- 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 the last keypress in normal mode *NormalKey* `key`:: a key is received in normal mode. This hook will not trigger when the user presses a key on the left-hand side of a normal-mode mapping (see <>), but will trigger for keys on the right-hand side. See also `RawKey` below. *InsertIdle*:: a certain duration has passed since the last keypress in insert mode *InsertKey* `key`:: a key is received in insert mode. This hook will not trigger when the user presses a key on the left-hand side of a insert-mode mapping (see <>), but will trigger for keys on the right-hand side. See also `RawKey` below. *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 the last keypress in prompt mode *WinCreate* `buffer name`:: a window was created. This hook is executed in draft context, so any 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* `.`:: 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* `=`:: an option was set in a window context. This hook is executed in a draft context, so any changes to selections or input state will be discarded. *GlobalSetOption* `=`:: an option was set at the global scope *BufSetOption* `=`:: 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* `.,.`:: 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* `[push|pop]::`:: Triggered whenever a mode is pushed or removed from the mode stack. *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, regardless of what mode Kakoune is in, or what mappings are present (see <>). It cannot triggered by `execute-keys`, even with the `-with-hooks` option (see <>). *ModuleLoaded* `module`:: Triggered after 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 <>). == 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 <>) 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`.