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