home/doc/pages/keys.asciidoc

= Keys

== Key Syntax

Usual keys are written using their ascii character, including capital
keys. Non printable keys use an alternate name, written between *<*
and *>*, such as *<esc>* or *<del>*. Modified keys are written between
*<* and *>* as well, with the modifier specified as either *c* for
Control, or *a* for Alt, followed by a *-* and the key (either its
name or ascii character), for example *<c-x>*, *<a-space>*.

In order to bind some keys to arbitrary ones, refer to the 'mapping'
documentation page.

== Insert mode

*<esc>*::
    leave insert mode

*<backspace>*::
    delete characters before cursors

*<del>*::
    delete characters under cursors

*<left>*, *<right>*, *<up>*, *<down>*::
    move the cursors in given direction

*<home>*::
    move cursors to line begin

*<end>*::
    move cursors to end of line

*<c-n>*::
    select next completion candidate

*<c-p>*::
    select previous completion candidate

*<c-x>*::
    explicit insert completion query, followed by:

    *f*:::
        explicit file completion

    *w*:::
        explicit word completion (current buffer)

    *W*:::
        explicit word completion (all buffers)

    *l*:::
        explicit line completion

*<c-o>*::
    disable automatic completion for this insert session

*<c-r>*::
    insert contents of the register given by next key

*<c-v>*::
    insert next keystroke directly into the buffer, without interpreting it

*<c-u>*::
    commit changes up to now as a single undo group

*<a-;>*::
    escape to normal mode for a single command

== Using Counts

In normal mode, commands can be prefixed with a numeric count, which can control
the command behaviour.

For example, *3W* selects 3 consecutive words and *3w* select the third word on
the right of selection end.

== Disabling Hooks

Any normal mode command can be prefixed with *\* which will disable hook execution
for the duration for the command (including the duration of modes the command could
move to, so *\i* will disable hooks for the whole insert session).

As autoindentation is implemented in terms of hooks, this can be used to disable
it when pasting text.

== Movement

'word' is a sequence of alphanumeric characters or underscore, and 'WORD'
is a sequence of non whitespace characters

*h*::
    select the character on the left of selection end

*j*::
    select the character below the selection end

*k*::
    select the character above the selection end

*l*::
    select the character on the right of selection end

*w*::
    select the word and following whitespaces on the right of selection end

*b*::
    select preceding whitespaces and the word on the left of selection end

*e*::
    select preceding whitespaces and the word on the right of selection end

*<a-[wbe]>*::
    same as [wbe] but select WORD instead of word

*f*::
    select to the next occurrence of given character

*t*::
    select until the next occurrence of given character

*<a-[ft]>*::
    same as [ft] but in the other direction

*m*::
    select to matching character, see the `matching_pairs` options
    in <<doc/pages/options#,`:doc options`>>

*M*::
    extend selection to matching character

*x*::
    select line on which selection end lies (or next line when end lies
    on an end-of-line)

*X*:: similar to *x*, except the current selection is extended

*<a-x>*::
    expand selections to contain full lines (including end-of-lines)

*<a-X>*::
    trim selections to only contain full lines (not including last
    end-of-line)

*%*::
    select whole buffer

*<a-h>*::
    select to line begin

*<a-l>*::
    select to line end

*/*::
    search (select next match)

*<a-/>*::
    search (select previous match)

*?*::
    search (extend to next match)

*<a-?>*::
    search (extend to previous match)

*n*::
    select next match

*N*::
    add a new selection with next match

*<a-n>*::
    select previous match

*<a-N>*::
    add a new selection with previous match

*pageup, <c-b>*::
    scroll one page up

*pagedown, <c-f>*::
    scroll one page down

*<c-u>*::
    scroll half a page up

*<c-d>*::
    scroll half a page down

*'*::
    rotate selections (the main selection becomes the next one)

*<a-'>*::
    rotate selections backwards

*;*::
    reduce selections to their cursor

*<a-;>*::
    flip the selections direction

*<a-:>*::
    ensure selections are in forward direction (cursor after anchor)

*<a-.>*::
    repeat last object or *f*/*t* selection command

== Changes

*i*::
    enter insert mode before current selection

*a*::
    enter insert mode after current selection

*d*::
    yank and delete current selection

*c*::
    yank and delete current selection and enter insert mode

*.*::
    repeat last insert mode change (*i*, *a*, or *c*, including the
    inserted text)

*<a-d>*::
    delete current selection (not yanking)

*<a-c>*::
    delete current selection and enter insert mode (not yanking)

*I*::
    enter insert mode at current selection begin line start

*A*::
    enter insert mode at current selection end line end

*o*::
    enter insert mode in a new line (or in a given count of new lines) below
    current selection end

*O*::
    enter insert mode in a new line (or in a given count of new lines) above
    current selection begin

*<a-o>*::
    add an empty line below cursor

*<a-O>*::
    add an empty line above cursor

*y*::
    yank selections

*p*::
    paste after current selection end

*P*::
    paste before current selection begin

*<a-p>*::
    paste all after current selection end, and select each pasted string

*<a-P>*::
    paste all before current selection begin, and select each pasted string

*R*::
    replace current selection with yanked text

*<a-R>*::
    replace current selection with every yanked text

*r*::
    replace each character with the next entered one

*<a-j>*::
    join selected lines

*<a-J>*::
    join selected lines and select spaces inserted in place of line breaks

*<a-m>*::
    merge contiguous selections together (works across lines as well)

*>*::
    indent selected lines

*<a\->>*::
    indent selected lines, including empty lines

*<*::
    deindent selected lines

*<a-<>*::
    deindent selected lines, do not remove incomplete indent (3 leading
    spaces when indent is 4)

*|*::
    pipe each selection through the given external filter program and
    replace the selection with its output

*<a-|>*::
    pipe each selection through the given external filter program and
    ignore its output

*!*::
    insert command output before selection

*<a-!>*::
    append command output after selection

*u*::
    undo last change

*<a-u>*::
    move backward in history

*U*::
    redo last change

*<a-U>*::
    move forward in history

*&*::
    align selection, align the cursor of selections by inserting spaces
    before the first character of the selection

*<a-&>*::
    copy indent, copy the indentation of the main selection (or the
    count one if a count is given) to all other ones

*`*::
    to lower case

*~*::
    to upper case

*<a-`>*::
    swap case

*@*::
    convert tabs to spaces in current selections, uses the buffer tabstop
    option or the count parameter for tabstop

*<a-@>*::
    convert spaces to tabs in current selections, uses the buffer tabstop
    option or the count parameter for tabstop

*<a-">*::
    rotate selections content, if specified, the count groups selections,
    so the following command

----------
    3<a-">
----------

    rotate (1, 2, 3) and (3, 4, 6) independently

== Goto Commands

*g*, *G*::
    When a count is specified, *G* only extends the current selection to the given line,
    *g* sends the anchor to the given line and a menu is then displayed which waits
    for one of the following additional keys:

    *h*:::
        go to line begin

    *l*:::
        go to line end

    *i*:::
        go to non blank line start

    *g*, *k*:::
        go to the first line

    *j*:::
        go to the last line

    *e*:::
        go to last char of last line

    *t*:::
        go to the first displayed line

    *c*:::
        go to the middle displayed line

    *b*:::
        go to the last displayed line

    *a*:::
        go to the previous (alternate) buffer

    *f*:::
        open the file whose name is selected

    *.*:::
        go to last buffer modification position

== View commands

*v*, *V*::
    *V* enters lock view mode (which will be left when the <esc> is hit),
    and *v* modifies the current view; a menu is then displayed which waits
    for one of the following additional keys:

    *v*, *c*:::
        center the main selection in the window (vertically)

    *m*:::
        center the main selection in the window (horizontally)

    *t*:::
        scroll to put the main selection on the top line of the window

    *b*:::
        scroll to put the main selection on the bottom line of the window

    *h*:::
        scroll the window count columns left

    *j*:::
        scroll the window count line downward

    *k*:::
        scroll the window count line upward

    *l*:::
        scroll the window count columns right


== Marks

Marks use the *^* register by default.

*Z*::
    save the current selections to the register

*z*::
    restore the selections from the register

*<a-z>*, *<a-Z>*::
    *<a-z>* combines the selections from the register with the current ones, whereas
    *<a-Z>* combines the current selections with the register; a menu is then
    displayed which waits for one of the following additional keys:

    *a*:::
        append the selections

    *u*:::
        keep a union of the selections

    *i*:::
        keep an intersection of the selections

    *<*:::
        select the selection with the leftmost cursor for each pair

    *>*:::
        select the selection with the rightmost cursor for each pair

    *+*:::
        select the longest selection

    *-*:::
        select the shortest selection

== Macros

Macros use the *@* register by default

*<esc>*::
    end macro recording

*Q*::
    start or end macro recording

*q*::
    play a recorded macro

== Searching

Searches use the */* register by default

***::
    set the search pattern to the current selection (automatically
    detects word boundaries)

*<a-***>*::
    set the search pattern to the current selection (verbatim, no smart
    detection)

== Jump list


*<c-i>*::
    Jump forward

*<c-o>*::
    Jump backward

*<c-s>*::
    save current selections

== Multiple selections

*s*::
    create a selection

*<a-s>*::
    split the current selections on line boundaries

*S*::
    split the current selection

*C*::
    copy the current selection to the next line

*<a-C>*::
    copy the current selection to the previous line

*<space>*::
    clear a multiple selection

*<a-space>*::
    clear the current selection

*<a-k>*::
    keep the selections that match the given regex

*<a-K>*::
    clear selections that match the given regex

*$*::
    pipe each selection to the given shell command and keep the ones
    for which the shell returned 0

== Object Selection

*<a-a>*::
    selects the whole object

*<a-i>*::
    selects the inner object, that is the object excluding its surrounder

*[*::
    selects to object start

*]*::
    selects to object end

*{*::
    extends selections to object start

*}*::
    extends selections to object end

After these keys, you need to enter a second key in order to specify which
object you want

*b*, *(*, *)*::
    select the enclosing parenthesis

*B*, *{*, *}*::
    select the enclosing {} block

*r*, *[*, *]*::
    select the enclosing [] block

*a*, *<*, *>*::
    select the enclosing <> block

*"*, *Q*::
    select the enclosing double quoted string

*'*, *q*::
    select the enclosing single quoted string

*`*, *g*::
    select the enclosing grave quoted string

*w*::
    select the whole word

*W*::
    select the whole WORD

*s*::
    select the sentence

*p*::
    select the paragraph

*␣*::
    select the whitespaces

*i*::
    select the current indentation block

*n*::
    select the number

*u*::
    select the argument

*c*::
    select user defined object, will prompt for open and close text

== Prompt Commands

*<ret>*::
    validate prompt

*<esc>*::
    abandon without

*<left>*, *<a-h>*::
    move cursor to previous character

*<right>*, *<a-l>*::
    move cursor to previous character

*<home>*::
    move cursor to first character

*<end>*::
    move cursor past the last character

*<backspace>*, *<a-x>*::
    erase character before cursor

*<del>*, *<a-d>*::
    erase character under cursor

*<c-w>*::
    avance to next word begin

*<c-a-w>*::
    advance to next WORD begin

*<c-b>*::
    go back to previous word begin

*<c-a-b>*::
    go back to previous WORD begin

*<c-e>*::
    advance to next word end

*<c-a-e>*::
    advance to next word end

*<up>*, *<c-p>*::
    select previous entry in history

*<down>*, *<c-n>*::
    select next entry in history

*<tab>*::
    select next completion candidate

*<backtab>*::
    select previous completion candidate

*<c-r>*::
    insert then content of the register given by next key

*<c-v>*::
    insert next keystroke without interpreting it

*<c-o>*::
    disable auto completion for this prompt