kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

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`.