kakoune/doc/pages/registers.asciidoc

= Registers

== Description

Registers are named lists of text -instead of simply text- in order to interact
well with multiselection. They are used for various purposes, like storing
yanked text, the locations of selections in a buffer, or groups captured by a
regular expression.

== Interacting

*<c-r><c>*::
    when in insert mode or in a prompt, insert the value stored in the
    *c* register (single character)

*"<c>*::
    in normal mode, select the *<c>* register (single character)

== Alternate names

Non alphanumeric registers have an alternative name that can be used
in contexts where only alphanumeric identifiers are possible.

== Default registers

All normal-mode commands using a register default to a specific one if not specified:

*"* (dquote)::
    default delete / copy / paste / replace register, used by:
    *c*, *d*, *y*, *p*, *<a-p>*, *<P>*, *<a-P>*, *R* and *<a-R>*
    (see <<keys#changes, `:doc keys changes`>>)

*/* (slash)::
    default search / regex register, used by:
    */*, *<a-/>*, *?*, *<a-?>*, *n*, *<a-n>*, *N*, *<a-N>*, ***, *<a-*>*,
    *s*, *S*, *<a-k>* and *<a-K>*
    (see <<keys#searching, `:doc keys searching`>>)

*@* (arobase)::
    default macro register, used by:
    *q* and *Q*
    (see <<keys#macros, `:doc keys macros`>>)

*^* (caret)::
    default mark register, used by:
    *z*, *<a-z>*, *Z* and *<a-Z>*
    (see <<keys#marks, `:doc keys marks`>>
    and <<registers#marks, `:doc registers marks`>>)

*|* (pipe)::
    default shell command register, used by commands that spawn a subshell:
    *|*, *<a-|>*, *!* and *<a-!>*
    (see <<keys#changes-through-external-programs, `:doc keys changes-through-external-programs`>>)

== Special registers

Some registers are not general purposes, they cannot be written to, but they
contain some special data

*%* (percent)::
    current buffer name

*.* (dot)::
    current selection contents

*#* (hash)::
    selection indices (first selection has 1, second has 2, ...)

*_* (underscore)::
    null register, always empty

*:* (colon)::
    last entered command

== Integer registers

Registers *1* to *9* hold the grouped sub-matches of the regular
expression used to make the last selection. Example: applying the
following regular expression to the date of the day would put the day of
the week in register *1*, the month in register *2*, and the day of the
month in register *3*, but select the entire date:

--------------------
(\w+) (\w+) (\d+) .+
--------------------

== Marks

When a register is used to store a set of selections with the *Z* key (see
<<keys#marks, `:doc keys marks`>>), the selections are stored as a list of
spans, in a format similar to `%val{selections_desc}` (see
<<expansions#value-expansions, `:doc expansions value-expansions`). However,
the very first item of the list is of the form:

------------------------------------------
<buffer name>@<timestamp>@<main sel index>
------------------------------------------

with:

*buffer name*::
    `%val{buffile}` of the buffer selections relate to

*timestamp*::
    `%val{timestamp}` at which the selection apply to

*main sel index*::
    0-based index of the main selection