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