a36473f4bb
Commit217dd6a1d(Disable history when executing maps, 2015-11-10) made it so with map global normal X %{:echo 123<ret>} X does not add to prompt history (%reg{:}). Unfortunately this behavior was not extended to mappings in the "user" keymap, nor to mappings in custom user modes. In my experience, not adding to history is almost always the expected behavior for mappings. Most users achieve this by adding a leading space: map global user X %{: echo 123<ret>} but that's awkward. We should have good defaults (no nnoremap) and map should work the same way across all modes. Fix this by also disabling history when executing user mappings. This is a breaking change but I think it only breaks hypothetical scenarios. I found some uses where user mappings add to history but none of them looks intentional.f702a641d1/.config/kak/kakrc (L169)604ef1c1c2/kakrc (L96)d22e7d6f68/kak/kakrc (L71)https://grep.app/search?q=map%20%28global%7Cbuffer%7Cwindow%29%20user%20.%2A%5B%21%3A/%5D%5B%5E%20%5D.%2A%3Cret%3E®exp=true
162 lines
4.4 KiB
Plaintext
162 lines
4.4 KiB
Plaintext
= Mapping
|
|
|
|
== Description
|
|
|
|
Creating and removing shortcuts boils down to the following commands,
|
|
respectively:
|
|
|
|
---------------------------------------
|
|
map [switches] <scope> <mode> <key> <keys>
|
|
unmap <scope> <mode> <key> [<expected>]
|
|
---------------------------------------
|
|
|
|
The *map* command makes *key* behave as if the *keys* sequence was typed.
|
|
|
|
*mode* dictates in what context the mapping will be available:
|
|
|
|
*insert*::
|
|
insert mode
|
|
|
|
*normal*::
|
|
normal mode
|
|
|
|
*prompt*::
|
|
prompts, such as when entering a command through *:*, or a regex through */*
|
|
|
|
*menu*::
|
|
mode entered when a menu is displayed with the 'menu' command
|
|
|
|
*user*::
|
|
mode entered when the user prefix is hit (default: ',')
|
|
|
|
*goto*::
|
|
mode entered when the goto key is hit (default: 'g')
|
|
|
|
*view*::
|
|
mode entered when the view key is hit (default: 'v')
|
|
|
|
*object*::
|
|
mode entered when an object selection is triggered (e.g. '<a-i>')
|
|
|
|
The context of execution of the above modes is always the current one at the
|
|
time of execution of the mapping, except for *user* mode (always executed
|
|
in a 'normal' context). Refer to <<modes#,`:doc modes`>> for more details.
|
|
|
|
An optional *-docstring* switch followed by a string can be used
|
|
to describe what the mapping does. This docstring will be used
|
|
in autoinfo boxes.
|
|
|
|
The *unmap* command removes a mapping of *key* in the given *scope* and
|
|
*mode*. If *expected* is specified, the mapping is removed only if it is
|
|
set to the same sequence of keys passed using the *expected* argument.
|
|
|
|
For more information about the values of the *scope* parameter, refer to
|
|
<<scopes#,`:doc scopes`>>.
|
|
|
|
== Mapping commands
|
|
|
|
It's common to use a normal-mode or user-mode mapping to trigger a command,
|
|
like this:
|
|
|
|
----
|
|
map global user n :make-next-error<ret>
|
|
----
|
|
|
|
If you make a normal-mode mapping, you can prefix it with a count or a register
|
|
name like any other normal-mode key. You can forward this information to the
|
|
command you invoke with the `%val{count}` and `%val{register}` expansions
|
|
(See <<expansions#`:doc expansions`>>). For example:
|
|
|
|
----
|
|
map global normal = ': echo Got count %val{count} and reg %val{register}<ret>'
|
|
----
|
|
|
|
== Mappable keys
|
|
|
|
See <<keys#,`:doc keys`>> to discover the list of default bindings.
|
|
|
|
For *key* and *keys* in the *map* command, the following key names can
|
|
be used:
|
|
|
|
*x*, *<x>*::
|
|
Most keys, especially alphabetic keys, represent themselves.
|
|
Keys can also be wrapped in angle-brackets for consistency
|
|
with the non-alphabetic keys below.
|
|
|
|
*<c-x>*::
|
|
Holding down Control while pressing the *x* key.
|
|
|
|
*<a-x>*::
|
|
Holding down Alt while pressing the *x* key.
|
|
|
|
*<s-x>*, *X*, *<X>*, *<s-X>*::
|
|
Holding down Shift while pressing the *x* key.
|
|
*<s-x>*, *<s-X>* and *<X>* are treated as the same key. The *s-* modifier
|
|
only works with ASCII letters and cannot be used with other printable keys
|
|
(non-ASCII letters, digits, punctuation) because their shift behaviour
|
|
depends on your keyboard layout. The *s-* modifier _can_ be used with
|
|
special keys like *<up>* and *<tab>*.
|
|
|
|
*<c-a-x>*::
|
|
Holding down Control and Alt while pressing the *x* key.
|
|
|
|
*<lt>*, *<gt>*::
|
|
The *<* and *>* characters.
|
|
|
|
*<plus>*, *<minus>*::
|
|
The *+* and *-* characters.
|
|
|
|
*<ret>*::
|
|
The Return or Enter key.
|
|
|
|
*<space>*::
|
|
The space bar.
|
|
|
|
*<tab>*::
|
|
The Tab key.
|
|
|
|
*<backspace>*::
|
|
The Backspace (delete to the left) key.
|
|
|
|
*<del>*::
|
|
The Delete (to the right) key.
|
|
|
|
*<esc>*::
|
|
The Escape key.
|
|
|
|
*<up>*, *<down>*, *<left>*, *<right>*::
|
|
*<pageup>*, *<pagedown>*, *<home>*, *<end>*::
|
|
The usual cursor-movement keys.
|
|
|
|
*<ins>*::
|
|
The Insert key.
|
|
|
|
*<F1>*, *<F2>*, ...*<F12>*::
|
|
Function keys.
|
|
|
|
*<semicolon>*, *<percent>*::
|
|
The *;* and *%* characters, these keys allow reducing the amount of
|
|
backslash escaping in scripts (for example, `exec \%` becomes `exec
|
|
<percent>`)
|
|
|
|
NOTE: Although Kakoune allows many key combinations to be mapped, not every
|
|
possible combination can be triggered. For example, due to limitations in
|
|
the way terminals handle control characters, mappings like *<c-s-a>* are
|
|
unlikely to work in Kakoune's terminal UI.
|
|
|
|
== Default mappings
|
|
|
|
Some mappings exist by default in the global scope:
|
|
|
|
In normal mode:
|
|
|
|
* `<left>` maps to `h`
|
|
* `<right>` maps to `l`
|
|
* `<up>` maps to `k`
|
|
* `<down>` maps to `j`
|
|
* `<home>` maps to `<a-h>`
|
|
* `<end>` maps to `<a-l>`
|
|
|
|
Shift version of those mappings exist as well
|
|
(for example `<s-left>` maps to `H`).
|