-\1f
-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 ----------
-
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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::.
-
-\1f
-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'.
-
-\1f
-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.
-