Skip to content

Latest commit

 

History

History
165 lines (116 loc) · 4.63 KB

mapping.asciidoc

File metadata and controls

165 lines (116 loc) · 4.63 KB

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 :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 :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>'

Note the space between the : and the command. This prevents Kakoune from adding this command to the prompt history, so the user won’t have to scroll past it to review commands they actually typed.

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.asciidoc). For example:

map global normal = ': echo Got count %val{count} and reg %val{register}<ret>'

Mappable keys

See :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).