[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A position is the index of a character in the text of 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, the character after a position is often said to be “at” that position.
Positions are usually represented as integers starting from 1, but can also be represented as markers—special objects which relocate automatically when text is inserted or deleted so they stay with the surrounding characters. @xref{Markers}.
1.1 Point | The special position where editing takes place. | |
1.2 Motion | Changing point. | |
1.3 Excursions | Temporary motion and buffer changes. | |
1.4 Narrowing | Restricting editing to a portion of the buffer. |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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. Many terminals display the cursor over the character that immediately follows point; on such terminals, 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. @xref{Window Point}, for more details.
This function returns the position of point in the current buffer, as an integer.
(point) ⇒ 175
This function returns the minimum accessible value of point in the current buffer. This is 1, unless narrowing is in effect, in which case it is the position of the start of the region that you narrowed to. (See section Narrowing.)
This function returns the maximum accessible value of point in the
current buffer. This is (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).
This function returns (point-min)
if flag is less than 1,
(point-max)
otherwise. The argument flag must be a number.
This function returns the total number of characters in the current
buffer. In the absence of any narrowing (see section Narrowing),
point-max
returns a value one larger than this.
(buffer-size) ⇒ 35
(point-max) ⇒ 36
The value of this buffer-local variable is the former length of the current buffer, as of the last time it was read in, saved or auto-saved.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
1.2.1 Motion by Characters | Moving in terms of characters. | |
1.2.2 Motion by Words | Moving in terms of words. | |
1.2.3 Motion to an End of the Buffer | Moving to the beginning or end of the buffer. | |
1.2.4 Motion by Text Lines | Moving in terms of lines of text. | |
1.2.5 Motion by Screen Lines | Moving in terms of lines as displayed. | |
1.2.6 The User-Level Vertical Motion Commands | Implementation of next-line and
previous-line .
| |
1.2.7 Moving over Balanced Expressions | Moving by parsing lists and sexps. | |
1.2.8 Skipping Characters | Skipping characters belonging to a certain set. |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These functions move point based on a count of characters.
goto-char
is a fundamental primitive because it is the way to
move point to a specified position.
This function sets point in the current buffer to the value position. If position is less than 1, then point is set to the beginning of the buffer. If it is greater than the length of the buffer, then point is set to the end of the buffer.
If narrowing is in effect, then the position is still measured from the beginning of the buffer, but point cannot be moved outside of the accessible portion. Therefore, if position is too small, point is set to the beginning of the accessible portion of the text; if position is too large, point is set to the end.
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.
This function moves point forward, towards the end of the buffer,
count characters (or backward, towards the beginning of the
buffer, if count is negative). If the function attempts to move
point past the beginning or end of the buffer (or the limits of the
accessible portion, when narrowing is in effect), an error is signaled
with error code beginning-of-buffer
or end-of-buffer
.
In an interactive call, count is the numeric prefix argument.
This function moves point backward, towards the beginning of the buffer,
count characters (or forward, towards the end of the buffer, if
count is negative). If the function attempts to move point past
the beginning or end of the buffer (or the limits of the accessible
portion, when narrowing is in effect), an error is signaled with error
code beginning-of-buffer
or end-of-buffer
.
In an interactive call, count is the numeric prefix argument.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These functions for parsing words use the syntax table to decide whether a given character is part of a word. @xref{Syntax Tables}.
This function moves point forward count words (or backward if
count is negative). Normally it returns t
. If this motion
encounters the beginning or end of the buffer, or the limits of the
accessible portion when narrowing is in effect, point stops there
and the value is nil
.
In an interactive call, count is set to the numeric prefix argument.
This function just like 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 negative argument.
This variable affects the behavior of 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.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 which 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.
This function moves point to the beginning of the buffer (or the limits
of the accessible portion, when narrowing is in effect), setting the
mark at the previous position. If n is non-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
.
Don’t use this function in Lisp programs!
This function moves point to the end of the buffer (or the limits of
the accessible portion, when narrowing is in effect), setting the mark
at the previous position. If n is non-nil
, then it puts
point n tenths of the way from the end.
In an interactive call, n is the numeric prefix argument,
if provided; otherwise n defaults to nil
.
Don’t use this function in Lisp programs!
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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, or by how tabs and control characters are displayed.
This function moves point to the front of the lineth line, counting from line 1 at beginning of buffer. If line is less than 1, then point is set to the beginning of the buffer. If line is greater than the number of lines in the buffer, then point is set to the end of the last line of the buffer.
If narrowing is in effect, then line still counts from the beginning of the buffer, but point cannot go outside the accessible portion. So point is set at the beginning or end of the accessible portion of the text if the line number specifies a position that is inaccessible.
The return value of goto-line
is the difference between
line and the line number of the line to which point actually was
able move (before taking account of any narrowing). Thus, the value is
positive if the scan encounters the 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.
This function moves point to the beginning of the current line. With an
argument count not 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 at the beginning of the last line. No error is signaled.
This function moves point to the end of the current line. With an
argument count not 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 at the end of the last line. No error is signaled.
This function moves point forward count lines, to the beginning of the line. If count is negative, it moves point -count lines backward, to the beginning of the line.
If the beginning or end of the buffer (or of the accessible portion) is encountered before that many lines are found, then point stops at the beginning or end. 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 will
positioned at the end of the last line, and the value will be 2.
In an interactive call, count is the numeric prefix argument.
This function returns the number of lines between the positions start and end in the current buffer. If start and end are equal, then it returns 0. Otherwise it returns at least 1, even if start and end are on the same line. This is because the text between them, considered in isolation, must contain at least one line unless it is empty.
Here is an example of using count-lines
:
(defun current-line () "Return the vertical position of point in the selected window. Top line is 0. Counts each text line only once, even if it wraps." (+ (count-lines (window-start) (point)) (if (= (current-column) 0) 1 0) -1))
Also see the functions bolp
and eolp
in @ref{Near Point}.
These functions do not move point, but test whether it is already at the
beginning or end of a line.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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. Then vertical-motion
moves point just like forward-line
. @xref{Truncation}.
Because the width of a given string depends on the flags which control
the appearance of certain characters, vertical-motion
will behave
differently on a given piece of text found in different buffers. It
will even act differently in different windows showing the same buffer,
because the width may differ and so may the truncation flag.
@xref{Usual Display}.
This function moves point to the start of the screen line count screen lines down from the screen line containing point. If count is negative, it moves up instead.
This function returns the number of lines moved. The value may be less in absolute value than count if the beginning or end of the buffer was reached.
This function moves point with respect to the text currently displayed in the selected window. Point is moved to the beginning of the screen line count screen lines from the top of the window. If count is negative, point moves either to the beginning of the line -count lines from the bottom or else to the last line of the buffer if the buffer ends above the specified screen position.
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
which 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, with the top line in the window numbered 0.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A goal column is useful if you want to edit text such as a table in
which you want to move point to a certain column on each line. The goal
column affects the vertical text line motion commands, next-line
and previous-line
. See Basic Editing Commands in The GNU Emacs Manual.
This variable holds an explicitly specified goal column for vertical
line motion commands. If it is an integer, it specifies a column, and
these commands try to move to that column on each line. If it is
nil
, then the commands set their own goal columns. Any other
value is invalid.
This variable holds the temporary goal column during a sequence of
consecutive vertical line motion commands. It is overridden by
goal-column
if that is non-nil
. It is set each time a
vertical motion command is invoked, unless the previous command was also
a vertical motion command.
This variable controls how the vertical line motion commands operate
when starting at the end of a line. If track-eol
is
non-nil
, then vertical motion starting at the end of a line will
keep to the ends of lines. This means moving to the end of each line
moved onto. The value of track-eol
has no effect if point is not
at the end of a line when the first vertical motion command is given.
track-eol
has its effect by causing temporary-goal-column
to be set to 9999 instead of to the current column.
This command sets the variable goal-column
to specify a permanent
goal column for the vertical line motion commands. If unset is
nil
, then goal-column
is set to the current column of
point. If unset is non-nil
, then goal-column
is set
to nil
.
This function is intended for interactive use; and in an interactive call, unset is the raw prefix argument.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 @ref{Syntax Tables}. @xref{Parsing Expressions}, for lower-level primitives for scanning sexps or parts of sexps. For user-level commands, see Lists and Sexps in GNU Emacs Manual.
Move forward across arg balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.)
Move backward across arg balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.)
Move forward out of arg levels of parentheses. A negative argument means move backward but still to a less deep spot.
Move forward down arg levels of parentheses. A negative argument means move backward but still go down arg level.
Move forward across arg balanced expressions. Balanced expressions include both those delimited by parentheses and other kinds, such as words and string constants. For example,
---------- Buffer: foo ---------- (concat∗ "foo " (car x) y z) ---------- Buffer: foo ----------
(forward-sexp 3) ⇒ nil ---------- Buffer: foo ---------- (concat "foo " (car x) y∗ z) ---------- Buffer: foo ----------
Move backward across arg balanced expressions.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 @ref{Motion and Syntax}.
This function moves point in the current buffer forward, skipping over
a given set of characters. Emacs first examines the character following
point; if it matches character-set, then point is advanced and the
next character is examined. This continues until a character is found
that does not match. The function returns nil
.
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. @xref{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 ----------
This function moves point backward, skipping characters that match
character-set. It just like skip-chars-forward
except for the direction of motion.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 @ref{Window Configurations}, and @pxref{Frame Configurations}).
The 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 (@pxref{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 500 times in the Lisp
sources of Emacs.
The values of point and the mark for other buffers are not saved by
save-excursion
, so any changes made to point and the mark in the
other buffers will 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
(@pxref{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)))
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 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 continue to do so, but the functions which use them will refuse to operate on text that is inaccessible.
The commands for saving buffers are unaffected by narrowing; the entire buffer is saved regardless of the any narrowing.
This function sets the accessible portion of the current buffer to start at start and end at end. Both arguments should be character positions.
In an interactive call, start and end are set to the bounds of the current region (point and the mark, with the smallest first).
This function sets the accessible portion of the current buffer to
include just the current page. An optional first argument
move-count non-nil
means to move forward or backward by
move-count pages and then narrow.
In an interactive call, move-count is set to the numeric prefix argument.
This function cancels any narrowing in the current buffer, so that the entire contents are accessible. This is called widening. It is equivalent to the following expression:
(narrow-to-region 1 (1+ (buffer-size)))
This special form saves the current bounds of the accessible portion, evaluates the body forms, and finally restores the saved bounds, thus restoring the same state of narrowing (or absence thereof) formerly in effect. The state of narrowing is restored even in the event of an abnormal exit via throw or error (@pxref{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
function. 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 they came
from), but it does not restore the identity of the current buffer.
Point and the mark are not restored by this special form; 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 technique yields correct results if body does further
narrowing. However, save-restriction
can become confused if they
widen and then make changes outside the area 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 ----------
[Top] | [Contents] | [Index] | [ ? ] |
This document was generated on January 16, 2023 using texi2html 5.0.
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 January 16, 2023 using texi2html 5.0.