kakoune/doc/pages/hooks.asciidoc

191 lines
5.6 KiB
Plaintext
Raw Normal View History

= Hooks
== Description
2016-04-08 18:00:24 +02:00
Commands can be registered to be executed when certain events arise. To
2016-02-10 22:03:49 +01:00
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`>>).
2016-02-10 22:03:49 +01:00
*command* is a string containing the commands to execute when the hook
is called.
2016-02-10 22:03:49 +01:00
For example to automatically use line numbering with .cc files, use the
following command:
----------------------------------------------------
2017-01-04 01:07:45 +01:00
hook global WinCreate .*\.cc %{ add-highlighter number_lines }
----------------------------------------------------
If *group* is given, make this hook part of the named group. Groups are used
2016-02-10 22:03:49 +01:00
for removing hooks with the following command:
-----------------------
2017-01-04 01:07:45 +01:00
remove-hooks <scope> <group>
-----------------------
2016-02-10 22:03:49 +01:00
A call to the command above will remove every hooks in *scope* that are part
of the given *group*.
== Default hooks
*NormalIdle*::
2017-11-02 10:37:39 +01:00
a certain duration has passed since last key was pressed in normal mode
*NormalBegin*::
2017-11-02 10:37:39 +01:00
entering normal mode
*NormalEnd*::
2017-11-02 10:37:39 +01:00
leaving normal mode
*NormalKey*::
2017-11-02 10:37:39 +01:00
a key is received in normal mode, the key is used for filtering
*InsertIdle*::
2017-11-02 10:37:39 +01:00
a certain duration has passed since last key was pressed in insert mode
*InsertBegin*::
2017-11-02 10:37:39 +01:00
entering insert mode
*InsertEnd*::
2017-11-02 10:37:39 +01:00
leaving insert mode
*InsertKey*::
2017-11-02 10:37:39 +01:00
a key is received in insert mode, the key is used for filtering
2016-06-20 20:30:28 +02:00
*InsertChar*::
2017-11-02 10:37:39 +01:00
a character is received in insert mode, the character is used for
filtering
2016-06-20 20:30:28 +02:00
2017-03-30 11:38:56 +02:00
*InsertDelete*::
2017-11-02 10:37:39 +01:00
a character is deleted in insert mode, the character deleted by
the main selection is used for filtering
2017-03-30 11:38:56 +02:00
*InsertMove*::
2017-11-02 10:37:39 +01:00
the cursor moved (without inserting) in insert mode, the key that
triggered the move is used for filtering
*PromptIdle*::
2017-11-02 10:37:39 +01:00
a certain duration has passed since last key was pressed in prompt mode
*WinCreate*::
2017-11-02 10:37:39 +01:00
a window was created, the filtering text is the buffer name
*WinClose*::
2017-11-02 10:37:39 +01:00
a window was destroyed, the filtering text is the buffer name
2016-05-13 10:33:11 +02:00
*WinResize*::
2017-11-02 10:37:39 +01:00
a window resized, the filtering text is *<line>.<column>*
2016-05-13 10:33:11 +02:00
*WinDisplay*::
2017-11-02 10:37:39 +01:00
a window was bound a client, the filtering text is the buffer name
*WinSetOption*::
2017-11-02 10:37:39 +01:00
an option was set in a window context, the filtering text is
*<option_name>=<new_value>*
*BufSetOption*::
2017-11-02 10:37:39 +01:00
an option was set in a buffer context, the filtering text is
*<option_name>=<new_value>*
*BufNewFile*::
2017-11-02 10:37:39 +01:00
a buffer for a new file has been created, filename is used for
filtering
*BufOpenFile*::
2017-11-02 10:37:39 +01:00
a buffer for an existing file has been created, filename is used
for filtering
*BufCreate*::
2017-11-02 10:37:39 +01:00
a buffer has been created, filename is used for filtering
*BufWritePre*::
2017-11-02 10:37:39 +01:00
executed just before a buffer is written, filename is used for
filtering
*BufWritePost*::
2017-11-02 10:37:39 +01:00
executed just after a buffer is written, filename is used for filtering
*BufClose*::
2017-11-02 10:37:39 +01:00
executed when a buffer is deleted, while it is still valid
*BufOpenFifo*::
2017-11-02 10:37:39 +01:00
executed when a buffer opens a fifo
*BufReadFifo*::
2017-11-02 10:37:39 +01:00
executed after some data has been read from a fifo and inserted in
the buffer
*BufCloseFifo*::
2017-11-02 10:37:39 +01:00
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*::
2017-11-02 10:37:39 +01:00
an error was encountered while executing a user command the error
message is used for filtering
*KakBegin*::
2017-11-02 10:37:39 +01:00
kakoune has started, this hook is called just after reading the user
configuration files
*KakEnd*::
2017-11-02 10:37:39 +01:00
kakoune is quitting
*FocusIn*::
2017-11-02 10:37:39 +01:00
on supported clients, triggered when the client gets focused. The
filtering text is the client name
*FocusOut*::
2017-11-02 10:37:39 +01:00
on supported clients, triggered when the client gets unfocused. The
filtering text is the client name
*InsertCompletionShow*::
2017-11-02 10:37:39 +01:00
Triggered when the insert completion menu gets displayed
*InsertCompletionHide*::
2017-11-02 10:37:39 +01:00
Triggered when the insert completion menu gets hidden
*InsertCompletionSelect*::
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*::
2017-11-02 10:37:39 +01:00
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.
2017-06-26 18:50:22 +02:00
While defining hook commands with a `%sh{}` block, some additional env
vars are available:
2017-06-26 18:50:22 +02:00
* `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
2017-06-26 18:50:22 +02:00
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`>>)