Commit | Line | Data |
---|---|---|
6bf7aab6 | 1 | @c This is part of the Emacs manual. |
ab422c4d PE |
2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software |
3 | @c Foundation, Inc. | |
6bf7aab6 | 4 | @c See file emacs.texi for copying conditions. |
abb9615e | 5 | @node Registers |
6bf7aab6 DL |
6 | @chapter Registers |
7 | @cindex registers | |
8 | ||
485bceb5 RS |
9 | Emacs @dfn{registers} are compartments where you can save text, |
10 | rectangles, positions, and other things for later use. Once you save | |
11 | text or a rectangle in a register, you can copy it into the buffer | |
d0ca439d CY |
12 | once, or many times; once you save a position in a register, you can |
13 | jump back to that position once, or many times. | |
14 | ||
15 | Each register has a name that consists of a single character, which | |
16 | we will denote by @var{r}; @var{r} can be a letter (such as @samp{a}) | |
17 | or a number (such as @samp{1}); case matters, so register @samp{a} is | |
18 | not the same as register @samp{A}. | |
6bf7aab6 DL |
19 | |
20 | @findex view-register | |
d0ca439d CY |
21 | A register can store a position, a piece of text, a rectangle, a |
22 | number, a window configuration, or a file name, but only one thing at | |
23 | any given time. Whatever you store in a register remains there until | |
24 | you store something else in that register. To see what register | |
25 | @var{r} contains, use @kbd{M-x view-register}: | |
6bf7aab6 DL |
26 | |
27 | @table @kbd | |
28 | @item M-x view-register @key{RET} @var{r} | |
29 | Display a description of what register @var{r} contains. | |
30 | @end table | |
31 | ||
c48a6229 | 32 | @dfn{Bookmarks} record files and positions in them, so you can |
21100e7d CY |
33 | return to those positions when you look at the file again. Bookmarks |
34 | are similar in spirit to registers, so they are also documented in | |
35 | this chapter. | |
c48a6229 | 36 | |
6bf7aab6 | 37 | @menu |
a30ed87b LMI |
38 | * Position Registers:: Saving positions in registers. |
39 | * Text Registers:: Saving text in registers. | |
40 | * Rectangle Registers:: Saving rectangles in registers. | |
41 | * Configuration Registers:: Saving window configurations in registers. | |
42 | * Number Registers:: Numbers in registers. | |
43 | * File Registers:: File names in registers. | |
ced5cc29 | 44 | * Keyboard Macro Registers:: Keyboard macros in registers. |
a30ed87b | 45 | * Bookmarks:: Bookmarks are like registers, but persistent. |
6bf7aab6 DL |
46 | @end menu |
47 | ||
a30ed87b | 48 | @node Position Registers |
6bf7aab6 | 49 | @section Saving Positions in Registers |
7ea0f431 | 50 | @cindex saving position in a register |
6bf7aab6 | 51 | |
6bf7aab6 DL |
52 | @table @kbd |
53 | @item C-x r @key{SPC} @var{r} | |
d0ca439d CY |
54 | Record the position of point and the current buffer in register |
55 | @var{r} (@code{point-to-register}). | |
6bf7aab6 | 56 | @item C-x r j @var{r} |
d0ca439d CY |
57 | Jump to the position and buffer saved in register @var{r} |
58 | (@code{jump-to-register}). | |
6bf7aab6 DL |
59 | @end table |
60 | ||
61 | @kindex C-x r SPC | |
62 | @findex point-to-register | |
d0ca439d CY |
63 | Typing @kbd{C-x r @key{SPC}} (@code{point-to-register}), followed by |
64 | a character @kbd{@var{r}}, saves both the position of point and the | |
65 | current buffer in register @var{r}. The register retains this | |
66 | information until you store something else in it. | |
6bf7aab6 DL |
67 | |
68 | @kindex C-x r j | |
69 | @findex jump-to-register | |
d0ca439d CY |
70 | The command @kbd{C-x r j @var{r}} switches to the buffer recorded in |
71 | register @var{r}, and moves point to the recorded position. The | |
72 | contents of the register are not changed, so you can jump to the saved | |
73 | position any number of times. | |
6bf7aab6 DL |
74 | |
75 | If you use @kbd{C-x r j} to go to a saved position, but the buffer it | |
76 | was saved from has been killed, @kbd{C-x r j} tries to create the buffer | |
77 | again by visiting the same file. Of course, this works only for buffers | |
78 | that were visiting files. | |
79 | ||
a30ed87b | 80 | @node Text Registers |
6bf7aab6 | 81 | @section Saving Text in Registers |
7ea0f431 | 82 | @cindex saving text in a register |
6bf7aab6 DL |
83 | |
84 | When you want to insert a copy of the same piece of text several | |
85 | times, it may be inconvenient to yank it from the kill ring, since each | |
86 | subsequent kill moves that entry further down the ring. An alternative | |
87 | is to store the text in a register and later retrieve it. | |
88 | ||
89 | @table @kbd | |
90 | @item C-x r s @var{r} | |
91 | Copy region into register @var{r} (@code{copy-to-register}). | |
92 | @item C-x r i @var{r} | |
93 | Insert text from register @var{r} (@code{insert-register}). | |
7ea0f431 EZ |
94 | @item M-x append-to-register @key{RET} @var{r} |
95 | Append region to text in register @var{r}. | |
0979429b J |
96 | |
97 | @kindex C-x r + | |
98 | When register @var{r} contains text, you can use @kbd{C-x r +} | |
99 | (@code{increment-register}) to append to that register. Note that | |
100 | command @kbd{C-x r +} behaves differently if @var{r} contains a | |
101 | number. @xref{Number Registers}. | |
102 | ||
7ea0f431 EZ |
103 | @item M-x prepend-to-register @key{RET} @var{r} |
104 | Prepend region to text in register @var{r}. | |
6bf7aab6 DL |
105 | @end table |
106 | ||
107 | @kindex C-x r s | |
6bf7aab6 | 108 | @findex copy-to-register |
e75e59fd | 109 | @kbd{C-x r s @var{r}} stores a copy of the text of the region into |
d0ca439d CY |
110 | the register named @var{r}. If the mark is inactive, Emacs first |
111 | reactivates the mark where it was last set. The mark is deactivated | |
112 | at the end of this command. @xref{Mark}. @kbd{C-u C-x r s @var{r}}, | |
113 | the same command with a prefix argument, copies the text into register | |
114 | @var{r} and deletes the text from the buffer as well; you can think of | |
115 | this as ``moving'' the region text into the register. | |
6bf7aab6 | 116 | |
7ea0f431 EZ |
117 | @findex append-to-register |
118 | @findex prepend-to-register | |
119 | @kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of | |
120 | the text in the region to the text already stored in the register | |
d0ca439d | 121 | named @var{r}. If invoked with a prefix argument, it deletes the |
60b541d1 EZ |
122 | region after appending it to the register. The command |
123 | @code{prepend-to-register} is similar, except that it @emph{prepends} | |
d0ca439d | 124 | the region text to the text in the register instead of |
60b541d1 | 125 | @emph{appending} it. |
7ea0f431 | 126 | |
0979429b J |
127 | @vindex register-separator |
128 | When you are collecting text using @code{append-to-register} and | |
129 | @code{prepend-to-register}, you may want to separate individual | |
130 | collected pieces using a separator. In that case, configure a | |
131 | @code{register-separator} and store the separator text in to that | |
132 | register. For example, to get double newlines as text separator | |
133 | during the collection process, you can use the following setting. | |
134 | ||
135 | @example | |
136 | (setq register-separator ?+) | |
137 | (set-register register-separator "\n\n") | |
138 | @end example | |
139 | ||
d0ca439d CY |
140 | @kindex C-x r i |
141 | @findex insert-register | |
6bf7aab6 | 142 | @kbd{C-x r i @var{r}} inserts in the buffer the text from register |
21100e7d CY |
143 | @var{r}. Normally it leaves point before the text and sets the mark |
144 | after, without activating it. With a numeric argument, it instead | |
145 | puts point after the text and the mark before. | |
6bf7aab6 | 146 | |
a30ed87b | 147 | @node Rectangle Registers |
6bf7aab6 | 148 | @section Saving Rectangles in Registers |
7ea0f431 | 149 | @cindex saving rectangle in a register |
6bf7aab6 | 150 | |
d0ca439d CY |
151 | A register can contain a rectangle instead of linear text. |
152 | @xref{Rectangles}, for basic information on how to specify a rectangle | |
153 | in the buffer. | |
6bf7aab6 DL |
154 | |
155 | @table @kbd | |
156 | @findex copy-rectangle-to-register | |
157 | @kindex C-x r r | |
158 | @item C-x r r @var{r} | |
159 | Copy the region-rectangle into register @var{r} | |
160 | (@code{copy-rectangle-to-register}). With numeric argument, delete it as | |
161 | well. | |
162 | @item C-x r i @var{r} | |
163 | Insert the rectangle stored in register @var{r} (if it contains a | |
164 | rectangle) (@code{insert-register}). | |
165 | @end table | |
166 | ||
21100e7d CY |
167 | The @kbd{C-x r i @var{r}} (@code{insert-register}) command, |
168 | previously documented in @ref{Text Registers}, inserts a rectangle | |
58179cce | 169 | rather than a text string, if the register contains a rectangle. |
6bf7aab6 | 170 | |
a30ed87b | 171 | @node Configuration Registers |
6bf7aab6 | 172 | @section Saving Window Configurations in Registers |
7ea0f431 | 173 | @cindex saving window configuration in a register |
6bf7aab6 DL |
174 | |
175 | @findex window-configuration-to-register | |
176 | @findex frame-configuration-to-register | |
177 | @kindex C-x r w | |
178 | @kindex C-x r f | |
179 | You can save the window configuration of the selected frame in a | |
180 | register, or even the configuration of all windows in all frames, and | |
d0ca439d CY |
181 | restore the configuration later. @xref{Windows}, for information |
182 | about window configurations. | |
6bf7aab6 DL |
183 | |
184 | @table @kbd | |
185 | @item C-x r w @var{r} | |
186 | Save the state of the selected frame's windows in register @var{r} | |
187 | (@code{window-configuration-to-register}). | |
188 | @item C-x r f @var{r} | |
189 | Save the state of all frames, including all their windows, in register | |
190 | @var{r} (@code{frame-configuration-to-register}). | |
191 | @end table | |
192 | ||
193 | Use @kbd{C-x r j @var{r}} to restore a window or frame configuration. | |
194 | This is the same command used to restore a cursor position. When you | |
195 | restore a frame configuration, any existing frames not included in the | |
196 | configuration become invisible. If you wish to delete these frames | |
197 | instead, use @kbd{C-u C-x r j @var{r}}. | |
198 | ||
a30ed87b | 199 | @node Number Registers |
6bf7aab6 | 200 | @section Keeping Numbers in Registers |
7ea0f431 | 201 | @cindex saving number in a register |
6bf7aab6 DL |
202 | |
203 | There are commands to store a number in a register, to insert | |
204 | the number in the buffer in decimal, and to increment it. These commands | |
205 | can be useful in keyboard macros (@pxref{Keyboard Macros}). | |
206 | ||
207 | @table @kbd | |
485bceb5 | 208 | @item C-u @var{number} C-x r n @var{r} |
6bf7aab6 DL |
209 | @kindex C-x r n |
210 | @findex number-to-register | |
485bceb5 RS |
211 | Store @var{number} into register @var{r} (@code{number-to-register}). |
212 | @item C-u @var{number} C-x r + @var{r} | |
6bf7aab6 DL |
213 | @kindex C-x r + |
214 | @findex increment-register | |
0979429b J |
215 | If @var{r} contains a number, increment the number in that register by |
216 | @var{number}. Note that command @kbd{C-x r +} | |
217 | (@code{increment-register}) behaves differently if @var{r} contains | |
218 | text. @xref{Text Registers}. | |
d48102cf | 219 | @item C-x r i @var{r} |
485bceb5 | 220 | Insert the number from register @var{r} into the buffer. |
6bf7aab6 DL |
221 | @end table |
222 | ||
d48102cf | 223 | @kbd{C-x r i} is the same command used to insert any other sort of |
485bceb5 RS |
224 | register contents into the buffer. @kbd{C-x r +} with no numeric |
225 | argument increments the register value by 1; @kbd{C-x r n} with no | |
226 | numeric argument stores zero in the register. | |
6bf7aab6 | 227 | |
a30ed87b | 228 | @node File Registers |
6bf7aab6 | 229 | @section Keeping File Names in Registers |
5fe3b9bc | 230 | @cindex saving file name in a register |
6bf7aab6 DL |
231 | |
232 | If you visit certain file names frequently, you can visit them more | |
233 | conveniently if you put their names in registers. Here's the Lisp code | |
234 | used to put a file name in a register: | |
235 | ||
236 | @smallexample | |
237 | (set-register ?@var{r} '(file . @var{name})) | |
238 | @end smallexample | |
239 | ||
240 | @need 3000 | |
241 | @noindent | |
242 | For example, | |
243 | ||
244 | @smallexample | |
245 | (set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog")) | |
246 | @end smallexample | |
247 | ||
248 | @noindent | |
249 | puts the file name shown in register @samp{z}. | |
250 | ||
251 | To visit the file whose name is in register @var{r}, type @kbd{C-x r j | |
252 | @var{r}}. (This is the same command used to jump to a position or | |
253 | restore a frame configuration.) | |
254 | ||
ced5cc29 XF |
255 | @node Keyboard Macro Registers |
256 | @section Keyboard Macro Registers | |
257 | @cindex saving keyboard macro in a register | |
258 | @cindex keyboard macros, in registers | |
259 | ||
260 | @kindex C-x C-k x | |
261 | @findex kmacro-to-register | |
569c1c6e EZ |
262 | If you need to execute a keyboard macro (@pxref{Keyboard Macros}) |
263 | frequently, it is more convenient to put it in a register or save it | |
264 | (@pxref{Save Keyboard Macro}). @kbd{C-x C-k x @var{r}} | |
265 | (@code{kmacro-to-register}) stores the last keyboard macro in register | |
266 | @var{r}. | |
ced5cc29 XF |
267 | |
268 | To execute the keyboard macro in register @var{r}, type @kbd{C-x r j | |
269 | @var{r}}. (This is the same command used to jump to a position or | |
270 | restore a frameset.) | |
271 | ||
6bf7aab6 DL |
272 | @node Bookmarks |
273 | @section Bookmarks | |
274 | @cindex bookmarks | |
275 | ||
276 | @dfn{Bookmarks} are somewhat like registers in that they record | |
277 | positions you can jump to. Unlike registers, they have long names, and | |
278 | they persist automatically from one Emacs session to the next. The | |
279 | prototypical use of bookmarks is to record ``where you were reading'' in | |
280 | various files. | |
281 | ||
282 | @table @kbd | |
283 | @item C-x r m @key{RET} | |
284 | Set the bookmark for the visited file, at point. | |
285 | ||
286 | @item C-x r m @var{bookmark} @key{RET} | |
287 | @findex bookmark-set | |
288 | Set the bookmark named @var{bookmark} at point (@code{bookmark-set}). | |
289 | ||
290 | @item C-x r b @var{bookmark} @key{RET} | |
291 | @findex bookmark-jump | |
292 | Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}). | |
293 | ||
294 | @item C-x r l | |
295 | @findex list-bookmarks | |
296 | List all bookmarks (@code{list-bookmarks}). | |
297 | ||
298 | @item M-x bookmark-save | |
299 | @findex bookmark-save | |
300 | Save all the current bookmark values in the default bookmark file. | |
301 | @end table | |
302 | ||
303 | @kindex C-x r m | |
304 | @findex bookmark-set | |
305 | @kindex C-x r b | |
306 | @findex bookmark-jump | |
307 | The prototypical use for bookmarks is to record one current position | |
308 | in each of several files. So the command @kbd{C-x r m}, which sets a | |
309 | bookmark, uses the visited file name as the default for the bookmark | |
310 | name. If you name each bookmark after the file it points to, then you | |
311 | can conveniently revisit any of those files with @kbd{C-x r b}, and move | |
312 | to the position of the bookmark at the same time. | |
313 | ||
314 | @kindex C-x r l | |
315 | To display a list of all your bookmarks in a separate buffer, type | |
316 | @kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer, | |
317 | you can use it to edit your bookmark definitions or annotate the | |
1f7ebf7c RS |
318 | bookmarks. Type @kbd{C-h m} in the bookmark buffer for more |
319 | information about its special editing commands. | |
6bf7aab6 | 320 | |
b6e63cbe | 321 | When you kill Emacs, Emacs saves your bookmarks, if |
21100e7d CY |
322 | you have changed any bookmark values. You can also save the bookmarks |
323 | at any time with the @kbd{M-x bookmark-save} command. Bookmarks are | |
324 | saved to the file @file{~/.emacs.d/bookmarks} (for compatibility with | |
325 | older versions of Emacs, if you have a file named @file{~/.emacs.bmk}, | |
326 | that is used instead). The bookmark commands load your default | |
327 | bookmark file automatically. This saving and loading is how bookmarks | |
328 | persist from one Emacs session to the next. | |
6bf7aab6 DL |
329 | |
330 | @vindex bookmark-save-flag | |
d0ca439d CY |
331 | If you set the variable @code{bookmark-save-flag} to 1, each command |
332 | that sets a bookmark will also save your bookmarks; this way, you | |
b6e63cbe | 333 | don't lose any bookmark values even if Emacs crashes. The value, if |
d0ca439d | 334 | a number, says how many bookmark modifications should go by between |
b6e63cbe GM |
335 | saving. If you set this variable to @code{nil}, Emacs only |
336 | saves bookmarks if you explicitly use @kbd{M-x bookmark-save}. | |
6bf7aab6 | 337 | |
b7a017ad XF |
338 | @vindex bookmark-default-file |
339 | The variable @code{bookmark-default-file} specifies the file in | |
340 | which to save bookmarks by default. | |
341 | ||
6bf7aab6 DL |
342 | @vindex bookmark-search-size |
343 | Bookmark position values are saved with surrounding context, so that | |
344 | @code{bookmark-jump} can find the proper position even if the file is | |
345 | modified slightly. The variable @code{bookmark-search-size} says how | |
13b9ee95 | 346 | many characters of context to record on each side of the bookmark's |
6bf7aab6 DL |
347 | position. |
348 | ||
349 | Here are some additional commands for working with bookmarks: | |
350 | ||
351 | @table @kbd | |
352 | @item M-x bookmark-load @key{RET} @var{filename} @key{RET} | |
353 | @findex bookmark-load | |
354 | Load a file named @var{filename} that contains a list of bookmark | |
355 | values. You can use this command, as well as @code{bookmark-write}, to | |
356 | work with other files of bookmark values in addition to your default | |
357 | bookmark file. | |
358 | ||
359 | @item M-x bookmark-write @key{RET} @var{filename} @key{RET} | |
360 | @findex bookmark-write | |
361 | Save all the current bookmark values in the file @var{filename}. | |
362 | ||
363 | @item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET} | |
364 | @findex bookmark-delete | |
365 | Delete the bookmark named @var{bookmark}. | |
366 | ||
367 | @item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET} | |
368 | @findex bookmark-insert-location | |
369 | Insert in the buffer the name of the file that bookmark @var{bookmark} | |
370 | points to. | |
371 | ||
372 | @item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET} | |
373 | @findex bookmark-insert | |
374 | Insert in the buffer the @emph{contents} of the file that bookmark | |
375 | @var{bookmark} points to. | |
376 | @end table |