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: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text
55 Examining Buffer Contents
56 =========================
58 This section describes two functions that allow a Lisp program to
59 convert any portion of the text in the buffer into a string.
61 - Function: buffer-substring start end &optional buffer
62 - Function: buffer-string start end &optional buffer
63 These functions are equivalent and return a string containing a
64 copy of the text of the region defined by positions START and END
65 in the buffer. If the arguments are not positions in the
66 accessible portion of the buffer, `buffer-substring' signals an
67 `args-out-of-range' error. If optional argument BUFFER is `nil',
68 the current buffer is assumed.
70 If the region delineated by START and END contains duplicable
71 extents, they will be remembered in the string. *Note Duplicable
74 It is not necessary for START to be less than END; the arguments
75 can be given in either order. But most often the smaller argument
78 ---------- Buffer: foo ----------
79 This is the contents of buffer foo
81 ---------- Buffer: foo ----------
83 (buffer-substring 1 10)
85 (buffer-substring (point-max) 10)
86 => "he contents of buffer foo
90 File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text
95 This function lets you compare portions of the text in a buffer,
96 without copying them into strings first.
98 - Function: compare-buffer-substrings buffer1 start1 end1 buffer2
100 This function lets you compare two substrings of the same buffer
101 or two different buffers. The first three arguments specify one
102 substring, giving a buffer and two positions within the buffer.
103 The last three arguments specify the other substring in the same
104 way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for
107 The value is negative if the first substring is less, positive if
108 the first is greater, and zero if they are equal. The absolute
109 value of the result is one plus the index of the first differing
110 characters within the substrings.
112 This function ignores case when comparing characters if
113 `case-fold-search' is non-`nil'. It always ignores text
116 Suppose the current buffer contains the text `foobarbar
117 haha!rara!'; then in this example the two substrings are `rbar '
118 and `rara!'. The value is 2 because the first substring is greater
119 at the second character.
121 (compare-buffer-substring nil 6 11 nil 16 21)
125 File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text
130 "Insertion" means adding new text to a buffer. The inserted text
131 goes at point--between the character before point and the character
134 Insertion relocates markers that point at positions after the
135 insertion point, so that they stay with the surrounding text (*note
136 Markers::). When a marker points at the place of insertion, insertion
137 normally doesn't relocate the marker, so that it points to the
138 beginning of the inserted text; however, certain special functions such
139 as `insert-before-markers' relocate such markers to point after the
142 Some insertion functions leave point before the inserted text, while
143 other functions leave it after. We call the former insertion "after
144 point" and the latter insertion "before point".
146 If a string with non-`nil' extent data is inserted, the remembered
147 extents will also be inserted. *Note Duplicable Extents::.
149 Insertion functions signal an error if the current buffer is
152 These functions copy text characters from strings and buffers along
153 with their properties. The inserted characters have exactly the same
154 properties as the characters they were copied from. By contrast,
155 characters specified as separate arguments, not part of a string or
156 buffer, inherit their text properties from the neighboring text.
158 - Function: insert &rest args
159 This function inserts the strings and/or characters ARGS into the
160 current buffer, at point, moving point forward. In other words, it
161 inserts the text before point. An error is signaled unless all
162 ARGS are either strings or characters. The value is `nil'.
164 - Function: insert-before-markers &rest args
165 This function inserts the strings and/or characters ARGS into the
166 current buffer, at point, moving point forward. An error is
167 signaled unless all ARGS are either strings or characters. The
170 This function is unlike the other insertion functions in that it
171 relocates markers initially pointing at the insertion point, to
172 point after the inserted text.
174 - Function: insert-string string &optional buffer
175 This function inserts STRING into BUFFER before point. BUFFER
176 defaults to the current buffer if omitted. This function is
177 chiefly useful if you want to insert a string in a buffer other
178 than the current one (otherwise you could just use `insert').
180 - Function: insert-char character &optional count ignored buffer
181 This function inserts COUNT instances of CHARACTER into BUFFER
182 before point. COUNT must be a number, and CHARACTER must be a
185 If optional argument BUFFER is `nil', the current buffer is
186 assumed. (In FSF Emacs, the third argument is called INHERIT and
187 refers to text properties. In XEmacs, it is always ignored.)
189 This function always returns `nil'.
191 - Function: insert-buffer-substring from-buffer-or-name &optional
193 This function inserts a portion of buffer FROM-BUFFER-OR-NAME
194 (which must already exist) into the current buffer before point.
195 The text inserted is the region from START and END. (These
196 arguments default to the beginning and end of the accessible
197 portion of that buffer.) This function returns `nil'.
199 In this example, the form is executed with buffer `bar' as the
200 current buffer. We assume that buffer `bar' is initially empty.
202 ---------- Buffer: foo ----------
203 We hold these truths to be self-evident, that all
204 ---------- Buffer: foo ----------
206 (insert-buffer-substring "foo" 1 20)
209 ---------- Buffer: bar ----------
210 We hold these truth-!-
211 ---------- Buffer: bar ----------
214 File: lispref.info, Node: Commands for Insertion, Next: Deletion, Prev: Insertion, Up: Text
216 User-Level Insertion Commands
217 =============================
219 This section describes higher-level commands for inserting text,
220 commands intended primarily for the user but useful also in Lisp
223 - Command: insert-buffer from-buffer-or-name
224 This command inserts the entire contents of FROM-BUFFER-OR-NAME
225 (which must exist) into the current buffer after point. It leaves
226 the mark after the inserted text. The value is `nil'.
228 - Command: self-insert-command count
229 This command inserts the last character typed; it does so COUNT
230 times, before point, and returns `nil'. Most printing characters
231 are bound to this command. In routine use, `self-insert-command'
232 is the most frequently called function in XEmacs, but programs
233 rarely use it except to install it on a keymap.
235 In an interactive call, COUNT is the numeric prefix argument.
237 This command calls `auto-fill-function' whenever that is non-`nil'
238 and the character inserted is a space or a newline (*note Auto
241 This command performs abbrev expansion if Abbrev mode is enabled
242 and the inserted character does not have word-constituent syntax.
243 (*Note Abbrevs::, and *Note Syntax Class Table::.)
245 This is also responsible for calling `blink-paren-function' when
246 the inserted character has close parenthesis syntax (*note
249 - Command: newline &optional count
250 This command inserts newlines into the current buffer before point.
251 If COUNT is supplied, that many newline characters are inserted.
253 This function calls `auto-fill-function' if the current column
254 number is greater than the value of `fill-column' and COUNT is
255 `nil'. Typically what `auto-fill-function' does is insert a
256 newline; thus, the overall result in this case is to insert two
257 newlines at different places: one at point, and another earlier in
258 the line. `newline' does not auto-fill if COUNT is non-`nil'.
260 This command indents to the left margin if that is not zero.
263 The value returned is `nil'. In an interactive call, COUNT is the
264 numeric prefix argument.
266 - Command: split-line
267 This command splits the current line, moving the portion of the
268 line after point down vertically so that it is on the next line
269 directly below where it was before. Whitespace is inserted as
270 needed at the beginning of the lower line, using the `indent-to'
271 function. `split-line' returns the position of point.
273 Programs hardly ever use this function.
275 - Variable: overwrite-mode
276 This variable controls whether overwrite mode is in effect: a
277 non-`nil' value enables the mode. It is automatically made
278 buffer-local when set in any fashion.
281 File: lispref.info, Node: Deletion, Next: User-Level Deletion, Prev: Commands for Insertion, Up: Text
286 Deletion means removing part of the text in a buffer, without saving
287 it in the kill ring (*note The Kill Ring::). Deleted text can't be
288 yanked, but can be reinserted using the undo mechanism (*note Undo::).
289 Some deletion functions do save text in the kill ring in some special
292 All of the deletion functions operate on the current buffer, and all
293 return a value of `nil'.
295 - Command: erase-buffer &optional buffer
296 This function deletes the entire text of BUFFER, leaving it empty.
297 If the buffer is read-only, it signals a `buffer-read-only'
298 error. Otherwise, it deletes the text without asking for any
299 confirmation. It returns `nil'. BUFFER defaults to the current
302 Normally, deleting a large amount of text from a buffer inhibits
303 further auto-saving of that buffer "because it has shrunk".
304 However, `erase-buffer' does not do this, the idea being that the
305 future text is not really related to the former text, and its size
306 should not be compared with that of the former text.
308 - Command: delete-region start end &optional buffer
309 This command deletes the text in BUFFER in the region defined by
310 START and END. The value is `nil'. If optional argument BUFFER
311 is `nil', the current buffer is assumed.
313 - Command: delete-char count &optional killp
314 This command deletes COUNT characters directly after point, or
315 before point if COUNT is negative. If KILLP is non-`nil', then it
316 saves the deleted characters in the kill ring.
318 In an interactive call, COUNT is the numeric prefix argument, and
319 KILLP is the unprocessed prefix argument. Therefore, if a prefix
320 argument is supplied, the text is saved in the kill ring. If no
321 prefix argument is supplied, then one character is deleted, but
322 not saved in the kill ring.
324 The value returned is always `nil'.
326 - Command: delete-backward-char count &optional killp
327 This command deletes COUNT characters directly before point, or
328 after point if COUNT is negative. If KILLP is non-`nil', then it
329 saves the deleted characters in the kill ring.
331 In an interactive call, COUNT is the numeric prefix argument, and
332 KILLP is the unprocessed prefix argument. Therefore, if a prefix
333 argument is supplied, the text is saved in the kill ring. If no
334 prefix argument is supplied, then one character is deleted, but
335 not saved in the kill ring.
337 The value returned is always `nil'.
339 - Command: backward-delete-char-untabify count &optional killp
340 This command deletes COUNT characters backward, changing tabs into
341 spaces. When the next character to be deleted is a tab, it is
342 first replaced with the proper number of spaces to preserve
343 alignment and then one of those spaces is deleted instead of the
344 tab. If KILLP is non-`nil', then the command saves the deleted
345 characters in the kill ring.
347 Conversion of tabs to spaces happens only if COUNT is positive.
348 If it is negative, exactly -COUNT characters after point are
351 In an interactive call, COUNT is the numeric prefix argument, and
352 KILLP is the unprocessed prefix argument. Therefore, if a prefix
353 argument is supplied, the text is saved in the kill ring. If no
354 prefix argument is supplied, then one character is deleted, but
355 not saved in the kill ring.
357 The value returned is always `nil'.
360 File: lispref.info, Node: User-Level Deletion, Next: The Kill Ring, Prev: Deletion, Up: Text
362 User-Level Deletion Commands
363 ============================
365 This section describes higher-level commands for deleting text,
366 commands intended primarily for the user but useful also in Lisp
369 - Command: delete-horizontal-space
370 This function deletes all spaces and tabs around point. It returns
373 In the following examples, we call `delete-horizontal-space' four
374 times, once on each line, with point between the second and third
375 characters on the line each time.
377 ---------- Buffer: foo ----------
382 ---------- Buffer: foo ----------
384 (delete-horizontal-space) ; Four times.
387 ---------- Buffer: foo ----------
392 ---------- Buffer: foo ----------
394 - Command: delete-indentation &optional join-following-p
395 This function joins the line point is on to the previous line,
396 deleting any whitespace at the join and in some cases replacing it
397 with one space. If JOIN-FOLLOWING-P is non-`nil',
398 `delete-indentation' joins this line to the following line
399 instead. The value is `nil'.
401 If there is a fill prefix, and the second of the lines being joined
402 starts with the prefix, then `delete-indentation' deletes the fill
403 prefix before joining the lines. *Note Margins::.
405 In the example below, point is located on the line starting
406 `events', and it makes no difference if there are trailing spaces
407 in the preceding line.
409 ---------- Buffer: foo ----------
410 When in the course of human
411 -!- events, it becomes necessary
412 ---------- Buffer: foo ----------
417 ---------- Buffer: foo ----------
418 When in the course of human-!- events, it becomes necessary
419 ---------- Buffer: foo ----------
421 After the lines are joined, the function `fixup-whitespace' is
422 responsible for deciding whether to leave a space at the junction.
424 - Command: fixup-whitespace
425 This function replaces all the white space surrounding point with
426 either one space or no space, according to the context. It
429 At the beginning or end of a line, the appropriate amount of space
430 is none. Before a character with close parenthesis syntax, or
431 after a character with open parenthesis or expression-prefix
432 syntax, no space is also appropriate. Otherwise, one space is
433 appropriate. *Note Syntax Class Table::.
435 In the example below, `fixup-whitespace' is called the first time
436 with point before the word `spaces' in the first line. For the
437 second invocation, point is directly after the `('.
439 ---------- Buffer: foo ----------
440 This has too many -!-spaces
441 This has too many spaces at the start of (-!- this list)
442 ---------- Buffer: foo ----------
449 ---------- Buffer: foo ----------
450 This has too many spaces
451 This has too many spaces at the start of (this list)
452 ---------- Buffer: foo ----------
454 - Command: just-one-space
455 This command replaces any spaces and tabs around point with a
456 single space. It returns `nil'.
458 - Command: delete-blank-lines
459 This function deletes blank lines surrounding point. If point is
460 on a blank line with one or more blank lines before or after it,
461 then all but one of them are deleted. If point is on an isolated
462 blank line, then it is deleted. If point is on a nonblank line,
463 the command deletes all blank lines following it.
465 A blank line is defined as a line containing only tabs and spaces.
467 `delete-blank-lines' returns `nil'.
470 File: lispref.info, Node: The Kill Ring, Next: Undo, Prev: User-Level Deletion, Up: Text
475 "Kill" functions delete text like the deletion functions, but save
476 it so that the user can reinsert it by "yanking". Most of these
477 functions have `kill-' in their name. By contrast, the functions whose
478 names start with `delete-' normally do not save text for yanking
479 (though they can still be undone); these are "deletion" functions.
481 Most of the kill commands are primarily for interactive use, and are
482 not described here. What we do describe are the functions provided for
483 use in writing such commands. You can use these functions to write
484 commands for killing text. When you need to delete text for internal
485 purposes within a Lisp function, you should normally use deletion
486 functions, so as not to disturb the kill ring contents. *Note
489 Killed text is saved for later yanking in the "kill ring". This is
490 a list that holds a number of recent kills, not just the last text
491 kill. We call this a "ring" because yanking treats it as having
492 elements in a cyclic order. The list is kept in the variable
493 `kill-ring', and can be operated on with the usual functions for lists;
494 there are also specialized functions, described in this section, that
497 Some people think this use of the word "kill" is unfortunate, since
498 it refers to operations that specifically _do not_ destroy the entities
499 "killed". This is in sharp contrast to ordinary life, in which death
500 is permanent and "killed" entities do not come back to life.
501 Therefore, other metaphors have been proposed. For example, the term
502 "cut ring" makes sense to people who, in pre-computer days, used
503 scissors and paste to cut up and rearrange manuscripts. However, it
504 would be difficult to change the terminology now.
508 * Kill Ring Concepts:: What text looks like in the kill ring.
509 * Kill Functions:: Functions that kill text.
510 * Yank Commands:: Commands that access the kill ring.
511 * Low-Level Kill Ring:: Functions and variables for kill ring access.
512 * Internals of Kill Ring:: Variables that hold kill-ring data.
515 File: lispref.info, Node: Kill Ring Concepts, Next: Kill Functions, Up: The Kill Ring
520 The kill ring records killed text as strings in a list, most recent
521 first. A short kill ring, for example, might look like this:
523 ("some text" "a different piece of text" "even older text")
525 When the list reaches `kill-ring-max' entries in length, adding a new
526 entry automatically deletes the last entry.
528 When kill commands are interwoven with other commands, each kill
529 command makes a new entry in the kill ring. Multiple kill commands in
530 succession build up a single entry in the kill ring, which would be
531 yanked as a unit; the second and subsequent consecutive kill commands
532 add text to the entry made by the first one.
534 For yanking, one entry in the kill ring is designated the "front" of
535 the ring. Some yank commands "rotate" the ring by designating a
536 different element as the "front." But this virtual rotation doesn't
537 change the list itself--the most recent entry always comes first in the
541 File: lispref.info, Node: Kill Functions, Next: Yank Commands, Prev: Kill Ring Concepts, Up: The Kill Ring
543 Functions for Killing
544 ---------------------
546 `kill-region' is the usual subroutine for killing text. Any command
547 that calls this function is a "kill command" (and should probably have
548 `kill' in its name). `kill-region' puts the newly killed text in a new
549 element at the beginning of the kill ring or adds it to the most recent
550 element. It uses the `last-command' variable to determine whether the
551 previous command was a kill command, and if so appends the killed text
552 to the most recent entry.
554 - Command: kill-region start end &optional verbose
555 This function kills the text in the region defined by START and
556 END. The text is deleted but saved in the kill ring, along with
557 its text properties. The value is always `nil'.
559 In an interactive call, START and END are point and the mark.
561 If the buffer is read-only, `kill-region' modifies the kill ring
562 just the same, then signals an error without modifying the buffer.
563 This is convenient because it lets the user use all the kill
564 commands to copy text into the kill ring from a read-only buffer.
566 - Command: copy-region-as-kill start end
567 This command saves the region defined by START and END on the kill
568 ring (including text properties), but does not delete the text
569 from the buffer. It returns `nil'. It also indicates the extent
570 of the text copied by moving the cursor momentarily, or by
571 displaying a message in the echo area.
573 The command does not set `this-command' to `kill-region', so a
574 subsequent kill command does not append to the same kill ring
577 Don't call `copy-region-as-kill' in Lisp programs unless you aim to
578 support Emacs 18. For Emacs 19, it is better to use `kill-new' or
579 `kill-append' instead. *Note Low-Level Kill Ring::.
582 File: lispref.info, Node: Yank Commands, Next: Low-Level Kill Ring, Prev: Kill Functions, Up: The Kill Ring
584 Functions for Yanking
585 ---------------------
587 "Yanking" means reinserting an entry of previously killed text from
588 the kill ring. The text properties are copied too.
590 - Command: yank &optional arg
591 This command inserts before point the text in the first entry in
592 the kill ring. It positions the mark at the beginning of that
593 text, and point at the end.
595 If ARG is a list (which occurs interactively when the user types
596 `C-u' with no digits), then `yank' inserts the text as described
597 above, but puts point before the yanked text and puts the mark
600 If ARG is a number, then `yank' inserts the ARGth most recently
601 killed text--the ARGth element of the kill ring list.
603 `yank' does not alter the contents of the kill ring or rotate it.
606 - Command: yank-pop arg
607 This command replaces the just-yanked entry from the kill ring
608 with a different entry from the kill ring.
610 This is allowed only immediately after a `yank' or another
611 `yank-pop'. At such a time, the region contains text that was just
612 inserted by yanking. `yank-pop' deletes that text and inserts in
613 its place a different piece of killed text. It does not add the
614 deleted text to the kill ring, since it is already in the kill
617 If ARG is `nil', then the replacement text is the previous element
618 of the kill ring. If ARG is numeric, the replacement is the ARGth
619 previous kill. If ARG is negative, a more recent kill is the
622 The sequence of kills in the kill ring wraps around, so that after
623 the oldest one comes the newest one, and before the newest one
626 The value is always `nil'.
629 File: lispref.info, Node: Low-Level Kill Ring, Next: Internals of Kill Ring, Prev: Yank Commands, Up: The Kill Ring
634 These functions and variables provide access to the kill ring at a
635 lower level, but still convenient for use in Lisp programs. They take
636 care of interaction with X Window selections. They do not exist in
639 - Function: current-kill count &optional do-not-move
640 The function `current-kill' rotates the yanking pointer which
641 designates the "front" of the kill ring by COUNT places (from newer
642 kills to older ones), and returns the text at that place in the
645 If the optional second argument DO-NOT-MOVE is non-`nil', then
646 `current-kill' doesn't alter the yanking pointer; it just returns
647 the COUNTth kill, counting from the current yanking pointer.
649 If COUNT is zero, indicating a request for the latest kill,
650 `current-kill' calls the value of `interprogram-paste-function'
651 (documented below) before consulting the kill ring.
653 - Function: kill-new string &optional replace
654 This function makes the text STRING the latest entry in the kill
655 ring, and sets `kill-ring-yank-pointer' to point to it.
657 Normally, STRING is added to the front of the kill ring as a new
658 entry. However, if optional argument REPLACE is non-`nil', the
659 entry previously at the front of the kill ring is discarded, and
662 This function runs the functions on `kill-hooks', and also invokes
663 the value of `interprogram-cut-function' (see below).
665 - Function: kill-append string before-p
666 This function appends the text STRING to the first entry in the
667 kill ring. Normally STRING goes at the end of the entry, but if
668 BEFORE-P is non-`nil', it goes at the beginning. This function
669 also invokes the value of `interprogram-cut-function' (see below).
671 - Variable: interprogram-paste-function
672 This variable provides a way of transferring killed text from other
673 programs, when you are using a window system. Its value should be
674 `nil' or a function of no arguments.
676 If the value is a function, `current-kill' calls it to get the
677 "most recent kill". If the function returns a non-`nil' value,
678 then that value is used as the "most recent kill". If it returns
679 `nil', then the first element of `kill-ring' is used.
681 The normal use of this hook is to get the X server's primary
682 selection as the most recent kill, even if the selection belongs
683 to another X client. *Note X Selections::.
685 - Variable: interprogram-cut-function
686 This variable provides a way of communicating killed text to other
687 programs, when you are using a window system. Its value should be
688 `nil' or a function of one argument.
690 If the value is a function, `kill-new' and `kill-append' call it
691 with the new first element of the kill ring as an argument.
693 The normal use of this hook is to set the X server's primary
694 selection to the newly killed text.
697 File: lispref.info, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring
699 Internals of the Kill Ring
700 --------------------------
702 The variable `kill-ring' holds the kill ring contents, in the form
703 of a list of strings. The most recent kill is always at the front of
706 The `kill-ring-yank-pointer' variable points to a link in the kill
707 ring list, whose CAR is the text to yank next. We say it identifies
708 the "front" of the ring. Moving `kill-ring-yank-pointer' to a
709 different link is called "rotating the kill ring". We call the kill
710 ring a "ring" because the functions that move the yank pointer wrap
711 around from the end of the list to the beginning, or vice-versa.
712 Rotation of the kill ring is virtual; it does not change the value of
715 Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
716 whose values are normally lists. The word "pointer" in the name of the
717 `kill-ring-yank-pointer' indicates that the variable's purpose is to
718 identify one element of the list for use by the next yank command.
720 The value of `kill-ring-yank-pointer' is always `eq' to one of the
721 links in the kill ring list. The element it identifies is the CAR of
722 that link. Kill commands, which change the kill ring, also set this
723 variable to the value of `kill-ring'. The effect is to rotate the ring
724 so that the newly killed text is at the front.
726 Here is a diagram that shows the variable `kill-ring-yank-pointer'
727 pointing to the second entry in the kill ring `("some text" "a
728 different piece of text" "yet older text")'.
730 kill-ring kill-ring-yank-pointer
732 | ___ ___ ---> ___ ___ ___ ___
733 --> |___|___|------> |___|___|--> |___|___|--> nil
736 | | -->"yet older text"
738 | --> "a different piece of text"
742 This state of affairs might occur after `C-y' (`yank') immediately
743 followed by `M-y' (`yank-pop').
745 - Variable: kill-ring
746 This variable holds the list of killed text sequences, most
747 recently killed first.
749 - Variable: kill-ring-yank-pointer
750 This variable's value indicates which element of the kill ring is
751 at the "front" of the ring for yanking. More precisely, the value
752 is a tail of the value of `kill-ring', and its CAR is the kill
753 string that `C-y' should yank.
755 - User Option: kill-ring-max
756 The value of this variable is the maximum length to which the kill
757 ring can grow, before elements are thrown away at the end. The
758 default value for `kill-ring-max' is 30.
761 File: lispref.info, Node: Undo, Next: Maintaining Undo, Prev: The Kill Ring, Up: Text
766 Most buffers have an "undo list", which records all changes made to
767 the buffer's text so that they can be undone. (The buffers that don't
768 have one are usually special-purpose buffers for which XEmacs assumes
769 that undoing is not useful.) All the primitives that modify the text
770 in the buffer automatically add elements to the front of the undo list,
771 which is in the variable `buffer-undo-list'.
773 - Variable: buffer-undo-list
774 This variable's value is the undo list of the current buffer. A
775 value of `t' disables the recording of undo information.
777 Here are the kinds of elements an undo list can have:
780 This kind of element records a previous value of point. Ordinary
781 cursor motion does not get any sort of undo record, but deletion
782 commands use these entries to record where point was before the
786 This kind of element indicates how to delete text that was
787 inserted. Upon insertion, the text occupied the range START-END
791 This kind of element indicates how to reinsert text that was
792 deleted. The deleted text itself is the string TEXT. The place to
793 reinsert it is `(abs POSITION)'.
796 This kind of element indicates that an unmodified buffer became
797 modified. The elements HIGH and LOW are two integers, each
798 recording 16 bits of the visited file's modification time as of
799 when it was previously visited or saved. `primitive-undo' uses
800 those values to determine whether to mark the buffer as unmodified
801 once again; it does so only if the file's modification time
802 matches those numbers.
804 `(nil PROPERTY VALUE START . END)'
805 This kind of element records a change in a text property. Here's
806 how you might undo the change:
808 (put-text-property START END PROPERTY VALUE)
811 This element indicates where point was at an earlier time.
812 Undoing this element sets point to POSITION. Deletion normally
813 creates an element of this kind as well as a reinsertion element.
816 This element is a boundary. The elements between two boundaries
817 are called a "change group"; normally, each change group
818 corresponds to one keyboard command, and undo commands normally
819 undo an entire group as a unit.
821 - Function: undo-boundary
822 This function places a boundary element in the undo list. The undo
823 command stops at such a boundary, and successive undo commands undo
824 to earlier and earlier boundaries. This function returns `nil'.
826 The editor command loop automatically creates an undo boundary
827 before each key sequence is executed. Thus, each undo normally
828 undoes the effects of one command. Self-inserting input
829 characters are an exception. The command loop makes a boundary
830 for the first such character; the next 19 consecutive
831 self-inserting input characters do not make boundaries, and then
832 the 20th does, and so on as long as self-inserting characters
835 All buffer modifications add a boundary whenever the previous
836 undoable change was made in some other buffer. This way, a
837 command that modifies several buffers makes a boundary in each
840 Calling this function explicitly is useful for splitting the
841 effects of a command into more than one unit. For example,
842 `query-replace' calls `undo-boundary' after each replacement, so
843 that the user can undo individual replacements one by one.
845 - Function: primitive-undo count list
846 This is the basic function for undoing elements of an undo list.
847 It undoes the first COUNT elements of LIST, returning the rest of
848 LIST. You could write this function in Lisp, but it is convenient
851 `primitive-undo' adds elements to the buffer's undo list when it
852 changes the buffer. Undo commands avoid confusion by saving the
853 undo list value at the beginning of a sequence of undo operations.
854 Then the undo operations use and update the saved value. The new
855 elements added by undoing are not part of this saved value, so
856 they don't interfere with continuing to undo.
859 File: lispref.info, Node: Maintaining Undo, Next: Filling, Prev: Undo, Up: Text
861 Maintaining Undo Lists
862 ======================
864 This section describes how to enable and disable undo information for
865 a given buffer. It also explains how the undo list is truncated
866 automatically so it doesn't get too big.
868 Recording of undo information in a newly created buffer is normally
869 enabled to start with; but if the buffer name starts with a space, the
870 undo recording is initially disabled. You can explicitly enable or
871 disable undo recording with the following two functions, or by setting
872 `buffer-undo-list' yourself.
874 - Command: buffer-enable-undo &optional buffer-or-name
875 This command enables recording undo information for buffer
876 BUFFER-OR-NAME, so that subsequent changes can be undone. If no
877 argument is supplied, then the current buffer is used. This
878 function does nothing if undo recording is already enabled in the
879 buffer. It returns `nil'.
881 In an interactive call, BUFFER-OR-NAME is the current buffer. You
882 cannot specify any other buffer.
884 - Command: buffer-disable-undo &optional buffer
885 - Command: buffer-flush-undo &optional buffer
886 This function discards the undo list of BUFFER, and disables
887 further recording of undo information. As a result, it is no
888 longer possible to undo either previous changes or any subsequent
889 changes. If the undo list of BUFFER is already disabled, this
890 function has no effect.
892 This function returns `nil'. It cannot be called interactively.
894 The name `buffer-flush-undo' is not considered obsolete, but the
895 preferred name `buffer-disable-undo' is new as of Emacs versions
898 As editing continues, undo lists get longer and longer. To prevent
899 them from using up all available memory space, garbage collection trims
900 them back to size limits you can set. (For this purpose, the "size" of
901 an undo list measures the cons cells that make up the list, plus the
902 strings of deleted text.) Two variables control the range of acceptable
903 sizes: `undo-limit' and `undo-strong-limit'.
905 - Variable: undo-limit
906 This is the soft limit for the acceptable size of an undo list.
907 The change group at which this size is exceeded is the last one
910 - Variable: undo-strong-limit
911 This is the upper limit for the acceptable size of an undo list.
912 The change group at which this size is exceeded is discarded
913 itself (along with all older change groups). There is one
914 exception: the very latest change group is never discarded no
915 matter how big it is.
918 File: lispref.info, Node: Filling, Next: Margins, Prev: Maintaining Undo, Up: Text
923 "Filling" means adjusting the lengths of lines (by moving the line
924 breaks) so that they are nearly (but no greater than) a specified
925 maximum width. Additionally, lines can be "justified", which means
926 inserting spaces to make the left and/or right margins line up
927 precisely. The width is controlled by the variable `fill-column'. For
928 ease of reading, lines should be no longer than 70 or so columns.
930 You can use Auto Fill mode (*note Auto Filling::) to fill text
931 automatically as you insert it, but changes to existing text may leave
932 it improperly filled. Then you must fill the text explicitly.
934 Most of the commands in this section return values that are not
935 meaningful. All the functions that do filling take note of the current
936 left margin, current right margin, and current justification style
937 (*note Margins::). If the current justification style is `none', the
938 filling functions don't actually do anything.
940 Several of the filling functions have an argument JUSTIFY. If it is
941 non-`nil', that requests some kind of justification. It can be `left',
942 `right', `full', or `center', to request a specific style of
943 justification. If it is `t', that means to use the current
944 justification style for this part of the text (see
945 `current-justification', below).
947 When you call the filling functions interactively, using a prefix
948 argument implies the value `full' for JUSTIFY.
950 - Command: fill-paragraph justify
951 This command fills the paragraph at or after point. If JUSTIFY is
952 non-`nil', each line is justified as well. It uses the ordinary
953 paragraph motion commands to find paragraph boundaries. *Note
954 Paragraphs: (xemacs)Paragraphs.
956 - Command: fill-region start end &optional justify
957 This command fills each of the paragraphs in the region from START
958 to END. It justifies as well if JUSTIFY is non-`nil'.
960 The variable `paragraph-separate' controls how to distinguish
961 paragraphs. *Note Standard Regexps::.
963 - Command: fill-individual-paragraphs start end &optional justify
965 This command fills each paragraph in the region according to its
966 individual fill prefix. Thus, if the lines of a paragraph were
967 indented with spaces, the filled paragraph will remain indented in
970 The first two arguments, START and END, are the beginning and end
971 of the region to be filled. The third and fourth arguments,
972 JUSTIFY and MAIL-FLAG, are optional. If JUSTIFY is non-`nil', the
973 paragraphs are justified as well as filled. If MAIL-FLAG is
974 non-`nil', it means the function is operating on a mail message
975 and therefore should not fill the header lines.
977 Ordinarily, `fill-individual-paragraphs' regards each change in
978 indentation as starting a new paragraph. If
979 `fill-individual-varying-indent' is non-`nil', then only separator
980 lines separate paragraphs. That mode can handle indented
981 paragraphs with additional indentation on the first line.
983 - User Option: fill-individual-varying-indent
984 This variable alters the action of `fill-individual-paragraphs' as
987 - Command: fill-region-as-paragraph start end &optional justify
988 This command considers a region of text as a paragraph and fills
989 it. If the region was made up of many paragraphs, the blank lines
990 between paragraphs are removed. This function justifies as well
991 as filling when JUSTIFY is non-`nil'.
993 In an interactive call, any prefix argument requests justification.
995 In Adaptive Fill mode, which is enabled by default,
996 `fill-region-as-paragraph' on an indented paragraph when there is
997 no fill prefix uses the indentation of the second line of the
998 paragraph as the fill prefix.
1000 - Command: justify-current-line how eop nosqueeze
1001 This command inserts spaces between the words of the current line
1002 so that the line ends exactly at `fill-column'. It returns `nil'.
1004 The argument HOW, if non-`nil' specifies explicitly the style of
1005 justification. It can be `left', `right', `full', `center', or
1006 `none'. If it is `t', that means to do follow specified
1007 justification style (see `current-justification', below). `nil'
1008 means to do full justification.
1010 If EOP is non-`nil', that means do left-justification when
1011 `current-justification' specifies full justification. This is used
1012 for the last line of a paragraph; even if the paragraph as a whole
1013 is fully justified, the last line should not be.
1015 If NOSQUEEZE is non-`nil', that means do not change interior
1018 - User Option: default-justification
1019 This variable's value specifies the style of justification to use
1020 for text that doesn't specify a style with a text property. The
1021 possible values are `left', `right', `full', `center', or `none'.
1022 The default value is `left'.
1024 - Function: current-justification
1025 This function returns the proper justification style to use for
1026 filling the text around point.
1028 - Variable: fill-paragraph-function
1029 This variable provides a way for major modes to override the
1030 filling of paragraphs. If the value is non-`nil',
1031 `fill-paragraph' calls this function to do the work. If the
1032 function returns a non-`nil' value, `fill-paragraph' assumes the
1033 job is done, and immediately returns that value.
1035 The usual use of this feature is to fill comments in programming
1036 language modes. If the function needs to fill a paragraph in the
1037 usual way, it can do so as follows:
1039 (let ((fill-paragraph-function nil))
1040 (fill-paragraph arg))
1042 - Variable: use-hard-newlines
1043 If this variable is non-`nil', the filling functions do not delete
1044 newlines that have the `hard' text property. These "hard
1045 newlines" act as paragraph separators.
1048 File: lispref.info, Node: Margins, Next: Auto Filling, Prev: Filling, Up: Text
1053 - User Option: fill-prefix
1054 This variable specifies a string of text that appears at the
1055 beginning of normal text lines and should be disregarded when
1056 filling them. Any line that fails to start with the fill prefix
1057 is considered the start of a paragraph; so is any line that starts
1058 with the fill prefix followed by additional whitespace. Lines
1059 that start with the fill prefix but no additional whitespace are
1060 ordinary text lines that can be filled together. The resulting
1061 filled lines also start with the fill prefix.
1063 The fill prefix follows the left margin whitespace, if any.
1065 - User Option: fill-column
1066 This buffer-local variable specifies the maximum width of filled
1067 lines. Its value should be an integer, which is a number of
1068 columns. All the filling, justification and centering commands
1069 are affected by this variable, including Auto Fill mode (*note
1072 As a practical matter, if you are writing text for other people to
1073 read, you should set `fill-column' to no more than 70. Otherwise
1074 the line will be too long for people to read comfortably, and this
1075 can make the text seem clumsy.
1077 - Variable: default-fill-column
1078 The value of this variable is the default value for `fill-column'
1079 in buffers that do not override it. This is the same as
1080 `(default-value 'fill-column)'.
1082 The default value for `default-fill-column' is 70.
1084 - Command: set-left-margin from to margin
1085 This sets the `left-margin' property on the text from FROM to TO
1086 to the value MARGIN. If Auto Fill mode is enabled, this command
1087 also refills the region to fit the new margin.
1089 - Command: set-right-margin from to margin
1090 This sets the `right-margin' property on the text from FROM to TO
1091 to the value MARGIN. If Auto Fill mode is enabled, this command
1092 also refills the region to fit the new margin.
1094 - Function: current-left-margin
1095 This function returns the proper left margin value to use for
1096 filling the text around point. The value is the sum of the
1097 `left-margin' property of the character at the start of the
1098 current line (or zero if none), and the value of the variable
1101 - Function: current-fill-column
1102 This function returns the proper fill column value to use for
1103 filling the text around point. The value is the value of the
1104 `fill-column' variable, minus the value of the `right-margin'
1105 property of the character after point.
1107 - Command: move-to-left-margin &optional n force
1108 This function moves point to the left margin of the current line.
1109 The column moved to is determined by calling the function
1110 `current-left-margin'. If the argument N is non-`nil',
1111 `move-to-left-margin' moves forward N-1 lines first.
1113 If FORCE is non-`nil', that says to fix the line's indentation if
1114 that doesn't match the left margin value.
1116 - Function: delete-to-left-margin &optional from to
1117 This function removes left margin indentation from the text
1118 between FROM and TO. The amount of indentation to delete is
1119 determined by calling `current-left-margin'. In no case does this
1120 function delete non-whitespace.
1122 The arguments FROM and TO are optional; the default is the whole
1125 - Function: indent-to-left-margin
1126 This is the default `indent-line-function', used in Fundamental
1127 mode, Text mode, etc. Its effect is to adjust the indentation at
1128 the beginning of the current line to the value specified by the
1129 variable `left-margin'. This may involve either inserting or
1130 deleting whitespace.
1132 - Variable: left-margin
1133 This variable specifies the base left margin column. In
1134 Fundamental mode, <LFD> indents to this column. This variable
1135 automatically becomes buffer-local when set in any fashion.
1138 File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text
1143 Auto Fill mode is a minor mode that fills lines automatically as text
1144 is inserted. This section describes the hook used by Auto Fill mode.
1145 For a description of functions that you can call explicitly to fill and
1146 justify existing text, see *Note Filling::.
1148 Auto Fill mode also enables the functions that change the margins and
1149 justification style to refill portions of the text. *Note Margins::.
1151 - Variable: auto-fill-function
1152 The value of this variable should be a function (of no arguments)
1153 to be called after self-inserting a space or a newline. It may be
1154 `nil', in which case nothing special is done in that case.
1156 The value of `auto-fill-function' is `do-auto-fill' when Auto-Fill
1157 mode is enabled. That is a function whose sole purpose is to
1158 implement the usual strategy for breaking a line.
1160 In older Emacs versions, this variable was named
1161 `auto-fill-hook', but since it is not called with the
1162 standard convention for hooks, it was renamed to
1163 `auto-fill-function' in version 19.
projects / chise / xemacs-chise.git / blob