1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: The Selected Console and Device, Next: Console and Device I/O, Prev: Connecting to a Console or Device, Up: Consoles and Devices
55 The Selected Console and Device
56 ===============================
58 - Function: select-console console
59 This function selects the console CONSOLE. Subsequent editing
60 commands apply to its selected device, selected frame, and selected
61 window. The selection of CONSOLE lasts until the next time the
62 user does something to select a different console, or until the
63 next time this function is called.
65 - Function: selected-console
66 This function returns the console which is currently active.
68 - Function: select-device device
69 This function selects the device DEVICE.
71 - Function: selected-device &optional console
72 This function returns the device which is currently active. If
73 optional CONSOLE is non-`nil', this function returns the device
74 that would be currently active if CONSOLE were the selected
78 File: lispref.info, Node: Console and Device I/O, Prev: The Selected Console and Device, Up: Consoles and Devices
80 Console and Device I/O
81 ======================
83 - Function: console-disable-input console
84 This function disables input on console CONSOLE.
86 - Function: console-enable-input console
87 This function enables input on console CONSOLE.
89 Each device has a "baud rate" value associated with it. On most
90 systems, changing this value will affect the amount of padding and
91 other strategic decisions made during redisplay.
93 - Function: device-baud-rate &optional device
94 This function returns the output baud rate of DEVICE.
96 - Function: set-device-baud-rate device rate
97 This function sets the output baud rate of DEVICE to RATE.
100 File: lispref.info, Node: Positions, Next: Markers, Prev: Consoles and Devices, Up: Top
105 A "position" is the index of a character in the text of a buffer.
106 More precisely, a position identifies the place between two characters
107 (or before the first character, or after the last character), so we can
108 speak of the character before or after a given position. However, we
109 often speak of the character "at" a position, meaning the character
112 Positions are usually represented as integers starting from 1, but
113 can also be represented as "markers"--special objects that relocate
114 automatically when text is inserted or deleted so they stay with the
115 surrounding characters. *Note Markers::.
119 * Point:: The special position where editing takes place.
120 * Motion:: Changing point.
121 * Excursions:: Temporary motion and buffer changes.
122 * Narrowing:: Restricting editing to a portion of the buffer.
125 File: lispref.info, Node: Point, Next: Motion, Up: Positions
130 "Point" is a special buffer position used by many editing commands,
131 including the self-inserting typed characters and text insertion
132 functions. Other commands move point through the text to allow editing
133 and insertion at different places.
135 Like other positions, point designates a place between two characters
136 (or before the first character, or after the last character), rather
137 than a particular character. Usually terminals display the cursor over
138 the character that immediately follows point; point is actually before
139 the character on which the cursor sits.
141 The value of point is a number between 1 and the buffer size plus 1.
142 If narrowing is in effect (*note Narrowing::), then point is constrained
143 to fall within the accessible portion of the buffer (possibly at one end
146 Each buffer has its own value of point, which is independent of the
147 value of point in other buffers. Each window also has a value of point,
148 which is independent of the value of point in other windows on the same
149 buffer. This is why point can have different values in various windows
150 that display the same buffer. When a buffer appears in only one window,
151 the buffer's point and the window's point normally have the same value,
152 so the distinction is rarely important. *Note Window Point::, for more
155 - Function: point &optional buffer
156 This function returns the value of point in BUFFER, as an integer.
157 BUFFER defaults to the current buffer if omitted.
162 - Function: point-min &optional buffer
163 This function returns the minimum accessible value of point in
164 BUFFER. This is normally 1, but if narrowing is in effect, it is
165 the position of the start of the region that you narrowed to.
166 (*Note Narrowing::.) BUFFER defaults to the current buffer if
169 - Function: point-max &optional buffer
170 This function returns the maximum accessible value of point in
171 BUFFER. This is `(1+ (buffer-size buffer))', unless narrowing is
172 in effect, in which case it is the position of the end of the
173 region that you narrowed to. (*note Narrowing::). BUFFER defaults
174 to the current buffer if omitted.
176 - Function: buffer-end flag &optional buffer
177 This function returns `(point-min buffer)' if FLAG is less than 1,
178 `(point-max buffer)' otherwise. The argument FLAG must be a
179 number. BUFFER defaults to the current buffer if omitted.
181 - Function: buffer-size &optional buffer
182 This function returns the total number of characters in BUFFER.
183 In the absence of any narrowing (*note Narrowing::), `point-max'
184 returns a value one larger than this. BUFFER defaults to the
185 current buffer if omitted.
192 - Variable: buffer-saved-size
193 The value of this buffer-local variable is the former length of the
194 current buffer, as of the last time it was read in, saved or
198 File: lispref.info, Node: Motion, Next: Excursions, Prev: Point, Up: Positions
203 Motion functions change the value of point, either relative to the
204 current value of point, relative to the beginning or end of the buffer,
205 or relative to the edges of the selected window. *Note Point::.
209 * Character Motion:: Moving in terms of characters.
210 * Word Motion:: Moving in terms of words.
211 * Buffer End Motion:: Moving to the beginning or end of the buffer.
212 * Text Lines:: Moving in terms of lines of text.
213 * Screen Lines:: Moving in terms of lines as displayed.
214 * List Motion:: Moving by parsing lists and sexps.
215 * Skipping Characters:: Skipping characters belonging to a certain set.
218 File: lispref.info, Node: Character Motion, Next: Word Motion, Up: Motion
223 These functions move point based on a count of characters.
224 `goto-char' is the fundamental primitive; the other functions use that.
226 - Command: goto-char position &optional buffer
227 This function sets point in `buffer' to the value POSITION. If
228 POSITION is less than 1, it moves point to the beginning of the
229 buffer. If POSITION is greater than the length of the buffer, it
230 moves point to the end. BUFFER defaults to the current buffer if
233 If narrowing is in effect, POSITION still counts from the
234 beginning of the buffer, but point cannot go outside the accessible
235 portion. If POSITION is out of range, `goto-char' moves point to
236 the beginning or the end of the accessible portion.
238 When this function is called interactively, POSITION is the
239 numeric prefix argument, if provided; otherwise it is read from the
242 `goto-char' returns POSITION.
244 - Command: forward-char &optional count buffer
245 This function moves point COUNT characters forward, towards the
246 end of the buffer (or backward, towards the beginning of the
247 buffer, if COUNT is negative). If the function attempts to move
248 point past the beginning or end of the buffer (or the limits of
249 the accessible portion, when narrowing is in effect), an error is
250 signaled with error code `beginning-of-buffer' or `end-of-buffer'.
251 BUFFER defaults to the current buffer if omitted.
253 In an interactive call, COUNT is the numeric prefix argument.
255 - Command: backward-char &optional count buffer
256 This function moves point COUNT characters backward, towards the
257 beginning of the buffer (or forward, towards the end of the
258 buffer, if COUNT is negative). If the function attempts to move
259 point past the beginning or end of the buffer (or the limits of
260 the accessible portion, when narrowing is in effect), an error is
261 signaled with error code `beginning-of-buffer' or `end-of-buffer'.
262 BUFFER defaults to the current buffer if omitted.
264 In an interactive call, COUNT is the numeric prefix argument.
267 File: lispref.info, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion
272 These functions for parsing words use the syntax table to decide
273 whether a given character is part of a word. *Note Syntax Tables::.
275 - Command: forward-word count &optional buffer
276 This function moves point forward COUNT words (or backward if
277 COUNT is negative). Normally it returns `t'. If this motion
278 encounters the beginning or end of the buffer, or the limits of the
279 accessible portion when narrowing is in effect, point stops there
280 and the value is `nil'. BUFFER defaults to the current buffer if
283 In an interactive call, COUNT is set to the numeric prefix
286 - Command: backward-word count &optional buffer
287 This function is just like `forward-word', except that it moves
288 backward until encountering the front of a word, rather than
289 forward. BUFFER defaults to the current buffer if omitted.
291 In an interactive call, COUNT is set to the numeric prefix
294 This function is rarely used in programs, as it is more efficient
295 to call `forward-word' with a negative argument.
297 - Variable: words-include-escapes
298 This variable affects the behavior of `forward-word' and everything
299 that uses it. If it is non-`nil', then characters in the "escape"
300 and "character quote" syntax classes count as part of words.
301 Otherwise, they do not.
304 File: lispref.info, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion
306 Motion to an End of the Buffer
307 ------------------------------
309 To move point to the beginning of the buffer, write:
311 (goto-char (point-min))
313 Likewise, to move to the end of the buffer, use:
315 (goto-char (point-max))
317 Here are two commands that users use to do these things. They are
318 documented here to warn you not to use them in Lisp programs, because
319 they set the mark and display messages in the echo area.
321 - Command: beginning-of-buffer &optional n
322 This function moves point to the beginning of the buffer (or the
323 limits of the accessible portion, when narrowing is in effect),
324 setting the mark at the previous position. If N is non-`nil',
325 then it puts point N tenths of the way from the beginning of the
328 In an interactive call, N is the numeric prefix argument, if
329 provided; otherwise N defaults to `nil'.
331 Don't use this function in Lisp programs!
333 - Command: end-of-buffer &optional n
334 This function moves point to the end of the buffer (or the limits
335 of the accessible portion, when narrowing is in effect), setting
336 the mark at the previous position. If N is non-`nil', then it puts
337 point N tenths of the way from the end of the buffer.
339 In an interactive call, N is the numeric prefix argument, if
340 provided; otherwise N defaults to `nil'.
342 Don't use this function in Lisp programs!
345 File: lispref.info, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion
350 Text lines are portions of the buffer delimited by newline
351 characters, which are regarded as part of the previous line. The first
352 text line begins at the beginning of the buffer, and the last text line
353 ends at the end of the buffer whether or not the last character is a
354 newline. The division of the buffer into text lines is not affected by
355 the width of the window, by line continuation in display, or by how
356 tabs and control characters are displayed.
358 - Command: goto-line line
359 This function moves point to the front of the LINEth line,
360 counting from line 1 at beginning of the buffer. If LINE is less
361 than 1, it moves point to the beginning of the buffer. If LINE is
362 greater than the number of lines in the buffer, it moves point to
363 the end of the buffer--that is, the _end of the last line_ of the
364 buffer. This is the only case in which `goto-line' does not
365 necessarily move to the beginning of a line.
367 If narrowing is in effect, then LINE still counts from the
368 beginning of the buffer, but point cannot go outside the accessible
369 portion. So `goto-line' moves point to the beginning or end of the
370 accessible portion, if the line number specifies an inaccessible
373 The return value of `goto-line' is the difference between LINE and
374 the line number of the line to which point actually was able to
375 move (in the full buffer, before taking account of narrowing).
376 Thus, the value is positive if the scan encounters the real end of
377 the buffer. The value is zero if scan encounters the end of the
378 accessible portion but not the real end of the buffer.
380 In an interactive call, LINE is the numeric prefix argument if one
381 has been provided. Otherwise LINE is read in the minibuffer.
383 - Command: beginning-of-line &optional count buffer
384 This function moves point to the beginning of the current line.
385 With an argument COUNT not `nil' or 1, it moves forward COUNT-1
386 lines and then to the beginning of the line. BUFFER defaults to
387 the current buffer if omitted.
389 If this function reaches the end of the buffer (or of the
390 accessible portion, if narrowing is in effect), it positions point
391 there. No error is signaled.
393 - Command: end-of-line &optional count buffer
394 This function moves point to the end of the current line. With an
395 argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
396 then to the end of the line. BUFFER defaults to the current
399 If this function reaches the end of the buffer (or of the
400 accessible portion, if narrowing is in effect), it positions point
401 there. No error is signaled.
403 - Command: forward-line &optional count buffer
404 This function moves point forward COUNT lines, to the beginning of
405 the line. If COUNT is negative, it moves point -COUNT lines
406 backward, to the beginning of a line. If COUNT is zero, it moves
407 point to the beginning of the current line. BUFFER defaults to
408 the current buffer if omitted.
410 If `forward-line' encounters the beginning or end of the buffer (or
411 of the accessible portion) before finding that many lines, it sets
412 point there. No error is signaled.
414 `forward-line' returns the difference between COUNT and the number
415 of lines actually moved. If you attempt to move down five lines
416 from the beginning of a buffer that has only three lines, point
417 stops at the end of the last line, and the value will be 2.
419 In an interactive call, COUNT is the numeric prefix argument.
421 - Function: count-lines start end
422 This function returns the number of lines between the positions
423 START and END in the current buffer. If START and END are equal,
424 then it returns 0. Otherwise it returns at least 1, even if START
425 and END are on the same line. This is because the text between
426 them, considered in isolation, must contain at least one line
429 Here is an example of using `count-lines':
431 (defun current-line ()
432 "Return the vertical position of point..."
433 (+ (count-lines (window-start) (point))
434 (if (= (current-column) 0) 1 0)
437 Also see the functions `bolp' and `eolp' in *Note Near Point::.
438 These functions do not move point, but test whether it is already at the
439 beginning or end of a line.
442 File: lispref.info, Node: Screen Lines, Next: List Motion, Prev: Text Lines, Up: Motion
444 Motion by Screen Lines
445 ----------------------
447 The line functions in the previous section count text lines,
448 delimited only by newline characters. By contrast, these functions
449 count screen lines, which are defined by the way the text appears on
450 the screen. A text line is a single screen line if it is short enough
451 to fit the width of the selected window, but otherwise it may occupy
452 several screen lines.
454 In some cases, text lines are truncated on the screen rather than
455 continued onto additional screen lines. In these cases,
456 `vertical-motion' moves point much like `forward-line'. *Note
459 Because the width of a given string depends on the flags that control
460 the appearance of certain characters, `vertical-motion' behaves
461 differently, for a given piece of text, depending on the buffer it is
462 in, and even on the selected window (because the width, the truncation
463 flag, and display table may vary between windows). *Note Usual
466 These functions scan text to determine where screen lines break, and
467 thus take time proportional to the distance scanned. If you intend to
468 use them heavily, Emacs provides caches which may improve the
469 performance of your code. *Note cache-long-line-scans: Text Lines.
471 - Function: vertical-motion count &optional window pixels
472 This function moves point to the start of the frame line COUNT
473 frame lines down from the frame line containing point. If COUNT
474 is negative, it moves up instead. The optional second argument
475 WINDOW may be used to specify a window other than the selected
476 window in which to perform the motion.
478 Normally, `vertical-motion' returns the number of lines moved. The
479 value may be less in absolute value than COUNT if the beginning or
480 end of the buffer was reached. If the optional third argument,
481 PIXELS is non-`nil', the vertical pixel height of the motion which
482 took place is returned instead of the actual number of lines
483 moved. A motion of zero lines returns the height of the current
486 Note that `vertical-motion' sets WINDOW's buffer's point, not
487 WINDOW's point. (This differs from FSF Emacs, which buggily always
488 sets current buffer's point, regardless of WINDOW.)
490 - Function: vertical-motion-pixels count &optional window how
491 This function moves point to the start of the frame line PIXELS
492 vertical pixels down from the frame line containing point, or up if
493 PIXELS is negative. The optional second argument WINDOW is the
494 window to move in, and defaults to the selected window. The
495 optional third argument HOW specifies the stopping condition. A
496 negative integer indicates that the motion should be no more than
497 PIXELS. A positive value indicates that the motion should be at
498 least PIXELS. Any other value indicates that the motion should be
499 as close as possible to PIXELS.
501 - Command: move-to-window-line count &optional window
502 This function moves point with respect to the text currently
503 displayed in WINDOW, which defaults to the selected window. It
504 moves point to the beginning of the screen line COUNT screen lines
505 from the top of the window. If COUNT is negative, that specifies a
506 position -COUNT lines from the bottom (or the last line of the
507 buffer, if the buffer ends above the specified screen position).
509 If COUNT is `nil', then point moves to the beginning of the line
510 in the middle of the window. If the absolute value of COUNT is
511 greater than the size of the window, then point moves to the place
512 that would appear on that screen line if the window were tall
513 enough. This will probably cause the next redisplay to scroll to
514 bring that location onto the screen.
516 In an interactive call, COUNT is the numeric prefix argument.
518 The value returned is the window line number point has moved to,
519 with the top line in the window numbered 0.
522 File: lispref.info, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion
524 Moving over Balanced Expressions
525 --------------------------------
527 Here are several functions concerned with balanced-parenthesis
528 expressions (also called "sexps" in connection with moving across them
529 in XEmacs). The syntax table controls how these functions interpret
530 various characters; see *Note Syntax Tables::. *Note Parsing
531 Expressions::, for lower-level primitives for scanning sexps or parts of
532 sexps. For user-level commands, see *Note Lists and Sexps:
533 (emacs)Lists and Sexps.
535 - Command: forward-list &optional arg
536 This function moves forward across ARG balanced groups of
537 parentheses. (Other syntactic entities such as words or paired
538 string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
539 is negative, move backward across that many groups of parentheses.
541 - Command: backward-list &optional arg
542 This function moves backward across ARG balanced groups of
543 parentheses. (Other syntactic entities such as words or paired
544 string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
545 is negative, move forward across that many groups of parentheses.
547 - Command: up-list arg
548 This function moves forward out of ARG levels of parentheses. A
549 negative argument means move backward but still to a less deep
552 - Command: down-list arg
553 This function moves forward into ARG levels of parentheses. A
554 negative argument means move backward but still go deeper in
555 parentheses (-ARG levels).
557 - Command: forward-sexp &optional arg
558 This function moves forward across ARG balanced expressions.
559 Balanced expressions include both those delimited by parentheses
560 and other kinds, such as words and string constants. ARG defaults
561 to 1 if omitted. If ARG is negative, move backward across that
562 many balanced expressions. For example,
564 ---------- Buffer: foo ----------
565 (concat-!- "foo " (car x) y z)
566 ---------- Buffer: foo ----------
571 ---------- Buffer: foo ----------
572 (concat "foo " (car x) y-!- z)
573 ---------- Buffer: foo ----------
575 - Command: backward-sexp &optional arg
576 This function moves backward across ARG balanced expressions. ARG
577 defaults to 1 if omitted. If ARG is negative, move forward across
578 that many balanced expressions.
580 - Command: beginning-of-defun &optional arg
581 This function moves back to the ARGth beginning of a defun. If
582 ARG is negative, this actually moves forward, but it still moves
583 to the beginning of a defun, not to the end of one. ARG defaults
586 - Command: end-of-defun &optional arg
587 This function moves forward to the ARGth end of a defun. If ARG
588 is negative, this actually moves backward, but it still moves to
589 the end of a defun, not to the beginning of one. ARG defaults to
592 - User Option: defun-prompt-regexp
593 If non-`nil', this variable holds a regular expression that
594 specifies what text can appear before the open-parenthesis that
595 starts a defun. That is to say, a defun begins on a line that
596 starts with a match for this regular expression, followed by a
597 character with open-parenthesis syntax.
600 File: lispref.info, Node: Skipping Characters, Prev: List Motion, Up: Motion
605 The following two functions move point over a specified set of
606 characters. For example, they are often used to skip whitespace. For
607 related functions, see *Note Motion and Syntax::.
609 - Function: skip-chars-forward character-set &optional limit buffer
610 This function moves point in BUFFER forward, skipping over a given
611 set of characters. It examines the character following point,
612 then advances point if the character matches CHARACTER-SET. This
613 continues until it reaches a character that does not match. The
614 function returns `nil'. BUFFER defaults to the current buffer if
617 The argument CHARACTER-SET is like the inside of a `[...]' in a
618 regular expression except that `]' is never special and `\' quotes
619 `^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters,
620 stopping before the first non-letter, and `"^a-zA-Z'" skips
621 non-letters stopping before the first letter. *Note Regular
624 If LIMIT is supplied (it must be a number or a marker), it
625 specifies the maximum position in the buffer that point can be
626 skipped to. Point will stop at or before LIMIT.
628 In the following example, point is initially located directly
629 before the `T'. After the form is evaluated, point is located at
630 the end of that line (between the `t' of `hat' and the newline).
631 The function skips all letters and spaces, but not newlines.
633 ---------- Buffer: foo ----------
634 I read "-!-The cat in the hat
636 ---------- Buffer: foo ----------
638 (skip-chars-forward "a-zA-Z ")
641 ---------- Buffer: foo ----------
642 I read "The cat in the hat-!-
644 ---------- Buffer: foo ----------
646 - Function: skip-chars-backward character-set &optional limit buffer
647 This function moves point backward, skipping characters that match
648 CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
649 except for the direction of motion.
652 File: lispref.info, Node: Excursions, Next: Narrowing, Prev: Motion, Up: Positions
657 It is often useful to move point "temporarily" within a localized
658 portion of the program, or to switch buffers temporarily. This is
659 called an "excursion", and it is done with the `save-excursion' special
660 form. This construct saves the current buffer and its values of point
661 and the mark so they can be restored after the completion of the
664 The forms for saving and restoring the configuration of windows are
665 described elsewhere (see *Note Window Configurations:: and *note Frame
668 - Special Form: save-excursion forms...
669 The `save-excursion' special form saves the identity of the current
670 buffer and the values of point and the mark in it, evaluates
671 FORMS, and finally restores the buffer and its saved values of
672 point and the mark. All three saved values are restored even in
673 case of an abnormal exit via `throw' or error (*note Nonlocal
676 The `save-excursion' special form is the standard way to switch
677 buffers or move point within one part of a program and avoid
678 affecting the rest of the program. It is used more than 500 times
679 in the Lisp sources of XEmacs.
681 `save-excursion' does not save the values of point and the mark for
682 other buffers, so changes in other buffers remain in effect after
683 `save-excursion' exits.
685 Likewise, `save-excursion' does not restore window-buffer
686 correspondences altered by functions such as `switch-to-buffer'.
687 One way to restore these correspondences, and the selected window,
688 is to use `save-window-excursion' inside `save-excursion' (*note
689 Window Configurations::).
691 The value returned by `save-excursion' is the result of the last of
692 FORMS, or `nil' if no FORMS are given.
697 (let ((old-buf (current-buffer))
698 (old-pnt (point-marker))
699 (old-mark (copy-marker (mark-marker))))
704 (set-marker (mark-marker) old-mark)))
706 - Special Form: save-current-buffer forms...
707 This special form is similar to `save-excursion' but it only saves
708 and restores the current buffer. Beginning with XEmacs 20.3,
709 `save-current-buffer' is a primitive.
711 - Special Form: with-current-buffer buffer forms...
712 This special form evaluates FORMS with BUFFER as the current
713 buffer. It returns the value of the last form.
715 - Special Form: with-temp-file file forms...
716 This special form creates a new buffer, evaluates FORMS there, and
717 writes the buffer to FILE. It returns the value of the last form
720 - Special Form: save-selected-window forms...
721 This special form is similar to `save-excursion' but it saves and
722 restores the selected window and nothing else.
725 File: lispref.info, Node: Narrowing, Prev: Excursions, Up: Positions
730 "Narrowing" means limiting the text addressable by XEmacs editing
731 commands to a limited range of characters in a buffer. The text that
732 remains addressable is called the "accessible portion" of the buffer.
734 Narrowing is specified with two buffer positions which become the
735 beginning and end of the accessible portion. For most editing commands
736 and most Emacs primitives, these positions replace the values of the
737 beginning and end of the buffer. While narrowing is in effect, no text
738 outside the accessible portion is displayed, and point cannot move
739 outside the accessible portion.
741 Values such as positions or line numbers, which usually count from
742 the beginning of the buffer, do so despite narrowing, but the functions
743 which use them refuse to operate on text that is inaccessible.
745 The commands for saving buffers are unaffected by narrowing; they
746 save the entire buffer regardless of any narrowing.
748 - Command: narrow-to-region start end &optional buffer
749 This function sets the accessible portion of BUFFER to start at
750 START and end at END. Both arguments should be character
751 positions. BUFFER defaults to the current buffer if omitted.
753 In an interactive call, START and END are set to the bounds of the
754 current region (point and the mark, with the smallest first).
756 - Command: narrow-to-page &optional move-count
757 This function sets the accessible portion of the current buffer to
758 include just the current page. An optional first argument
759 MOVE-COUNT non-`nil' means to move forward or backward by
760 MOVE-COUNT pages and then narrow. The variable `page-delimiter'
761 specifies where pages start and end (*note Standard Regexps::).
763 In an interactive call, MOVE-COUNT is set to the numeric prefix
766 - Command: widen &optional buffer
767 This function cancels any narrowing in BUFFER, so that the entire
768 contents are accessible. This is called "widening". It is
769 equivalent to the following expression:
771 (narrow-to-region 1 (1+ (buffer-size)))
773 BUFFER defaults to the current buffer if omitted.
775 - Special Form: save-restriction body...
776 This special form saves the current bounds of the accessible
777 portion, evaluates the BODY forms, and finally restores the saved
778 bounds, thus restoring the same state of narrowing (or absence
779 thereof) formerly in effect. The state of narrowing is restored
780 even in the event of an abnormal exit via `throw' or error (*note
781 Nonlocal Exits::). Therefore, this construct is a clean way to
782 narrow a buffer temporarily.
784 The value returned by `save-restriction' is that returned by the
785 last form in BODY, or `nil' if no body forms were given.
787 *Caution:* it is easy to make a mistake when using the
788 `save-restriction' construct. Read the entire description here
791 If BODY changes the current buffer, `save-restriction' still
792 restores the restrictions on the original buffer (the buffer whose
793 restrictions it saved from), but it does not restore the identity
794 of the current buffer.
796 `save-restriction' does _not_ restore point and the mark; use
797 `save-excursion' for that. If you use both `save-restriction' and
798 `save-excursion' together, `save-excursion' should come first (on
799 the outside). Otherwise, the old point value would be restored
800 with temporary narrowing still in effect. If the old point value
801 were outside the limits of the temporary narrowing, this would
802 fail to restore it accurately.
804 The `save-restriction' special form records the values of the
805 beginning and end of the accessible portion as distances from the
806 beginning and end of the buffer. In other words, it records the
807 amount of inaccessible text before and after the accessible
810 This method yields correct results if BODY does further narrowing.
811 However, `save-restriction' can become confused if the body widens
812 and then make changes outside the range of the saved narrowing.
813 When this is what you want to do, `save-restriction' is not the
814 right tool for the job. Here is what you must use instead:
816 (let ((beg (point-min-marker))
817 (end (point-max-marker)))
821 (set-buffer (marker-buffer beg))
822 (narrow-to-region beg end))))
824 Here is a simple example of correct use of `save-restriction':
826 ---------- Buffer: foo ----------
827 This is the contents of foo
828 This is the contents of foo
829 This is the contents of foo-!-
830 ---------- Buffer: foo ----------
836 (narrow-to-region 1 (point))
837 (goto-char (point-min))
838 (replace-string "foo" "bar")))
840 ---------- Buffer: foo ----------
841 This is the contents of bar
842 This is the contents of bar
843 This is the contents of foo-!-
844 ---------- Buffer: foo ----------
847 File: lispref.info, Node: Markers, Next: Text, Prev: Positions, Up: Top
852 A "marker" is a Lisp object used to specify a position in a buffer
853 relative to the surrounding text. A marker changes its offset from the
854 beginning of the buffer automatically whenever text is inserted or
855 deleted, so that it stays with the two characters on either side of it.
859 * Overview of Markers:: The components of a marker, and how it relocates.
860 * Predicates on Markers:: Testing whether an object is a marker.
861 * Creating Markers:: Making empty markers or markers at certain places.
862 * Information from Markers:: Finding the marker's buffer or character position.
863 * Changing Markers:: Moving the marker to a new buffer or position.
864 * The Mark:: How ``the mark'' is implemented with a marker.
865 * The Region:: How to access ``the region''.
868 File: lispref.info, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers
873 A marker specifies a buffer and a position in that buffer. The
874 marker can be used to represent a position in the functions that
875 require one, just as an integer could be used. *Note Positions::, for
876 a complete description of positions.
878 A marker has two attributes: the marker position, and the marker
879 buffer. The marker position is an integer that is equivalent (at a
880 given time) to the marker as a position in that buffer. But the
881 marker's position value can change often during the life of the marker.
882 Insertion and deletion of text in the buffer relocate the marker. The
883 idea is that a marker positioned between two characters remains between
884 those two characters despite insertion and deletion elsewhere in the
885 buffer. Relocation changes the integer equivalent of the marker.
887 Deleting text around a marker's position leaves the marker between
888 the characters immediately before and after the deleted text. Inserting
889 text at the position of a marker normally leaves the marker in front of
890 the new text--unless it is inserted with `insert-before-markers' (*note
893 Insertion and deletion in a buffer must check all the markers and
894 relocate them if necessary. This slows processing in a buffer with a
895 large number of markers. For this reason, it is a good idea to make a
896 marker point nowhere if you are sure you don't need it any more.
897 Unreferenced markers are garbage collected eventually, but until then
898 will continue to use time if they do point somewhere.
900 Because it is common to perform arithmetic operations on a marker
901 position, most of the arithmetic operations (including `+' and `-')
902 accept markers as arguments. In such cases, the marker stands for its
905 Note that you can use extents to achieve the same functionality, and
906 more, as markers. (Markers were defined before extents, which is why
907 they both continue to exist.) A zero-length extent with the
908 `detachable' property removed is almost identical to a marker. (*Note
909 Extent Endpoints::, for more information on zero-length extents.)
913 * In order to get marker-like behavior in a zero-length extent, the
914 `detachable' property must be removed (otherwise, the extent will
915 disappear when text near it is deleted) and exactly one endpoint
916 must be closed (if both endpoints are closed, the extent will
917 expand to contain text inserted where it is located).
919 * If a zero-length extent has the `end-open' property but not the
920 `start-open' property (this is the default), text inserted at the
921 extent's location causes the extent to move forward, just like a
924 * If a zero-length extent has the `start-open' property but not the
925 `end-open' property, text inserted at the extent's location causes
926 the extent to remain before the text, like what happens to markers
927 when `insert-before-markers' is used.
929 * Markers end up after or before inserted text depending on whether
930 `insert' or `insert-before-markers' was called. These functions
931 do not affect zero-length extents differently; instead, the
932 presence or absence of the `start-open' and `end-open' extent
933 properties determines this, as just described.
935 * Markers are automatically removed from a buffer when they are no
936 longer in use. Extents remain around until explicitly removed
939 * Many functions are provided for listing the extents in a buffer or
940 in a region of a buffer. No such functions exist for markers.
942 Here are examples of creating markers, setting markers, and moving
945 ;; Make a new marker that initially does not point anywhere:
946 (setq m1 (make-marker))
947 => #<marker in no buffer>
949 ;; Set `m1' to point between the 99th and 100th characters
950 ;; in the current buffer:
952 => #<marker at 100 in markers.texi>
954 ;; Now insert one character at the beginning of the buffer:
955 (goto-char (point-min))
960 ;; `m1' is updated appropriately.
962 => #<marker at 101 in markers.texi>
964 ;; Two markers that point to the same position
965 ;; are not `eq', but they are `equal'.
966 (setq m2 (copy-marker m1))
967 => #<marker at 101 in markers.texi>
973 ;; When you are finished using a marker, make it point nowhere.
975 => #<marker in no buffer>
978 File: lispref.info, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers
980 Predicates on Markers
981 =====================
983 You can test an object to see whether it is a marker, or whether it
984 is either an integer or a marker or either an integer, a character, or a
985 marker. The latter tests are useful in connection with the arithmetic
986 functions that work with any of markers, integers, or characters.
988 - Function: markerp object
989 This function returns `t' if OBJECT is a marker, `nil' otherwise.
990 Note that integers are not markers, even though many functions
991 will accept either a marker or an integer.
993 - Function: integer-or-marker-p object
994 This function returns `t' if OBJECT is an integer or a marker,
997 - Function: integer-char-or-marker-p object
998 This function returns `t' if OBJECT is an integer, a character, or
999 a marker, `nil' otherwise.
1001 - Function: number-or-marker-p object
1002 This function returns `t' if OBJECT is a number (either kind) or a
1003 marker, `nil' otherwise.
1005 - Function: number-char-or-marker-p object
1006 This function returns `t' if OBJECT is a number (either kind), a
1007 character, or a marker, `nil' otherwise.
1010 File: lispref.info, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers
1012 Functions That Create Markers
1013 =============================
1015 When you create a new marker, you can make it point nowhere, or point
1016 to the present position of point, or to the beginning or end of the
1017 accessible portion of the buffer, or to the same place as another given
1020 - Function: make-marker
1021 This functions returns a newly created marker that does not point
1025 => #<marker in no buffer>
1027 - Function: point-marker &optional dont-copy-p buffer
1028 This function returns a marker that points to the present position
1029 of point in BUFFER, which defaults to the current buffer. *Note
1030 Point::. For an example, see `copy-marker', below.
1032 Internally, a marker corresponding to point is always maintained.
1033 Normally the marker returned by `point-marker' is a copy; you may
1034 modify it with reckless abandon. However, if optional argument
1035 DONT-COPY-P is non-`nil', then the real point-marker is returned;
1036 modifying the position of this marker will move point. It is
1037 illegal to change the buffer of it, or make it point nowhere.
1039 - Function: point-min-marker &optional buffer
1040 This function returns a new marker that points to the beginning of
1041 the accessible portion of BUFFER, which defaults to the current
1042 buffer. This will be the beginning of the buffer unless narrowing
1043 is in effect. *Note Narrowing::.
1045 - Function: point-max-marker &optional buffer
1046 This function returns a new marker that points to the end of the
1047 accessible portion of BUFFER, which defaults to the current
1048 buffer. This will be the end of the buffer unless narrowing is in
1049 effect. *Note Narrowing::.
1051 Here are examples of this function and `point-min-marker', shown in
1052 a buffer containing a version of the source file for the text of
1056 => #<marker at 1 in markers.texi>
1058 => #<marker at 15573 in markers.texi>
1060 (narrow-to-region 100 200)
1063 => #<marker at 100 in markers.texi>
1065 => #<marker at 200 in markers.texi>
1067 - Function: copy-marker marker-or-integer
1068 If passed a marker as its argument, `copy-marker' returns a new
1069 marker that points to the same place and the same buffer as does
1070 MARKER-OR-INTEGER. If passed an integer as its argument,
1071 `copy-marker' returns a new marker that points to position
1072 MARKER-OR-INTEGER in the current buffer.
1074 If passed an integer argument less than 1, `copy-marker' returns a
1075 new marker that points to the beginning of the current buffer. If
1076 passed an integer argument greater than the length of the buffer,
1077 `copy-marker' returns a new marker that points to the end of the
1080 An error is signaled if MARKER is neither a marker nor an integer.
1082 (setq p (point-marker))
1083 => #<marker at 2139 in markers.texi>
1085 (setq q (copy-marker p))
1086 => #<marker at 2139 in markers.texi>
1098 => #<marker at 3000 in markers.texi>
1103 (setq p (point-marker t))
1104 => #<marker at 2139 in markers.texi>
1107 => #<marker at 3000 in markers.texi>
1113 => #<marker at 1 in markers.texi>
1116 => #<marker at 7572 in markers.texi>
1119 File: lispref.info, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers
1121 Information from Markers
1122 ========================
1124 This section describes the functions for accessing the components of
1127 - Function: marker-position marker
1128 This function returns the position that MARKER points to, or `nil'
1129 if it points nowhere.
1131 - Function: marker-buffer marker
1132 This function returns the buffer that MARKER points into, or `nil'
1133 if it points nowhere.
1135 (setq m (make-marker))
1136 => #<marker in no buffer>
1142 (set-marker m 3770 (current-buffer))
1143 => #<marker at 3770 in markers.texi>
1145 => #<buffer markers.texi>
1149 Two distinct markers are considered `equal' (even though not `eq')
1150 to each other if they have the same position and buffer, or if they
1154 File: lispref.info, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers
1156 Changing Marker Positions
1157 =========================
1159 This section describes how to change the position of an existing
1160 marker. When you do this, be sure you know whether the marker is used
1161 outside of your program, and, if so, what effects will result from
1162 moving it--otherwise, confusing things may happen in other parts of
1165 - Function: set-marker marker position &optional buffer
1166 This function moves MARKER to POSITION in BUFFER. If BUFFER is
1167 not provided, it defaults to the current buffer.
1169 If POSITION is less than 1, `set-marker' moves MARKER to the
1170 beginning of the buffer. If POSITION is greater than the size of
1171 the buffer, `set-marker' moves marker to the end of the buffer.
1172 If POSITION is `nil' or a marker that points nowhere, then MARKER
1173 is set to point nowhere.
1175 The value returned is MARKER.
1177 (setq m (point-marker))
1178 => #<marker at 4714 in markers.texi>
1180 => #<marker at 55 in markers.texi>
1181 (setq b (get-buffer "foo"))
1184 => #<marker at 1 in foo>
1186 - Function: move-marker marker position &optional buffer
1187 This is another name for `set-marker'.
projects / chise / xemacs-chise.git / blob