eintr: Point and mark
Point and 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 location of point and
restores this position 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 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
value of point 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 value of point, ‘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’. (
The Definition of ‘append-to-buffer’
append-to-buffer.)
Info Catalog
eintr: save-excursion
eintr: Template for save-excursion