@node Registers, Display, Rectangles, Top
@chapter Registers
@cindex registers

  XEmacs @dfn{registers} are places in which you can save text or
positions for later use.  Once you save text or a rectangle in a
register, you can copy it into the buffer once or many times; a position
saved in a register is used by moving point to that position.
Rectangles can also be copied into and out of registers
(@pxref{Rectangles}).

@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

@findex view-register
  @kbd{M-x view-register} reads a register name as an argument and then
displays the contents of the specified register.

@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.
* Numbers: RegNumbers.        Numbers in registers.
* Bookmarks::                 Bookmarks are like registers, but persistent.
@end menu

@node RegPos, RegText, Registers, Registers
@section Saving Positions in Registers

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

@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 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 location.  You can jump to the same position using the
same register as often as you want.

  If you use @kbd{C-x r j} to go to a saved position, but the buffer it
was saved from has been killed, @kbd{C-x r j} tries to create the buffer
again by visiting the same file.  Of course, this works only for buffers
that were visiting files.

@node RegText, RegRect, RegPos, Registers
@section Saving Text in Registers

  When you want to insert a copy of the same piece of text many times, it
can be impractical to use the kill ring, since each subsequent kill moves
the piece of text further down on the ring.  It becomes hard to keep
track of the argument needed to retrieve the same text with @kbd{C-y}.  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 g @var{r}
@itemx C-x r i @var{r}
Insert text contents of register @var{r} (@code{insert-register}).
@end table

@kindex C-x r s
@kindex C-x r g
@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 the text from register @var{r} in the buffer.
By default it leaves point before the text and places the mark after
it. With a numeric argument (@kbd{C-u}), it puts point after the text
and the mark before it.

@node RegRect, RegConfig, RegText, Registers
@section Saving Rectangles in Registers
@cindex rectangle

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

@table @kbd
@findex copy-rectangle-to-register
@kindex C-x r r
@item C-x r r @var{r}
Copy the region-rectangle into register @var{r}
(@code{copy-rectangle-to-register}).  With a numeric argument, delete it
as well.
@item C-x r g @var{r}
@itemx 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 linear text if the register
  contains
that, or inserts a rectangle if the register contains one.

  See also the command @code{sort-columns}, which you can think of
as sorting a rectangle.  @xref{Sorting}.

@node RegConfig, RegNumbers, RegRect, Registers
@section Saving Window Configurations in Registers

@findex window-configuration-to-register
@findex frame-configuration-to-register
@kindex C-x r w
@c @kindex C-x r f
  You can save the window configuration of the selected frame in a
register, or even the configuration of all windows in 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}).
@c @item C-x r f @var{r}
@item M-x frame-configuration-to-register @key{RET} @var{r}
Save the state of all frames, including all their windows, 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.  When you
restore a frame configuration, any existing frames not included in the
configuration become invisible.  If you wish to delete these frames
instead, use @kbd{C-u C-x r j @var{r}}.

@node RegNumbers, RegFiles, RegConfig, Registers
@section Keeping Numbers in Registers

  There are commands to store a number in a register, to insert
the number in the buffer in decimal, and to increment it.  These commands
can be useful in keyboard macros (@pxref{Keyboard Macros}).

@table @kbd
@item C-u @var{number} C-x r n @var{reg}
@kindex C-x r n
@findex number-to-register
Store @var{number} into register @var{reg} (@code{number-to-register}).
@item C-u @var{number} C-x r + @var{reg}
@kindex C-x r +
@findex increment-register
Increment the number in register @var{reg} by @var{number}
(@code{increment-register}).
@item C-x r g @var{reg}
Insert the number from register @var{reg} into the buffer.
@end table

  @kbd{C-x r g} is the same command used to insert any other
sort of register contents into the buffer.

@node RegFiles, Bookmarks, RegNumbers, Registers
@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

@need 3000
@noindent
For example,

@smallexample
(set-register ?z '(file . "/usr/src/xemacs/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.)

@node Bookmarks,  , RegFiles, Registers
@section Bookmarks
@cindex bookmarks

  @dfn{Bookmarks} are somewhat like registers in that they record
positions you can jump to.  Unlike registers, they have long names, and
they persist automatically from one Emacs session to the next.  The
prototypical use of bookmarks is to record ``where you were reading'' in
various files.

  Note: bookmark.el is distributed in edit-utils package.  You need to
install that to use bookmark facility (@pxref{Packages}).

@table @kbd
@item C-x r m @key{RET}
Set the bookmark for the visited file, at point.

@item C-x r m @var{bookmark} @key{RET}
@findex bookmark-set
Set the bookmark named @var{bookmark} at point (@code{bookmark-set}).

@item C-x r b @var{bookmark} @key{RET}
@findex bookmark-jump
Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}).

@item C-x r l
@findex list-bookmarks
List all bookmarks (@code{list-bookmarks}).

@item M-x bookmark-save
@findex bookmark-save
Save all the current bookmark values in the default bookmark file.
@end table

@kindex C-x r m
@findex bookmark-set
@kindex C-x r b
@findex bookmark-jump
  The prototypical use for bookmarks is to record one current position
in each of several files.  So the command @kbd{C-x r m}, which sets a
bookmark, uses the visited file name as the default for the bookmark
name.  If you name each bookmark after the file it points to, then you
can conveniently revisit any of those files with @kbd{C-x r b}, and move
to the position of the bookmark at the same time.

@kindex C-x r l
  To display a list of all your bookmarks in a separate buffer, type
@kbd{C-x r l} (@code{list-bookmarks}).  If you switch to that buffer,
you can use it to edit your bookmark definitions or annotate the
bookmarks.  Type @kbd{C-h m} in that buffer for more information about
its special editing commands.

  When you kill XEmacs, XEmacs offers to save your bookmark values in
your default bookmark file, @file{~/.emacs.bmk}, if you have changed any
bookmark values.  You can also save the bookmarks at any time with the
@kbd{M-x bookmark-save} command.  The bookmark commands load your
default bookmark file automatically.  This saving and loading is how
bookmarks persist from one XEmacs session to the next.

@vindex bookmark-save-flag
  If you set the variable @code{bookmark-save-flag} to 1, then each
command that sets a bookmark will also save your bookmarks; this way,
you don't lose any bookmark values even if XEmacs crashes.  (The value,
if a number, says how many bookmark modifications should go by between
saving.)

@vindex bookmark-search-size
  Bookmark position values are saved with surrounding context, so that
@code{bookmark-jump} can find the proper position even if the file is
modified slightly.  The variable @code{bookmark-search-size} says how
many characters of context to record, on each side of the bookmark's
position.

  Here are some additional commands for working with bookmarks:

@table @kbd
@item M-x bookmark-load @key{RET} @var{filename} @key{RET}
@findex bookmark-load
Load a file named @var{filename} that contains a list of bookmark
values.  You can use this command, as well as @code{bookmark-write}, to
work with other files of bookmark values in addition to your default
bookmark file.

@item M-x bookmark-write @key{RET} @var{filename} @key{RET}
@findex bookmark-write
Save all the current bookmark values in the file @var{filename}.

@item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET}
@findex bookmark-delete
Delete the bookmark named @var{bookmark}.

@item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET}
@findex bookmark-insert-location
Insert in the buffer the name of the file that bookmark @var{bookmark}
points to.

@item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET}
@findex bookmark-insert
Insert in the buffer the @emph{contents} of the file that bookmark
@var{bookmark} points to.
@end table