1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion
55 Moving over Balanced Expressions
56 --------------------------------
58 Here are several functions concerned with balanced-parenthesis
59 expressions (also called "sexps" in connection with moving across them
60 in XEmacs). The syntax table controls how these functions interpret
61 various characters; see *Note Syntax Tables::. *Note Parsing
62 Expressions::, for lower-level primitives for scanning sexps or parts of
63 sexps. For user-level commands, see *Note Lists and Sexps:
64 (emacs)Lists and Sexps.
66 - Command: forward-list &optional arg
67 This function moves forward across ARG balanced groups of
68 parentheses. (Other syntactic entities such as words or paired
69 string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
70 is negative, move backward across that many groups of parentheses.
72 - Command: backward-list &optional count
73 This function moves backward across COUNT balanced groups of
74 parentheses. (Other syntactic entities such as words or paired
75 string quotes are ignored.) COUNT defaults to 1 if omitted. If
76 COUNT is negative, move forward across that many groups of
79 - Command: up-list &optional count
80 This function moves forward out of COUNT levels of parentheses. A
81 negative argument means move backward but still to a less deep
84 - Command: down-list &optional count
85 This function moves forward into COUNT levels of parentheses. A
86 negative argument means move backward but still go deeper in
87 parentheses (-COUNT levels).
89 - Command: forward-sexp &optional count
90 This function moves forward across COUNT balanced expressions.
91 Balanced expressions include both those delimited by parentheses
92 and other kinds, such as words and string constants. COUNT
93 defaults to 1 if omitted. If COUNT is negative, move backward
94 across that many balanced expressions. For example,
96 ---------- Buffer: foo ----------
97 (concat-!- "foo " (car x) y z)
98 ---------- Buffer: foo ----------
103 ---------- Buffer: foo ----------
104 (concat "foo " (car x) y-!- z)
105 ---------- Buffer: foo ----------
107 - Command: backward-sexp &optional count
108 This function moves backward across COUNT balanced expressions.
109 COUNT defaults to 1 if omitted. If COUNT is negative, move
110 forward across that many balanced expressions.
112 - Command: beginning-of-defun &optional count
113 This function moves back to the COUNTth beginning of a defun. If
114 COUNT is negative, this actually moves forward, but it still moves
115 to the beginning of a defun, not to the end of one. COUNT
116 defaults to 1 if omitted.
118 - Command: end-of-defun &optional count
119 This function moves forward to the COUNTth end of a defun. If
120 COUNT is negative, this actually moves backward, but it still
121 moves to the end of a defun, not to the beginning of one. COUNT
122 defaults to 1 if omitted.
124 - User Option: defun-prompt-regexp
125 If non-`nil', this variable holds a regular expression that
126 specifies what text can appear before the open-parenthesis that
127 starts a defun. That is to say, a defun begins on a line that
128 starts with a match for this regular expression, followed by a
129 character with open-parenthesis syntax.
132 File: lispref.info, Node: Skipping Characters, Prev: List Motion, Up: Motion
137 The following two functions move point over a specified set of
138 characters. For example, they are often used to skip whitespace. For
139 related functions, see *Note Motion and Syntax::.
141 - Function: skip-chars-forward character-set &optional limit buffer
142 This function moves point in BUFFER forward, skipping over a given
143 set of characters. It examines the character following point,
144 then advances point if the character matches CHARACTER-SET. This
145 continues until it reaches a character that does not match. The
146 function returns `nil'. BUFFER defaults to the current buffer if
149 The argument CHARACTER-SET is like the inside of a `[...]' in a
150 regular expression except that `]' is never special and `\' quotes
151 `^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters,
152 stopping before the first non-letter, and `"^a-zA-Z'" skips
153 non-letters stopping before the first letter. *Note Regular
156 If LIMIT is supplied (it must be a number or a marker), it
157 specifies the maximum position in the buffer that point can be
158 skipped to. Point will stop at or before LIMIT.
160 In the following example, point is initially located directly
161 before the `T'. After the form is evaluated, point is located at
162 the end of that line (between the `t' of `hat' and the newline).
163 The function skips all letters and spaces, but not newlines.
165 ---------- Buffer: foo ----------
166 I read "-!-The cat in the hat
168 ---------- Buffer: foo ----------
170 (skip-chars-forward "a-zA-Z ")
173 ---------- Buffer: foo ----------
174 I read "The cat in the hat-!-
176 ---------- Buffer: foo ----------
178 - Function: skip-chars-backward character-set &optional limit buffer
179 This function moves point backward, skipping characters that match
180 CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
181 except for the direction of motion.
184 File: lispref.info, Node: Excursions, Next: Narrowing, Prev: Motion, Up: Positions
189 It is often useful to move point "temporarily" within a localized
190 portion of the program, or to switch buffers temporarily. This is
191 called an "excursion", and it is done with the `save-excursion' special
192 form. This construct saves the current buffer and its values of point
193 and the mark so they can be restored after the completion of the
196 The forms for saving and restoring the configuration of windows are
197 described elsewhere (see *Note Window Configurations:: and *note Frame
200 - Special Form: save-excursion forms...
201 The `save-excursion' special form saves the identity of the current
202 buffer and the values of point and the mark in it, evaluates
203 FORMS, and finally restores the buffer and its saved values of
204 point and the mark. All three saved values are restored even in
205 case of an abnormal exit via `throw' or error (*note Nonlocal
208 The `save-excursion' special form is the standard way to switch
209 buffers or move point within one part of a program and avoid
210 affecting the rest of the program. It is used more than 500 times
211 in the Lisp sources of XEmacs.
213 `save-excursion' does not save the values of point and the mark for
214 other buffers, so changes in other buffers remain in effect after
215 `save-excursion' exits.
217 Likewise, `save-excursion' does not restore window-buffer
218 correspondences altered by functions such as `switch-to-buffer'.
219 One way to restore these correspondences, and the selected window,
220 is to use `save-window-excursion' inside `save-excursion' (*note
221 Window Configurations::).
223 The value returned by `save-excursion' is the result of the last of
224 FORMS, or `nil' if no FORMS are given.
229 (let ((old-buf (current-buffer))
230 (old-pnt (point-marker))
231 (old-mark (copy-marker (mark-marker))))
236 (set-marker (mark-marker) old-mark)))
238 - Special Form: save-current-buffer forms...
239 This special form is similar to `save-excursion' but it only saves
240 and restores the current buffer. Beginning with XEmacs 20.3,
241 `save-current-buffer' is a primitive.
243 - Special Form: with-current-buffer buffer forms...
244 This special form evaluates FORMS with BUFFER as the current
245 buffer. It returns the value of the last form.
247 - Special Form: with-temp-file filename forms...
248 This special form creates a new buffer, evaluates FORMS there, and
249 writes the buffer to FILENAME. It returns the value of the last
252 - Special Form: save-selected-window forms...
253 This special form is similar to `save-excursion' but it saves and
254 restores the selected window and nothing else.
257 File: lispref.info, Node: Narrowing, Prev: Excursions, Up: Positions
262 "Narrowing" means limiting the text addressable by XEmacs editing
263 commands to a limited range of characters in a buffer. The text that
264 remains addressable is called the "accessible portion" of the buffer.
266 Narrowing is specified with two buffer positions which become the
267 beginning and end of the accessible portion. For most editing commands
268 and most Emacs primitives, these positions replace the values of the
269 beginning and end of the buffer. While narrowing is in effect, no text
270 outside the accessible portion is displayed, and point cannot move
271 outside the accessible portion.
273 Values such as positions or line numbers, which usually count from
274 the beginning of the buffer, do so despite narrowing, but the functions
275 which use them refuse to operate on text that is inaccessible.
277 The commands for saving buffers are unaffected by narrowing; they
278 save the entire buffer regardless of any narrowing.
280 - Command: narrow-to-region start end &optional buffer
281 This function sets the accessible portion of BUFFER to start at
282 START and end at END. Both arguments should be character
283 positions. BUFFER defaults to the current buffer if omitted.
285 In an interactive call, START and END are set to the bounds of the
286 current region (point and the mark, with the smallest first).
288 - Command: narrow-to-page &optional move-count
289 This function sets the accessible portion of the current buffer to
290 include just the current page. An optional first argument
291 MOVE-COUNT non-`nil' means to move forward or backward by
292 MOVE-COUNT pages and then narrow. The variable `page-delimiter'
293 specifies where pages start and end (*note Standard Regexps::).
295 In an interactive call, MOVE-COUNT is set to the numeric prefix
298 - Command: widen &optional buffer
299 This function cancels any narrowing in BUFFER, so that the entire
300 contents are accessible. This is called "widening". It is
301 equivalent to the following expression:
303 (narrow-to-region 1 (1+ (buffer-size)))
305 BUFFER defaults to the current buffer if omitted.
307 - Special Form: save-restriction body...
308 This special form saves the current bounds of the accessible
309 portion, evaluates the BODY forms, and finally restores the saved
310 bounds, thus restoring the same state of narrowing (or absence
311 thereof) formerly in effect. The state of narrowing is restored
312 even in the event of an abnormal exit via `throw' or error (*note
313 Nonlocal Exits::). Therefore, this construct is a clean way to
314 narrow a buffer temporarily.
316 The value returned by `save-restriction' is that returned by the
317 last form in BODY, or `nil' if no body forms were given.
319 *Caution:* it is easy to make a mistake when using the
320 `save-restriction' construct. Read the entire description here
323 If BODY changes the current buffer, `save-restriction' still
324 restores the restrictions on the original buffer (the buffer whose
325 restrictions it saved from), but it does not restore the identity
326 of the current buffer.
328 `save-restriction' does _not_ restore point and the mark; use
329 `save-excursion' for that. If you use both `save-restriction' and
330 `save-excursion' together, `save-excursion' should come first (on
331 the outside). Otherwise, the old point value would be restored
332 with temporary narrowing still in effect. If the old point value
333 were outside the limits of the temporary narrowing, this would
334 fail to restore it accurately.
336 The `save-restriction' special form records the values of the
337 beginning and end of the accessible portion as distances from the
338 beginning and end of the buffer. In other words, it records the
339 amount of inaccessible text before and after the accessible
342 This method yields correct results if BODY does further narrowing.
343 However, `save-restriction' can become confused if the body widens
344 and then make changes outside the range of the saved narrowing.
345 When this is what you want to do, `save-restriction' is not the
346 right tool for the job. Here is what you must use instead:
348 (let ((start (point-min-marker))
349 (end (point-max-marker)))
353 (set-buffer (marker-buffer start))
354 (narrow-to-region start end))))
356 Here is a simple example of correct use of `save-restriction':
358 ---------- Buffer: foo ----------
359 This is the contents of foo
360 This is the contents of foo
361 This is the contents of foo-!-
362 ---------- Buffer: foo ----------
368 (narrow-to-region 1 (point))
369 (goto-char (point-min))
370 (replace-string "foo" "bar")))
372 ---------- Buffer: foo ----------
373 This is the contents of bar
374 This is the contents of bar
375 This is the contents of foo-!-
376 ---------- Buffer: foo ----------
379 File: lispref.info, Node: Markers, Next: Text, Prev: Positions, Up: Top
384 A "marker" is a Lisp object used to specify a position in a buffer
385 relative to the surrounding text. A marker changes its offset from the
386 beginning of the buffer automatically whenever text is inserted or
387 deleted, so that it stays with the two characters on either side of it.
391 * Overview of Markers:: The components of a marker, and how it relocates.
392 * Predicates on Markers:: Testing whether an object is a marker.
393 * Creating Markers:: Making empty markers or markers at certain places.
394 * Information from Markers:: Finding the marker's buffer or character position.
395 * Changing Markers:: Moving the marker to a new buffer or position.
396 * The Mark:: How ``the mark'' is implemented with a marker.
397 * The Region:: How to access ``the region''.
400 File: lispref.info, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers
405 A marker specifies a buffer and a position in that buffer. The
406 marker can be used to represent a position in the functions that
407 require one, just as an integer could be used. *Note Positions::, for
408 a complete description of positions.
410 A marker has two attributes: the marker position, and the marker
411 buffer. The marker position is an integer that is equivalent (at a
412 given time) to the marker as a position in that buffer. But the
413 marker's position value can change often during the life of the marker.
414 Insertion and deletion of text in the buffer relocate the marker. The
415 idea is that a marker positioned between two characters remains between
416 those two characters despite insertion and deletion elsewhere in the
417 buffer. Relocation changes the integer equivalent of the marker.
419 Deleting text around a marker's position leaves the marker between
420 the characters immediately before and after the deleted text. Inserting
421 text at the position of a marker normally leaves the marker in front of
422 the new text--unless it is inserted with `insert-before-markers' (*note
425 Insertion and deletion in a buffer must check all the markers and
426 relocate them if necessary. This slows processing in a buffer with a
427 large number of markers. For this reason, it is a good idea to make a
428 marker point nowhere if you are sure you don't need it any more.
429 Unreferenced markers are garbage collected eventually, but until then
430 will continue to use time if they do point somewhere.
432 Because it is common to perform arithmetic operations on a marker
433 position, most of the arithmetic operations (including `+' and `-')
434 accept markers as arguments. In such cases, the marker stands for its
437 Note that you can use extents to achieve the same functionality, and
438 more, as markers. (Markers were defined before extents, which is why
439 they both continue to exist.) A zero-length extent with the
440 `detachable' property removed is almost identical to a marker. (*Note
441 Extent Endpoints::, for more information on zero-length extents.)
445 * In order to get marker-like behavior in a zero-length extent, the
446 `detachable' property must be removed (otherwise, the extent will
447 disappear when text near it is deleted) and exactly one endpoint
448 must be closed (if both endpoints are closed, the extent will
449 expand to contain text inserted where it is located).
451 * If a zero-length extent has the `end-open' property but not the
452 `start-open' property (this is the default), text inserted at the
453 extent's location causes the extent to move forward, just like a
456 * If a zero-length extent has the `start-open' property but not the
457 `end-open' property, text inserted at the extent's location causes
458 the extent to remain before the text, like what happens to markers
459 when `insert-before-markers' is used.
461 * Markers end up after or before inserted text depending on whether
462 `insert' or `insert-before-markers' was called. These functions
463 do not affect zero-length extents differently; instead, the
464 presence or absence of the `start-open' and `end-open' extent
465 properties determines this, as just described.
467 * Markers are automatically removed from a buffer when they are no
468 longer in use. Extents remain around until explicitly removed
471 * Many functions are provided for listing the extents in a buffer or
472 in a region of a buffer. No such functions exist for markers.
474 Here are examples of creating markers, setting markers, and moving
477 ;; Make a new marker that initially does not point anywhere:
478 (setq m1 (make-marker))
479 => #<marker in no buffer>
481 ;; Set `m1' to point between the 99th and 100th characters
482 ;; in the current buffer:
484 => #<marker at 100 in markers.texi>
486 ;; Now insert one character at the beginning of the buffer:
487 (goto-char (point-min))
492 ;; `m1' is updated appropriately.
494 => #<marker at 101 in markers.texi>
496 ;; Two markers that point to the same position
497 ;; are not `eq', but they are `equal'.
498 (setq m2 (copy-marker m1))
499 => #<marker at 101 in markers.texi>
505 ;; When you are finished using a marker, make it point nowhere.
507 => #<marker in no buffer>
510 File: lispref.info, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers
512 Predicates on Markers
513 =====================
515 You can test an object to see whether it is a marker, or whether it
516 is either an integer or a marker or either an integer, a character, or a
517 marker. The latter tests are useful in connection with the arithmetic
518 functions that work with any of markers, integers, or characters.
520 - Function: markerp object
521 This function returns `t' if OBJECT is a marker, `nil' otherwise.
522 Note that integers are not markers, even though many functions
523 will accept either a marker or an integer.
525 - Function: integer-or-marker-p object
526 This function returns `t' if OBJECT is an integer or a marker,
529 - Function: integer-char-or-marker-p object
530 This function returns `t' if OBJECT is an integer, a character, or
531 a marker, `nil' otherwise.
533 - Function: number-or-marker-p object
534 This function returns `t' if OBJECT is a number (either kind) or a
535 marker, `nil' otherwise.
537 - Function: number-char-or-marker-p object
538 This function returns `t' if OBJECT is a number (either kind), a
539 character, or a marker, `nil' otherwise.
542 File: lispref.info, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers
544 Functions That Create Markers
545 =============================
547 When you create a new marker, you can make it point nowhere, or point
548 to the present position of point, or to the beginning or end of the
549 accessible portion of the buffer, or to the same place as another given
552 - Function: make-marker
553 This functions returns a newly created marker that does not point
557 => #<marker in no buffer>
559 - Function: point-marker &optional dont-copy-p buffer
560 This function returns a marker that points to the present position
561 of point in BUFFER, which defaults to the current buffer. *Note
562 Point::. For an example, see `copy-marker', below.
564 Internally, a marker corresponding to point is always maintained.
565 Normally the marker returned by `point-marker' is a copy; you may
566 modify it with reckless abandon. However, if optional argument
567 DONT-COPY-P is non-`nil', then the real point-marker is returned;
568 modifying the position of this marker will move point. It is
569 illegal to change the buffer of it, or make it point nowhere.
571 - Function: point-min-marker &optional buffer
572 This function returns a new marker that points to the beginning of
573 the accessible portion of BUFFER, which defaults to the current
574 buffer. This will be the beginning of the buffer unless narrowing
575 is in effect. *Note Narrowing::.
577 - Function: point-max-marker &optional buffer
578 This function returns a new marker that points to the end of the
579 accessible portion of BUFFER, which defaults to the current
580 buffer. This will be the end of the buffer unless narrowing is in
581 effect. *Note Narrowing::.
583 Here are examples of this function and `point-min-marker', shown in
584 a buffer containing a version of the source file for the text of
588 => #<marker at 1 in markers.texi>
590 => #<marker at 15573 in markers.texi>
592 (narrow-to-region 100 200)
595 => #<marker at 100 in markers.texi>
597 => #<marker at 200 in markers.texi>
599 - Function: copy-marker marker-or-integer &optional marker-type
600 If passed a marker as its argument, `copy-marker' returns a new
601 marker that points to the same place and the same buffer as does
602 MARKER-OR-INTEGER. If passed an integer as its argument,
603 `copy-marker' returns a new marker that points to position
604 MARKER-OR-INTEGER in the current buffer.
606 If passed an integer argument less than 1, `copy-marker' returns a
607 new marker that points to the beginning of the current buffer. If
608 passed an integer argument greater than the length of the buffer,
609 `copy-marker' returns a new marker that points to the end of the
612 An error is signaled if MARKER-OR-INTEGER is neither a marker nor
615 Optional second argument MARKER-TYPE specifies the insertion type
616 of the new marker; see `marker-insertion-type'.
618 (setq p (point-marker))
619 => #<marker at 2139 in markers.texi>
621 (setq q (copy-marker p))
622 => #<marker at 2139 in markers.texi>
634 => #<marker at 3000 in markers.texi>
639 (setq p (point-marker t))
640 => #<marker at 2139 in markers.texi>
643 => #<marker at 3000 in markers.texi>
649 => #<marker at 1 in markers.texi>
652 => #<marker at 7572 in markers.texi>
655 File: lispref.info, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers
657 Information from Markers
658 ========================
660 This section describes the functions for accessing the components of
663 - Function: marker-position marker
664 This function returns the position that MARKER points to, or `nil'
665 if it points nowhere.
667 - Function: marker-buffer marker
668 This function returns the buffer that MARKER points into, or `nil'
669 if it points nowhere.
671 (setq m (make-marker))
672 => #<marker in no buffer>
678 (set-marker m 3770 (current-buffer))
679 => #<marker at 3770 in markers.texi>
681 => #<buffer markers.texi>
685 Two distinct markers are considered `equal' (even though not `eq')
686 to each other if they have the same position and buffer, or if they
690 File: lispref.info, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers
692 Changing Marker Positions
693 =========================
695 This section describes how to change the position of an existing
696 marker. When you do this, be sure you know whether the marker is used
697 outside of your program, and, if so, what effects will result from
698 moving it--otherwise, confusing things may happen in other parts of
701 - Function: set-marker marker position &optional buffer
702 This function moves MARKER to POSITION in BUFFER. If BUFFER is
703 not provided, it defaults to the current buffer.
705 POSITION can be a marker, an integer or `nil'. If POSITION is an
706 integer, `set-marker' moves MARKER to point before the POSITIONth
707 character in BUFFER. If POSITION is `nil', MARKER is made to
708 point nowhere. Then it no longer slows down editing in any
709 buffer. If POSITION is less than 1, MARKER is moved to the
710 beginning of BUFFER. If POSITION is greater than the size of
711 BUFFER, MARKER is moved to the end of BUFFER.
713 The value returned is MARKER.
715 (setq m (point-marker))
716 => #<marker at 4714 in markers.texi>
718 => #<marker at 55 in markers.texi>
719 (setq b (get-buffer "foo"))
722 => #<marker at 1 in foo>
724 - Function: move-marker marker position &optional buffer
725 This is another name for `set-marker'.
728 File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
733 One special marker in each buffer is designated "the mark". It
734 records a position for the user for the sake of commands such as `C-w'
735 and `C-x <TAB>'. Lisp programs should set the mark only to values that
736 have a potential use to the user, and never for their own internal
737 purposes. For example, the `replace-regexp' command sets the mark to
738 the value of point before doing any replacements, because this enables
739 the user to move back there conveniently after the replace is finished.
741 Once the mark "exists" in a buffer, it normally never ceases to
742 exist. However, it may become "inactive", and usually does so after
743 each command (other than simple motion commands and some commands that
744 explicitly activate the mark). When the mark is active, the region
745 between point and the mark is called the "active region" and is
746 highlighted specially.
748 Many commands are designed so that when called interactively they
749 operate on the text between point and the mark. Such commands work
750 only when an active region exists, i.e. when the mark is active. (The
751 reason for this is to prevent you from accidentally deleting or
752 changing large chunks of your text.) If you are writing such a command,
753 don't examine the mark directly; instead, use `interactive' with the
754 `r' specification. This provides the values of point and the mark as
755 arguments to the command in an interactive call, but permits other Lisp
756 programs to specify arguments explicitly, and automatically signals an
757 error if the command is called interactively when no active region
758 exists. *Note Interactive Codes::.
760 Each buffer has its own value of the mark that is independent of the
761 value of the mark in other buffers. (When a buffer is created, the mark
762 exists but does not point anywhere. We consider this state as "the
763 absence of a mark in that buffer.") However, only one active region can
764 exist at a time. Activating the mark in one buffer automatically
765 deactivates an active mark in any other buffer. Note that the user can
766 explicitly activate a mark at any time by using the command
767 `activate-region' (normally bound to `M-C-z') or by using the command
768 `exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
769 side effect of activating the mark.
771 Some people do not like active regions, so they disable this behavior
772 by setting the variable `zmacs-regions' to `nil'. This makes the mark
773 always active (except when a buffer is just created and the mark points
774 nowhere), and turns off the highlighting of the region between point
775 and the mark. Commands that explicitly retrieve the value of the mark
776 should make sure that they behave correctly and consistently
777 irrespective of the setting of `zmacs-regions'; some primitives are
778 provided to ensure this behavior.
780 In addition to the mark, each buffer has a "mark ring" which is a
781 list of markers containing previous values of the mark. When editing
782 commands change the mark, they should normally save the old value of the
783 mark on the mark ring. The variable `mark-ring-max' specifies the
784 maximum number of entries in the mark ring; once the list becomes this
785 long, adding a new element deletes the last element.
787 - Function: mark &optional force buffer
788 This function returns BUFFER's mark position as an integer.
789 BUFFER defaults to the current buffer if omitted.
791 If the mark is inactive, `mark' normally returns `nil'. However,
792 if FORCE is non-`nil', then `mark' returns the mark position
793 anyway--or `nil', if the mark is not yet set for the buffer.
795 (Remember that if ZMACS-REGIONS is `nil', the mark is always
796 active as long as it exists, and the FORCE argument will have no
799 If you are using this in an editing command, you are most likely
800 making a mistake; see the documentation of `set-mark' below.
802 - Function: mark-marker &optional force buffer
803 This function returns BUFFER's mark. BUFFER defaults to the
804 current buffer if omitted. This is the very marker that records
805 the mark location inside XEmacs, not a copy. Therefore, changing
806 this marker's position will directly affect the position of the
807 mark. Don't do it unless that is the effect you want.
809 If the mark is inactive, `mark-marker' normally returns `nil'.
810 However, if FORCE is non-`nil', then `mark-marker' returns the
812 (setq m (mark-marker))
813 => #<marker at 3420 in markers.texi>
815 => #<marker at 100 in markers.texi>
817 => #<marker at 100 in markers.texi>
819 Like any marker, this marker can be set to point at any buffer you
820 like. We don't recommend that you make it point at any buffer
821 other than the one of which it is the mark. If you do, it will
822 yield perfectly consistent, but rather odd, results.
824 - Function: set-mark position &optional buffer
825 This function sets `buffer''s mark to POSITION, and activates the
826 mark. BUFFER defaults to the current buffer if omitted. The old
827 value of the mark is _not_ pushed onto the mark ring.
829 *Please note:* Use this function only if you want the user to see
830 that the mark has moved, and you want the previous mark position to
831 be lost. Normally, when a new mark is set, the old one should go
832 on the `mark-ring'. For this reason, most applications should use
833 `push-mark' and `pop-mark', not `set-mark'.
835 Novice XEmacs Lisp programmers often try to use the mark for the
836 wrong purposes. The mark saves a location for the user's
837 convenience. An editing command should not alter the mark unless
838 altering the mark is part of the user-level functionality of the
839 command. (And, in that case, this effect should be documented.)
840 To remember a location for internal use in the Lisp program, store
841 it in a Lisp variable. For example:
843 (let ((start (point)))
845 (delete-region start (point))).
847 - Command: exchange-point-and-mark &optional dont-activate-region
848 This function exchanges the positions of point and the mark. It
849 is intended for interactive use. The mark is also activated
850 unless DONT-ACTIVATE-REGION is non-`nil'.
852 - Function: push-mark &optional position nomsg activate buffer
853 This function sets BUFFER's mark to POSITION, and pushes a copy of
854 the previous mark onto `mark-ring'. BUFFER defaults to the
855 current buffer if omitted. If POSITION is `nil', then the value
856 of point is used. `push-mark' returns `nil'.
858 If the last global mark pushed was not in BUFFER, also push
859 POSITION on the global mark ring (see below).
861 The function `push-mark' normally _does not_ activate the mark.
862 To do that, specify `t' for the argument ACTIVATE.
864 A `Mark set' message is displayed unless NOMSG is non-`nil'.
867 This function pops off the top element of `mark-ring' and makes
868 that mark become the buffer's actual mark. This does not move
869 point in the buffer, and it does nothing if `mark-ring' is empty.
870 It deactivates the mark.
872 The return value is not meaningful.
874 - Variable: mark-ring
875 The value of this buffer-local variable is the list of saved former
876 marks of the current buffer, most recent first.
879 => (#<marker at 11050 in markers.texi>
880 #<marker at 10832 in markers.texi>
883 - User Option: mark-ring-max
884 The value of this variable is the maximum size of `mark-ring'. If
885 more marks than this are pushed onto the `mark-ring', `push-mark'
886 discards an old mark when it adds a new one.
888 In additional to a per-buffer mark ring, there is a "global mark
889 ring". Marks are pushed onto the global mark ring the first time you
890 set a mark after switching buffers.
892 - Variable: global-mark-ring
893 The value of this variable is the list of saved former global
894 marks, most recent first.
896 - User Option: mark-ring-max
897 The value of this variable is the maximum size of
898 `global-mark-ring'. If more marks than this are pushed onto the
899 `global-mark-ring', `push-mark' discards an old mark when it adds
902 - Command: pop-global-mark
903 This function pops a mark off the global mark ring and jumps to
907 File: lispref.info, Node: The Region, Prev: The Mark, Up: Markers
912 The text between point and the mark is known as "the region".
913 Various functions operate on text delimited by point and the mark, but
914 only those functions specifically related to the region itself are
917 When `zmacs-regions' is non-`nil' (this is the default), the concept
918 of an "active region" exists. The region is active when the
919 corresponding mark is active. Note that only one active region at a
920 time can exist--i.e. only one buffer's region is active at a time.
921 *Note The Mark::, for more information about active regions.
923 - User Option: zmacs-regions
924 If non-`nil' (the default), active regions are used. *Note The
925 Mark::, for a detailed explanation of what this means.
927 A number of functions are provided for explicitly determining the
928 bounds of the region and whether it is active. Few programs need to use
929 these functions, however. A command designed to operate on a region
930 should normally use `interactive' with the `r' specification to find
931 the beginning and end of the region. This lets other Lisp programs
932 specify the bounds explicitly as arguments and automatically respects
933 the user's setting for ZMACS-REGIONS. (*Note Interactive Codes::.)
935 - Function: region-beginning &optional buffer
936 This function returns the position of the beginning of BUFFER's
937 region (as an integer). This is the position of either point or
938 the mark, whichever is smaller. BUFFER defaults to the current
941 If the mark does not point anywhere, an error is signaled. Note
942 that this function ignores whether the region is active.
944 - Function: region-end &optional buffer
945 This function returns the position of the end of BUFFER's region
946 (as an integer). This is the position of either point or the mark,
947 whichever is larger. BUFFER defaults to the current buffer if
950 If the mark does not point anywhere, an error is signaled. Note
951 that this function ignores whether the region is active.
953 - Function: region-exists-p
954 This function is non-`nil' if the region exists. If active regions
955 are in use (i.e. `zmacs-regions' is true), this means that the
956 region is active. Otherwise, this means that the user has pushed
957 a mark in this buffer at some point in the past. If this function
958 returns `nil', a function that uses the `r' interactive
959 specification will cause an error when called interactively.
961 - Function: region-active-p
962 If `zmacs-regions' is true, this is equivalent to
963 `region-exists-p'. Otherwise, this function always returns false.
964 This function is used by commands such as
965 `fill-paragraph-or-region' and `capitalize-region-or-word', which
966 operate either on the active region or on something else (e.g. the
967 word or paragraph at point).
969 - Variable: zmacs-region-stays
970 If a command sets this variable to true, the currently active
971 region will remain activated when the command finishes. (Normally
972 the region is deactivated when each command terminates.) If
973 ZMACS-REGIONS is false, however, this has no effect. Under normal
974 circumstances, you do not need to set this; use the interactive
975 specification `_' instead, if you want the region to remain active.
977 - Function: zmacs-activate-region
978 This function activates the region in the current buffer (this is
979 equivalent to activating the current buffer's mark). This will
980 normally also highlight the text in the active region and set
981 ZMACS-REGION-STAYS to `t'. (If ZMACS-REGIONS is false, however,
982 this function has no effect.)
984 - Function: zmacs-deactivate-region
985 This function deactivates the region in the current buffer (this is
986 equivalent to deactivating the current buffer's mark). This will
987 normally also unhighlight the text in the active region and set
988 ZMACS-REGION-STAYS to `nil'. (If ZMACS-REGIONS is false, however,
989 this function has no effect.)
991 - Function: zmacs-update-region
992 This function updates the active region, if it's currently active.
993 (If there is no active region, this function does nothing.) This
994 has the effect of updating the highlighting on the text in the
995 region; but you should never need to call this except under rather
996 strange circumstances. The command loop automatically calls it
997 when appropriate. Calling this function will call the hook
998 `zmacs-update-region-hook', if the region is active.
1000 - Variable: zmacs-activate-region-hook
1001 This normal hook is called when a region becomes active. (Usually
1002 this happens as a result of a command that activates the region,
1003 such as `set-mark-command', `activate-region', or
1004 `exchange-point-and-mark'.) Note that calling
1005 `zmacs-activate-region' will call this hook, even if the region is
1006 already active. If ZMACS-REGIONS is false, however, this hook
1007 will never get called under any circumstances.
1009 - Variable: zmacs-deactivate-region-hook
1010 This normal hook is called when an active region becomes inactive.
1011 (Calling `zmacs-deactivate-region' when the region is inactive will
1012 _not_ cause this hook to be called.) If ZMACS-REGIONS is false,
1013 this hook will never get called.
1015 - Variable: zmacs-update-region-hook
1016 This normal hook is called when an active region is "updated" by
1017 `zmacs-update-region'. This normally gets called at the end of
1018 each command that sets ZMACS-REGION-STAYS to `t', indicating that
1019 the region should remain activated. The motion commands do this.
1022 File: lispref.info, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top
1027 This chapter describes the functions that deal with the text in a
1028 buffer. Most examine, insert, or delete text in the current buffer,
1029 often in the vicinity of point. Many are interactive. All the
1030 functions that change the text provide for undoing the changes (*note
1033 Many text-related functions operate on a region of text defined by
1034 two buffer positions passed in arguments named START and END. These
1035 arguments should be either markers (*note Markers::) or numeric
1036 character positions (*note Positions::). The order of these arguments
1037 does not matter; it is all right for START to be the end of the region
1038 and END the beginning. For example, `(delete-region 1 10)' and
1039 `(delete-region 10 1)' are equivalent. An `args-out-of-range' error is
1040 signaled if either START or END is outside the accessible portion of
1041 the buffer. In an interactive call, point and the mark are used for
1044 Throughout this chapter, "text" refers to the characters in the
1045 buffer, together with their properties (when relevant).
1049 * Near Point:: Examining text in the vicinity of point.
1050 * Buffer Contents:: Examining text in a general fashion.
1051 * Comparing Text:: Comparing substrings of buffers.
1052 * Insertion:: Adding new text to a buffer.
1053 * Commands for Insertion:: User-level commands to insert text.
1054 * Deletion:: Removing text from a buffer.
1055 * User-Level Deletion:: User-level commands to delete text.
1056 * The Kill Ring:: Where removed text sometimes is saved for later use.
1057 * Undo:: Undoing changes to the text of a buffer.
1058 * Maintaining Undo:: How to enable and disable undo information.
1059 How to control how much information is kept.
1060 * Filling:: Functions for explicit filling.
1061 * Margins:: How to specify margins for filling commands.
1062 * Auto Filling:: How auto-fill mode is implemented to break lines.
1063 * Sorting:: Functions for sorting parts of the buffer.
1064 * Columns:: Computing horizontal positions, and using them.
1065 * Indentation:: Functions to insert or adjust indentation.
1066 * Case Changes:: Case conversion of parts of the buffer.
1067 * Text Properties:: Assigning Lisp property lists to text characters.
1068 * Substitution:: Replacing a given character wherever it appears.
1069 * Registers:: How registers are implemented. Accessing the text or
1070 position stored in a register.
1071 * Transposition:: Swapping two portions of a buffer.
1072 * Change Hooks:: Supplying functions to be run when text is changed.
1073 * Transformations:: MD5 and base64 support.
1076 File: lispref.info, Node: Near Point, Next: Buffer Contents, Up: Text
1078 Examining Text Near Point
1079 =========================
1081 Many functions are provided to look at the characters around point.
1082 Several simple functions are described here. See also `looking-at' in
1083 *Note Regexp Search::.
1085 Many of these functions take an optional BUFFER argument. In all
1086 such cases, the current buffer will be used if this argument is
1087 omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions
1088 usually did not have these optional BUFFER arguments and always
1089 operated on the current buffer.)
1091 - Function: char-after &optional position buffer
1092 This function returns the character in the buffer at (i.e.,
1093 immediately after) position POSITION. If POSITION is out of range
1094 for this purpose, either before the beginning of the buffer, or at
1095 or beyond the end, then the value is `nil'. The default for
1096 POSITION is point. If optional argument BUFFER is `nil', the
1097 current buffer is assumed.
1099 In the following example, assume that the first character in the
1102 (char-to-string (char-after 1))
1105 - Function: char-before &optional position buffer
1106 This function returns the character in the current buffer
1107 immediately before position POSITION. If POSITION is out of range
1108 for this purpose, either at or before the beginning of the buffer,
1109 or beyond the end, then the value is `nil'. The default for
1110 POSITION is point. If optional argument BUFFER is `nil', the
1111 current buffer is assumed.
1113 - Function: following-char &optional buffer
1114 This function returns the character following point in the buffer.
1115 This is similar to `(char-after (point))'. However, if point is at
1116 the end of the buffer, then the result of `following-char' is 0.
1117 If optional argument BUFFER is `nil', the current buffer is
1120 Remember that point is always between characters, and the terminal
1121 cursor normally appears over the character following point.
1122 Therefore, the character returned by `following-char' is the
1123 character the cursor is over.
1125 In this example, point is between the `a' and the `c'.
1127 ---------- Buffer: foo ----------
1128 Gentlemen may cry ``Pea-!-ce! Peace!,''
1129 but there is no peace.
1130 ---------- Buffer: foo ----------
1132 (char-to-string (preceding-char))
1134 (char-to-string (following-char))
1137 - Function: preceding-char &optional buffer
1138 This function returns the character preceding point in the buffer.
1139 See above, under `following-char', for an example. If point is at
1140 the beginning of the buffer, `preceding-char' returns 0. If
1141 optional argument BUFFER is `nil', the current buffer is assumed.
1143 - Function: bobp &optional buffer
1144 This function returns `t' if point is at the beginning of the
1145 buffer. If narrowing is in effect, this means the beginning of the
1146 accessible portion of the text. If optional argument BUFFER is
1147 `nil', the current buffer is assumed. See also `point-min' in
1150 - Function: eobp &optional buffer
1151 This function returns `t' if point is at the end of the buffer.
1152 If narrowing is in effect, this means the end of accessible
1153 portion of the text. If optional argument BUFFER is `nil', the
1154 current buffer is assumed. See also `point-max' in *Note Point::.
1156 - Function: bolp &optional buffer
1157 This function returns `t' if point is at the beginning of a line.
1158 If optional argument BUFFER is `nil', the current buffer is
1159 assumed. *Note Text Lines::. The beginning of the buffer (or its
1160 accessible portion) always counts as the beginning of a line.
1162 - Function: eolp &optional buffer
1163 This function returns `t' if point is at the end of a line. The
1164 end of the buffer is always considered the end of a line. If
1165 optional argument BUFFER is `nil', the current buffer is assumed.
1166 The end of the buffer (or of its accessible portion) is always
1167 considered the end of a line.
projects / chise / xemacs-chise.git- / blob