@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 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/positions
-@node Positions, Markers, Frames, Top
+@node Positions
@chapter Positions
@cindex position (in buffer)
backward until encountering the front of a word, rather than forward.
@end deffn
-@defvar words-include-escapes
+@defopt words-include-escapes
@c Emacs 19 feature
This variable affects the behavior of @code{forward-word} and everything
that uses it. If it is non-@code{nil}, then characters in the
``escape'' and ``character quote'' syntax classes count as part of
words. Otherwise, they do not.
-@end defvar
+@end defopt
@defvar inhibit-field-text-motion
If this variable is non-@code{nil}, certain motion functions including
of the window, by line continuation in display, or by how tabs and
control characters are displayed.
-@deffn Command goto-line line
-This function moves point to the front of the @var{line}th line,
-counting from line 1 at beginning of the buffer. If @var{line} is less
-than 1, it moves point to the beginning of the buffer. If @var{line} is
-greater than the number of lines in the buffer, it moves point to the
-end of the buffer---that is, the @emph{end of the last line} of the
-buffer. This is the only case in which @code{goto-line} does not
-necessarily move to the beginning of a line.
-
-If narrowing is in effect, then @var{line} still counts from the
-beginning of the buffer, but point cannot go outside the accessible
-portion. So @code{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 @code{goto-line} is the difference between
-@var{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, @var{line} is the numeric prefix argument if
-one has been provided. Otherwise @var{line} is read in the minibuffer.
-@end deffn
-
@deffn Command beginning-of-line &optional count
This function moves point to the beginning of the current line. With an
argument @var{count} not @code{nil} or 1, it moves forward
1, even if @var{start} and @var{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.
+@end defun
-Here is an example of using @code{count-lines}:
+@deffn Command count-words start end
+@cindex words in region
+This function returns the number of words between the positions
+@var{start} and @var{end} in the current buffer.
-@example
-@group
-(defun current-line ()
- "Return the vertical position of point@dots{}"
- (+ (count-lines (window-start) (point))
- (if (= (current-column) 0) 1 0)))
-@end group
-@end example
-@end defun
+This function can also be called interactively. In that case, it
+prints a message reporting the number of lines, words, and characters
+in the buffer, or in the region if the region is active.
+@end deffn
@defun line-number-at-pos &optional pos
@cindex line number
screen lines down from the screen line containing point. If @var{count}
is negative, it moves up instead.
-@code{vertical-motion} returns the number of screen lines over which it
-moved point. The value may be less in absolute value than @var{count}
-if the beginning or end of the buffer was reached.
+The @var{count} argument can be a cons cell, @code{(@var{cols}
+. @var{lines})}, instead of an integer. Then the function moves by
+@var{lines} screen lines, and puts point @var{cols} columns from the
+start of that screen line.
+
+The return value is the number of screen lines over which point was
+moved. The value may be less in absolute value than @var{count} if
+the beginning or end of the buffer was reached.
The window @var{window} is used for obtaining parameters such as the
width, the horizontal scrolling, and the display table. But
@end defun
@node List Motion
-@comment node-name, next, previous, up
@subsection Moving over Balanced Expressions
@cindex sexp motion
@cindex Lisp expression motion
@defvar 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.
+calls this function instead of using its normal method, passing it its
+optional argument. If the argument is non-@code{nil}, the function
+should move back by that many functions, like
+@code{beginning-of-defun} does.
@end defvar
@defvar end-of-defun-function
@end defvar
@node Skipping Characters
-@comment node-name, next, previous, up
@subsection Skipping Characters
@cindex skipping characters
@group
(skip-chars-forward "a-zA-Z ")
- @result{} nil
+ @result{} 18
---------- Buffer: foo ----------
I read "The cat in the hat@point{}
@cindex excursion
It is often useful to move point ``temporarily'' within a localized
-portion of the program, or to switch buffers temporarily. This is
-called an @dfn{excursion}, and it is done with the @code{save-excursion}
-special form. This construct initially remembers the identity of the
-current buffer, and its values of point and the mark, and restores them
-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}).
+portion of the program. This is called an @dfn{excursion}, and it is
+done with the @code{save-excursion} special form. This construct
+remembers the initial identity of the current buffer, and its values
+of point and the mark, and restores them after the excursion
+completes. It is the standard way to move point within one part of a
+program and avoid affecting the rest of the program, and is used
+thousands of times in the Lisp sources of Emacs.
+
+ If you only need to save and restore the identity of the current
+buffer, use @code{save-current-buffer} or @code{with-current-buffer}
+instead (@pxref{Current Buffer}). If you need to save or restore
+window configurations, see the forms described in @ref{Window
+Configurations} and in @ref{Frame Configurations}.
@defspec save-excursion body@dots{}
@cindex mark excursion
@cindex point 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{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}).
+This special form saves the identity of the current buffer and the
+values of point and the mark in it, evaluates @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}).
-The @code{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.
+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.
+@end defspec
-@code{save-excursion} does not save the values of point and the mark for
-other buffers, so changes in other buffers remain in effect after
-@code{save-excursion} exits.
+ Because @code{save-excursion} only saves point and mark for the
+buffer that was current at the start of the excursion, any changes
+made to point and/or mark in other buffers, during the excursion, will
+remain in effect afterward. This frequently leads to unintended
+consequences, so the byte compiler warns if you call @code{set-buffer}
+during an excursion:
-@cindex window excursions
-Likewise, @code{save-excursion} does not restore window-buffer
-correspondences altered by functions such as @code{switch-to-buffer}.
-One way to restore these correspondences, and the selected window, is to
-use @code{save-window-excursion} inside @code{save-excursion}
-(@pxref{Window Configurations}).
+@example
+Warning: Use `with-current-buffer' rather than save-excursion+set-buffer
+@end example
-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.
+@noindent
+To avoid such problems, you should call @code{save-excursion} only
+after setting the desired current buffer, as in the following example:
@example
@group
-(save-excursion @var{forms})
-@equiv{}
-(let ((old-buf (current-buffer))
- (old-pnt (point-marker))
-@end group
- (old-mark (copy-marker (mark-marker))))
- (unwind-protect
- (progn @var{forms})
- (set-buffer old-buf)
-@group
- (goto-char old-pnt)
- (set-marker (mark-marker) old-mark)))
+(defun append-string-to-buffer (string buffer)
+ "Append STRING to the end of BUFFER."
+ (with-current-buffer buffer
+ (save-excursion
+ (goto-char (point-max))
+ (insert string))))
@end group
@end example
-@end defspec
+
+@cindex window excursions
+ Likewise, @code{save-excursion} does not restore window-buffer
+correspondences altered by functions such as @code{switch-to-buffer}.
+One way to restore these correspondences, and the selected window, is to
+use @code{save-window-excursion} inside @code{save-excursion}
+(@pxref{Window Configurations}).
@strong{Warning:} Ordinary insertion of text adjacent to the saved
-point value relocates the saved value, just as it relocates all markers.
-More precisely, the saved value is a marker with insertion type
-@code{nil}. @xref{Marker Insertion Types}. Therefore, when the saved
-point value is restored, it normally comes before the inserted text.
+point value relocates the saved value, just as it relocates all
+markers. More precisely, the saved value is a marker with insertion
+type @code{nil}. @xref{Marker Insertion Types}. Therefore, when the
+saved point value is restored, it normally comes before the inserted
+text.
Although @code{save-excursion} saves the location of the mark, it does
not prevent functions which modify the buffer from setting
The commands for saving buffers are unaffected by narrowing; they save
the entire buffer regardless of any narrowing.
+ If you need to display in a single buffer several very different
+types of text, consider using an alternative facility described in
+@ref{Swapping Text}.
+
@deffn Command narrow-to-region start end
This function sets the accessible portion of the current buffer to start
at @var{start} and end at @var{end}. Both arguments should be character
@end group
@end example
@end defspec
-
-@ignore
- arch-tag: 56e8ff26-4ffe-4832-a141-7e991a2d0f87
-@end ignore