*** empty log message ***
[emacs.git] / lispref / positions.texi
blob5e9abd359c69291ce67c001af7f3bc9318224696
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
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.  @xref{Markers}.
23   See also the ``field'' feature (@pxref{Fields}), which provides
24 functions that are used by many cursur-motion commands.
26 @menu
27 * Point::         The special position where editing takes place.
28 * Motion::        Changing point.
29 * Excursions::    Temporary motion and buffer changes.
30 * Narrowing::     Restricting editing to a portion of the buffer.
31 @end menu
33 @node Point
34 @section Point
35 @cindex point
37   @dfn{Point} is a special buffer position used by many editing
38 commands, including the self-inserting typed characters and text
39 insertion functions.  Other commands move point through the text
40 to allow editing and insertion at different places.
42   Like other positions, point designates a place between two characters
43 (or before the first character, or after the last character), rather
44 than a particular character.  Usually terminals display the cursor over
45 the character that immediately follows point; point is actually before
46 the character on which the cursor sits.
48 @cindex point with narrowing
49   The value of point is a number no less than 1, and no greater than the
50 buffer size plus 1.  If narrowing is in effect (@pxref{Narrowing}), then
51 point is constrained to fall within the accessible portion of the buffer
52 (possibly at one end of it).
54   Each buffer has its own value of point, which is independent of the
55 value of point in other buffers.  Each window also has a value of point,
56 which is independent of the value of point in other windows on the same
57 buffer.  This is why point can have different values in various windows
58 that display the same buffer.  When a buffer appears in only one window,
59 the buffer's point and the window's point normally have the same value,
60 so the distinction is rarely important.  @xref{Window Point}, for more
61 details.
63 @defun point
64 @cindex current buffer position
65 This function returns the value of point in the current buffer,
66 as an integer.
68 @need 700
69 @example
70 @group
71 (point)
72      @result{} 175
73 @end group
74 @end example
75 @end defun
77 @defun point-min
78 This function returns the minimum accessible value of point in the
79 current buffer.  This is normally 1, but if narrowing is in effect, it
80 is the position of the start of the region that you narrowed to.
81 (@xref{Narrowing}.)
82 @end defun
84 @defun point-max
85 This function returns the maximum accessible value of point in the
86 current buffer.  This is @code{(1+ (buffer-size))}, unless narrowing is
87 in effect, in which case it is the position of the end of the region
88 that you narrowed to.  (@xref{Narrowing}.)
89 @end defun
91 @defun buffer-end flag
92 This function returns @code{(point-min)} if @var{flag} is less than 1,
93 @code{(point-max)} otherwise.  The argument @var{flag} must be a number.
94 @end defun
96 @defun buffer-size &optional buffer
97 This function returns the total number of characters in the current
98 buffer.  In the absence of any narrowing (@pxref{Narrowing}),
99 @code{point-max} returns a value one larger than this.
101 If you specify a buffer, @var{buffer}, then the value is the
102 size of @var{buffer}.
104 @example
105 @group
106 (buffer-size)
107      @result{} 35
108 @end group
109 @group
110 (point-max)
111      @result{} 36
112 @end group
113 @end example
114 @end defun
116 @node Motion
117 @section Motion
119   Motion functions change the value of point, either relative to the
120 current value of point, relative to the beginning or end of the buffer,
121 or relative to the edges of the selected window.  @xref{Point}.
123 @menu
124 * Character Motion::       Moving in terms of characters.
125 * Word Motion::            Moving in terms of words.
126 * Buffer End Motion::      Moving to the beginning or end of the buffer.
127 * Text Lines::             Moving in terms of lines of text.
128 * Screen Lines::           Moving in terms of lines as displayed.
129 * List Motion::            Moving by parsing lists and sexps.
130 * Skipping Characters::    Skipping characters belonging to a certain set.
131 @end menu
133 @node Character Motion
134 @subsection Motion by Characters
136   These functions move point based on a count of characters.
137 @code{goto-char} is the fundamental primitive; the other functions use
138 that.
140 @deffn Command goto-char position
141 This function sets point in the current buffer to the value
142 @var{position}.  If @var{position} is less than 1, it moves point to the
143 beginning of the buffer.  If @var{position} is greater than the length
144 of the buffer, it moves point to the end.
146 If narrowing is in effect, @var{position} still counts from the
147 beginning of the buffer, but point cannot go outside the accessible
148 portion.  If @var{position} is out of range, @code{goto-char} moves
149 point to the beginning or the end of the accessible portion.
151 When this function is called interactively, @var{position} is the
152 numeric prefix argument, if provided; otherwise it is read from the
153 minibuffer.
155 @code{goto-char} returns @var{position}.
156 @end deffn
158 @deffn Command forward-char &optional count
159 @c @kindex beginning-of-buffer
160 @c @kindex end-of-buffer
161 This function moves point @var{count} characters forward, towards the
162 end of the buffer (or backward, towards the beginning of the buffer, if
163 @var{count} is negative).  If the function attempts to move point past
164 the beginning or end of the buffer (or the limits of the accessible
165 portion, when narrowing is in effect), an error is signaled with error
166 code @code{beginning-of-buffer} or @code{end-of-buffer}.
168 In an interactive call, @var{count} is the numeric prefix argument.
169 @end deffn
171 @deffn Command backward-char &optional count
172 This function moves point @var{count} characters backward, towards the
173 beginning of the buffer (or forward, towards the end of the buffer, if
174 @var{count} is negative).  If the function attempts to move point past
175 the beginning or end of the buffer (or the limits of the accessible
176 portion, when narrowing is in effect), an error is signaled with error
177 code @code{beginning-of-buffer} or @code{end-of-buffer}.
179 In an interactive call, @var{count} is the numeric prefix argument.
180 @end deffn
182 @node Word Motion
183 @subsection Motion by Words
185   These functions for parsing words use the syntax table to decide
186 whether a given character is part of a word.  @xref{Syntax Tables}.
188 @deffn Command forward-word count
189 This function moves point forward @var{count} words (or backward if
190 @var{count} is negative).  ``Moving one word'' means moving until point
191 crosses a word-constituent character and then encounters a
192 word-separator character.  However, this function cannot move point past
193 the boundary of the accessible part of the buffer, or across a field
194 boundary (@pxref{Fields}).  The most common case of a field boundary is
195 the end of the prompt in the minibuffer.
197 If it is possible to move @var{count} words, without being stopped
198 prematurely by the buffer boundary or a field boundary, the value is
199 @code{t}.  Otherwise, the return value is @code{nil} and point stops at
200 the buffer boundary or field boundary.
202 If @code{inhibit-field-text-motion} is non-@code{nil},
203 this function ignores field boundaries.
205 In an interactive call, @var{count} is specified by the numeric prefix
206 argument.
207 @end deffn
209 @deffn Command backward-word count
210 This function is just like @code{forward-word}, except that it moves
211 backward until encountering the front of a word, rather than forward.
213 In an interactive call, @var{count} is set to the numeric prefix
214 argument.
216 @c [Now optimized by compiler.]
217 @c This function is rarely used in programs, as it is more efficient to
218 @c call @code{forward-word} with a negative argument.
219 @end deffn
221 @defvar words-include-escapes
222 @c Emacs 19 feature
223 This variable affects the behavior of @code{forward-word} and everything
224 that uses it.  If it is non-@code{nil}, then characters in the
225 ``escape'' and ``character quote'' syntax classes count as part of
226 words.  Otherwise, they do not.
227 @end defvar
229 @defvar inhibit-field-text-motion
230 @tindex inhibit-field-text-motion
231 If this variable is non-@code{nil}, certain motion functions including
232 @code{forward-word}, @code{forward-sentence}, and
233 @code{forward-paragraph} ignore field boundaries.
234 @end defvar
236 @node Buffer End Motion
237 @subsection Motion to an End of the Buffer
239   To move point to the beginning of the buffer, write:
241 @example
242 @group
243 (goto-char (point-min))
244 @end group
245 @end example
247 @noindent
248 Likewise, to move to the end of the buffer, use:
250 @example
251 @group
252 (goto-char (point-max))
253 @end group
254 @end example
256   Here are two commands that users use to do these things.  They are
257 documented here to warn you not to use them in Lisp programs, because
258 they set the mark and display messages in the echo area.
260 @deffn Command beginning-of-buffer &optional n
261 This function moves point to the beginning of the buffer (or the limits
262 of the accessible portion, when narrowing is in effect), setting the
263 mark at the previous position.  If @var{n} is non-@code{nil}, then it
264 puts point @var{n} tenths of the way from the beginning of the
265 accessible portion of the buffer.
267 In an interactive call, @var{n} is the numeric prefix argument,
268 if provided; otherwise @var{n} defaults to @code{nil}.
270 @strong{Warning:} Don't use this function in Lisp programs!
271 @end deffn
273 @deffn Command end-of-buffer &optional n
274 This function moves point to the end of the buffer (or the limits of the
275 accessible portion, when narrowing is in effect), setting the mark at
276 the previous position.  If @var{n} is non-@code{nil}, then it puts point
277 @var{n} tenths of the way from the end of the accessible portion of the
278 buffer.
280 In an interactive call, @var{n} is the numeric prefix argument,
281 if provided; otherwise @var{n} defaults to @code{nil}.
283 @strong{Warning:} Don't use this function in Lisp programs!
284 @end deffn
286 @node Text Lines
287 @subsection Motion by Text Lines
288 @cindex lines
290   Text lines are portions of the buffer delimited by newline characters,
291 which are regarded as part of the previous line.  The first text line
292 begins at the beginning of the buffer, and the last text line ends at
293 the end of the buffer whether or not the last character is a newline.
294 The division of the buffer into text lines is not affected by the width
295 of the window, by line continuation in display, or by how tabs and
296 control characters are displayed.
298 @deffn Command goto-line line
299 This function moves point to the front of the @var{line}th line,
300 counting from line 1 at beginning of the buffer.  If @var{line} is less
301 than 1, it moves point to the beginning of the buffer.  If @var{line} is
302 greater than the number of lines in the buffer, it moves point to the
303 end of the buffer---that is, the @emph{end of the last line} of the
304 buffer.  This is the only case in which @code{goto-line} does not
305 necessarily move to the beginning of a line.
307 If narrowing is in effect, then @var{line} still counts from the
308 beginning of the buffer, but point cannot go outside the accessible
309 portion.  So @code{goto-line} moves point to the beginning or end of the
310 accessible portion, if the line number specifies an inaccessible
311 position.
313 The return value of @code{goto-line} is the difference between
314 @var{line} and the line number of the line to which point actually was
315 able to move (in the full buffer, before taking account of narrowing).
316 Thus, the value is positive if the scan encounters the real end of the
317 buffer before finding the specified line.  The value is zero if scan
318 encounters the end of the accessible portion but not the real end of the
319 buffer.
321 In an interactive call, @var{line} is the numeric prefix argument if
322 one has been provided.  Otherwise @var{line} is read in the minibuffer.
323 @end deffn
325 @deffn Command beginning-of-line &optional count
326 This function moves point to the beginning of the current line.  With an
327 argument @var{count} not @code{nil} or 1, it moves forward
328 @var{count}@minus{}1 lines and then to the beginning of the line.
330 If this function reaches the end of the buffer (or of the accessible
331 portion, if narrowing is in effect), it positions point there.  No error
332 is signaled.
333 @end deffn
335 @defun line-beginning-position &optional count
336 @tindex line-beginning-position
337 Return the position that @code{(beginning-of-line @var{count})}
338 would move to.
339 @end defun
341 @deffn Command end-of-line &optional count
342 This function moves point to the end 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 end of the line.
346 If this function reaches the end of the buffer (or of the accessible
347 portion, if narrowing is in effect), it positions point there.  No error
348 is signaled.
349 @end deffn
351 @defun line-end-position &optional count
352 @tindex line-end-position
353 Return the position that @code{(end-of-line @var{count})}
354 would move to.
355 @end defun
357 @deffn Command forward-line &optional count
358 @cindex beginning of line
359 This function moves point forward @var{count} lines, to the beginning of
360 the line.  If @var{count} is negative, it moves point
361 @minus{}@var{count} lines backward, to the beginning of a line.  If
362 @var{count} is zero, it moves point to the beginning of the current
363 line.
365 If @code{forward-line} encounters the beginning or end of the buffer (or
366 of the accessible portion) before finding that many lines, it sets point
367 there.  No error is signaled.
369 @code{forward-line} returns the difference between @var{count} and the
370 number of lines actually moved.  If you attempt to move down five lines
371 from the beginning of a buffer that has only three lines, point stops at
372 the end of the last line, and the value will be 2.
374 In an interactive call, @var{count} is the numeric prefix argument.
375 @end deffn
377 @defun count-lines start end
378 @cindex lines in region
379 This function returns the number of lines between the positions
380 @var{start} and @var{end} in the current buffer.  If @var{start} and
381 @var{end} are equal, then it returns 0.  Otherwise it returns at least
382 1, even if @var{start} and @var{end} are on the same line.  This is
383 because the text between them, considered in isolation, must contain at
384 least one line unless it is empty.
386 Here is an example of using @code{count-lines}:
388 @example
389 @group
390 (defun current-line ()
391   "Return the vertical position of point@dots{}"
392   (+ (count-lines (window-start) (point))
393      (if (= (current-column) 0) 1 0)
394      -1))
395 @end group
396 @end example
397 @end defun
399 @ignore
400 @c ================
401 The @code{previous-line} and @code{next-line} commands are functions
402 that should not be used in programs.  They are for users and are
403 mentioned here only for completeness.
405 @deffn Command previous-line count
406 @cindex goal column
407 This function moves point up @var{count} lines (down if @var{count}
408 is negative).  In moving, it attempts to keep point in the ``goal column''
409 (normally the same column that it was at the beginning of the move).
411 If there is no character in the target line exactly under the current
412 column, point is positioned after the character in that line which
413 spans this column, or at the end of the line if it is not long enough.
415 If it attempts to move beyond the top or bottom of the buffer (or clipped
416 region), then point is positioned in the goal column in the top or
417 bottom line.  No error is signaled.
419 In an interactive call, @var{count} will be the numeric
420 prefix argument.
422 The command @code{set-goal-column} can be used to create a semipermanent
423 goal column to which this command always moves.  Then it does not try to
424 move vertically.
426 If you are thinking of using this in a Lisp program, consider using
427 @code{forward-line} with a negative argument instead.  It is usually easier
428 to use and more reliable (no dependence on goal column, etc.).
429 @end deffn
431 @deffn Command next-line count
432 This function moves point down @var{count} lines (up if @var{count}
433 is negative).  In moving, it attempts to keep point in the ``goal column''
434 (normally the same column that it was at the beginning of the move).
436 If there is no character in the target line exactly under the current
437 column, point is positioned after the character in that line which
438 spans this column, or at the end of the line if it is not long enough.
440 If it attempts to move beyond the top or bottom of the buffer (or clipped
441 region), then point is positioned in the goal column in the top or
442 bottom line.  No error is signaled.
444 In the case where the @var{count} is 1, and point is on the last
445 line of the buffer (or clipped region), a new empty line is inserted at the
446 end of the buffer (or clipped region) and point moved there.
448 In an interactive call, @var{count} will be the numeric
449 prefix argument.
451 The command @code{set-goal-column} can be used to create a semipermanent
452 goal column to which this command always moves.  Then it does not try to
453 move vertically.
455 If you are thinking of using this in a Lisp program, consider using
456 @code{forward-line} instead.  It is usually easier
457 to use and more reliable (no dependence on goal column, etc.).
458 @end deffn
460 @c ================
461 @end ignore
463   Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}.
464 These functions do not move point, but test whether it is already at the
465 beginning or end of a line.
467 @node Screen Lines
468 @subsection Motion by Screen Lines
470   The line functions in the previous section count text lines, delimited
471 only by newline characters.  By contrast, these functions count screen
472 lines, which are defined by the way the text appears on the screen.  A
473 text line is a single screen line if it is short enough to fit the width
474 of the selected window, but otherwise it may occupy several screen
475 lines.
477   In some cases, text lines are truncated on the screen rather than
478 continued onto additional screen lines.  In these cases,
479 @code{vertical-motion} moves point much like @code{forward-line}.
480 @xref{Truncation}.
482   Because the width of a given string depends on the flags that control
483 the appearance of certain characters, @code{vertical-motion} behaves
484 differently, for a given piece of text, depending on the buffer it is
485 in, and even on the selected window (because the width, the truncation
486 flag, and display table may vary between windows).  @xref{Usual
487 Display}.
489   These functions scan text to determine where screen lines break, and
490 thus take time proportional to the distance scanned.  If you intend to
491 use them heavily, Emacs provides caches which may improve the
492 performance of your code.  @xref{Truncation, cache-long-line-scans}.
495 @defun vertical-motion count &optional window
496 This function moves point to the start of the screen line @var{count}
497 screen lines down from the screen line containing point.  If @var{count}
498 is negative, it moves up instead.
500 @code{vertical-motion} returns the number of screen lines over which it
501 moved point.  The value may be less in absolute value than @var{count}
502 if the beginning or end of the buffer was reached.
504 The window @var{window} is used for obtaining parameters such as the
505 width, the horizontal scrolling, and the display table.  But
506 @code{vertical-motion} always operates on the current buffer, even if
507 @var{window} currently displays some other buffer.
508 @end defun
510 @deffn Command move-to-window-line count
511 This function moves point with respect to the text currently displayed
512 in the selected window.  It moves point to the beginning of the screen
513 line @var{count} screen lines from the top of the window.  If
514 @var{count} is negative, that specifies a position
515 @w{@minus{}@var{count}} lines from the bottom (or the last line of the
516 buffer, if the buffer ends above the specified screen position).
518 If @var{count} is @code{nil}, then point moves to the beginning of the
519 line in the middle of the window.  If the absolute value of @var{count}
520 is greater than the size of the window, then point moves to the place
521 that would appear on that screen line if the window were tall enough.
522 This will probably cause the next redisplay to scroll to bring that
523 location onto the screen.
525 In an interactive call, @var{count} is the numeric prefix argument.
527 The value returned is the window line number point has moved to, with
528 the top line in the window numbered 0.
529 @end deffn
531 @defun count-screen-lines &optional beg end count-final-newline window
532 This function returns the number of the screen lines occupied by the
533 text between positions @var{beg} and @var{end}.  These arguments default
534 to the beginning and end of the accessible portion of the buffer.
536 If region ends with a newline, it is significant if
537 @var{count-final-newline} is non-@code{nil}.  Otherwise it is ignored.
539 The argument @var{window} specifies the window used for obtaining
540 parameters such as width, horizontal scrolling, and so on.  The default
541 is the selected window.
543 Like @code{vertical-motion}, @code{count-screen-lines} always uses the
544 current buffer, regardless of which buffer is displayed in @var{window}.
545 This makes possible to use @code{count-screen-lines} in any buffer,
546 whether or not it is currently displayed in some window.
547 @end defun
549 @defun compute-motion from frompos to topos width offsets window
550 This function scans the current buffer, calculating screen positions.
551 It scans the buffer forward from position @var{from}, assuming that is
552 at screen coordinates @var{frompos}, to position @var{to} or coordinates
553 @var{topos}, whichever comes first.  It returns the ending buffer
554 position and screen coordinates.
556 The coordinate arguments @var{frompos} and @var{topos} are cons cells of
557 the form @code{(@var{hpos} . @var{vpos})}.
559 The argument @var{width} is the number of columns available to display
560 text; this affects handling of continuation lines.  Use the value
561 returned by @code{window-width} for the window of your choice;
562 normally, use @code{(window-width @var{window})}.
564 The argument @var{offsets} is either @code{nil} or a cons cell of the
565 form @code{(@var{hscroll} . @var{tab-offset})}.  Here @var{hscroll} is
566 the number of columns not being displayed at the left margin; most
567 callers get this by calling @code{window-hscroll}.  Meanwhile,
568 @var{tab-offset} is the offset between column numbers on the screen and
569 column numbers in the buffer.  This can be nonzero in a continuation
570 line, when the previous screen lines' widths do not add up to a multiple
571 of @code{tab-width}.  It is always zero in a non-continuation line.
573 The window @var{window} serves only to specify which display table to
574 use.  @code{compute-motion} always operates on the current buffer,
575 regardless of what buffer is displayed in @var{window}.
577 The return value is a list of five elements:
579 @example
580 (@var{pos} @var{vpos} @var{hpos} @var{prevhpos} @var{contin})
581 @end example
583 @noindent
584 Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
585 is the vertical screen position, and @var{hpos} is the horizontal screen
586 position.
588 The result @var{prevhpos} is the horizontal position one character back
589 from @var{pos}.  The result @var{contin} is @code{t} if the last line
590 was continued after (or within) the previous character.
592 For example, to find the buffer position of column @var{col} of screen line
593 @var{line} of a certain window, pass the window's display start location
594 as @var{from} and the window's upper-left coordinates as @var{frompos}.
595 Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
596 the end of the accessible portion of the buffer, and pass @var{line} and
597 @var{col} as @var{topos}.  Here's a function that does this:
599 @example
600 (defun coordinates-of-position (col line)
601   (car (compute-motion (window-start)
602                        '(0 . 0)
603                        (point-max)
604                        (cons col line)
605                        (window-width)
606                        (cons (window-hscroll) 0)
607                        (selected-window))))
608 @end example
610 When you use @code{compute-motion} for the minibuffer, you need to use
611 @code{minibuffer-prompt-width} to get the horizontal position of the
612 beginning of the first screen line.  @xref{Minibuffer Misc}.
613 @end defun
615 @node List Motion
616 @comment  node-name,  next,  previous,  up
617 @subsection Moving over Balanced Expressions 
618 @cindex sexp motion
619 @cindex Lisp expression motion
620 @cindex list motion
622   Here are several functions concerned with balanced-parenthesis
623 expressions (also called @dfn{sexps} in connection with moving across
624 them in Emacs).  The syntax table controls how these functions interpret
625 various characters; see @ref{Syntax Tables}.  @xref{Parsing
626 Expressions}, for lower-level primitives for scanning sexps or parts of
627 sexps.  For user-level commands, see @ref{Lists Commands,,, emacs, The GNU
628 Emacs Manual}.
630 @deffn Command forward-list &optional arg
631 This function moves forward across @var{arg} (default 1) balanced groups of
632 parentheses.  (Other syntactic entities such as words or paired string
633 quotes are ignored.)
634 @end deffn
636 @deffn Command backward-list &optional arg
637 This function moves backward across @var{arg} (default 1) balanced groups of
638 parentheses.  (Other syntactic entities such as words or paired string
639 quotes are ignored.)
640 @end deffn
642 @deffn Command up-list &optional arg
643 This function moves forward out of @var{arg} (default 1) levels of parentheses.
644 A negative argument means move backward but still to a less deep spot.
645 @end deffn
647 @deffn Command down-list &optional arg
648 This function moves forward into @var{arg} (default 1) levels of parentheses.  A
649 negative argument means move backward but still go
650 deeper in parentheses (@minus{}@var{arg} levels).
651 @end deffn
653 @deffn Command forward-sexp &optional arg
654 This function moves forward across @var{arg} (default 1) balanced expressions.
655 Balanced expressions include both those delimited by parentheses and
656 other kinds, such as words and string constants.  For example,
658 @example
659 @group
660 ---------- Buffer: foo ----------
661 (concat@point{} "foo " (car x) y z)
662 ---------- Buffer: foo ----------
663 @end group
665 @group
666 (forward-sexp 3)
667      @result{} nil
669 ---------- Buffer: foo ----------
670 (concat "foo " (car x) y@point{} z)
671 ---------- Buffer: foo ----------
672 @end group
673 @end example
674 @end deffn
676 @deffn Command backward-sexp &optional arg
677 This function moves backward across @var{arg} (default 1) balanced expressions.
678 @end deffn
680 @deffn Command beginning-of-defun arg
681 This function moves back to the @var{arg}th beginning of a defun.  If
682 @var{arg} is negative, this actually moves forward, but it still moves
683 to the beginning of a defun, not to the end of one.
684 @end deffn
686 @deffn Command end-of-defun arg
687 This function moves forward to the @var{arg}th end of a defun.  If
688 @var{arg} is negative, this actually moves backward, but it still moves
689 to the end of a defun, not to the beginning of one.
690 @end deffn
692 @defopt defun-prompt-regexp
693 If non-@code{nil}, this variable holds a regular expression that
694 specifies what text can appear before the open-parenthesis that starts a
695 defun.  That is to say, a defun begins on a line that starts with a
696 match for this regular expression, followed by a character with
697 open-parenthesis syntax.
698 @end defopt
700 @defvar beginning-of-defun-function
701 @tindex beginning-of-defun-function
702 If non-@code{nil}, this variable holds a function for finding the
703 beginning of a defun.  The function @code{beginning-of-defun}
704 calls this function instead of using its normal method.
705 @end defvar
707 @defvar end-of-defun-function
708 @tindex end-of-defun-function
709 If non-@code{nil}, this variable holds a function for finding the end of
710 a defun.  The function @code{end-of-defun} calls this function instead
711 of using its normal method.
712 @end defvar
714 @node Skipping Characters
715 @comment  node-name,  next,  previous,  up
716 @subsection Skipping Characters
717 @cindex skipping characters
719   The following two functions move point over a specified set of
720 characters.  For example, they are often used to skip whitespace.  For
721 related functions, see @ref{Motion and Syntax}.
723 @defun skip-chars-forward character-set &optional limit
724 This function moves point in the current buffer forward, skipping over a
725 given set of characters.  It examines the character following point,
726 then advances point if the character matches @var{character-set}.  This
727 continues until it reaches a character that does not match.  The
728 function returns the number of characters moved over.
730 The argument @var{character-set} is like the inside of a
731 @samp{[@dots{}]} in a regular expression except that @samp{]} is never
732 special and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}.  Thus,
733 @code{"a-zA-Z"} skips over all letters, stopping before the first
734 nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before the
735 first letter.  @xref{Regular Expressions}.
737 If @var{limit} is supplied (it must be a number or a marker), it
738 specifies the maximum position in the buffer that point can be skipped
739 to.  Point will stop at or before @var{limit}.
741 In the following example, point is initially located directly before the
742 @samp{T}.  After the form is evaluated, point is located at the end of
743 that line (between the @samp{t} of @samp{hat} and the newline).  The
744 function skips all letters and spaces, but not newlines.
746 @example
747 @group
748 ---------- Buffer: foo ----------
749 I read "@point{}The cat in the hat
750 comes back" twice.
751 ---------- Buffer: foo ----------
752 @end group
754 @group
755 (skip-chars-forward "a-zA-Z ")
756      @result{} nil
758 ---------- Buffer: foo ----------
759 I read "The cat in the hat@point{}
760 comes back" twice.
761 ---------- Buffer: foo ----------
762 @end group
763 @end example
764 @end defun
766 @defun skip-chars-backward character-set &optional limit
767 This function moves point backward, skipping characters that match
768 @var{character-set}, until @var{limit}.  It is just like
769 @code{skip-chars-forward} except for the direction of motion.
771 The return value indicates the distance traveled.  It is an integer that
772 is zero or less.
773 @end defun
775 @node Excursions
776 @section Excursions
777 @cindex excursion
779   It is often useful to move point ``temporarily'' within a localized
780 portion of the program, or to switch buffers temporarily.  This is
781 called an @dfn{excursion}, and it is done with the @code{save-excursion}
782 special form.  This construct initially remembers the identity of the
783 current buffer, and its values of point and the mark, and restores them
784 after the completion of the excursion.
786   The forms for saving and restoring the configuration of windows are
787 described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
788 Configurations}).
790 @defspec save-excursion forms@dots{}
791 @cindex mark excursion
792 @cindex point excursion
793 @cindex current buffer excursion
794 The @code{save-excursion} special form saves the identity of the current
795 buffer and the values of point and the mark in it, evaluates
796 @var{forms}, and finally restores the buffer and its saved values of
797 point and the mark.  All three saved values are restored even in case of
798 an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
800 The @code{save-excursion} special form is the standard way to switch
801 buffers or move point within one part of a program and avoid affecting
802 the rest of the program.  It is used more than 4000 times in the Lisp
803 sources of Emacs.
805 @code{save-excursion} does not save the values of point and the mark for
806 other buffers, so changes in other buffers remain in effect after
807 @code{save-excursion} exits.
809 @cindex window excursions
810 Likewise, @code{save-excursion} does not restore window-buffer
811 correspondences altered by functions such as @code{switch-to-buffer}.
812 One way to restore these correspondences, and the selected window, is to
813 use @code{save-window-excursion} inside @code{save-excursion}
814 (@pxref{Window Configurations}).
816 The value returned by @code{save-excursion} is the result of the last of
817 @var{forms}, or @code{nil} if no @var{forms} are given.
819 @example
820 @group
821 (save-excursion @var{forms})
822 @equiv{}
823 (let ((old-buf (current-buffer))
824       (old-pnt (point-marker))
825 @end group
826       (old-mark (copy-marker (mark-marker))))
827   (unwind-protect
828       (progn @var{forms})
829     (set-buffer old-buf)
830 @group
831     (goto-char old-pnt)
832     (set-marker (mark-marker) old-mark)))
833 @end group
834 @end example
835 @end defspec
837   @strong{Warning:} Ordinary insertion of text adjacent to the saved
838 point value relocates the saved value, just as it relocates all markers.
839 Therefore, when the saved point value is restored, it normally comes
840 before the inserted text.
842   Although @code{save-excursion} saves the location of the mark, it does
843 not prevent functions which modify the buffer from setting
844 @code{deactivate-mark}, and thus causing the deactivation of the mark
845 after the command finishes.  @xref{The Mark}.
847 @node Narrowing
848 @section Narrowing
849 @cindex narrowing
850 @cindex restriction (in a buffer)
851 @cindex accessible portion (of a buffer)
853   @dfn{Narrowing} means limiting the text addressable by Emacs editing
854 commands to a limited range of characters in a buffer.  The text that
855 remains addressable is called the @dfn{accessible portion} of the
856 buffer.
858   Narrowing is specified with two buffer positions which become the
859 beginning and end of the accessible portion.  For most editing commands
860 and most Emacs primitives, these positions replace the values of the
861 beginning and end of the buffer.  While narrowing is in effect, no text
862 outside the accessible portion is displayed, and point cannot move
863 outside the accessible portion.
865   Values such as positions or line numbers, which usually count from the
866 beginning of the buffer, do so despite narrowing, but the functions
867 which use them refuse to operate on text that is inaccessible.
869   The commands for saving buffers are unaffected by narrowing; they save
870 the entire buffer regardless of any narrowing.
872 @deffn Command narrow-to-region start end
873 This function sets the accessible portion of the current buffer to start
874 at @var{start} and end at @var{end}.  Both arguments should be character
875 positions.
877 In an interactive call, @var{start} and @var{end} are set to the bounds
878 of the current region (point and the mark, with the smallest first).
879 @end deffn
881 @deffn Command narrow-to-page move-count
882 This function sets the accessible portion of the current buffer to
883 include just the current page.  An optional first argument
884 @var{move-count} non-@code{nil} means to move forward or backward by
885 @var{move-count} pages and then narrow to one page.  The variable
886 @code{page-delimiter} specifies where pages start and end
887 (@pxref{Standard Regexps}).
889 In an interactive call, @var{move-count} is set to the numeric prefix
890 argument.
891 @end deffn
893 @deffn Command widen
894 @cindex widening
895 This function cancels any narrowing in the current buffer, so that the
896 entire contents are accessible.  This is called @dfn{widening}.
897 It is equivalent to the following expression:
899 @example
900 (narrow-to-region 1 (1+ (buffer-size)))
901 @end example
902 @end deffn
904 @defspec save-restriction body@dots{}
905 This special form saves the current bounds of the accessible portion,
906 evaluates the @var{body} forms, and finally restores the saved bounds,
907 thus restoring the same state of narrowing (or absence thereof) formerly
908 in effect.  The state of narrowing is restored even in the event of an
909 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
910 Therefore, this construct is a clean way to narrow a buffer temporarily.
912 The value returned by @code{save-restriction} is that returned by the
913 last form in @var{body}, or @code{nil} if no body forms were given.
915 @c Wordy to avoid overfull hbox.  --rjc 16mar92
916 @strong{Caution:} it is easy to make a mistake when using the
917 @code{save-restriction} construct.  Read the entire description here
918 before you try it.
920 If @var{body} changes the current buffer, @code{save-restriction} still
921 restores the restrictions on the original buffer (the buffer whose
922 restrictions it saved from), but it does not restore the identity of the
923 current buffer.
925 @code{save-restriction} does @emph{not} restore point and the mark; use
926 @code{save-excursion} for that.  If you use both @code{save-restriction}
927 and @code{save-excursion} together, @code{save-excursion} should come
928 first (on the outside).  Otherwise, the old point value would be
929 restored with temporary narrowing still in effect.  If the old point
930 value were outside the limits of the temporary narrowing, this would
931 fail to restore it accurately.
933 Here is a simple example of correct use of @code{save-restriction}:
935 @example
936 @group
937 ---------- Buffer: foo ----------
938 This is the contents of foo
939 This is the contents of foo
940 This is the contents of foo@point{}
941 ---------- Buffer: foo ----------
942 @end group
944 @group
945 (save-excursion
946   (save-restriction
947     (goto-char 1)
948     (forward-line 2)
949     (narrow-to-region 1 (point))
950     (goto-char (point-min))
951     (replace-string "foo" "bar")))
953 ---------- Buffer: foo ----------
954 This is the contents of bar
955 This is the contents of bar
956 This is the contents of foo@point{}
957 ---------- Buffer: foo ----------
958 @end group
959 @end example
960 @end defspec