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