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