Commit | Line | Data |
---|---|---|
6bf7aab6 DL |
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 | |
5 | @chapter Registers | |
6 | @cindex registers | |
7 | ||
485bceb5 RS |
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. | |
6bf7aab6 DL |
13 | |
14 | @findex view-register | |
15 | Each register has a name which is a single character. A register can | |
16 | store a piece of text, a rectangle, a position, a window configuration, | |
17 | or a file name, but only one thing at any given time. Whatever you | |
18 | store in a register remains there until you store something else in that | |
19 | register. To see what a register @var{r} contains, use @kbd{M-x | |
20 | view-register}. | |
21 | ||
22 | @table @kbd | |
23 | @item M-x view-register @key{RET} @var{r} | |
24 | Display a description of what register @var{r} contains. | |
25 | @end table | |
26 | ||
27 | @menu | |
28 | * Position: RegPos. Saving positions in registers. | |
29 | * Text: RegText. Saving text in registers. | |
30 | * Rectangle: RegRect. Saving rectangles in registers. | |
31 | * Configurations: RegConfig. Saving window configurations in registers. | |
32 | * Files: RegFiles. File names in registers. | |
33 | * Numbers: RegNumbers. Numbers in registers. | |
34 | * Bookmarks:: Bookmarks are like registers, but persistent. | |
35 | @end menu | |
36 | ||
37 | @node RegPos | |
38 | @section Saving Positions in Registers | |
39 | ||
40 | Saving a position records a place in a buffer so that you can move | |
41 | back there later. Moving to a saved position switches to that buffer | |
42 | and moves point to that place in it. | |
43 | ||
44 | @table @kbd | |
45 | @item C-x r @key{SPC} @var{r} | |
46 | Save position of point in register @var{r} (@code{point-to-register}). | |
47 | @item C-x r j @var{r} | |
48 | Jump to the position saved in register @var{r} (@code{jump-to-register}). | |
49 | @end table | |
50 | ||
51 | @kindex C-x r SPC | |
52 | @findex point-to-register | |
53 | To save the current position of point in a register, choose a name | |
54 | @var{r} and type @kbd{C-x r @key{SPC} @var{r}}. The register @var{r} | |
55 | retains the position thus saved until you store something else in that | |
56 | register. | |
57 | ||
58 | @kindex C-x r j | |
59 | @findex jump-to-register | |
60 | The command @kbd{C-x r j @var{r}} moves point to the position recorded | |
61 | in register @var{r}. The register is not affected; it continues to | |
62 | record the same position. You can jump to the saved position any number | |
63 | of times. | |
64 | ||
65 | If you use @kbd{C-x r j} to go to a saved position, but the buffer it | |
66 | was saved from has been killed, @kbd{C-x r j} tries to create the buffer | |
67 | again by visiting the same file. Of course, this works only for buffers | |
68 | that were visiting files. | |
69 | ||
70 | @node RegText | |
71 | @section Saving Text in Registers | |
72 | ||
73 | When you want to insert a copy of the same piece of text several | |
74 | times, it may be inconvenient to yank it from the kill ring, since each | |
75 | subsequent kill moves that entry further down the ring. An alternative | |
76 | is to store the text in a register and later retrieve it. | |
77 | ||
78 | @table @kbd | |
79 | @item C-x r s @var{r} | |
80 | Copy region into register @var{r} (@code{copy-to-register}). | |
81 | @item C-x r i @var{r} | |
82 | Insert text from register @var{r} (@code{insert-register}). | |
83 | @end table | |
84 | ||
85 | @kindex C-x r s | |
86 | @kindex C-x r i | |
87 | @findex copy-to-register | |
88 | @findex insert-register | |
89 | @kbd{C-x r s @var{r}} stores a copy of the text of the region into the | |
90 | register named @var{r}. Given a numeric argument, @kbd{C-x r s @var{r}} | |
91 | deletes the text from the buffer as well. | |
92 | ||
93 | @kbd{C-x r i @var{r}} inserts in the buffer the text from register | |
94 | @var{r}. Normally it leaves point before the text and places the mark | |
95 | after, but with a numeric argument (@kbd{C-u}) it puts point after the | |
96 | text and the mark before. | |
97 | ||
98 | @node RegRect | |
99 | @section Saving Rectangles in Registers | |
100 | ||
101 | A register can contain a rectangle instead of linear text. The | |
102 | rectangle is represented as a list of strings. @xref{Rectangles}, for | |
103 | basic information on how to specify a rectangle in the buffer. | |
104 | ||
105 | @table @kbd | |
106 | @findex copy-rectangle-to-register | |
107 | @kindex C-x r r | |
108 | @item C-x r r @var{r} | |
109 | Copy the region-rectangle into register @var{r} | |
110 | (@code{copy-rectangle-to-register}). With numeric argument, delete it as | |
111 | well. | |
112 | @item C-x r i @var{r} | |
113 | Insert the rectangle stored in register @var{r} (if it contains a | |
114 | rectangle) (@code{insert-register}). | |
115 | @end table | |
116 | ||
117 | The @kbd{C-x r i @var{r}} command inserts a text string if the | |
118 | register contains one, and inserts a rectangle if the register contains | |
119 | one. | |
120 | ||
121 | See also the command @code{sort-columns}, which you can think of | |
122 | as sorting a rectangle. @xref{Sorting}. | |
123 | ||
124 | @node RegConfig | |
125 | @section Saving Window Configurations in Registers | |
126 | ||
127 | @findex window-configuration-to-register | |
128 | @findex frame-configuration-to-register | |
129 | @kindex C-x r w | |
130 | @kindex C-x r f | |
131 | You can save the window configuration of the selected frame in a | |
132 | register, or even the configuration of all windows in all frames, and | |
133 | restore the configuration later. | |
134 | ||
135 | @table @kbd | |
136 | @item C-x r w @var{r} | |
137 | Save the state of the selected frame's windows in register @var{r} | |
138 | (@code{window-configuration-to-register}). | |
139 | @item C-x r f @var{r} | |
140 | Save the state of all frames, including all their windows, in register | |
141 | @var{r} (@code{frame-configuration-to-register}). | |
142 | @end table | |
143 | ||
144 | Use @kbd{C-x r j @var{r}} to restore a window or frame configuration. | |
145 | This is the same command used to restore a cursor position. When you | |
146 | restore a frame configuration, any existing frames not included in the | |
147 | configuration become invisible. If you wish to delete these frames | |
148 | instead, use @kbd{C-u C-x r j @var{r}}. | |
149 | ||
150 | @node RegNumbers | |
151 | @section Keeping Numbers in Registers | |
152 | ||
153 | There are commands to store a number in a register, to insert | |
154 | the number in the buffer in decimal, and to increment it. These commands | |
155 | can be useful in keyboard macros (@pxref{Keyboard Macros}). | |
156 | ||
157 | @table @kbd | |
485bceb5 | 158 | @item C-u @var{number} C-x r n @var{r} |
6bf7aab6 DL |
159 | @kindex C-x r n |
160 | @findex number-to-register | |
485bceb5 RS |
161 | Store @var{number} into register @var{r} (@code{number-to-register}). |
162 | @item C-u @var{number} C-x r + @var{r} | |
6bf7aab6 DL |
163 | @kindex C-x r + |
164 | @findex increment-register | |
485bceb5 | 165 | Increment the number in register @var{r} by @var{number} |
6bf7aab6 | 166 | (@code{increment-register}). |
485bceb5 RS |
167 | @item C-x r g @var{r} |
168 | Insert the number from register @var{r} into the buffer. | |
6bf7aab6 DL |
169 | @end table |
170 | ||
485bceb5 RS |
171 | @kbd{C-x r g} is the same command used to insert any other sort of |
172 | register contents into the buffer. @kbd{C-x r +} with no numeric | |
173 | argument increments the register value by 1; @kbd{C-x r n} with no | |
174 | numeric argument stores zero in the register. | |
6bf7aab6 DL |
175 | |
176 | @node RegFiles | |
177 | @section Keeping File Names in Registers | |
178 | ||
179 | If you visit certain file names frequently, you can visit them more | |
180 | conveniently if you put their names in registers. Here's the Lisp code | |
181 | used to put a file name in a register: | |
182 | ||
183 | @smallexample | |
184 | (set-register ?@var{r} '(file . @var{name})) | |
185 | @end smallexample | |
186 | ||
187 | @need 3000 | |
188 | @noindent | |
189 | For example, | |
190 | ||
191 | @smallexample | |
192 | (set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog")) | |
193 | @end smallexample | |
194 | ||
195 | @noindent | |
196 | puts the file name shown in register @samp{z}. | |
197 | ||
198 | To visit the file whose name is in register @var{r}, type @kbd{C-x r j | |
199 | @var{r}}. (This is the same command used to jump to a position or | |
200 | restore a frame configuration.) | |
201 | ||
202 | @node Bookmarks | |
203 | @section Bookmarks | |
204 | @cindex bookmarks | |
205 | ||
206 | @dfn{Bookmarks} are somewhat like registers in that they record | |
207 | positions you can jump to. Unlike registers, they have long names, and | |
208 | they persist automatically from one Emacs session to the next. The | |
209 | prototypical use of bookmarks is to record ``where you were reading'' in | |
210 | various files. | |
211 | ||
212 | @table @kbd | |
213 | @item C-x r m @key{RET} | |
214 | Set the bookmark for the visited file, at point. | |
215 | ||
216 | @item C-x r m @var{bookmark} @key{RET} | |
217 | @findex bookmark-set | |
218 | Set the bookmark named @var{bookmark} at point (@code{bookmark-set}). | |
219 | ||
220 | @item C-x r b @var{bookmark} @key{RET} | |
221 | @findex bookmark-jump | |
222 | Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}). | |
223 | ||
224 | @item C-x r l | |
225 | @findex list-bookmarks | |
226 | List all bookmarks (@code{list-bookmarks}). | |
227 | ||
228 | @item M-x bookmark-save | |
229 | @findex bookmark-save | |
230 | Save all the current bookmark values in the default bookmark file. | |
231 | @end table | |
232 | ||
233 | @kindex C-x r m | |
234 | @findex bookmark-set | |
235 | @kindex C-x r b | |
236 | @findex bookmark-jump | |
237 | The prototypical use for bookmarks is to record one current position | |
238 | in each of several files. So the command @kbd{C-x r m}, which sets a | |
239 | bookmark, uses the visited file name as the default for the bookmark | |
240 | name. If you name each bookmark after the file it points to, then you | |
241 | can conveniently revisit any of those files with @kbd{C-x r b}, and move | |
242 | to the position of the bookmark at the same time. | |
243 | ||
244 | @kindex C-x r l | |
245 | To display a list of all your bookmarks in a separate buffer, type | |
246 | @kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer, | |
247 | you can use it to edit your bookmark definitions or annotate the | |
248 | bookmarks. Type @kbd{C-h m} in that buffer for more information about | |
249 | its special editing commands. | |
250 | ||
251 | When you kill Emacs, Emacs offers to save your bookmark values in your | |
252 | default bookmark file, @file{~/.emacs.bmk}, if you have changed any | |
253 | bookmark values. You can also save the bookmarks at any time with the | |
254 | @kbd{M-x bookmark-save} command. The bookmark commands load your | |
255 | default bookmark file automatically. This saving and loading is how | |
256 | bookmarks persist from one Emacs session to the next. | |
257 | ||
258 | @vindex bookmark-save-flag | |
259 | If you set the variable @code{bookmark-save-flag} to 1, then each | |
260 | command that sets a bookmark will also save your bookmarks; this way, | |
261 | you don't lose any bookmark values even if Emacs crashes. (The value, | |
262 | if a number, says how many bookmark modifications should go by between | |
263 | saving.) | |
264 | ||
265 | @vindex bookmark-search-size | |
266 | Bookmark position values are saved with surrounding context, so that | |
267 | @code{bookmark-jump} can find the proper position even if the file is | |
268 | modified slightly. The variable @code{bookmark-search-size} says how | |
269 | many characters of context to record, on each side of the bookmark's | |
270 | position. | |
271 | ||
272 | Here are some additional commands for working with bookmarks: | |
273 | ||
274 | @table @kbd | |
275 | @item M-x bookmark-load @key{RET} @var{filename} @key{RET} | |
276 | @findex bookmark-load | |
277 | Load a file named @var{filename} that contains a list of bookmark | |
278 | values. You can use this command, as well as @code{bookmark-write}, to | |
279 | work with other files of bookmark values in addition to your default | |
280 | bookmark file. | |
281 | ||
282 | @item M-x bookmark-write @key{RET} @var{filename} @key{RET} | |
283 | @findex bookmark-write | |
284 | Save all the current bookmark values in the file @var{filename}. | |
285 | ||
286 | @item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET} | |
287 | @findex bookmark-delete | |
288 | Delete the bookmark named @var{bookmark}. | |
289 | ||
290 | @item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET} | |
291 | @findex bookmark-insert-location | |
292 | Insert in the buffer the name of the file that bookmark @var{bookmark} | |
293 | points to. | |
294 | ||
295 | @item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET} | |
296 | @findex bookmark-insert | |
297 | Insert in the buffer the @emph{contents} of the file that bookmark | |
298 | @var{bookmark} points to. | |
299 | @end table |