001: @c This is part of the Emacs manual.
002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software
003: @c Foundation, Inc.
004: @c See file emacs.texi for copying conditions.
005: @node Registers
006: @chapter Registers
007: @cindex registers
008: 
009:   Emacs @dfn{registers} are compartments where you can save text,
010: rectangles, positions, and other things for later use.  Once you save
011: text or a rectangle in a register, you can copy it into the buffer
012: once or many times; once you save a position in a register, you can
013: jump back to that position once or many times.
014: 
015:   Each register has a name that consists of a single character, which
016: we will denote by @var{r}; @var{r} can be a letter (such as @samp{a})
017: or a number (such as @samp{1}); case matters, so register @samp{a} is
018: not the same as register @samp{A}.  You can also set a register in
019: non-alphanumeric characters, for instance @samp{*} or @samp{C-d}.
020: Note, it's not possible to set a register in @samp{C-g} or @samp{ESC},
021: because these keys are reserved for quitting (@pxref{Quitting}).
022: 
023: @findex view-register
024:   A register can store a position, a piece of text, a rectangle, a
025: number, a window configuration, or a file name, but only one thing at
026: any given time.  Whatever you store in a register remains there until
027: you store something else in that register.  To see what register
028: @var{r} contains, use @kbd{M-x view-register}:
029: 
030: @table @kbd
031: @item M-x view-register @key{RET} @var{r}
032: Display a description of what register @var{r} contains.
033: @end table
034: 
035: @vindex register-preview-delay
036: @cindex preview of registers
037:   All of the commands that prompt for a register will display a
038: preview window that lists the existing registers (if there are
039: any) after a short delay.  To change the length of the delay,
040: customize @code{register-preview-delay}.  To prevent this display, set
041: that option to @code{nil}.  You can explicitly request a preview
042: window by pressing @kbd{C-h} or @key{F1}.
043: 
044:   @dfn{Bookmarks} record files and positions in them, so you can
045: return to those positions when you look at the file again.  Bookmarks
046: are similar in spirit to registers, so they are also documented in
047: this chapter.
048: 
049: @menu
050: * Position Registers::       Saving positions in registers.
051: * Text Registers::           Saving text in registers.
052: * Rectangle Registers::      Saving rectangles in registers.
053: * Configuration Registers::  Saving window configurations in registers.
054: * Number Registers::         Numbers in registers.
055: * File Registers::           File names in registers.
056: * Keyboard Macro Registers:: Keyboard macros in registers.
057: * Bookmarks::                Bookmarks are like registers, but persistent.
058: @end menu
059: 
060: @node Position Registers
061: @section Saving Positions in Registers
062: @cindex saving position in a register
063: 
064: @table @kbd
065: @item C-x r @key{SPC} @var{r}
066: Record the position of point and the current buffer in register
067: @var{r} (@code{point-to-register}).
068: @item C-x r j @var{r}
069: Jump to the position and buffer saved in register @var{r}
070: (@code{jump-to-register}).
071: @end table
072: 
073: @kindex C-x r SPC
074: @findex point-to-register
075:   Typing @kbd{C-x r @key{SPC}} (@code{point-to-register}), followed by
076: a character @kbd{@var{r}}, saves both the position of point and the
077: current buffer in register @var{r}.  The register retains this
078: information until you store something else in it.
079: 
080: @kindex C-x r j
081: @findex jump-to-register
082:   The command @kbd{C-x r j @var{r}} switches to the buffer recorded in
083: register @var{r}, pushes a mark, and moves point to the recorded
084: position.  (The mark is not pushed if point was already at the
085: recorded position, or in successive calls to the command.)  The
086: contents of the register are not changed, so you can jump to the saved
087: position any number of times.
088: 
089:   If you use @kbd{C-x r j} to go to a saved position, but the buffer it
090: was saved from has been killed, @kbd{C-x r j} tries to create the buffer
091: again by visiting the same file.  Of course, this works only for buffers
092: that were visiting files.
093: 
094: @node Text Registers
095: @section Saving Text in Registers
096: @cindex saving text in a register
097: 
098:   When you want to insert a copy of the same piece of text several
099: times, it may be inconvenient to yank it from the kill ring, since each
100: subsequent kill moves that entry further down the ring.  An alternative
101: is to store the text in a register and later retrieve it.
102: 
103: @table @kbd
104: @item C-x r s @var{r}
105: Copy region into register @var{r} (@code{copy-to-register}).
106: @item C-x r i @var{r}
107: Insert text from register @var{r} (@code{insert-register}).
108: @item M-x append-to-register @key{RET} @var{r}
109: Append region to text in register @var{r}.
110: 
111: When register @var{r} contains text, you can use @kbd{C-x r +}
112: (@code{increment-register}) to append to that register.  Note that
113: command @kbd{C-x r +} behaves differently if @var{r} contains a
114: number.  @xref{Number Registers}.
115: 
116: @item M-x prepend-to-register @key{RET} @var{r}
117: Prepend region to text in register @var{r}.
118: @end table
119: 
120: @kindex C-x r s
121: @findex copy-to-register
122:   @kbd{C-x r s @var{r}} stores a copy of the text of the region into
123: the register named @var{r}.  If the mark is inactive, Emacs first
124: reactivates the mark where it was last set.  The mark is deactivated
125: at the end of this command.  @xref{Mark}.  @kbd{C-u C-x r s @var{r}},
126: the same command with a prefix argument, copies the text into register
127: @var{r} and deletes the text from the buffer as well; you can think of
128: this as moving the region text into the register.
129: 
130: @findex append-to-register
131: @findex prepend-to-register
132:   @kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of
133: the text in the region to the text already stored in the register
134: named @var{r}.  If invoked with a prefix argument, it deletes the
135: region after appending it to the register.  The command
136: @code{prepend-to-register} is similar, except that it @emph{prepends}
137: the region text to the text in the register instead of
138: @emph{appending} it.
139: 
140: @vindex register-separator
141:   When you are collecting text using @code{append-to-register} and
142: @code{prepend-to-register}, you may want to separate individual
143: collected pieces using a separator.  In that case, configure a
144: @code{register-separator} and store the separator text in to that
145: register.  For example, to get double newlines as text separator
146: during the collection process, you can use the following setting.
147: 
148: @example
149: (setq register-separator ?+)
150: (set-register register-separator "\n\n")
151: @end example
152: 
153: @kindex C-x r i
154: @findex insert-register
155:   @kbd{C-x r i @var{r}} inserts in the buffer the text from register
156: @var{r}.  Normally it leaves point after the text and sets the mark
157: before, without activating it.  With a numeric argument, it instead
158: puts point before the text and the mark after.
159: 
160: @node Rectangle Registers
161: @section Saving Rectangles in Registers
162: @cindex saving rectangle in a register
163: 
164:   A register can contain a rectangle instead of linear text.
165: @xref{Rectangles}, for basic information on how to specify a rectangle
166: in the buffer.
167: 
168: @table @kbd
169: @findex copy-rectangle-to-register
170: @kindex C-x r r
171: @item C-x r r @var{r}
172: Copy the region-rectangle into register @var{r}
173: (@code{copy-rectangle-to-register}).  With numeric argument, delete it as
174: well.
175: @item C-x r i @var{r}
176: Insert the rectangle stored in register @var{r} (if it contains a
177: rectangle) (@code{insert-register}).
178: @end table
179: 
180:   The @kbd{C-x r i @var{r}} (@code{insert-register}) command,
181: previously documented in @ref{Text Registers}, inserts a rectangle
182: rather than a text string, if the register contains a rectangle.
183: 
184: @node Configuration Registers
185: @section Saving Window Configurations in Registers
186: @cindex saving window configuration in a register
187: 
188: @findex window-configuration-to-register
189: @findex frameset-to-register
190: @kindex C-x r w
191: @kindex C-x r f
192:   You can save the window configuration of the selected frame in a
193: register, or even the configuration of all windows in all frames, and
194: restore the configuration later.  @xref{Windows}, for information
195: about window configurations.
196: 
197: @table @kbd
198: @item C-x r w @var{r}
199: Save the state of the selected frame's windows in register @var{r}
200: (@code{window-configuration-to-register}).
201: @item C-x r f @var{r}
202: Save the state of all frames, including all their windows, in register
203: @var{r} (@code{frameset-to-register}).
204: @end table
205: 
206:   Use @kbd{C-x r j @var{r}} to restore a window or frame configuration.
207: This is the same command used to restore a cursor position.  When you
208: restore a frame configuration, any existing frames not included in the
209: configuration become invisible.  If you wish to delete these frames
210: instead, use @kbd{C-u C-x r j @var{r}}.
211: 
212: @node Number Registers
213: @section Keeping Numbers in Registers
214: @cindex saving number in a register
215: 
216:   There are commands to store a number in a register, to insert
217: the number in the buffer in decimal, and to increment it.  These commands
218: can be useful in keyboard macros (@pxref{Keyboard Macros}).
219: 
220: @table @kbd
221: @item C-u @var{number} C-x r n @var{r}
222: @kindex C-x r n
223: @findex number-to-register
224: Store @var{number} into register @var{r} (@code{number-to-register}).
225: @item C-u @var{number} C-x r + @var{r}
226: @kindex C-x r +
227: @findex increment-register
228: If @var{r} contains a number, increment the number in that register by
229: @var{number}.  Note that command @kbd{C-x r +}
230: (@code{increment-register}) behaves differently if @var{r} contains
231: text.  @xref{Text Registers}.
232: @item C-x r i @var{r}
233: Insert the number from register @var{r} into the buffer.
234: @end table
235: 
236:   @kbd{C-x r i} is the same command used to insert any other sort of
237: register contents into the buffer.  @kbd{C-x r +} with no numeric
238: argument increments the register value by 1; @kbd{C-x r n} with no
239: numeric argument stores zero in the register.
240: 
241: @node File Registers
242: @section Keeping File Names in Registers
243: @cindex saving file name in a register
244: 
245:   If you visit certain file names frequently, you can visit them more
246: conveniently if you put their names in registers.  Here's the Lisp code
247: used to put a file @var{name} into register @var{r}:
248: 
249: @smallexample
250: (set-register @var{r} '(file . @var{name}))
251: @end smallexample
252: 
253: @need 3000
254: @noindent
255: For example,
256: 
257: @smallexample
258: (set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))
259: @end smallexample
260: 
261: @noindent
262: puts the file name shown in register @samp{z}.
263: 
264:   To visit the file whose name is in register @var{r}, type @kbd{C-x r j
265: @var{r}}.  (This is the same command used to jump to a position or
266: restore a frame configuration.)
267: 
268: @node Keyboard Macro Registers
269: @section Keyboard Macro Registers
270: @cindex saving keyboard macro in a register
271: @cindex keyboard macros, in registers
272: 
273: @kindex C-x C-k x
274: @findex kmacro-to-register
275:   If you need to execute a keyboard macro (@pxref{Keyboard Macros})
276: frequently, it is more convenient to put it in a register or save it
277: (@pxref{Save Keyboard Macro}).  @kbd{C-x C-k x @var{r}}
278: (@code{kmacro-to-register}) stores the last keyboard macro in register
279: @var{r}.
280: 
281:   To execute the keyboard macro in register @var{r}, type @kbd{C-x r j
282: @var{r}}.  (This is the same command used to jump to a position or
283: restore a frameset.)
284: 
285: @node Bookmarks
286: @section Bookmarks
287: @cindex bookmarks
288: 
289:   @dfn{Bookmarks} are somewhat like registers in that they record
290: positions you can jump to.  Unlike registers, they have long names, and
291: they persist automatically from one Emacs session to the next.  The
292: prototypical use of bookmarks is to record where you were reading in
293: various files.
294: 
295: @table @kbd
296: @item C-x r m @key{RET}
297: Set the bookmark for the visited file, at point.
298: 
299: @item C-x r m @var{bookmark} @key{RET}
300: Set the bookmark named @var{bookmark} at point (@code{bookmark-set}).
301: 
302: @item C-x r M @var{bookmark} @key{RET}
303: Like @kbd{C-x r m}, but don't overwrite an existing bookmark.
304: 
305: @item C-x r b @var{bookmark} @key{RET}
306: Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}).
307: 
308: @item C-x r l
309: List all bookmarks (@code{list-bookmarks}).
310: 
311: @item M-x bookmark-save
312: Save all the current bookmark values in the default bookmark file.
313: @end table
314: 
315: @kindex C-x r m
316: @findex bookmark-set
317: @kindex C-x r b
318: @findex bookmark-jump
319:   To record the current position in the visited file, use the command
320: @kbd{C-x r m}, which sets a bookmark using the visited file name as
321: the default for the bookmark name.  If you name each bookmark after
322: the file it points to, then you can conveniently revisit any of those
323: files with @kbd{C-x r b}, and move to the position of the bookmark at
324: the same time.
325: 
326: @kindex C-x r M
327: @findex bookmark-set-no-overwrite
328:   The command @kbd{C-x r M} (@code{bookmark-set-no-overwrite}) works
329: like @w{@kbd{C-x r m}}, but it signals an error if the specified
330: bookmark already exists, instead of overwriting it.
331: 
332: @kindex C-x r l
333: @findex list-bookmarks
334:   To display a list of all your bookmarks in a separate buffer, type
335: @kbd{C-x r l} (@code{list-bookmarks}).  If you switch to that buffer,
336: you can use it to edit your bookmark definitions or annotate the
337: bookmarks.  Type @kbd{C-h m} in the bookmark buffer for more
338: information about its special editing commands.
339: 
340: @findex bookmark-save
341:   When you kill Emacs, Emacs saves your bookmarks, if
342: you have changed any bookmark values.  You can also save the bookmarks
343: at any time with the @kbd{M-x bookmark-save} command.  Bookmarks are
344: saved to the file @file{~/.emacs.d/bookmarks} (for compatibility with
345: older versions of Emacs, if you have a file named @file{~/.emacs.bmk},
346: that is used instead).  The bookmark commands load your default
347: bookmark file automatically.  This saving and loading is how bookmarks
348: persist from one Emacs session to the next.
349: 
350: @vindex bookmark-save-flag
351:   If you set the variable @code{bookmark-save-flag} to 1, each command
352: that sets a bookmark will also save your bookmarks; this way, you
353: don't lose any bookmark values even if Emacs crashes.  The value, if
354: a number, says how many bookmark modifications should go by between
355: saving.  If you set this variable to @code{nil}, Emacs only
356: saves bookmarks if you explicitly use @kbd{M-x bookmark-save}.
357: 
358: @vindex bookmark-default-file
359:   The variable @code{bookmark-default-file} specifies the file in
360: which to save bookmarks by default.
361: 
362: @vindex bookmark-search-size
363:   Bookmark position values are saved with surrounding context, so that
364: @code{bookmark-jump} can find the proper position even if the file is
365: modified slightly.  The variable @code{bookmark-search-size} says how
366: many characters of context to record on each side of the bookmark's
367: position.
368: 
369:   Here are some additional commands for working with bookmarks:
370: 
371: @table @kbd
372: @item M-x bookmark-load @key{RET} @var{filename} @key{RET}
373: @findex bookmark-load
374: Load a file named @var{filename} that contains a list of bookmark
375: values.  You can use this command, as well as @code{bookmark-write}, to
376: work with other files of bookmark values in addition to your default
377: bookmark file.
378: 
379: @item M-x bookmark-write @key{RET} @var{filename} @key{RET}
380: @findex bookmark-write
381: Save all the current bookmark values in the file @var{filename}.
382: 
383: @item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET}
384: @findex bookmark-delete
385: Delete the bookmark named @var{bookmark}.
386: 
387: @item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET}
388: @findex bookmark-insert-location
389: Insert in the buffer the name of the file that bookmark @var{bookmark}
390: points to.
391: 
392: @item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET}
393: @findex bookmark-insert
394: Insert in the buffer the @emph{contents} of the file that bookmark
395: @var{bookmark} points to.
396: @end table
397: