A position is the index of a character in the text of a buffer. More precisely, a position identifies the place between two characters (or before the first character, or after the last character), so we can speak of the character before or after a given position. However, we often speak of the character "at" a position, meaning the character after that position.
Positions are usually represented as integers starting from 1, but can also be represented as markers---special objects that relocate automatically when text is inserted or deleted so they stay with the surrounding characters. See section Markers.
Point is a special buffer position used by many editing commands, including the self-inserting typed characters and text insertion functions. Other commands move point through the text to allow editing and insertion at different places.
Like other positions, point designates a place between two characters (or before the first character, or after the last character), rather than a particular character. Usually terminals display the cursor over the character that immediately follows point; point is actually before the character on which the cursor sits.
The value of point is a number between 1 and the buffer size plus 1. If narrowing is in effect (see section Narrowing), then point is constrained to fall within the accessible portion of the buffer (possibly at one end of it).
Each buffer has its own value of point, which is independent of the value of point in other buffers. Each window also has a value of point, which is independent of the value of point in other windows on the same buffer. This is why point can have different values in various windows that display the same buffer. When a buffer appears in only one window, the buffer's point and the window's point normally have the same value, so the distinction is rarely important. See section Windows and Point, for more details.
(point)
=> 175
(1+ (buffer-size)), unless narrowing is in effect, in
which case it is the position of the end of the region that you
narrowed to. (See section Narrowing).
(point-min) if flag is less than 1,
(point-max) otherwise. The argument flag
must be a number.
point-max
returns a value one larger than this.
(buffer-size)
=> 35
(point-max)
=> 36
Motion functions change the value of point, either relative to the current value of point, relative to the beginning or end of the buffer, or relative to the edges of the selected window. See section Point.
These functions move point based on a count of characters.
goto-char is the fundamental primitive; the other
functions use that.
If narrowing is in effect, position still counts from
the beginning of the buffer, but point cannot go outside the
accessible portion. If position is out of range,
goto-char moves point to the beginning or the end of
the accessible portion.
When this function is called interactively, position is the numeric prefix argument, if provided; otherwise it is read from the minibuffer.
goto-char returns position.
beginning-of-buffer or
end-of-buffer. In an interactive call, count is the numeric prefix argument.
beginning-of-buffer or
end-of-buffer. In an interactive call, count is the numeric prefix argument.
These functions for parsing words use the syntax table to decide whether a given character is part of a word. See section Syntax Tables.
If it is possible to move count words, without being
stopped by the buffer boundary (except perhaps after the last
word), the value is t. Otherwise, the return value is
nil and point stops at the buffer boundary.
In an interactive call, count is set to the numeric prefix argument.
forward-word, except that it moves backward until
encountering the front of a word, rather than forward. In an interactive call, count is set to the numeric prefix argument.
This function is rarely used in programs, as it is more
efficient to call forward-word with a negative
argument.
forward-word and everything that uses it.
If it is non-nil, then characters in the "escape" and
"character quote" syntax classes count as part of words. Otherwise,
they do not.
To move point to the beginning of the buffer, write:
(goto-char (point-min))
Likewise, to move to the end of the buffer, use:
(goto-char (point-max))
Here are two commands that users use to do these things. They are documented here to warn you not to use them in Lisp programs, because they set the mark and display messages in the echo area.
nil, then it
puts point n tenths of the way from the beginning of the
buffer. In an interactive call, n is the numeric prefix
argument, if provided; otherwise n defaults to
nil.
Warning: Don't use this function in Lisp programs!
nil, then it puts
point n tenths of the way from the end of the buffer.
In an interactive call, n is the numeric prefix
argument, if provided; otherwise n defaults to
nil.
Warning: Don't use this function in Lisp programs!
Text lines are portions of the buffer delimited by newline characters, which are regarded as part of the previous line. The first text line begins at the beginning of the buffer, and the last text line ends at the end of the buffer whether or not the last character is a newline. The division of the buffer into text lines is not affected by the width of the window, by line continuation in display, or by how tabs and control characters are displayed.
goto-line does not necessarily move to the beginning
of a line. If narrowing is in effect, then line still counts
from the beginning of the buffer, but point cannot go outside the
accessible portion. So goto-line moves point to the
beginning or end of the accessible portion, if the line number
specifies an inaccessible position.
The return value of goto-line is the difference
between line and the line number of the line to which
point actually was able to move (in the full buffer, before taking
account of narrowing). Thus, the value is positive if the scan
encounters the real end of the buffer before finding the specified
line. The value is zero if scan encounters the end of the
accessible portion but not the real end of the buffer.
In an interactive call, line is the numeric prefix argument if one has been provided. Otherwise line is read in the minibuffer.
nil or 1, it moves forward
count-1 lines and then to the beginning of the line.
If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point there. No error is signaled.
nil or 1, it moves forward count-1
lines and then to the end of the line. If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point there. No error is signaled.
If forward-line encounters the beginning or end of
the buffer (or of the accessible portion) before finding that many
lines, it sets point there. No error is signaled.
forward-line returns the difference between
count and the number of lines actually moved. If you
attempt to move down five lines from the beginning of a buffer that
has only three lines, point stops at the end of the last line, and
the value will be 2.
In an interactive call, count is the numeric prefix argument.
Here is an example of using count-lines:
(defun current-line ()
"Return the vertical position of point..."
(+ (count-lines (window-start) (point))
(if (= (current-column) 0) 1 0)
-1))
Also see the functions bolp and eolp
in section Examining Text Near
Point. These functions do not move point, but test whether it
is already at the beginning or end of a line.
The line functions in the previous section count text lines, delimited only by newline characters. By contrast, these functions count screen lines, which are defined by the way the text appears on the screen. A text line is a single screen line if it is short enough to fit the width of the selected window, but otherwise it may occupy several screen lines.
In some cases, text lines are truncated on the screen rather
than continued onto additional screen lines. In these cases,
vertical-motion moves point much like
forward-line. See section Truncation.
Because the width of a given string depends on the flags that
control the appearance of certain characters,
vertical-motion behaves differently, for a given piece
of text, depending on the buffer it is in, and even on the selected
window (because the width, the truncation flag, and display table
may vary between windows). See section Usual Display Conventions.
These functions scan text to determine where screen lines break, and thus take time proportional to the distance scanned. If you intend to use them heavily, Emacs provides caches which may improve the performance of your code. See section Truncation.
vertical-motion returns the number of screen lines
over which it moved point. The value may be less in absolute value
than count if the beginning or end of the buffer was
reached.
The window window is used for obtaining parameters
such as the width, the horizontal scrolling, and the display table.
But vertical-motion always operates on the current
buffer, even if window currently displays some other
buffer.
If count is nil, then point moves to the
beginning of the line in the middle of the window. If the absolute
value of count is greater than the size of the window,
then point moves to the place that would appear on that screen line
if the window were tall enough. This will probably cause the next
redisplay to scroll to bring that location onto the screen.
In an interactive call, count is the numeric prefix argument.
The value returned is the window line number point has moved to, with the top line in the window numbered 0.
The coordinate arguments frompos and topos
are cons cells of the form (hpos .
vpos).
The argument width is the number of columns available
to display text; this affects handling of continuation lines. Use
the value returned by window-width for the window of
your choice; normally, use (window-width
window).
The argument offsets is either nil or a
cons cell of the form (hscroll .
tab-offset). Here hscroll is the
number of columns not being displayed at the left margin; most
callers get this by calling window-hscroll. Meanwhile,
tab-offset is the offset between column numbers on the
screen and column numbers in the buffer. This can be nonzero in a
continuation line, when the previous screen lines' widths do not
add up to a multiple of tab-width. It is always zero
in a non-continuation line.
The window window serves only to specify which
display table to use. compute-motion always operates
on the current buffer, regardless of what buffer is displayed in
window.
The return value is a list of five elements:
(pos vpos hpos prevhpos contin)
Here pos is the buffer position where the scan stopped, vpos is the vertical screen position, and hpos is the horizontal screen position.
The result prevhpos is the horizontal position one
character back from pos. The result contin is
t if the last line was continued after (or within) the
previous character.
For example, to find the buffer position of column
col of screen line line of a certain window,
pass the window's display start location as from and the
window's upper-left coordinates as frompos. Pass the
buffer's (point-max) as to, to limit the
scan to the end of the accessible portion of the buffer, and pass
line and col as topos. Here's a
function that does this:
(defun coordinates-of-position (col line)
(car (compute-motion (window-start)
'(0 . 0)
(point-max)
(cons col line)
(window-width)
(cons (window-hscroll) 0)
(selected-window))))
When you use compute-motion for the minibuffer, you
need to use minibuffer-prompt-width to get the
horizontal position of the beginning of the first screen line. See
section Minibuffer Miscellany.
Here are several functions concerned with balanced-parenthesis expressions (also called sexps in connection with moving across them in Emacs). The syntax table controls how these functions interpret various characters; see section Syntax Tables. See section Parsing Balanced Expressions, for lower-level primitives for scanning sexps or parts of sexps. For user-level commands, see section `Lists Commands' in GNU Emacs Manual.
---------- Buffer: foo ----------
(concat-!- "foo " (car x) y z)
---------- Buffer: foo ----------
(forward-sexp 3)
=> nil
---------- Buffer: foo ----------
(concat "foo " (car x) y-!- z)
---------- Buffer: foo ----------
nil,
this variable holds a regular expression that specifies what text
can appear before the open-parenthesis that starts a defun. That is
to say, a defun begins on a line that starts with a match for this
regular expression, followed by a character with open-parenthesis
syntax.
The following two functions move point over a specified set of characters. For example, they are often used to skip whitespace. For related functions, see section Motion and Syntax.
The argument character-set is like the inside of a
`[...]' in a regular expression except that
`]' is never special and `\' quotes
`^', `-' or `\'. Thus,
"a-zA-Z" skips over all letters, stopping before the
first nonletter, and "^a-zA-Z" skips nonletters
stopping before the first letter. See section Regular Expressions.
If limit is supplied (it must be a number or a marker), it specifies the maximum position in the buffer that point can be skipped to. Point will stop at or before limit.
In the following example, point is initially located directly before the `T'. After the form is evaluated, point is located at the end of that line (between the `t' of `hat' and the newline). The function skips all letters and spaces, but not newlines.
---------- Buffer: foo ----------
I read "-!-The cat in the hat
comes back" twice.
---------- Buffer: foo ----------
(skip-chars-forward "a-zA-Z ")
=> nil
---------- Buffer: foo ----------
I read "The cat in the hat-!-
comes back" twice.
---------- Buffer: foo ----------
skip-chars-forward except for the direction of motion.
The return value indicates the distance traveled. It is an integer that is zero or less.
It is often useful to move point "temporarily" within a
localized portion of the program, or to switch buffers temporarily.
This is called an excursion, and it is done with the
save-excursion special form. This construct saves the
current buffer and its values of point and the mark so they can be
restored after the completion of the excursion.
The forms for saving and restoring the configuration of windows are described elsewhere (see section Window Configurations, and see section Frame Configurations).
save-excursion
special form saves the identity of the current buffer and the
values of point and the mark in it, evaluates forms, and
finally restores the buffer and its saved values of point and the
mark. All three saved values are restored even in case of an
abnormal exit via throw or error (see section Nonlocal Exits). The save-excursion special form is the standard way
to switch buffers or move point within one part of a program and
avoid affecting the rest of the program. It is used more than 4000
times in the Lisp sources of Emacs.
save-excursion does not save the values of point
and the mark for other buffers, so changes in other buffers remain
in effect after save-excursion exits.
Likewise,
save-excursion does not restore window-buffer
correspondences altered by functions such as
switch-to-buffer. One way to restore these
correspondences, and the selected window, is to use
save-window-excursion inside
save-excursion (see section Window Configurations).
The value returned by save-excursion is the result
of the last of forms, or nil if no
forms are given.
(save-excursion forms)
==
(let ((old-buf (current-buffer))
(old-pnt (point-marker))
(old-mark (copy-marker (mark-marker))))
(unwind-protect
(progn forms)
(set-buffer old-buf)
(goto-char old-pnt)
(set-marker (mark-marker) old-mark)))
Warning: Ordinary insertion of text adjacent to the saved point value relocates the saved value, just as it relocates all markers. Therefore, when the saved point value is restored, it normally comes before the inserted text.
Although save-excursion saves the location of the
mark, it does not prevent functions which modify the buffer from
setting deactivate-mark, and thus causing the
deactivation of the mark after the command finishes. See section The Mark.
Narrowing means limiting the text addressable by Emacs editing commands to a limited range of characters in a buffer. The text that remains addressable is called the accessible portion of the buffer.
Narrowing is specified with two buffer positions which become the beginning and end of the accessible portion. For most editing commands and most Emacs primitives, these positions replace the values of the beginning and end of the buffer. While narrowing is in effect, no text outside the accessible portion is displayed, and point cannot move outside the accessible portion.
Values such as positions or line numbers, which usually count from the beginning of the buffer, do so despite narrowing, but the functions which use them refuse to operate on text that is inaccessible.
The commands for saving buffers are unaffected by narrowing; they save the entire buffer regardless of any narrowing.
In an interactive call, start and end are set to the bounds of the current region (point and the mark, with the smallest first).
nil means to move forward or backward by
move-count pages and then narrow to one page. The
variable page-delimiter specifies where pages start
and end (see section Standard Regular
Expressions Used in Editing). In an interactive call, move-count is set to the numeric prefix argument.
(narrow-to-region 1 (1+ (buffer-size)))
throw or error (see section Nonlocal Exits). Therefore, this
construct is a clean way to narrow a buffer temporarily. The value returned by save-restriction is that
returned by the last form in body, or nil
if no body forms were given.
Caution: it is easy to make a mistake when
using the save-restriction construct. Read the entire
description here before you try it.
If body changes the current buffer,
save-restriction still restores the restrictions on
the original buffer (the buffer whose restrictions it saved from),
but it does not restore the identity of the current buffer.
save-restriction does not restore point
and the mark; use save-excursion for that. If you use
both save-restriction and save-excursion
together, save-excursion should come first (on the
outside). Otherwise, the old point value would be restored with
temporary narrowing still in effect. If the old point value were
outside the limits of the temporary narrowing, this would fail to
restore it accurately.
The save-restriction special form records the
values of the beginning and end of the accessible portion as
distances from the beginning and end of the buffer. In other words,
it records the amount of inaccessible text before and after the
accessible portion.
This method yields correct results if body does
further narrowing. However, save-restriction can
become confused if the body widens and then makes changes outside
the range of the saved narrowing. When this is what you want to do,
save-restriction is not the right tool for the job.
Here is what you must use instead:
(let ((beg (point-min-marker))
(end (point-max-marker)))
(unwind-protect
(progn body)
(save-excursion
(set-buffer (marker-buffer beg))
(narrow-to-region beg end))))
Here is a simple example of correct use of
save-restriction:
---------- Buffer: foo ----------
This is the contents of foo
This is the contents of foo
This is the contents of foo-!-
---------- Buffer: foo ----------
(save-excursion
(save-restriction
(goto-char 1)
(forward-line 2)
(narrow-to-region 1 (point))
(goto-char (point-min))
(replace-string "foo" "bar")))
---------- Buffer: foo ----------
This is the contents of bar
This is the contents of bar
This is the contents of foo-!-
---------- Buffer: foo ----------