1 @c -*- mode: texinfo; coding: utf-8 -*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-2016 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
7 @cindex position (in buffer)
8 @cindex buffer position
10 A @dfn{position} is the index of a character in the text of a buffer.
11 More precisely, a position identifies the place between two characters
12 (or before the first character, or after the last character), so we can
13 speak of the character before or after a given position. However, we
14 often speak of the character ``at'' a position, meaning the character
17 Positions are usually represented as integers starting from 1, but
18 can also be represented as @dfn{markers}---special objects that
19 relocate automatically when text is inserted or deleted so they stay
20 with the surrounding characters. Functions that expect an argument to
21 be a position (an integer), but accept a marker as a substitute,
22 normally ignore which buffer the marker points into; they convert the
23 marker to an integer, and use that integer, exactly as if you had
24 passed the integer as the argument, even if the marker points to the
25 wrong buffer. A marker that points nowhere cannot convert to an
26 integer; using it instead of an integer causes an error.
29 See also the field feature (@pxref{Fields}), which provides
30 functions that are used by many cursor-motion commands.
33 * Point:: The special position where editing takes place.
34 * Motion:: Changing point.
35 * Excursions:: Temporary motion and buffer changes.
36 * Narrowing:: Restricting editing to a portion of the buffer.
43 @dfn{Point} is a special buffer position used by many editing
44 commands, including the self-inserting typed characters and text
45 insertion functions. Other commands move point through the text
46 to allow editing and insertion at different places.
48 Like other positions, point designates a place between two characters
49 (or before the first character, or after the last character), rather
50 than a particular character. Usually terminals display the cursor over
51 the character that immediately follows point; point is actually before
52 the character on which the cursor sits.
54 @cindex point with narrowing
55 The value of point is a number no less than 1, and no greater than the
56 buffer size plus 1. If narrowing is in effect (@pxref{Narrowing}), then
57 point is constrained to fall within the accessible portion of the buffer
58 (possibly at one end of it).
60 Each buffer has its own value of point, which is independent of the
61 value of point in other buffers. Each window also has a value of point,
62 which is independent of the value of point in other windows on the same
63 buffer. This is why point can have different values in various windows
64 that display the same buffer. When a buffer appears in only one window,
65 the buffer's point and the window's point normally have the same value,
66 so the distinction is rarely important. @xref{Window Point}, for more
70 @cindex current buffer position
71 This function returns the value of point in the current buffer,
84 This function returns the minimum accessible value of point in the
85 current buffer. This is normally 1, but if narrowing is in effect, it
86 is the position of the start of the region that you narrowed to.
91 This function returns the maximum accessible value of point in the
92 current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is
93 in effect, in which case it is the position of the end of the region
94 that you narrowed to. (@xref{Narrowing}.)
97 @defun buffer-end flag
98 This function returns @code{(point-max)} if @var{flag} is greater than
99 0, @code{(point-min)} otherwise. The argument @var{flag} must be a
103 @defun buffer-size &optional buffer
104 This function returns the total number of characters in the current
105 buffer. In the absence of any narrowing (@pxref{Narrowing}),
106 @code{point-max} returns a value one larger than this.
108 If you specify a buffer, @var{buffer}, then the value is the
109 size of @var{buffer}.
125 @cindex motion by chars, words, lines, lists
127 Motion functions change the value of point, either relative to the
128 current value of point, relative to the beginning or end of the buffer,
129 or relative to the edges of the selected window. @xref{Point}.
132 * Character Motion:: Moving in terms of characters.
133 * Word Motion:: Moving in terms of words.
134 * Buffer End Motion:: Moving to the beginning or end of the buffer.
135 * Text Lines:: Moving in terms of lines of text.
136 * Screen Lines:: Moving in terms of lines as displayed.
137 * List Motion:: Moving by parsing lists and sexps.
138 * Skipping Characters:: Skipping characters belonging to a certain set.
141 @node Character Motion
142 @subsection Motion by Characters
144 These functions move point based on a count of characters.
145 @code{goto-char} is the fundamental primitive; the other functions use
148 @deffn Command goto-char position
149 This function sets point in the current buffer to the value
151 @c This behavior used to be documented until 2013/08.
153 If @var{position} is less than 1, it moves point to the beginning of
154 the buffer. If @var{position} is greater than the length of the
155 buffer, it moves point to the end.
158 If narrowing is in effect, @var{position} still counts from the
159 beginning of the buffer, but point cannot go outside the accessible
160 portion. If @var{position} is out of range, @code{goto-char} moves
161 point to the beginning or the end of the accessible portion.
163 When this function is called interactively, @var{position} is the
164 numeric prefix argument, if provided; otherwise it is read from the
167 @code{goto-char} returns @var{position}.
170 @deffn Command forward-char &optional count
171 @c @kindex beginning-of-buffer
172 @c @kindex end-of-buffer
173 This function moves point @var{count} characters forward, towards the
174 end of the buffer (or backward, towards the beginning of the buffer, if
175 @var{count} is negative). If @var{count} is @code{nil}, the default
178 If this attempts to move past the beginning or end of the buffer (or
179 the limits of the accessible portion, when narrowing is in effect), it
180 signals an error with error symbol @code{beginning-of-buffer} or
181 @code{end-of-buffer}.
183 In an interactive call, @var{count} is the numeric prefix argument.
186 @deffn Command backward-char &optional count
187 This is just like @code{forward-char} except that it moves
188 in the opposite direction.
192 @subsection Motion by Words
194 The functions for parsing words described below use the syntax table
195 to decide whether a given character is part of a word. @xref{Syntax
198 @deffn Command forward-word &optional count
199 This function moves point forward @var{count} words (or backward if
200 @var{count} is negative). If @var{count} is omitted or @code{nil}, it
201 defaults to 1. In an interactive call, @var{count} is specified by
202 the numeric prefix argument.
204 ``Moving one word'' means moving until point crosses a
205 word-constituent character, which indicates the beginning of a word,
206 and then continue moving until the word ends. By default, characters
207 that begin and end words, known as @dfn{word boundaries}, are defined
208 by the current buffer's syntax table (@pxref{Syntax Class Table}), but
209 modes can override that by setting up a suitable
210 @code{find-word-boundary-function-table}, described below. In any
211 case, this function cannot move point past the boundary of the
212 accessible portion of the buffer, or across a field boundary
213 (@pxref{Fields}). The most common case of a field boundary is the end
214 of the prompt in the minibuffer.
216 If it is possible to move @var{count} words, without being stopped
217 prematurely by the buffer boundary or a field boundary, the value is
218 @code{t}. Otherwise, the return value is @code{nil} and point stops at
219 the buffer boundary or field boundary.
221 If @code{inhibit-field-text-motion} is non-@code{nil},
222 this function ignores field boundaries.
226 @deffn Command backward-word &optional count
227 This function is just like @code{forward-word}, except that it moves
228 backward until encountering the front of a word, rather than forward.
231 @defopt words-include-escapes
233 This variable affects the behavior of @code{forward-word} and
234 @code{backward-word}, and everything that uses them. If it is
235 non-@code{nil}, then characters in the escape and character-quote
236 syntax classes count as part of words. Otherwise, they do not.
239 @defvar inhibit-field-text-motion
240 If this variable is non-@code{nil}, certain motion functions including
241 @code{forward-word}, @code{forward-sentence}, and
242 @code{forward-paragraph} ignore field boundaries.
245 @defvar find-word-boundary-function-table
246 This variable affects the behavior of @code{forward-word} and
247 @code{backward-word}, and everything that uses them. Its value is a
248 char-table (@pxref{Char-Tables}) of functions to search for word
249 boundaries. If a character has a non-@code{nil} entry in this table,
250 then when a word starts or ends with that character, the corresponding
251 function will be called with 2 arguments: @var{pos} and @var{limit}.
252 The function should return the position of the other word boundary.
253 Specifically, if @var{pos} is smaller than @var{limit}, then @var{pos}
254 is at the beginning of a word, and the function should return the
255 position after the last character of the word; otherwise, @var{pos} is
256 at the last character of a word, and the function should return the
257 position of that word's first character.
260 @defun forward-word-strictly &optional count
261 This function is like @code{forward-word}, but it is not affected by
262 @code{find-word-boundary-function-table}. Lisp programs that should
263 not change behavior when word movement is modified by modes which set
264 that table, such as @code{subword-mode}, should use this function
265 instead of @code{forward-word}.
268 @defun backward-word-strictly &optional count
269 This function is like @code{backward-word}, but it is not affected by
270 @code{find-word-boundary-function-table}. Like with
271 @code{forward-word-strictly}, use this function instead of
272 @code{backward-word} when movement by words should only consider
276 @node Buffer End Motion
277 @subsection Motion to an End of the Buffer
278 @cindex move to beginning or end of buffer
280 To move point to the beginning of the buffer, write:
284 (goto-char (point-min))
289 Likewise, to move to the end of the buffer, use:
293 (goto-char (point-max))
297 Here are two commands that users use to do these things. They are
298 documented here to warn you not to use them in Lisp programs, because
299 they set the mark and display messages in the echo area.
301 @deffn Command beginning-of-buffer &optional n
302 This function moves point to the beginning of the buffer (or the limits
303 of the accessible portion, when narrowing is in effect), setting the
304 mark at the previous position (except in Transient Mark mode, if
305 the mark is already active, it does not set the mark.)
307 If @var{n} is non-@code{nil}, then it puts point @var{n} tenths of the
308 way from the beginning of the accessible portion of the buffer. In an
309 interactive call, @var{n} is the numeric prefix argument, if provided;
310 otherwise @var{n} defaults to @code{nil}.
312 @strong{Warning:} Don't use this function in Lisp programs!
315 @deffn Command end-of-buffer &optional n
316 This function moves point to the end of the buffer (or the limits of
317 the accessible portion, when narrowing is in effect), setting the mark
318 at the previous position (except in Transient Mark mode when the mark
319 is already active). If @var{n} is non-@code{nil}, then it puts point
320 @var{n} tenths of the way from the end of the accessible portion of
323 In an interactive call, @var{n} is the numeric prefix argument,
324 if provided; otherwise @var{n} defaults to @code{nil}.
326 @strong{Warning:} Don't use this function in Lisp programs!
330 @subsection Motion by Text Lines
333 Text lines are portions of the buffer delimited by newline characters,
334 which are regarded as part of the previous line. The first text line
335 begins at the beginning of the buffer, and the last text line ends at
336 the end of the buffer whether or not the last character is a newline.
337 The division of the buffer into text lines is not affected by the width
338 of the window, by line continuation in display, or by how tabs and
339 control characters are displayed.
341 @deffn Command beginning-of-line &optional count
342 This function moves point to the beginning of the current line. With an
343 argument @var{count} not @code{nil} or 1, it moves forward
344 @var{count}@minus{}1 lines and then to the beginning of the line.
346 This function does not move point across a field boundary
347 (@pxref{Fields}) unless doing so would move beyond there to a
348 different line; therefore, if @var{count} is @code{nil} or 1, and
349 point starts at a field boundary, point does not move. To ignore
350 field boundaries, either bind @code{inhibit-field-text-motion} to
351 @code{t}, or use the @code{forward-line} function instead. For
352 instance, @code{(forward-line 0)} does the same thing as
353 @code{(beginning-of-line)}, except that it ignores field boundaries.
355 If this function reaches the end of the buffer (or of the accessible
356 portion, if narrowing is in effect), it positions point there. No error
360 @defun line-beginning-position &optional count
361 Return the position that @code{(beginning-of-line @var{count})}
365 @deffn Command end-of-line &optional count
366 This function moves point to the end of the current line. With an
367 argument @var{count} not @code{nil} or 1, it moves forward
368 @var{count}@minus{}1 lines and then to the end of the line.
370 This function does not move point across a field boundary
371 (@pxref{Fields}) unless doing so would move beyond there to a
372 different line; therefore, if @var{count} is @code{nil} or 1, and
373 point starts at a field boundary, point does not move. To ignore
374 field boundaries, bind @code{inhibit-field-text-motion} to @code{t}.
376 If this function reaches the end of the buffer (or of the accessible
377 portion, if narrowing is in effect), it positions point there. No error
381 @defun line-end-position &optional count
382 Return the position that @code{(end-of-line @var{count})}
386 @deffn Command forward-line &optional count
387 @cindex beginning of line
388 This function moves point forward @var{count} lines, to the beginning of
389 the line following that. If @var{count} is negative, it moves point
390 @minus{}@var{count} lines backward, to the beginning of a line
391 preceding that. If @var{count} is zero, it moves point to the
392 beginning of the current line. If @var{count} is @code{nil}, that
395 If @code{forward-line} encounters the beginning or end of the buffer (or
396 of the accessible portion) before finding that many lines, it sets point
397 there. No error is signaled.
399 @code{forward-line} returns the difference between @var{count} and the
400 number of lines actually moved. If you attempt to move down five lines
401 from the beginning of a buffer that has only three lines, point stops at
402 the end of the last line, and the value will be 2. As an explicit
403 exception, if the last accessible line is non-empty, but has no
404 newline (e.g., if the buffer ends without a newline), the function
405 sets point to the end of that line, and the value returned by the
406 function counts that line as one line successfully moved.
408 In an interactive call, @var{count} is the numeric prefix argument.
411 @defun count-lines start end
412 @cindex lines in region
413 @anchor{Definition of count-lines}
414 This function returns the number of lines between the positions
415 @var{start} and @var{end} in the current buffer. If @var{start} and
416 @var{end} are equal, then it returns 0. Otherwise it returns at least
417 1, even if @var{start} and @var{end} are on the same line. This is
418 because the text between them, considered in isolation, must contain at
419 least one line unless it is empty.
422 @deffn Command count-words start end
423 @cindex words in region
424 This function returns the number of words between the positions
425 @var{start} and @var{end} in the current buffer.
427 This function can also be called interactively. In that case, it
428 prints a message reporting the number of lines, words, and characters
429 in the buffer, or in the region if the region is active.
432 @defun line-number-at-pos &optional pos
434 This function returns the line number in the current buffer
435 corresponding to the buffer position @var{pos}. If @var{pos} is @code{nil}
436 or omitted, the current buffer position is used.
441 The @code{previous-line} and @code{next-line} commands are functions
442 that should not be used in programs. They are for users and are
443 mentioned here only for completeness.
445 @deffn Command previous-line count
447 This function moves point up @var{count} lines (down if @var{count}
448 is negative). In moving, it attempts to keep point in the @dfn{goal column}
449 (normally the same column that it was at the beginning of the move).
451 If there is no character in the target line exactly under the current
452 column, point is positioned after the character in that line which
453 spans this column, or at the end of the line if it is not long enough.
455 If it attempts to move beyond the top or bottom of the buffer (or clipped
456 region), then point is positioned in the goal column in the top or
457 bottom line. No error is signaled.
459 In an interactive call, @var{count} will be the numeric
462 The command @code{set-goal-column} can be used to create a semipermanent
463 goal column to which this command always moves. Then it does not try to
466 If you are thinking of using this in a Lisp program, consider using
467 @code{forward-line} with a negative argument instead. It is usually easier
468 to use and more reliable (no dependence on goal column, etc.).
471 @deffn Command next-line count
472 This function moves point down @var{count} lines (up if @var{count}
473 is negative). In moving, it attempts to keep point in the goal column
474 (normally the same column that it was at the beginning of the move).
476 If there is no character in the target line exactly under the current
477 column, point is positioned after the character in that line which
478 spans this column, or at the end of the line if it is not long enough.
480 If it attempts to move beyond the top or bottom of the buffer (or clipped
481 region), then point is positioned in the goal column in the top or
482 bottom line. No error is signaled.
484 In the case where the @var{count} is 1, and point is on the last
485 line of the buffer (or clipped region), a new empty line is inserted at the
486 end of the buffer (or clipped region) and point moved there.
488 In an interactive call, @var{count} will be the numeric
491 The command @code{set-goal-column} can be used to create a semipermanent
492 goal column to which this command always moves. Then it does not try to
495 If you are thinking of using this in a Lisp program, consider using
496 @code{forward-line} instead. It is usually easier
497 to use and more reliable (no dependence on goal column, etc.).
503 Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}.
504 These functions do not move point, but test whether it is already at the
505 beginning or end of a line.
508 @subsection Motion by Screen Lines
509 @cindex screen lines, moving by
511 The line functions in the previous section count text lines, delimited
512 only by newline characters. By contrast, these functions count screen
513 lines, which are defined by the way the text appears on the screen. A
514 text line is a single screen line if it is short enough to fit the width
515 of the selected window, but otherwise it may occupy several screen
518 In some cases, text lines are truncated on the screen rather than
519 continued onto additional screen lines. In these cases,
520 @code{vertical-motion} moves point much like @code{forward-line}.
523 Because the width of a given string depends on the flags that control
524 the appearance of certain characters, @code{vertical-motion} behaves
525 differently, for a given piece of text, depending on the buffer it is
526 in, and even on the selected window (because the width, the truncation
527 flag, and display table may vary between windows). @xref{Usual
530 These functions scan text to determine where screen lines break, and
531 thus take time proportional to the distance scanned.
533 If you intend to use them heavily, Emacs provides caches which may
534 improve the performance of your code. @xref{Truncation, cache-long-scans}.
537 @defun vertical-motion count &optional window cur-col
538 This function moves point to the start of the screen line @var{count}
539 screen lines down from the screen line containing point. If @var{count}
540 is negative, it moves up instead.
542 The @var{count} argument can be a cons cell, @code{(@var{cols}
543 . @var{lines})}, instead of an integer. Then the function moves by
544 @var{lines} screen lines, and puts point @var{cols} columns from the
545 visual start of that screen line. Note that @var{cols} are counted
546 from the @emph{visual} start of the line; if the window is scrolled
547 horizontally (@pxref{Horizontal Scrolling}), the column on which point
548 will end is in addition to the number of columns by which the text is
551 The return value is the number of screen lines over which point was
552 moved. The value may be less in absolute value than @var{count} if
553 the beginning or end of the buffer was reached.
555 The window @var{window} is used for obtaining parameters such as the
556 width, the horizontal scrolling, and the display table. But
557 @code{vertical-motion} always operates on the current buffer, even if
558 @var{window} currently displays some other buffer.
560 The optional argument @var{cur-col} specifies the current column when
561 the function is called. This is the window-relative horizontal
562 coordinate of point, measured in units of font width of the frame's
563 default face. Providing it speeds up the function, especially in very
564 long lines, because it doesn't have to go back in the buffer in order
565 to determine the current column. Note that @var{cur-col} is also
566 counted from the visual start of the line.
569 @defun count-screen-lines &optional beg end count-final-newline window
570 This function returns the number of screen lines in the text from
571 @var{beg} to @var{end}. The number of screen lines may be different
572 from the number of actual lines, due to line continuation, the display
573 table, etc. If @var{beg} and @var{end} are @code{nil} or omitted,
574 they default to the beginning and end of the accessible portion of the
577 If the region ends with a newline, that is ignored unless the optional
578 third argument @var{count-final-newline} is non-@code{nil}.
580 The optional fourth argument @var{window} specifies the window for
581 obtaining parameters such as width, horizontal scrolling, and so on.
582 The default is to use the selected window's parameters.
584 Like @code{vertical-motion}, @code{count-screen-lines} always uses the
585 current buffer, regardless of which buffer is displayed in
586 @var{window}. This makes possible to use @code{count-screen-lines} in
587 any buffer, whether or not it is currently displayed in some window.
590 @deffn Command move-to-window-line count
591 This function moves point with respect to the text currently displayed
592 in the selected window. It moves point to the beginning of the screen
593 line @var{count} screen lines from the top of the window; zero means
594 the topmost line. If @var{count} is negative, that specifies a
595 position @w{@minus{}@var{count}} lines from the bottom (or the last
596 line of the buffer, if the buffer ends above the specified screen
597 position); thus, @var{count} of -1 specifies the last fully visible
598 screen line of the window.
600 If @var{count} is @code{nil}, then point moves to the beginning of the
601 line in the middle of the window. If the absolute value of @var{count}
602 is greater than the size of the window, then point moves to the place
603 that would appear on that screen line if the window were tall enough.
604 This will probably cause the next redisplay to scroll to bring that
605 location onto the screen.
607 In an interactive call, @var{count} is the numeric prefix argument.
609 The value returned is the screen line number point has moved to,
610 relative to the top line of the window.
613 @vindex move-to-window-group-line-function
614 @defun move-to-window-group-line count
615 This function is like @code{move-to-window-line}, except that when the
616 selected window is a part of a group of windows (@pxref{Window
617 Group}), @code{move-to-window-group-line} will move to a position with
618 respect to the entire group, not just the single window. This
619 condition holds when the buffer local variable
620 @code{move-to-window-group-line-function} is set to a function. In
621 this case, @code{move-to-window-group-line} calls the function with
622 the argument @var{count}, then returns its result.
625 @defun compute-motion from frompos to topos width offsets window
626 This function scans the current buffer, calculating screen positions.
627 It scans the buffer forward from position @var{from}, assuming that is
628 at screen coordinates @var{frompos}, to position @var{to} or coordinates
629 @var{topos}, whichever comes first. It returns the ending buffer
630 position and screen coordinates.
632 The coordinate arguments @var{frompos} and @var{topos} are cons cells of
633 the form @code{(@var{hpos} . @var{vpos})}.
635 The argument @var{width} is the number of columns available to display
636 text; this affects handling of continuation lines. @code{nil} means
637 the actual number of usable text columns in the window, which is
638 equivalent to the value returned by @code{(window-width window)}.
640 The argument @var{offsets} is either @code{nil} or a cons cell of the
641 form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is
642 the number of columns not being displayed at the left margin; most
643 callers get this by calling @code{window-hscroll}. Meanwhile,
644 @var{tab-offset} is the offset between column numbers on the screen and
645 column numbers in the buffer. This can be nonzero in a continuation
646 line, when the previous screen lines' widths do not add up to a multiple
647 of @code{tab-width}. It is always zero in a non-continuation line.
649 The window @var{window} serves only to specify which display table to
650 use. @code{compute-motion} always operates on the current buffer,
651 regardless of what buffer is displayed in @var{window}.
653 The return value is a list of five elements:
656 (@var{pos} @var{hpos} @var{vpos} @var{prevhpos} @var{contin})
660 Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
661 is the vertical screen position, and @var{hpos} is the horizontal screen
664 The result @var{prevhpos} is the horizontal position one character back
665 from @var{pos}. The result @var{contin} is @code{t} if the last line
666 was continued after (or within) the previous character.
668 For example, to find the buffer position of column @var{col} of screen line
669 @var{line} of a certain window, pass the window's display start location
670 as @var{from} and the window's upper-left coordinates as @var{frompos}.
671 Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
672 the end of the accessible portion of the buffer, and pass @var{line} and
673 @var{col} as @var{topos}. Here's a function that does this:
676 (defun coordinates-of-position (col line)
677 (car (compute-motion (window-start)
682 (cons (window-hscroll) 0)
686 When you use @code{compute-motion} for the minibuffer, you need to use
687 @code{minibuffer-prompt-width} to get the horizontal position of the
688 beginning of the first screen line. @xref{Minibuffer Contents}.
692 @subsection Moving over Balanced Expressions
694 @cindex Lisp expression motion
696 @cindex balanced parenthesis motion
698 Here are several functions concerned with balanced-parenthesis
699 expressions (also called @dfn{sexps} in connection with moving across
700 them in Emacs). The syntax table controls how these functions interpret
701 various characters; see @ref{Syntax Tables}. @xref{Parsing
702 Expressions}, for lower-level primitives for scanning sexps or parts of
703 sexps. For user-level commands, see @ref{Parentheses,, Commands for
704 Editing with Parentheses, emacs, The GNU Emacs Manual}.
706 @deffn Command forward-list &optional arg
707 This function moves forward across @var{arg} (default 1) balanced groups of
708 parentheses. (Other syntactic entities such as words or paired string
712 @deffn Command backward-list &optional arg
713 This function moves backward across @var{arg} (default 1) balanced groups of
714 parentheses. (Other syntactic entities such as words or paired string
718 @deffn Command up-list &optional arg escape-strings no-syntax-crossing
719 This function moves forward out of @var{arg} (default 1) levels of
720 parentheses. A negative argument means move backward but still to a
721 less deep spot. If @var{escape-strings} is non-@code{nil} (as it is
722 interactively), move out of enclosing strings as well. If
723 @var{no-syntax-crossing} is non-@code{nil} (as it is interactively), prefer
724 to break out of any enclosing string instead of moving to the start of
725 a list broken across multiple strings. On error, location of point is
729 @deffn Command backward-up-list &optional arg escape-strings no-syntax-crossing
730 This function is just like @code{up-list}, but with a negated argument.
733 @deffn Command down-list &optional arg
734 This function moves forward into @var{arg} (default 1) levels of
735 parentheses. A negative argument means move backward but still go
736 deeper in parentheses (@minus{}@var{arg} levels).
739 @deffn Command forward-sexp &optional arg
740 This function moves forward across @var{arg} (default 1) balanced expressions.
741 Balanced expressions include both those delimited by parentheses and
742 other kinds, such as words and string constants.
743 @xref{Parsing Expressions}. For example,
747 ---------- Buffer: foo ----------
748 (concat@point{} "foo " (car x) y z)
749 ---------- Buffer: foo ----------
756 ---------- Buffer: foo ----------
757 (concat "foo " (car x) y@point{} z)
758 ---------- Buffer: foo ----------
763 @deffn Command backward-sexp &optional arg
764 This function moves backward across @var{arg} (default 1) balanced expressions.
767 @deffn Command beginning-of-defun &optional arg
768 This function moves back to the @var{arg}th beginning of a defun. If
769 @var{arg} is negative, this actually moves forward, but it still moves
770 to the beginning of a defun, not to the end of one. @var{arg} defaults
774 @deffn Command end-of-defun &optional arg
775 This function moves forward to the @var{arg}th end of a defun. If
776 @var{arg} is negative, this actually moves backward, but it still moves
777 to the end of a defun, not to the beginning of one. @var{arg} defaults
781 @defopt defun-prompt-regexp
782 If non-@code{nil}, this buffer-local variable holds a regular
783 expression that specifies what text can appear before the
784 open-parenthesis that starts a defun. That is to say, a defun begins
785 on a line that starts with a match for this regular expression,
786 followed by a character with open-parenthesis syntax.
789 @defopt open-paren-in-column-0-is-defun-start
790 If this variable's value is non-@code{nil}, an open parenthesis in
791 column 0 is considered to be the start of a defun. If it is
792 @code{nil}, an open parenthesis in column 0 has no special meaning.
793 The default is @code{t}.
796 @defvar beginning-of-defun-function
797 If non-@code{nil}, this variable holds a function for finding the
798 beginning of a defun. The function @code{beginning-of-defun}
799 calls this function instead of using its normal method, passing it its
800 optional argument. If the argument is non-@code{nil}, the function
801 should move back by that many functions, like
802 @code{beginning-of-defun} does.
805 @defvar end-of-defun-function
806 If non-@code{nil}, this variable holds a function for finding the end of
807 a defun. The function @code{end-of-defun} calls this function instead
808 of using its normal method.
811 @node Skipping Characters
812 @subsection Skipping Characters
813 @cindex skipping characters
815 The following two functions move point over a specified set of
816 characters. For example, they are often used to skip whitespace. For
817 related functions, see @ref{Motion and Syntax}.
819 These functions convert the set string to multibyte if the buffer is
820 multibyte, and they convert it to unibyte if the buffer is unibyte, as
821 the search functions do (@pxref{Searching and Matching}).
823 @defun skip-chars-forward character-set &optional limit
824 This function moves point in the current buffer forward, skipping over a
825 given set of characters. It examines the character following point,
826 then advances point if the character matches @var{character-set}. This
827 continues until it reaches a character that does not match. The
828 function returns the number of characters moved over.
830 The argument @var{character-set} is a string, like the inside of a
831 @samp{[@dots{}]} in a regular expression except that @samp{]} does not
832 terminate it, and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}.
833 Thus, @code{"a-zA-Z"} skips over all letters, stopping before the
834 first nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before
835 the first letter. See @xref{Regular Expressions}. Character classes
836 can also be used, e.g., @code{"[:alnum:]"}. See @pxref{Char Classes}.
838 If @var{limit} is supplied (it must be a number or a marker), it
839 specifies the maximum position in the buffer that point can be skipped
840 to. Point will stop at or before @var{limit}.
842 In the following example, point is initially located directly before the
843 @samp{T}. After the form is evaluated, point is located at the end of
844 that line (between the @samp{t} of @samp{hat} and the newline). The
845 function skips all letters and spaces, but not newlines.
849 ---------- Buffer: foo ----------
850 I read "@point{}The cat in the hat
852 ---------- Buffer: foo ----------
856 (skip-chars-forward "a-zA-Z ")
859 ---------- Buffer: foo ----------
860 I read "The cat in the hat@point{}
862 ---------- Buffer: foo ----------
867 @defun skip-chars-backward character-set &optional limit
868 This function moves point backward, skipping characters that match
869 @var{character-set}, until @var{limit}. It is just like
870 @code{skip-chars-forward} except for the direction of motion.
872 The return value indicates the distance traveled. It is an integer that
880 It is often useful to move point temporarily within a localized
881 portion of the program. This is called an @dfn{excursion}, and it is
882 done with the @code{save-excursion} special form. This construct
883 remembers the initial identity of the current buffer, and its value
884 of point, and restores them after the excursion
885 completes. It is the standard way to move point within one part of a
886 program and avoid affecting the rest of the program, and is used
887 thousands of times in the Lisp sources of Emacs.
889 If you only need to save and restore the identity of the current
890 buffer, use @code{save-current-buffer} or @code{with-current-buffer}
891 instead (@pxref{Current Buffer}). If you need to save or restore
892 window configurations, see the forms described in @ref{Window
893 Configurations} and in @ref{Frame Configurations}. @c frameset?
895 @defspec save-excursion body@dots{}
896 @cindex point excursion
897 This special form saves the identity of the current buffer and the
898 value of point in it, evaluates @var{body}, and finally
899 restores the buffer and its saved value of point. Both saved values are
900 restored even in case of an abnormal exit via
901 @code{throw} or error (@pxref{Nonlocal Exits}).
903 The value returned by @code{save-excursion} is the result of the last
904 form in @var{body}, or @code{nil} if no body forms were given.
907 Because @code{save-excursion} only saves point for the
908 buffer that was current at the start of the excursion, any changes
909 made to point in other buffers, during the excursion, will
910 remain in effect afterward. This frequently leads to unintended
911 consequences, so the byte compiler warns if you call @code{set-buffer}
915 Warning: Use ‘with-current-buffer’ rather than
916 save-excursion+set-buffer
920 To avoid such problems, you should call @code{save-excursion} only
921 after setting the desired current buffer, as in the following example:
925 (defun append-string-to-buffer (string buffer)
926 "Append STRING to the end of BUFFER."
927 (with-current-buffer buffer
929 (goto-char (point-max))
934 @cindex window excursions
935 Likewise, @code{save-excursion} does not restore window-buffer
936 correspondences altered by functions such as @code{switch-to-buffer}.
938 @strong{Warning:} Ordinary insertion of text adjacent to the saved
939 point value relocates the saved value, just as it relocates all
940 markers. More precisely, the saved value is a marker with insertion
941 type @code{nil}. @xref{Marker Insertion Types}. Therefore, when the
942 saved point value is restored, it normally comes before the inserted
945 @defmac save-mark-and-excursion body@dots{}
946 @cindex mark excursion
947 @cindex point excursion
948 This macro is like @code{save-excursion}, but also saves and restores
949 the mark location and @code{mark-active}. This macro does what
950 @code{save-excursion} did before Emacs 25.1.
956 @cindex restriction (in a buffer)
957 @cindex accessible portion (of a buffer)
959 @dfn{Narrowing} means limiting the text addressable by Emacs editing
960 commands to a limited range of characters in a buffer. The text that
961 remains addressable is called the @dfn{accessible portion} of the
964 Narrowing is specified with two buffer positions, which become the
965 beginning and end of the accessible portion. For most editing
966 commands and primitives, these positions replace the values of the
967 beginning and end of the buffer. While narrowing is in effect, no
968 text outside the accessible portion is displayed, and point cannot
969 move outside the accessible portion. Note that narrowing does not
970 alter actual buffer positions (@pxref{Point}); it only determines
971 which positions are considered the accessible portion of the buffer.
972 Most functions refuse to operate on text that is outside the
975 Commands for saving buffers are unaffected by narrowing; they save
976 the entire buffer regardless of any narrowing.
978 If you need to display in a single buffer several very different
979 types of text, consider using an alternative facility described in
982 @deffn Command narrow-to-region start end
983 This function sets the accessible portion of the current buffer to start
984 at @var{start} and end at @var{end}. Both arguments should be character
987 In an interactive call, @var{start} and @var{end} are set to the bounds
988 of the current region (point and the mark, with the smallest first).
991 @deffn Command narrow-to-page &optional move-count
992 This function sets the accessible portion of the current buffer to
993 include just the current page. An optional first argument
994 @var{move-count} non-@code{nil} means to move forward or backward by
995 @var{move-count} pages and then narrow to one page. The variable
996 @code{page-delimiter} specifies where pages start and end
997 (@pxref{Standard Regexps}).
999 In an interactive call, @var{move-count} is set to the numeric prefix
1003 @deffn Command widen
1005 This function cancels any narrowing in the current buffer, so that the
1006 entire contents are accessible. This is called @dfn{widening}.
1007 It is equivalent to the following expression:
1010 (narrow-to-region 1 (1+ (buffer-size)))
1014 @defun buffer-narrowed-p
1015 This function returns non-@code{nil} if the buffer is narrowed, and
1016 @code{nil} otherwise.
1019 @defspec save-restriction body@dots{}
1020 This special form saves the current bounds of the accessible portion,
1021 evaluates the @var{body} forms, and finally restores the saved bounds,
1022 thus restoring the same state of narrowing (or absence thereof) formerly
1023 in effect. The state of narrowing is restored even in the event of an
1024 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
1025 Therefore, this construct is a clean way to narrow a buffer temporarily.
1027 The value returned by @code{save-restriction} is that returned by the
1028 last form in @var{body}, or @code{nil} if no body forms were given.
1030 @c Wordy to avoid overfull hbox. --rjc 16mar92
1031 @strong{Caution:} it is easy to make a mistake when using the
1032 @code{save-restriction} construct. Read the entire description here
1035 If @var{body} changes the current buffer, @code{save-restriction} still
1036 restores the restrictions on the original buffer (the buffer whose
1037 restrictions it saved from), but it does not restore the identity of the
1040 @code{save-restriction} does @emph{not} restore point; use
1041 @code{save-excursion} for that. If you use both @code{save-restriction}
1042 and @code{save-excursion} together, @code{save-excursion} should come
1043 first (on the outside). Otherwise, the old point value would be
1044 restored with temporary narrowing still in effect. If the old point
1045 value were outside the limits of the temporary narrowing, this would
1046 fail to restore it accurately.
1048 Here is a simple example of correct use of @code{save-restriction}:
1052 ---------- Buffer: foo ----------
1053 This is the contents of foo
1054 This is the contents of foo
1055 This is the contents of foo@point{}
1056 ---------- Buffer: foo ----------
1064 (narrow-to-region 1 (point))
1065 (goto-char (point-min))
1066 (replace-string "foo" "bar")))
1068 ---------- Buffer: foo ----------
1069 This is the contents of bar
1070 This is the contents of bar
1071 This is the contents of foo@point{}
1072 ---------- Buffer: foo ----------