186 lines
5.4 KiB
Plaintext
186 lines
5.4 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>] <scope> <hook_name> <filtering_regex> <commands>
|
|
----------------------------------------------------------------------
|
|
|
|
*scope* can be one of *global*, *buffer* or *window* (See
|
|
<<scopes#,`:doc scopes`>>).
|
|
|
|
*command* is a string containing the commands to execute when the hook
|
|
is called.
|
|
|
|
For example to automatically use line numbering with .cc files, use the
|
|
following command:
|
|
|
|
----------------------------------------------------
|
|
hook global WinCreate .*\.cc %{ add-highlighter number_lines }
|
|
----------------------------------------------------
|
|
|
|
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 hooks in *scope* that are part
|
|
of the given *group*.
|
|
|
|
== Default hooks
|
|
|
|
*NormalIdle*::
|
|
a certain duration has passed since last key was pressed in normal mode
|
|
|
|
*NormalBegin*::
|
|
entering normal mode
|
|
|
|
*NormalEnd*::
|
|
leaving normal mode
|
|
|
|
*NormalKey*::
|
|
a key is received in normal mode, the key is used for filtering
|
|
|
|
*InsertIdle*::
|
|
a certain duration has passed since last key was pressed in insert mode
|
|
|
|
*InsertBegin*::
|
|
entering insert mode
|
|
|
|
*InsertEnd*::
|
|
leaving insert mode
|
|
|
|
*InsertKey*::
|
|
a key is received in insert mode, the key is used for filtering
|
|
|
|
*InsertChar*::
|
|
a character is received in insert mode, the character is used for
|
|
filtering
|
|
|
|
*InsertDelete*::
|
|
a character is deleted in insert mode, the character deleted by
|
|
the main selection is used for filtering
|
|
|
|
*InsertMove*::
|
|
the cursor moved (without inserting) in insert mode, the key that
|
|
triggered the move is used for filtering
|
|
|
|
*PromptIdle*::
|
|
a certain duration has passed since last key was pressed in prompt mode
|
|
|
|
*WinCreate*::
|
|
a window was created, the filtering text is the buffer name
|
|
|
|
*WinClose*::
|
|
a window was destroyed, the filtering text is the buffer name
|
|
|
|
*WinResize*::
|
|
a window resized, the filtering text is *<line>.<column>*
|
|
|
|
*WinDisplay*::
|
|
a window was bound a client, the filtering text is the buffer name
|
|
|
|
*WinSetOption*::
|
|
an option was set in a window context, the filtering text is
|
|
*<option_name>=<new_value>*
|
|
|
|
*BufSetOption*::
|
|
an option was set in a buffer context, the filtering text is
|
|
*<option_name>=<new_value>*
|
|
|
|
*BufNewFile*::
|
|
a buffer for a new file has been created, filename is used for
|
|
filtering
|
|
|
|
*BufOpenFile*::
|
|
a buffer for an existing file has been created, filename is used
|
|
for filtering
|
|
|
|
*BufCreate*::
|
|
a buffer has been created, filename is used for filtering
|
|
|
|
*BufWritePre*::
|
|
executed just before a buffer is written, filename is used for
|
|
filtering
|
|
|
|
*BufWritePost*::
|
|
executed just after a buffer is written, filename is used for filtering
|
|
|
|
*BufClose*::
|
|
executed when a buffer is deleted, while it is still valid
|
|
|
|
*BufOpenFifo*::
|
|
executed when a buffer opens a fifo
|
|
|
|
*BufReadFifo*::
|
|
executed after some data has been read from a fifo and inserted in
|
|
the buffer
|
|
|
|
*BufCloseFifo*::
|
|
executed when a fifo buffer closes its fifo file descriptor either
|
|
because the buffer is being deleted,
|
|
or because the writing end has been closed
|
|
|
|
*RuntimeError*::
|
|
an error was encountered while executing a user command the error
|
|
message is used for filtering
|
|
|
|
*KakBegin*::
|
|
kakoune has started, this hook is called just after reading the user
|
|
configuration files
|
|
|
|
*KakEnd*::
|
|
kakoune is quitting
|
|
|
|
*FocusIn*::
|
|
on supported clients, triggered when the client gets focused. The
|
|
filtering text is the client name
|
|
|
|
*FocusOut*::
|
|
on supported clients, triggered when the client gets unfocused. The
|
|
filtering text is the client name
|
|
|
|
*InsertCompletionShow*::
|
|
Triggered when the insert completion menu gets displayed
|
|
|
|
*InsertCompletionHide*::
|
|
Triggered when the insert completion menu gets hidden
|
|
|
|
*RawKey*::
|
|
Triggered whenever a key is pressed by the user, the key is
|
|
used for filtering.
|
|
|
|
When not specified, the filtering text is an empty string. 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, you have access to
|
|
the following expansions:
|
|
|
|
* `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`>>)
|