hooks.asciidoc (8439B)
1 = Hooks 2 3 == Description 4 5 Commands can be registered to be executed when certain events arise. To 6 register a hook use the following command: 7 8 ------------------------------------------------------------------ 9 hook [<switches>] <scope> <hook_name> <filtering_regex> <commands> 10 ------------------------------------------------------------------ 11 12 *scope* can be one of *global*, *buffer* or *window* (See 13 <<scopes#,`:doc scopes`>>). 14 15 *hook_name* must be one of the hook names in the list below, like `InsertKey` 16 or `BufSetOption`. 17 18 *filtering_regex* must match the entire parameter string in order for the 19 commands to be executed. 20 21 *command* is a string containing the commands to execute when the hook 22 is called. 23 24 For *switches*, see <<commands#hooks,`:doc commands hooks`>>. 25 26 If a hook is registered with the `-group` switch, it can later be removed with 27 the `remove-hooks` command: 28 29 ---------------------------- 30 remove-hooks <scope> <group> 31 ---------------------------- 32 33 This command removes all hooks originally registered in *scope* whose 34 `-group` switch matches the regex *group*. 35 36 For example to automatically use line numbering with .cc files, use the 37 following command: 38 39 -------------------------------------------------------------- 40 hook global WinCreate .*\.cc %{ add-highlighter number-lines } 41 -------------------------------------------------------------- 42 43 == Default hooks 44 45 The parameter string associated with each hook is described after the hook 46 name. Hooks with no description will always use an empty string. 47 48 *NormalIdle*:: 49 a certain duration has passed since the last keypress in normal mode 50 51 *NormalKey* `key`:: 52 a key is received in normal mode. This hook will not trigger when the user 53 presses a key on the left-hand side of a normal-mode mapping (see 54 <<mapping#,`:doc mapping`>>), but will trigger for keys on the right-hand 55 side. See also `RawKey` below. 56 57 *InsertIdle*:: 58 a certain duration has passed since the last keypress in insert mode 59 60 *InsertKey* `key`:: 61 a key is received in insert mode. This hook will not trigger when the user 62 presses a key on the left-hand side of a insert-mode mapping (see 63 <<mapping#,`:doc mapping`>>), but will trigger for keys on the right-hand 64 side. See also `RawKey` below. 65 66 *InsertChar* `char`:: 67 a character is received in insert mode 68 69 *InsertDelete* `deleted char`:: 70 a character is deleted in insert mode 71 72 *InsertMove* `move key`:: 73 the cursor moved (without inserting) in insert mode 74 75 *PromptIdle*:: 76 a certain duration has passed since the last keypress in prompt mode 77 78 *WinCreate* `buffer name`:: 79 a window was created. This hook is executed in draft context, so any 80 changes to selections or input state will be discarded. 81 82 *WinClose* `buffer name`:: 83 a window was destroyed. This hook is executed in a draft context, so any 84 changes to selections or input state will be discarded. 85 86 *WinResize* `<line>.<column>`:: 87 a window was resized. This hook is executed in a draft context, so any 88 changes to selections or input state will be discarded. 89 90 *WinDisplay* `buffer name`:: 91 a client switched to displaying the given buffer. 92 93 *WinSetOption* `<option_name>=<new_value>`:: 94 an option was set in a window context. This hook is executed in a draft 95 context, so any changes to selections or input state will be discarded. 96 97 *GlobalSetOption* `<option_name>=<new_value>`:: 98 an option was set at the global scope 99 100 *BufSetOption* `<option_name>=<new_value>`:: 101 an option was set in a buffer context 102 103 *BufNewFile* `filename`:: 104 a buffer for a new file has been created 105 106 *BufOpenFile* `filename`:: 107 a buffer for an existing file has been created 108 109 *BufCreate* `filename`:: 110 a buffer has been created 111 112 *BufWritePre* `filename`:: 113 executed just before a buffer is written 114 115 *BufWritePost* `filename`:: 116 executed just after a buffer is written 117 118 *BufReload* `filename`:: 119 executed after a buffer reload has been triggered by an external 120 modification to its file 121 122 *BufClose* `buffer name`:: 123 executed when a buffer is deleted, while it is still valid 124 125 *BufOpenFifo* `buffer name`:: 126 executed when a buffer opens a fifo 127 128 *BufReadFifo* `<start line>.<start column>,<end line>.<end column>`:: 129 executed after some data has been read from a fifo and inserted in 130 the buffer. The hook param contains the range of text that was just 131 inserted, in a format compatible with the `select` command. 132 133 *BufCloseFifo*:: 134 executed when a fifo buffer closes its fifo file descriptor either 135 because the buffer is being deleted or the writing end has been closed 136 137 *ClientCreate* `client name`:: 138 executed when a new client is created. 139 140 *ClientClose* `client name`:: 141 executed when a client is closed, after it was removed from the client 142 list. 143 144 *ClientRenamed* `<old name>:<new name>`:: 145 executed when a client is renamed using the `rename-client` command 146 147 *SessionRenamed* `<old name>:<new name>`:: 148 executed when a session is renamed using the `rename-session` command 149 150 *EnterDirectory* `path`:: 151 executed on startup and when the current working directory is changed 152 using the `change-directory` command. The hook param is an absolute path 153 to the new working directory. 154 155 *RuntimeError* `error message`:: 156 an error was encountered while executing a user command 157 158 *ModeChange* `[push|pop]:<old mode>:<new mode>`:: 159 Triggered whenever a mode is pushed or removed from the mode stack. 160 The mode name can be things like 'normal' or 'insert' for regular 161 interactive modes, or 'next-key[<name>]' for sub-modes where Kakoune 162 prompts for a key. For example, `g` in normal mode pushes 'next-key[goto]' 163 mode, the `enter-user-mode foo` command pushes 'next-key[user.foo]' mode, 164 and the `on-key -mode-name bar` command pushes 'next-key[bar]' mode. 165 166 *KakBegin* `session name`:: 167 Kakoune has started, this hook is called just after reading the user 168 configuration files 169 170 *KakEnd*:: 171 Kakoune is quitting 172 173 *FocusIn* `client name`:: 174 on supported clients, triggered when the client gets focused 175 176 *FocusOut* `client name`:: 177 on supported clients, triggered when the client gets unfocused 178 179 *InsertCompletionShow*:: 180 Triggered when the insert completion menu gets displayed 181 182 *InsertCompletionHide* `completion`:: 183 Triggered when the insert completion menu gets hidden, the list of 184 inserted completions text ranges is passed as filtering text, in the 185 same format the `select` command expects. 186 187 *RawKey* `key`:: 188 Triggered whenever a key is pressed by the user, regardless of what mode 189 Kakoune is in, or what mappings are present (see 190 <<mapping#,`:doc mapping`>>). It cannot be triggered by `execute-keys`, 191 even with the `-with-hooks` option (see 192 <<execeval#execute-keys-specific-switches,`:doc execeval execute-keys-specific-switches`>>). 193 194 *RegisterModified* `register`:: 195 Triggered after a register has been written to. 196 197 *ModuleLoaded* `module`:: 198 Triggered after a module is evaluated by the first `require-module` call 199 200 *User* `param`:: 201 Triggered via the `trigger-user-hook` command. Provides a way for plugins 202 to introduce custom hooks by specifying what *param* would be. 203 204 Note that some hooks will not consider underlying scopes depending on what 205 context they are bound to be run into, e.g. the `BufWritePost` hook is a buffer 206 hook, and will not consider the `window` scope. 207 208 While defining hook commands with a `%sh{}` block, some additional env 209 vars are available: 210 211 * `kak_hook_param`: filtering text passed to the currently executing hook 212 213 * `kak_hook_param_capture_N`: text captured by the hook filter regex capturing 214 group N, N can either be the capturing group number, or its name 215 (See <<regex#groups,`:doc regex groups`>>). 216 217 == Disabling Hooks 218 219 Hooks can be disabled temporarily by prefixing any normal mode command by `\` 220 (see <<keys#,`:doc keys`>>) and permanently by setting the `disabled_hooks` option 221 which accepts a regex describing which hooks won't be executed. For example 222 indentation hooks can be disabled with '.*-indent'. 223 224 Finally, hook execution can be disabled while using the `execute-keys` or 225 `evaluate-commands` commands by using the `-no-hooks` switch. 226 (See <<execeval#,`:doc execeval`>>) 227 228 As an exception to these rules, hooks declared with the `-always` switch 229 are triggered no matter what. A good use case is doing some cleanup on `BufCloseFifo`.