"Fossies" - the Fresh Open Source Software Archive

Member "emacs-25.3/doc/emacs/regs.texi" (14 Apr 2017, 15127 Bytes) of package /linux/misc/emacs-25.3.tar.xz:


Caution: As a special service "Fossies" has tried to format the requested Texinfo source page into HTML format but that may be not always succeeeded perfectly. Alternatively you can here view or download the uninterpreted Texinfo source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "regs.texi": 25.1_vs_25.2.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Registers

Emacs 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 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 r; r can be a letter (such as ‘a’) or a number (such as ‘1’); case matters, so register ‘a’ is not the same as register ‘A’.

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 r contains, use M-x view-register:

M-x view-register <RET> r

Display a description of what register r contains.

All of the commands that prompt for a register will display a preview window that lists the existing registers (if there are any) after a short delay. To change the length of the delay, customize register-preview-delay. To prevent this display, set that option to nil. You can explicitly request a preview window by pressing C-h or <F1>.

Bookmarks record files and positions in them, so you can 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Saving Positions in Registers

C-x r <SPC> r

Record the position of point and the current buffer in register r (point-to-register).

C-x r j r

Jump to the position and buffer saved in register r (jump-to-register).

Typing C-x r <SPC> (point-to-register), followed by a character r, saves both the position of point and the current buffer in register r. The register retains this information until you store something else in it.

The command C-x r j r switches to the buffer recorded in register 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.

If you use C-x r j to go to a saved position, but the buffer it was saved from has been killed, 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Saving Text in Registers

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.

C-x r s r

Copy region into register r (copy-to-register).

C-x r i r

Insert text from register r (insert-register).

M-x append-to-register <RET> r

Append region to text in register r.

When register r contains text, you can use C-x r + (increment-register) to append to that register. Note that command C-x r + behaves differently if r contains a number. See section Keeping Numbers in Registers.

M-x prepend-to-register <RET> r

Prepend region to text in register r.

C-x r s r stores a copy of the text of the region into the register named 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}. C-u C-x r s r, the same command with a prefix argument, copies the text into register r and deletes the text from the buffer as well; you can think of this as moving the region text into the register.

M-x append-to-register <RET> r appends the copy of the text in the region to the text already stored in the register named r. If invoked with a prefix argument, it deletes the region after appending it to the register. The command prepend-to-register is similar, except that it prepends the region text to the text in the register instead of appending it.

When you are collecting text using append-to-register and prepend-to-register, you may want to separate individual collected pieces using a separator. In that case, configure a 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.

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

C-x r i r inserts in the buffer the text from register r. Normally it leaves point after the text and sets the mark before, without activating it. With a numeric argument, it instead puts point before the text and the mark after.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Saving Rectangles in Registers

A register can contain a rectangle instead of linear text. @xref{Rectangles}, for basic information on how to specify a rectangle in the buffer.

C-x r r r

Copy the region-rectangle into register r (copy-rectangle-to-register). With numeric argument, delete it as well.

C-x r i r

Insert the rectangle stored in register r (if it contains a rectangle) (insert-register).

The C-x r i r (insert-register) command, previously documented in Saving Text in Registers, inserts a rectangle rather than a text string, if the register contains a rectangle.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 Saving Window Configurations in Registers

You can save the window configuration of the selected frame in a register, or even the configuration of all windows in all frames, and restore the configuration later. @xref{Windows}, for information about window configurations.

C-x r w r

Save the state of the selected frame’s windows in register r (window-configuration-to-register).

C-x r f r

Save the state of all frames, including all their windows, in register r (frameset-to-register).

Use C-x r j 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 C-u C-x r j r.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 Keeping Numbers in Registers

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}).

C-u number C-x r n r

Store number into register r (number-to-register).

C-u number C-x r + r

If r contains a number, increment the number in that register by number. Note that command C-x r + (increment-register) behaves differently if r contains text. See section Saving Text in Registers.

C-x r i r

Insert the number from register r into the buffer.

C-x r i is the same command used to insert any other sort of register contents into the buffer. C-x r + with no numeric argument increments the register value by 1; C-x r n with no numeric argument stores zero in the register.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6 Keeping File Names in Registers

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 into register r:

(set-register r '(file . name))

For example,

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

puts the file name shown in register ‘z’.

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7 Keyboard Macro Registers

If you need to execute a keyboard macro (@pxref{Keyboard Macros}) frequently, it is more convenient to put it in a register or save it (@pxref{Save Keyboard Macro}). C-x C-k x r (kmacro-to-register) stores the last keyboard macro in register r.

To execute the keyboard macro in register r, type C-x r j r. (This is the same command used to jump to a position or restore a frameset.)


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.8 Bookmarks

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.

C-x r m <RET>

Set the bookmark for the visited file, at point.

C-x r m bookmark <RET>

Set the bookmark named bookmark at point (bookmark-set).

C-x r M bookmark <RET>

Like C-x r m, but don’t overwrite an existing bookmark.

C-x r b bookmark <RET>

Jump to the bookmark named bookmark (bookmark-jump).

C-x r l

List all bookmarks (list-bookmarks).

M-x bookmark-save

Save all the current bookmark values in the default bookmark file.

The prototypical use for bookmarks is to record one current position in each of several files. So the command 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 C-x r b, and move to the position of the bookmark at the same time.

The command C-x r M (bookmark-set-no-overwrite) works like C-x r m, but it signals an error if the specified bookmark already exists, instead of overwriting it.

To display a list of all your bookmarks in a separate buffer, type C-x r l (list-bookmarks). If you switch to that buffer, you can use it to edit your bookmark definitions or annotate the bookmarks. Type C-h m in the bookmark buffer for more information about its special editing commands.

When you kill Emacs, Emacs saves your bookmarks, if you have changed any bookmark values. You can also save the bookmarks at any time with the M-x bookmark-save command. Bookmarks are saved to the file ‘~/.emacs.d/bookmarks’ (for compatibility with older versions of Emacs, if you have a file named ‘~/.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.

If you set the variable bookmark-save-flag to 1, each command that sets a bookmark will also save your bookmarks; this way, you don’t lose any bookmark values even if Emacs crashes. The value, if a number, says how many bookmark modifications should go by between saving. If you set this variable to nil, Emacs only saves bookmarks if you explicitly use M-x bookmark-save.

The variable bookmark-default-file specifies the file in which to save bookmarks by default.

Bookmark position values are saved with surrounding context, so that bookmark-jump can find the proper position even if the file is modified slightly. The variable bookmark-search-size says how many characters of context to record on each side of the bookmark’s position.

Here are some additional commands for working with bookmarks:

M-x bookmark-load <RET> filename <RET>

Load a file named filename that contains a list of bookmark values. You can use this command, as well as bookmark-write, to work with other files of bookmark values in addition to your default bookmark file.

M-x bookmark-write <RET> filename <RET>

Save all the current bookmark values in the file filename.

M-x bookmark-delete <RET> bookmark <RET>

Delete the bookmark named bookmark.

M-x bookmark-insert-location <RET> bookmark <RET>

Insert in the buffer the name of the file that bookmark bookmark points to.

M-x bookmark-insert <RET> bookmark <RET>

Insert in the buffer the contents of the file that bookmark bookmark points to.


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on October 2, 2017 using texi2html.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated on October 2, 2017 using texi2html.