1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
58 One special marker in each buffer is designated "the mark". It
59 records a position for the user for the sake of commands such as `C-w'
60 and `C-x <TAB>'. Lisp programs should set the mark only to values that
61 have a potential use to the user, and never for their own internal
62 purposes. For example, the `replace-regexp' command sets the mark to
63 the value of point before doing any replacements, because this enables
64 the user to move back there conveniently after the replace is finished.
66 Once the mark "exists" in a buffer, it normally never ceases to
67 exist. However, it may become "inactive", and usually does so after
68 each command (other than simple motion commands and some commands that
69 explicitly activate the mark). When the mark is active, the region
70 between point and the mark is called the "active region" and is
71 highlighted specially.
73 Many commands are designed so that when called interactively they
74 operate on the text between point and the mark. Such commands work
75 only when an active region exists, i.e. when the mark is active. (The
76 reason for this is to prevent you from accidentally deleting or
77 changing large chunks of your text.) If you are writing such a command,
78 don't examine the mark directly; instead, use `interactive' with the
79 `r' specification. This provides the values of point and the mark as
80 arguments to the command in an interactive call, but permits other Lisp
81 programs to specify arguments explicitly, and automatically signals an
82 error if the command is called interactively when no active region
83 exists. *Note Interactive Codes::.
85 Each buffer has its own value of the mark that is independent of the
86 value of the mark in other buffers. (When a buffer is created, the mark
87 exists but does not point anywhere. We consider this state as "the
88 absence of a mark in that buffer.") However, only one active region can
89 exist at a time. Activating the mark in one buffer automatically
90 deactivates an active mark in any other buffer. Note that the user can
91 explicitly activate a mark at any time by using the command
92 `activate-region' (normally bound to `M-C-z') or by using the command
93 `exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
94 side effect of activating the mark.
96 Some people do not like active regions, so they disable this behavior
97 by setting the variable `zmacs-regions' to `nil'. This makes the mark
98 always active (except when a buffer is just created and the mark points
99 nowhere), and turns off the highlighting of the region between point
100 and the mark. Commands that explicitly retrieve the value of the mark
101 should make sure that they behave correctly and consistently
102 irrespective of the setting of `zmacs-regions'; some primitives are
103 provided to ensure this behavior.
105 In addition to the mark, each buffer has a "mark ring" which is a
106 list of markers containing previous values of the mark. When editing
107 commands change the mark, they should normally save the old value of the
108 mark on the mark ring. The variable `mark-ring-max' specifies the
109 maximum number of entries in the mark ring; once the list becomes this
110 long, adding a new element deletes the last element.
112 - Function: mark &optional force buffer
113 This function returns BUFFER's mark position as an integer.
114 BUFFER defaults to the current buffer if omitted.
116 If the mark is inactive, `mark' normally returns `nil'. However,
117 if FORCE is non-`nil', then `mark' returns the mark position
118 anyway--or `nil', if the mark is not yet set for the buffer.
120 (Remember that if ZMACS-REGIONS is `nil', the mark is always
121 active as long as it exists, and the FORCE argument will have no
124 If you are using this in an editing command, you are most likely
125 making a mistake; see the documentation of `set-mark' below.
127 - Function: mark-marker inactive-p buffer
128 This function returns BUFFER's mark. BUFFER defaults to the
129 current buffer if omitted. This is the very marker that records
130 the mark location inside XEmacs, not a copy. Therefore, changing
131 this marker's position will directly affect the position of the
132 mark. Don't do it unless that is the effect you want.
134 If the mark is inactive, `mark-marker' normally returns `nil'.
135 However, if FORCE is non-`nil', then `mark-marker' returns the
137 (setq m (mark-marker))
138 => #<marker at 3420 in markers.texi>
140 => #<marker at 100 in markers.texi>
142 => #<marker at 100 in markers.texi>
144 Like any marker, this marker can be set to point at any buffer you
145 like. We don't recommend that you make it point at any buffer
146 other than the one of which it is the mark. If you do, it will
147 yield perfectly consistent, but rather odd, results.
149 - Function: set-mark position &optional buffer
150 This function sets `buffer''s mark to POSITION, and activates the
151 mark. BUFFER defaults to the current buffer if omitted. The old
152 value of the mark is _not_ pushed onto the mark ring.
154 *Please note:* Use this function only if you want the user to see
155 that the mark has moved, and you want the previous mark position to
156 be lost. Normally, when a new mark is set, the old one should go
157 on the `mark-ring'. For this reason, most applications should use
158 `push-mark' and `pop-mark', not `set-mark'.
160 Novice XEmacs Lisp programmers often try to use the mark for the
161 wrong purposes. The mark saves a location for the user's
162 convenience. An editing command should not alter the mark unless
163 altering the mark is part of the user-level functionality of the
164 command. (And, in that case, this effect should be documented.)
165 To remember a location for internal use in the Lisp program, store
166 it in a Lisp variable. For example:
170 (delete-region beg (point))).
172 - Command: exchange-point-and-mark &optional dont-activate-region
173 This function exchanges the positions of point and the mark. It
174 is intended for interactive use. The mark is also activated
175 unless DONT-ACTIVATE-REGION is non-`nil'.
177 - Function: push-mark &optional position nomsg activate buffer
178 This function sets BUFFER's mark to POSITION, and pushes a copy of
179 the previous mark onto `mark-ring'. BUFFER defaults to the
180 current buffer if omitted. If POSITION is `nil', then the value
181 of point is used. `push-mark' returns `nil'.
183 If the last global mark pushed was not in BUFFER, also push
184 POSITION on the global mark ring (see below).
186 The function `push-mark' normally _does not_ activate the mark.
187 To do that, specify `t' for the argument ACTIVATE.
189 A `Mark set' message is displayed unless NOMSG is non-`nil'.
192 This function pops off the top element of `mark-ring' and makes
193 that mark become the buffer's actual mark. This does not move
194 point in the buffer, and it does nothing if `mark-ring' is empty.
195 It deactivates the mark.
197 The return value is not meaningful.
199 - Variable: mark-ring
200 The value of this buffer-local variable is the list of saved former
201 marks of the current buffer, most recent first.
204 => (#<marker at 11050 in markers.texi>
205 #<marker at 10832 in markers.texi>
208 - User Option: mark-ring-max
209 The value of this variable is the maximum size of `mark-ring'. If
210 more marks than this are pushed onto the `mark-ring', `push-mark'
211 discards an old mark when it adds a new one.
213 In additional to a per-buffer mark ring, there is a "global mark
214 ring". Marks are pushed onto the global mark ring the first time you
215 set a mark after switching buffers.
217 - Variable: global-mark-ring
218 The value of this variable is the list of saved former global
219 marks, most recent first.
221 - User Option: mark-ring-max
222 The value of this variable is the maximum size of
223 `global-mark-ring'. If more marks than this are pushed onto the
224 `global-mark-ring', `push-mark' discards an old mark when it adds
227 - Command: pop-global-mark
228 This function pops a mark off the global mark ring and jumps to
232 File: lispref.info, Node: The Region, Prev: The Mark, Up: Markers
237 The text between point and the mark is known as "the region".
238 Various functions operate on text delimited by point and the mark, but
239 only those functions specifically related to the region itself are
242 When `zmacs-regions' is non-`nil' (this is the default), the concept
243 of an "active region" exists. The region is active when the
244 corresponding mark is active. Note that only one active region at a
245 time can exist--i.e. only one buffer's region is active at a time.
246 *Note The Mark::, for more information about active regions.
248 - User Option: zmacs-regions
249 If non-`nil' (the default), active regions are used. *Note The
250 Mark::, for a detailed explanation of what this means.
252 A number of functions are provided for explicitly determining the
253 bounds of the region and whether it is active. Few programs need to use
254 these functions, however. A command designed to operate on a region
255 should normally use `interactive' with the `r' specification to find
256 the beginning and end of the region. This lets other Lisp programs
257 specify the bounds explicitly as arguments and automatically respects
258 the user's setting for ZMACS-REGIONS. (*Note Interactive Codes::.)
260 - Function: region-beginning &optional buffer
261 This function returns the position of the beginning of BUFFER's
262 region (as an integer). This is the position of either point or
263 the mark, whichever is smaller. BUFFER defaults to the current
266 If the mark does not point anywhere, an error is signaled. Note
267 that this function ignores whether the region is active.
269 - Function: region-end &optional buffer
270 This function returns the position of the end of BUFFER's region
271 (as an integer). This is the position of either point or the mark,
272 whichever is larger. BUFFER defaults to the current buffer if
275 If the mark does not point anywhere, an error is signaled. Note
276 that this function ignores whether the region is active.
278 - Function: region-exists-p
279 This function is non-`nil' if the region exists. If active regions
280 are in use (i.e. `zmacs-regions' is true), this means that the
281 region is active. Otherwise, this means that the user has pushed
282 a mark in this buffer at some point in the past. If this function
283 returns `nil', a function that uses the `r' interactive
284 specification will cause an error when called interactively.
286 - Function: region-active-p
287 If `zmacs-regions' is true, this is equivalent to
288 `region-exists-p'. Otherwise, this function always returns false.
289 This function is used by commands such as
290 `fill-paragraph-or-region' and `capitalize-region-or-word', which
291 operate either on the active region or on something else (e.g. the
292 word or paragraph at point).
294 - Variable: zmacs-region-stays
295 If a command sets this variable to true, the currently active
296 region will remain activated when the command finishes. (Normally
297 the region is deactivated when each command terminates.) If
298 ZMACS-REGIONS is false, however, this has no effect. Under normal
299 circumstances, you do not need to set this; use the interactive
300 specification `_' instead, if you want the region to remain active.
302 - Function: zmacs-activate-region
303 This function activates the region in the current buffer (this is
304 equivalent to activating the current buffer's mark). This will
305 normally also highlight the text in the active region and set
306 ZMACS-REGION-STAYS to `t'. (If ZMACS-REGIONS is false, however,
307 this function has no effect.)
309 - Function: zmacs-deactivate-region
310 This function deactivates the region in the current buffer (this is
311 equivalent to deactivating the current buffer's mark). This will
312 normally also unhighlight the text in the active region and set
313 ZMACS-REGION-STAYS to `nil'. (If ZMACS-REGIONS is false, however,
314 this function has no effect.)
316 - Function: zmacs-update-region
317 This function updates the active region, if it's currently active.
318 (If there is no active region, this function does nothing.) This
319 has the effect of updating the highlighting on the text in the
320 region; but you should never need to call this except under rather
321 strange circumstances. The command loop automatically calls it
322 when appropriate. Calling this function will call the hook
323 `zmacs-update-region-hook', if the region is active.
325 - Variable: zmacs-activate-region-hook
326 This normal hook is called when a region becomes active. (Usually
327 this happens as a result of a command that activates the region,
328 such as `set-mark-command', `activate-region', or
329 `exchange-point-and-mark'.) Note that calling
330 `zmacs-activate-region' will call this hook, even if the region is
331 already active. If ZMACS-REGIONS is false, however, this hook
332 will never get called under any circumstances.
334 - Variable: zmacs-deactivate-region-hook
335 This normal hook is called when an active region becomes inactive.
336 (Calling `zmacs-deactivate-region' when the region is inactive will
337 _not_ cause this hook to be called.) If ZMACS-REGIONS is false,
338 this hook will never get called.
340 - Variable: zmacs-update-region-hook
341 This normal hook is called when an active region is "updated" by
342 `zmacs-update-region'. This normally gets called at the end of
343 each command that sets ZMACS-REGION-STAYS to `t', indicating that
344 the region should remain activated. The motion commands do this.
347 File: lispref.info, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top
352 This chapter describes the functions that deal with the text in a
353 buffer. Most examine, insert, or delete text in the current buffer,
354 often in the vicinity of point. Many are interactive. All the
355 functions that change the text provide for undoing the changes (*note
358 Many text-related functions operate on a region of text defined by
359 two buffer positions passed in arguments named START and END. These
360 arguments should be either markers (*note Markers::) or numeric
361 character positions (*note Positions::). The order of these arguments
362 does not matter; it is all right for START to be the end of the region
363 and END the beginning. For example, `(delete-region 1 10)' and
364 `(delete-region 10 1)' are equivalent. An `args-out-of-range' error is
365 signaled if either START or END is outside the accessible portion of
366 the buffer. In an interactive call, point and the mark are used for
369 Throughout this chapter, "text" refers to the characters in the
370 buffer, together with their properties (when relevant).
374 * Near Point:: Examining text in the vicinity of point.
375 * Buffer Contents:: Examining text in a general fashion.
376 * Comparing Text:: Comparing substrings of buffers.
377 * Insertion:: Adding new text to a buffer.
378 * Commands for Insertion:: User-level commands to insert text.
379 * Deletion:: Removing text from a buffer.
380 * User-Level Deletion:: User-level commands to delete text.
381 * The Kill Ring:: Where removed text sometimes is saved for later use.
382 * Undo:: Undoing changes to the text of a buffer.
383 * Maintaining Undo:: How to enable and disable undo information.
384 How to control how much information is kept.
385 * Filling:: Functions for explicit filling.
386 * Margins:: How to specify margins for filling commands.
387 * Auto Filling:: How auto-fill mode is implemented to break lines.
388 * Sorting:: Functions for sorting parts of the buffer.
389 * Columns:: Computing horizontal positions, and using them.
390 * Indentation:: Functions to insert or adjust indentation.
391 * Case Changes:: Case conversion of parts of the buffer.
392 * Text Properties:: Assigning Lisp property lists to text characters.
393 * Substitution:: Replacing a given character wherever it appears.
394 * Registers:: How registers are implemented. Accessing the text or
395 position stored in a register.
396 * Transposition:: Swapping two portions of a buffer.
397 * Change Hooks:: Supplying functions to be run when text is changed.
398 * Transformations:: MD5 and base64 support.
401 File: lispref.info, Node: Near Point, Next: Buffer Contents, Up: Text
403 Examining Text Near Point
404 =========================
406 Many functions are provided to look at the characters around point.
407 Several simple functions are described here. See also `looking-at' in
408 *Note Regexp Search::.
410 Many of these functions take an optional BUFFER argument. In all
411 such cases, the current buffer will be used if this argument is
412 omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions
413 usually did not have these optional BUFFER arguments and always
414 operated on the current buffer.)
416 - Function: char-after &optional position buffer
417 This function returns the character in the buffer at (i.e.,
418 immediately after) position POSITION. If POSITION is out of range
419 for this purpose, either before the beginning of the buffer, or at
420 or beyond the end, then the value is `nil'. The default for
421 POSITION is point. If optional argument BUFFER is `nil', the
422 current buffer is assumed.
424 In the following example, assume that the first character in the
427 (char-to-string (char-after 1))
430 - Function: char-before &optional position buffer
431 This function returns the character in the current buffer
432 immediately before position POSITION. If POSITION is out of range
433 for this purpose, either at or before the beginning of the buffer,
434 or beyond the end, then the value is `nil'. The default for
435 POSITION is point. If optional argument BUFFER is `nil', the
436 current buffer is assumed.
438 - Function: following-char &optional buffer
439 This function returns the character following point in the buffer.
440 This is similar to `(char-after (point))'. However, if point is at
441 the end of the buffer, then the result of `following-char' is 0.
442 If optional argument BUFFER is `nil', the current buffer is
445 Remember that point is always between characters, and the terminal
446 cursor normally appears over the character following point.
447 Therefore, the character returned by `following-char' is the
448 character the cursor is over.
450 In this example, point is between the `a' and the `c'.
452 ---------- Buffer: foo ----------
453 Gentlemen may cry ``Pea-!-ce! Peace!,''
454 but there is no peace.
455 ---------- Buffer: foo ----------
457 (char-to-string (preceding-char))
459 (char-to-string (following-char))
462 - Function: preceding-char &optional buffer
463 This function returns the character preceding point in the buffer.
464 See above, under `following-char', for an example. If point is at
465 the beginning of the buffer, `preceding-char' returns 0. If
466 optional argument BUFFER is `nil', the current buffer is assumed.
468 - Function: bobp &optional buffer
469 This function returns `t' if point is at the beginning of the
470 buffer. If narrowing is in effect, this means the beginning of the
471 accessible portion of the text. If optional argument BUFFER is
472 `nil', the current buffer is assumed. See also `point-min' in
475 - Function: eobp &optional buffer
476 This function returns `t' if point is at the end of the buffer.
477 If narrowing is in effect, this means the end of accessible
478 portion of the text. If optional argument BUFFER is `nil', the
479 current buffer is assumed. See also `point-max' in *Note Point::.
481 - Function: bolp &optional buffer
482 This function returns `t' if point is at the beginning of a line.
483 If optional argument BUFFER is `nil', the current buffer is
484 assumed. *Note Text Lines::. The beginning of the buffer (or its
485 accessible portion) always counts as the beginning of a line.
487 - Function: eolp &optional buffer
488 This function returns `t' if point is at the end of a line. The
489 end of the buffer is always considered the end of a line. If
490 optional argument BUFFER is `nil', the current buffer is assumed.
491 The end of the buffer (or of its accessible portion) is always
492 considered the end of a line.
495 File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text
497 Examining Buffer Contents
498 =========================
500 This section describes two functions that allow a Lisp program to
501 convert any portion of the text in the buffer into a string.
503 - Function: buffer-substring start end &optional buffer
504 - Function: buffer-string start end &optional buffer
505 These functions are equivalent and return a string containing a
506 copy of the text of the region defined by positions START and END
507 in the buffer. If the arguments are not positions in the
508 accessible portion of the buffer, `buffer-substring' signals an
509 `args-out-of-range' error. If optional argument BUFFER is `nil',
510 the current buffer is assumed.
512 If the region delineated by START and END contains duplicable
513 extents, they will be remembered in the string. *Note Duplicable
516 It is not necessary for START to be less than END; the arguments
517 can be given in either order. But most often the smaller argument
520 ---------- Buffer: foo ----------
521 This is the contents of buffer foo
523 ---------- Buffer: foo ----------
525 (buffer-substring 1 10)
527 (buffer-substring (point-max) 10)
528 => "he contents of buffer foo
532 File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text
537 This function lets you compare portions of the text in a buffer,
538 without copying them into strings first.
540 - Function: compare-buffer-substrings buffer1 start1 end1 buffer2
542 This function lets you compare two substrings of the same buffer
543 or two different buffers. The first three arguments specify one
544 substring, giving a buffer and two positions within the buffer.
545 The last three arguments specify the other substring in the same
546 way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for
549 The value is negative if the first substring is less, positive if
550 the first is greater, and zero if they are equal. The absolute
551 value of the result is one plus the index of the first differing
552 characters within the substrings.
554 This function ignores case when comparing characters if
555 `case-fold-search' is non-`nil'. It always ignores text
558 Suppose the current buffer contains the text `foobarbar
559 haha!rara!'; then in this example the two substrings are `rbar '
560 and `rara!'. The value is 2 because the first substring is greater
561 at the second character.
563 (compare-buffer-substring nil 6 11 nil 16 21)
567 File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text
572 "Insertion" means adding new text to a buffer. The inserted text
573 goes at point--between the character before point and the character
576 Insertion relocates markers that point at positions after the
577 insertion point, so that they stay with the surrounding text (*note
578 Markers::). When a marker points at the place of insertion, insertion
579 normally doesn't relocate the marker, so that it points to the
580 beginning of the inserted text; however, certain special functions such
581 as `insert-before-markers' relocate such markers to point after the
584 Some insertion functions leave point before the inserted text, while
585 other functions leave it after. We call the former insertion "after
586 point" and the latter insertion "before point".
588 If a string with non-`nil' extent data is inserted, the remembered
589 extents will also be inserted. *Note Duplicable Extents::.
591 Insertion functions signal an error if the current buffer is
594 These functions copy text characters from strings and buffers along
595 with their properties. The inserted characters have exactly the same
596 properties as the characters they were copied from. By contrast,
597 characters specified as separate arguments, not part of a string or
598 buffer, inherit their text properties from the neighboring text.
600 - Function: insert &rest args
601 This function inserts the strings and/or characters ARGS into the
602 current buffer, at point, moving point forward. In other words, it
603 inserts the text before point. An error is signaled unless all
604 ARGS are either strings or characters. The value is `nil'.
606 - Function: insert-before-markers &rest args
607 This function inserts the strings and/or characters ARGS into the
608 current buffer, at point, moving point forward. An error is
609 signaled unless all ARGS are either strings or characters. The
612 This function is unlike the other insertion functions in that it
613 relocates markers initially pointing at the insertion point, to
614 point after the inserted text.
616 - Function: insert-string string &optional buffer
617 This function inserts STRING into BUFFER before point. BUFFER
618 defaults to the current buffer if omitted. This function is
619 chiefly useful if you want to insert a string in a buffer other
620 than the current one (otherwise you could just use `insert').
622 - Function: insert-char character count &optional buffer
623 This function inserts COUNT instances of CHARACTER into BUFFER
624 before point. COUNT must be a number, and CHARACTER must be a
625 character. The value is `nil'. If optional argument BUFFER is
626 `nil', the current buffer is assumed. (In FSF Emacs, the third
627 argument is called INHERIT and refers to text properties.)
629 - Function: insert-buffer-substring from-buffer-or-name &optional
631 This function inserts a portion of buffer FROM-BUFFER-OR-NAME
632 (which must already exist) into the current buffer before point.
633 The text inserted is the region from START and END. (These
634 arguments default to the beginning and end of the accessible
635 portion of that buffer.) This function returns `nil'.
637 In this example, the form is executed with buffer `bar' as the
638 current buffer. We assume that buffer `bar' is initially empty.
640 ---------- Buffer: foo ----------
641 We hold these truths to be self-evident, that all
642 ---------- Buffer: foo ----------
644 (insert-buffer-substring "foo" 1 20)
647 ---------- Buffer: bar ----------
648 We hold these truth-!-
649 ---------- Buffer: bar ----------
652 File: lispref.info, Node: Commands for Insertion, Next: Deletion, Prev: Insertion, Up: Text
654 User-Level Insertion Commands
655 =============================
657 This section describes higher-level commands for inserting text,
658 commands intended primarily for the user but useful also in Lisp
661 - Command: insert-buffer from-buffer-or-name
662 This command inserts the entire contents of FROM-BUFFER-OR-NAME
663 (which must exist) into the current buffer after point. It leaves
664 the mark after the inserted text. The value is `nil'.
666 - Command: self-insert-command count
667 This command inserts the last character typed; it does so COUNT
668 times, before point, and returns `nil'. Most printing characters
669 are bound to this command. In routine use, `self-insert-command'
670 is the most frequently called function in XEmacs, but programs
671 rarely use it except to install it on a keymap.
673 In an interactive call, COUNT is the numeric prefix argument.
675 This command calls `auto-fill-function' whenever that is non-`nil'
676 and the character inserted is a space or a newline (*note Auto
679 This command performs abbrev expansion if Abbrev mode is enabled
680 and the inserted character does not have word-constituent syntax.
681 (*Note Abbrevs::, and *Note Syntax Class Table::.)
683 This is also responsible for calling `blink-paren-function' when
684 the inserted character has close parenthesis syntax (*note
687 - Command: newline &optional number-of-newlines
688 This command inserts newlines into the current buffer before point.
689 If NUMBER-OF-NEWLINES is supplied, that many newline characters
692 This function calls `auto-fill-function' if the current column
693 number is greater than the value of `fill-column' and
694 NUMBER-OF-NEWLINES is `nil'. Typically what `auto-fill-function'
695 does is insert a newline; thus, the overall result in this case is
696 to insert two newlines at different places: one at point, and
697 another earlier in the line. `newline' does not auto-fill if
698 NUMBER-OF-NEWLINES is non-`nil'.
700 This command indents to the left margin if that is not zero.
703 The value returned is `nil'. In an interactive call, COUNT is the
704 numeric prefix argument.
706 - Command: split-line
707 This command splits the current line, moving the portion of the
708 line after point down vertically so that it is on the next line
709 directly below where it was before. Whitespace is inserted as
710 needed at the beginning of the lower line, using the `indent-to'
711 function. `split-line' returns the position of point.
713 Programs hardly ever use this function.
715 - Variable: overwrite-mode
716 This variable controls whether overwrite mode is in effect: a
717 non-`nil' value enables the mode. It is automatically made
718 buffer-local when set in any fashion.
721 File: lispref.info, Node: Deletion, Next: User-Level Deletion, Prev: Commands for Insertion, Up: Text
726 Deletion means removing part of the text in a buffer, without saving
727 it in the kill ring (*note The Kill Ring::). Deleted text can't be
728 yanked, but can be reinserted using the undo mechanism (*note Undo::).
729 Some deletion functions do save text in the kill ring in some special
732 All of the deletion functions operate on the current buffer, and all
733 return a value of `nil'.
735 - Function: erase-buffer &optional buffer
736 This function deletes the entire text of BUFFER, leaving it empty.
737 If the buffer is read-only, it signals a `buffer-read-only'
738 error. Otherwise, it deletes the text without asking for any
739 confirmation. It returns `nil'. BUFFER defaults to the current
742 Normally, deleting a large amount of text from a buffer inhibits
743 further auto-saving of that buffer "because it has shrunk".
744 However, `erase-buffer' does not do this, the idea being that the
745 future text is not really related to the former text, and its size
746 should not be compared with that of the former text.
748 - Command: delete-region start end &optional buffer
749 This command deletes the text in BUFFER in the region defined by
750 START and END. The value is `nil'. If optional argument BUFFER
751 is `nil', the current buffer is assumed.
753 - Command: delete-char count &optional killp
754 This command deletes COUNT characters directly after point, or
755 before point if COUNT is negative. If KILLP is non-`nil', then it
756 saves the deleted characters in the kill ring.
758 In an interactive call, COUNT is the numeric prefix argument, and
759 KILLP is the unprocessed prefix argument. Therefore, if a prefix
760 argument is supplied, the text is saved in the kill ring. If no
761 prefix argument is supplied, then one character is deleted, but
762 not saved in the kill ring.
764 The value returned is always `nil'.
766 - Command: delete-backward-char count &optional killp
767 This command deletes COUNT characters directly before point, or
768 after point if COUNT is negative. If KILLP is non-`nil', then it
769 saves the deleted characters in the kill ring.
771 In an interactive call, COUNT is the numeric prefix argument, and
772 KILLP is the unprocessed prefix argument. Therefore, if a prefix
773 argument is supplied, the text is saved in the kill ring. If no
774 prefix argument is supplied, then one character is deleted, but
775 not saved in the kill ring.
777 The value returned is always `nil'.
779 - Command: backward-delete-char-untabify count &optional killp
780 This command deletes COUNT characters backward, changing tabs into
781 spaces. When the next character to be deleted is a tab, it is
782 first replaced with the proper number of spaces to preserve
783 alignment and then one of those spaces is deleted instead of the
784 tab. If KILLP is non-`nil', then the command saves the deleted
785 characters in the kill ring.
787 Conversion of tabs to spaces happens only if COUNT is positive.
788 If it is negative, exactly -COUNT characters after point are
791 In an interactive call, COUNT is the numeric prefix argument, and
792 KILLP is the unprocessed prefix argument. Therefore, if a prefix
793 argument is supplied, the text is saved in the kill ring. If no
794 prefix argument is supplied, then one character is deleted, but
795 not saved in the kill ring.
797 The value returned is always `nil'.
800 File: lispref.info, Node: User-Level Deletion, Next: The Kill Ring, Prev: Deletion, Up: Text
802 User-Level Deletion Commands
803 ============================
805 This section describes higher-level commands for deleting text,
806 commands intended primarily for the user but useful also in Lisp
809 - Command: delete-horizontal-space
810 This function deletes all spaces and tabs around point. It returns
813 In the following examples, we call `delete-horizontal-space' four
814 times, once on each line, with point between the second and third
815 characters on the line each time.
817 ---------- Buffer: foo ----------
822 ---------- Buffer: foo ----------
824 (delete-horizontal-space) ; Four times.
827 ---------- Buffer: foo ----------
832 ---------- Buffer: foo ----------
834 - Command: delete-indentation &optional join-following-p
835 This function joins the line point is on to the previous line,
836 deleting any whitespace at the join and in some cases replacing it
837 with one space. If JOIN-FOLLOWING-P is non-`nil',
838 `delete-indentation' joins this line to the following line
839 instead. The value is `nil'.
841 If there is a fill prefix, and the second of the lines being joined
842 starts with the prefix, then `delete-indentation' deletes the fill
843 prefix before joining the lines. *Note Margins::.
845 In the example below, point is located on the line starting
846 `events', and it makes no difference if there are trailing spaces
847 in the preceding line.
849 ---------- Buffer: foo ----------
850 When in the course of human
851 -!- events, it becomes necessary
852 ---------- Buffer: foo ----------
857 ---------- Buffer: foo ----------
858 When in the course of human-!- events, it becomes necessary
859 ---------- Buffer: foo ----------
861 After the lines are joined, the function `fixup-whitespace' is
862 responsible for deciding whether to leave a space at the junction.
864 - Function: fixup-whitespace
865 This function replaces all the white space surrounding point with
866 either one space or no space, according to the context. It
869 At the beginning or end of a line, the appropriate amount of space
870 is none. Before a character with close parenthesis syntax, or
871 after a character with open parenthesis or expression-prefix
872 syntax, no space is also appropriate. Otherwise, one space is
873 appropriate. *Note Syntax Class Table::.
875 In the example below, `fixup-whitespace' is called the first time
876 with point before the word `spaces' in the first line. For the
877 second invocation, point is directly after the `('.
879 ---------- Buffer: foo ----------
880 This has too many -!-spaces
881 This has too many spaces at the start of (-!- this list)
882 ---------- Buffer: foo ----------
889 ---------- Buffer: foo ----------
890 This has too many spaces
891 This has too many spaces at the start of (this list)
892 ---------- Buffer: foo ----------
894 - Command: just-one-space
895 This command replaces any spaces and tabs around point with a
896 single space. It returns `nil'.
898 - Command: delete-blank-lines
899 This function deletes blank lines surrounding point. If point is
900 on a blank line with one or more blank lines before or after it,
901 then all but one of them are deleted. If point is on an isolated
902 blank line, then it is deleted. If point is on a nonblank line,
903 the command deletes all blank lines following it.
905 A blank line is defined as a line containing only tabs and spaces.
907 `delete-blank-lines' returns `nil'.
910 File: lispref.info, Node: The Kill Ring, Next: Undo, Prev: User-Level Deletion, Up: Text
915 "Kill" functions delete text like the deletion functions, but save
916 it so that the user can reinsert it by "yanking". Most of these
917 functions have `kill-' in their name. By contrast, the functions whose
918 names start with `delete-' normally do not save text for yanking
919 (though they can still be undone); these are "deletion" functions.
921 Most of the kill commands are primarily for interactive use, and are
922 not described here. What we do describe are the functions provided for
923 use in writing such commands. You can use these functions to write
924 commands for killing text. When you need to delete text for internal
925 purposes within a Lisp function, you should normally use deletion
926 functions, so as not to disturb the kill ring contents. *Note
929 Killed text is saved for later yanking in the "kill ring". This is
930 a list that holds a number of recent kills, not just the last text
931 kill. We call this a "ring" because yanking treats it as having
932 elements in a cyclic order. The list is kept in the variable
933 `kill-ring', and can be operated on with the usual functions for lists;
934 there are also specialized functions, described in this section, that
937 Some people think this use of the word "kill" is unfortunate, since
938 it refers to operations that specifically _do not_ destroy the entities
939 "killed". This is in sharp contrast to ordinary life, in which death
940 is permanent and "killed" entities do not come back to life.
941 Therefore, other metaphors have been proposed. For example, the term
942 "cut ring" makes sense to people who, in pre-computer days, used
943 scissors and paste to cut up and rearrange manuscripts. However, it
944 would be difficult to change the terminology now.
948 * Kill Ring Concepts:: What text looks like in the kill ring.
949 * Kill Functions:: Functions that kill text.
950 * Yank Commands:: Commands that access the kill ring.
951 * Low-Level Kill Ring:: Functions and variables for kill ring access.
952 * Internals of Kill Ring:: Variables that hold kill-ring data.
955 File: lispref.info, Node: Kill Ring Concepts, Next: Kill Functions, Up: The Kill Ring
960 The kill ring records killed text as strings in a list, most recent
961 first. A short kill ring, for example, might look like this:
963 ("some text" "a different piece of text" "even older text")
965 When the list reaches `kill-ring-max' entries in length, adding a new
966 entry automatically deletes the last entry.
968 When kill commands are interwoven with other commands, each kill
969 command makes a new entry in the kill ring. Multiple kill commands in
970 succession build up a single entry in the kill ring, which would be
971 yanked as a unit; the second and subsequent consecutive kill commands
972 add text to the entry made by the first one.
974 For yanking, one entry in the kill ring is designated the "front" of
975 the ring. Some yank commands "rotate" the ring by designating a
976 different element as the "front." But this virtual rotation doesn't
977 change the list itself--the most recent entry always comes first in the
981 File: lispref.info, Node: Kill Functions, Next: Yank Commands, Prev: Kill Ring Concepts, Up: The Kill Ring
983 Functions for Killing
984 ---------------------
986 `kill-region' is the usual subroutine for killing text. Any command
987 that calls this function is a "kill command" (and should probably have
988 `kill' in its name). `kill-region' puts the newly killed text in a new
989 element at the beginning of the kill ring or adds it to the most recent
990 element. It uses the `last-command' variable to determine whether the
991 previous command was a kill command, and if so appends the killed text
992 to the most recent entry.
994 - Command: kill-region start end
995 This function kills the text in the region defined by START and
996 END. The text is deleted but saved in the kill ring, along with
997 its text properties. The value is always `nil'.
999 In an interactive call, START and END are point and the mark.
1001 If the buffer is read-only, `kill-region' modifies the kill ring
1002 just the same, then signals an error without modifying the buffer.
1003 This is convenient because it lets the user use all the kill
1004 commands to copy text into the kill ring from a read-only buffer.
1006 - Command: copy-region-as-kill start end
1007 This command saves the region defined by START and END on the kill
1008 ring (including text properties), but does not delete the text
1009 from the buffer. It returns `nil'. It also indicates the extent
1010 of the text copied by moving the cursor momentarily, or by
1011 displaying a message in the echo area.
1013 The command does not set `this-command' to `kill-region', so a
1014 subsequent kill command does not append to the same kill ring
1017 Don't call `copy-region-as-kill' in Lisp programs unless you aim to
1018 support Emacs 18. For Emacs 19, it is better to use `kill-new' or
1019 `kill-append' instead. *Note Low-Level Kill Ring::.
1022 File: lispref.info, Node: Yank Commands, Next: Low-Level Kill Ring, Prev: Kill Functions, Up: The Kill Ring
1024 Functions for Yanking
1025 ---------------------
1027 "Yanking" means reinserting an entry of previously killed text from
1028 the kill ring. The text properties are copied too.
1030 - Command: yank &optional arg
1031 This command inserts before point the text in the first entry in
1032 the kill ring. It positions the mark at the beginning of that
1033 text, and point at the end.
1035 If ARG is a list (which occurs interactively when the user types
1036 `C-u' with no digits), then `yank' inserts the text as described
1037 above, but puts point before the yanked text and puts the mark
1040 If ARG is a number, then `yank' inserts the ARGth most recently
1041 killed text--the ARGth element of the kill ring list.
1043 `yank' does not alter the contents of the kill ring or rotate it.
1046 - Command: yank-pop arg
1047 This command replaces the just-yanked entry from the kill ring
1048 with a different entry from the kill ring.
1050 This is allowed only immediately after a `yank' or another
1051 `yank-pop'. At such a time, the region contains text that was just
1052 inserted by yanking. `yank-pop' deletes that text and inserts in
1053 its place a different piece of killed text. It does not add the
1054 deleted text to the kill ring, since it is already in the kill
1057 If ARG is `nil', then the replacement text is the previous element
1058 of the kill ring. If ARG is numeric, the replacement is the ARGth
1059 previous kill. If ARG is negative, a more recent kill is the
1062 The sequence of kills in the kill ring wraps around, so that after
1063 the oldest one comes the newest one, and before the newest one
1066 The value is always `nil'.
1069 File: lispref.info, Node: Low-Level Kill Ring, Next: Internals of Kill Ring, Prev: Yank Commands, Up: The Kill Ring
1074 These functions and variables provide access to the kill ring at a
1075 lower level, but still convenient for use in Lisp programs. They take
1076 care of interaction with X Window selections. They do not exist in
1079 - Function: current-kill n &optional do-not-move
1080 The function `current-kill' rotates the yanking pointer which
1081 designates the "front" of the kill ring by N places (from newer
1082 kills to older ones), and returns the text at that place in the
1085 If the optional second argument DO-NOT-MOVE is non-`nil', then
1086 `current-kill' doesn't alter the yanking pointer; it just returns
1087 the Nth kill, counting from the current yanking pointer.
1089 If N is zero, indicating a request for the latest kill,
1090 `current-kill' calls the value of `interprogram-paste-function'
1091 (documented below) before consulting the kill ring.
1093 - Function: kill-new string
1094 This function puts the text STRING into the kill ring as a new
1095 entry at the front of the ring. It discards the oldest entry if
1096 appropriate. It also invokes the value of
1097 `interprogram-cut-function' (see below).
1099 - Function: kill-append string before-p
1100 This function appends the text STRING to the first entry in the
1101 kill ring. Normally STRING goes at the end of the entry, but if
1102 BEFORE-P is non-`nil', it goes at the beginning. This function
1103 also invokes the value of `interprogram-cut-function' (see below).
1105 - Variable: interprogram-paste-function
1106 This variable provides a way of transferring killed text from other
1107 programs, when you are using a window system. Its value should be
1108 `nil' or a function of no arguments.
1110 If the value is a function, `current-kill' calls it to get the
1111 "most recent kill". If the function returns a non-`nil' value,
1112 then that value is used as the "most recent kill". If it returns
1113 `nil', then the first element of `kill-ring' is used.
1115 The normal use of this hook is to get the X server's primary
1116 selection as the most recent kill, even if the selection belongs
1117 to another X client. *Note X Selections::.
1119 - Variable: interprogram-cut-function
1120 This variable provides a way of communicating killed text to other
1121 programs, when you are using a window system. Its value should be
1122 `nil' or a function of one argument.
1124 If the value is a function, `kill-new' and `kill-append' call it
1125 with the new first element of the kill ring as an argument.
1127 The normal use of this hook is to set the X server's primary
1128 selection to the newly killed text.