1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
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: Excursions, Next: Narrowing, Prev: Motion, Up: Positions
58 It is often useful to move point "temporarily" within a localized
59 portion of the program, or to switch buffers temporarily. This is
60 called an "excursion", and it is done with the `save-excursion' special
61 form. This construct saves the current buffer and its values of point
62 and the mark so they can be restored after the completion of the
65 The forms for saving and restoring the configuration of windows are
66 described elsewhere (see *Note Window Configurations:: and *note Frame
69 - Special Form: save-excursion FORMS...
70 The `save-excursion' special form saves the identity of the current
71 buffer and the values of point and the mark in it, evaluates
72 FORMS, and finally restores the buffer and its saved values of
73 point and the mark. All three saved values are restored even in
74 case of an abnormal exit via `throw' or error (*note Nonlocal
77 The `save-excursion' special form is the standard way to switch
78 buffers or move point within one part of a program and avoid
79 affecting the rest of the program. It is used more than 500 times
80 in the Lisp sources of XEmacs.
82 `save-excursion' does not save the values of point and the mark for
83 other buffers, so changes in other buffers remain in effect after
84 `save-excursion' exits.
86 Likewise, `save-excursion' does not restore window-buffer
87 correspondences altered by functions such as `switch-to-buffer'.
88 One way to restore these correspondences, and the selected window,
89 is to use `save-window-excursion' inside `save-excursion' (*note
90 Window Configurations::.).
92 The value returned by `save-excursion' is the result of the last of
93 FORMS, or `nil' if no FORMS are given.
98 (let ((old-buf (current-buffer))
99 (old-pnt (point-marker))
100 (old-mark (copy-marker (mark-marker))))
105 (set-marker (mark-marker) old-mark)))
107 - Special Form: save-current-buffer FORMS...
108 This special form is similar to `save-excursion' but it only saves
109 and restores the current buffer. Beginning with XEmacs 20.3,
110 `save-current-buffer' is a primitive.
112 - Special Form: with-current-buffer BUFFER FORMS...
113 This special form evaluates FORMS with BUFFER as the current
114 buffer. It returns the value of the last form.
116 - Special Form: with-temp-file FILE FORMS...
117 This special form creates a new buffer, evaluates FORMS there, and
118 writes the buffer to FILE. It returns the value of the last form
121 - Special Form: save-selected-window FORMS...
122 This special form is similar to `save-excursion' but it saves and
123 restores the selected window and nothing else.
126 File: lispref.info, Node: Narrowing, Prev: Excursions, Up: Positions
131 "Narrowing" means limiting the text addressable by XEmacs editing
132 commands to a limited range of characters in a buffer. The text that
133 remains addressable is called the "accessible portion" of the buffer.
135 Narrowing is specified with two buffer positions which become the
136 beginning and end of the accessible portion. For most editing commands
137 and most Emacs primitives, these positions replace the values of the
138 beginning and end of the buffer. While narrowing is in effect, no text
139 outside the accessible portion is displayed, and point cannot move
140 outside the accessible portion.
142 Values such as positions or line numbers, which usually count from
143 the beginning of the buffer, do so despite narrowing, but the functions
144 which use them refuse to operate on text that is inaccessible.
146 The commands for saving buffers are unaffected by narrowing; they
147 save the entire buffer regardless of any narrowing.
149 - Command: narrow-to-region START END &optional BUFFER
150 This function sets the accessible portion of BUFFER to start at
151 START and end at END. Both arguments should be character
152 positions. BUFFER defaults to the current buffer if omitted.
154 In an interactive call, START and END are set to the bounds of the
155 current region (point and the mark, with the smallest first).
157 - Command: narrow-to-page &optional MOVE-COUNT
158 This function sets the accessible portion of the current buffer to
159 include just the current page. An optional first argument
160 MOVE-COUNT non-`nil' means to move forward or backward by
161 MOVE-COUNT pages and then narrow. The variable `page-delimiter'
162 specifies where pages start and end (*note Standard Regexps::.).
164 In an interactive call, MOVE-COUNT is set to the numeric prefix
167 - Command: widen &optional BUFFER
168 This function cancels any narrowing in BUFFER, so that the entire
169 contents are accessible. This is called "widening". It is
170 equivalent to the following expression:
172 (narrow-to-region 1 (1+ (buffer-size)))
174 BUFFER defaults to the current buffer if omitted.
176 - Special Form: save-restriction BODY...
177 This special form saves the current bounds of the accessible
178 portion, evaluates the BODY forms, and finally restores the saved
179 bounds, thus restoring the same state of narrowing (or absence
180 thereof) formerly in effect. The state of narrowing is restored
181 even in the event of an abnormal exit via `throw' or error (*note
182 Nonlocal Exits::.). Therefore, this construct is a clean way to
183 narrow a buffer temporarily.
185 The value returned by `save-restriction' is that returned by the
186 last form in BODY, or `nil' if no body forms were given.
188 *Caution:* it is easy to make a mistake when using the
189 `save-restriction' construct. Read the entire description here
192 If BODY changes the current buffer, `save-restriction' still
193 restores the restrictions on the original buffer (the buffer whose
194 restrictions it saved from), but it does not restore the identity
195 of the current buffer.
197 `save-restriction' does *not* restore point and the mark; use
198 `save-excursion' for that. If you use both `save-restriction' and
199 `save-excursion' together, `save-excursion' should come first (on
200 the outside). Otherwise, the old point value would be restored
201 with temporary narrowing still in effect. If the old point value
202 were outside the limits of the temporary narrowing, this would
203 fail to restore it accurately.
205 The `save-restriction' special form records the values of the
206 beginning and end of the accessible portion as distances from the
207 beginning and end of the buffer. In other words, it records the
208 amount of inaccessible text before and after the accessible
211 This method yields correct results if BODY does further narrowing.
212 However, `save-restriction' can become confused if the body widens
213 and then make changes outside the range of the saved narrowing.
214 When this is what you want to do, `save-restriction' is not the
215 right tool for the job. Here is what you must use instead:
217 (let ((beg (point-min-marker))
218 (end (point-max-marker)))
222 (set-buffer (marker-buffer beg))
223 (narrow-to-region beg end))))
225 Here is a simple example of correct use of `save-restriction':
227 ---------- Buffer: foo ----------
228 This is the contents of foo
229 This is the contents of foo
230 This is the contents of foo-!-
231 ---------- Buffer: foo ----------
237 (narrow-to-region 1 (point))
238 (goto-char (point-min))
239 (replace-string "foo" "bar")))
241 ---------- Buffer: foo ----------
242 This is the contents of bar
243 This is the contents of bar
244 This is the contents of foo-!-
245 ---------- Buffer: foo ----------
248 File: lispref.info, Node: Markers, Next: Text, Prev: Positions, Up: Top
253 A "marker" is a Lisp object used to specify a position in a buffer
254 relative to the surrounding text. A marker changes its offset from the
255 beginning of the buffer automatically whenever text is inserted or
256 deleted, so that it stays with the two characters on either side of it.
260 * Overview of Markers:: The components of a marker, and how it relocates.
261 * Predicates on Markers:: Testing whether an object is a marker.
262 * Creating Markers:: Making empty markers or markers at certain places.
263 * Information from Markers:: Finding the marker's buffer or character position.
264 * Changing Markers:: Moving the marker to a new buffer or position.
265 * The Mark:: How "the mark" is implemented with a marker.
266 * The Region:: How to access "the region".
269 File: lispref.info, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers
274 A marker specifies a buffer and a position in that buffer. The
275 marker can be used to represent a position in the functions that
276 require one, just as an integer could be used. *Note Positions::, for
277 a complete description of positions.
279 A marker has two attributes: the marker position, and the marker
280 buffer. The marker position is an integer that is equivalent (at a
281 given time) to the marker as a position in that buffer. But the
282 marker's position value can change often during the life of the marker.
283 Insertion and deletion of text in the buffer relocate the marker. The
284 idea is that a marker positioned between two characters remains between
285 those two characters despite insertion and deletion elsewhere in the
286 buffer. Relocation changes the integer equivalent of the marker.
288 Deleting text around a marker's position leaves the marker between
289 the characters immediately before and after the deleted text. Inserting
290 text at the position of a marker normally leaves the marker in front of
291 the new text--unless it is inserted with `insert-before-markers' (*note
294 Insertion and deletion in a buffer must check all the markers and
295 relocate them if necessary. This slows processing in a buffer with a
296 large number of markers. For this reason, it is a good idea to make a
297 marker point nowhere if you are sure you don't need it any more.
298 Unreferenced markers are garbage collected eventually, but until then
299 will continue to use time if they do point somewhere.
301 Because it is common to perform arithmetic operations on a marker
302 position, most of the arithmetic operations (including `+' and `-')
303 accept markers as arguments. In such cases, the marker stands for its
306 Note that you can use extents to achieve the same functionality, and
307 more, as markers. (Markers were defined before extents, which is why
308 they both continue to exist.) A zero-length extent with the
309 `detachable' property removed is almost identical to a marker. (*Note
310 Extent Endpoints::, for more information on zero-length extents.)
314 * In order to get marker-like behavior in a zero-length extent, the
315 `detachable' property must be removed (otherwise, the extent will
316 disappear when text near it is deleted) and exactly one endpoint
317 must be closed (if both endpoints are closed, the extent will
318 expand to contain text inserted where it is located).
320 * If a zero-length extent has the `end-open' property but not the
321 `start-open' property (this is the default), text inserted at the
322 extent's location causes the extent to move forward, just like a
325 * If a zero-length extent has the `start-open' property but not the
326 `end-open' property, text inserted at the extent's location causes
327 the extent to remain before the text, like what happens to markers
328 when `insert-before-markers' is used.
330 * Markers end up after or before inserted text depending on whether
331 `insert' or `insert-before-markers' was called. These functions
332 do not affect zero-length extents differently; instead, the
333 presence or absence of the `start-open' and `end-open' extent
334 properties determines this, as just described.
336 * Markers are automatically removed from a buffer when they are no
337 longer in use. Extents remain around until explicitly removed
340 * Many functions are provided for listing the extents in a buffer or
341 in a region of a buffer. No such functions exist for markers.
343 Here are examples of creating markers, setting markers, and moving
346 ;; Make a new marker that initially does not point anywhere:
347 (setq m1 (make-marker))
348 => #<marker in no buffer>
350 ;; Set `m1' to point between the 99th and 100th characters
351 ;; in the current buffer:
353 => #<marker at 100 in markers.texi>
355 ;; Now insert one character at the beginning of the buffer:
356 (goto-char (point-min))
361 ;; `m1' is updated appropriately.
363 => #<marker at 101 in markers.texi>
365 ;; Two markers that point to the same position
366 ;; are not `eq', but they are `equal'.
367 (setq m2 (copy-marker m1))
368 => #<marker at 101 in markers.texi>
374 ;; When you are finished using a marker, make it point nowhere.
376 => #<marker in no buffer>
379 File: lispref.info, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers
381 Predicates on Markers
382 =====================
384 You can test an object to see whether it is a marker, or whether it
385 is either an integer or a marker or either an integer, a character, or a
386 marker. The latter tests are useful in connection with the arithmetic
387 functions that work with any of markers, integers, or characters.
389 - Function: markerp OBJECT
390 This function returns `t' if OBJECT is a marker, `nil' otherwise.
391 Note that integers are not markers, even though many functions
392 will accept either a marker or an integer.
394 - Function: integer-or-marker-p OBJECT
395 This function returns `t' if OBJECT is an integer or a marker,
398 - Function: integer-char-or-marker-p OBJECT
399 This function returns `t' if OBJECT is an integer, a character, or
400 a marker, `nil' otherwise.
402 - Function: number-or-marker-p OBJECT
403 This function returns `t' if OBJECT is a number (either kind) or a
404 marker, `nil' otherwise.
406 - Function: number-char-or-marker-p OBJECT
407 This function returns `t' if OBJECT is a number (either kind), a
408 character, or a marker, `nil' otherwise.
411 File: lispref.info, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers
413 Functions That Create Markers
414 =============================
416 When you create a new marker, you can make it point nowhere, or point
417 to the present position of point, or to the beginning or end of the
418 accessible portion of the buffer, or to the same place as another given
421 - Function: make-marker
422 This functions returns a newly created marker that does not point
426 => #<marker in no buffer>
428 - Function: point-marker &optional DONT-COPY-P BUFFER
429 This function returns a marker that points to the present position
430 of point in BUFFER, which defaults to the current buffer. *Note
431 Point::. For an example, see `copy-marker', below.
433 Internally, a marker corresponding to point is always maintained.
434 Normally the marker returned by `point-marker' is a copy; you may
435 modify it with reckless abandon. However, if optional argument
436 DONT-COPY-P is non-`nil', then the real point-marker is returned;
437 modifying the position of this marker will move point. It is
438 illegal to change the buffer of it, or make it point nowhere.
440 - Function: point-min-marker &optional BUFFER
441 This function returns a new marker that points to the beginning of
442 the accessible portion of BUFFER, which defaults to the current
443 buffer. This will be the beginning of the buffer unless narrowing
444 is in effect. *Note Narrowing::.
446 - Function: point-max-marker &optional BUFFER
447 This function returns a new marker that points to the end of the
448 accessible portion of BUFFER, which defaults to the current
449 buffer. This will be the end of the buffer unless narrowing is in
450 effect. *Note Narrowing::.
452 Here are examples of this function and `point-min-marker', shown in
453 a buffer containing a version of the source file for the text of
457 => #<marker at 1 in markers.texi>
459 => #<marker at 15573 in markers.texi>
461 (narrow-to-region 100 200)
464 => #<marker at 100 in markers.texi>
466 => #<marker at 200 in markers.texi>
468 - Function: copy-marker MARKER-OR-INTEGER
469 If passed a marker as its argument, `copy-marker' returns a new
470 marker that points to the same place and the same buffer as does
471 MARKER-OR-INTEGER. If passed an integer as its argument,
472 `copy-marker' returns a new marker that points to position
473 MARKER-OR-INTEGER in the current buffer.
475 If passed an integer argument less than 1, `copy-marker' returns a
476 new marker that points to the beginning of the current buffer. If
477 passed an integer argument greater than the length of the buffer,
478 `copy-marker' returns a new marker that points to the end of the
481 An error is signaled if MARKER is neither a marker nor an integer.
483 (setq p (point-marker))
484 => #<marker at 2139 in markers.texi>
486 (setq q (copy-marker p))
487 => #<marker at 2139 in markers.texi>
499 => #<marker at 3000 in markers.texi>
504 (setq p (point-marker t))
505 => #<marker at 2139 in markers.texi>
508 => #<marker at 3000 in markers.texi>
514 => #<marker at 1 in markers.texi>
517 => #<marker at 7572 in markers.texi>
520 File: lispref.info, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers
522 Information from Markers
523 ========================
525 This section describes the functions for accessing the components of
528 - Function: marker-position MARKER
529 This function returns the position that MARKER points to, or `nil'
530 if it points nowhere.
532 - Function: marker-buffer MARKER
533 This function returns the buffer that MARKER points into, or `nil'
534 if it points nowhere.
536 (setq m (make-marker))
537 => #<marker in no buffer>
543 (set-marker m 3770 (current-buffer))
544 => #<marker at 3770 in markers.texi>
546 => #<buffer markers.texi>
550 Two distinct markers are considered `equal' (even though not `eq')
551 to each other if they have the same position and buffer, or if they
555 File: lispref.info, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers
557 Changing Marker Positions
558 =========================
560 This section describes how to change the position of an existing
561 marker. When you do this, be sure you know whether the marker is used
562 outside of your program, and, if so, what effects will result from
563 moving it--otherwise, confusing things may happen in other parts of
566 - Function: set-marker MARKER POSITION &optional BUFFER
567 This function moves MARKER to POSITION in BUFFER. If BUFFER is
568 not provided, it defaults to the current buffer.
570 If POSITION is less than 1, `set-marker' moves MARKER to the
571 beginning of the buffer. If POSITION is greater than the size of
572 the buffer, `set-marker' moves marker to the end of the buffer.
573 If POSITION is `nil' or a marker that points nowhere, then MARKER
574 is set to point nowhere.
576 The value returned is MARKER.
578 (setq m (point-marker))
579 => #<marker at 4714 in markers.texi>
581 => #<marker at 55 in markers.texi>
582 (setq b (get-buffer "foo"))
585 => #<marker at 1 in foo>
587 - Function: move-marker MARKER POSITION &optional BUFFER
588 This is another name for `set-marker'.
591 File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
596 One special marker in each buffer is designated "the mark". It
597 records a position for the user for the sake of commands such as `C-w'
598 and `C-x <TAB>'. Lisp programs should set the mark only to values that
599 have a potential use to the user, and never for their own internal
600 purposes. For example, the `replace-regexp' command sets the mark to
601 the value of point before doing any replacements, because this enables
602 the user to move back there conveniently after the replace is finished.
604 Once the mark "exists" in a buffer, it normally never ceases to
605 exist. However, it may become "inactive", and usually does so after
606 each command (other than simple motion commands and some commands that
607 explicitly activate the mark). When the mark is active, the region
608 between point and the mark is called the "active region" and is
609 highlighted specially.
611 Many commands are designed so that when called interactively they
612 operate on the text between point and the mark. Such commands work
613 only when an active region exists, i.e. when the mark is active. (The
614 reason for this is to prevent you from accidentally deleting or
615 changing large chunks of your text.) If you are writing such a command,
616 don't examine the mark directly; instead, use `interactive' with the
617 `r' specification. This provides the values of point and the mark as
618 arguments to the command in an interactive call, but permits other Lisp
619 programs to specify arguments explicitly, and automatically signals an
620 error if the command is called interactively when no active region
621 exists. *Note Interactive Codes::.
623 Each buffer has its own value of the mark that is independent of the
624 value of the mark in other buffers. (When a buffer is created, the mark
625 exists but does not point anywhere. We consider this state as "the
626 absence of a mark in that buffer.") However, only one active region can
627 exist at a time. Activating the mark in one buffer automatically
628 deactivates an active mark in any other buffer. Note that the user can
629 explicitly activate a mark at any time by using the command
630 `activate-region' (normally bound to `M-C-z') or by using the command
631 `exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
632 side effect of activating the mark.
634 Some people do not like active regions, so they disable this behavior
635 by setting the variable `zmacs-regions' to `nil'. This makes the mark
636 always active (except when a buffer is just created and the mark points
637 nowhere), and turns off the highlighting of the region between point
638 and the mark. Commands that explicitly retrieve the value of the mark
639 should make sure that they behave correctly and consistently
640 irrespective of the setting of `zmacs-regions'; some primitives are
641 provided to ensure this behavior.
643 In addition to the mark, each buffer has a "mark ring" which is a
644 list of markers containing previous values of the mark. When editing
645 commands change the mark, they should normally save the old value of the
646 mark on the mark ring. The variable `mark-ring-max' specifies the
647 maximum number of entries in the mark ring; once the list becomes this
648 long, adding a new element deletes the last element.
650 - Function: mark &optional FORCE BUFFER
651 This function returns BUFFER's mark position as an integer.
652 BUFFER defaults to the current buffer if omitted.
654 If the mark is inactive, `mark' normally returns `nil'. However,
655 if FORCE is non-`nil', then `mark' returns the mark position
656 anyway--or `nil', if the mark is not yet set for the buffer.
658 (Remember that if ZMACS-REGIONS is `nil', the mark is always
659 active as long as it exists, and the FORCE argument will have no
662 If you are using this in an editing command, you are most likely
663 making a mistake; see the documentation of `set-mark' below.
665 - Function: mark-marker INACTIVE-P BUFFER
666 This function returns BUFFER's mark. BUFFER defaults to the
667 current buffer if omitted. This is the very marker that records
668 the mark location inside XEmacs, not a copy. Therefore, changing
669 this marker's position will directly affect the position of the
670 mark. Don't do it unless that is the effect you want.
672 If the mark is inactive, `mark-marker' normally returns `nil'.
673 However, if FORCE is non-`nil', then `mark-marker' returns the
675 (setq m (mark-marker))
676 => #<marker at 3420 in markers.texi>
678 => #<marker at 100 in markers.texi>
680 => #<marker at 100 in markers.texi>
682 Like any marker, this marker can be set to point at any buffer you
683 like. We don't recommend that you make it point at any buffer
684 other than the one of which it is the mark. If you do, it will
685 yield perfectly consistent, but rather odd, results.
687 - Function: set-mark POSITION &optional BUFFER
688 This function sets `buffer''s mark to POSITION, and activates the
689 mark. BUFFER defaults to the current buffer if omitted. The old
690 value of the mark is *not* pushed onto the mark ring.
692 *Please note:* Use this function only if you want the user to see
693 that the mark has moved, and you want the previous mark position to
694 be lost. Normally, when a new mark is set, the old one should go
695 on the `mark-ring'. For this reason, most applications should use
696 `push-mark' and `pop-mark', not `set-mark'.
698 Novice XEmacs Lisp programmers often try to use the mark for the
699 wrong purposes. The mark saves a location for the user's
700 convenience. An editing command should not alter the mark unless
701 altering the mark is part of the user-level functionality of the
702 command. (And, in that case, this effect should be documented.)
703 To remember a location for internal use in the Lisp program, store
704 it in a Lisp variable. For example:
708 (delete-region beg (point))).
710 - Command: exchange-point-and-mark &optional DONT-ACTIVATE-REGION
711 This function exchanges the positions of point and the mark. It
712 is intended for interactive use. The mark is also activated
713 unless DONT-ACTIVATE-REGION is non-`nil'.
715 - Function: push-mark &optional POSITION NOMSG ACTIVATE BUFFER
716 This function sets BUFFER's mark to POSITION, and pushes a copy of
717 the previous mark onto `mark-ring'. BUFFER defaults to the
718 current buffer if omitted. If POSITION is `nil', then the value
719 of point is used. `push-mark' returns `nil'.
721 If the last global mark pushed was not in BUFFER, also push
722 POSITION on the global mark ring (see below).
724 The function `push-mark' normally *does not* activate the mark.
725 To do that, specify `t' for the argument ACTIVATE.
727 A `Mark set' message is displayed unless NOMSG is non-`nil'.
730 This function pops off the top element of `mark-ring' and makes
731 that mark become the buffer's actual mark. This does not move
732 point in the buffer, and it does nothing if `mark-ring' is empty.
733 It deactivates the mark.
735 The return value is not meaningful.
737 - Variable: mark-ring
738 The value of this buffer-local variable is the list of saved former
739 marks of the current buffer, most recent first.
742 => (#<marker at 11050 in markers.texi>
743 #<marker at 10832 in markers.texi>
746 - User Option: mark-ring-max
747 The value of this variable is the maximum size of `mark-ring'. If
748 more marks than this are pushed onto the `mark-ring', `push-mark'
749 discards an old mark when it adds a new one.
751 In additional to a per-buffer mark ring, there is a "global mark
752 ring". Marks are pushed onto the global mark ring the first time you
753 set a mark after switching buffers.
755 - Variable: global-mark-ring
756 The value of this variable is the list of saved former global
757 marks, most recent first.
759 - User Option: mark-ring-max
760 The value of this variable is the maximum size of
761 `global-mark-ring'. If more marks than this are pushed onto the
762 `global-mark-ring', `push-mark' discards an old mark when it adds
765 - Command: pop-global-mark
766 This function pops a mark off the global mark ring and jumps to
770 File: lispref.info, Node: The Region, Prev: The Mark, Up: Markers
775 The text between point and the mark is known as "the region".
776 Various functions operate on text delimited by point and the mark, but
777 only those functions specifically related to the region itself are
780 When `zmacs-regions' is non-`nil' (this is the default), the concept
781 of an "active region" exists. The region is active when the
782 corresponding mark is active. Note that only one active region at a
783 time can exist - i.e. only one buffer's region is active at a time.
784 *Note The Mark::, for more information about active regions.
786 - User Option: zmacs-regions
787 If non-`nil' (the default), active regions are used. *Note The
788 Mark::, for a detailed explanation of what this means.
790 A number of functions are provided for explicitly determining the
791 bounds of the region and whether it is active. Few programs need to use
792 these functions, however. A command designed to operate on a region
793 should normally use `interactive' with the `r' specification to find
794 the beginning and end of the region. This lets other Lisp programs
795 specify the bounds explicitly as arguments and automatically respects
796 the user's setting for ZMACS-REGIONS. (*Note Interactive Codes::.)
798 - Function: region-beginning &optional BUFFER
799 This function returns the position of the beginning of BUFFER's
800 region (as an integer). This is the position of either point or
801 the mark, whichever is smaller. BUFFER defaults to the current
804 If the mark does not point anywhere, an error is signaled. Note
805 that this function ignores whether the region is active.
807 - Function: region-end &optional BUFFER
808 This function returns the position of the end of BUFFER's region
809 (as an integer). This is the position of either point or the mark,
810 whichever is larger. BUFFER defaults to the current buffer if
813 If the mark does not point anywhere, an error is signaled. Note
814 that this function ignores whether the region is active.
816 - Function: region-exists-p
817 This function is non-`nil' if the region exists. If active regions
818 are in use (i.e. `zmacs-regions' is true), this means that the
819 region is active. Otherwise, this means that the user has pushed
820 a mark in this buffer at some point in the past. If this function
821 returns `nil', a function that uses the `r' interactive
822 specification will cause an error when called interactively.
824 - Function: region-active-p
825 If `zmacs-regions' is true, this is equivalent to
826 `region-exists-p'. Otherwise, this function always returns false.
827 This function is used by commands such as
828 `fill-paragraph-or-region' and `capitalize-region-or-word', which
829 operate either on the active region or on something else (e.g. the
830 word or paragraph at point).
832 - Variable: zmacs-region-stays
833 If a command sets this variable to true, the currently active
834 region will remain activated when the command finishes. (Normally
835 the region is deactivated when each command terminates.) If
836 ZMACS-REGIONS is false, however, this has no effect. Under normal
837 circumstances, you do not need to set this; use the interactive
838 specification `_' instead, if you want the region to remain active.
840 - Function: zmacs-activate-region
841 This function activates the region in the current buffer (this is
842 equivalent to activating the current buffer's mark). This will
843 normally also highlight the text in the active region and set
844 ZMACS-REGION-STAYS to `t'. (If ZMACS-REGIONS is false, however,
845 this function has no effect.)
847 - Function: zmacs-deactivate-region
848 This function deactivates the region in the current buffer (this is
849 equivalent to deactivating the current buffer's mark). This will
850 normally also unhighlight the text in the active region and set
851 ZMACS-REGION-STAYS to `nil'. (If ZMACS-REGIONS is false, however,
852 this function has no effect.)
854 - Function: zmacs-update-region
855 This function updates the active region, if it's currently active.
856 (If there is no active region, this function does nothing.) This
857 has the effect of updating the highlighting on the text in the
858 region; but you should never need to call this except under rather
859 strange circumstances. The command loop automatically calls it
860 when appropriate. Calling this function will call the hook
861 `zmacs-update-region-hook', if the region is active.
863 - Variable: zmacs-activate-region-hook
864 This normal hook is called when a region becomes active. (Usually
865 this happens as a result of a command that activates the region,
866 such as `set-mark-command', `activate-region', or
867 `exchange-point-and-mark'.) Note that calling
868 `zmacs-activate-region' will call this hook, even if the region is
869 already active. If ZMACS-REGIONS is false, however, this hook
870 will never get called under any circumstances.
872 - Variable: zmacs-deactivate-region-hook
873 This normal hook is called when an active region becomes inactive.
874 (Calling `zmacs-deactivate-region' when the region is inactive will
875 *not* cause this hook to be called.) If ZMACS-REGIONS is false,
876 this hook will never get called.
878 - Variable: zmacs-update-region-hook
879 This normal hook is called when an active region is "updated" by
880 `zmacs-update-region'. This normally gets called at the end of
881 each command that sets ZMACS-REGION-STAYS to `t', indicating that
882 the region should remain activated. The motion commands do this.
885 File: lispref.info, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top
890 This chapter describes the functions that deal with the text in a
891 buffer. Most examine, insert, or delete text in the current buffer,
892 often in the vicinity of point. Many are interactive. All the
893 functions that change the text provide for undoing the changes (*note
896 Many text-related functions operate on a region of text defined by
897 two buffer positions passed in arguments named START and END. These
898 arguments should be either markers (*note Markers::.) or numeric
899 character positions (*note Positions::.). The order of these arguments
900 does not matter; it is all right for START to be the end of the region
901 and END the beginning. For example, `(delete-region 1 10)' and
902 `(delete-region 10 1)' are equivalent. An `args-out-of-range' error is
903 signaled if either START or END is outside the accessible portion of
904 the buffer. In an interactive call, point and the mark are used for
907 Throughout this chapter, "text" refers to the characters in the
908 buffer, together with their properties (when relevant).
912 * Near Point:: Examining text in the vicinity of point.
913 * Buffer Contents:: Examining text in a general fashion.
914 * Comparing Text:: Comparing substrings of buffers.
915 * Insertion:: Adding new text to a buffer.
916 * Commands for Insertion:: User-level commands to insert text.
917 * Deletion:: Removing text from a buffer.
918 * User-Level Deletion:: User-level commands to delete text.
919 * The Kill Ring:: Where removed text sometimes is saved for later use.
920 * Undo:: Undoing changes to the text of a buffer.
921 * Maintaining Undo:: How to enable and disable undo information.
922 How to control how much information is kept.
923 * Filling:: Functions for explicit filling.
924 * Margins:: How to specify margins for filling commands.
925 * Auto Filling:: How auto-fill mode is implemented to break lines.
926 * Sorting:: Functions for sorting parts of the buffer.
927 * Columns:: Computing horizontal positions, and using them.
928 * Indentation:: Functions to insert or adjust indentation.
929 * Case Changes:: Case conversion of parts of the buffer.
930 * Text Properties:: Assigning Lisp property lists to text characters.
931 * Substitution:: Replacing a given character wherever it appears.
932 * Registers:: How registers are implemented. Accessing the text or
933 position stored in a register.
934 * Transposition:: Swapping two portions of a buffer.
935 * Change Hooks:: Supplying functions to be run when text is changed.
936 * Transformations:: MD5 and base64 support.
939 File: lispref.info, Node: Near Point, Next: Buffer Contents, Up: Text
941 Examining Text Near Point
942 =========================
944 Many functions are provided to look at the characters around point.
945 Several simple functions are described here. See also `looking-at' in
946 *Note Regexp Search::.
948 Many of these functions take an optional BUFFER argument. In all
949 such cases, the current buffer will be used if this argument is
950 omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions
951 usually did not have these optional BUFFER arguments and always
952 operated on the current buffer.)
954 - Function: char-after POSITION &optional BUFFER
955 This function returns the character in the buffer at (i.e.,
956 immediately after) position POSITION. If POSITION is out of range
957 for this purpose, either before the beginning of the buffer, or at
958 or beyond the end, then the value is `nil'. If optional argument
959 BUFFER is `nil', the current buffer is assumed.
961 In the following example, assume that the first character in the
964 (char-to-string (char-after 1))
967 - Function: following-char &optional BUFFER
968 This function returns the character following point in the buffer.
969 This is similar to `(char-after (point))'. However, if point is at
970 the end of the buffer, then the result of `following-char' is 0.
971 If optional argument BUFFER is `nil', the current buffer is
974 Remember that point is always between characters, and the terminal
975 cursor normally appears over the character following point.
976 Therefore, the character returned by `following-char' is the
977 character the cursor is over.
979 In this example, point is between the `a' and the `c'.
981 ---------- Buffer: foo ----------
982 Gentlemen may cry ``Pea-!-ce! Peace!,''
983 but there is no peace.
984 ---------- Buffer: foo ----------
986 (char-to-string (preceding-char))
988 (char-to-string (following-char))
991 - Function: preceding-char &optional BUFFER
992 This function returns the character preceding point in the buffer.
993 See above, under `following-char', for an example. If point is at
994 the beginning of the buffer, `preceding-char' returns 0. If
995 optional argument BUFFER is `nil', the current buffer is assumed.
997 - Function: bobp &optional BUFFER
998 This function returns `t' if point is at the beginning of the
999 buffer. If narrowing is in effect, this means the beginning of the
1000 accessible portion of the text. If optional argument BUFFER is
1001 `nil', the current buffer is assumed. See also `point-min' in
1004 - Function: eobp &optional BUFFER
1005 This function returns `t' if point is at the end of the buffer.
1006 If narrowing is in effect, this means the end of accessible
1007 portion of the text. If optional argument BUFFER is `nil', the
1008 current buffer is assumed. See also `point-max' in *Note Point::.
1010 - Function: bolp &optional BUFFER
1011 This function returns `t' if point is at the beginning of a line.
1012 If optional argument BUFFER is `nil', the current buffer is
1013 assumed. *Note Text Lines::. The beginning of the buffer (or its
1014 accessible portion) always counts as the beginning of a line.
1016 - Function: eolp &optional BUFFER
1017 This function returns `t' if point is at the end of a line. The
1018 end of the buffer is always considered the end of a line. If
1019 optional argument BUFFER is `nil', the current buffer is assumed.
1020 The end of the buffer (or of its accessible portion) is always
1021 considered the end of a line.
1024 File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text
1026 Examining Buffer Contents
1027 =========================
1029 This section describes two functions that allow a Lisp program to
1030 convert any portion of the text in the buffer into a string.
1032 - Function: buffer-substring START END &optional BUFFER
1033 - Function: buffer-string START END &optional BUFFER
1034 These functions are equivalent and return a string containing a
1035 copy of the text of the region defined by positions START and END
1036 in the buffer. If the arguments are not positions in the
1037 accessible portion of the buffer, `buffer-substring' signals an
1038 `args-out-of-range' error. If optional argument BUFFER is `nil',
1039 the current buffer is assumed.
1041 If the region delineated by START and END contains duplicable
1042 extents, they will be remembered in the string. *Note Duplicable
1045 It is not necessary for START to be less than END; the arguments
1046 can be given in either order. But most often the smaller argument
1049 ---------- Buffer: foo ----------
1050 This is the contents of buffer foo
1052 ---------- Buffer: foo ----------
1054 (buffer-substring 1 10)
1056 (buffer-substring (point-max) 10)
1057 => "he contents of buffer foo
1061 File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text
1066 This function lets you compare portions of the text in a buffer,
1067 without copying them into strings first.
1069 - Function: compare-buffer-substrings BUFFER1 START1 END1 BUFFER2
1071 This function lets you compare two substrings of the same buffer
1072 or two different buffers. The first three arguments specify one
1073 substring, giving a buffer and two positions within the buffer.
1074 The last three arguments specify the other substring in the same
1075 way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for
1078 The value is negative if the first substring is less, positive if
1079 the first is greater, and zero if they are equal. The absolute
1080 value of the result is one plus the index of the first differing
1081 characters within the substrings.
1083 This function ignores case when comparing characters if
1084 `case-fold-search' is non-`nil'. It always ignores text
1087 Suppose the current buffer contains the text `foobarbar
1088 haha!rara!'; then in this example the two substrings are `rbar '
1089 and `rara!'. The value is 2 because the first substring is greater
1090 at the second character.
1092 (compare-buffer-substring nil 6 11 nil 16 21)
1096 File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text
1101 "Insertion" means adding new text to a buffer. The inserted text
1102 goes at point--between the character before point and the character
1105 Insertion relocates markers that point at positions after the
1106 insertion point, so that they stay with the surrounding text (*note
1107 Markers::.). When a marker points at the place of insertion, insertion
1108 normally doesn't relocate the marker, so that it points to the
1109 beginning of the inserted text; however, certain special functions such
1110 as `insert-before-markers' relocate such markers to point after the
1113 Some insertion functions leave point before the inserted text, while
1114 other functions leave it after. We call the former insertion "after
1115 point" and the latter insertion "before point".
1117 If a string with non-`nil' extent data is inserted, the remembered
1118 extents will also be inserted. *Note Duplicable Extents::.
1120 Insertion functions signal an error if the current buffer is
1123 These functions copy text characters from strings and buffers along
1124 with their properties. The inserted characters have exactly the same
1125 properties as the characters they were copied from. By contrast,
1126 characters specified as separate arguments, not part of a string or
1127 buffer, inherit their text properties from the neighboring text.
1129 - Function: insert &rest ARGS
1130 This function inserts the strings and/or characters ARGS into the
1131 current buffer, at point, moving point forward. In other words, it
1132 inserts the text before point. An error is signaled unless all
1133 ARGS are either strings or characters. The value is `nil'.
1135 - Function: insert-before-markers &rest ARGS
1136 This function inserts the strings and/or characters ARGS into the
1137 current buffer, at point, moving point forward. An error is
1138 signaled unless all ARGS are either strings or characters. The
1141 This function is unlike the other insertion functions in that it
1142 relocates markers initially pointing at the insertion point, to
1143 point after the inserted text.
1145 - Function: insert-string STRING &optional BUFFER
1146 This function inserts STRING into BUFFER before point. BUFFER
1147 defaults to the current buffer if omitted. This function is
1148 chiefly useful if you want to insert a string in a buffer other
1149 than the current one (otherwise you could just use `insert').
1151 - Function: insert-char CHARACTER COUNT &optional BUFFER
1152 This function inserts COUNT instances of CHARACTER into BUFFER
1153 before point. COUNT must be a number, and CHARACTER must be a
1154 character. The value is `nil'. If optional argument BUFFER is
1155 `nil', the current buffer is assumed. (In FSF Emacs, the third
1156 argument is called INHERIT and refers to text properties.)
1158 - Function: insert-buffer-substring FROM-BUFFER-OR-NAME &optional
1160 This function inserts a portion of buffer FROM-BUFFER-OR-NAME
1161 (which must already exist) into the current buffer before point.
1162 The text inserted is the region from START and END. (These
1163 arguments default to the beginning and end of the accessible
1164 portion of that buffer.) This function returns `nil'.
1166 In this example, the form is executed with buffer `bar' as the
1167 current buffer. We assume that buffer `bar' is initially empty.
1169 ---------- Buffer: foo ----------
1170 We hold these truths to be self-evident, that all
1171 ---------- Buffer: foo ----------
1173 (insert-buffer-substring "foo" 1 20)
1176 ---------- Buffer: bar ----------
1177 We hold these truth-!-
1178 ---------- Buffer: bar ----------
projects / chise / xemacs-chise.git.1 / blob