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