@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Registers, Display, Rectangles, Top
@chapter Registers
@cindex registers

  Emacs @dfn{registers} are places you can save text or positions for
later use.  Text and rectangles saved in registers can be copied into
the buffer once or many times; you can move point to a position saved in
a register.

@findex view-register
  Each register has a name which is a single character.  A register can
store a piece of text, a rectangle, a position, a window configuration
or a file name, but only one thing at any given time.  Whatever you
store in a register remains there until you store something else in that
register.  To see what a register @var{r} contains, use @kbd{M-x
view-register}.

@table @kbd
@item M-x view-register @key{RET} @var{r}
Display a description of what register @var{r} contains.
@end table

@menu
* Position: RegPos.           Saving positions in registers.
* Text: RegText.              Saving text in registers.
* Rectangle: RegRect.         Saving rectangles in registers.
* Configurations: RegConfig.  Saving window configurations in registers.
* Files: RegFiles.            File names in registers.
@end menu

@node RegPos
@section Saving Positions in Registers

  Saving a position records a spot in a buffer so that you can move back
there later.  Moving to a saved position reselects that buffer and moves
point to that spot.

@table @kbd
@item C-x r @key{SPC} @var{r}
Save position of point in register @var{r} (@code{point-to-register}).
@item C-x r j @var{r}
Jump to the position saved in register @var{r} (@code{jump-to-register}).
@end table

@kindex C-x r @key{SPC}
@findex point-to-register
  To save the current position of point in a register, choose a name
@var{r} and type @kbd{C-x r @key{SPC} @var{r}}.  The register @var{r}
retains the position thus saved until you store something else in that
register.

@kindex C-x r j
@findex jump-to-register
  The command @kbd{C-x r j @var{r}} moves point to the position recorded
in register @var{r}.  The register is not affected; it continues to
record the same position.  You can jump to the same position using the
same register any number of times.

@node RegText
@section Saving Text in Registers

  When you want to insert a copy of the same piece of text several
times, it may be inconvenient to yank it from the kill ring, since each
subsequent kill moves that entry further down the ring.  An alternative
is to store the text in a register with @kbd{C-x r s}
(@code{copy-to-register}) and then retrieve it with @kbd{C-x r i}
(@code{insert-register}).

@table @kbd
@item C-x r s @var{r}
Copy region into register @var{r} (@code{copy-to-register}).
@item C-x r i @var{r}
Insert text from register @var{r} (@code{insert-register}).
@end table

@kindex C-x r s
@kindex C-x r i
@findex copy-to-register
@findex insert-register
  @kbd{C-x r s @var{r}} stores a copy of the text of the region into the
register named @var{r}.  Given a numeric argument, @kbd{C-x r s @var{r}}
deletes the text from the buffer as well.

  @kbd{C-x r i @var{r}} inserts in the buffer the text from register
@var{r}.  Normally it leaves point before the text and places the mark
after, but with a numeric argument (@kbd{C-u}) it puts point after the
text and the mark before.

@node RegRect
@section Saving Rectangles in Registers

  A register can contain a rectangle instead of linear text.  The
rectangle is represented as a list of strings.  @xref{Rectangles}, for
basic information on how to specify a rectangle in the buffer.

@table @kbd
@item C-x r r @var{r}
Copy the region-rectangle into register @var{r}
(@code{copy-region-to-rectangle}).  With numeric argument, delete it as
well.
@item C-x r i @var{r}
Insert the rectangle stored in register @var{r} (if it contains a
rectangle) (@code{insert-register}).
@end table

  The @kbd{C-x r i @var{r}} command inserts a text string if the
register contains one, and inserts a rectangle if the register contains
one.

@node RegConfig
@section Saving Window Configurations in Registers

@findex window-configuration-to-register
@findex frame-configuration-to-register
@kindex C-x r w
@kindex C-x r f
  You can save the window configuration of the selected frame in a
register, or even the configuration of all frames, and restore the
configuration later.

@table @kbd
@item C-x r w @var{r}
Save the state of the selected frame's windows in register @var{r}
(@code{window-configuration-to-register}).
@item C-x r f @var{r}
Save the state of all windows in all frames in register @var{r}
(@code{frame-configuration-to-register}).
@end table

  Use @kbd{C-x r j @var{r}} to restore a window or frame configuration.
This is the same command used to restore a cursor position.

@node RegFiles
@section Keeping File Names in Registers

  If you visit certain file names frequently, you can visit them more
conveniently if you put their names in registers.  Here's the Lisp code
used to put a file name in a register:

@smallexample
(set-register ?@var{r} '(file . @var{name}))
@end smallexample

@noindent
For example,

@smallexample
(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))
@end smallexample

@noindent
puts the file name shown in register @samp{z}.

  To visit the file whose name is in register @var{r}, type @kbd{C-x r j
@var{r}}.  (This is the same command used to jump to a position or
restore a frame configuration.)