man/regs.texi

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