1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
4 @node Registers, Display, Rectangles, Top
8 Emacs @dfn{registers} are compartments where you can save text,
9 rectangles, positions, and other things for later use. Once you save
10 text or a rectangle in a register, you can copy it into the buffer
11 once, or many times; you can move point to a position saved in a
12 register once, or many times.
15 Each register has a name, which consists of a single character.
17 store a piece of text, a rectangle, a position, a window configuration,
18 or a file name, but only one thing at any given time. Whatever you
19 store in a register remains there until you store something else in that
20 register. To see what a register @var{r} contains, use @kbd{M-x
24 @item M-x view-register @key{RET} @var{r}
25 Display a description of what register @var{r} contains.
29 * Position: RegPos. Saving positions in registers.
30 * Text: RegText. Saving text in registers.
31 * Rectangle: RegRect. Saving rectangles in registers.
32 * Configurations: RegConfig. Saving window configurations in registers.
33 * Files: RegFiles. File names in registers.
34 * Numbers: RegNumbers. Numbers in registers.
35 * Bookmarks:: Bookmarks are like registers, but persistent.
39 @section Saving Positions in Registers
41 Saving a position records a place in a buffer so that you can move
42 back there later. Moving to a saved position switches to that buffer
43 and moves point to that place in it.
46 @item C-x r @key{SPC} @var{r}
47 Save position of point in register @var{r} (@code{point-to-register}).
49 Jump to the position saved in register @var{r} (@code{jump-to-register}).
53 @findex point-to-register
54 To save the current position of point in a register, choose a name
55 @var{r} and type @kbd{C-x r @key{SPC} @var{r}}. The register @var{r}
56 retains the position thus saved until you store something else in that
60 @findex jump-to-register
61 The command @kbd{C-x r j @var{r}} moves point to the position recorded
62 in register @var{r}. The register is not affected; it continues to
63 hold the same position. You can jump to the saved position any number
66 If you use @kbd{C-x r j} to go to a saved position, but the buffer it
67 was saved from has been killed, @kbd{C-x r j} tries to create the buffer
68 again by visiting the same file. Of course, this works only for buffers
69 that were visiting files.
72 @section Saving Text in Registers
74 When you want to insert a copy of the same piece of text several
75 times, it may be inconvenient to yank it from the kill ring, since each
76 subsequent kill moves that entry further down the ring. An alternative
77 is to store the text in a register and later retrieve it.
81 Copy region into register @var{r} (@code{copy-to-register}).
83 Insert text from register @var{r} (@code{insert-register}).
88 @findex copy-to-register
89 @findex insert-register
90 @kbd{C-x r s @var{r}} stores a copy of the text of the region into
91 the register named @var{r}. @kbd{C-u C-x r s @var{r}}, the same
92 command with a numeric argument, deletes the text from the buffer as
95 @kbd{C-x r i @var{r}} inserts in the buffer the text from register
96 @var{r}. Normally it leaves point before the text and places the mark
97 after, but with a numeric argument (@kbd{C-u}) it puts point after the
98 text and the mark before.
101 @section Saving Rectangles in Registers
103 A register can contain a rectangle instead of linear text. The
104 rectangle is represented as a list of strings. @xref{Rectangles}, for
105 basic information on how to specify a rectangle in the buffer.
108 @findex copy-rectangle-to-register
110 @item C-x r r @var{r}
111 Copy the region-rectangle into register @var{r}
112 (@code{copy-rectangle-to-register}). With numeric argument, delete it as
114 @item C-x r i @var{r}
115 Insert the rectangle stored in register @var{r} (if it contains a
116 rectangle) (@code{insert-register}).
119 The @kbd{C-x r i @var{r}} command inserts a text string if the
120 register contains one, and inserts a rectangle if the register contains
123 See also the command @code{sort-columns}, which you can think of
124 as sorting a rectangle. @xref{Sorting}.
127 @section Saving Window Configurations in Registers
129 @findex window-configuration-to-register
130 @findex frame-configuration-to-register
133 You can save the window configuration of the selected frame in a
134 register, or even the configuration of all windows in all frames, and
135 restore the configuration later.
138 @item C-x r w @var{r}
139 Save the state of the selected frame's windows in register @var{r}
140 (@code{window-configuration-to-register}).
141 @item C-x r f @var{r}
142 Save the state of all frames, including all their windows, in register
143 @var{r} (@code{frame-configuration-to-register}).
146 Use @kbd{C-x r j @var{r}} to restore a window or frame configuration.
147 This is the same command used to restore a cursor position. When you
148 restore a frame configuration, any existing frames not included in the
149 configuration become invisible. If you wish to delete these frames
150 instead, use @kbd{C-u C-x r j @var{r}}.
153 @section Keeping Numbers in Registers
155 There are commands to store a number in a register, to insert
156 the number in the buffer in decimal, and to increment it. These commands
157 can be useful in keyboard macros (@pxref{Keyboard Macros}).
160 @item C-u @var{number} C-x r n @var{r}
162 @findex number-to-register
163 Store @var{number} into register @var{r} (@code{number-to-register}).
164 @item C-u @var{number} C-x r + @var{r}
166 @findex increment-register
167 Increment the number in register @var{r} by @var{number}
168 (@code{increment-register}).
169 @item C-x r g @var{r}
170 Insert the number from register @var{r} into the buffer.
173 @kbd{C-x r g} is the same command used to insert any other sort of
174 register contents into the buffer. @kbd{C-x r +} with no numeric
175 argument increments the register value by 1; @kbd{C-x r n} with no
176 numeric argument stores zero in the register.
179 @section Keeping File Names in Registers
181 If you visit certain file names frequently, you can visit them more
182 conveniently if you put their names in registers. Here's the Lisp code
183 used to put a file name in a register:
186 (set-register ?@var{r} '(file . @var{name}))
194 (set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))
198 puts the file name shown in register @samp{z}.
200 To visit the file whose name is in register @var{r}, type @kbd{C-x r j
201 @var{r}}. (This is the same command used to jump to a position or
202 restore a frame configuration.)
208 @dfn{Bookmarks} are somewhat like registers in that they record
209 positions you can jump to. Unlike registers, they have long names, and
210 they persist automatically from one Emacs session to the next. The
211 prototypical use of bookmarks is to record ``where you were reading'' in
215 @item C-x r m @key{RET}
216 Set the bookmark for the visited file, at point.
218 @item C-x r m @var{bookmark} @key{RET}
220 Set the bookmark named @var{bookmark} at point (@code{bookmark-set}).
222 @item C-x r b @var{bookmark} @key{RET}
223 @findex bookmark-jump
224 Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}).
227 @findex list-bookmarks
228 List all bookmarks (@code{list-bookmarks}).
230 @item M-x bookmark-save
231 @findex bookmark-save
232 Save all the current bookmark values in the default bookmark file.
238 @findex bookmark-jump
239 The prototypical use for bookmarks is to record one current position
240 in each of several files. So the command @kbd{C-x r m}, which sets a
241 bookmark, uses the visited file name as the default for the bookmark
242 name. If you name each bookmark after the file it points to, then you
243 can conveniently revisit any of those files with @kbd{C-x r b}, and move
244 to the position of the bookmark at the same time.
247 To display a list of all your bookmarks in a separate buffer, type
248 @kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer,
249 you can use it to edit your bookmark definitions or annotate the
250 bookmarks. Type @kbd{C-h m} in that buffer for more information about
251 its special editing commands.
253 When you kill Emacs, Emacs offers to save your bookmark values in your
254 default bookmark file, @file{~/.emacs.bmk}, if you have changed any
255 bookmark values. You can also save the bookmarks at any time with the
256 @kbd{M-x bookmark-save} command. The bookmark commands load your
257 default bookmark file automatically. This saving and loading is how
258 bookmarks persist from one Emacs session to the next.
260 @vindex bookmark-save-flag
261 If you set the variable @code{bookmark-save-flag} to 1, then each
262 command that sets a bookmark will also save your bookmarks; this way,
263 you don't lose any bookmark values even if Emacs crashes. (The value,
264 if a number, says how many bookmark modifications should go by between
267 @vindex bookmark-search-size
268 Bookmark position values are saved with surrounding context, so that
269 @code{bookmark-jump} can find the proper position even if the file is
270 modified slightly. The variable @code{bookmark-search-size} says how
271 many characters of context to record on each side of the bookmark's
274 Here are some additional commands for working with bookmarks:
277 @item M-x bookmark-load @key{RET} @var{filename} @key{RET}
278 @findex bookmark-load
279 Load a file named @var{filename} that contains a list of bookmark
280 values. You can use this command, as well as @code{bookmark-write}, to
281 work with other files of bookmark values in addition to your default
284 @item M-x bookmark-write @key{RET} @var{filename} @key{RET}
285 @findex bookmark-write
286 Save all the current bookmark values in the file @var{filename}.
288 @item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET}
289 @findex bookmark-delete
290 Delete the bookmark named @var{bookmark}.
292 @item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET}
293 @findex bookmark-insert-location
294 Insert in the buffer the name of the file that bookmark @var{bookmark}
297 @item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET}
298 @findex bookmark-insert
299 Insert in the buffer the @emph{contents} of the file that bookmark
300 @var{bookmark} points to.