regs.texi 13.3 KB
Newer Older
Dave Love's avatar
#  
Dave Love committed
1
@c This is part of the Emacs manual.
2
@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012
3
@c   Free Software Foundation, Inc.
Dave Love's avatar
#  
Dave Love committed
4
@c See file emacs.texi for copying conditions.
5
@node Registers
Dave Love's avatar
#  
Dave Love committed
6 7 8
@chapter Registers
@cindex registers

Richard M. Stallman's avatar
Richard M. Stallman committed
9 10 11
  Emacs @dfn{registers} are compartments where you can save text,
rectangles, positions, and other things for later use.  Once you save
text or a rectangle in a register, you can copy it into the buffer
12 13 14 15 16 17 18
once, or many times; once you save a position in a register, you can
jump back to that position once, or many times.

  Each register has a name that consists of a single character, which
we will denote by @var{r}; @var{r} can be a letter (such as @samp{a})
or a number (such as @samp{1}); case matters, so register @samp{a} is
not the same as register @samp{A}.
Dave Love's avatar
#  
Dave Love committed
19 20

@findex view-register
21 22 23 24 25
  A register can store a position, a piece of text, a rectangle, a
number, a window configuration, or a file name, but only one thing at
any given time.  Whatever you store in a register remains there until
you store something else in that register.  To see what register
@var{r} contains, use @kbd{M-x view-register}:
Dave Love's avatar
#  
Dave Love committed
26 27 28 29 30 31

@table @kbd
@item M-x view-register @key{RET} @var{r}
Display a description of what register @var{r} contains.
@end table

32
  @dfn{Bookmarks} record files and positions in them, so you can
Chong Yidong's avatar
Chong Yidong committed
33 34 35
return to those positions when you look at the file again.  Bookmarks
are similar in spirit to registers, so they are also documented in
this chapter.
36

Dave Love's avatar
#  
Dave Love committed
37
@menu
38 39 40 41 42 43 44
* Position Registers::       Saving positions in registers.
* Text Registers::           Saving text in registers.
* Rectangle Registers::      Saving rectangles in registers.
* Configuration Registers::  Saving window configurations in registers.
* Number Registers::         Numbers in registers.
* File Registers::           File names in registers.
* Bookmarks::                Bookmarks are like registers, but persistent.
Dave Love's avatar
#  
Dave Love committed
45 46
@end menu

47
@node Position Registers
Dave Love's avatar
#  
Dave Love committed
48
@section Saving Positions in Registers
49
@cindex saving position in a register
Dave Love's avatar
#  
Dave Love committed
50 51 52

@table @kbd
@item C-x r @key{SPC} @var{r}
53 54
Record the position of point and the current buffer in register
@var{r} (@code{point-to-register}).
Dave Love's avatar
#  
Dave Love committed
55
@item C-x r j @var{r}
56 57
Jump to the position and buffer saved in register @var{r}
(@code{jump-to-register}).
Dave Love's avatar
#  
Dave Love committed
58 59 60 61
@end table

@kindex C-x r SPC
@findex point-to-register
62 63 64 65
  Typing @kbd{C-x r @key{SPC}} (@code{point-to-register}), followed by
a character @kbd{@var{r}}, saves both the position of point and the
current buffer in register @var{r}.  The register retains this
information until you store something else in it.
Dave Love's avatar
#  
Dave Love committed
66 67 68

@kindex C-x r j
@findex jump-to-register
69 70 71 72
  The command @kbd{C-x r j @var{r}} switches to the buffer recorded in
register @var{r}, and moves point to the recorded position.  The
contents of the register are not changed, so you can jump to the saved
position any number of times.
Dave Love's avatar
#  
Dave Love committed
73 74 75 76 77 78

  If you use @kbd{C-x r j} to go to a saved position, but the buffer it
was saved from has been killed, @kbd{C-x r j} tries to create the buffer
again by visiting the same file.  Of course, this works only for buffers
that were visiting files.

79
@node Text Registers
Dave Love's avatar
#  
Dave Love committed
80
@section Saving Text in Registers
81
@cindex saving text in a register
Dave Love's avatar
#  
Dave Love committed
82 83 84 85 86 87 88 89 90 91 92

  When you want to insert a copy of the same piece of text several
times, it may be inconvenient to yank it from the kill ring, since each
subsequent kill moves that entry further down the ring.  An alternative
is to store the text in a register and later retrieve it.

@table @kbd
@item C-x r s @var{r}
Copy region into register @var{r} (@code{copy-to-register}).
@item C-x r i @var{r}
Insert text from register @var{r} (@code{insert-register}).
93 94
@item M-x append-to-register @key{RET} @var{r}
Append region to text in register @var{r}.
95 96 97 98 99 100 101

@kindex C-x r +
When register @var{r} contains text, you can use @kbd{C-x r +}
(@code{increment-register}) to append to that register.  Note that
command @kbd{C-x r +} behaves differently if @var{r} contains a
number.  @xref{Number Registers}.

102 103
@item M-x prepend-to-register @key{RET} @var{r}
Prepend region to text in register @var{r}.
Dave Love's avatar
#  
Dave Love committed
104 105 106 107
@end table

@kindex C-x r s
@findex copy-to-register
Richard M. Stallman's avatar
Richard M. Stallman committed
108
  @kbd{C-x r s @var{r}} stores a copy of the text of the region into
109 110 111 112 113 114
the register named @var{r}.  If the mark is inactive, Emacs first
reactivates the mark where it was last set.  The mark is deactivated
at the end of this command.  @xref{Mark}.  @kbd{C-u C-x r s @var{r}},
the same command with a prefix argument, copies the text into register
@var{r} and deletes the text from the buffer as well; you can think of
this as ``moving'' the region text into the register.
Dave Love's avatar
#  
Dave Love committed
115

116 117 118 119
@findex append-to-register
@findex prepend-to-register
  @kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of
the text in the region to the text already stored in the register
120
named @var{r}.  If invoked with a prefix argument, it deletes the
121 122
region after appending it to the register.  The command
@code{prepend-to-register} is similar, except that it @emph{prepends}
123
the region text to the text in the register instead of
124
@emph{appending} it.
125

126 127 128 129 130 131 132 133 134 135 136 137 138
@vindex register-separator
  When you are collecting text using @code{append-to-register} and
@code{prepend-to-register}, you may want to separate individual
collected pieces using a separator.  In that case, configure a
@code{register-separator} and store the separator text in to that
register.  For example, to get double newlines as text separator
during the collection process, you can use the following setting.

@example
(setq register-separator ?+)
(set-register register-separator "\n\n")
@end example

139 140
@kindex C-x r i
@findex insert-register
Dave Love's avatar
#  
Dave Love committed
141
  @kbd{C-x r i @var{r}} inserts in the buffer the text from register
Chong Yidong's avatar
Chong Yidong committed
142 143 144
@var{r}.  Normally it leaves point before the text and sets the mark
after, without activating it.  With a numeric argument, it instead
puts point after the text and the mark before.
Dave Love's avatar
#  
Dave Love committed
145

146
@node Rectangle Registers
Dave Love's avatar
#  
Dave Love committed
147
@section Saving Rectangles in Registers
148
@cindex saving rectangle in a register
Dave Love's avatar
#  
Dave Love committed
149

150 151 152
  A register can contain a rectangle instead of linear text.
@xref{Rectangles}, for basic information on how to specify a rectangle
in the buffer.
Dave Love's avatar
#  
Dave Love committed
153 154 155 156 157 158 159 160 161 162 163 164 165

@table @kbd
@findex copy-rectangle-to-register
@kindex C-x r r
@item C-x r r @var{r}
Copy the region-rectangle into register @var{r}
(@code{copy-rectangle-to-register}).  With numeric argument, delete it as
well.
@item C-x r i @var{r}
Insert the rectangle stored in register @var{r} (if it contains a
rectangle) (@code{insert-register}).
@end table

Chong Yidong's avatar
Chong Yidong committed
166 167
  The @kbd{C-x r i @var{r}} (@code{insert-register}) command,
previously documented in @ref{Text Registers}, inserts a rectangle
Juanma Barranquero's avatar
Juanma Barranquero committed
168
rather than a text string, if the register contains a rectangle.
Dave Love's avatar
#  
Dave Love committed
169

170
@node Configuration Registers
Dave Love's avatar
#  
Dave Love committed
171
@section Saving Window Configurations in Registers
172
@cindex saving window configuration in a register
Dave Love's avatar
#  
Dave Love committed
173 174 175 176 177 178 179

@findex window-configuration-to-register
@findex frame-configuration-to-register
@kindex C-x r w
@kindex C-x r f
  You can save the window configuration of the selected frame in a
register, or even the configuration of all windows in all frames, and
180 181
restore the configuration later.  @xref{Windows}, for information
about window configurations.
Dave Love's avatar
#  
Dave Love committed
182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197

@table @kbd
@item C-x r w @var{r}
Save the state of the selected frame's windows in register @var{r}
(@code{window-configuration-to-register}).
@item C-x r f @var{r}
Save the state of all frames, including all their windows, in register
@var{r} (@code{frame-configuration-to-register}).
@end table

  Use @kbd{C-x r j @var{r}} to restore a window or frame configuration.
This is the same command used to restore a cursor position.  When you
restore a frame configuration, any existing frames not included in the
configuration become invisible.  If you wish to delete these frames
instead, use @kbd{C-u C-x r j @var{r}}.

198
@node Number Registers
Dave Love's avatar
#  
Dave Love committed
199
@section Keeping Numbers in Registers
200
@cindex saving number in a register
Dave Love's avatar
#  
Dave Love committed
201 202 203 204 205 206

  There are commands to store a number in a register, to insert
the number in the buffer in decimal, and to increment it.  These commands
can be useful in keyboard macros (@pxref{Keyboard Macros}).

@table @kbd
Richard M. Stallman's avatar
Richard M. Stallman committed
207
@item C-u @var{number} C-x r n @var{r}
Dave Love's avatar
#  
Dave Love committed
208 209
@kindex C-x r n
@findex number-to-register
Richard M. Stallman's avatar
Richard M. Stallman committed
210 211
Store @var{number} into register @var{r} (@code{number-to-register}).
@item C-u @var{number} C-x r + @var{r}
Dave Love's avatar
#  
Dave Love committed
212 213
@kindex C-x r +
@findex increment-register
214 215 216 217
If @var{r} contains a number, increment the number in that register by
@var{number}.  Note that command @kbd{C-x r +}
(@code{increment-register}) behaves differently if @var{r} contains
text.  @xref{Text Registers}.
218
@item C-x r i @var{r}
Richard M. Stallman's avatar
Richard M. Stallman committed
219
Insert the number from register @var{r} into the buffer.
Dave Love's avatar
#  
Dave Love committed
220 221
@end table

222
  @kbd{C-x r i} is the same command used to insert any other sort of
Richard M. Stallman's avatar
Richard M. Stallman committed
223 224 225
register contents into the buffer.  @kbd{C-x r +} with no numeric
argument increments the register value by 1; @kbd{C-x r n} with no
numeric argument stores zero in the register.
Dave Love's avatar
#  
Dave Love committed
226

227
@node File Registers
Dave Love's avatar
#  
Dave Love committed
228
@section Keeping File Names in Registers
Pavel Janík's avatar
Pavel Janík committed
229
@cindex saving file name in a register
Dave Love's avatar
#  
Dave Love committed
230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299

  If you visit certain file names frequently, you can visit them more
conveniently if you put their names in registers.  Here's the Lisp code
used to put a file name in a register:

@smallexample
(set-register ?@var{r} '(file . @var{name}))
@end smallexample

@need 3000
@noindent
For example,

@smallexample
(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))
@end smallexample

@noindent
puts the file name shown in register @samp{z}.

  To visit the file whose name is in register @var{r}, type @kbd{C-x r j
@var{r}}.  (This is the same command used to jump to a position or
restore a frame configuration.)

@node Bookmarks
@section Bookmarks
@cindex bookmarks

  @dfn{Bookmarks} are somewhat like registers in that they record
positions you can jump to.  Unlike registers, they have long names, and
they persist automatically from one Emacs session to the next.  The
prototypical use of bookmarks is to record ``where you were reading'' in
various files.

@table @kbd
@item C-x r m @key{RET}
Set the bookmark for the visited file, at point.

@item C-x r m @var{bookmark} @key{RET}
@findex bookmark-set
Set the bookmark named @var{bookmark} at point (@code{bookmark-set}).

@item C-x r b @var{bookmark} @key{RET}
@findex bookmark-jump
Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}).

@item C-x r l
@findex list-bookmarks
List all bookmarks (@code{list-bookmarks}).

@item M-x bookmark-save
@findex bookmark-save
Save all the current bookmark values in the default bookmark file.
@end table

@kindex C-x r m
@findex bookmark-set
@kindex C-x r b
@findex bookmark-jump
  The prototypical use for bookmarks is to record one current position
in each of several files.  So the command @kbd{C-x r m}, which sets a
bookmark, uses the visited file name as the default for the bookmark
name.  If you name each bookmark after the file it points to, then you
can conveniently revisit any of those files with @kbd{C-x r b}, and move
to the position of the bookmark at the same time.

@kindex C-x r l
  To display a list of all your bookmarks in a separate buffer, type
@kbd{C-x r l} (@code{list-bookmarks}).  If you switch to that buffer,
you can use it to edit your bookmark definitions or annotate the
Richard M. Stallman's avatar
Richard M. Stallman committed
300 301
bookmarks.  Type @kbd{C-h m} in the bookmark buffer for more
information about its special editing commands.
Dave Love's avatar
#  
Dave Love committed
302

303
  When you kill Emacs, Emacs saves your bookmarks, if
Chong Yidong's avatar
Chong Yidong committed
304 305 306 307 308 309 310
you have changed any bookmark values.  You can also save the bookmarks
at any time with the @kbd{M-x bookmark-save} command.  Bookmarks are
saved to the file @file{~/.emacs.d/bookmarks} (for compatibility with
older versions of Emacs, if you have a file named @file{~/.emacs.bmk},
that is used instead).  The bookmark commands load your default
bookmark file automatically.  This saving and loading is how bookmarks
persist from one Emacs session to the next.
Dave Love's avatar
#  
Dave Love committed
311 312

@vindex bookmark-save-flag
313 314
  If you set the variable @code{bookmark-save-flag} to 1, each command
that sets a bookmark will also save your bookmarks; this way, you
315
don't lose any bookmark values even if Emacs crashes.  The value, if
316
a number, says how many bookmark modifications should go by between
317 318
saving.  If you set this variable to @code{nil}, Emacs only
saves bookmarks if you explicitly use @kbd{M-x bookmark-save}.
Dave Love's avatar
#  
Dave Love committed
319 320 321 322 323

@vindex bookmark-search-size
  Bookmark position values are saved with surrounding context, so that
@code{bookmark-jump} can find the proper position even if the file is
modified slightly.  The variable @code{bookmark-search-size} says how
324
many characters of context to record on each side of the bookmark's
Dave Love's avatar
#  
Dave Love committed
325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354
position.

  Here are some additional commands for working with bookmarks:

@table @kbd
@item M-x bookmark-load @key{RET} @var{filename} @key{RET}
@findex bookmark-load
Load a file named @var{filename} that contains a list of bookmark
values.  You can use this command, as well as @code{bookmark-write}, to
work with other files of bookmark values in addition to your default
bookmark file.

@item M-x bookmark-write @key{RET} @var{filename} @key{RET}
@findex bookmark-write
Save all the current bookmark values in the file @var{filename}.

@item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET}
@findex bookmark-delete
Delete the bookmark named @var{bookmark}.

@item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET}
@findex bookmark-insert-location
Insert in the buffer the name of the file that bookmark @var{bookmark}
points to.

@item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET}
@findex bookmark-insert
Insert in the buffer the @emph{contents} of the file that bookmark
@var{bookmark} points to.
@end table