@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/positions
@node Positions, Markers, Frames, Top
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 @dfn{markers}---special objects that relocate
-automatically when text is inserted or deleted so they stay with the
-surrounding characters. Functions that expect an argument to be a
-position (an integer), but accept a marker as a substitute, normally
-ignore the marker buffer. Of course, markers used this way usually
-point to a position in the buffer that the function operates on, but
-that is entirely the programmer's responsibility. @xref{Markers}.
+ Positions are usually represented as integers starting from 1, but
+can also be represented as @dfn{markers}---special objects that
+relocate automatically when text is inserted or deleted so they stay
+with the surrounding characters. Functions that expect an argument to
+be a position (an integer), but accept a marker as a substitute,
+normally ignore which buffer the marker points into; they convert the
+marker to an integer, and use that integer, exactly as if you had
+passed the integer as the argument, even if the marker points to the
+``wrong'' buffer. A marker that points nowhere cannot convert to an
+integer; using it instead of an integer causes an error.
+@xref{Markers}.
See also the ``field'' feature (@pxref{Fields}), which provides
functions that are used by many cursor-motion commands.
@node Motion
@section Motion
+@cindex motion by chars, words, lines, lists
Motion functions change the value of point, either relative to the
current value of point, relative to the beginning or end of the buffer,
@c @kindex end-of-buffer
This function moves point @var{count} characters forward, towards the
end of the buffer (or backward, towards the beginning of the buffer, if
-@var{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 @code{beginning-of-buffer} or @code{end-of-buffer}.
+@var{count} is negative). If @var{count} is @code{nil}, the default
+is 1.
+
+If this attempts to move past the beginning or end of the buffer (or
+the limits of the accessible portion, when narrowing is in effect), it
+signals an error with error symbol @code{beginning-of-buffer} or
+@code{end-of-buffer}.
In an interactive call, @var{count} is the numeric prefix argument.
@end deffn
@deffn Command backward-char &optional count
-This function moves point @var{count} characters backward, towards the
-beginning of the buffer (or forward, towards the end of the buffer, if
-@var{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 @code{beginning-of-buffer} or @code{end-of-buffer}.
-
-In an interactive call, @var{count} is the numeric prefix argument.
+This is just like @code{forward-char} except that it moves
+in the opposite direction.
@end deffn
@node Word Motion
@deffn Command forward-word &optional count
This function moves point forward @var{count} words (or backward if
-@var{count} is negative). ``Moving one word'' means moving until point
-crosses a word-constituent character and then encounters a
-word-separator character. However, this function cannot move point past
-the boundary of the accessible portion of the buffer, or across a field
-boundary (@pxref{Fields}). The most common case of a field boundary is
-the end of the prompt in the minibuffer.
+@var{count} is negative). If @var{count} is @code{nil}, it moves
+forward one word.
+
+``Moving one word'' means moving until point crosses a
+word-constituent character and then encounters a word-separator
+character. However, this function cannot move point past the boundary
+of the accessible portion of the buffer, or across a field boundary
+(@pxref{Fields}). The most common case of a field boundary is the end
+of the prompt in the minibuffer.
If it is possible to move @var{count} words, without being stopped
prematurely by the buffer boundary or a field boundary, the value is
@end defvar
@defvar inhibit-field-text-motion
-@tindex inhibit-field-text-motion
If this variable is non-@code{nil}, certain motion functions including
@code{forward-word}, @code{forward-sentence}, and
@code{forward-paragraph} ignore field boundaries.
@node Buffer End Motion
@subsection Motion to an End of the Buffer
+@cindex move to beginning or end of buffer
To move point to the beginning of the buffer, write:
@deffn Command beginning-of-buffer &optional n
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 @var{n} is non-@code{nil}, then it
-puts point @var{n} tenths of the way from the beginning of the
-accessible portion of the buffer.
+mark at the previous position (except in Transient Mark mode, if
+the mark is already active, it does not set the mark.)
-In an interactive call, @var{n} is the numeric prefix argument,
-if provided; otherwise @var{n} defaults to @code{nil}.
+If @var{n} is non-@code{nil}, then it puts point @var{n} tenths of the
+way from the beginning of the accessible portion of the buffer. In an
+interactive call, @var{n} is the numeric prefix argument, if provided;
+otherwise @var{n} defaults to @code{nil}.
@strong{Warning:} Don't use this function in Lisp programs!
@end deffn
@deffn Command end-of-buffer &optional n
-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 @var{n} is non-@code{nil}, then it puts point
-@var{n} tenths of the way from the end of the accessible portion of the
-buffer.
+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 (except in Transient Mark mode when the mark
+is already active). If @var{n} is non-@code{nil}, then it puts point
+@var{n} tenths of the way from the end of the accessible portion of
+the buffer.
In an interactive call, @var{n} is the numeric prefix argument,
if provided; otherwise @var{n} defaults to @code{nil}.
@end deffn
@defun line-beginning-position &optional count
-@tindex line-beginning-position
Return the position that @code{(beginning-of-line @var{count})}
would move to.
@end defun
@end deffn
@defun line-end-position &optional count
-@tindex line-end-position
Return the position that @code{(end-of-line @var{count})}
would move to.
@end defun
the line. If @var{count} is negative, it moves point
@minus{}@var{count} lines backward, to the beginning of a line. If
@var{count} is zero, it moves point to the beginning of the current
-line.
+line. If @var{count} is @code{nil}, that means 1.
If @code{forward-line} encounters the beginning or end of the buffer (or
of the accessible portion) before finding that many lines, it sets point
@defun line-number-at-pos &optional pos
@cindex line number
This function returns the line number in the current buffer
-corresponding the buffer position @var{pos}. If @var{pos} is @code{nil}
+corresponding to the buffer position @var{pos}. If @var{pos} is @code{nil}
or omitted, the current buffer position is used.
@end defun
the form @code{(@var{hpos} . @var{vpos})}.
The argument @var{width} is the number of columns available to display
-text; this affects handling of continuation lines. Use the value
-returned by @code{window-width} for the window of your choice;
-normally, use @code{(window-width @var{window})}.
+text; this affects handling of continuation lines. @code{nil} means
+the actual number of usable text columns in the window, which is
+equivalent to the value returned by @code{(window-width window)}.
The argument @var{offsets} is either @code{nil} or a cons cell of the
form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is
When you use @code{compute-motion} for the minibuffer, you need to use
@code{minibuffer-prompt-width} to get the horizontal position of the
-beginning of the first screen line. @xref{Minibuffer Misc}.
+beginning of the first screen line. @xref{Minibuffer Contents}.
@end defun
@node List Motion
@cindex sexp motion
@cindex Lisp expression motion
@cindex list motion
+@cindex balanced parenthesis motion
Here are several functions concerned with balanced-parenthesis
expressions (also called @dfn{sexps} in connection with moving across
@deffn Command forward-sexp &optional arg
This function moves forward across @var{arg} (default 1) balanced expressions.
Balanced expressions include both those delimited by parentheses and
-other kinds, such as words and string constants
+other kinds, such as words and string constants.
@xref{Parsing Expressions}. For example,
@example
@deffn Command beginning-of-defun &optional arg
This function moves back to the @var{arg}th beginning of a defun. If
@var{arg} is negative, this actually moves forward, but it still moves
-to the beginning of a defun, not to the end of one.
+to the beginning of a defun, not to the end of one. @var{arg} defaults
+to 1.
@end deffn
@deffn Command end-of-defun &optional arg
This function moves forward to the @var{arg}th end of a defun. If
@var{arg} is negative, this actually moves backward, but it still moves
-to the end of a defun, not to the beginning of one.
+to the end of a defun, not to the beginning of one. @var{arg} defaults
+to 1.
@end deffn
@defopt defun-prompt-regexp
-If non-@code{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.
+If non-@code{nil}, this buffer-local 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.
@end defopt
@defopt open-paren-in-column-0-is-defun-start
@end defopt
@defvar beginning-of-defun-function
-@tindex beginning-of-defun-function
If non-@code{nil}, this variable holds a function for finding the
beginning of a defun. The function @code{beginning-of-defun}
calls this function instead of using its normal method.
@end defvar
@defvar end-of-defun-function
-@tindex end-of-defun-function
If non-@code{nil}, this variable holds a function for finding the end of
a defun. The function @code{end-of-defun} calls this function instead
of using its normal method.
continues until it reaches a character that does not match. The
function returns the number of characters moved over.
-The argument @var{character-set} is like the inside of a
-@samp{[@dots{}]} in a regular expression except that @samp{]} is never
-special and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}. Thus,
-@code{"a-zA-Z"} skips over all letters, stopping before the first
-nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before the
-first letter. @xref{Regular Expressions}.
+The argument @var{character-set} is a string, like the inside of a
+@samp{[@dots{}]} in a regular expression except that @samp{]} does not
+terminate it, and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}.
+Thus, @code{"a-zA-Z"} skips over all letters, stopping before the
+first nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before
+the first letter. See @xref{Regular Expressions}. Character classes
+can also be used, e.g. @code{"[:alnum:]"}. See @pxref{Char Classes}.
If @var{limit} is supplied (it must be a number or a marker), it
specifies the maximum position in the buffer that point can be skipped
described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
Configurations}).
-@defspec save-excursion forms@dots{}
+@defspec save-excursion body@dots{}
@cindex mark excursion
@cindex point excursion
-@cindex current buffer excursion
The @code{save-excursion} special form saves the identity of the current
buffer and the values of point and the mark in it, evaluates
-@var{forms}, and finally restores the buffer and its saved values of
+@var{body}, 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 @code{throw} or error (@pxref{Nonlocal Exits}).
use @code{save-window-excursion} inside @code{save-excursion}
(@pxref{Window Configurations}).
-The value returned by @code{save-excursion} is the result of the last of
-@var{forms}, or @code{nil} if no @var{forms} are given.
+The value returned by @code{save-excursion} is the result of the last
+form in @var{body}, or @code{nil} if no body forms were given.
@example
@group