9a68a2d3af
the buffer name was not a very interesting information, whereas the buffer range allows a hook to run only on the appended text instead of all the buffer.
207 lines
6.6 KiB
Plaintext
207 lines
6.6 KiB
Plaintext
= 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
|
|
|
|
*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*::
|
|
Triggered when the insert completion menu gets hidden
|
|
|
|
*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 capture N
|
|
|
|
== 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`.
|