kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

mapping.asciidoc (5005B)


      1 = Mapping
      2 
      3 == Description
      4 
      5 Creating and removing shortcuts boils down to the following commands,
      6 respectively:
      7 
      8 ---------------------------------------
      9 map [switches] <scope> <mode> <key> <keys>
     10 unmap <scope> <mode> <key> [<expected>]
     11 ---------------------------------------
     12 
     13 The *map* command makes *key* behave as if the *keys* sequence was typed.
     14 
     15 *mode* dictates in what context the mapping will be available:
     16 
     17     *insert*::
     18         insert mode
     19 
     20     *normal*::
     21         normal mode
     22 
     23     *prompt*::
     24         prompts, such as when entering a command through *:*, or a regex through */*
     25 
     26     *user*::
     27         mode entered when the user prefix is hit (default: '<space>')
     28 
     29     *goto*::
     30         mode entered when the goto key is hit (default: 'g')
     31 
     32     *view*::
     33         mode entered when the view key is hit (default: 'v')
     34 
     35     *object*::
     36         mode entered when an object selection is triggered (e.g. '<a-i>')
     37 
     38 The context of execution of the above modes is always the current one at the
     39 time of execution of the mapping, except for *user* mode (always executed
     40 in a 'normal' context). Refer to <<modes#,`:doc modes`>> for more details.
     41 
     42 The optional *-atomic* switch controls how counts affect the mapping.
     43 Without *-atomic*, the count is passed to the first key in the mapping.
     44 With *-atomic*, a count greater than one repeats the whole mapping.
     45 
     46 An optional *-docstring* switch followed by a string can be used
     47 to describe what the mapping does. This docstring will be used
     48 in autoinfo boxes.
     49 
     50 The *unmap* command removes a mapping of *key* in the given *scope* and
     51 *mode*. If *expected* is specified, the mapping is removed only if it is
     52 set to the same sequence of keys passed using the *expected* argument.
     53 
     54 For more information about the values of the *scope* parameter, refer to
     55 <<scopes#,`:doc scopes`>>.
     56 
     57 == Mapping commands
     58 
     59 It's common to use a normal-mode or user-mode mapping to trigger a command,
     60 like this:
     61 
     62 ----
     63 map global user n :make-next-error<ret>
     64 ----
     65 
     66 If you make a normal-mode mapping, you can prefix it with a count or a register
     67 name like any other normal-mode key. You can forward this information to the
     68 command you invoke with the `%val{count}` and `%val{register}` expansions
     69 (See <<expansions#,`:doc expansions`>>). For example:
     70 
     71 ----
     72 map global normal = ':echo Got count %val{count} and reg %val{register}<ret>'
     73 ----
     74 
     75 == Mappable keys
     76 
     77 See <<keys#,`:doc keys`>> to learn what each key does in each mode. The keys on
     78 the right-hand side of the mapping are not affected by other mappings, they
     79 always perform their original function.
     80 
     81 For *key* and *keys* in the *map* command, the following key names can
     82 be used:
     83 
     84 *x*, *<x>*::
     85     Most keys, especially alphabetic keys, represent themselves.
     86     Keys can also be wrapped in angle-brackets for consistency
     87     with the non-alphabetic keys below.
     88 
     89 *<c-x>*::
     90     Holding down Control while pressing the *x* key.
     91 
     92 *<a-x>*::
     93     Holding down Alt while pressing the *x* key.
     94 
     95 *<s-x>*, *X*, *<X>*, *<s-X>*::
     96     Holding down Shift while pressing the *x* key.
     97     *<s-x>*, *<s-X>* and *<X>* are treated as the same key. The *s-* modifier
     98     only works with ASCII letters and cannot be used with other printable keys
     99     (non-ASCII letters, digits, punctuation) because their shift behaviour
    100     depends on your keyboard layout. The *s-* modifier _can_ be used with
    101     special keys like *<up>* and *<tab>*.
    102 
    103 *<c-a-x>*::
    104     Holding down Control and Alt while pressing the *x* key.
    105 
    106 *<lt>*, *<gt>*::
    107     The *<* and *>* characters.
    108 
    109 *<plus>*, *<minus>*::
    110     The *+* and *-* characters.
    111 
    112 *<ret>*::
    113     The Return or Enter key.
    114 
    115 *<space>*::
    116     The space bar.
    117 
    118 *<tab>*::
    119     The Tab key.
    120 
    121 *<backspace>*::
    122     The Backspace (delete to the left) key.
    123 
    124 *<del>*::
    125     The Delete (to the right) key.
    126 
    127 *<esc>*::
    128     The Escape key.
    129 
    130 *<up>*, *<down>*, *<left>*, *<right>*::
    131 *<pageup>*, *<pagedown>*, *<home>*, *<end>*::
    132     The usual cursor-movement keys.
    133 
    134 *<ins>*::
    135     The Insert key.
    136 
    137 *<F1>*, *<F2>*, ...*<F12>*::
    138     Function keys.
    139 
    140 *<semicolon>*, *<percent>*, *<quote>*, *<dquote>*::
    141     The *;*, *%*, *'* and *"* characters, these keys allow reducing the amount
    142     of backslash escaping in scripts (for example, `exec \%` becomes `exec
    143     <percent>`)
    144 
    145 NOTE: Although Kakoune allows many key combinations to be mapped, not every
    146 possible combination can be triggered. For example, due to limitations in
    147 the way terminals handle control characters, mappings like *<c-s-a>* are
    148 unlikely to work in Kakoune's terminal UI.
    149 
    150 Some keys, like `<c-c>` and `<c-g>`, cannot be remapped because they are
    151 used to cancel operations. See <<keys#cancelling-operations,`:doc keys cancelling-operations`>>.
    152 
    153 == Default mappings
    154 
    155 Some mappings exist by default in the global scope:
    156 
    157 In normal mode:
    158 
    159   * `<left>`  maps to `h`
    160   * `<right>` maps to `l`
    161   * `<up>`    maps to `k`
    162   * `<down>`  maps to `j`
    163   * `<home>`  maps to `<a-h>`
    164   * `<end>`   maps to `<a-l>`
    165 
    166 Shift version of those mappings exist as well
    167 (for example `<s-left>` maps to `H`).