@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/positions
@node Positions, Markers, Frames, Top
surrounding characters. @xref{Markers}.
See also the ``field'' feature (@pxref{Fields}), which provides
-functions that are used by many cursur-motion commands.
+functions that are used by many cursor-motion commands.
@menu
* Point:: The special position where editing takes place.
@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 part of the buffer, or across a field
+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.
@code{t}. Otherwise, the return value is @code{nil} and point stops at
the buffer boundary or field boundary.
+If @code{inhibit-field-text-motion} is non-@code{nil},
+this function ignores field boundaries.
+
In an interactive call, @var{count} is specified by the numeric prefix
argument.
@end deffn
In an interactive call, @var{count} is set to the numeric prefix
argument.
-This function is rarely used in programs, as it is more efficient to
-call @code{forward-word} with a negative argument.
+@c [Now optimized by compiler.]
+@c This function is rarely used in programs, as it is more efficient to
+@c call @code{forward-word} with a negative argument.
@end deffn
@defvar words-include-escapes
words. Otherwise, they do not.
@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.
+@end defvar
+
@node Buffer End Motion
@subsection Motion to an End of the Buffer
argument @var{count} not @code{nil} or 1, it moves forward
@var{count}@minus{}1 lines and then to the beginning of the line.
+This function does not move point across a field boundary
+(@pxref{Fields}) unless doing so would move beyond there to a
+different line; therefore, if @var{count} is @code{nil} or 1, and
+point starts at a field boundary, point does not move. To ignore
+field boundaries, either bind @code{inhibit-field-text-motion} to
+@code{t}, or use the @code{forward-line} function instead. For
+instance, @code{(forward-line 0)} does the same thing as
+@code{(beginning-of-line)}, except that it ignores field boundaries.
+
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 does not move across a field boundary (@pxref{Fields}),
-unless it moves to another line beyond the one that contains the field
-boundary. If @var{count} is zero, and point starts at a field boundary,
-then point does not move.
@end deffn
@defun line-beginning-position &optional count
argument @var{count} not @code{nil} or 1, it moves forward
@var{count}@minus{}1 lines and then to the end of the line.
+This function does not move point across a field boundary
+(@pxref{Fields}) unless doing so would move beyond there to a
+different line; therefore, if @var{count} is @code{nil} or 1, and
+point starts at a field boundary, point does not move. To ignore
+field boundaries, bind @code{inhibit-field-text-motion} to @code{t}.
+
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 does not move across a field boundary, unless it moves to
-another line beyond the one that contains the field boundary. If
-@var{count} is zero, and point starts at a field boundary, then point
-does not move.
@end deffn
@defun line-end-position &optional count
use them heavily, Emacs provides caches which may improve the
performance of your code. @xref{Truncation, cache-long-line-scans}.
-
@defun vertical-motion count &optional window
This function moves point to the start of the screen line @var{count}
screen lines down from the screen line containing point. If @var{count}
@var{window} currently displays some other buffer.
@end defun
+@defun count-screen-lines &optional beg end count-final-newline window
+This function returns the number of screen lines in the text from
+@var{beg} to @var{end}. The number of screen lines may be different
+from the number of actual lines, due to line continuation, the display
+table, etc. If @var{beg} and @var{end} are @code{nil} or omitted,
+they default to the beginning and end of the accessible portion of the
+buffer.
+
+If the region ends with a newline, that is ignored unless the optional
+third argument @var{count-final-newline} is non-@code{nil}.
+
+The optional fourth argument @var{window} specifies the window for
+obtaining parameters such as width, horizontal scrolling, and so on.
+The default is to use the selected window's parameters.
+
+Like @code{vertical-motion}, @code{count-screen-lines} always uses the
+current buffer, regardless of which buffer is displayed in
+@var{window}. This makes possible to use @code{count-screen-lines} in
+any buffer, whether or not it is currently displayed in some window.
+@end defun
+
@deffn Command move-to-window-line count
This function moves point with respect to the text currently displayed
in the selected window. It moves point to the beginning of the screen
The return value is a list of five elements:
@example
-(@var{pos} @var{vpos} @var{hpos} @var{prevhpos} @var{contin})
+(@var{pos} @var{hpos} @var{vpos} @var{prevhpos} @var{contin})
@end example
@noindent
@node List Motion
@comment node-name, next, previous, up
-@subsection Moving over Balanced Expressions
+@subsection Moving over Balanced Expressions
@cindex sexp motion
@cindex Lisp expression motion
@cindex list motion
sexps. For user-level commands, see @ref{Lists Commands,,, emacs, The GNU
Emacs Manual}.
-@deffn Command forward-list arg
-This function moves forward across @var{arg} balanced groups of
+@deffn Command forward-list &optional arg
+This function moves forward across @var{arg} (default 1) balanced groups of
parentheses. (Other syntactic entities such as words or paired string
quotes are ignored.)
@end deffn
-@deffn Command backward-list arg
-This function moves backward across @var{arg} balanced groups of
+@deffn Command backward-list &optional arg
+This function moves backward across @var{arg} (default 1) balanced groups of
parentheses. (Other syntactic entities such as words or paired string
quotes are ignored.)
@end deffn
-@deffn Command up-list arg
-This function moves forward out of @var{arg} levels of parentheses.
+@deffn Command up-list &optional arg
+This function moves forward out of @var{arg} (default 1) levels of parentheses.
A negative argument means move backward but still to a less deep spot.
@end deffn
-@deffn Command down-list arg
-This function moves forward into @var{arg} levels of parentheses. A
+@deffn Command down-list &optional arg
+This function moves forward into @var{arg} (default 1) levels of parentheses. A
negative argument means move backward but still go
deeper in parentheses (@minus{}@var{arg} levels).
@end deffn
-@deffn Command forward-sexp arg
-This function moves forward across @var{arg} balanced expressions.
+@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. For example,
+other kinds, such as words and string constants
+@xref{Parsing Expressions}. For example,
@example
@group
@end example
@end deffn
-@deffn Command backward-sexp arg
-This function moves backward across @var{arg} balanced expressions.
+@deffn Command backward-sexp &optional arg
+This function moves backward across @var{arg} (default 1) balanced expressions.
@end deffn
@deffn Command beginning-of-defun arg
open-parenthesis syntax.
@end defopt
+@defopt open-paren-in-column-0-is-defun-start
+If this variable's value is non-@code{nil}, an open parenthesis in
+column 0 is considered to be the start of a defun. If it is
+@code{nil}, an open parenthesis in column 0 has no special meaning.
+The default is @code{t}.
+@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.
+@end defvar
+
@node Skipping Characters
@comment node-name, next, previous, up
@subsection Skipping Characters
characters. For example, they are often used to skip whitespace. For
related functions, see @ref{Motion and Syntax}.
+These functions convert the set string to multibyte if the buffer is
+multibyte, and they convert it to unibyte if the buffer is unibyte, as
+the search functions do (@pxref{Searching and Matching}).
+
@defun skip-chars-forward character-set &optional limit
This function moves point in the current buffer forward, skipping over a
given set of characters. It examines the character following point,
---------- Buffer: foo ----------
@end group
@end example
+
+Note that char classes are not currently supported in
+@var{character-set}; they will be treated as literals. Thus you
+cannot use @code{"[:alpha:]"} instead of @code{"a-zA-Z"} to include
+non-ASCII letters. A way to skip forward over all letters is:
+
+@example
+(re-search-forward "\\=[[:alpha:]]*" nil t)
+@end example
@end defun
@defun skip-chars-backward character-set &optional limit
value were outside the limits of the temporary narrowing, this would
fail to restore it accurately.
-The @code{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 @var{body} does further narrowing.
-However, @code{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, @code{save-restriction} is not the right
-tool for the job. Here is what you must use instead:
-
-@example
-@group
-(let ((beg (point-min-marker))
- (end (point-max-marker)))
- (unwind-protect
- (progn @var{body})
- (save-excursion
- (set-buffer (marker-buffer beg))
- (narrow-to-region beg end))))
-@end group
-@end example
-
Here is a simple example of correct use of @code{save-restriction}:
@example