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 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