doc/emacs/regs.texi

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