mirror of git://git.sv.gnu.org/emacs.git
476 lines
18 KiB
Plaintext
476 lines
18 KiB
Plaintext
@c This is part of the Emacs manual.
|
|
@c Copyright (C) 1985--1987, 1993--1995, 1997, 2001--2024 Free Software
|
|
@c Foundation, Inc.
|
|
@c See file emacs.texi for copying conditions.
|
|
@node Registers
|
|
@chapter Registers
|
|
@cindex registers
|
|
|
|
Emacs @dfn{registers} are compartments where you can save text,
|
|
rectangles, positions, and other things for later use. Once you save
|
|
text or a rectangle in a register, you can copy it into the buffer
|
|
once or many times; once you save a position in a register, you can
|
|
jump back to that position once or many times.
|
|
|
|
Each register has a name that consists of a single character, which
|
|
we will denote by @var{r}; @var{r} can be a letter (such as @samp{a})
|
|
or a number (such as @samp{1}); case matters, so register @samp{a} is
|
|
not the same as register @samp{A}. You can also set a register in
|
|
non-alphanumeric characters, for instance @samp{C-d} by using for
|
|
example @key{C-q} @samp{C-d}.
|
|
|
|
@findex view-register
|
|
A register can store a position, a piece of text, a rectangle, a
|
|
number, a window or frame configuration, a buffer name, 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 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
|
|
|
|
|
|
@cindex preview of registers
|
|
@vindex register-use-preview
|
|
All of the commands that prompt for a register will by default
|
|
display a preview window that lists the existing registers (if there
|
|
are any) and their current values, after a short delay. This and
|
|
other aspects of prompting for a register can be customized by setting
|
|
the value of @code{register-use-preview}, which can have the following
|
|
values:
|
|
|
|
@table @code
|
|
@vindex register-preview-delay
|
|
@item traditional
|
|
With this value, which is the default, Emacs behaves like it did in
|
|
all the versions before Emacs 29: it shows a preview of existing registers
|
|
after a delay, and lets you overwrite the values of existing registers
|
|
by typing a single character, the name of the register. The preview
|
|
appears after the delay determined by the customizable variable
|
|
@code{register-preview-delay}, which specifies the delay in seconds;
|
|
setting it to @code{nil} disables the preview (but you can still
|
|
explicitly request a preview window by pressing @kbd{C-h} or
|
|
@key{F1} when Emacs prompts for a register).
|
|
|
|
@item t
|
|
This value requests a more flexible preview of existing registers.
|
|
The preview appears immediately when Emacs prompts for a register
|
|
(thus @code{register-preview-delay} has no effect), and the preview
|
|
window provides navigation: by using @kbd{C-n} and @kbd{C-p} (or the
|
|
@kbd{@key{UP}} and @kbd{@key{DOWN}} arrow keys), you can move between
|
|
the registers in the preview window. To overwrite the value of an
|
|
existing registers in this mode, you need to type @key{RET} after
|
|
selecting the register by navigation or typing its name.
|
|
|
|
In addition, the registers shown by the preview are filtered according
|
|
to the command that popped the preview: for example, the preview shown
|
|
by @code{insert-register} will only show registers whose values can be
|
|
inserted into the buffer, omitting registers which hold window
|
|
configurations, positions, and other un-insertable values.
|
|
|
|
@item insist
|
|
This value is like @code{t}, but in addition you can press the same
|
|
key as the name of register one more time to exit the minibuffer,
|
|
instead of pressing @key{RET}.
|
|
|
|
@item nil
|
|
This value requests behavior similar to @code{traditional}, but the
|
|
preview is shown without delay, and is filtered according to the
|
|
command.
|
|
|
|
@item never
|
|
This value is like @code{nil}, but it disables the preview.
|
|
@end table
|
|
|
|
@dfn{Bookmarks} record files and positions in them, so you can
|
|
return to those positions when you look at the file again. Bookmarks
|
|
are similar in spirit to registers, so they are also documented in
|
|
this chapter.
|
|
|
|
@menu
|
|
* Position Registers:: Saving positions in registers.
|
|
* Text Registers:: Saving text in registers.
|
|
* Rectangle Registers:: Saving rectangles in registers.
|
|
* Configuration Registers:: Saving window/frame configurations in registers.
|
|
* Number Registers:: Numbers in registers.
|
|
* File and Buffer Registers:: File and buffer names in registers.
|
|
* Keyboard Macro Registers:: Keyboard macros in registers.
|
|
* Bookmarks:: Bookmarks are like registers, but persistent.
|
|
@end menu
|
|
|
|
@node Position Registers
|
|
@section Saving Positions in Registers
|
|
@cindex saving position in a register
|
|
|
|
@table @kbd
|
|
@item C-x r @key{SPC} @var{r}
|
|
Record the position of point and the current buffer in register
|
|
@var{r} (@code{point-to-register}).
|
|
@item C-x r j @var{r}
|
|
Jump to the position and buffer saved in register @var{r}
|
|
(@code{jump-to-register}).
|
|
@end table
|
|
|
|
@kindex C-x r SPC
|
|
@findex point-to-register
|
|
Typing @kbd{C-x r @key{SPC}} (@code{point-to-register}), followed by
|
|
a character @kbd{@var{r}}, saves both the position of point and the
|
|
current buffer in register @var{r}. The register retains this
|
|
information until you store something else in it.
|
|
|
|
@kindex C-x r j
|
|
@findex jump-to-register
|
|
The command @kbd{C-x r j @var{r}} switches to the buffer recorded in
|
|
register @var{r}, pushes a mark, and moves point to the recorded
|
|
position. (The mark is not pushed if point was already at the
|
|
recorded position, or in successive calls to the command.) The
|
|
contents of the register are not changed, so you can jump to the saved
|
|
position any number of times.
|
|
|
|
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 Text Registers
|
|
@section Saving Text in Registers
|
|
@cindex saving text in a register
|
|
|
|
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 and later retrieve it.
|
|
|
|
@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}).
|
|
@item M-x append-to-register @key{RET} @var{r}
|
|
Append region to text in register @var{r}.
|
|
|
|
When register @var{r} contains text, you can use @kbd{C-x r +}
|
|
(@code{increment-register}) to append to that register. Note that
|
|
command @kbd{C-x r +} behaves differently if @var{r} contains a
|
|
number. @xref{Number Registers}.
|
|
|
|
@item M-x prepend-to-register @key{RET} @var{r}
|
|
Prepend region to text in register @var{r}.
|
|
@end table
|
|
|
|
@kindex C-x r s
|
|
@findex copy-to-register
|
|
@kbd{C-x r s @var{r}} stores a copy of the text of the region into
|
|
the register named @var{r}. If the mark is inactive, Emacs first
|
|
reactivates the mark where it was last set. The mark is deactivated
|
|
at the end of this command. @xref{Mark}. @kbd{C-u C-x r s @var{r}},
|
|
the same command with a prefix argument, copies the text into register
|
|
@var{r} and deletes the text from the buffer as well; you can think of
|
|
this as moving the region text into the register.
|
|
|
|
@findex append-to-register
|
|
@findex prepend-to-register
|
|
@kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of
|
|
the text in the region to the text already stored in the register
|
|
named @var{r}. If invoked with a prefix argument, it deletes the
|
|
region after appending it to the register. The command
|
|
@code{prepend-to-register} is similar, except that it @emph{prepends}
|
|
the region text to the text in the register instead of
|
|
@emph{appending} it.
|
|
|
|
@vindex register-separator
|
|
When you are collecting text using @code{append-to-register} and
|
|
@code{prepend-to-register}, you may want to separate individual
|
|
collected pieces using a separator. In that case, configure a
|
|
@code{register-separator} and store the separator text in to that
|
|
register. For example, to get double newlines as text separator
|
|
during the collection process, you can use the following setting.
|
|
|
|
@example
|
|
(setq register-separator ?+)
|
|
(set-register register-separator "\n\n")
|
|
@end example
|
|
|
|
@kindex C-x r i
|
|
@findex insert-register
|
|
@kbd{C-x r i @var{r}} inserts in the buffer the text from register
|
|
@var{r}. Normally it leaves point after the text and sets the mark
|
|
before, without activating it. With a prefix argument, it instead
|
|
puts point before the text and the mark after.
|
|
|
|
@node Rectangle Registers
|
|
@section Saving Rectangles in Registers
|
|
@cindex saving rectangle in a register
|
|
|
|
A register can contain a rectangle instead of linear text.
|
|
@xref{Rectangles}, for basic information on how to specify a rectangle
|
|
in the 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 prefix 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}} (@code{insert-register}) command,
|
|
previously documented in @ref{Text Registers}, inserts a rectangle
|
|
rather than a text string, if the register contains a rectangle.
|
|
|
|
@node Configuration Registers
|
|
@section Saving Window and Frame Configurations in Registers
|
|
@cindex saving window configuration in a register
|
|
@cindex saving frame configuration in a register
|
|
@cindex frameset, saving in a register
|
|
|
|
@findex window-configuration-to-register
|
|
@findex frameset-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 windows in all frames, and
|
|
restore the configuration later. @xref{Window Convenience}, for
|
|
information about window configurations.
|
|
|
|
@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}).
|
|
@cindex frameset
|
|
@item C-x r f @var{r}
|
|
Save the state of all frames, including all their windows (a.k.a.@:
|
|
@dfn{frameset}), in register @var{r} (@code{frameset-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 Number Registers
|
|
@section Keeping Numbers in Registers
|
|
@cindex saving number in a register
|
|
|
|
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{r}
|
|
@kindex C-x r n
|
|
@findex number-to-register
|
|
Store @var{number} into register @var{r} (@code{number-to-register}).
|
|
@item C-u @var{number} C-x r + @var{r}
|
|
@kindex C-x r +
|
|
@findex increment-register
|
|
If @var{r} contains a number, increment the number in that register by
|
|
@var{number}. Note that command @kbd{C-x r +}
|
|
(@code{increment-register}) behaves differently if @var{r} contains
|
|
text. @xref{Text Registers}.
|
|
@item C-x r i @var{r}
|
|
Insert the number from register @var{r} into the buffer.
|
|
@end table
|
|
|
|
@kbd{C-x r i} is the same command used to insert any other sort of
|
|
register contents into the buffer. @kbd{C-x r +} with no numeric
|
|
argument increments the register value by 1; @kbd{C-x r n} with no
|
|
numeric argument stores zero in the register.
|
|
|
|
@node File and Buffer Registers
|
|
@section Keeping File and Buffer Names in Registers
|
|
@cindex saving file name in a register
|
|
@cindex saving buffer name in a register
|
|
|
|
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 @var{name} into register @var{r}:
|
|
|
|
@smallexample
|
|
(set-register @var{r} '(file . @var{name}))
|
|
@end smallexample
|
|
|
|
@need 3000
|
|
@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.)
|
|
|
|
Similarly, if there are certain buffers you visit frequently, you
|
|
can put their names in registers. For instance, if you visit the
|
|
@samp{*Messages*} buffer often, you can use the following snippet to
|
|
put that buffer into the @samp{m} register:
|
|
|
|
@smallexample
|
|
(set-register ?m '(buffer . "*Messages*"))
|
|
@end smallexample
|
|
|
|
To switch to the buffer whose name is in register @var{r}, type
|
|
@kbd{C-x r j @var{r}}.
|
|
|
|
@node Keyboard Macro Registers
|
|
@section Keyboard Macro Registers
|
|
@cindex saving keyboard macro in a register
|
|
@cindex keyboard macros, in registers
|
|
|
|
@kindex C-x C-k x
|
|
@findex kmacro-to-register
|
|
If you need to execute a keyboard macro (@pxref{Keyboard Macros})
|
|
frequently, it is more convenient to put it in a register or save it
|
|
(@pxref{Save Keyboard Macro}). @kbd{C-x C-k x @var{r}}
|
|
(@code{kmacro-to-register}) stores the last keyboard macro in register
|
|
@var{r}.
|
|
|
|
To execute the keyboard macro 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 frameset.)
|
|
|
|
@node Bookmarks
|
|
@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.
|
|
|
|
@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}
|
|
Set the bookmark named @var{bookmark} at point (@code{bookmark-set}).
|
|
|
|
@item C-x r M @var{bookmark} @key{RET}
|
|
Like @kbd{C-x r m}, but don't overwrite an existing bookmark.
|
|
|
|
@item C-x r b @var{bookmark} @key{RET}
|
|
Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}).
|
|
|
|
@item C-x r l
|
|
List all bookmarks (@code{list-bookmarks}).
|
|
|
|
@item M-x 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
|
|
To record the current position in the visited file, use the command
|
|
@kbd{C-x r m}, which sets a bookmark using 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} (@code{bookmark-jump}), and move to the
|
|
position of the bookmark at the same time.
|
|
|
|
@vindex bookmark-fringe-mark
|
|
In addition to recording the current position, on graphical displays
|
|
@kbd{C-x r m} places a special image on the left fringe
|
|
(@pxref{Fringes}) of the screen line corresponding to the recorded
|
|
position, to indicate that there's a bookmark there. This can be
|
|
controlled by the user option @code{bookmark-fringe-mark}: customize
|
|
it to @code{nil} to disable the fringe mark. The default value is
|
|
@code{bookmark-mark}, which is the bitmap used for this purpose. When
|
|
you later use @kbd{C-x r b} to jump back to the bookmark, the fringe
|
|
mark will be again shown on the fringe.
|
|
|
|
@kindex C-x r M
|
|
@findex bookmark-set-no-overwrite
|
|
The command @kbd{C-x r M} (@code{bookmark-set-no-overwrite}) works
|
|
like @w{@kbd{C-x r m}}, but it signals an error if the specified
|
|
bookmark already exists, instead of overwriting it.
|
|
|
|
@kindex C-x r l
|
|
@findex list-bookmarks
|
|
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 the bookmark buffer for more
|
|
information about its special editing commands.
|
|
|
|
@findex bookmark-save
|
|
When you kill Emacs, Emacs saves your bookmarks, if
|
|
you have changed any bookmark values. You can also save the bookmarks
|
|
at any time with the @kbd{M-x bookmark-save} command. Bookmarks are
|
|
saved to the file @file{~/.emacs.d/bookmarks} (for compatibility with
|
|
older versions of Emacs, if you have a file named @file{~/.emacs.bmk},
|
|
that is used instead). The bookmark commands load your default
|
|
bookmark file automatically. This saving and loading is how bookmarks
|
|
persist from one Emacs session to the next.
|
|
|
|
@vindex bookmark-save-flag
|
|
If you set the variable @code{bookmark-save-flag} to 1, each command
|
|
that sets a bookmark will also save your bookmarks; this way, you
|
|
don't lose any bookmark values even if Emacs crashes. The value, if
|
|
a number, says how many bookmark modifications should go by between
|
|
saving. If you set this variable to @code{nil}, Emacs only
|
|
saves bookmarks if you explicitly use @kbd{M-x bookmark-save}.
|
|
|
|
@vindex bookmark-default-file
|
|
The variable @code{bookmark-default-file} specifies the file in
|
|
which to save bookmarks by default.
|
|
|
|
@vindex bookmark-use-annotations
|
|
@cindex bookmark annotations
|
|
If you set the variable @code{bookmark-use-annotations} to @code{t},
|
|
setting a bookmark will query for an annotation. If a bookmark has an
|
|
annotation, it is automatically shown in a separate window when you
|
|
jump to the bookmark.
|
|
|
|
@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. (In buffers that are visiting encrypted files, no context
|
|
is saved in the bookmarks file no matter the value of this variable.)
|
|
|
|
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
|