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. If
594 @var{count} is negative, that specifies a position
595 @w{@minus{}@var{count}} lines from the bottom (or the last line of the
596 buffer, if the buffer ends above the specified screen position).
598 If @var{count} is @code{nil}, then point moves to the beginning of the
599 line in the middle of the window. If the absolute value of @var{count}
600 is greater than the size of the window, then point moves to the place
601 that would appear on that screen line if the window were tall enough.
602 This will probably cause the next redisplay to scroll to bring that
603 location onto the screen.
605 In an interactive call, @var{count} is the numeric prefix argument.
607 The value returned is the window line number point has moved to, with
608 the top line in the window numbered 0.
611 @vindex move-to-window-group-line-function
612 @defun move-to-window-group-line count
613 This function is like @code{move-to-window-line}, except that when the
614 selected window is a part of a group of windows (@pxref{Window
615 Group}), @code{move-to-window-group-line} will move to a position with
616 respect to the entire group, not just the single window. This
617 condition holds when the buffer local variable
618 @code{move-to-window-group-line-function} is set to a function. In
619 this case, @code{move-to-window-group-line} calls the function with
620 the argument @var{count}, then returns its result.
623 @defun compute-motion from frompos to topos width offsets window
624 This function scans the current buffer, calculating screen positions.
625 It scans the buffer forward from position @var{from}, assuming that is
626 at screen coordinates @var{frompos}, to position @var{to} or coordinates
627 @var{topos}, whichever comes first. It returns the ending buffer
628 position and screen coordinates.
630 The coordinate arguments @var{frompos} and @var{topos} are cons cells of
631 the form @code{(@var{hpos} . @var{vpos})}.
633 The argument @var{width} is the number of columns available to display
634 text; this affects handling of continuation lines. @code{nil} means
635 the actual number of usable text columns in the window, which is
636 equivalent to the value returned by @code{(window-width window)}.
638 The argument @var{offsets} is either @code{nil} or a cons cell of the
639 form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is
640 the number of columns not being displayed at the left margin; most
641 callers get this by calling @code{window-hscroll}. Meanwhile,
642 @var{tab-offset} is the offset between column numbers on the screen and
643 column numbers in the buffer. This can be nonzero in a continuation
644 line, when the previous screen lines' widths do not add up to a multiple
645 of @code{tab-width}. It is always zero in a non-continuation line.
647 The window @var{window} serves only to specify which display table to
648 use. @code{compute-motion} always operates on the current buffer,
649 regardless of what buffer is displayed in @var{window}.
651 The return value is a list of five elements:
654 (@var{pos} @var{hpos} @var{vpos} @var{prevhpos} @var{contin})
658 Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
659 is the vertical screen position, and @var{hpos} is the horizontal screen
662 The result @var{prevhpos} is the horizontal position one character back
663 from @var{pos}. The result @var{contin} is @code{t} if the last line
664 was continued after (or within) the previous character.
666 For example, to find the buffer position of column @var{col} of screen line
667 @var{line} of a certain window, pass the window's display start location
668 as @var{from} and the window's upper-left coordinates as @var{frompos}.
669 Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
670 the end of the accessible portion of the buffer, and pass @var{line} and
671 @var{col} as @var{topos}. Here's a function that does this:
674 (defun coordinates-of-position (col line)
675 (car (compute-motion (window-start)
680 (cons (window-hscroll) 0)
684 When you use @code{compute-motion} for the minibuffer, you need to use
685 @code{minibuffer-prompt-width} to get the horizontal position of the
686 beginning of the first screen line. @xref{Minibuffer Contents}.
690 @subsection Moving over Balanced Expressions
692 @cindex Lisp expression motion
694 @cindex balanced parenthesis motion
696 Here are several functions concerned with balanced-parenthesis
697 expressions (also called @dfn{sexps} in connection with moving across
698 them in Emacs). The syntax table controls how these functions interpret
699 various characters; see @ref{Syntax Tables}. @xref{Parsing
700 Expressions}, for lower-level primitives for scanning sexps or parts of
701 sexps. For user-level commands, see @ref{Parentheses,, Commands for
702 Editing with Parentheses, emacs, The GNU Emacs Manual}.
704 @deffn Command forward-list &optional arg
705 This function moves forward across @var{arg} (default 1) balanced groups of
706 parentheses. (Other syntactic entities such as words or paired string
710 @deffn Command backward-list &optional arg
711 This function moves backward across @var{arg} (default 1) balanced groups of
712 parentheses. (Other syntactic entities such as words or paired string
716 @deffn Command up-list &optional arg escape-strings no-syntax-crossing
717 This function moves forward out of @var{arg} (default 1) levels of
718 parentheses. A negative argument means move backward but still to a
719 less deep spot. If @var{escape-strings} is non-@code{nil} (as it is
720 interactively), move out of enclosing strings as well. If
721 @var{no-syntax-crossing} is non-@code{nil} (as it is interactively), prefer
722 to break out of any enclosing string instead of moving to the start of
723 a list broken across multiple strings. On error, location of point is
727 @deffn Command backward-up-list &optional arg escape-strings no-syntax-crossing
728 This function is just like @code{up-list}, but with a negated argument.
731 @deffn Command down-list &optional arg
732 This function moves forward into @var{arg} (default 1) levels of
733 parentheses. A negative argument means move backward but still go
734 deeper in parentheses (@minus{}@var{arg} levels).
737 @deffn Command forward-sexp &optional arg
738 This function moves forward across @var{arg} (default 1) balanced expressions.
739 Balanced expressions include both those delimited by parentheses and
740 other kinds, such as words and string constants.
741 @xref{Parsing Expressions}. For example,
745 ---------- Buffer: foo ----------
746 (concat@point{} "foo " (car x) y z)
747 ---------- Buffer: foo ----------
754 ---------- Buffer: foo ----------
755 (concat "foo " (car x) y@point{} z)
756 ---------- Buffer: foo ----------
761 @deffn Command backward-sexp &optional arg
762 This function moves backward across @var{arg} (default 1) balanced expressions.
765 @deffn Command beginning-of-defun &optional arg
766 This function moves back to the @var{arg}th beginning of a defun. If
767 @var{arg} is negative, this actually moves forward, but it still moves
768 to the beginning of a defun, not to the end of one. @var{arg} defaults
772 @deffn Command end-of-defun &optional arg
773 This function moves forward to the @var{arg}th end of a defun. If
774 @var{arg} is negative, this actually moves backward, but it still moves
775 to the end of a defun, not to the beginning of one. @var{arg} defaults
779 @defopt defun-prompt-regexp
780 If non-@code{nil}, this buffer-local variable holds a regular
781 expression that specifies what text can appear before the
782 open-parenthesis that starts a defun. That is to say, a defun begins
783 on a line that starts with a match for this regular expression,
784 followed by a character with open-parenthesis syntax.
787 @defopt open-paren-in-column-0-is-defun-start
788 If this variable's value is non-@code{nil}, an open parenthesis in
789 column 0 is considered to be the start of a defun. If it is
790 @code{nil}, an open parenthesis in column 0 has no special meaning.
791 The default is @code{t}.
794 @defvar beginning-of-defun-function
795 If non-@code{nil}, this variable holds a function for finding the
796 beginning of a defun. The function @code{beginning-of-defun}
797 calls this function instead of using its normal method, passing it its
798 optional argument. If the argument is non-@code{nil}, the function
799 should move back by that many functions, like
800 @code{beginning-of-defun} does.
803 @defvar end-of-defun-function
804 If non-@code{nil}, this variable holds a function for finding the end of
805 a defun. The function @code{end-of-defun} calls this function instead
806 of using its normal method.
809 @node Skipping Characters
810 @subsection Skipping Characters
811 @cindex skipping characters
813 The following two functions move point over a specified set of
814 characters. For example, they are often used to skip whitespace. For
815 related functions, see @ref{Motion and Syntax}.
817 These functions convert the set string to multibyte if the buffer is
818 multibyte, and they convert it to unibyte if the buffer is unibyte, as
819 the search functions do (@pxref{Searching and Matching}).
821 @defun skip-chars-forward character-set &optional limit
822 This function moves point in the current buffer forward, skipping over a
823 given set of characters. It examines the character following point,
824 then advances point if the character matches @var{character-set}. This
825 continues until it reaches a character that does not match. The
826 function returns the number of characters moved over.
828 The argument @var{character-set} is a string, like the inside of a
829 @samp{[@dots{}]} in a regular expression except that @samp{]} does not
830 terminate it, and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}.
831 Thus, @code{"a-zA-Z"} skips over all letters, stopping before the
832 first nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before
833 the first letter. See @xref{Regular Expressions}. Character classes
834 can also be used, e.g., @code{"[:alnum:]"}. See @pxref{Char Classes}.
836 If @var{limit} is supplied (it must be a number or a marker), it
837 specifies the maximum position in the buffer that point can be skipped
838 to. Point will stop at or before @var{limit}.
840 In the following example, point is initially located directly before the
841 @samp{T}. After the form is evaluated, point is located at the end of
842 that line (between the @samp{t} of @samp{hat} and the newline). The
843 function skips all letters and spaces, but not newlines.
847 ---------- Buffer: foo ----------
848 I read "@point{}The cat in the hat
850 ---------- Buffer: foo ----------
854 (skip-chars-forward "a-zA-Z ")
857 ---------- Buffer: foo ----------
858 I read "The cat in the hat@point{}
860 ---------- Buffer: foo ----------
865 @defun skip-chars-backward character-set &optional limit
866 This function moves point backward, skipping characters that match
867 @var{character-set}, until @var{limit}. It is just like
868 @code{skip-chars-forward} except for the direction of motion.
870 The return value indicates the distance traveled. It is an integer that
878 It is often useful to move point temporarily within a localized
879 portion of the program. This is called an @dfn{excursion}, and it is
880 done with the @code{save-excursion} special form. This construct
881 remembers the initial identity of the current buffer, and its value
882 of point, and restores them after the excursion
883 completes. It is the standard way to move point within one part of a
884 program and avoid affecting the rest of the program, and is used
885 thousands of times in the Lisp sources of Emacs.
887 If you only need to save and restore the identity of the current
888 buffer, use @code{save-current-buffer} or @code{with-current-buffer}
889 instead (@pxref{Current Buffer}). If you need to save or restore
890 window configurations, see the forms described in @ref{Window
891 Configurations} and in @ref{Frame Configurations}. @c frameset?
893 @defspec save-excursion body@dots{}
894 @cindex point excursion
895 This special form saves the identity of the current buffer and the
896 value of point in it, evaluates @var{body}, and finally
897 restores the buffer and its saved value of point. Both saved values are
898 restored even in case of an abnormal exit via
899 @code{throw} or error (@pxref{Nonlocal Exits}).
901 The value returned by @code{save-excursion} is the result of the last
902 form in @var{body}, or @code{nil} if no body forms were given.
905 Because @code{save-excursion} only saves point for the
906 buffer that was current at the start of the excursion, any changes
907 made to point in other buffers, during the excursion, will
908 remain in effect afterward. This frequently leads to unintended
909 consequences, so the byte compiler warns if you call @code{set-buffer}
913 Warning: Use ‘with-current-buffer’ rather than
914 save-excursion+set-buffer
918 To avoid such problems, you should call @code{save-excursion} only
919 after setting the desired current buffer, as in the following example:
923 (defun append-string-to-buffer (string buffer)
924 "Append STRING to the end of BUFFER."
925 (with-current-buffer buffer
927 (goto-char (point-max))
932 @cindex window excursions
933 Likewise, @code{save-excursion} does not restore window-buffer
934 correspondences altered by functions such as @code{switch-to-buffer}.
936 @strong{Warning:} Ordinary insertion of text adjacent to the saved
937 point value relocates the saved value, just as it relocates all
938 markers. More precisely, the saved value is a marker with insertion
939 type @code{nil}. @xref{Marker Insertion Types}. Therefore, when the
940 saved point value is restored, it normally comes before the inserted
943 @defmac save-mark-and-excursion body@dots{}
944 @cindex mark excursion
945 @cindex point excursion
946 This macro is like @code{save-excursion}, but also saves and restores
947 the mark location and @code{mark-active}. This macro does what
948 @code{save-excursion} did before Emacs 25.1.
954 @cindex restriction (in a buffer)
955 @cindex accessible portion (of a buffer)
957 @dfn{Narrowing} means limiting the text addressable by Emacs editing
958 commands to a limited range of characters in a buffer. The text that
959 remains addressable is called the @dfn{accessible portion} of the
962 Narrowing is specified with two buffer positions, which become the
963 beginning and end of the accessible portion. For most editing
964 commands and primitives, these positions replace the values of the
965 beginning and end of the buffer. While narrowing is in effect, no
966 text outside the accessible portion is displayed, and point cannot
967 move outside the accessible portion. Note that narrowing does not
968 alter actual buffer positions (@pxref{Point}); it only determines
969 which positions are considered the accessible portion of the buffer.
970 Most functions refuse to operate on text that is outside the
973 Commands for saving buffers are unaffected by narrowing; they save
974 the entire buffer regardless of any narrowing.
976 If you need to display in a single buffer several very different
977 types of text, consider using an alternative facility described in
980 @deffn Command narrow-to-region start end
981 This function sets the accessible portion of the current buffer to start
982 at @var{start} and end at @var{end}. Both arguments should be character
985 In an interactive call, @var{start} and @var{end} are set to the bounds
986 of the current region (point and the mark, with the smallest first).
989 @deffn Command narrow-to-page &optional move-count
990 This function sets the accessible portion of the current buffer to
991 include just the current page. An optional first argument
992 @var{move-count} non-@code{nil} means to move forward or backward by
993 @var{move-count} pages and then narrow to one page. The variable
994 @code{page-delimiter} specifies where pages start and end
995 (@pxref{Standard Regexps}).
997 In an interactive call, @var{move-count} is set to the numeric prefix
1001 @deffn Command widen
1003 This function cancels any narrowing in the current buffer, so that the
1004 entire contents are accessible. This is called @dfn{widening}.
1005 It is equivalent to the following expression:
1008 (narrow-to-region 1 (1+ (buffer-size)))
1012 @defun buffer-narrowed-p
1013 This function returns non-@code{nil} if the buffer is narrowed, and
1014 @code{nil} otherwise.
1017 @defspec save-restriction body@dots{}
1018 This special form saves the current bounds of the accessible portion,
1019 evaluates the @var{body} forms, and finally restores the saved bounds,
1020 thus restoring the same state of narrowing (or absence thereof) formerly
1021 in effect. The state of narrowing is restored even in the event of an
1022 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
1023 Therefore, this construct is a clean way to narrow a buffer temporarily.
1025 The value returned by @code{save-restriction} is that returned by the
1026 last form in @var{body}, or @code{nil} if no body forms were given.
1028 @c Wordy to avoid overfull hbox. --rjc 16mar92
1029 @strong{Caution:} it is easy to make a mistake when using the
1030 @code{save-restriction} construct. Read the entire description here
1033 If @var{body} changes the current buffer, @code{save-restriction} still
1034 restores the restrictions on the original buffer (the buffer whose
1035 restrictions it saved from), but it does not restore the identity of the
1038 @code{save-restriction} does @emph{not} restore point; use
1039 @code{save-excursion} for that. If you use both @code{save-restriction}
1040 and @code{save-excursion} together, @code{save-excursion} should come
1041 first (on the outside). Otherwise, the old point value would be
1042 restored with temporary narrowing still in effect. If the old point
1043 value were outside the limits of the temporary narrowing, this would
1044 fail to restore it accurately.
1046 Here is a simple example of correct use of @code{save-restriction}:
1050 ---------- Buffer: foo ----------
1051 This is the contents of foo
1052 This is the contents of foo
1053 This is the contents of foo@point{}
1054 ---------- Buffer: foo ----------
1062 (narrow-to-region 1 (point))
1063 (goto-char (point-min))
1064 (replace-string "foo" "bar")))
1066 ---------- Buffer: foo ----------
1067 This is the contents of bar
1068 This is the contents of bar
1069 This is the contents of foo@point{}
1070 ---------- Buffer: foo ----------