(calendar-mode-line-format): do not use #' on undefined functions
[emacs.git] / lispref / positions.texi
blob67e33cb2cbe50be32650ff702bef13bbc24c3b92
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 portion 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}.
494 @defun vertical-motion count &optional window
495 This function moves point to the start of the screen line @var{count}
496 screen lines down from the screen line containing point.  If @var{count}
497 is negative, it moves up instead.
499 @code{vertical-motion} returns the number of screen lines over which it
500 moved point.  The value may be less in absolute value than @var{count}
501 if the beginning or end of the buffer was reached.
503 The window @var{window} is used for obtaining parameters such as the
504 width, the horizontal scrolling, and the display table.  But
505 @code{vertical-motion} always operates on the current buffer, even if
506 @var{window} currently displays some other buffer.
507 @end defun
509 @defun count-screen-lines &optional beg end count-final-newline window
510 This function returns the number of screen lines in the text from
511 @var{beg} to @var{end}.  The number of screen lines may be different
512 from the number of actual lines, due to line continuation, the display
513 table, etc.  If @var{beg} and @var{end} are @code{nil} or omitted,
514 they default to the beginning and end of the accessible portion of the
515 buffer.
517 If the region ends with a newline, that is ignored unless the optional
518 third argument @var{count-final-newline} is non-@code{nil}.
520 The optional fourth argument @var{window} specifies the window for
521 obtaining parameters such as width, horizontal scrolling, and so on.
522 The default is to use the selected window's parameters.
524 Like @code{vertical-motion}, @code{count-screen-lines} always uses the
525 current buffer, regardless of which buffer is displayed in
526 @var{window}.  This makes possible to use @code{count-screen-lines} in
527 any buffer, whether or not it is currently displayed in some window.
528 @end defun
530 @deffn Command move-to-window-line count
531 This function moves point with respect to the text currently displayed
532 in the selected window.  It moves point to the beginning of the screen
533 line @var{count} screen lines from the top of the window.  If
534 @var{count} is negative, that specifies a position
535 @w{@minus{}@var{count}} lines from the bottom (or the last line of the
536 buffer, if the buffer ends above the specified screen position).
538 If @var{count} is @code{nil}, then point moves to the beginning of the
539 line in the middle of the window.  If the absolute value of @var{count}
540 is greater than the size of the window, then point moves to the place
541 that would appear on that screen line if the window were tall enough.
542 This will probably cause the next redisplay to scroll to bring that
543 location onto the screen.
545 In an interactive call, @var{count} is the numeric prefix argument.
547 The value returned is the window line number point has moved to, with
548 the top line in the window numbered 0.
549 @end deffn
551 @defun compute-motion from frompos to topos width offsets window
552 This function scans the current buffer, calculating screen positions.
553 It scans the buffer forward from position @var{from}, assuming that is
554 at screen coordinates @var{frompos}, to position @var{to} or coordinates
555 @var{topos}, whichever comes first.  It returns the ending buffer
556 position and screen coordinates.
558 The coordinate arguments @var{frompos} and @var{topos} are cons cells of
559 the form @code{(@var{hpos} . @var{vpos})}.
561 The argument @var{width} is the number of columns available to display
562 text; this affects handling of continuation lines.  Use the value
563 returned by @code{window-width} for the window of your choice;
564 normally, use @code{(window-width @var{window})}.
566 The argument @var{offsets} is either @code{nil} or a cons cell of the
567 form @code{(@var{hscroll} . @var{tab-offset})}.  Here @var{hscroll} is
568 the number of columns not being displayed at the left margin; most
569 callers get this by calling @code{window-hscroll}.  Meanwhile,
570 @var{tab-offset} is the offset between column numbers on the screen and
571 column numbers in the buffer.  This can be nonzero in a continuation
572 line, when the previous screen lines' widths do not add up to a multiple
573 of @code{tab-width}.  It is always zero in a non-continuation line.
575 The window @var{window} serves only to specify which display table to
576 use.  @code{compute-motion} always operates on the current buffer,
577 regardless of what buffer is displayed in @var{window}.
579 The return value is a list of five elements:
581 @example
582 (@var{pos} @var{vpos} @var{hpos} @var{prevhpos} @var{contin})
583 @end example
585 @noindent
586 Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
587 is the vertical screen position, and @var{hpos} is the horizontal screen
588 position.
590 The result @var{prevhpos} is the horizontal position one character back
591 from @var{pos}.  The result @var{contin} is @code{t} if the last line
592 was continued after (or within) the previous character.
594 For example, to find the buffer position of column @var{col} of screen line
595 @var{line} of a certain window, pass the window's display start location
596 as @var{from} and the window's upper-left coordinates as @var{frompos}.
597 Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
598 the end of the accessible portion of the buffer, and pass @var{line} and
599 @var{col} as @var{topos}.  Here's a function that does this:
601 @example
602 (defun coordinates-of-position (col line)
603   (car (compute-motion (window-start)
604                        '(0 . 0)
605                        (point-max)
606                        (cons col line)
607                        (window-width)
608                        (cons (window-hscroll) 0)
609                        (selected-window))))
610 @end example
612 When you use @code{compute-motion} for the minibuffer, you need to use
613 @code{minibuffer-prompt-width} to get the horizontal position of the
614 beginning of the first screen line.  @xref{Minibuffer Misc}.
615 @end defun
617 @node List Motion
618 @comment  node-name,  next,  previous,  up
619 @subsection Moving over Balanced Expressions 
620 @cindex sexp motion
621 @cindex Lisp expression motion
622 @cindex list motion
624   Here are several functions concerned with balanced-parenthesis
625 expressions (also called @dfn{sexps} in connection with moving across
626 them in Emacs).  The syntax table controls how these functions interpret
627 various characters; see @ref{Syntax Tables}.  @xref{Parsing
628 Expressions}, for lower-level primitives for scanning sexps or parts of
629 sexps.  For user-level commands, see @ref{Lists Commands,,, emacs, The GNU
630 Emacs Manual}.
632 @deffn Command forward-list &optional arg
633 This function moves forward across @var{arg} (default 1) balanced groups of
634 parentheses.  (Other syntactic entities such as words or paired string
635 quotes are ignored.)
636 @end deffn
638 @deffn Command backward-list &optional arg
639 This function moves backward across @var{arg} (default 1) balanced groups of
640 parentheses.  (Other syntactic entities such as words or paired string
641 quotes are ignored.)
642 @end deffn
644 @deffn Command up-list &optional arg
645 This function moves forward out of @var{arg} (default 1) levels of parentheses.
646 A negative argument means move backward but still to a less deep spot.
647 @end deffn
649 @deffn Command down-list &optional arg
650 This function moves forward into @var{arg} (default 1) levels of parentheses.  A
651 negative argument means move backward but still go
652 deeper in parentheses (@minus{}@var{arg} levels).
653 @end deffn
655 @deffn Command forward-sexp &optional arg
656 This function moves forward across @var{arg} (default 1) balanced expressions.
657 Balanced expressions include both those delimited by parentheses and
658 other kinds, such as words and string constants.  For example,
660 @example
661 @group
662 ---------- Buffer: foo ----------
663 (concat@point{} "foo " (car x) y z)
664 ---------- Buffer: foo ----------
665 @end group
667 @group
668 (forward-sexp 3)
669      @result{} nil
671 ---------- Buffer: foo ----------
672 (concat "foo " (car x) y@point{} z)
673 ---------- Buffer: foo ----------
674 @end group
675 @end example
676 @end deffn
678 @deffn Command backward-sexp &optional arg
679 This function moves backward across @var{arg} (default 1) balanced expressions.
680 @end deffn
682 @deffn Command beginning-of-defun arg
683 This function moves back to the @var{arg}th beginning of a defun.  If
684 @var{arg} is negative, this actually moves forward, but it still moves
685 to the beginning of a defun, not to the end of one.
686 @end deffn
688 @deffn Command end-of-defun arg
689 This function moves forward to the @var{arg}th end of a defun.  If
690 @var{arg} is negative, this actually moves backward, but it still moves
691 to the end of a defun, not to the beginning of one.
692 @end deffn
694 @defopt defun-prompt-regexp
695 If non-@code{nil}, this variable holds a regular expression that
696 specifies what text can appear before the open-parenthesis that starts a
697 defun.  That is to say, a defun begins on a line that starts with a
698 match for this regular expression, followed by a character with
699 open-parenthesis syntax.
700 @end defopt
702 @defopt open-paren-in-column-0-is-defun-start
703 If this variable's value is non-@code{nil}, an open parenthesis in
704 column 0 is considered to be the start of a defun.  If it is
705 @code{nil}, an open parenthesis in column 0 has no special meaning.
706 The default is @code{t}.
707 @end defopt
709 @defvar beginning-of-defun-function
710 @tindex beginning-of-defun-function
711 If non-@code{nil}, this variable holds a function for finding the
712 beginning of a defun.  The function @code{beginning-of-defun}
713 calls this function instead of using its normal method.
714 @end defvar
716 @defvar end-of-defun-function
717 @tindex end-of-defun-function
718 If non-@code{nil}, this variable holds a function for finding the end of
719 a defun.  The function @code{end-of-defun} calls this function instead
720 of using its normal method.
721 @end defvar
723 @node Skipping Characters
724 @comment  node-name,  next,  previous,  up
725 @subsection Skipping Characters
726 @cindex skipping characters
728   The following two functions move point over a specified set of
729 characters.  For example, they are often used to skip whitespace.  For
730 related functions, see @ref{Motion and Syntax}.
732 @defun skip-chars-forward character-set &optional limit
733 This function moves point in the current buffer forward, skipping over a
734 given set of characters.  It examines the character following point,
735 then advances point if the character matches @var{character-set}.  This
736 continues until it reaches a character that does not match.  The
737 function returns the number of characters moved over.
739 The argument @var{character-set} is like the inside of a
740 @samp{[@dots{}]} in a regular expression except that @samp{]} is never
741 special and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}.  Thus,
742 @code{"a-zA-Z"} skips over all letters, stopping before the first
743 nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before the
744 first letter.  @xref{Regular Expressions}.
746 If @var{limit} is supplied (it must be a number or a marker), it
747 specifies the maximum position in the buffer that point can be skipped
748 to.  Point will stop at or before @var{limit}.
750 In the following example, point is initially located directly before the
751 @samp{T}.  After the form is evaluated, point is located at the end of
752 that line (between the @samp{t} of @samp{hat} and the newline).  The
753 function skips all letters and spaces, but not newlines.
755 @example
756 @group
757 ---------- Buffer: foo ----------
758 I read "@point{}The cat in the hat
759 comes back" twice.
760 ---------- Buffer: foo ----------
761 @end group
763 @group
764 (skip-chars-forward "a-zA-Z ")
765      @result{} nil
767 ---------- Buffer: foo ----------
768 I read "The cat in the hat@point{}
769 comes back" twice.
770 ---------- Buffer: foo ----------
771 @end group
772 @end example
773 @end defun
775 @defun skip-chars-backward character-set &optional limit
776 This function moves point backward, skipping characters that match
777 @var{character-set}, until @var{limit}.  It is just like
778 @code{skip-chars-forward} except for the direction of motion.
780 The return value indicates the distance traveled.  It is an integer that
781 is zero or less.
782 @end defun
784 @node Excursions
785 @section Excursions
786 @cindex excursion
788   It is often useful to move point ``temporarily'' within a localized
789 portion of the program, or to switch buffers temporarily.  This is
790 called an @dfn{excursion}, and it is done with the @code{save-excursion}
791 special form.  This construct initially remembers the identity of the
792 current buffer, and its values of point and the mark, and restores them
793 after the completion of the excursion.
795   The forms for saving and restoring the configuration of windows are
796 described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
797 Configurations}).
799 @defspec save-excursion forms@dots{}
800 @cindex mark excursion
801 @cindex point excursion
802 @cindex current buffer excursion
803 The @code{save-excursion} special form saves the identity of the current
804 buffer and the values of point and the mark in it, evaluates
805 @var{forms}, and finally restores the buffer and its saved values of
806 point and the mark.  All three saved values are restored even in case of
807 an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
809 The @code{save-excursion} special form is the standard way to switch
810 buffers or move point within one part of a program and avoid affecting
811 the rest of the program.  It is used more than 4000 times in the Lisp
812 sources of Emacs.
814 @code{save-excursion} does not save the values of point and the mark for
815 other buffers, so changes in other buffers remain in effect after
816 @code{save-excursion} exits.
818 @cindex window excursions
819 Likewise, @code{save-excursion} does not restore window-buffer
820 correspondences altered by functions such as @code{switch-to-buffer}.
821 One way to restore these correspondences, and the selected window, is to
822 use @code{save-window-excursion} inside @code{save-excursion}
823 (@pxref{Window Configurations}).
825 The value returned by @code{save-excursion} is the result of the last of
826 @var{forms}, or @code{nil} if no @var{forms} are given.
828 @example
829 @group
830 (save-excursion @var{forms})
831 @equiv{}
832 (let ((old-buf (current-buffer))
833       (old-pnt (point-marker))
834 @end group
835       (old-mark (copy-marker (mark-marker))))
836   (unwind-protect
837       (progn @var{forms})
838     (set-buffer old-buf)
839 @group
840     (goto-char old-pnt)
841     (set-marker (mark-marker) old-mark)))
842 @end group
843 @end example
844 @end defspec
846   @strong{Warning:} Ordinary insertion of text adjacent to the saved
847 point value relocates the saved value, just as it relocates all markers.
848 Therefore, when the saved point value is restored, it normally comes
849 before the inserted text.
851   Although @code{save-excursion} saves the location of the mark, it does
852 not prevent functions which modify the buffer from setting
853 @code{deactivate-mark}, and thus causing the deactivation of the mark
854 after the command finishes.  @xref{The Mark}.
856 @node Narrowing
857 @section Narrowing
858 @cindex narrowing
859 @cindex restriction (in a buffer)
860 @cindex accessible portion (of a buffer)
862   @dfn{Narrowing} means limiting the text addressable by Emacs editing
863 commands to a limited range of characters in a buffer.  The text that
864 remains addressable is called the @dfn{accessible portion} of the
865 buffer.
867   Narrowing is specified with two buffer positions which become the
868 beginning and end of the accessible portion.  For most editing commands
869 and most Emacs primitives, these positions replace the values of the
870 beginning and end of the buffer.  While narrowing is in effect, no text
871 outside the accessible portion is displayed, and point cannot move
872 outside the accessible portion.
874   Values such as positions or line numbers, which usually count from the
875 beginning of the buffer, do so despite narrowing, but the functions
876 which use them refuse to operate on text that is inaccessible.
878   The commands for saving buffers are unaffected by narrowing; they save
879 the entire buffer regardless of any narrowing.
881 @deffn Command narrow-to-region start end
882 This function sets the accessible portion of the current buffer to start
883 at @var{start} and end at @var{end}.  Both arguments should be character
884 positions.
886 In an interactive call, @var{start} and @var{end} are set to the bounds
887 of the current region (point and the mark, with the smallest first).
888 @end deffn
890 @deffn Command narrow-to-page move-count
891 This function sets the accessible portion of the current buffer to
892 include just the current page.  An optional first argument
893 @var{move-count} non-@code{nil} means to move forward or backward by
894 @var{move-count} pages and then narrow to one page.  The variable
895 @code{page-delimiter} specifies where pages start and end
896 (@pxref{Standard Regexps}).
898 In an interactive call, @var{move-count} is set to the numeric prefix
899 argument.
900 @end deffn
902 @deffn Command widen
903 @cindex widening
904 This function cancels any narrowing in the current buffer, so that the
905 entire contents are accessible.  This is called @dfn{widening}.
906 It is equivalent to the following expression:
908 @example
909 (narrow-to-region 1 (1+ (buffer-size)))
910 @end example
911 @end deffn
913 @defspec save-restriction body@dots{}
914 This special form saves the current bounds of the accessible portion,
915 evaluates the @var{body} forms, and finally restores the saved bounds,
916 thus restoring the same state of narrowing (or absence thereof) formerly
917 in effect.  The state of narrowing is restored even in the event of an
918 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
919 Therefore, this construct is a clean way to narrow a buffer temporarily.
921 The value returned by @code{save-restriction} is that returned by the
922 last form in @var{body}, or @code{nil} if no body forms were given.
924 @c Wordy to avoid overfull hbox.  --rjc 16mar92
925 @strong{Caution:} it is easy to make a mistake when using the
926 @code{save-restriction} construct.  Read the entire description here
927 before you try it.
929 If @var{body} changes the current buffer, @code{save-restriction} still
930 restores the restrictions on the original buffer (the buffer whose
931 restrictions it saved from), but it does not restore the identity of the
932 current buffer.
934 @code{save-restriction} does @emph{not} restore point and the mark; use
935 @code{save-excursion} for that.  If you use both @code{save-restriction}
936 and @code{save-excursion} together, @code{save-excursion} should come
937 first (on the outside).  Otherwise, the old point value would be
938 restored with temporary narrowing still in effect.  If the old point
939 value were outside the limits of the temporary narrowing, this would
940 fail to restore it accurately.
942 Here is a simple example of correct use of @code{save-restriction}:
944 @example
945 @group
946 ---------- Buffer: foo ----------
947 This is the contents of foo
948 This is the contents of foo
949 This is the contents of foo@point{}
950 ---------- Buffer: foo ----------
951 @end group
953 @group
954 (save-excursion
955   (save-restriction
956     (goto-char 1)
957     (forward-line 2)
958     (narrow-to-region 1 (point))
959     (goto-char (point-min))
960     (replace-string "foo" "bar")))
962 ---------- Buffer: foo ----------
963 This is the contents of bar
964 This is the contents of bar
965 This is the contents of foo@point{}
966 ---------- Buffer: foo ----------
967 @end group
968 @end example
969 @end defspec