This is ../info/lispref.info, produced by makeinfo version 4.0 from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY * Lispref: (lispref). XEmacs Lisp Reference Manual. END-INFO-DIR-ENTRY Edition History: GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May, November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. Copyright (C) 1995, 1996 Ben Wing. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.  File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers The Mark ======== One special marker in each buffer is designated "the mark". It records a position for the user for the sake of commands such as `C-w' and `C-x '. Lisp programs should set the mark only to values that have a potential use to the user, and never for their own internal purposes. For example, the `replace-regexp' command sets the mark to the value of point before doing any replacements, because this enables the user to move back there conveniently after the replace is finished. Once the mark "exists" in a buffer, it normally never ceases to exist. However, it may become "inactive", and usually does so after each command (other than simple motion commands and some commands that explicitly activate the mark). When the mark is active, the region between point and the mark is called the "active region" and is highlighted specially. Many commands are designed so that when called interactively they operate on the text between point and the mark. Such commands work only when an active region exists, i.e. when the mark is active. (The reason for this is to prevent you from accidentally deleting or changing large chunks of your text.) If you are writing such a command, don't examine the mark directly; instead, use `interactive' with the `r' specification. This provides the values of point and the mark as arguments to the command in an interactive call, but permits other Lisp programs to specify arguments explicitly, and automatically signals an error if the command is called interactively when no active region exists. *Note Interactive Codes::. Each buffer has its own value of the mark that is independent of the value of the mark in other buffers. (When a buffer is created, the mark exists but does not point anywhere. We consider this state as "the absence of a mark in that buffer.") However, only one active region can exist at a time. Activating the mark in one buffer automatically deactivates an active mark in any other buffer. Note that the user can explicitly activate a mark at any time by using the command `activate-region' (normally bound to `M-C-z') or by using the command `exchange-point-and-mark' (normally bound to `C-x C-x'), which has the side effect of activating the mark. Some people do not like active regions, so they disable this behavior by setting the variable `zmacs-regions' to `nil'. This makes the mark always active (except when a buffer is just created and the mark points nowhere), and turns off the highlighting of the region between point and the mark. Commands that explicitly retrieve the value of the mark should make sure that they behave correctly and consistently irrespective of the setting of `zmacs-regions'; some primitives are provided to ensure this behavior. In addition to the mark, each buffer has a "mark ring" which is a list of markers containing previous values of the mark. When editing commands change the mark, they should normally save the old value of the mark on the mark ring. The variable `mark-ring-max' specifies the maximum number of entries in the mark ring; once the list becomes this long, adding a new element deletes the last element. - Function: mark &optional force buffer This function returns BUFFER's mark position as an integer. BUFFER defaults to the current buffer if omitted. If the mark is inactive, `mark' normally returns `nil'. However, if FORCE is non-`nil', then `mark' returns the mark position anyway--or `nil', if the mark is not yet set for the buffer. (Remember that if ZMACS-REGIONS is `nil', the mark is always active as long as it exists, and the FORCE argument will have no effect.) If you are using this in an editing command, you are most likely making a mistake; see the documentation of `set-mark' below. - Function: mark-marker inactive-p buffer This function returns BUFFER's mark. BUFFER defaults to the current buffer if omitted. This is the very marker that records the mark location inside XEmacs, not a copy. Therefore, changing this marker's position will directly affect the position of the mark. Don't do it unless that is the effect you want. If the mark is inactive, `mark-marker' normally returns `nil'. However, if FORCE is non-`nil', then `mark-marker' returns the mark anyway. (setq m (mark-marker)) => # (set-marker m 100) => # (mark-marker) => # Like any marker, this marker can be set to point at any buffer you like. We don't recommend that you make it point at any buffer other than the one of which it is the mark. If you do, it will yield perfectly consistent, but rather odd, results. - Function: set-mark position &optional buffer This function sets `buffer''s mark to POSITION, and activates the mark. BUFFER defaults to the current buffer if omitted. The old value of the mark is _not_ pushed onto the mark ring. *Please note:* Use this function only if you want the user to see that the mark has moved, and you want the previous mark position to be lost. Normally, when a new mark is set, the old one should go on the `mark-ring'. For this reason, most applications should use `push-mark' and `pop-mark', not `set-mark'. Novice XEmacs Lisp programmers often try to use the mark for the wrong purposes. The mark saves a location for the user's convenience. An editing command should not alter the mark unless altering the mark is part of the user-level functionality of the command. (And, in that case, this effect should be documented.) To remember a location for internal use in the Lisp program, store it in a Lisp variable. For example: (let ((beg (point))) (forward-line 1) (delete-region beg (point))). - Command: exchange-point-and-mark &optional dont-activate-region This function exchanges the positions of point and the mark. It is intended for interactive use. The mark is also activated unless DONT-ACTIVATE-REGION is non-`nil'. - Function: push-mark &optional position nomsg activate buffer This function sets BUFFER's mark to POSITION, and pushes a copy of the previous mark onto `mark-ring'. BUFFER defaults to the current buffer if omitted. If POSITION is `nil', then the value of point is used. `push-mark' returns `nil'. If the last global mark pushed was not in BUFFER, also push POSITION on the global mark ring (see below). The function `push-mark' normally _does not_ activate the mark. To do that, specify `t' for the argument ACTIVATE. A `Mark set' message is displayed unless NOMSG is non-`nil'. - Function: pop-mark This function pops off the top element of `mark-ring' and makes that mark become the buffer's actual mark. This does not move point in the buffer, and it does nothing if `mark-ring' is empty. It deactivates the mark. The return value is not meaningful. - Variable: mark-ring The value of this buffer-local variable is the list of saved former marks of the current buffer, most recent first. mark-ring => (# # ...) - User Option: mark-ring-max The value of this variable is the maximum size of `mark-ring'. If more marks than this are pushed onto the `mark-ring', `push-mark' discards an old mark when it adds a new one. In additional to a per-buffer mark ring, there is a "global mark ring". Marks are pushed onto the global mark ring the first time you set a mark after switching buffers. - Variable: global-mark-ring The value of this variable is the list of saved former global marks, most recent first. - User Option: mark-ring-max The value of this variable is the maximum size of `global-mark-ring'. If more marks than this are pushed onto the `global-mark-ring', `push-mark' discards an old mark when it adds a new one. - Command: pop-global-mark This function pops a mark off the global mark ring and jumps to that location.  File: lispref.info, Node: The Region, Prev: The Mark, Up: Markers The Region ========== The text between point and the mark is known as "the region". Various functions operate on text delimited by point and the mark, but only those functions specifically related to the region itself are described here. When `zmacs-regions' is non-`nil' (this is the default), the concept of an "active region" exists. The region is active when the corresponding mark is active. Note that only one active region at a time can exist--i.e. only one buffer's region is active at a time. *Note The Mark::, for more information about active regions. - User Option: zmacs-regions If non-`nil' (the default), active regions are used. *Note The Mark::, for a detailed explanation of what this means. A number of functions are provided for explicitly determining the bounds of the region and whether it is active. Few programs need to use these functions, however. A command designed to operate on a region should normally use `interactive' with the `r' specification to find the beginning and end of the region. This lets other Lisp programs specify the bounds explicitly as arguments and automatically respects the user's setting for ZMACS-REGIONS. (*Note Interactive Codes::.) - Function: region-beginning &optional buffer This function returns the position of the beginning of BUFFER's region (as an integer). This is the position of either point or the mark, whichever is smaller. BUFFER defaults to the current buffer if omitted. If the mark does not point anywhere, an error is signaled. Note that this function ignores whether the region is active. - Function: region-end &optional buffer This function returns the position of the end of BUFFER's region (as an integer). This is the position of either point or the mark, whichever is larger. BUFFER defaults to the current buffer if omitted. If the mark does not point anywhere, an error is signaled. Note that this function ignores whether the region is active. - Function: region-exists-p This function is non-`nil' if the region exists. If active regions are in use (i.e. `zmacs-regions' is true), this means that the region is active. Otherwise, this means that the user has pushed a mark in this buffer at some point in the past. If this function returns `nil', a function that uses the `r' interactive specification will cause an error when called interactively. - Function: region-active-p If `zmacs-regions' is true, this is equivalent to `region-exists-p'. Otherwise, this function always returns false. This function is used by commands such as `fill-paragraph-or-region' and `capitalize-region-or-word', which operate either on the active region or on something else (e.g. the word or paragraph at point). - Variable: zmacs-region-stays If a command sets this variable to true, the currently active region will remain activated when the command finishes. (Normally the region is deactivated when each command terminates.) If ZMACS-REGIONS is false, however, this has no effect. Under normal circumstances, you do not need to set this; use the interactive specification `_' instead, if you want the region to remain active. - Function: zmacs-activate-region This function activates the region in the current buffer (this is equivalent to activating the current buffer's mark). This will normally also highlight the text in the active region and set ZMACS-REGION-STAYS to `t'. (If ZMACS-REGIONS is false, however, this function has no effect.) - Function: zmacs-deactivate-region This function deactivates the region in the current buffer (this is equivalent to deactivating the current buffer's mark). This will normally also unhighlight the text in the active region and set ZMACS-REGION-STAYS to `nil'. (If ZMACS-REGIONS is false, however, this function has no effect.) - Function: zmacs-update-region This function updates the active region, if it's currently active. (If there is no active region, this function does nothing.) This has the effect of updating the highlighting on the text in the region; but you should never need to call this except under rather strange circumstances. The command loop automatically calls it when appropriate. Calling this function will call the hook `zmacs-update-region-hook', if the region is active. - Variable: zmacs-activate-region-hook This normal hook is called when a region becomes active. (Usually this happens as a result of a command that activates the region, such as `set-mark-command', `activate-region', or `exchange-point-and-mark'.) Note that calling `zmacs-activate-region' will call this hook, even if the region is already active. If ZMACS-REGIONS is false, however, this hook will never get called under any circumstances. - Variable: zmacs-deactivate-region-hook This normal hook is called when an active region becomes inactive. (Calling `zmacs-deactivate-region' when the region is inactive will _not_ cause this hook to be called.) If ZMACS-REGIONS is false, this hook will never get called. - Variable: zmacs-update-region-hook This normal hook is called when an active region is "updated" by `zmacs-update-region'. This normally gets called at the end of each command that sets ZMACS-REGION-STAYS to `t', indicating that the region should remain activated. The motion commands do this.  File: lispref.info, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top Text **** This chapter describes the functions that deal with the text in a buffer. Most examine, insert, or delete text in the current buffer, often in the vicinity of point. Many are interactive. All the functions that change the text provide for undoing the changes (*note Undo::). Many text-related functions operate on a region of text defined by two buffer positions passed in arguments named START and END. These arguments should be either markers (*note Markers::) or numeric character positions (*note Positions::). The order of these arguments does not matter; it is all right for START to be the end of the region and END the beginning. For example, `(delete-region 1 10)' and `(delete-region 10 1)' are equivalent. An `args-out-of-range' error is signaled if either START or END is outside the accessible portion of the buffer. In an interactive call, point and the mark are used for these arguments. Throughout this chapter, "text" refers to the characters in the buffer, together with their properties (when relevant). * Menu: * Near Point:: Examining text in the vicinity of point. * Buffer Contents:: Examining text in a general fashion. * Comparing Text:: Comparing substrings of buffers. * Insertion:: Adding new text to a buffer. * Commands for Insertion:: User-level commands to insert text. * Deletion:: Removing text from a buffer. * User-Level Deletion:: User-level commands to delete text. * The Kill Ring:: Where removed text sometimes is saved for later use. * Undo:: Undoing changes to the text of a buffer. * Maintaining Undo:: How to enable and disable undo information. How to control how much information is kept. * Filling:: Functions for explicit filling. * Margins:: How to specify margins for filling commands. * Auto Filling:: How auto-fill mode is implemented to break lines. * Sorting:: Functions for sorting parts of the buffer. * Columns:: Computing horizontal positions, and using them. * Indentation:: Functions to insert or adjust indentation. * Case Changes:: Case conversion of parts of the buffer. * Text Properties:: Assigning Lisp property lists to text characters. * Substitution:: Replacing a given character wherever it appears. * Registers:: How registers are implemented. Accessing the text or position stored in a register. * Transposition:: Swapping two portions of a buffer. * Change Hooks:: Supplying functions to be run when text is changed. * Transformations:: MD5 and base64 support.  File: lispref.info, Node: Near Point, Next: Buffer Contents, Up: Text Examining Text Near Point ========================= Many functions are provided to look at the characters around point. Several simple functions are described here. See also `looking-at' in *Note Regexp Search::. Many of these functions take an optional BUFFER argument. In all such cases, the current buffer will be used if this argument is omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions usually did not have these optional BUFFER arguments and always operated on the current buffer.) - Function: char-after &optional position buffer This function returns the character in the buffer at (i.e., immediately after) position POSITION. If POSITION is out of range for this purpose, either before the beginning of the buffer, or at or beyond the end, then the value is `nil'. The default for POSITION is point. If optional argument BUFFER is `nil', the current buffer is assumed. In the following example, assume that the first character in the buffer is `@': (char-to-string (char-after 1)) => "@" - Function: char-before &optional position buffer This function returns the character in the current buffer immediately before position POSITION. If POSITION is out of range for this purpose, either at or before the beginning of the buffer, or beyond the end, then the value is `nil'. The default for POSITION is point. If optional argument BUFFER is `nil', the current buffer is assumed. - Function: following-char &optional buffer This function returns the character following point in the buffer. This is similar to `(char-after (point))'. However, if point is at the end of the buffer, then the result of `following-char' is 0. If optional argument BUFFER is `nil', the current buffer is assumed. Remember that point is always between characters, and the terminal cursor normally appears over the character following point. Therefore, the character returned by `following-char' is the character the cursor is over. In this example, point is between the `a' and the `c'. ---------- Buffer: foo ---------- Gentlemen may cry ``Pea-!-ce! Peace!,'' but there is no peace. ---------- Buffer: foo ---------- (char-to-string (preceding-char)) => "a" (char-to-string (following-char)) => "c" - Function: preceding-char &optional buffer This function returns the character preceding point in the buffer. See above, under `following-char', for an example. If point is at the beginning of the buffer, `preceding-char' returns 0. If optional argument BUFFER is `nil', the current buffer is assumed. - Function: bobp &optional buffer This function returns `t' if point is at the beginning of the buffer. If narrowing is in effect, this means the beginning of the accessible portion of the text. If optional argument BUFFER is `nil', the current buffer is assumed. See also `point-min' in *Note Point::. - Function: eobp &optional buffer This function returns `t' if point is at the end of the buffer. If narrowing is in effect, this means the end of accessible portion of the text. If optional argument BUFFER is `nil', the current buffer is assumed. See also `point-max' in *Note Point::. - Function: bolp &optional buffer This function returns `t' if point is at the beginning of a line. If optional argument BUFFER is `nil', the current buffer is assumed. *Note Text Lines::. The beginning of the buffer (or its accessible portion) always counts as the beginning of a line. - Function: eolp &optional buffer This function returns `t' if point is at the end of a line. The end of the buffer is always considered the end of a line. If optional argument BUFFER is `nil', the current buffer is assumed. The end of the buffer (or of its accessible portion) is always considered the end of a line.  File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text Examining Buffer Contents ========================= This section describes two functions that allow a Lisp program to convert any portion of the text in the buffer into a string. - Function: buffer-substring start end &optional buffer - Function: buffer-string start end &optional buffer These functions are equivalent and return a string containing a copy of the text of the region defined by positions START and END in the buffer. If the arguments are not positions in the accessible portion of the buffer, `buffer-substring' signals an `args-out-of-range' error. If optional argument BUFFER is `nil', the current buffer is assumed. If the region delineated by START and END contains duplicable extents, they will be remembered in the string. *Note Duplicable Extents::. It is not necessary for START to be less than END; the arguments can be given in either order. But most often the smaller argument is written first. ---------- Buffer: foo ---------- This is the contents of buffer foo ---------- Buffer: foo ---------- (buffer-substring 1 10) => "This is t" (buffer-substring (point-max) 10) => "he contents of buffer foo "  File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text Comparing Text ============== This function lets you compare portions of the text in a buffer, without copying them into strings first. - Function: compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2 This function lets you compare two substrings of the same buffer or two different buffers. The first three arguments specify one substring, giving a buffer and two positions within the buffer. The last three arguments specify the other substring in the same way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for the current buffer. The value is negative if the first substring is less, positive if the first is greater, and zero if they are equal. The absolute value of the result is one plus the index of the first differing characters within the substrings. This function ignores case when comparing characters if `case-fold-search' is non-`nil'. It always ignores text properties. Suppose the current buffer contains the text `foobarbar haha!rara!'; then in this example the two substrings are `rbar ' and `rara!'. The value is 2 because the first substring is greater at the second character. (compare-buffer-substring nil 6 11 nil 16 21) => 2  File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text Inserting Text ============== "Insertion" means adding new text to a buffer. The inserted text goes at point--between the character before point and the character after point. Insertion relocates markers that point at positions after the insertion point, so that they stay with the surrounding text (*note Markers::). When a marker points at the place of insertion, insertion normally doesn't relocate the marker, so that it points to the beginning of the inserted text; however, certain special functions such as `insert-before-markers' relocate such markers to point after the inserted text. Some insertion functions leave point before the inserted text, while other functions leave it after. We call the former insertion "after point" and the latter insertion "before point". If a string with non-`nil' extent data is inserted, the remembered extents will also be inserted. *Note Duplicable Extents::. Insertion functions signal an error if the current buffer is read-only. These functions copy text characters from strings and buffers along with their properties. The inserted characters have exactly the same properties as the characters they were copied from. By contrast, characters specified as separate arguments, not part of a string or buffer, inherit their text properties from the neighboring text. - Function: insert &rest args This function inserts the strings and/or characters ARGS into the current buffer, at point, moving point forward. In other words, it inserts the text before point. An error is signaled unless all ARGS are either strings or characters. The value is `nil'. - Function: insert-before-markers &rest args This function inserts the strings and/or characters ARGS into the current buffer, at point, moving point forward. An error is signaled unless all ARGS are either strings or characters. The value is `nil'. This function is unlike the other insertion functions in that it relocates markers initially pointing at the insertion point, to point after the inserted text. - Function: insert-string string &optional buffer This function inserts STRING into BUFFER before point. BUFFER defaults to the current buffer if omitted. This function is chiefly useful if you want to insert a string in a buffer other than the current one (otherwise you could just use `insert'). - Function: insert-char character count &optional buffer This function inserts COUNT instances of CHARACTER into BUFFER before point. COUNT must be a number, and CHARACTER must be a character. The value is `nil'. If optional argument BUFFER is `nil', the current buffer is assumed. (In FSF Emacs, the third argument is called INHERIT and refers to text properties.) - Function: insert-buffer-substring from-buffer-or-name &optional start end This function inserts a portion of buffer FROM-BUFFER-OR-NAME (which must already exist) into the current buffer before point. The text inserted is the region from START and END. (These arguments default to the beginning and end of the accessible portion of that buffer.) This function returns `nil'. In this example, the form is executed with buffer `bar' as the current buffer. We assume that buffer `bar' is initially empty. ---------- Buffer: foo ---------- We hold these truths to be self-evident, that all ---------- Buffer: foo ---------- (insert-buffer-substring "foo" 1 20) => nil ---------- Buffer: bar ---------- We hold these truth-!- ---------- Buffer: bar ----------  File: lispref.info, Node: Commands for Insertion, Next: Deletion, Prev: Insertion, Up: Text User-Level Insertion Commands ============================= This section describes higher-level commands for inserting text, commands intended primarily for the user but useful also in Lisp programs. - Command: insert-buffer from-buffer-or-name This command inserts the entire contents of FROM-BUFFER-OR-NAME (which must exist) into the current buffer after point. It leaves the mark after the inserted text. The value is `nil'. - Command: self-insert-command count This command inserts the last character typed; it does so COUNT times, before point, and returns `nil'. Most printing characters are bound to this command. In routine use, `self-insert-command' is the most frequently called function in XEmacs, but programs rarely use it except to install it on a keymap. In an interactive call, COUNT is the numeric prefix argument. This command calls `auto-fill-function' whenever that is non-`nil' and the character inserted is a space or a newline (*note Auto Filling::). This command performs abbrev expansion if Abbrev mode is enabled and the inserted character does not have word-constituent syntax. (*Note Abbrevs::, and *Note Syntax Class Table::.) This is also responsible for calling `blink-paren-function' when the inserted character has close parenthesis syntax (*note Blinking::). - Command: newline &optional number-of-newlines This command inserts newlines into the current buffer before point. If NUMBER-OF-NEWLINES is supplied, that many newline characters are inserted. This function calls `auto-fill-function' if the current column number is greater than the value of `fill-column' and NUMBER-OF-NEWLINES is `nil'. Typically what `auto-fill-function' does is insert a newline; thus, the overall result in this case is to insert two newlines at different places: one at point, and another earlier in the line. `newline' does not auto-fill if NUMBER-OF-NEWLINES is non-`nil'. This command indents to the left margin if that is not zero. *Note Margins::. The value returned is `nil'. In an interactive call, COUNT is the numeric prefix argument. - Command: split-line This command splits the current line, moving the portion of the line after point down vertically so that it is on the next line directly below where it was before. Whitespace is inserted as needed at the beginning of the lower line, using the `indent-to' function. `split-line' returns the position of point. Programs hardly ever use this function. - Variable: overwrite-mode This variable controls whether overwrite mode is in effect: a non-`nil' value enables the mode. It is automatically made buffer-local when set in any fashion.  File: lispref.info, Node: Deletion, Next: User-Level Deletion, Prev: Commands for Insertion, Up: Text Deleting Text ============= Deletion means removing part of the text in a buffer, without saving it in the kill ring (*note The Kill Ring::). Deleted text can't be yanked, but can be reinserted using the undo mechanism (*note Undo::). Some deletion functions do save text in the kill ring in some special cases. All of the deletion functions operate on the current buffer, and all return a value of `nil'. - Function: erase-buffer &optional buffer This function deletes the entire text of BUFFER, leaving it empty. If the buffer is read-only, it signals a `buffer-read-only' error. Otherwise, it deletes the text without asking for any confirmation. It returns `nil'. BUFFER defaults to the current buffer if omitted. Normally, deleting a large amount of text from a buffer inhibits further auto-saving of that buffer "because it has shrunk". However, `erase-buffer' does not do this, the idea being that the future text is not really related to the former text, and its size should not be compared with that of the former text. - Command: delete-region start end &optional buffer This command deletes the text in BUFFER in the region defined by START and END. The value is `nil'. If optional argument BUFFER is `nil', the current buffer is assumed. - Command: delete-char count &optional killp This command deletes COUNT characters directly after point, or before point if COUNT is negative. If KILLP is non-`nil', then it saves the deleted characters in the kill ring. In an interactive call, COUNT is the numeric prefix argument, and KILLP is the unprocessed prefix argument. Therefore, if a prefix argument is supplied, the text is saved in the kill ring. If no prefix argument is supplied, then one character is deleted, but not saved in the kill ring. The value returned is always `nil'. - Command: delete-backward-char count &optional killp This command deletes COUNT characters directly before point, or after point if COUNT is negative. If KILLP is non-`nil', then it saves the deleted characters in the kill ring. In an interactive call, COUNT is the numeric prefix argument, and KILLP is the unprocessed prefix argument. Therefore, if a prefix argument is supplied, the text is saved in the kill ring. If no prefix argument is supplied, then one character is deleted, but not saved in the kill ring. The value returned is always `nil'. - Command: backward-delete-char-untabify count &optional killp This command deletes COUNT characters backward, changing tabs into spaces. When the next character to be deleted is a tab, it is first replaced with the proper number of spaces to preserve alignment and then one of those spaces is deleted instead of the tab. If KILLP is non-`nil', then the command saves the deleted characters in the kill ring. Conversion of tabs to spaces happens only if COUNT is positive. If it is negative, exactly -COUNT characters after point are deleted. In an interactive call, COUNT is the numeric prefix argument, and KILLP is the unprocessed prefix argument. Therefore, if a prefix argument is supplied, the text is saved in the kill ring. If no prefix argument is supplied, then one character is deleted, but not saved in the kill ring. The value returned is always `nil'.  File: lispref.info, Node: User-Level Deletion, Next: The Kill Ring, Prev: Deletion, Up: Text User-Level Deletion Commands ============================ This section describes higher-level commands for deleting text, commands intended primarily for the user but useful also in Lisp programs. - Command: delete-horizontal-space This function deletes all spaces and tabs around point. It returns `nil'. In the following examples, we call `delete-horizontal-space' four times, once on each line, with point between the second and third characters on the line each time. ---------- Buffer: foo ---------- I -!-thought I -!- thought We-!- thought Yo-!-u thought ---------- Buffer: foo ---------- (delete-horizontal-space) ; Four times. => nil ---------- Buffer: foo ---------- Ithought Ithought Wethought You thought ---------- Buffer: foo ---------- - Command: delete-indentation &optional join-following-p This function joins the line point is on to the previous line, deleting any whitespace at the join and in some cases replacing it with one space. If JOIN-FOLLOWING-P is non-`nil', `delete-indentation' joins this line to the following line instead. The value is `nil'. If there is a fill prefix, and the second of the lines being joined starts with the prefix, then `delete-indentation' deletes the fill prefix before joining the lines. *Note Margins::. In the example below, point is located on the line starting `events', and it makes no difference if there are trailing spaces in the preceding line. ---------- Buffer: foo ---------- When in the course of human -!- events, it becomes necessary ---------- Buffer: foo ---------- (delete-indentation) => nil ---------- Buffer: foo ---------- When in the course of human-!- events, it becomes necessary ---------- Buffer: foo ---------- After the lines are joined, the function `fixup-whitespace' is responsible for deciding whether to leave a space at the junction. - Function: fixup-whitespace This function replaces all the white space surrounding point with either one space or no space, according to the context. It returns `nil'. At the beginning or end of a line, the appropriate amount of space is none. Before a character with close parenthesis syntax, or after a character with open parenthesis or expression-prefix syntax, no space is also appropriate. Otherwise, one space is appropriate. *Note Syntax Class Table::. In the example below, `fixup-whitespace' is called the first time with point before the word `spaces' in the first line. For the second invocation, point is directly after the `('. ---------- Buffer: foo ---------- This has too many -!-spaces This has too many spaces at the start of (-!- this list) ---------- Buffer: foo ---------- (fixup-whitespace) => nil (fixup-whitespace) => nil ---------- Buffer: foo ---------- This has too many spaces This has too many spaces at the start of (this list) ---------- Buffer: foo ---------- - Command: just-one-space This command replaces any spaces and tabs around point with a single space. It returns `nil'. - Command: delete-blank-lines This function deletes blank lines surrounding point. If point is on a blank line with one or more blank lines before or after it, then all but one of them are deleted. If point is on an isolated blank line, then it is deleted. If point is on a nonblank line, the command deletes all blank lines following it. A blank line is defined as a line containing only tabs and spaces. `delete-blank-lines' returns `nil'.  File: lispref.info, Node: The Kill Ring, Next: Undo, Prev: User-Level Deletion, Up: Text The Kill Ring ============= "Kill" functions delete text like the deletion functions, but save it so that the user can reinsert it by "yanking". Most of these functions have `kill-' in their name. By contrast, the functions whose names start with `delete-' normally do not save text for yanking (though they can still be undone); these are "deletion" functions. Most of the kill commands are primarily for interactive use, and are not described here. What we do describe are the functions provided for use in writing such commands. You can use these functions to write commands for killing text. When you need to delete text for internal purposes within a Lisp function, you should normally use deletion functions, so as not to disturb the kill ring contents. *Note Deletion::. Killed text is saved for later yanking in the "kill ring". This is a list that holds a number of recent kills, not just the last text kill. We call this a "ring" because yanking treats it as having elements in a cyclic order. The list is kept in the variable `kill-ring', and can be operated on with the usual functions for lists; there are also specialized functions, described in this section, that treat it as a ring. Some people think this use of the word "kill" is unfortunate, since it refers to operations that specifically _do not_ destroy the entities "killed". This is in sharp contrast to ordinary life, in which death is permanent and "killed" entities do not come back to life. Therefore, other metaphors have been proposed. For example, the term "cut ring" makes sense to people who, in pre-computer days, used scissors and paste to cut up and rearrange manuscripts. However, it would be difficult to change the terminology now. * Menu: * Kill Ring Concepts:: What text looks like in the kill ring. * Kill Functions:: Functions that kill text. * Yank Commands:: Commands that access the kill ring. * Low-Level Kill Ring:: Functions and variables for kill ring access. * Internals of Kill Ring:: Variables that hold kill-ring data.  File: lispref.info, Node: Kill Ring Concepts, Next: Kill Functions, Up: The Kill Ring Kill Ring Concepts ------------------ The kill ring records killed text as strings in a list, most recent first. A short kill ring, for example, might look like this: ("some text" "a different piece of text" "even older text") When the list reaches `kill-ring-max' entries in length, adding a new entry automatically deletes the last entry. When kill commands are interwoven with other commands, each kill command makes a new entry in the kill ring. Multiple kill commands in succession build up a single entry in the kill ring, which would be yanked as a unit; the second and subsequent consecutive kill commands add text to the entry made by the first one. For yanking, one entry in the kill ring is designated the "front" of the ring. Some yank commands "rotate" the ring by designating a different element as the "front." But this virtual rotation doesn't change the list itself--the most recent entry always comes first in the list.  File: lispref.info, Node: Kill Functions, Next: Yank Commands, Prev: Kill Ring Concepts, Up: The Kill Ring Functions for Killing --------------------- `kill-region' is the usual subroutine for killing text. Any command that calls this function is a "kill command" (and should probably have `kill' in its name). `kill-region' puts the newly killed text in a new element at the beginning of the kill ring or adds it to the most recent element. It uses the `last-command' variable to determine whether the previous command was a kill command, and if so appends the killed text to the most recent entry. - Command: kill-region start end This function kills the text in the region defined by START and END. The text is deleted but saved in the kill ring, along with its text properties. The value is always `nil'. In an interactive call, START and END are point and the mark. If the buffer is read-only, `kill-region' modifies the kill ring just the same, then signals an error without modifying the buffer. This is convenient because it lets the user use all the kill commands to copy text into the kill ring from a read-only buffer. - Command: copy-region-as-kill start end This command saves the region defined by START and END on the kill ring (including text properties), but does not delete the text from the buffer. It returns `nil'. It also indicates the extent of the text copied by moving the cursor momentarily, or by displaying a message in the echo area. The command does not set `this-command' to `kill-region', so a subsequent kill command does not append to the same kill ring entry. Don't call `copy-region-as-kill' in Lisp programs unless you aim to support Emacs 18. For Emacs 19, it is better to use `kill-new' or `kill-append' instead. *Note Low-Level Kill Ring::.  File: lispref.info, Node: Yank Commands, Next: Low-Level Kill Ring, Prev: Kill Functions, Up: The Kill Ring Functions for Yanking --------------------- "Yanking" means reinserting an entry of previously killed text from the kill ring. The text properties are copied too. - Command: yank &optional arg This command inserts before point the text in the first entry in the kill ring. It positions the mark at the beginning of that text, and point at the end. If ARG is a list (which occurs interactively when the user types `C-u' with no digits), then `yank' inserts the text as described above, but puts point before the yanked text and puts the mark after it. If ARG is a number, then `yank' inserts the ARGth most recently killed text--the ARGth element of the kill ring list. `yank' does not alter the contents of the kill ring or rotate it. It returns `nil'. - Command: yank-pop arg This command replaces the just-yanked entry from the kill ring with a different entry from the kill ring. This is allowed only immediately after a `yank' or another `yank-pop'. At such a time, the region contains text that was just inserted by yanking. `yank-pop' deletes that text and inserts in its place a different piece of killed text. It does not add the deleted text to the kill ring, since it is already in the kill ring somewhere. If ARG is `nil', then the replacement text is the previous element of the kill ring. If ARG is numeric, the replacement is the ARGth previous kill. If ARG is negative, a more recent kill is the replacement. The sequence of kills in the kill ring wraps around, so that after the oldest one comes the newest one, and before the newest one goes the oldest. The value is always `nil'.  File: lispref.info, Node: Low-Level Kill Ring, Next: Internals of Kill Ring, Prev: Yank Commands, Up: The Kill Ring Low-Level Kill Ring ------------------- These functions and variables provide access to the kill ring at a lower level, but still convenient for use in Lisp programs. They take care of interaction with X Window selections. They do not exist in Emacs version 18. - Function: current-kill n &optional do-not-move The function `current-kill' rotates the yanking pointer which designates the "front" of the kill ring by N places (from newer kills to older ones), and returns the text at that place in the ring. If the optional second argument DO-NOT-MOVE is non-`nil', then `current-kill' doesn't alter the yanking pointer; it just returns the Nth kill, counting from the current yanking pointer. If N is zero, indicating a request for the latest kill, `current-kill' calls the value of `interprogram-paste-function' (documented below) before consulting the kill ring. - Function: kill-new string This function puts the text STRING into the kill ring as a new entry at the front of the ring. It discards the oldest entry if appropriate. It also invokes the value of `interprogram-cut-function' (see below). - Function: kill-append string before-p This function appends the text STRING to the first entry in the kill ring. Normally STRING goes at the end of the entry, but if BEFORE-P is non-`nil', it goes at the beginning. This function also invokes the value of `interprogram-cut-function' (see below). - Variable: interprogram-paste-function This variable provides a way of transferring killed text from other programs, when you are using a window system. Its value should be `nil' or a function of no arguments. If the value is a function, `current-kill' calls it to get the "most recent kill". If the function returns a non-`nil' value, then that value is used as the "most recent kill". If it returns `nil', then the first element of `kill-ring' is used. The normal use of this hook is to get the X server's primary selection as the most recent kill, even if the selection belongs to another X client. *Note X Selections::. - Variable: interprogram-cut-function This variable provides a way of communicating killed text to other programs, when you are using a window system. Its value should be `nil' or a function of one argument. If the value is a function, `kill-new' and `kill-append' call it with the new first element of the kill ring as an argument. The normal use of this hook is to set the X server's primary selection to the newly killed text.