kakoune

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

keys.asciidoc (20911B)


      1 = Keys
      2 
      3 == Key Syntax
      4 
      5 Usual keys are written using their ascii character, including capital
      6 keys. Non printable keys use an alternate name, written between *<*
      7 and *>*, such as *<esc>* or *<del>*. Modified keys are written between
      8 *<* and *>* as well, with the modifier specified as either *c* for
      9 Control, *a* for Alt, or *s* for Shift, followed by a *-* and the key (either
     10 its name or ascii character), for example *<c-x>*, *<a-space>*, *<c-a-w>*.
     11 
     12 In order to bind some keys to arbitrary ones, refer to <<mapping#,`:doc mapping`>>
     13 
     14 == Insert mode
     15 
     16 *<esc>*::
     17     leave insert mode
     18 
     19 *<backspace>*::
     20     delete characters before cursors
     21 
     22 *<del>*::
     23     delete characters under cursors
     24 
     25 *<left>*, *<right>*, *<up>*, *<down>*::
     26     move the cursors in given direction
     27 
     28 *<home>*::
     29     move cursors to line begin
     30 
     31 *<end>*::
     32     move cursors to end of line
     33 
     34 *<c-r>*::
     35     insert contents of the register given by next key
     36 
     37 *<c-v>*::
     38     insert next keystroke directly into the buffer, without interpreting it
     39 
     40 *<c-u>*::
     41     commit changes up to now as a single undo group
     42 
     43 *<a-;>*, *<a-semicolon>*::
     44     escape to normal mode for a single command
     45 
     46 == Insert mode completion
     47 
     48 The `completers` option controls automatic completion, which kicks in when
     49 the value specified in the `idle_timeout` option is reached.
     50 
     51 *<c-o>*::
     52     toggle automatic completion
     53 
     54 *<c-n>*::
     55     select next completion candidate
     56 
     57 *<c-p>*::
     58     select previous completion candidate
     59 
     60 *<c-x>*::
     61     explicit insert completion query, followed by:
     62 
     63     *f*:::
     64         explicit file completion
     65 
     66     *w*:::
     67         explicit word completion (current buffer)
     68 
     69     *W*:::
     70         explicit word completion (all buffers)
     71 
     72     *l*:::
     73         explicit line completion (current buffer)
     74 
     75     *L*:::
     76         explicit line completion (all buffers)
     77 
     78 == Using Counts
     79 
     80 In normal mode, commands can be prefixed with a numeric `count`, which can control
     81 the command behaviour.
     82 
     83 For example, *3W* selects 3 consecutive words and *3w* select the third word on
     84 the right of the end of each selection.
     85 
     86 == Disabling Hooks
     87 
     88 Any normal mode command can be prefixed with `\` which will disable hook execution
     89 for the duration for the command (including the duration of modes the command could
     90 move to, so `\i` will disable hooks for the whole insert session) (see
     91 <<hooks#,`:doc hooks`>>).
     92 
     93 As autoindentation is implemented in terms of hooks, this can be used to disable
     94 it when pasting text.
     95 
     96 == Movement
     97 
     98 'word' is a sequence of alphanumeric characters, or those in the `extra_word_chars`
     99 option (see <<options#builtin-options,`:doc options builtin-options`>>).
    100 'WORD' is a sequence of non whitespace characters. Generally, a movement on its own
    101 will move each selection to cover the text moved over, while holding down
    102 the Shift modifier and moving will extend each selection instead.
    103 
    104 *h*::
    105     select the character on the left of the end of each selection
    106     `<left>` maps to this by default.
    107     (See <<mapping#default-mappings,`:doc mapping default-mappings`>>)
    108 
    109 *j*::
    110     select the character below the end of each selection
    111     `<down>` maps to this by default.
    112     (See <<mapping#default-mappings,`:doc mapping default-mappings`>>)
    113 
    114 *k*::
    115     select the character above the end of each selection
    116     `<up>` maps to this by default.
    117     (See <<mapping#default-mappings,`:doc mapping default-mappings`>>)
    118 
    119 *l*::
    120     select the character on the right of the end of each selection
    121     `<right>` maps to this by default.
    122     (See <<mapping#default-mappings,`:doc mapping default-mappings`>>)
    123 
    124 *w*::
    125     select the word and following whitespaces on the right of the end of each selection
    126 
    127 *b*::
    128     select preceding whitespaces and the word on the left of the end of each selection
    129 
    130 *e*::
    131     select preceding whitespaces and the word on the right of the end of each selection
    132 
    133 *<a-[wbe]>*::
    134     same as [wbe] but select WORD instead of word
    135 
    136 *f*::
    137     select to the next occurrence of given character
    138 
    139 *t*::
    140     select until the next occurrence of given character
    141 
    142 *<a-[ft]>*::
    143     same as [ft] but in the other direction
    144 
    145 *<a-.>*::
    146     repeat last object or *f*/*t* selection command
    147 
    148 *m*::
    149     select to the next sequence enclosed by matching characters, see the
    150     `matching_pairs` option in <<options#,`:doc options`>>
    151 
    152 *M*::
    153     extend the current selection to the next sequence enclosed by matching
    154     character, see the `matching_pairs` option in <<options#,`:doc options`>>
    155 
    156 *<a-m>*::
    157     select to the previous sequence enclosed by matching characters, see the
    158     `matching_pairs` option in <<options#,`:doc options`>>
    159 
    160 *<a-M>*::
    161     extend the current selection to the previous sequence enclosed by matching
    162     characters, see the `matching_pairs` option in <<options#,`:doc options`>>
    163 
    164 *x*::
    165     expand selections to contain full lines (including end-of-lines)
    166 
    167 *<a-x>*::
    168     trim selections to only contain full lines (not including last
    169     end-of-line)
    170 
    171 *%*, *<percent>*::
    172     select whole buffer
    173 
    174 *<a-h>*::
    175     select to line begin
    176     `<home>` maps to this by default.
    177     (See <<mapping#default-mappings,`:doc mapping default-mappings`>>)
    178 
    179 *<a-l>*::
    180     select to line end
    181     `<end>` maps to this by default.
    182     (See <<mapping#default-mappings,`:doc mapping default-mappings`>>)
    183 
    184 *<pageup>, <c-b>*::
    185     scroll one page up
    186 
    187 *<pagedown>, <c-f>*::
    188     scroll one page down
    189 
    190 *<c-u>*::
    191     scroll half a page up
    192 
    193 *<c-d>*::
    194     scroll half a page down
    195 
    196 *;*, *<semicolon>*::
    197     reduce selections to their cursor
    198 
    199 *<a-;>*, *<a-semicolon>*::
    200     flip the direction of each selection
    201 
    202 *<a-:>*::
    203     ensure selections are in forward direction (cursor after anchor)
    204 
    205 == Changes
    206 
    207 Yanking (copying) and pasting use the *"* register by default (See <<registers#,`:doc registers`>>)
    208 
    209 *i*::
    210     enter insert mode before selections
    211 
    212 *a*::
    213     enter insert mode after selections
    214 
    215 *d*::
    216     yank and delete selections
    217 
    218 *c*::
    219     yank and delete selections and enter insert mode
    220 
    221 *.*::
    222     repeat last insert mode change (*i*, *a*, or *c*, including the
    223     inserted text)
    224 
    225 *<a-d>*::
    226     delete selections (not yanking)
    227 
    228 *<a-c>*::
    229     delete selections and enter insert mode (not yanking)
    230 
    231 *I*::
    232     enter insert mode at the beginning of the lines containing
    233     the start of each selection
    234 
    235 *A*::
    236     enter insert mode at the end of the lines containing
    237     the end of each selection
    238 
    239 *o*::
    240     enter insert mode in a new line (or in a given `count` of new lines)
    241     below the end of each selection
    242 
    243 *O*::
    244     enter insert mode in a new line (or in a given `count` of new lines)
    245     above the beginning of each selection
    246 
    247 *<a-o>*::
    248     add an empty line below cursor
    249 
    250 *<a-O>*::
    251     add an empty line above cursor
    252 
    253 *y*::
    254     yank selections
    255 
    256 *p*::
    257     paste after the end of each selection
    258 
    259 *P*::
    260     paste before the beginning of each selection
    261 
    262 *<a-p>*::
    263     paste all after the end of each selection, and select each pasted string
    264 
    265 *<a-P>*::
    266     paste all before the start of each selection, and select each pasted string
    267 
    268 *R*::
    269     replace selections with yanked text
    270 
    271 *<a-R>*::
    272     replace selections with every yanked text
    273 
    274 *r*::
    275     replace each character with the next entered one
    276 
    277 *<a-j>*::
    278     join selected lines
    279 
    280 *<a-J>*::
    281     join selected lines and select spaces inserted in place of line breaks
    282 
    283 *<a-_>*::
    284     merge contiguous selections together (works across lines as well)
    285 
    286 *<+>*, *<plus>*::
    287     duplicate each selection (generating overlapping selections)
    288 
    289 *<a-+>*, *<a-plus>*::
    290     merge overlapping selections
    291 
    292 *>*, *<gt>*::
    293     indent selected lines
    294 
    295 *<a-\>>*, *<a-gt>*::
    296     indent selected lines, including empty lines
    297 
    298 *<*, *<lt>*::
    299     unindent selected lines
    300 
    301 *<a-<>*, *<a-lt>*::
    302     unindent selected lines, do not remove incomplete indent (3 leading
    303     spaces when indent is 4)
    304 
    305 *u*::
    306     undo last change
    307 
    308 *U*::
    309     redo last change
    310 
    311 *<c-j>*::
    312     move forward in changes history
    313 
    314 *<c-k>*::
    315     move backward in changes history
    316 
    317 *<a-u>*::
    318     undo last selection change
    319 
    320 *<a-U>*::
    321     redo last selection change
    322 
    323 *&*::
    324     align selections, align the cursor of each selection by inserting spaces
    325     before the first character of each selection
    326 
    327 *<a-&>*::
    328     copy indent, copy the indentation of the main selection (or the
    329     `count` one if a `count` is given) to all other ones
    330 
    331 *`*::
    332     to lower case
    333 
    334 *~*::
    335     to upper case
    336 
    337 *<a-`>*::
    338     swap case
    339 
    340 *@*::
    341     convert tabs to spaces in each selection, uses the buffer tabstop
    342     option or the `count` parameter for tabstop
    343 
    344 *<a-@>*::
    345     convert spaces to tabs in each selection, uses the buffer tabstop
    346     option or the `count` parameter for tabstop
    347 
    348 *_*::
    349     unselect whitespace surrounding each selection, drop those that only
    350     contain whitespace
    351 
    352 *<a-)>*::
    353     rotate selections content, if specified, the `count` groups selections,
    354     so the following command
    355 
    356 ----------
    357     3<a-)>
    358 ----------
    359 
    360     rotates (1, 2, 3) and (3, 4, 6) independently
    361 
    362 *<a-(>*::
    363     rotate selections content backward
    364 
    365 == Changes through external programs
    366 
    367 Shell expansions are available, (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)
    368 The default command comes from the *|* register (See <<registers#,`:doc registers`>>)
    369 
    370 *|*::
    371     pipe each selection through the given external filter program and
    372     replace the selection with its output.
    373 
    374 *<a-|>*::
    375     pipe each selection through the given external filter program and
    376     ignore its output.
    377 
    378 *!*::
    379     insert and select command output before each selection.
    380 
    381 *<a-!>*::
    382     append and select command output after each selection.
    383 
    384 == Searching
    385 
    386 Searches use the */* register by default (See <<registers#,`:doc registers`>>)
    387 
    388 */*::
    389     select next match after each selection
    390 
    391 *<a-/>*::
    392     select previous match before each selection
    393 
    394 *?*::
    395     extend to next match after each selection
    396 
    397 *<a-?>*::
    398     extend to previous match before each selection
    399 
    400 *n*::
    401     select next match after the main selection
    402 
    403 *N*::
    404     add a new selection with next match after the main selection
    405 
    406 *<a-n>*::
    407     select previous match before the main selection
    408 
    409 *<a-N>*::
    410     add a new selection with previous match before the main selection
    411 
    412 ***::
    413     set the search pattern to the main selection (automatically
    414     detects word boundaries)
    415 
    416 *<a-***>*::
    417     set the search pattern to the main selection (verbatim, no smart
    418     detection)
    419 
    420 == Goto commands
    421 
    422 *g*, *G*::
    423     When a `count` is specified, *G* only extends the selection to the given line,
    424     *g* sends the anchor to the given line and a menu is then displayed which waits
    425     for one of the following additional keys:
    426 
    427     *h*:::
    428         go to line begin
    429 
    430     *l*:::
    431         go to line end
    432 
    433     *u*:::
    434         go up one display line
    435 
    436     *d*:::
    437         go down one display line
    438 
    439     *i*:::
    440         go to non blank line start
    441 
    442     *g*, *k*:::
    443         go to the first line
    444 
    445     *j*:::
    446         go to the last line
    447 
    448     *e*:::
    449         go to last char of last line
    450 
    451     *t*:::
    452         go to the first displayed line
    453 
    454     *c*:::
    455         go to the middle displayed line
    456 
    457     *b*:::
    458         go to the last displayed line
    459 
    460     *a*:::
    461         go to the previous (alternate) buffer
    462 
    463     *f*:::
    464         open the file whose name is selected
    465 
    466     *.*:::
    467         go to last buffer modification position
    468 
    469 == View commands
    470 
    471 *v*, *V*::
    472     *V* enters lock view mode (which will be left when the <esc> is hit),
    473     and *v* modifies the current view; a menu is then displayed which waits
    474     for one of the following additional keys:
    475 
    476     *v*, *c*:::
    477         center the main selection in the window (vertically)
    478 
    479     *m*:::
    480         center the main selection in the window (horizontally)
    481 
    482     *t*:::
    483         scroll to put the main selection on the top line of the window
    484 
    485     *b*:::
    486         scroll to put the main selection on the bottom line of the window
    487 
    488     *<*:::
    489         scroll to put the main cursor on the leftmost column of the window
    490 
    491     *>*:::
    492         scroll to put the main cursor on the rightmost column of the window
    493 
    494     *h*:::
    495         scroll the window `count` columns left
    496 
    497     *j*:::
    498         scroll the window `count` line downward
    499 
    500     *k*:::
    501         scroll the window `count` line upward
    502 
    503     *l*:::
    504         scroll the window `count` columns right
    505 
    506 == Marks
    507 
    508 Current selections position can be saved in a register and restored later on.
    509 Marks use the *^* register by default (See <<registers#,`:doc registers`>>)
    510 
    511 *Z*::
    512     save selections to the register
    513 
    514 *z*::
    515     restore selections from the register
    516 
    517 *<a-z>*, *<a-Z>*::
    518     *<a-z>* combines selections from the register with the current ones, whereas
    519     *<a-Z>* combines current selections with the ones in the register; a menu
    520     is then displayed which waits for one of the following additional keys:
    521 
    522     *a*:::
    523         append selections
    524 
    525     *u*:::
    526         keep a union of selections
    527 
    528     *i*:::
    529         keep an intersection of selections
    530 
    531     *<*:::
    532         select the selection with the leftmost cursor for each pair
    533 
    534     *>*:::
    535         select the selection with the rightmost cursor for each pair
    536 
    537     *+*:::
    538         select the longest selection
    539 
    540     *-*:::
    541         select the shortest selection
    542 
    543 == Macros
    544 
    545 Macros use the *@* register by default (See <<registers#,`:doc registers`>>)
    546 
    547 *Q*::
    548     start or end macro recording
    549 
    550 *q*::
    551     play a recorded macro
    552 
    553 == Jump list
    554 
    555 Some commands, like the goto commands, buffer switch or search commands,
    556 push the previous selections to the client's jump list. It is possible
    557 to skim through the jump list using:
    558 
    559 *<c-i>*::
    560     jump forward
    561 
    562 *<c-o>*::
    563     jump backward
    564 
    565 *<c-s>*::
    566     create a jump step, but also save the current selection to have it be
    567     restored when the step is subsequently cycled through
    568 
    569 == Multiple selections
    570 
    571 *s*, *S*, *<a-k>* and *<a-K>* use the */* register by default (See <<registers#,`:doc registers`>>)
    572 
    573 *s*::
    574     create a selection for each match of the given regex
    575     (selects the count capture if it is given)
    576 
    577 *S*::
    578     split selections with the given regex
    579     (selects the count capture if it is given)
    580 
    581 *<a-s>*::
    582     split selections on line boundaries
    583 
    584 *<a-S>*::
    585     select first and last characters of each selection
    586 
    587 *C*::
    588     duplicate selections on the lines that follow them
    589 
    590 *<a-C>*::
    591     duplicate selections on the lines that precede them
    592 
    593 *,*::
    594     clear selections to only keep the main one
    595 
    596 *<a-,>*::
    597     clear the main selection
    598 
    599 *<a-k>*::
    600     keep selections that match the given regex
    601 
    602 *<a-K>*::
    603     clear selections that match the given regex
    604 
    605 *$*::
    606     pipe each selection to the given shell command and keep the ones
    607     for which the shell returned 0. Shell expansions are available,
    608     (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)
    609 
    610 *)*::
    611     rotate main selection (the main selection becomes the next one)
    612 
    613 *(*::
    614     rotate main selection backward (the main selection becomes the previous one)
    615 
    616 == Object Selection
    617 
    618 For nestable objects, a `count` can be used in order to specify which surrounding
    619 level to select. Object selections are repeatable using *<a-.>*.
    620 
    621 === Whole object
    622 
    623 A 'whole object' is an object *including* its surrounding characters.
    624 For example, for a quoted string this will select the quotes, and
    625 for a word this will select trailing spaces.
    626 
    627 *<a-a>*::
    628     select the whole surrounding object
    629 
    630 *[*::
    631     select to the whole surrounding object start
    632 
    633 *]*::
    634     select to the whole surrounding object end
    635 
    636 *{*::
    637     extend selections to the whole surrounding object start
    638 
    639 *}*::
    640     extend selections to the whole surrounding object end
    641 
    642 *<a-A>:: select each whole nested object in selections
    643 
    644 === Inner object
    645 
    646 An 'inner object' is an object *excluding* its surrounding characters.
    647 For example, for a quoted string this will *not* select the quotes, and
    648 for a word this will *not* select trailing spaces.
    649 
    650 *<a-i>*::
    651     select the surrounding inner object
    652 
    653 *<a-[>*::
    654     select to the surrounding inner object start
    655 
    656 *<a-]>*::
    657     select to the surrounding inner object end
    658 
    659 *<a-{>*::
    660     extend selections to the surrounding inner object start
    661 
    662 *<a-}>*::
    663     extend selections to the surrounding inner object end
    664 
    665 *<a-I>*::
    666     select each inner nested object in selections
    667 
    668 === Objects types
    669 
    670 After the keys described above, a second key needs to be entered
    671 in order to specify the wanted object:
    672 
    673 *b*, *(*, *)*::
    674     select the enclosing parenthesis
    675 
    676 *B*, *{*, *}*::
    677     select the enclosing {} block
    678 
    679 *r*, *[*, *]*::
    680     select the enclosing [] block
    681 
    682 *a*, *<*, *>*::
    683     select the enclosing <> block
    684 
    685 *Q*, *"*::
    686     select the enclosing double quoted string
    687 
    688 *q*, *'*::
    689     select the enclosing single quoted string
    690 
    691 *g*, *`*::
    692     select the enclosing grave quoted string
    693 
    694 *w*::
    695     select the whole word
    696 
    697 *<a-w>*::
    698     select the whole WORD
    699 
    700 *s*::
    701     select the sentence
    702 
    703 *p*::
    704     select the paragraph
    705 
    706 *␣*::
    707     select the whitespaces
    708 
    709 *i*::
    710     select the current indentation block
    711 
    712 *n*::
    713     select the number
    714 
    715 *u*::
    716     select the argument
    717 
    718 *c*::
    719     select user defined object, will prompt for open and close text
    720 
    721 *<a-;>*, *<a-semicolon>*::
    722     run a command with additional expansions describing the selection
    723     context (See <<expansions#,`:doc expansions`>>)
    724 
    725 If a punctuation character is entered, it will act as the delimiter.
    726 For instance, if the cursor is on the `o` of `/home/bar`, typing
    727 `<a-a>/` will select `/home/`.
    728 
    729 == Prompt commands
    730 
    731 When pressing `:` in normal mode, Kakoune will open a prompt to enter
    732 a command.  The executed command line is stored in the *:* register
    733 (See <<registers#,`:doc registers`>>).
    734 
    735 During editing, a transient *clipboard* is available, its content is
    736 empty at the start of prompt edition, and is not preserved afterwards.
    737 
    738 The following keys are recognized by this mode to help with editing
    739 (See <<commands#,`:doc commands`>>).
    740 
    741 *<ret>*::
    742     validate prompt
    743 
    744 *<esc>*::
    745     abandon without validating prompt
    746 
    747 *<left>*, *<c-b>*::
    748     move cursor to previous character
    749 
    750 *<right>*, *<c-f>*::
    751     move cursor to next character
    752 
    753 *<home>*, *<c-a>*::
    754     move cursor to first character
    755 
    756 *<end>*, *<c-e>*::
    757     move cursor past the last character
    758 
    759 *<backspace>*, *<c-h>*::
    760     erase character before cursor
    761 
    762 *<del>*, *<c-d>*::
    763     erase character under cursor
    764 
    765 *<a-f>*::
    766     advance to next word begin
    767 
    768 *<a-F>*::
    769     advance to next WORD begin
    770 
    771 *<a-b>*::
    772     go back to previous word begin
    773 
    774 *<a-B>*::
    775     go back to previous WORD begin
    776 
    777 *<a-e>*::
    778     advance to next word end
    779 
    780 *<a-E>*::
    781     advance to next WORD end
    782 
    783 *<c-w>*::
    784     erase to previous word begin, save erased content to *clipboard*
    785 
    786 *<c-W>*::
    787     erase to previous WORD begin, save erased content to *clipboard*
    788 
    789 *<a-d>*::
    790     erase to next word begin, save erased content to *clipboard*
    791 
    792 *<a-D>*::
    793     erase to next WORD begin, save erased content to *clipboard*
    794 
    795 *<c-k>*::
    796     erase to end of line, save erased content to *clipboard*
    797 
    798 *<c-u>*::
    799     erase to begin of line, save erased content to *clipboard*
    800 
    801 *<c-y>*::
    802     insert *clipboard* content before cursor
    803 
    804 *<up>*, *<c-p>*::
    805     select previous entry in history
    806 
    807 *<down>*, *<c-n>*::
    808     select next entry in history
    809 
    810 *<tab>*::
    811     select next completion candidate
    812 
    813 *<s-tab>*::
    814     select previous completion candidate
    815 
    816 *<c-r>*::
    817     insert the content of the register given by next key, if next key has
    818     the Alt modifier, it will insert all values in the register joined with
    819     spaces, else it will insert the main one. if it has the Control modifier,
    820     it will quote the inserted value(s).
    821 
    822 *<c-v>*::
    823     insert next keystroke without interpreting it
    824 
    825 *<c-x>*::
    826     explicit completion query, followed by:
    827 
    828     *f*:::
    829         explicit file completion
    830 
    831     *w*:::
    832         explicit word completion (from current buffer)
    833 
    834 *<c-o>*::
    835     toggle automatic completion
    836 
    837 *<a-!>*::
    838     expand the typed expansions in currently entered text
    839     (See <<expansions#,`:doc expansions`>>)
    840 
    841 *<a-;>*, *<a-semicolon>*::
    842     escape to normal mode for a single command
    843 
    844 == User commands
    845 
    846 *<space>*::
    847     enter default `user mode` to access custom commands
    848     (See <<modes#user-mode,`:doc modes user-mode`>>)
    849 
    850 == Cancelling operations
    851 
    852 These keys are used to cancel long-running operations, either inside
    853 Kakoune or outside it. Because they are intended as a safety mechanism
    854 when something goes wrong, these keys are handled very early on in
    855 Kakoune's input processing, and therefore cannot be remapped in any mode.
    856 
    857 *<c-c>*::
    858     Stop any external processes. If you ever see Kakoune display a message
    859     like "waiting for shell command to finish", this key will stop
    860     that command so you can regain control of Kakoune.
    861     Technically, this key causes Kakoune to send the SIGINT signal
    862     to its entire process group.
    863 
    864 *<c-g>*::
    865     Cancel a long-running Kakoune operation, such as a regex search on a
    866     very large file. This also clears Kakoune's input buffer, so any
    867     commands that were waiting for the long-running operation to complete
    868     will also be cancelled.