home/doc/pages/mapping.asciidoc

= 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.

Some keys, like `<c-c>` and `<c-g>`, cannot be remapped because they are
used to cancel operations. See <<keys#cancelling-operations,`:doc keys cancelling-operations`>>.

== 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`).