1 This is ../info/lispref.info, produced by makeinfo version 4.0b 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: Skipping Characters, Prev: List Motion, Up: Motion
58 The following two functions move point over a specified set of
59 characters. For example, they are often used to skip whitespace. For
60 related functions, see *Note Motion and Syntax::.
62 - Function: skip-chars-forward character-set &optional limit buffer
63 This function moves point in BUFFER forward, skipping over a given
64 set of characters. It examines the character following point,
65 then advances point if the character matches CHARACTER-SET. This
66 continues until it reaches a character that does not match. The
67 function returns `nil'. BUFFER defaults to the current buffer if
70 The argument CHARACTER-SET is like the inside of a `[...]' in a
71 regular expression except that `]' is never special and `\' quotes
72 `^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters,
73 stopping before the first non-letter, and `"^a-zA-Z'" skips
74 non-letters stopping before the first letter. *Note Regular
77 If LIMIT is supplied (it must be a number or a marker), it
78 specifies the maximum position in the buffer that point can be
79 skipped to. Point will stop at or before LIMIT.
81 In the following example, point is initially located directly
82 before the `T'. After the form is evaluated, point is located at
83 the end of that line (between the `t' of `hat' and the newline).
84 The function skips all letters and spaces, but not newlines.
86 ---------- Buffer: foo ----------
87 I read "-!-The cat in the hat
89 ---------- Buffer: foo ----------
91 (skip-chars-forward "a-zA-Z ")
94 ---------- Buffer: foo ----------
95 I read "The cat in the hat-!-
97 ---------- Buffer: foo ----------
99 - Function: skip-chars-backward character-set &optional limit buffer
100 This function moves point backward, skipping characters that match
101 CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
102 except for the direction of motion.
105 File: lispref.info, Node: Excursions, Next: Narrowing, Prev: Motion, Up: Positions
110 It is often useful to move point "temporarily" within a localized
111 portion of the program, or to switch buffers temporarily. This is
112 called an "excursion", and it is done with the `save-excursion' special
113 form. This construct saves the current buffer and its values of point
114 and the mark so they can be restored after the completion of the
117 The forms for saving and restoring the configuration of windows are
118 described elsewhere (see *Note Window Configurations:: and *note Frame
121 - Special Form: save-excursion forms...
122 The `save-excursion' special form saves the identity of the current
123 buffer and the values of point and the mark in it, evaluates
124 FORMS, and finally restores the buffer and its saved values of
125 point and the mark. All three saved values are restored even in
126 case of an abnormal exit via `throw' or error (*note Nonlocal
129 The `save-excursion' special form is the standard way to switch
130 buffers or move point within one part of a program and avoid
131 affecting the rest of the program. It is used more than 500 times
132 in the Lisp sources of XEmacs.
134 `save-excursion' does not save the values of point and the mark for
135 other buffers, so changes in other buffers remain in effect after
136 `save-excursion' exits.
138 Likewise, `save-excursion' does not restore window-buffer
139 correspondences altered by functions such as `switch-to-buffer'.
140 One way to restore these correspondences, and the selected window,
141 is to use `save-window-excursion' inside `save-excursion' (*note
142 Window Configurations::).
144 The value returned by `save-excursion' is the result of the last of
145 FORMS, or `nil' if no FORMS are given.
150 (let ((old-buf (current-buffer))
151 (old-pnt (point-marker))
152 (old-mark (copy-marker (mark-marker))))
157 (set-marker (mark-marker) old-mark)))
159 - Special Form: save-current-buffer forms...
160 This special form is similar to `save-excursion' but it only saves
161 and restores the current buffer. Beginning with XEmacs 20.3,
162 `save-current-buffer' is a primitive.
164 - Special Form: with-current-buffer buffer forms...
165 This special form evaluates FORMS with BUFFER as the current
166 buffer. It returns the value of the last form.
168 - Special Form: with-temp-file filename forms...
169 This special form creates a new buffer, evaluates FORMS there, and
170 writes the buffer to FILENAME. It returns the value of the last
173 - Special Form: save-selected-window forms...
174 This special form is similar to `save-excursion' but it saves and
175 restores the selected window and nothing else.
178 File: lispref.info, Node: Narrowing, Prev: Excursions, Up: Positions
183 "Narrowing" means limiting the text addressable by XEmacs editing
184 commands to a limited range of characters in a buffer. The text that
185 remains addressable is called the "accessible portion" of the buffer.
187 Narrowing is specified with two buffer positions which become the
188 beginning and end of the accessible portion. For most editing commands
189 and most Emacs primitives, these positions replace the values of the
190 beginning and end of the buffer. While narrowing is in effect, no text
191 outside the accessible portion is displayed, and point cannot move
192 outside the accessible portion.
194 Values such as positions or line numbers, which usually count from
195 the beginning of the buffer, do so despite narrowing, but the functions
196 which use them refuse to operate on text that is inaccessible.
198 The commands for saving buffers are unaffected by narrowing; they
199 save the entire buffer regardless of any narrowing.
201 - Command: narrow-to-region start end &optional buffer
202 This function sets the accessible portion of BUFFER to start at
203 START and end at END. Both arguments should be character
204 positions. BUFFER defaults to the current buffer if omitted.
206 In an interactive call, START and END are set to the bounds of the
207 current region (point and the mark, with the smallest first).
209 - Command: narrow-to-page &optional move-count
210 This function sets the accessible portion of the current buffer to
211 include just the current page. An optional first argument
212 MOVE-COUNT non-`nil' means to move forward or backward by
213 MOVE-COUNT pages and then narrow. The variable `page-delimiter'
214 specifies where pages start and end (*note Standard Regexps::).
216 In an interactive call, MOVE-COUNT is set to the numeric prefix
219 - Command: widen &optional buffer
220 This function cancels any narrowing in BUFFER, so that the entire
221 contents are accessible. This is called "widening". It is
222 equivalent to the following expression:
224 (narrow-to-region 1 (1+ (buffer-size)))
226 BUFFER defaults to the current buffer if omitted.
228 - Special Form: save-restriction body...
229 This special form saves the current bounds of the accessible
230 portion, evaluates the BODY forms, and finally restores the saved
231 bounds, thus restoring the same state of narrowing (or absence
232 thereof) formerly in effect. The state of narrowing is restored
233 even in the event of an abnormal exit via `throw' or error (*note
234 Nonlocal Exits::). Therefore, this construct is a clean way to
235 narrow a buffer temporarily.
237 The value returned by `save-restriction' is that returned by the
238 last form in BODY, or `nil' if no body forms were given.
240 *Caution:* it is easy to make a mistake when using the
241 `save-restriction' construct. Read the entire description here
244 If BODY changes the current buffer, `save-restriction' still
245 restores the restrictions on the original buffer (the buffer whose
246 restrictions it saved from), but it does not restore the identity
247 of the current buffer.
249 `save-restriction' does _not_ restore point and the mark; use
250 `save-excursion' for that. If you use both `save-restriction' and
251 `save-excursion' together, `save-excursion' should come first (on
252 the outside). Otherwise, the old point value would be restored
253 with temporary narrowing still in effect. If the old point value
254 were outside the limits of the temporary narrowing, this would
255 fail to restore it accurately.
257 The `save-restriction' special form records the values of the
258 beginning and end of the accessible portion as distances from the
259 beginning and end of the buffer. In other words, it records the
260 amount of inaccessible text before and after the accessible
263 This method yields correct results if BODY does further narrowing.
264 However, `save-restriction' can become confused if the body widens
265 and then make changes outside the range of the saved narrowing.
266 When this is what you want to do, `save-restriction' is not the
267 right tool for the job. Here is what you must use instead:
269 (let ((start (point-min-marker))
270 (end (point-max-marker)))
274 (set-buffer (marker-buffer start))
275 (narrow-to-region start end))))
277 Here is a simple example of correct use of `save-restriction':
279 ---------- Buffer: foo ----------
280 This is the contents of foo
281 This is the contents of foo
282 This is the contents of foo-!-
283 ---------- Buffer: foo ----------
289 (narrow-to-region 1 (point))
290 (goto-char (point-min))
291 (replace-string "foo" "bar")))
293 ---------- Buffer: foo ----------
294 This is the contents of bar
295 This is the contents of bar
296 This is the contents of foo-!-
297 ---------- Buffer: foo ----------
300 File: lispref.info, Node: Markers, Next: Text, Prev: Positions, Up: Top
305 A "marker" is a Lisp object used to specify a position in a buffer
306 relative to the surrounding text. A marker changes its offset from the
307 beginning of the buffer automatically whenever text is inserted or
308 deleted, so that it stays with the two characters on either side of it.
312 * Overview of Markers:: The components of a marker, and how it relocates.
313 * Predicates on Markers:: Testing whether an object is a marker.
314 * Creating Markers:: Making empty markers or markers at certain places.
315 * Information from Markers:: Finding the marker's buffer or character position.
316 * Changing Markers:: Moving the marker to a new buffer or position.
317 * The Mark:: How ``the mark'' is implemented with a marker.
318 * The Region:: How to access ``the region''.
321 File: lispref.info, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers
326 A marker specifies a buffer and a position in that buffer. The
327 marker can be used to represent a position in the functions that
328 require one, just as an integer could be used. *Note Positions::, for
329 a complete description of positions.
331 A marker has two attributes: the marker position, and the marker
332 buffer. The marker position is an integer that is equivalent (at a
333 given time) to the marker as a position in that buffer. But the
334 marker's position value can change often during the life of the marker.
335 Insertion and deletion of text in the buffer relocate the marker. The
336 idea is that a marker positioned between two characters remains between
337 those two characters despite insertion and deletion elsewhere in the
338 buffer. Relocation changes the integer equivalent of the marker.
340 Deleting text around a marker's position leaves the marker between
341 the characters immediately before and after the deleted text. Inserting
342 text at the position of a marker normally leaves the marker in front of
343 the new text--unless it is inserted with `insert-before-markers' (*note
346 Insertion and deletion in a buffer must check all the markers and
347 relocate them if necessary. This slows processing in a buffer with a
348 large number of markers. For this reason, it is a good idea to make a
349 marker point nowhere if you are sure you don't need it any more.
350 Unreferenced markers are garbage collected eventually, but until then
351 will continue to use time if they do point somewhere.
353 Because it is common to perform arithmetic operations on a marker
354 position, most of the arithmetic operations (including `+' and `-')
355 accept markers as arguments. In such cases, the marker stands for its
358 Note that you can use extents to achieve the same functionality, and
359 more, as markers. (Markers were defined before extents, which is why
360 they both continue to exist.) A zero-length extent with the
361 `detachable' property removed is almost identical to a marker. (*Note
362 Extent Endpoints::, for more information on zero-length extents.)
366 * In order to get marker-like behavior in a zero-length extent, the
367 `detachable' property must be removed (otherwise, the extent will
368 disappear when text near it is deleted) and exactly one endpoint
369 must be closed (if both endpoints are closed, the extent will
370 expand to contain text inserted where it is located).
372 * If a zero-length extent has the `end-open' property but not the
373 `start-open' property (this is the default), text inserted at the
374 extent's location causes the extent to move forward, just like a
377 * If a zero-length extent has the `start-open' property but not the
378 `end-open' property, text inserted at the extent's location causes
379 the extent to remain before the text, like what happens to markers
380 when `insert-before-markers' is used.
382 * Markers end up after or before inserted text depending on whether
383 `insert' or `insert-before-markers' was called. These functions
384 do not affect zero-length extents differently; instead, the
385 presence or absence of the `start-open' and `end-open' extent
386 properties determines this, as just described.
388 * Markers are automatically removed from a buffer when they are no
389 longer in use. Extents remain around until explicitly removed
392 * Many functions are provided for listing the extents in a buffer or
393 in a region of a buffer. No such functions exist for markers.
395 Here are examples of creating markers, setting markers, and moving
398 ;; Make a new marker that initially does not point anywhere:
399 (setq m1 (make-marker))
400 => #<marker in no buffer>
402 ;; Set `m1' to point between the 99th and 100th characters
403 ;; in the current buffer:
405 => #<marker at 100 in markers.texi>
407 ;; Now insert one character at the beginning of the buffer:
408 (goto-char (point-min))
413 ;; `m1' is updated appropriately.
415 => #<marker at 101 in markers.texi>
417 ;; Two markers that point to the same position
418 ;; are not `eq', but they are `equal'.
419 (setq m2 (copy-marker m1))
420 => #<marker at 101 in markers.texi>
426 ;; When you are finished using a marker, make it point nowhere.
428 => #<marker in no buffer>
431 File: lispref.info, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers
433 Predicates on Markers
434 =====================
436 You can test an object to see whether it is a marker, or whether it
437 is either an integer or a marker or either an integer, a character, or a
438 marker. The latter tests are useful in connection with the arithmetic
439 functions that work with any of markers, integers, or characters.
441 - Function: markerp object
442 This function returns `t' if OBJECT is a marker, `nil' otherwise.
443 Note that integers are not markers, even though many functions
444 will accept either a marker or an integer.
446 - Function: integer-or-marker-p object
447 This function returns `t' if OBJECT is an integer or a marker,
450 - Function: integer-char-or-marker-p object
451 This function returns `t' if OBJECT is an integer, a character, or
452 a marker, `nil' otherwise.
454 - Function: number-or-marker-p object
455 This function returns `t' if OBJECT is a number (either kind) or a
456 marker, `nil' otherwise.
458 - Function: number-char-or-marker-p object
459 This function returns `t' if OBJECT is a number (either kind), a
460 character, or a marker, `nil' otherwise.
463 File: lispref.info, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers
465 Functions That Create Markers
466 =============================
468 When you create a new marker, you can make it point nowhere, or point
469 to the present position of point, or to the beginning or end of the
470 accessible portion of the buffer, or to the same place as another given
473 - Function: make-marker
474 This functions returns a newly created marker that does not point
478 => #<marker in no buffer>
480 - Function: point-marker &optional dont-copy-p buffer
481 This function returns a marker that points to the present position
482 of point in BUFFER, which defaults to the current buffer. *Note
483 Point::. For an example, see `copy-marker', below.
485 Internally, a marker corresponding to point is always maintained.
486 Normally the marker returned by `point-marker' is a copy; you may
487 modify it with reckless abandon. However, if optional argument
488 DONT-COPY-P is non-`nil', then the real point-marker is returned;
489 modifying the position of this marker will move point. It is
490 illegal to change the buffer of it, or make it point nowhere.
492 - Function: point-min-marker &optional buffer
493 This function returns a new marker that points to the beginning of
494 the accessible portion of BUFFER, which defaults to the current
495 buffer. This will be the beginning of the buffer unless narrowing
496 is in effect. *Note Narrowing::.
498 - Function: point-max-marker &optional buffer
499 This function returns a new marker that points to the end of the
500 accessible portion of BUFFER, which defaults to the current
501 buffer. This will be the end of the buffer unless narrowing is in
502 effect. *Note Narrowing::.
504 Here are examples of this function and `point-min-marker', shown in
505 a buffer containing a version of the source file for the text of
509 => #<marker at 1 in markers.texi>
511 => #<marker at 15573 in markers.texi>
513 (narrow-to-region 100 200)
516 => #<marker at 100 in markers.texi>
518 => #<marker at 200 in markers.texi>
520 - Function: copy-marker marker-or-integer &optional marker-type
521 If passed a marker as its argument, `copy-marker' returns a new
522 marker that points to the same place and the same buffer as does
523 MARKER-OR-INTEGER. If passed an integer as its argument,
524 `copy-marker' returns a new marker that points to position
525 MARKER-OR-INTEGER in the current buffer.
527 If passed an integer argument less than 1, `copy-marker' returns a
528 new marker that points to the beginning of the current buffer. If
529 passed an integer argument greater than the length of the buffer,
530 `copy-marker' returns a new marker that points to the end of the
533 An error is signaled if MARKER-OR-INTEGER is neither a marker nor
536 Optional second argument MARKER-TYPE specifies the insertion type
537 of the new marker; see `marker-insertion-type'.
539 (setq p (point-marker))
540 => #<marker at 2139 in markers.texi>
542 (setq q (copy-marker p))
543 => #<marker at 2139 in markers.texi>
555 => #<marker at 3000 in markers.texi>
560 (setq p (point-marker t))
561 => #<marker at 2139 in markers.texi>
564 => #<marker at 3000 in markers.texi>
570 => #<marker at 1 in markers.texi>
573 => #<marker at 7572 in markers.texi>
576 File: lispref.info, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers
578 Information from Markers
579 ========================
581 This section describes the functions for accessing the components of
584 - Function: marker-position marker
585 This function returns the position that MARKER points to, or `nil'
586 if it points nowhere.
588 - Function: marker-buffer marker
589 This function returns the buffer that MARKER points into, or `nil'
590 if it points nowhere.
592 (setq m (make-marker))
593 => #<marker in no buffer>
599 (set-marker m 3770 (current-buffer))
600 => #<marker at 3770 in markers.texi>
602 => #<buffer markers.texi>
606 Two distinct markers are considered `equal' (even though not `eq')
607 to each other if they have the same position and buffer, or if they
611 File: lispref.info, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers
613 Changing Marker Positions
614 =========================
616 This section describes how to change the position of an existing
617 marker. When you do this, be sure you know whether the marker is used
618 outside of your program, and, if so, what effects will result from
619 moving it--otherwise, confusing things may happen in other parts of
622 - Function: set-marker marker position &optional buffer
623 This function moves MARKER to POSITION in BUFFER. If BUFFER is
624 not provided, it defaults to the current buffer.
626 POSITION can be a marker, an integer or `nil'. If POSITION is an
627 integer, `set-marker' moves MARKER to point before the POSITIONth
628 character in BUFFER. If POSITION is `nil', MARKER is made to
629 point nowhere. Then it no longer slows down editing in any
630 buffer. If POSITION is less than 1, MARKER is moved to the
631 beginning of BUFFER. If POSITION is greater than the size of
632 BUFFER, MARKER is moved to the end of BUFFER.
634 The value returned is MARKER.
636 (setq m (point-marker))
637 => #<marker at 4714 in markers.texi>
639 => #<marker at 55 in markers.texi>
640 (setq b (get-buffer "foo"))
643 => #<marker at 1 in foo>
645 - Function: move-marker marker position &optional buffer
646 This is another name for `set-marker'.
649 File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
654 One special marker in each buffer is designated "the mark". It
655 records a position for the user for the sake of commands such as `C-w'
656 and `C-x <TAB>'. Lisp programs should set the mark only to values that
657 have a potential use to the user, and never for their own internal
658 purposes. For example, the `replace-regexp' command sets the mark to
659 the value of point before doing any replacements, because this enables
660 the user to move back there conveniently after the replace is finished.
662 Once the mark "exists" in a buffer, it normally never ceases to
663 exist. However, it may become "inactive", and usually does so after
664 each command (other than simple motion commands and some commands that
665 explicitly activate the mark). When the mark is active, the region
666 between point and the mark is called the "active region" and is
667 highlighted specially.
669 Many commands are designed so that when called interactively they
670 operate on the text between point and the mark. Such commands work
671 only when an active region exists, i.e. when the mark is active. (The
672 reason for this is to prevent you from accidentally deleting or
673 changing large chunks of your text.) If you are writing such a command,
674 don't examine the mark directly; instead, use `interactive' with the
675 `r' specification. This provides the values of point and the mark as
676 arguments to the command in an interactive call, but permits other Lisp
677 programs to specify arguments explicitly, and automatically signals an
678 error if the command is called interactively when no active region
679 exists. *Note Interactive Codes::.
681 Each buffer has its own value of the mark that is independent of the
682 value of the mark in other buffers. (When a buffer is created, the mark
683 exists but does not point anywhere. We consider this state as "the
684 absence of a mark in that buffer.") However, only one active region can
685 exist at a time. Activating the mark in one buffer automatically
686 deactivates an active mark in any other buffer. Note that the user can
687 explicitly activate a mark at any time by using the command
688 `activate-region' (normally bound to `M-C-z') or by using the command
689 `exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
690 side effect of activating the mark.
692 Some people do not like active regions, so they disable this behavior
693 by setting the variable `zmacs-regions' to `nil'. This makes the mark
694 always active (except when a buffer is just created and the mark points
695 nowhere), and turns off the highlighting of the region between point
696 and the mark. Commands that explicitly retrieve the value of the mark
697 should make sure that they behave correctly and consistently
698 irrespective of the setting of `zmacs-regions'; some primitives are
699 provided to ensure this behavior.
701 In addition to the mark, each buffer has a "mark ring" which is a
702 list of markers containing previous values of the mark. When editing
703 commands change the mark, they should normally save the old value of the
704 mark on the mark ring. The variable `mark-ring-max' specifies the
705 maximum number of entries in the mark ring; once the list becomes this
706 long, adding a new element deletes the last element.
708 - Function: mark &optional force buffer
709 This function returns BUFFER's mark position as an integer.
710 BUFFER defaults to the current buffer if omitted.
712 If the mark is inactive, `mark' normally returns `nil'. However,
713 if FORCE is non-`nil', then `mark' returns the mark position
714 anyway--or `nil', if the mark is not yet set for the buffer.
716 (Remember that if ZMACS-REGIONS is `nil', the mark is always
717 active as long as it exists, and the FORCE argument will have no
720 If you are using this in an editing command, you are most likely
721 making a mistake; see the documentation of `set-mark' below.
723 - Function: mark-marker &optional force buffer
724 This function returns BUFFER's mark. BUFFER defaults to the
725 current buffer if omitted. This is the very marker that records
726 the mark location inside XEmacs, not a copy. Therefore, changing
727 this marker's position will directly affect the position of the
728 mark. Don't do it unless that is the effect you want.
730 If the mark is inactive, `mark-marker' normally returns `nil'.
731 However, if FORCE is non-`nil', then `mark-marker' returns the
733 (setq m (mark-marker))
734 => #<marker at 3420 in markers.texi>
736 => #<marker at 100 in markers.texi>
738 => #<marker at 100 in markers.texi>
740 Like any marker, this marker can be set to point at any buffer you
741 like. We don't recommend that you make it point at any buffer
742 other than the one of which it is the mark. If you do, it will
743 yield perfectly consistent, but rather odd, results.
745 - Function: set-mark position &optional buffer
746 This function sets `buffer''s mark to POSITION, and activates the
747 mark. BUFFER defaults to the current buffer if omitted. The old
748 value of the mark is _not_ pushed onto the mark ring.
750 *Please note:* Use this function only if you want the user to see
751 that the mark has moved, and you want the previous mark position to
752 be lost. Normally, when a new mark is set, the old one should go
753 on the `mark-ring'. For this reason, most applications should use
754 `push-mark' and `pop-mark', not `set-mark'.
756 Novice XEmacs Lisp programmers often try to use the mark for the
757 wrong purposes. The mark saves a location for the user's
758 convenience. An editing command should not alter the mark unless
759 altering the mark is part of the user-level functionality of the
760 command. (And, in that case, this effect should be documented.)
761 To remember a location for internal use in the Lisp program, store
762 it in a Lisp variable. For example:
764 (let ((start (point)))
766 (delete-region start (point))).
768 - Command: exchange-point-and-mark &optional dont-activate-region
769 This function exchanges the positions of point and the mark. It
770 is intended for interactive use. The mark is also activated
771 unless DONT-ACTIVATE-REGION is non-`nil'.
773 - Function: push-mark &optional position nomsg activate buffer
774 This function sets BUFFER's mark to POSITION, and pushes a copy of
775 the previous mark onto `mark-ring'. BUFFER defaults to the
776 current buffer if omitted. If POSITION is `nil', then the value
777 of point is used. `push-mark' returns `nil'.
779 If the last global mark pushed was not in BUFFER, also push
780 POSITION on the global mark ring (see below).
782 The function `push-mark' normally _does not_ activate the mark.
783 To do that, specify `t' for the argument ACTIVATE.
785 A `Mark set' message is displayed unless NOMSG is non-`nil'.
788 This function pops off the top element of `mark-ring' and makes
789 that mark become the buffer's actual mark. This does not move
790 point in the buffer, and it does nothing if `mark-ring' is empty.
791 It deactivates the mark.
793 The return value is not meaningful.
795 - Variable: mark-ring
796 The value of this buffer-local variable is the list of saved former
797 marks of the current buffer, most recent first.
800 => (#<marker at 11050 in markers.texi>
801 #<marker at 10832 in markers.texi>
804 - User Option: mark-ring-max
805 The value of this variable is the maximum size of `mark-ring'. If
806 more marks than this are pushed onto the `mark-ring', `push-mark'
807 discards an old mark when it adds a new one.
809 In additional to a per-buffer mark ring, there is a "global mark
810 ring". Marks are pushed onto the global mark ring the first time you
811 set a mark after switching buffers.
813 - Variable: global-mark-ring
814 The value of this variable is the list of saved former global
815 marks, most recent first.
817 - User Option: mark-ring-max
818 The value of this variable is the maximum size of
819 `global-mark-ring'. If more marks than this are pushed onto the
820 `global-mark-ring', `push-mark' discards an old mark when it adds
823 - Command: pop-global-mark
824 This function pops a mark off the global mark ring and jumps to
828 File: lispref.info, Node: The Region, Prev: The Mark, Up: Markers
833 The text between point and the mark is known as "the region".
834 Various functions operate on text delimited by point and the mark, but
835 only those functions specifically related to the region itself are
838 When `zmacs-regions' is non-`nil' (this is the default), the concept
839 of an "active region" exists. The region is active when the
840 corresponding mark is active. Note that only one active region at a
841 time can exist--i.e. only one buffer's region is active at a time.
842 *Note The Mark::, for more information about active regions.
844 - User Option: zmacs-regions
845 If non-`nil' (the default), active regions are used. *Note The
846 Mark::, for a detailed explanation of what this means.
848 A number of functions are provided for explicitly determining the
849 bounds of the region and whether it is active. Few programs need to use
850 these functions, however. A command designed to operate on a region
851 should normally use `interactive' with the `r' specification to find
852 the beginning and end of the region. This lets other Lisp programs
853 specify the bounds explicitly as arguments and automatically respects
854 the user's setting for ZMACS-REGIONS. (*Note Interactive Codes::.)
856 - Function: region-beginning &optional buffer
857 This function returns the position of the beginning of BUFFER's
858 region (as an integer). This is the position of either point or
859 the mark, whichever is smaller. BUFFER defaults to the current
862 If the mark does not point anywhere, an error is signaled. Note
863 that this function ignores whether the region is active.
865 - Function: region-end &optional buffer
866 This function returns the position of the end of BUFFER's region
867 (as an integer). This is the position of either point or the mark,
868 whichever is larger. BUFFER defaults to the current buffer if
871 If the mark does not point anywhere, an error is signaled. Note
872 that this function ignores whether the region is active.
874 - Function: region-exists-p
875 This function is non-`nil' if the region exists. If active regions
876 are in use (i.e. `zmacs-regions' is true), this means that the
877 region is active. Otherwise, this means that the user has pushed
878 a mark in this buffer at some point in the past. If this function
879 returns `nil', a function that uses the `r' interactive
880 specification will cause an error when called interactively.
882 - Function: region-active-p
883 If `zmacs-regions' is true, this is equivalent to
884 `region-exists-p'. Otherwise, this function always returns false.
885 This function is used by commands such as
886 `fill-paragraph-or-region' and `capitalize-region-or-word', which
887 operate either on the active region or on something else (e.g. the
888 word or paragraph at point).
890 - Variable: zmacs-region-stays
891 If a command sets this variable to true, the currently active
892 region will remain activated when the command finishes. (Normally
893 the region is deactivated when each command terminates.) If
894 ZMACS-REGIONS is false, however, this has no effect. Under normal
895 circumstances, you do not need to set this; use the interactive
896 specification `_' instead, if you want the region to remain active.
898 - Function: zmacs-activate-region
899 This function activates the region in the current buffer (this is
900 equivalent to activating the current buffer's mark). This will
901 normally also highlight the text in the active region and set
902 ZMACS-REGION-STAYS to `t'. (If ZMACS-REGIONS is false, however,
903 this function has no effect.)
905 - Function: zmacs-deactivate-region
906 This function deactivates the region in the current buffer (this is
907 equivalent to deactivating the current buffer's mark). This will
908 normally also unhighlight the text in the active region and set
909 ZMACS-REGION-STAYS to `nil'. (If ZMACS-REGIONS is false, however,
910 this function has no effect.)
912 - Function: zmacs-update-region
913 This function updates the active region, if it's currently active.
914 (If there is no active region, this function does nothing.) This
915 has the effect of updating the highlighting on the text in the
916 region; but you should never need to call this except under rather
917 strange circumstances. The command loop automatically calls it
918 when appropriate. Calling this function will call the hook
919 `zmacs-update-region-hook', if the region is active.
921 - Variable: zmacs-activate-region-hook
922 This normal hook is called when a region becomes active. (Usually
923 this happens as a result of a command that activates the region,
924 such as `set-mark-command', `activate-region', or
925 `exchange-point-and-mark'.) Note that calling
926 `zmacs-activate-region' will call this hook, even if the region is
927 already active. If ZMACS-REGIONS is false, however, this hook
928 will never get called under any circumstances.
930 - Variable: zmacs-deactivate-region-hook
931 This normal hook is called when an active region becomes inactive.
932 (Calling `zmacs-deactivate-region' when the region is inactive will
933 _not_ cause this hook to be called.) If ZMACS-REGIONS is false,
934 this hook will never get called.
936 - Variable: zmacs-update-region-hook
937 This normal hook is called when an active region is "updated" by
938 `zmacs-update-region'. This normally gets called at the end of
939 each command that sets ZMACS-REGION-STAYS to `t', indicating that
940 the region should remain activated. The motion commands do this.
943 File: lispref.info, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top
948 This chapter describes the functions that deal with the text in a
949 buffer. Most examine, insert, or delete text in the current buffer,
950 often in the vicinity of point. Many are interactive. All the
951 functions that change the text provide for undoing the changes (*note
954 Many text-related functions operate on a region of text defined by
955 two buffer positions passed in arguments named START and END. These
956 arguments should be either markers (*note Markers::) or numeric
957 character positions (*note Positions::). The order of these arguments
958 does not matter; it is all right for START to be the end of the region
959 and END the beginning. For example, `(delete-region 1 10)' and
960 `(delete-region 10 1)' are equivalent. An `args-out-of-range' error is
961 signaled if either START or END is outside the accessible portion of
962 the buffer. In an interactive call, point and the mark are used for
965 Throughout this chapter, "text" refers to the characters in the
966 buffer, together with their properties (when relevant).
970 * Near Point:: Examining text in the vicinity of point.
971 * Buffer Contents:: Examining text in a general fashion.
972 * Comparing Text:: Comparing substrings of buffers.
973 * Insertion:: Adding new text to a buffer.
974 * Commands for Insertion:: User-level commands to insert text.
975 * Deletion:: Removing text from a buffer.
976 * User-Level Deletion:: User-level commands to delete text.
977 * The Kill Ring:: Where removed text sometimes is saved for later use.
978 * Undo:: Undoing changes to the text of a buffer.
979 * Maintaining Undo:: How to enable and disable undo information.
980 How to control how much information is kept.
981 * Filling:: Functions for explicit filling.
982 * Margins:: How to specify margins for filling commands.
983 * Auto Filling:: How auto-fill mode is implemented to break lines.
984 * Sorting:: Functions for sorting parts of the buffer.
985 * Columns:: Computing horizontal positions, and using them.
986 * Indentation:: Functions to insert or adjust indentation.
987 * Case Changes:: Case conversion of parts of the buffer.
988 * Text Properties:: Assigning Lisp property lists to text characters.
989 * Substitution:: Replacing a given character wherever it appears.
990 * Registers:: How registers are implemented. Accessing the text or
991 position stored in a register.
992 * Transposition:: Swapping two portions of a buffer.
993 * Change Hooks:: Supplying functions to be run when text is changed.
994 * Transformations:: MD5 and base64 support.
997 File: lispref.info, Node: Near Point, Next: Buffer Contents, Up: Text
999 Examining Text Near Point
1000 =========================
1002 Many functions are provided to look at the characters around point.
1003 Several simple functions are described here. See also `looking-at' in
1004 *Note Regexp Search::.
1006 Many of these functions take an optional BUFFER argument. In all
1007 such cases, the current buffer will be used if this argument is
1008 omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions
1009 usually did not have these optional BUFFER arguments and always
1010 operated on the current buffer.)
1012 - Function: char-after &optional position buffer
1013 This function returns the character in the buffer at (i.e.,
1014 immediately after) position POSITION. If POSITION is out of range
1015 for this purpose, either before the beginning of the buffer, or at
1016 or beyond the end, then the value is `nil'. The default for
1017 POSITION is point. If optional argument BUFFER is `nil', the
1018 current buffer is assumed.
1020 In the following example, assume that the first character in the
1023 (char-to-string (char-after 1))
1026 - Function: char-before &optional position buffer
1027 This function returns the character in the current buffer
1028 immediately before position POSITION. If POSITION is out of range
1029 for this purpose, either at or before the beginning of the buffer,
1030 or beyond the end, then the value is `nil'. The default for
1031 POSITION is point. If optional argument BUFFER is `nil', the
1032 current buffer is assumed.
1034 - Function: following-char &optional buffer
1035 This function returns the character following point in the buffer.
1036 This is similar to `(char-after (point))'. However, if point is at
1037 the end of the buffer, then the result of `following-char' is 0.
1038 If optional argument BUFFER is `nil', the current buffer is
1041 Remember that point is always between characters, and the terminal
1042 cursor normally appears over the character following point.
1043 Therefore, the character returned by `following-char' is the
1044 character the cursor is over.
1046 In this example, point is between the `a' and the `c'.
1048 ---------- Buffer: foo ----------
1049 Gentlemen may cry ``Pea-!-ce! Peace!,''
1050 but there is no peace.
1051 ---------- Buffer: foo ----------
1053 (char-to-string (preceding-char))
1055 (char-to-string (following-char))
1058 - Function: preceding-char &optional buffer
1059 This function returns the character preceding point in the buffer.
1060 See above, under `following-char', for an example. If point is at
1061 the beginning of the buffer, `preceding-char' returns 0. If
1062 optional argument BUFFER is `nil', the current buffer is assumed.
1064 - Function: bobp &optional buffer
1065 This function returns `t' if point is at the beginning of the
1066 buffer. If narrowing is in effect, this means the beginning of the
1067 accessible portion of the text. If optional argument BUFFER is
1068 `nil', the current buffer is assumed. See also `point-min' in
1071 - Function: eobp &optional buffer
1072 This function returns `t' if point is at the end of the buffer.
1073 If narrowing is in effect, this means the end of accessible
1074 portion of the text. If optional argument BUFFER is `nil', the
1075 current buffer is assumed. See also `point-max' in *Note Point::.
1077 - Function: bolp &optional buffer
1078 This function returns `t' if point is at the beginning of a line.
1079 If optional argument BUFFER is `nil', the current buffer is
1080 assumed. *Note Text Lines::. The beginning of the buffer (or its
1081 accessible portion) always counts as the beginning of a line.
1083 - Function: eolp &optional buffer
1084 This function returns `t' if point is at the end of a line. The
1085 end of the buffer is always considered the end of a line. If
1086 optional argument BUFFER is `nil', the current buffer is assumed.
1087 The end of the buffer (or of its accessible portion) is always
1088 considered the end of a line.
1091 File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text
1093 Examining Buffer Contents
1094 =========================
1096 This section describes two functions that allow a Lisp program to
1097 convert any portion of the text in the buffer into a string.
1099 - Function: buffer-substring start end &optional buffer
1100 - Function: buffer-string start end &optional buffer
1101 These functions are equivalent and return a string containing a
1102 copy of the text of the region defined by positions START and END
1103 in the buffer. If the arguments are not positions in the
1104 accessible portion of the buffer, `buffer-substring' signals an
1105 `args-out-of-range' error. If optional argument BUFFER is `nil',
1106 the current buffer is assumed.
1108 If the region delineated by START and END contains duplicable
1109 extents, they will be remembered in the string. *Note Duplicable
1112 It is not necessary for START to be less than END; the arguments
1113 can be given in either order. But most often the smaller argument
1116 ---------- Buffer: foo ----------
1117 This is the contents of buffer foo
1119 ---------- Buffer: foo ----------
1121 (buffer-substring 1 10)
1123 (buffer-substring (point-max) 10)
1124 => "he contents of buffer foo
1128 File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text
1133 This function lets you compare portions of the text in a buffer,
1134 without copying them into strings first.
1136 - Function: compare-buffer-substrings buffer1 start1 end1 buffer2
1138 This function lets you compare two substrings of the same buffer
1139 or two different buffers. The first three arguments specify one
1140 substring, giving a buffer and two positions within the buffer.
1141 The last three arguments specify the other substring in the same
1142 way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for
1145 The value is negative if the first substring is less, positive if
1146 the first is greater, and zero if they are equal. The absolute
1147 value of the result is one plus the index of the first differing
1148 characters within the substrings.
1150 This function ignores case when comparing characters if
1151 `case-fold-search' is non-`nil'. It always ignores text
1154 Suppose the current buffer contains the text `foobarbar
1155 haha!rara!'; then in this example the two substrings are `rbar '
1156 and `rara!'. The value is 2 because the first substring is greater
1157 at the second character.
1159 (compare-buffer-substring nil 6 11 nil 16 21)
projects / chise / xemacs-chise.git / blob