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