(posn-set-point): Fix typos: parameter is `position', not `posn'.
[emacs.git] / lispref / positions.texi
blob22a800a22163615331fdcc84320eacc33a6a3b09
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001
4 @c  Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/positions
7 @node Positions, Markers, Frames, Top
8 @chapter Positions
9 @cindex position (in buffer)
11   A @dfn{position} is the index of a character in the text of a buffer.
12 More precisely, a position identifies the place between two characters
13 (or before the first character, or after the last character), so we can
14 speak of the character before or after a given position.  However, we
15 often speak of the character ``at'' a position, meaning the character
16 after that position.
18   Positions are usually represented as integers starting from 1, but can
19 also be represented as @dfn{markers}---special objects that relocate
20 automatically when text is inserted or deleted so they stay with the
21 surrounding characters.  Functions that expect an argument to be a
22 position (an integer), but accept a marker as a substitute, normally
23 ignore the marker buffer.  Of course, markers used this way usually
24 point to a position in the buffer that the function operates on, but
25 that is entirely the programmer's responsibility.  @xref{Markers}.
27   See also the ``field'' feature (@pxref{Fields}), which provides
28 functions that are used by many cursor-motion commands.
30 @menu
31 * Point::         The special position where editing takes place.
32 * Motion::        Changing point.
33 * Excursions::    Temporary motion and buffer changes.
34 * Narrowing::     Restricting editing to a portion of the buffer.
35 @end menu
37 @node Point
38 @section Point
39 @cindex point
41   @dfn{Point} is a special buffer position used by many editing
42 commands, including the self-inserting typed characters and text
43 insertion functions.  Other commands move point through the text
44 to allow editing and insertion at different places.
46   Like other positions, point designates a place between two characters
47 (or before the first character, or after the last character), rather
48 than a particular character.  Usually terminals display the cursor over
49 the character that immediately follows point; point is actually before
50 the character on which the cursor sits.
52 @cindex point with narrowing
53   The value of point is a number no less than 1, and no greater than the
54 buffer size plus 1.  If narrowing is in effect (@pxref{Narrowing}), then
55 point is constrained to fall within the accessible portion of the buffer
56 (possibly at one end of it).
58   Each buffer has its own value of point, which is independent of the
59 value of point in other buffers.  Each window also has a value of point,
60 which is independent of the value of point in other windows on the same
61 buffer.  This is why point can have different values in various windows
62 that display the same buffer.  When a buffer appears in only one window,
63 the buffer's point and the window's point normally have the same value,
64 so the distinction is rarely important.  @xref{Window Point}, for more
65 details.
67 @defun point
68 @cindex current buffer position
69 This function returns the value of point in the current buffer,
70 as an integer.
72 @need 700
73 @example
74 @group
75 (point)
76      @result{} 175
77 @end group
78 @end example
79 @end defun
81 @defun point-min
82 This function returns the minimum accessible value of point in the
83 current buffer.  This is normally 1, but if narrowing is in effect, it
84 is the position of the start of the region that you narrowed to.
85 (@xref{Narrowing}.)
86 @end defun
88 @defun point-max
89 This function returns the maximum accessible value of point in the
90 current buffer.  This is @code{(1+ (buffer-size))}, unless narrowing is
91 in effect, in which case it is the position of the end of the region
92 that you narrowed to.  (@xref{Narrowing}.)
93 @end defun
95 @defun buffer-end flag
96 This function returns @code{(point-max)} if @var{flag} is greater than
97 0, @code{(point-min)} otherwise.  The argument @var{flag} must be a
98 number.
99 @end defun
101 @defun buffer-size &optional buffer
102 This function returns the total number of characters in the current
103 buffer.  In the absence of any narrowing (@pxref{Narrowing}),
104 @code{point-max} returns a value one larger than this.
106 If you specify a buffer, @var{buffer}, then the value is the
107 size of @var{buffer}.
109 @example
110 @group
111 (buffer-size)
112      @result{} 35
113 @end group
114 @group
115 (point-max)
116      @result{} 36
117 @end group
118 @end example
119 @end defun
121 @node Motion
122 @section Motion
124   Motion functions change the value of point, either relative to the
125 current value of point, relative to the beginning or end of the buffer,
126 or relative to the edges of the selected window.  @xref{Point}.
128 @menu
129 * Character Motion::       Moving in terms of characters.
130 * Word Motion::            Moving in terms of words.
131 * Buffer End Motion::      Moving to the beginning or end of the buffer.
132 * Text Lines::             Moving in terms of lines of text.
133 * Screen Lines::           Moving in terms of lines as displayed.
134 * List Motion::            Moving by parsing lists and sexps.
135 * Skipping Characters::    Skipping characters belonging to a certain set.
136 @end menu
138 @node Character Motion
139 @subsection Motion by Characters
141   These functions move point based on a count of characters.
142 @code{goto-char} is the fundamental primitive; the other functions use
143 that.
145 @deffn Command goto-char position
146 This function sets point in the current buffer to the value
147 @var{position}.  If @var{position} is less than 1, it moves point to the
148 beginning of the buffer.  If @var{position} is greater than the length
149 of the buffer, it moves point to the end.
151 If narrowing is in effect, @var{position} still counts from the
152 beginning of the buffer, but point cannot go outside the accessible
153 portion.  If @var{position} is out of range, @code{goto-char} moves
154 point to the beginning or the end of the accessible portion.
156 When this function is called interactively, @var{position} is the
157 numeric prefix argument, if provided; otherwise it is read from the
158 minibuffer.
160 @code{goto-char} returns @var{position}.
161 @end deffn
163 @deffn Command forward-char &optional count
164 @c @kindex beginning-of-buffer
165 @c @kindex end-of-buffer
166 This function moves point @var{count} characters forward, towards the
167 end of the buffer (or backward, towards the beginning of the buffer, if
168 @var{count} is negative).  If the function attempts to move point past
169 the beginning or end of the buffer (or the limits of the accessible
170 portion, when narrowing is in effect), an error is signaled with error
171 code @code{beginning-of-buffer} or @code{end-of-buffer}.
173 In an interactive call, @var{count} is the numeric prefix argument.
174 @end deffn
176 @deffn Command backward-char &optional count
177 This function moves point @var{count} characters backward, towards the
178 beginning of the buffer (or forward, towards the end of the buffer, if
179 @var{count} is negative).  If the function attempts to move point past
180 the beginning or end of the buffer (or the limits of the accessible
181 portion, when narrowing is in effect), an error is signaled with error
182 code @code{beginning-of-buffer} or @code{end-of-buffer}.
184 In an interactive call, @var{count} is the numeric prefix argument.
185 @end deffn
187 @node Word Motion
188 @subsection Motion by Words
190   These functions for parsing words use the syntax table to decide
191 whether a given character is part of a word.  @xref{Syntax Tables}.
193 @deffn Command forward-word &optional count
194 This function moves point forward @var{count} words (or backward if
195 @var{count} is negative).  ``Moving one word'' means moving until point
196 crosses a word-constituent character and then encounters a
197 word-separator character.  However, this function cannot move point past
198 the boundary of the accessible portion of the buffer, or across a field
199 boundary (@pxref{Fields}).  The most common case of a field boundary is
200 the end of the prompt in the minibuffer.
202 If it is possible to move @var{count} words, without being stopped
203 prematurely by the buffer boundary or a field boundary, the value is
204 @code{t}.  Otherwise, the return value is @code{nil} and point stops at
205 the buffer boundary or field boundary.
207 If @code{inhibit-field-text-motion} is non-@code{nil},
208 this function ignores field boundaries.
210 In an interactive call, @var{count} is specified by the numeric prefix
211 argument.  If @var{count} is omitted or @code{nil}, it defaults to 1.
212 @end deffn
214 @deffn Command backward-word &optional count
215 This function is just like @code{forward-word}, except that it moves
216 backward until encountering the front of a word, rather than forward.
217 @end deffn
219 @defvar words-include-escapes
220 @c Emacs 19 feature
221 This variable affects the behavior of @code{forward-word} and everything
222 that uses it.  If it is non-@code{nil}, then characters in the
223 ``escape'' and ``character quote'' syntax classes count as part of
224 words.  Otherwise, they do not.
225 @end defvar
227 @defvar inhibit-field-text-motion
228 @tindex inhibit-field-text-motion
229 If this variable is non-@code{nil}, certain motion functions including
230 @code{forward-word}, @code{forward-sentence}, and
231 @code{forward-paragraph} ignore field boundaries.
232 @end defvar
234 @node Buffer End Motion
235 @subsection Motion to an End of the Buffer
237   To move point to the beginning of the buffer, write:
239 @example
240 @group
241 (goto-char (point-min))
242 @end group
243 @end example
245 @noindent
246 Likewise, to move to the end of the buffer, use:
248 @example
249 @group
250 (goto-char (point-max))
251 @end group
252 @end example
254   Here are two commands that users use to do these things.  They are
255 documented here to warn you not to use them in Lisp programs, because
256 they set the mark and display messages in the echo area.
258 @deffn Command beginning-of-buffer &optional n
259 This function moves point to the beginning of the buffer (or the limits
260 of the accessible portion, when narrowing is in effect), setting the
261 mark at the previous position.  If @var{n} is non-@code{nil}, then it
262 puts point @var{n} tenths of the way from the beginning of the
263 accessible portion of the buffer.
265 In an interactive call, @var{n} is the numeric prefix argument,
266 if provided; otherwise @var{n} defaults to @code{nil}.
268 @strong{Warning:} Don't use this function in Lisp programs!
269 @end deffn
271 @deffn Command end-of-buffer &optional n
272 This function moves point to the end of the buffer (or the limits of the
273 accessible portion, when narrowing is in effect), setting the mark at
274 the previous position.  If @var{n} is non-@code{nil}, then it puts point
275 @var{n} tenths of the way from the end of the accessible portion of the
276 buffer.
278 In an interactive call, @var{n} is the numeric prefix argument,
279 if provided; otherwise @var{n} defaults to @code{nil}.
281 @strong{Warning:} Don't use this function in Lisp programs!
282 @end deffn
284 @node Text Lines
285 @subsection Motion by Text Lines
286 @cindex lines
288   Text lines are portions of the buffer delimited by newline characters,
289 which are regarded as part of the previous line.  The first text line
290 begins at the beginning of the buffer, and the last text line ends at
291 the end of the buffer whether or not the last character is a newline.
292 The division of the buffer into text lines is not affected by the width
293 of the window, by line continuation in display, or by how tabs and
294 control characters are displayed.
296 @deffn Command goto-line line
297 This function moves point to the front of the @var{line}th line,
298 counting from line 1 at beginning of the buffer.  If @var{line} is less
299 than 1, it moves point to the beginning of the buffer.  If @var{line} is
300 greater than the number of lines in the buffer, it moves point to the
301 end of the buffer---that is, the @emph{end of the last line} of the
302 buffer.  This is the only case in which @code{goto-line} does not
303 necessarily move to the beginning of a line.
305 If narrowing is in effect, then @var{line} still counts from the
306 beginning of the buffer, but point cannot go outside the accessible
307 portion.  So @code{goto-line} moves point to the beginning or end of the
308 accessible portion, if the line number specifies an inaccessible
309 position.
311 The return value of @code{goto-line} is the difference between
312 @var{line} and the line number of the line to which point actually was
313 able to move (in the full buffer, before taking account of narrowing).
314 Thus, the value is positive if the scan encounters the real end of the
315 buffer before finding the specified line.  The value is zero if scan
316 encounters the end of the accessible portion but not the real end of the
317 buffer.
319 In an interactive call, @var{line} is the numeric prefix argument if
320 one has been provided.  Otherwise @var{line} is read in the minibuffer.
321 @end deffn
323 @deffn Command beginning-of-line &optional count
324 This function moves point to the beginning of the current line.  With an
325 argument @var{count} not @code{nil} or 1, it moves forward
326 @var{count}@minus{}1 lines and then to the beginning of the line.
328 This function does not move point across a field boundary
329 (@pxref{Fields}) unless doing so would move beyond there to a
330 different line; therefore, if @var{count} is @code{nil} or 1, and
331 point starts at a field boundary, point does not move.  To ignore
332 field boundaries, either bind @code{inhibit-field-text-motion} to
333 @code{t}, or use the @code{forward-line} function instead.  For
334 instance, @code{(forward-line 0)} does the same thing as
335 @code{(beginning-of-line)}, except that it ignores field boundaries.
337 If this function reaches the end of the buffer (or of the accessible
338 portion, if narrowing is in effect), it positions point there.  No error
339 is signaled.
340 @end deffn
342 @defun line-beginning-position &optional count
343 @tindex line-beginning-position
344 Return the position that @code{(beginning-of-line @var{count})}
345 would move to.
346 @end defun
348 @deffn Command end-of-line &optional count
349 This function moves point to the end of the current line.  With an
350 argument @var{count} not @code{nil} or 1, it moves forward
351 @var{count}@minus{}1 lines and then to the end of the line.
353 This function does not move point across a field boundary
354 (@pxref{Fields}) unless doing so would move beyond there to a
355 different line; therefore, if @var{count} is @code{nil} or 1, and
356 point starts at a field boundary, point does not move.  To ignore
357 field boundaries, bind @code{inhibit-field-text-motion} to @code{t}.
359 If this function reaches the end of the buffer (or of the accessible
360 portion, if narrowing is in effect), it positions point there.  No error
361 is signaled.
362 @end deffn
364 @defun line-end-position &optional count
365 @tindex line-end-position
366 Return the position that @code{(end-of-line @var{count})}
367 would move to.
368 @end defun
370 @deffn Command forward-line &optional count
371 @cindex beginning of line
372 This function moves point forward @var{count} lines, to the beginning of
373 the line.  If @var{count} is negative, it moves point
374 @minus{}@var{count} lines backward, to the beginning of a line.  If
375 @var{count} is zero, it moves point to the beginning of the current
376 line.
378 If @code{forward-line} encounters the beginning or end of the buffer (or
379 of the accessible portion) before finding that many lines, it sets point
380 there.  No error is signaled.
382 @code{forward-line} returns the difference between @var{count} and the
383 number of lines actually moved.  If you attempt to move down five lines
384 from the beginning of a buffer that has only three lines, point stops at
385 the end of the last line, and the value will be 2.
387 In an interactive call, @var{count} is the numeric prefix argument.
388 @end deffn
390 @defun count-lines start end
391 @cindex lines in region
392 This function returns the number of lines between the positions
393 @var{start} and @var{end} in the current buffer.  If @var{start} and
394 @var{end} are equal, then it returns 0.  Otherwise it returns at least
395 1, even if @var{start} and @var{end} are on the same line.  This is
396 because the text between them, considered in isolation, must contain at
397 least one line unless it is empty.
399 Here is an example of using @code{count-lines}:
401 @example
402 @group
403 (defun current-line ()
404   "Return the vertical position of point@dots{}"
405   (+ (count-lines (window-start) (point))
406      (if (= (current-column) 0) 1 0)))
407 @end group
408 @end example
409 @end defun
411 @defun line-number-at-pos &optional pos
412 @cindex line number
413 This function returns the line number in the current buffer
414 corresponding the buffer position @var{pos}.  If @var{pos} is @code{nil}
415 or omitted, the current buffer position is used.
416 @end defun
418 @ignore
419 @c ================
420 The @code{previous-line} and @code{next-line} commands are functions
421 that should not be used in programs.  They are for users and are
422 mentioned here only for completeness.
424 @deffn Command previous-line count
425 @cindex goal column
426 This function moves point up @var{count} lines (down if @var{count}
427 is negative).  In moving, it attempts to keep point in the ``goal column''
428 (normally the same column that it was at the beginning of the move).
430 If there is no character in the target line exactly under the current
431 column, point is positioned after the character in that line which
432 spans this column, or at the end of the line if it is not long enough.
434 If it attempts to move beyond the top or bottom of the buffer (or clipped
435 region), then point is positioned in the goal column in the top or
436 bottom line.  No error is signaled.
438 In an interactive call, @var{count} will be the numeric
439 prefix argument.
441 The command @code{set-goal-column} can be used to create a semipermanent
442 goal column to which this command always moves.  Then it does not try to
443 move vertically.
445 If you are thinking of using this in a Lisp program, consider using
446 @code{forward-line} with a negative argument instead.  It is usually easier
447 to use and more reliable (no dependence on goal column, etc.).
448 @end deffn
450 @deffn Command next-line count
451 This function moves point down @var{count} lines (up if @var{count}
452 is negative).  In moving, it attempts to keep point in the ``goal column''
453 (normally the same column that it was at the beginning of the move).
455 If there is no character in the target line exactly under the current
456 column, point is positioned after the character in that line which
457 spans this column, or at the end of the line if it is not long enough.
459 If it attempts to move beyond the top or bottom of the buffer (or clipped
460 region), then point is positioned in the goal column in the top or
461 bottom line.  No error is signaled.
463 In the case where the @var{count} is 1, and point is on the last
464 line of the buffer (or clipped region), a new empty line is inserted at the
465 end of the buffer (or clipped region) and point moved there.
467 In an interactive call, @var{count} will be the numeric
468 prefix argument.
470 The command @code{set-goal-column} can be used to create a semipermanent
471 goal column to which this command always moves.  Then it does not try to
472 move vertically.
474 If you are thinking of using this in a Lisp program, consider using
475 @code{forward-line} instead.  It is usually easier
476 to use and more reliable (no dependence on goal column, etc.).
477 @end deffn
479 @c ================
480 @end ignore
482   Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}.
483 These functions do not move point, but test whether it is already at the
484 beginning or end of a line.
486 @node Screen Lines
487 @subsection Motion by Screen Lines
489   The line functions in the previous section count text lines, delimited
490 only by newline characters.  By contrast, these functions count screen
491 lines, which are defined by the way the text appears on the screen.  A
492 text line is a single screen line if it is short enough to fit the width
493 of the selected window, but otherwise it may occupy several screen
494 lines.
496   In some cases, text lines are truncated on the screen rather than
497 continued onto additional screen lines.  In these cases,
498 @code{vertical-motion} moves point much like @code{forward-line}.
499 @xref{Truncation}.
501   Because the width of a given string depends on the flags that control
502 the appearance of certain characters, @code{vertical-motion} behaves
503 differently, for a given piece of text, depending on the buffer it is
504 in, and even on the selected window (because the width, the truncation
505 flag, and display table may vary between windows).  @xref{Usual
506 Display}.
508   These functions scan text to determine where screen lines break, and
509 thus take time proportional to the distance scanned.  If you intend to
510 use them heavily, Emacs provides caches which may improve the
511 performance of your code.  @xref{Truncation, cache-long-line-scans}.
513 @defun vertical-motion count &optional window
514 This function moves point to the start of the screen line @var{count}
515 screen lines down from the screen line containing point.  If @var{count}
516 is negative, it moves up instead.
518 @code{vertical-motion} returns the number of screen lines over which it
519 moved point.  The value may be less in absolute value than @var{count}
520 if the beginning or end of the buffer was reached.
522 The window @var{window} is used for obtaining parameters such as the
523 width, the horizontal scrolling, and the display table.  But
524 @code{vertical-motion} always operates on the current buffer, even if
525 @var{window} currently displays some other buffer.
526 @end defun
528 @defun count-screen-lines &optional beg end count-final-newline window
529 This function returns the number of screen lines in the text from
530 @var{beg} to @var{end}.  The number of screen lines may be different
531 from the number of actual lines, due to line continuation, the display
532 table, etc.  If @var{beg} and @var{end} are @code{nil} or omitted,
533 they default to the beginning and end of the accessible portion of the
534 buffer.
536 If the region ends with a newline, that is ignored unless the optional
537 third argument @var{count-final-newline} is non-@code{nil}.
539 The optional fourth argument @var{window} specifies the window for
540 obtaining parameters such as width, horizontal scrolling, and so on.
541 The default is to use the selected window's parameters.
543 Like @code{vertical-motion}, @code{count-screen-lines} always uses the
544 current buffer, regardless of which buffer is displayed in
545 @var{window}.  This makes possible to use @code{count-screen-lines} in
546 any buffer, whether or not it is currently displayed in some window.
547 @end defun
549 @deffn Command move-to-window-line count
550 This function moves point with respect to the text currently displayed
551 in the selected window.  It moves point to the beginning of the screen
552 line @var{count} screen lines from the top of the window.  If
553 @var{count} is negative, that specifies a position
554 @w{@minus{}@var{count}} lines from the bottom (or the last line of the
555 buffer, if the buffer ends above the specified screen position).
557 If @var{count} is @code{nil}, then point moves to the beginning of the
558 line in the middle of the window.  If the absolute value of @var{count}
559 is greater than the size of the window, then point moves to the place
560 that would appear on that screen line if the window were tall enough.
561 This will probably cause the next redisplay to scroll to bring that
562 location onto the screen.
564 In an interactive call, @var{count} is the numeric prefix argument.
566 The value returned is the window line number point has moved to, with
567 the top line in the window numbered 0.
568 @end deffn
570 @defun compute-motion from frompos to topos width offsets window
571 This function scans the current buffer, calculating screen positions.
572 It scans the buffer forward from position @var{from}, assuming that is
573 at screen coordinates @var{frompos}, to position @var{to} or coordinates
574 @var{topos}, whichever comes first.  It returns the ending buffer
575 position and screen coordinates.
577 The coordinate arguments @var{frompos} and @var{topos} are cons cells of
578 the form @code{(@var{hpos} . @var{vpos})}.
580 The argument @var{width} is the number of columns available to display
581 text; this affects handling of continuation lines.  Use the value
582 returned by @code{window-width} for the window of your choice;
583 normally, use @code{(window-width @var{window})}.
585 The argument @var{offsets} is either @code{nil} or a cons cell of the
586 form @code{(@var{hscroll} . @var{tab-offset})}.  Here @var{hscroll} is
587 the number of columns not being displayed at the left margin; most
588 callers get this by calling @code{window-hscroll}.  Meanwhile,
589 @var{tab-offset} is the offset between column numbers on the screen and
590 column numbers in the buffer.  This can be nonzero in a continuation
591 line, when the previous screen lines' widths do not add up to a multiple
592 of @code{tab-width}.  It is always zero in a non-continuation line.
594 The window @var{window} serves only to specify which display table to
595 use.  @code{compute-motion} always operates on the current buffer,
596 regardless of what buffer is displayed in @var{window}.
598 The return value is a list of five elements:
600 @example
601 (@var{pos} @var{hpos} @var{vpos} @var{prevhpos} @var{contin})
602 @end example
604 @noindent
605 Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
606 is the vertical screen position, and @var{hpos} is the horizontal screen
607 position.
609 The result @var{prevhpos} is the horizontal position one character back
610 from @var{pos}.  The result @var{contin} is @code{t} if the last line
611 was continued after (or within) the previous character.
613 For example, to find the buffer position of column @var{col} of screen line
614 @var{line} of a certain window, pass the window's display start location
615 as @var{from} and the window's upper-left coordinates as @var{frompos}.
616 Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
617 the end of the accessible portion of the buffer, and pass @var{line} and
618 @var{col} as @var{topos}.  Here's a function that does this:
620 @example
621 (defun coordinates-of-position (col line)
622   (car (compute-motion (window-start)
623                        '(0 . 0)
624                        (point-max)
625                        (cons col line)
626                        (window-width)
627                        (cons (window-hscroll) 0)
628                        (selected-window))))
629 @end example
631 When you use @code{compute-motion} for the minibuffer, you need to use
632 @code{minibuffer-prompt-width} to get the horizontal position of the
633 beginning of the first screen line.  @xref{Minibuffer Misc}.
634 @end defun
636 @node List Motion
637 @comment  node-name,  next,  previous,  up
638 @subsection Moving over Balanced Expressions
639 @cindex sexp motion
640 @cindex Lisp expression motion
641 @cindex list motion
643   Here are several functions concerned with balanced-parenthesis
644 expressions (also called @dfn{sexps} in connection with moving across
645 them in Emacs).  The syntax table controls how these functions interpret
646 various characters; see @ref{Syntax Tables}.  @xref{Parsing
647 Expressions}, for lower-level primitives for scanning sexps or parts of
648 sexps.  For user-level commands, see @ref{Parentheses,, Commands for
649 Editing with Parentheses, emacs, The GNU Emacs Manual}.
651 @deffn Command forward-list &optional arg
652 This function moves forward across @var{arg} (default 1) balanced groups of
653 parentheses.  (Other syntactic entities such as words or paired string
654 quotes are ignored.)
655 @end deffn
657 @deffn Command backward-list &optional arg
658 This function moves backward across @var{arg} (default 1) balanced groups of
659 parentheses.  (Other syntactic entities such as words or paired string
660 quotes are ignored.)
661 @end deffn
663 @deffn Command up-list &optional arg
664 This function moves forward out of @var{arg} (default 1) levels of parentheses.
665 A negative argument means move backward but still to a less deep spot.
666 @end deffn
668 @deffn Command down-list &optional arg
669 This function moves forward into @var{arg} (default 1) levels of
670 parentheses.  A negative argument means move backward but still go
671 deeper in parentheses (@minus{}@var{arg} levels).
672 @end deffn
674 @deffn Command forward-sexp &optional arg
675 This function moves forward across @var{arg} (default 1) balanced expressions.
676 Balanced expressions include both those delimited by parentheses and
677 other kinds, such as words and string constants
678 @xref{Parsing Expressions}.  For example,
680 @example
681 @group
682 ---------- Buffer: foo ----------
683 (concat@point{} "foo " (car x) y z)
684 ---------- Buffer: foo ----------
685 @end group
687 @group
688 (forward-sexp 3)
689      @result{} nil
691 ---------- Buffer: foo ----------
692 (concat "foo " (car x) y@point{} z)
693 ---------- Buffer: foo ----------
694 @end group
695 @end example
696 @end deffn
698 @deffn Command backward-sexp &optional arg
699 This function moves backward across @var{arg} (default 1) balanced expressions.
700 @end deffn
702 @deffn Command beginning-of-defun &optional arg
703 This function moves back to the @var{arg}th beginning of a defun.  If
704 @var{arg} is negative, this actually moves forward, but it still moves
705 to the beginning of a defun, not to the end of one.
706 @end deffn
708 @deffn Command end-of-defun &optional arg
709 This function moves forward to the @var{arg}th end of a defun.  If
710 @var{arg} is negative, this actually moves backward, but it still moves
711 to the end of a defun, not to the beginning of one.
712 @end deffn
714 @defopt defun-prompt-regexp
715 If non-@code{nil}, this variable holds a regular expression that
716 specifies what text can appear before the open-parenthesis that starts a
717 defun.  That is to say, a defun begins on a line that starts with a
718 match for this regular expression, followed by a character with
719 open-parenthesis syntax.
720 @end defopt
722 @defopt open-paren-in-column-0-is-defun-start
723 If this variable's value is non-@code{nil}, an open parenthesis in
724 column 0 is considered to be the start of a defun.  If it is
725 @code{nil}, an open parenthesis in column 0 has no special meaning.
726 The default is @code{t}.
727 @end defopt
729 @defvar beginning-of-defun-function
730 @tindex beginning-of-defun-function
731 If non-@code{nil}, this variable holds a function for finding the
732 beginning of a defun.  The function @code{beginning-of-defun}
733 calls this function instead of using its normal method.
734 @end defvar
736 @defvar end-of-defun-function
737 @tindex end-of-defun-function
738 If non-@code{nil}, this variable holds a function for finding the end of
739 a defun.  The function @code{end-of-defun} calls this function instead
740 of using its normal method.
741 @end defvar
743 @node Skipping Characters
744 @comment  node-name,  next,  previous,  up
745 @subsection Skipping Characters
746 @cindex skipping characters
748   The following two functions move point over a specified set of
749 characters.  For example, they are often used to skip whitespace.  For
750 related functions, see @ref{Motion and Syntax}.
752 These functions convert the set string to multibyte if the buffer is
753 multibyte, and they convert it to unibyte if the buffer is unibyte, as
754 the search functions do (@pxref{Searching and Matching}).
756 @defun skip-chars-forward character-set &optional limit
757 This function moves point in the current buffer forward, skipping over a
758 given set of characters.  It examines the character following point,
759 then advances point if the character matches @var{character-set}.  This
760 continues until it reaches a character that does not match.  The
761 function returns the number of characters moved over.
763 The argument @var{character-set} is like the inside of a
764 @samp{[@dots{}]} in a regular expression except that @samp{]} is never
765 special and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}.  Thus,
766 @code{"a-zA-Z"} skips over all letters, stopping before the first
767 nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before the
768 first letter.  @xref{Regular Expressions}.
770 If @var{limit} is supplied (it must be a number or a marker), it
771 specifies the maximum position in the buffer that point can be skipped
772 to.  Point will stop at or before @var{limit}.
774 In the following example, point is initially located directly before the
775 @samp{T}.  After the form is evaluated, point is located at the end of
776 that line (between the @samp{t} of @samp{hat} and the newline).  The
777 function skips all letters and spaces, but not newlines.
779 @example
780 @group
781 ---------- Buffer: foo ----------
782 I read "@point{}The cat in the hat
783 comes back" twice.
784 ---------- Buffer: foo ----------
785 @end group
787 @group
788 (skip-chars-forward "a-zA-Z ")
789      @result{} nil
791 ---------- Buffer: foo ----------
792 I read "The cat in the hat@point{}
793 comes back" twice.
794 ---------- Buffer: foo ----------
795 @end group
796 @end example
798 Note that char classes are not currently supported in
799 @var{character-set}; they will be treated as literals.  Thus you
800 cannot use @code{"[:alpha:]"} instead of @code{"a-zA-Z"} to include
801 non-@acronym{ASCII} letters.  A way to skip forward over all letters is:
803 @example
804 (re-search-forward "\\=[[:alpha:]]*" nil t)
805 @end example
806 @end defun
808 @defun skip-chars-backward character-set &optional limit
809 This function moves point backward, skipping characters that match
810 @var{character-set}, until @var{limit}.  It is just like
811 @code{skip-chars-forward} except for the direction of motion.
813 The return value indicates the distance traveled.  It is an integer that
814 is zero or less.
815 @end defun
817 @node Excursions
818 @section Excursions
819 @cindex excursion
821   It is often useful to move point ``temporarily'' within a localized
822 portion of the program, or to switch buffers temporarily.  This is
823 called an @dfn{excursion}, and it is done with the @code{save-excursion}
824 special form.  This construct initially remembers the identity of the
825 current buffer, and its values of point and the mark, and restores them
826 after the completion of the excursion.
828   The forms for saving and restoring the configuration of windows are
829 described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
830 Configurations}).
832 @defspec save-excursion forms@dots{}
833 @cindex mark excursion
834 @cindex point excursion
835 @cindex current buffer excursion
836 The @code{save-excursion} special form saves the identity of the current
837 buffer and the values of point and the mark in it, evaluates
838 @var{forms}, and finally restores the buffer and its saved values of
839 point and the mark.  All three saved values are restored even in case of
840 an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
842 The @code{save-excursion} special form is the standard way to switch
843 buffers or move point within one part of a program and avoid affecting
844 the rest of the program.  It is used more than 4000 times in the Lisp
845 sources of Emacs.
847 @code{save-excursion} does not save the values of point and the mark for
848 other buffers, so changes in other buffers remain in effect after
849 @code{save-excursion} exits.
851 @cindex window excursions
852 Likewise, @code{save-excursion} does not restore window-buffer
853 correspondences altered by functions such as @code{switch-to-buffer}.
854 One way to restore these correspondences, and the selected window, is to
855 use @code{save-window-excursion} inside @code{save-excursion}
856 (@pxref{Window Configurations}).
858 The value returned by @code{save-excursion} is the result of the last of
859 @var{forms}, or @code{nil} if no @var{forms} are given.
861 @example
862 @group
863 (save-excursion @var{forms})
864 @equiv{}
865 (let ((old-buf (current-buffer))
866       (old-pnt (point-marker))
867 @end group
868       (old-mark (copy-marker (mark-marker))))
869   (unwind-protect
870       (progn @var{forms})
871     (set-buffer old-buf)
872 @group
873     (goto-char old-pnt)
874     (set-marker (mark-marker) old-mark)))
875 @end group
876 @end example
877 @end defspec
879   @strong{Warning:} Ordinary insertion of text adjacent to the saved
880 point value relocates the saved value, just as it relocates all markers.
881 More precisely, the saved value is a marker with insertion type
882 @code{nil}.  @xref{Marker Insertion Types}.  Therefore, when the saved
883 point value is restored, it normally comes before the inserted text.
885   Although @code{save-excursion} saves the location of the mark, it does
886 not prevent functions which modify the buffer from setting
887 @code{deactivate-mark}, and thus causing the deactivation of the mark
888 after the command finishes.  @xref{The Mark}.
890 @node Narrowing
891 @section Narrowing
892 @cindex narrowing
893 @cindex restriction (in a buffer)
894 @cindex accessible portion (of a buffer)
896   @dfn{Narrowing} means limiting the text addressable by Emacs editing
897 commands to a limited range of characters in a buffer.  The text that
898 remains addressable is called the @dfn{accessible portion} of the
899 buffer.
901   Narrowing is specified with two buffer positions which become the
902 beginning and end of the accessible portion.  For most editing commands
903 and most Emacs primitives, these positions replace the values of the
904 beginning and end of the buffer.  While narrowing is in effect, no text
905 outside the accessible portion is displayed, and point cannot move
906 outside the accessible portion.
908   Values such as positions or line numbers, which usually count from the
909 beginning of the buffer, do so despite narrowing, but the functions
910 which use them refuse to operate on text that is inaccessible.
912   The commands for saving buffers are unaffected by narrowing; they save
913 the entire buffer regardless of any narrowing.
915 @deffn Command narrow-to-region start end
916 This function sets the accessible portion of the current buffer to start
917 at @var{start} and end at @var{end}.  Both arguments should be character
918 positions.
920 In an interactive call, @var{start} and @var{end} are set to the bounds
921 of the current region (point and the mark, with the smallest first).
922 @end deffn
924 @deffn Command narrow-to-page &optional move-count
925 This function sets the accessible portion of the current buffer to
926 include just the current page.  An optional first argument
927 @var{move-count} non-@code{nil} means to move forward or backward by
928 @var{move-count} pages and then narrow to one page.  The variable
929 @code{page-delimiter} specifies where pages start and end
930 (@pxref{Standard Regexps}).
932 In an interactive call, @var{move-count} is set to the numeric prefix
933 argument.
934 @end deffn
936 @deffn Command widen
937 @cindex widening
938 This function cancels any narrowing in the current buffer, so that the
939 entire contents are accessible.  This is called @dfn{widening}.
940 It is equivalent to the following expression:
942 @example
943 (narrow-to-region 1 (1+ (buffer-size)))
944 @end example
945 @end deffn
947 @defspec save-restriction body@dots{}
948 This special form saves the current bounds of the accessible portion,
949 evaluates the @var{body} forms, and finally restores the saved bounds,
950 thus restoring the same state of narrowing (or absence thereof) formerly
951 in effect.  The state of narrowing is restored even in the event of an
952 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
953 Therefore, this construct is a clean way to narrow a buffer temporarily.
955 The value returned by @code{save-restriction} is that returned by the
956 last form in @var{body}, or @code{nil} if no body forms were given.
958 @c Wordy to avoid overfull hbox.  --rjc 16mar92
959 @strong{Caution:} it is easy to make a mistake when using the
960 @code{save-restriction} construct.  Read the entire description here
961 before you try it.
963 If @var{body} changes the current buffer, @code{save-restriction} still
964 restores the restrictions on the original buffer (the buffer whose
965 restrictions it saved from), but it does not restore the identity of the
966 current buffer.
968 @code{save-restriction} does @emph{not} restore point and the mark; use
969 @code{save-excursion} for that.  If you use both @code{save-restriction}
970 and @code{save-excursion} together, @code{save-excursion} should come
971 first (on the outside).  Otherwise, the old point value would be
972 restored with temporary narrowing still in effect.  If the old point
973 value were outside the limits of the temporary narrowing, this would
974 fail to restore it accurately.
976 Here is a simple example of correct use of @code{save-restriction}:
978 @example
979 @group
980 ---------- Buffer: foo ----------
981 This is the contents of foo
982 This is the contents of foo
983 This is the contents of foo@point{}
984 ---------- Buffer: foo ----------
985 @end group
987 @group
988 (save-excursion
989   (save-restriction
990     (goto-char 1)
991     (forward-line 2)
992     (narrow-to-region 1 (point))
993     (goto-char (point-min))
994     (replace-string "foo" "bar")))
996 ---------- Buffer: foo ----------
997 This is the contents of bar
998 This is the contents of bar
999 This is the contents of foo@point{}
1000 ---------- Buffer: foo ----------
1001 @end group
1002 @end example
1003 @end defspec
1005 @ignore
1006    arch-tag: 56e8ff26-4ffe-4832-a141-7e991a2d0f87
1007 @end ignore