home/doc/pages/keys.asciidoc
Johannes Altmanninger c2ab5d4694 Allow to undo and redo selection changes
From the issue:

> It often happens to me that I carefully craft a selection with multiple
> cursors, ready to make changes elegantly, only to completely mess it
> up by pressing a wrong key (by merging the cursors for example). Being
> able to undo the last selection change (even if only until the previous
> buffer change) would make this much less painful.

Fix this by recording selection changes and allowing simple linear
undo/redo of selection changes.

The preliminary key bindings are <c-h> and <c-k>.
Here are some other vacant normal mode keys I considered

	X Y
	<backspace> <minus>
	# ^ =
	<plus> '

unfortunately none of them is super convenient to type.  Maybe we
can kick out some other normal mode command?

---

This feature has some overlap with the jump list (<c-o>/<c-i>) and
with undo (u) but each of the three features have their moment.

Currently there's no special integration with either peer feature;
the three histories are completely independent.  In future we might
want to synchronize them so we can implement Sublime Text's "Soft
undo" feature.

Note that it is possible to restore selections that predate a buffer
modification. Depending on the buffer modification, the selections
might look different of course. (When trying to apply an old buffer's
selection to the new buffer, Kakoune computes a diff of the buffers
and updates the selection accordingly. This works quite well for
many practical examples.)

This makes us record the full history of all selections for each
client. This seems wasteful, we could set a limit. I don't expect
excessive memory usage in practice (we also keep the full history of
buffer changes) but I could be wrong.

Closes #898
2022-09-02 02:59:47 +02:00

834 lines
19 KiB
Plaintext

= 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, *a* for Alt, or *s* for Shift, followed by a *-* and the key (either
its name or ascii character), for example *<c-x>*, *<a-space>*, *<c-a-w>*.
In order to bind some keys to arbitrary ones, refer to <<mapping#,`:doc mapping`>>
== 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-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-;>*, *<a-semicolon>*::
escape to normal mode for a single command
== Insert mode completion
The `completers` option controls automatic completion, which kicks in when
the value specified in the `idle_timeout` option is reached.
*<c-o>*::
toggle automatic completion
*<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 (current buffer)
*L*:::
explicit line completion (all buffers)
== 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 the end of each selection.
== 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) (see
<<hooks#,`:doc hooks`>>).
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 those in the `extra_word_chars`
option (see <<options#builtin-options,`:doc options builtin-options`>>).
'WORD' is a sequence of non whitespace characters. Generally, a movement on its own
will move each selection to cover the text moved over, while holding down
the Shift modifier and moving will extend each selection instead.
*h*::
select the character on the left of the end of each selection
`<left>` maps to this by default.
(See <<mapping#default-mappings,`:doc mapping default-mappings`>>)
*j*::
select the character below the end of each selection
`<down>` maps to this by default.
(See <<mapping#default-mappings,`:doc mapping default-mappings`>>)
*k*::
select the character above the end of each selection
`<up>` maps to this by default.
(See <<mapping#default-mappings,`:doc mapping default-mappings`>>)
*l*::
select the character on the right of the end of each selection
`<right>` maps to this by default.
(See <<mapping#default-mappings,`:doc mapping default-mappings`>>)
*w*::
select the word and following whitespaces on the right of the end of each selection
*b*::
select preceding whitespaces and the word on the left of the end of each selection
*e*::
select preceding whitespaces and the word on the right of the end of each selection
*<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
*<a-.>*::
repeat last object or *f*/*t* selection command
*m*::
select to the next sequence enclosed by matching characters, see the
`matching_pairs` option in <<options#,`:doc options`>>
*M*::
extend the current selection to the next sequence enclosed by matching
character, see the `matching_pairs` option in <<options#,`:doc options`>>
*<a-m>*::
select to the previous sequence enclosed by matching characters, see the
`matching_pairs` option in <<options#,`:doc options`>>
*<a-M>*::
extend the current selection to the previous sequence enclosed by matching
characters, see the `matching_pairs` option in <<options#,`:doc options`>>
*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)
*%*, *<percent>*::
select whole buffer
*<a-h>*::
select to line begin
`<home>` maps to this by default.
(See <<mapping#default-mappings,`:doc mapping default-mappings`>>)
*<a-l>*::
select to line end
`<end>` maps to this by default.
(See <<mapping#default-mappings,`:doc mapping default-mappings`>>)
*<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
*;*, *<semicolon>*::
reduce selections to their cursor
*<a-;>*, *<a-semicolon>*::
flip the direction of each selection
*<a-:>*::
ensure selections are in forward direction (cursor after anchor)
== Changes
Yanking (copying) and pasting use the *"* register by default (See <<registers#,`:doc registers`>>)
*i*::
enter insert mode before selections
*a*::
enter insert mode after selections
*d*::
yank and delete selections
*c*::
yank and delete selections and enter insert mode
*.*::
repeat last insert mode change (*i*, *a*, or *c*, including the
inserted text)
*<a-d>*::
delete selections (not yanking)
*<a-c>*::
delete selections and enter insert mode (not yanking)
*I*::
enter insert mode at the beginning of the lines containing
the start of each selection
*A*::
enter insert mode at the end of the lines containing
the end of each selection
*o*::
enter insert mode in a new line (or in a given `count` of new lines)
below the end of each selection
*O*::
enter insert mode in a new line (or in a given `count` of new lines)
above the beginning of each selection
*<a-o>*::
add an empty line below cursor
*<a-O>*::
add an empty line above cursor
*y*::
yank selections
*p*::
paste after the end of each selection
*P*::
paste before the beginning of each selection
*<a-p>*::
paste all after the end of each selection, and select each pasted string
*<a-P>*::
paste all before the start of each selection, and select each pasted string
*R*::
replace selections with yanked text
*<a-R>*::
replace selections 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-_>*::
merge contiguous selections together (works across lines as well)
*<+>*, *<plus>*::
duplicate each selection (generating overlapping selections)
*<a-+>*, *<a-plus>*::
merge overlapping selections
*>*, *<gt>*::
indent selected lines
*<a\->>*, *<a-gt>*::
indent selected lines, including empty lines
*<*, *<lt>*::
unindent selected lines
*<a-<>*, *<a-lt>*::
unindent selected lines, do not remove incomplete indent (3 leading
spaces when indent is 4)
*u*::
undo last change
*<a-u>*::
move backward in history
*U*::
redo last change
*<a-U>*::
move forward in history
*<c-h>*::
undo last selection change
*<c-k>*::
redo last selection change
*&*::
align selections, align the cursor of each selection by inserting spaces
before the first character of each 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 each selection, uses the buffer tabstop
option or the `count` parameter for tabstop
*<a-@>*::
convert spaces to tabs in each selection, uses the buffer tabstop
option or the `count` parameter for tabstop
*_*::
unselect whitespace surrounding each selection, drop those that only
contain whitespace
*<a-)>*::
rotate selections content, if specified, the `count` groups selections,
so the following command
----------
3<a-)>
----------
rotates (1, 2, 3) and (3, 4, 6) independently
*<a-(>*::
rotate selections content backward
== Changes through external programs
Shell expansions are available, (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)
The default command comes from the *|* register (See <<registers#,`:doc registers`>>)
*|*::
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 and select command output before each selection.
*<a-!>*::
append and select command output after each selection.
== Searching
Searches use the */* register by default (See <<registers#,`:doc registers`>>)
*/*::
select next match after each selection
*<a-/>*::
select previous match before each selection
*?*::
extend to next match after each selection
*<a-?>*::
extend to previous match before each selection
*n*::
select next match after the main selection
*N*::
add a new selection with next match after the main selection
*<a-n>*::
select previous match before the main selection
*<a-N>*::
add a new selection with previous match before the main selection
***::
set the search pattern to the main selection (automatically
detects word boundaries)
*<a-***>*::
set the search pattern to the main selection (verbatim, no smart
detection)
== Goto commands
*g*, *G*::
When a `count` is specified, *G* only extends the 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
Current selections position can be saved in a register and restored later on.
Marks use the *^* register by default (See <<registers#,`:doc registers`>>)
*Z*::
save selections to the register
*z*::
restore selections from the register
*<a-z>*, *<a-Z>*::
*<a-z>* combines selections from the register with the current ones, whereas
*<a-Z>* combines current selections with the ones in the register; a menu
is then displayed which waits for one of the following additional keys:
*a*:::
append selections
*u*:::
keep a union of selections
*i*:::
keep an intersection of 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 (See <<registers#,`:doc registers`>>)
*Q*::
start or end macro recording
*q*::
play a recorded macro
*<esc>*::
end macro recording
== Jump list
Some commands, like the goto commands, buffer switch or search commands,
push the previous selections to the client's jump list. It is possible
to skim through the jump list using:
*<c-i>*::
jump forward
*<c-o>*::
jump backward
*<c-s>*::
create a jump step, but also save the current selection to have it be
restored when the step is subsequently cycled through
== Multiple selections
*s*, *S*, *<a-k>* and *<a-K>* use the */* register by default (See <<registers#,`:doc registers`>>)
*s*::
create a selection for each match of the given regex
(selects the count capture if it is given)
*S*::
split selections with the given regex
(selects the count capture if it is given)
*<a-s>*::
split selections on line boundaries
*<a-S>*::
select first and last characters of each selection
*C*::
copy the main selection to the next line
*<a-C>*::
copy the main selection to the previous line
*,*::
clear selections to only keep the main one
*<a-,>*::
clear the main selection
*<a-k>*::
keep 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. Shell expansions are available,
(See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)
*)*::
rotate main selection (the main selection becomes the next one)
*(*::
rotate main selection backward (the main selection becomes the previous one)
== Object Selection
For nestable objects, a `count` can be used in order to specify which surrounding
level to select. Object selections are repeatable using *<a-.>*.
=== Whole object
A 'whole object' is an object *including* its surrounding characters.
For example, for a quoted string this will select the quotes, and
for a word this will select trailing spaces.
*<a-a>*::
select the whole object
*[*::
select to the whole object start
*]*::
select to the whole object end
*{*::
extend selections to the whole object start
*}*::
extend selections to the whole object end
=== Inner object
An 'inner object' is an object *excluding* its surrounding characters.
For example, for a quoted string this will *not* select the quotes, and
for a word this will *not* select trailing spaces.
*<a-i>*::
select the inner object
*<a-[>*::
select to the inner object start
*<a-]>*::
select to the inner object end
*<a-{>*::
extend selections to the inner object start
*<a-}>*::
extend selections to the inner object end
=== Objects types
After the keys described above, a second key needs to be entered
in order to specify the wanted object:
*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
*<a-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
*<a-;>*, *<a-semicolon>*::
run a command with additional expansions describing the selection
context (See <<expansions#,`:doc expansions`>>)
If a punctuation character is entered, it will act as the delimiter.
For instance, if the cursor is on the `o` of `/home/bar`, typing
`<a-a>/` will select `/home/`.
== Prompt commands
When pressing `:` in normal mode, Kakoune will open a prompt to enter
a command. The executed command line is stored in the *:* register
(See <<registers#,`:doc registers`>>).
During editing, a transient *clipboard* is available, its content is
empty at the start of prompt edition, and is not preserved afterwards.
The following keys are recognized by this mode to help with editing
(See <<commands#,`:doc commands`>>).
*<ret>*::
validate prompt
*<esc>*::
abandon without validating prompt
*<left>*, *<c-b>*::
move cursor to previous character
*<right>*, *<c-f>*::
move cursor to next character
*<home>*, *<c-a>*::
move cursor to first character
*<end>*, *<c-e>*::
move cursor past the last character
*<backspace>*, *<c-h>*::
erase character before cursor
*<del>*, *<c-d>*::
erase character under cursor
*<a-f>*::
advance to next word begin
*<a-F>*::
advance to next WORD begin
*<a-b>*::
go back to previous word begin
*<a-B>*::
go back to previous WORD begin
*<a-e>*::
advance to next word end
*<a-E>*::
advance to next WORD end
*<c-w>*::
erase to previous word begin, save erased content to *clipboard*
*<c-W>*::
erase to previous WORD begin, save erased content to *clipboard*
*<a-d>*::
erase to next word begin, save erased content to *clipboard*
*<a-D>*::
erase to next WORD begin, save erased content to *clipboard*
*<c-k>*::
erase to end of line, save erased content to *clipboard*
*<c-u>*::
erase to begin of line, save erased content to *clipboard*
*<c-y>*::
insert *clipboard* content before cursor
*<up>*, *<c-p>*::
select previous entry in history
*<down>*, *<c-n>*::
select next entry in history
*<tab>*::
select next completion candidate
*<s-tab>*::
select previous completion candidate
*<c-r>*::
insert then content of the register given by next key, if next key
has the Alt modifier, it will insert all values in the register
joined with spaces, else it will insert the main one
*<c-v>*::
insert next keystroke without interpreting it
*<c-x>*::
explicit completion query, followed by:
*f*:::
explicit file completion
*w*:::
explicit word completion (from current buffer)
*<c-o>*::
toggle automatic completion
*<a-!>*::
expand the typed expansions in currently entered text
(See <<expansions#,`:doc expansions`>>)
*<a-;>*, *<a-semicolon>*::
escape to normal mode for a single command
== User commands
*<space>*::
enter default `user mode` to access custom commands
(See <<modes#user-mode,`:doc modes user-mode`>>)