save-excursion
The save-excursion function is the fourth and final special form
that we will discuss in this chapter.
In Emacs Lisp programs used for editing, the save-excursion
function is very common. It saves the location of point and mark,
executes the body of the function, and then restores point and mark to
their previous positions if their locations were changed. Its primary
purpose is to keep the user from being surprised and disturbed by
unexpected movement of point or mark.
Before discussing save-excursion, however, it may be useful
first to review what point and mark are in GNU Emacs. Point is
the current location of the cursor. Wherever the cursor
is, that is point. More precisely, on terminals where the cursor
appears to be on top of a character, point is immediately before the
character. In Emacs Lisp, point is an integer. The first character in
a buffer is number one, the second is number two, and so on. The
function point returns the current position of the cursor as a
number. Each buffer has its own value for point.
The mark is another position in the buffer; its value can be set
with a command such as C-SPC (set-mark-command). If
a mark has been set, you can use the command C-x C-x
(exchange-point-and-mark) to cause the cursor to jump to the mark
and set the mark to be the previous position of point. In addition, if
you set another mark, the position of the previous mark is saved in the
mark ring. Many mark positions can be saved this way. You can jump the
cursor to a saved mark by typing C-u C-SPC one or more
times.
The part of the buffer between point and mark is called the
region. Numerous commands work on the region, including
center-region, count-lines-region, kill-region, and
print-region.
The save-excursion special form saves the locations of point and
mark and restores those positions after the code within the body of the
special form is evaluated by the Lisp interpreter. Thus, if point were
in the beginning of a piece of text and some code moved point to the end
of the buffer, the save-excursion would put point back to where
it was before, after the expressions in the body of the function were
evaluated.
In Emacs, a function frequently moves point as part of its internal
workings even though a user would not expect this. For example,
count-lines-region moves point. To prevent the user from being
bothered by jumps that are both unexpected and (from the user's point of
view) unnecessary, save-excursion is often used to keep point and
mark in the location expected by the user. The use of
save-excursion is good housekeeping.
To make sure the house stays clean, save-excursion restores the
values of point and mark even if something goes wrong in the code inside
of it (or, to be more precise and to use the proper jargon, "in case of
abnormal exit"). This feature is very helpful.
In addition to recording the values of point and mark,
save-excursion keeps track of the current buffer, and restores
it, too. This means you can write code that will change the buffer and
have save-excursion switch you back to the original buffer. This
is how save-excursion is used in append-to-buffer.
(See section The Definition of append-to-buffer.)
Go to the first, previous, next, last section, table of contents.