2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/positions.info
8 @node Positions, Markers, Consoles and Devices, Top
10 @cindex position (in buffer)
12 A @dfn{position} is the index of a character in the text of a buffer.
13 More precisely, a position identifies the place between two characters
14 (or before the first character, or after the last character), so we can
15 speak of the character before or after a given position. However, we
16 often speak of the character ``at'' a position, meaning the character
19 Positions are usually represented as integers starting from 1, but can
20 also be represented as @dfn{markers}---special objects that relocate
21 automatically when text is inserted or deleted so they stay with the
22 surrounding characters. @xref{Markers}.
25 * Point:: The special position where editing takes place.
26 * Motion:: Changing point.
27 * Excursions:: Temporary motion and buffer changes.
28 * Narrowing:: Restricting editing to a portion of the buffer.
36 @dfn{Point} is a special buffer position used by many editing
37 commands, including the self-inserting typed characters and text
38 insertion functions. Other commands move point through the text
39 to allow editing and insertion at different places.
41 Like other positions, point designates a place between two characters
42 (or before the first character, or after the last character), rather
43 than a particular character. Usually terminals display the cursor over
44 the character that immediately follows point; point is actually before
45 the character on which the cursor sits.
47 @cindex point with narrowing
48 The value of point is a number between 1 and the buffer size plus 1.
49 If narrowing is in effect (@pxref{Narrowing}), then point is constrained
50 to fall within the accessible portion of the buffer (possibly at one end
53 Each buffer has its own value of point, which is independent of the
54 value of point in other buffers. Each window also has a value of point,
55 which is independent of the value of point in other windows on the same
56 buffer. This is why point can have different values in various windows
57 that display the same buffer. When a buffer appears in only one window,
58 the buffer's point and the window's point normally have the same value,
59 so the distinction is rarely important. @xref{Window Point}, for more
62 @defun point &optional buffer
63 @cindex current buffer position
64 This function returns the value of point in @var{buffer}, as an integer.
65 @var{buffer} defaults to the current buffer if omitted.
76 @defun point-min &optional buffer
77 This function returns the minimum accessible value of point in
78 @var{buffer}. This is normally 1, but if narrowing is in effect, it is
79 the position of the start of the region that you narrowed to.
80 (@xref{Narrowing}.) @var{buffer} defaults to the current buffer if
84 @defun point-max &optional buffer
85 This function returns the maximum accessible value of point in
86 @var{buffer}. This is @code{(1+ (buffer-size buffer))}, unless
87 narrowing is in effect, in which case it is the position of the end of
88 the region that you narrowed to. (@pxref{Narrowing}). @var{buffer}
89 defaults to the current buffer if omitted.
92 @defun buffer-end flag &optional buffer
93 This function returns @code{(point-min buffer)} if @var{flag} is less
94 than 1, @code{(point-max buffer)} otherwise. The argument @var{flag}
95 must be a number. @var{buffer} defaults to the current buffer if
99 @defun buffer-size &optional buffer
100 This function returns the total number of characters in @var{buffer}.
101 In the absence of any narrowing (@pxref{Narrowing}), @code{point-max}
102 returns a value one larger than this. @var{buffer} defaults to the
103 current buffer if omitted.
117 @defvar buffer-saved-size
118 The value of this buffer-local variable is the former length of the
119 current buffer, as of the last time it was read in, saved or auto-saved.
126 Motion functions change the value of point, either relative to the
127 current value of point, relative to the beginning or end of the buffer,
128 or relative to the edges of the selected window. @xref{Point}.
131 * Character Motion:: Moving in terms of characters.
132 * Word Motion:: Moving in terms of words.
133 * Buffer End Motion:: Moving to the beginning or end of the buffer.
134 * Text Lines:: Moving in terms of lines of text.
135 * Screen Lines:: Moving in terms of lines as displayed.
136 * List Motion:: Moving by parsing lists and sexps.
137 * Skipping Characters:: Skipping characters belonging to a certain set.
141 @node Character Motion
142 @subsection Motion by Characters
144 These functions move point based on a count of characters.
145 @code{goto-char} is the fundamental primitive; the other functions use
148 @deffn Command goto-char position &optional buffer
149 This function sets point in @code{buffer} to the value @var{position}.
150 If @var{position} is less than 1, it moves point to the beginning of the
151 buffer. If @var{position} is greater than the length of the buffer, it
152 moves point to the end. @var{buffer} defaults to the current buffer if
155 If narrowing is in effect, @var{position} still counts from the
156 beginning of the buffer, but point cannot go outside the accessible
157 portion. If @var{position} is out of range, @code{goto-char} moves
158 point to the beginning or the end of the accessible portion.
160 When this function is called interactively, @var{position} is the
161 numeric prefix argument, if provided; otherwise it is read from the
164 @code{goto-char} returns @var{position}.
167 @deffn Command forward-char &optional count buffer
168 @c @kindex beginning-of-buffer
169 @c @kindex end-of-buffer
170 This function moves point @var{count} characters forward, towards the
171 end of the buffer (or backward, towards the beginning of the buffer, if
172 @var{count} is negative). If the function attempts to move point past
173 the beginning or end of the buffer (or the limits of the accessible
174 portion, when narrowing is in effect), an error is signaled with error
175 code @code{beginning-of-buffer} or @code{end-of-buffer}. @var{buffer}
176 defaults to the current buffer if omitted.
179 In an interactive call, @var{count} is the numeric prefix argument.
182 @deffn Command backward-char &optional count buffer
183 This function moves point @var{count} characters backward, towards the
184 beginning of the buffer (or forward, towards the end of the buffer, if
185 @var{count} is negative). If the function attempts to move point past
186 the beginning or end of the buffer (or the limits of the accessible
187 portion, when narrowing is in effect), an error is signaled with error
188 code @code{beginning-of-buffer} or @code{end-of-buffer}. @var{buffer}
189 defaults to the current buffer if omitted.
192 In an interactive call, @var{count} is the numeric prefix argument.
197 @subsection Motion by Words
199 These functions for parsing words use the syntax table to decide
200 whether a given character is part of a word. @xref{Syntax Tables}.
202 @deffn Command forward-word &optional count buffer
203 This function moves point forward @var{count} words (or backward if
204 @var{count} is negative). Normally it returns @code{t}. If this motion
205 encounters the beginning or end of the buffer, or the limits of the
206 accessible portion when narrowing is in effect, point stops there and
207 the value is @code{nil}.
209 @var{count} defaults to @code{1} and @var{buffer} defaults to the
212 In an interactive call, @var{count} is set to the numeric prefix
216 @deffn Command backward-word &optional count buffer
217 This function is just like @code{forward-word}, except that it moves
218 backward until encountering the front of a word, rather than forward.
219 @var{buffer} defaults to the current buffer if omitted.
221 In an interactive call, @var{count} is set to the numeric prefix
225 @defvar words-include-escapes
227 This variable affects the behavior of @code{forward-word} and everything
228 that uses it. If it is non-@code{nil}, then characters in the
229 ``escape'' and ``character quote'' syntax classes count as part of
230 words. Otherwise, they do not.
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:
241 (goto-char (point-min))
246 Likewise, to move to the end of the buffer, use:
250 (goto-char (point-max))
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 count
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{count} is non-@code{nil}, then it
262 puts point @var{count} tenths of the way from the beginning of the buffer.
264 In an interactive call, @var{count} is the numeric prefix argument,
265 if provided; otherwise @var{count} defaults to @code{nil}.
267 Don't use this function in Lisp programs!
270 @deffn Command end-of-buffer &optional count
271 This function moves point to the end of the buffer (or the limits of
272 the accessible portion, when narrowing is in effect), setting the mark
273 at the previous position. If @var{count} is non-@code{nil}, then it puts
274 point @var{count} tenths of the way from the end of the buffer.
276 In an interactive call, @var{count} is the numeric prefix argument,
277 if provided; otherwise @var{count} defaults to @code{nil}.
279 Don't use this function in Lisp programs!
284 @subsection Motion by Text Lines
287 Text lines are portions of the buffer delimited by newline characters,
288 which are regarded as part of the previous line. The first text line
289 begins at the beginning of the buffer, and the last text line ends at
290 the end of the buffer whether or not the last character is a newline.
291 The division of the buffer into text lines is not affected by the width
292 of the window, by line continuation in display, or by how tabs and
293 control characters are displayed.
295 @deffn Command goto-line line
296 This function moves point to the front of the @var{line}th line,
297 counting from line 1 at beginning of the buffer. If @var{line} is less
298 than 1, it moves point to the beginning of the buffer. If @var{line} is
299 greater than the number of lines in the buffer, it moves point to the
300 end of the buffer---that is, the @emph{end of the last line} of the
301 buffer. This is the only case in which @code{goto-line} does not
302 necessarily move to the beginning of a line.
304 If narrowing is in effect, then @var{line} still counts from the
305 beginning of the buffer, but point cannot go outside the accessible
306 portion. So @code{goto-line} moves point to the beginning or end of the
307 accessible portion, if the line number specifies an inaccessible
310 The return value of @code{goto-line} is the difference between
311 @var{line} and the line number of the line to which point actually was
312 able to move (in the full buffer, before taking account of narrowing).
313 Thus, the value is positive if the scan encounters the real end of the
314 buffer. The value is zero if scan encounters the end of the accessible
315 portion but not the real end of the buffer.
317 In an interactive call, @var{line} is the numeric prefix argument if
318 one has been provided. Otherwise @var{line} is read in the minibuffer.
321 @deffn Command beginning-of-line &optional count buffer
322 This function moves point to the beginning of the current line. With an
323 argument @var{count} not @code{nil} or 1, it moves forward
324 @var{count}@minus{}1 lines and then to the beginning of the line.
325 @var{buffer} defaults to the current buffer if omitted.
327 If this function reaches the end of the buffer (or of the accessible
328 portion, if narrowing is in effect), it positions point there. No error
332 @deffn Command end-of-line &optional count buffer
333 This function moves point to the end of the current line. With an
334 argument @var{count} not @code{nil} or 1, it moves forward
335 @var{count}@minus{}1 lines and then to the end of the line.
336 @var{buffer} defaults to the current buffer if omitted.
338 If this function reaches the end of the buffer (or of the accessible
339 portion, if narrowing is in effect), it positions point there. No error
343 @deffn Command forward-line &optional count buffer
344 @cindex beginning of line
345 This function moves point forward @var{count} lines, to the beginning of
346 the line. If @var{count} is negative, it moves point
347 @minus{}@var{count} lines backward, to the beginning of a line. If
348 @var{count} is zero, it moves point to the beginning of the current
349 line. @var{buffer} defaults to the current buffer if omitted.
351 If @code{forward-line} encounters the beginning or end of the buffer (or
352 of the accessible portion) before finding that many lines, it sets point
353 there. No error is signaled.
355 @code{forward-line} returns the difference between @var{count} and the
356 number of lines actually moved. If you attempt to move down five lines
357 from the beginning of a buffer that has only three lines, point stops at
358 the end of the last line, and the value will be 2.
360 In an interactive call, @var{count} is the numeric prefix argument.
363 @defun count-lines start end &optional ignore-invisible-lines-flag
364 @cindex lines in region
365 This function returns the number of lines between the positions
366 @var{start} and @var{end} in the current buffer. If @var{start} and
367 @var{end} are equal, then it returns 0. Otherwise it returns at least
368 1, even if @var{start} and @var{end} are on the same line. This is
369 because the text between them, considered in isolation, must contain at
370 least one line unless it is empty.
372 With optional @var{ignore-invisible-lines-flag} non-@code{nil}, lines
373 collapsed with selective-display are excluded from the line count.
375 @strong{N.B.} The expression to return the current line number is not
379 (1+ (count-lines 1 (point-at-bol)))
382 Here is an example of using @code{count-lines}:
386 (defun current-line ()
387 "Return the vertical position of point@dots{}"
388 (+ (count-lines (window-start) (point))
389 (if (= (current-column) 0) 1 0)
397 The @code{previous-line} and @code{next-line} commands are functions
398 that should not be used in programs. They are for users and are
399 mentioned here only for completeness.
401 @deffn Command previous-line count
403 This function moves point up @var{count} lines (down if @var{count}
404 is negative). In moving, it attempts to keep point in the ``goal column''
405 (normally the same column that it was at the beginning of the move).
407 If there is no character in the target line exactly under the current
408 column, point is positioned after the character in that line which
409 spans this column, or at the end of the line if it is not long enough.
411 If it attempts to move beyond the top or bottom of the buffer (or clipped
412 region), then point is positioned in the goal column in the top or
413 bottom line. No error is signaled.
415 In an interactive call, @var{count} will be the numeric
418 The command @code{set-goal-column} can be used to create a semipermanent
419 goal column to which this command always moves. Then it does not try to
422 If you are thinking of using this in a Lisp program, consider using
423 @code{forward-line} with a negative argument instead. It is usually easier
424 to use and more reliable (no dependence on goal column, etc.).
427 @deffn Command next-line count
428 This function moves point down @var{count} lines (up if @var{count}
429 is negative). In moving, it attempts to keep point in the ``goal column''
430 (normally the same column that it was at the beginning of the move).
432 If there is no character in the target line exactly under the current
433 column, point is positioned after the character in that line which
434 spans this column, or at the end of the line if it is not long enough.
436 If it attempts to move beyond the top or bottom of the buffer (or clipped
437 region), then point is positioned in the goal column in the top or
438 bottom line. No error is signaled.
440 In the case where the @var{count} is 1, and point is on the last
441 line of the buffer (or clipped region), a new empty line is inserted at the
442 end of the buffer (or clipped region) and point moved there.
444 In an interactive call, @var{count} will be the numeric
447 The command @code{set-goal-column} can be used to create a semipermanent
448 goal column to which this command always moves. Then it does not try to
451 If you are thinking of using this in a Lisp program, consider using
452 @code{forward-line} instead. It is usually easier
453 to use and more reliable (no dependence on goal column, etc.).
459 Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}.
460 These functions do not move point, but test whether it is already at the
461 beginning or end of a line.
465 @subsection Motion by Screen Lines
467 The line functions in the previous section count text lines, delimited
468 only by newline characters. By contrast, these functions count screen
469 lines, which are defined by the way the text appears on the screen. A
470 text line is a single screen line if it is short enough to fit the width
471 of the selected window, but otherwise it may occupy several screen
474 In some cases, text lines are truncated on the screen rather than
475 continued onto additional screen lines. In these cases,
476 @code{vertical-motion} moves point much like @code{forward-line}.
479 Because the width of a given string depends on the flags that control
480 the appearance of certain characters, @code{vertical-motion} behaves
481 differently, for a given piece of text, depending on the buffer it is
482 in, and even on the selected window (because the width, the truncation
483 flag, and display table may vary between windows). @xref{Usual
486 These functions scan text to determine where screen lines break, and
487 thus take time proportional to the distance scanned. If you intend to
488 use them heavily, SXEmacs provides caches which may improve the
489 performance of your code. @xref{Text Lines, cache-long-line-scans}.
492 @defun vertical-motion count &optional window pixels
493 This function moves point to the start of the frame line @var{count}
494 frame lines down from the frame line containing point. If @var{count}
495 is negative, it moves up instead. The optional second argument
496 @var{window} may be used to specify a window other than the
497 selected window in which to perform the motion.
499 Normally, @code{vertical-motion} returns the number of lines moved. The
500 value may be less in absolute value than @var{count} if the beginning or
501 end of the buffer was reached. If the optional third argument,
502 @var{pixels} is non-@code{nil}, the vertical pixel height of the motion
503 which took place is returned instead of the actual number of lines
504 moved. A motion of zero lines returns the height of the current line.
506 Note that @code{vertical-motion} sets @var{window}'s buffer's point, not
507 @var{window}'s point. (This differs from FSF Emacs, which buggily always
508 sets current buffer's point, regardless of @var{window}.)
511 @defun vertical-motion-pixels count &optional window how
512 This function moves point to the start of the frame line @var{pixels}
513 vertical pixels down from the frame line containing point, or up if
514 @var{pixels} is negative. The optional second argument @var{window} is
515 the window to move in, and defaults to the selected window. The
516 optional third argument @var{how} specifies the stopping condition. A
517 negative integer indicates that the motion should be no more
518 than @var{pixels}. A positive value indicates that the
519 motion should be at least @var{pixels}. Any other value indicates
520 that the motion should be as close as possible to @var{pixels}.
523 @deffn Command move-to-window-line count &optional window
524 This function moves point with respect to the text currently displayed
525 in @var{window}, which defaults to the selected window. It moves point
526 to the beginning of the screen line @var{count} screen lines from the
527 top of the window. If @var{count} is negative, that specifies a
528 position @w{@minus{}@var{count}} lines from the bottom (or the last line
529 of the buffer, if the buffer ends above the specified screen position).
531 If @var{count} is @code{nil}, then point moves to the beginning of the
532 line in the middle of the window. If the absolute value of @var{count}
533 is greater than the size of the window, then point moves to the place
534 that would appear on that screen line if the window were tall enough.
535 This will probably cause the next redisplay to scroll to bring that
536 location onto the screen.
538 In an interactive call, @var{count} is the numeric prefix argument.
540 The value returned is the window line number point has moved to, with
541 the top line in the window numbered 0.
544 @ignore Not in SXEmacs+XEmacs
545 @defun compute-motion from frompos to topos width offsets window
546 This function scans the current buffer, calculating screen positions.
547 It scans the buffer forward from position @var{from}, assuming that is
548 at screen coordinates @var{frompos}, to position @var{to} or coordinates
549 @var{topos}, whichever comes first. It returns the ending buffer
550 position and screen coordinates.
552 The coordinate arguments @var{frompos} and @var{topos} are cons cells of
553 the form @code{(@var{hpos} . @var{vpos})}.
555 The argument @var{width} is the number of columns available to display
556 text; this affects handling of continuation lines. Use the value
557 returned by @code{window-width} for the window of your choice;
558 normally, use @code{(window-width @var{window})}.
560 The argument @var{offsets} is either @code{nil} or a cons cell of the
561 form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is
562 the number of columns not being displayed at the left margin; most
563 callers get this from @code{window-hscroll}. Meanwhile,
564 @var{tab-offset} is the offset between column numbers on the screen and
565 column numbers in the buffer. This can be nonzero in a continuation
566 line, when the previous screen lines' widths do not add up to a multiple
567 of @code{tab-width}. It is always zero in a non-continuation line.
569 The window @var{window} serves only to specify which display table to
570 use. @code{compute-motion} always operates on the current buffer,
571 regardless of what buffer is displayed in @var{window}.
573 The return value is a list of five elements:
576 (@var{pos} @var{vpos} @var{hpos} @var{prevhpos} @var{contin})
580 Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
581 is the vertical screen position, and @var{hpos} is the horizontal screen
584 The result @var{prevhpos} is the horizontal position one character back
585 from @var{pos}. The result @var{contin} is @code{t} if the last line
586 was continued after (or within) the previous character.
588 For example, to find the buffer position of column @var{col} of line
589 @var{line} of a certain window, pass the window's display start location
590 as @var{from} and the window's upper-left coordinates as @var{frompos}.
591 Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
592 the end of the accessible portion of the buffer, and pass @var{line} and
593 @var{col} as @var{topos}. Here's a function that does this:
596 (defun coordinates-of-position (col line)
597 (car (compute-motion (window-start)
602 (cons (window-hscroll) 0)
606 When you use @code{compute-motion} for the minibuffer, you need to use
607 @code{minibuffer-prompt-width} to get the horizontal position of the
608 beginning of the first screen line. @xref{Minibuffer Misc}.
614 @subsection Moving over Balanced Expressions
616 @cindex Lisp expression motion
619 Here are several functions concerned with balanced-parenthesis
620 expressions (also called @dfn{sexps} in connection with moving across
621 them in SXEmacs). The syntax table controls how these functions interpret
622 various characters; see @ref{Syntax Tables}. @xref{Parsing
623 Expressions}, for lower-level primitives for scanning sexps or parts of
624 sexps. For user-level commands, see @ref{Lists and Sexps,,, sxemacs, SXEmacs
627 @deffn Command forward-list &optional arg
628 This function moves forward across @var{arg} balanced groups of
629 parentheses. (Other syntactic entities such as words or paired string
630 quotes are ignored.) @var{arg} defaults to 1 if omitted. If @var{arg}
631 is negative, move backward across that many groups of parentheses.
634 @deffn Command backward-list &optional count
635 This function moves backward across @var{count} balanced groups of
636 parentheses. (Other syntactic entities such as words or paired string
637 quotes are ignored.) @var{count} defaults to 1 if omitted. If
638 @var{count} is negative, move forward across that many groups of
642 @deffn Command up-list &optional count
643 This function moves forward out of @var{count} levels of parentheses.
644 A negative argument means move backward but still to a less deep spot.
647 @deffn Command down-list &optional count
648 This function moves forward into @var{count} levels of parentheses.
649 A negative argument means move backward but still go deeper in
650 parentheses (@minus{}@var{count} levels).
653 @deffn Command forward-sexp &optional count
654 This function moves forward across @var{count} balanced expressions.
655 Balanced expressions include both those delimited by parentheses and
656 other kinds, such as words and string constants. @var{count} defaults to
657 1 if omitted. If @var{count} is negative, move backward across that many
658 balanced expressions. For example,
662 ---------- Buffer: foo ----------
663 (concat@point{} "foo " (car x) y z)
664 ---------- Buffer: foo ----------
671 ---------- Buffer: foo ----------
672 (concat "foo " (car x) y@point{} z)
673 ---------- Buffer: foo ----------
678 @deffn Command backward-sexp &optional count
679 This function moves backward across @var{count} balanced expressions.
680 @var{count} defaults to 1 if omitted. If @var{count} is negative, move
681 forward across that many balanced expressions.
684 @deffn Command beginning-of-defun &optional count
685 This function moves back to the @var{count}th beginning of a defun.
686 If @var{count} is negative, this actually moves forward, but it still
687 moves to the beginning of a defun, not to the end of one. @var{count}
688 defaults to 1 if omitted.
691 @deffn Command end-of-defun &optional count
692 This function moves forward to the @var{count}th end of a defun.
693 If @var{count} is negative, this actually moves backward, but it still
694 moves to the end of a defun, not to the beginning of one. @var{count}
695 defaults to 1 if omitted.
698 @defopt defun-prompt-regexp
699 If non-@code{nil}, this variable holds a regular expression that
700 specifies what text can appear before the open-parenthesis that starts a
701 defun. That is to say, a defun begins on a line that starts with a
702 match for this regular expression, followed by a character with
703 open-parenthesis syntax.
707 @node Skipping Characters
708 @subsection Skipping Characters
709 @cindex skipping characters
711 The following two functions move point over a specified set of
712 characters. For example, they are often used to skip whitespace. For
713 related functions, see @ref{Motion and Syntax}.
715 @defun skip-chars-forward character-set &optional limit buffer
716 This function moves point in @var{buffer} forward, skipping over a
717 given set of characters. It examines the character following point,
718 then advances point if the character matches @var{character-set}. This
719 continues until it reaches a character that does not match. The
720 function returns @code{nil}. @var{buffer} defaults to the current
723 The argument @var{character-set} is like the inside of a
724 @samp{[@dots{}]} in a regular expression except that @samp{]} is never
725 special and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}. Thus,
726 @code{"a-zA-Z"} skips over all letters, stopping before the first
727 non-letter, and @code{"^a-zA-Z}" skips non-letters stopping before the
728 first letter. @xref{Regular Expressions}.
730 If @var{limit} is supplied (it must be a number or a marker), it
731 specifies the maximum position in the buffer that point can be skipped
732 to. Point will stop at or before @var{limit}.
734 In the following example, point is initially located directly before the
735 @samp{T}. After the form is evaluated, point is located at the end of
736 that line (between the @samp{t} of @samp{hat} and the newline). The
737 function skips all letters and spaces, but not newlines.
741 ---------- Buffer: foo ----------
742 I read "@point{}The cat in the hat
744 ---------- Buffer: foo ----------
748 (skip-chars-forward "a-zA-Z ")
751 ---------- Buffer: foo ----------
752 I read "The cat in the hat@point{}
754 ---------- Buffer: foo ----------
759 @defun skip-chars-backward character-set &optional limit buffer
760 This function moves point backward, skipping characters that match
761 @var{character-set}, until @var{limit}. It just like
762 @code{skip-chars-forward} except for the direction of motion.
770 It is often useful to move point ``temporarily'' within a localized
771 portion of the program, or to switch buffers temporarily. This is
772 called an @dfn{excursion}, and it is done with the @code{save-excursion}
773 special form. This construct saves the current buffer and its values of
774 point and the mark so they can be restored after the completion of the
777 The forms for saving and restoring the configuration of windows are
778 described elsewhere (see @ref{Window Configurations} and @pxref{Frame
781 @defspec save-excursion forms@dots{}
782 @cindex mark excursion
783 @cindex point excursion
784 @cindex current buffer excursion
785 The @code{save-excursion} special form saves the identity of the current
786 buffer and the values of point and the mark in it, evaluates
787 @var{forms}, and finally restores the buffer and its saved values of
788 point and the mark. All three saved values are restored even in case of
789 an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
791 The @code{save-excursion} special form is the standard way to switch
792 buffers or move point within one part of a program and avoid affecting
793 the rest of the program. It is used more than 500 times in the Lisp
796 @code{save-excursion} does not save the values of point and the mark for
797 other buffers, so changes in other buffers remain in effect after
798 @code{save-excursion} exits.
800 @cindex window excursions
801 Likewise, @code{save-excursion} does not restore window-buffer
802 correspondences altered by functions such as @code{switch-to-buffer}.
803 One way to restore these correspondences, and the selected window, is to
804 use @code{save-window-excursion} inside @code{save-excursion}
805 (@pxref{Window Configurations}).
807 The value returned by @code{save-excursion} is the result of the last of
808 @var{forms}, or @code{nil} if no @var{forms} are given.
815 (let ((old-buf (current-buffer))
816 (old-pnt (point-marker))
817 (old-mark (copy-marker (mark-marker))))
822 (set-marker (mark-marker) old-mark)))
827 @defspec save-current-buffer forms@dots{}
828 This special form is similar to @code{save-excursion} but it only
829 saves and restores the current buffer. Beginning with XEmacs 20.3,
830 @code{save-current-buffer} is a primitive.
833 @defspec with-current-buffer buffer forms@dots{}
834 This special form evaluates @var{forms} with @var{buffer} as the current
835 buffer. It returns the value of the last form.
838 @defspec with-temp-file filename forms@dots{}
839 This special form creates a new buffer, evaluates @var{forms} there, and
840 writes the buffer to @var{filename}. It returns the value of the last form
844 @defspec save-selected-window forms@dots{}
845 This special form is similar to @code{save-excursion} but it saves and
846 restores the selected window and nothing else.
853 @cindex restriction (in a buffer)
854 @cindex accessible portion (of a buffer)
856 @dfn{Narrowing} means limiting the text addressable by SXEmacs editing
857 commands to a limited range of characters in a buffer. The text that
858 remains addressable is called the @dfn{accessible portion} of the
861 Narrowing is specified with two buffer positions which become the
862 beginning and end of the accessible portion. For most editing commands
863 and most SXEmacs primitives, these positions replace the values of the
864 beginning and end of the buffer. While narrowing is in effect, no text
865 outside the accessible portion is displayed, and point cannot move
866 outside the accessible portion.
868 Values such as positions or line numbers, which usually count from the
869 beginning of the buffer, do so despite narrowing, but the functions
870 which use them refuse to operate on text that is inaccessible.
872 The commands for saving buffers are unaffected by narrowing; they save
873 the entire buffer regardless of any narrowing.
875 @deffn Command narrow-to-region start end &optional buffer
876 This function sets the accessible portion of @var{buffer} to start at
877 @var{start} and end at @var{end}. Both arguments should be character
878 positions. @var{buffer} defaults to the current buffer if omitted.
880 In an interactive call, @var{start} and @var{end} are set to the bounds
881 of the current region (point and the mark, with the smallest first).
884 @deffn Command narrow-to-page &optional move-count
885 This function sets the accessible portion of the current buffer to
886 include just the current page. An optional first argument
887 @var{move-count} non-@code{nil} means to move forward or backward by
888 @var{move-count} pages and then narrow. The variable
889 @code{page-delimiter} specifies where pages start and end
890 (@pxref{Standard Regexps}).
892 In an interactive call, @var{move-count} is set to the numeric prefix
896 @deffn Command widen &optional buffer
898 This function cancels any narrowing in @var{buffer}, so that the
899 entire contents are accessible. This is called @dfn{widening}.
900 It is equivalent to the following expression:
903 (narrow-to-region 1 (1+ (buffer-size)))
906 @var{buffer} defaults to the current buffer if omitted.
909 @defspec save-restriction body@dots{}
910 This special form saves the current bounds of the accessible portion,
911 evaluates the @var{body} forms, and finally restores the saved bounds,
912 thus restoring the same state of narrowing (or absence thereof) formerly
913 in effect. The state of narrowing is restored even in the event of an
914 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
915 Therefore, this construct is a clean way to narrow a buffer temporarily.
917 The value returned by @code{save-restriction} is that returned by the
918 last form in @var{body}, or @code{nil} if no body forms were given.
920 @c Wordy to avoid overfull hbox. --rjc 16mar92
921 @strong{Caution:} it is easy to make a mistake when using the
922 @code{save-restriction} construct. Read the entire description here
925 If @var{body} changes the current buffer, @code{save-restriction} still
926 restores the restrictions on the original buffer (the buffer whose
927 restrictions it saved from), but it does not restore the identity of the
930 @code{save-restriction} does @emph{not} restore point and the mark; use
931 @code{save-excursion} for that. If you use both @code{save-restriction}
932 and @code{save-excursion} together, @code{save-excursion} should come
933 first (on the outside). Otherwise, the old point value would be
934 restored with temporary narrowing still in effect. If the old point
935 value were outside the limits of the temporary narrowing, this would
936 fail to restore it accurately.
938 The @code{save-restriction} special form records the values of the
939 beginning and end of the accessible portion as distances from the
940 beginning and end of the buffer. In other words, it records the amount
941 of inaccessible text before and after the accessible portion.
943 This method yields correct results if @var{body} does further narrowing.
944 However, @code{save-restriction} can become confused if the body widens
945 and then make changes outside the range of the saved narrowing. When
946 this is what you want to do, @code{save-restriction} is not the right
947 tool for the job. Here is what you must use instead:
951 (let ((start (point-min-marker))
952 (end (point-max-marker)))
956 (set-buffer (marker-buffer start))
957 (narrow-to-region start end))))
961 Here is a simple example of correct use of @code{save-restriction}:
965 ---------- Buffer: foo ----------
966 This is the contents of foo
967 This is the contents of foo
968 This is the contents of foo@point{}
969 ---------- Buffer: foo ----------
977 (narrow-to-region 1 (point))
978 (goto-char (point-min))
979 (replace-string "foo" "bar")))
981 ---------- Buffer: foo ----------
982 This is the contents of bar
983 This is the contents of bar
984 This is the contents of foo@point{}
985 ---------- Buffer: foo ----------