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

*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