[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
41.1 Point | The special position where editing takes place. | |
41.2 Motion | Changing point. | |
41.3 Excursions | Temporary motion and buffer changes. | |
41.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. 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.
This function returns the value of point in buffer, as an integer. buffer defaults to the current buffer if omitted.
(point) ⇒ 175 |
This function returns the minimum accessible value of point in buffer. This is normally 1, but if narrowing is in effect, it is the position of the start of the region that you narrowed to. (See section Narrowing.) buffer defaults to the current buffer if omitted.
This function returns the maximum accessible value of point in
buffer. This is (1+ (buffer-size buffer))
, 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). buffer
defaults to the current buffer if omitted.
This function returns (point-min buffer)
if flag is less
than 1, (point-max buffer)
otherwise. The argument flag
must be a number. buffer defaults to the current buffer if
omitted.
This function returns the total number of characters in buffer.
In the absence of any narrowing (see section Narrowing), point-max
returns a value one larger than this. buffer defaults to the
current buffer if omitted.
(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.
41.2.1 Motion by Characters | Moving in terms of characters. | |
41.2.2 Motion by Words | Moving in terms of words. | |
41.2.3 Motion to an End of the Buffer | Moving to the beginning or end of the buffer. | |
41.2.4 Motion by Text Lines | Moving in terms of lines of text. | |
41.2.5 Motion by Screen Lines | Moving in terms of lines as displayed. | |
41.2.6 Moving over Balanced Expressions | Moving by parsing lists and sexps. | |
41.2.7 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 the fundamental primitive; the other functions use
that.
This function sets point in buffer
to the value position.
If position is less than 1, it moves point to the beginning of the
buffer. If position is greater than the length of the buffer, it
moves point to the end. buffer defaults to the current buffer if
omitted.
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.
This function moves point count characters forward, towards the
end of the buffer (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
. buffer
defaults to the current buffer if omitted.
In an interactive call, count is the numeric prefix argument.
This function moves point count characters backward, towards the
beginning of the buffer (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
. buffer
defaults to the current buffer if omitted.
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. See section 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
.
count defaults to 1
and buffer defaults to the
current buffer.
In an interactive call, count is set to the numeric prefix argument.
This function is just like forward-word
, except that it moves
backward until encountering the front of a word, rather than forward.
buffer defaults to the current buffer if omitted.
In an interactive call, count is set to the numeric prefix 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 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.
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 count is non-nil
, then it
puts point count tenths of the way from the beginning of the buffer.
In an interactive call, count is the numeric prefix argument,
if provided; otherwise count 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 count is non-nil
, then it puts
point count tenths of the way from the end of the buffer.
In an interactive call, count is the numeric prefix argument,
if provided; otherwise count 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, by line continuation in display, 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 the buffer. If line is less
than 1, it moves point to the beginning of the buffer. If line is
greater than the number of lines in the buffer, it moves point to the
end of the buffer—that is, the end of the last line of the
buffer. This is the only case in which 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. 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.
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.
buffer defaults to the current buffer if omitted.
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.
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.
buffer defaults to the current buffer if omitted.
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.
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 a line. If count is zero, it moves point to the beginning of the current line. buffer defaults to the current buffer if omitted.
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.
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.
With optional ignore-invisible-lines-flag non-nil
, lines
collapsed with selective-display are excluded from the line count.
N.B. The expression to return the current line number is not obvious:
(1+ (count-lines 1 (point-at-bol))) |
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 Examining Text 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. 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 cache-long-line-scans.
This function moves point to the start of the frame line count frame lines down from the frame line containing point. If count is negative, it moves up instead. The optional second argument window may be used to specify a window other than the selected window in which to perform the motion.
Normally, vertical-motion
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. If the optional third argument,
pixels is non-nil
, the vertical pixel height of the motion
which took place is returned instead of the actual number of lines
moved. A motion of zero lines returns the height of the current line.
Note that vertical-motion
sets window’s buffer’s point, not
window’s point. (This differs from FSF Emacs, which buggily always
sets current buffer’s point, regardless of window.)
This function moves point to the start of the frame line pixels vertical pixels down from the frame line containing point, or up if pixels is negative. The optional second argument window is the window to move in, and defaults to the selected window. The optional third argument how specifies the stopping condition. A negative fixnum indicates that the motion should be no more than pixels. A positive value indicates that the motion should be at least pixels. Any other value indicates that the motion should be as close as possible to pixels.
This function moves point with respect to the text currently displayed in window, which defaults to the selected window. It moves point to the beginning of the screen line count screen lines from the top of the window. If count is negative, that specifies a position -count lines from the bottom (or 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
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here are several functions concerned with balanced-parenthesis expressions (also called sexps in connection with moving across them in XEmacs). The syntax table controls how these functions interpret various characters; see Syntax Tables. See section Parsing Balanced Expressions, for lower-level primitives for scanning sexps or parts of sexps. For user-level commands, see (xemacs)Lists and Sexps section ‘Lists and Sexps’ in XEmacs Reference Manual.
This function moves forward across arg balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.) arg defaults to 1 if omitted. If arg is negative, move backward across that many groups of parentheses.
This function moves backward across count balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.) count defaults to 1 if omitted. If count is negative, move forward across that many groups of parentheses.
This function moves forward out of count levels of parentheses. A negative argument means move backward but still to a less deep spot.
This function moves forward into count levels of parentheses. A negative argument means move backward but still go deeper in parentheses (-count levels).
This function moves forward across count balanced expressions. Balanced expressions include both those delimited by parentheses and other kinds, such as words and string constants. count defaults to 1 if omitted. If count is negative, move backward across that many balanced expressions. 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 ---------- |
This function moves backward across count balanced expressions. count defaults to 1 if omitted. If count is negative, move forward across that many balanced expressions.
This function moves back to the countth beginning of a defun. If count is negative, this actually moves forward, but it still moves to the beginning of a defun, not to the end of one. count defaults to 1 if omitted.
This function moves forward to the countth end of a defun. If count is negative, this actually moves backward, but it still moves to the end of a defun, not to the beginning of one. count defaults to 1 if omitted.
If non-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.
[ < ] | [ > ] | [ << ] | [ 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 Motion and Syntax.
This function moves point in buffer forward, skipping over a
given set of characters. It examines the character following point,
then advances point if the character matches character-set. This
continues until it reaches a character that does not match. The
function returns nil
. buffer defaults to the current
buffer if omitted.
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
non-letter, and "^a-zA-Z
" skips non-letters 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 ---------- |
This function moves point backward, skipping characters that match
character-set, until limit. 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 operator. 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 Window Configurations and see section Frame Configurations).
The save-excursion
special operator 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 operator 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 XEmacs.
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))) |
This special operator is similar to save-excursion
but it only
saves and restores the current buffer. Beginning with XEmacs 20.3,
save-current-buffer
is a primitive.
This macro evaluates forms with buffer as the current buffer. It returns the value of the last form.
This macro creates a new buffer, evaluates forms there, and writes the buffer to filename. It returns the value of the last form evaluated.
This macro is similar to save-excursion
but it saves and
restores the selected window and nothing else.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.