InfoMagic Source Code 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / gnu / elisp / elisp-22 < prev next >

Wrap

GNU Info File | 1993-05-31 | 48.7 KB | 1,221 lines

This is Info file elisp, produced by Makeinfo-1.55 from the input file elisp.texi. This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for Emacs Version 19. Published by the Free Software Foundation, 675 Massachusetts Avenue, Cambridge, MA 02139 USA Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. 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. File: elisp, Node: Skipping Characters, Prev: List Motion, Up: Motion Skipping Characters ------------------- The following two functions move point over a specified set of characters. For example, they are often used to skip whitespace. For related functions, see *Note Motion and Syntax::. - Function: skip-chars-forward CHARACTER-SET &optional LIMIT This function moves point in the current buffer forward, skipping over a given set of characters. Emacs first examines the character following point; if it matches CHARACTER-SET, then point is advanced and the next character is examined. This continues until a character is found that does not match. The function returns `nil'. The argument CHARACTER-SET is like the inside of a `[...]' in a regular expression except that `]' is never special and `\' quotes `^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters, stopping before the first nonletter, and `"^a-zA-Z'" skips nonletters stopping before the first letter. *Note Regular Expressions::. If LIMIT is supplied (it must be a number or a marker), it specifies the maximum position in the buffer that point can be skipped to. Point will stop at or before LIMIT. In the following example, point is initially located directly before the `T'. After the form is evaluated, point is located at the end of that line (between the `t' of `hat' and the newline). The function skips all letters and spaces, but not newlines. ---------- Buffer: foo ---------- I read "-!-The cat in the hat comes back" twice. ---------- Buffer: foo ---------- (skip-chars-forward "a-zA-Z ") => nil ---------- Buffer: foo ---------- I read "The cat in the hat-!- comes back" twice. ---------- Buffer: foo ---------- - Function: skip-chars-backward CHARACTER-SET &optional LIMIT This function moves point backward, skipping characters that match CHARACTER-SET. It just like `skip-chars-forward' except for the direction of motion. File: elisp, Node: Excursions, Next: Narrowing, Prev: Motion, Up: Positions Excursions ========== It is often useful to move point "temporarily" within a localized portion of the program, or to switch buffers temporarily. This is called an "excursion", and it is done with the `save-excursion' special form. This construct saves the current buffer and its values of point and the mark so they can be restored after the completion of the excursion. The forms for saving and restoring the configuration of windows are described elsewhere (see *Note Window Configurations::, and *note Frame Configurations::.). - Special Form: save-excursion FORMS... The `save-excursion' special form saves the identity of the current buffer and the values of point and the mark in it, evaluates FORMS, and finally restores the buffer and its saved values of point and the mark. All three saved values are restored even in case of an abnormal exit via throw or error (*note Nonlocal Exits::.). The `save-excursion' special form is the standard way to switch buffers or move point within one part of a program and avoid affecting the rest of the program. It is used more than 500 times in the Lisp sources of Emacs. The values of point and the mark for other buffers are not saved by `save-excursion', so any changes made to point and the mark in the other buffers will remain in effect after `save-excursion' exits. Likewise, `save-excursion' does not restore window-buffer correspondences altered by functions such as `switch-to-buffer'. One way to restore these correspondences, and the selected window, is to use `save-window-excursion' inside `save-excursion' (*note Window Configurations::.). The value returned by `save-excursion' is the result of the last of FORMS, or `nil' if no FORMS are given. (save-excursion FORMS) == (let ((old-buf (current-buffer)) (old-pnt (point-marker)) (old-mark (copy-marker (mark-marker)))) (unwind-protect (progn FORMS) (set-buffer old-buf) (goto-char old-pnt) (set-marker (mark-marker) old-mark))) File: elisp, Node: Narrowing, Prev: Excursions, Up: Positions Narrowing ========= "Narrowing" means limiting the text addressable by Emacs editing commands to a limited range of characters in a buffer. The text that remains addressable is called the "accessible portion" of the buffer. Narrowing is specified with two buffer positions which become the beginning and end of the accessible portion. For most editing commands these positions replace the values of the beginning and end of the buffer. While narrowing is in effect, no text outside the accessible portion is displayed, and point cannot move outside the accessible portion. Values such as positions or line numbers which usually count from the beginning of the buffer continue to do so, but the functions which use them will refuse to operate on text that is inaccessible. The commands for saving buffers are unaffected by narrowing; the entire buffer is saved regardless of the any narrowing. - Command: narrow-to-region START END This function sets the accessible portion of the current buffer to start at START and end at END. Both arguments should be character positions. In an interactive call, START and END are set to the bounds of the current region (point and the mark, with the smallest first). - Command: narrow-to-page MOVE-COUNT This function sets the accessible portion of the current buffer to include just the current page. An optional first argument MOVE-COUNT non-`nil' means to move forward or backward by MOVE-COUNT pages and then narrow. In an interactive call, MOVE-COUNT is set to the numeric prefix argument. - Command: widen This function cancels any narrowing in the current buffer, so that the entire contents are accessible. This is called "widening". It is equivalent to the following expression: (narrow-to-region 1 (1+ (buffer-size))) - Special Form: save-restriction BODY... This special form saves the current bounds of the accessible portion, evaluates the BODY forms, and finally restores the saved bounds, thus restoring the same state of narrowing (or absence thereof) formerly in effect. The state of narrowing is restored even in the event of an abnormal exit via throw or error (*note Nonlocal Exits::.). Therefore, this construct is a clean way to narrow a buffer temporarily. The value returned by `save-restriction' is that returned by the last form in BODY, or `nil' if no body forms were given. *Caution:* it is easy to make a mistake when using the `save-restriction' function. Read the entire description here before you try it. If BODY changes the current buffer, `save-restriction' still restores the restrictions on the original buffer (the buffer they came from), but it does not restore the identity of the current buffer. Point and the mark are *not* restored by this special form; use `save-excursion' for that. If you use both `save-restriction' and `save-excursion' together, `save-excursion' should come first (on the outside). Otherwise, the old point value would be restored with temporary narrowing still in effect. If the old point value were outside the limits of the temporary narrowing, this would fail to restore it accurately. The `save-restriction' special form records the values of the beginning and end of the accessible portion as distances from the beginning and end of the buffer. In other words, it records the amount of inaccessible text before and after the accessible portion. This technique yields correct results if BODY does further narrowing. However, `save-restriction' can become confused if they widen and then make changes outside the area of the saved narrowing. When this is what you want to do, `save-restriction' is not the right tool for the job. Here is what you must use instead: (let ((beg (point-min-marker)) (end (point-max-marker))) (unwind-protect (progn BODY) (save-excursion (set-buffer (marker-buffer beg)) (narrow-to-region beg end)))) Here is a simple example of correct use of `save-restriction': ---------- Buffer: foo ---------- This is the contents of foo This is the contents of foo This is the contents of foo-!- ---------- Buffer: foo ---------- (save-excursion (save-restriction (goto-char 1) (forward-line 2) (narrow-to-region 1 (point)) (goto-char (point-min)) (replace-string "foo" "bar"))) ---------- Buffer: foo ---------- This is the contents of bar This is the contents of bar This is the contents of foo-!- ---------- Buffer: foo ---------- File: elisp, Node: Markers, Next: Text, Prev: Positions, Up: Top Markers ******* A "marker" is a Lisp object used to specify a position in a buffer relative to the surrounding text. A marker changes its offset from the beginning of the buffer automatically whenever text is inserted or deleted, so that it stays with the two characters on either side of it. * Menu: * Overview of Markers:: The components of a marker, and how it relocates. * Predicates on Markers:: Testing whether an object is a marker. * Creating Markers:: Making empty markers or markers at certain places. * Information from Markers:: Finding the marker's buffer or character position. * Changing Markers:: Moving the marker to a new buffer or position. * The Mark:: How "the mark" is implemented with a marker. * The Region:: How to access "the region". File: elisp, Node: Overview of Markers, Next: Predicates on Markers, Prev: Markers, Up: Markers Overview of Markers =================== A marker specifies a buffer and a position in that buffer. The marker can be used to represent a position in the functions that require one, just as an integer could be used. *Note Positions::, for a complete description of positions. A marker has two attributes: the marker position, and the marker buffer. The marker position is an integer which is equivalent (at the moment) to the marker as a position in that buffer; however, as text is inserted or deleted in the buffer, the marker is relocated, so that its integer equivalent changes. The idea is that a marker positioned between two characters in a buffer will remain between those two characters despite any changes made to the contents of the buffer; thus, a marker's offset from the beginning of a buffer may change often during the life of the marker. If the text around a marker is deleted, the marker is repositioned between the characters immediately before and after the deleted text. If text is inserted at the position of a marker, the marker remains in front of the new text unless it is inserted with `insert-before-markers' (*note Insertion::.). When text is inserted or deleted somewhere before the marker position (not next to the marker), the marker moves back and forth with the two neighboring characters. When a buffer is modified, all of its markers must be checked so that they can be relocated if necessary. This slows processing in a buffer with a large number of markers. For this reason, it is a good idea to make a marker point nowhere if you are sure you don't need it any more. Unreferenced markers will eventually be garbage collected, but until then will continue to be updated if they do point somewhere. Because it is quite common to perform arithmetic operations on a marker position, most of the arithmetic operations (including `+' and `-') accept markers as arguments. In such cases, the current position of the marker is used. Here are examples of creating markers, setting markers, and moving point to markers: ;; Make a new marker that initially does not point anywhere: (setq m1 (make-marker)) => #<marker in no buffer> ;; Set `m1' to point between the 100th and 101st characters ;; in the current buffer: (set-marker m1 100) => #<marker at 100 in markers.texi> ;; Now insert one character at the beginning of the buffer: (goto-char (point-min)) => 1 (insert "Q") => nil ;; `m1' is updated appropriately. m1 => #<marker at 101 in markers.texi> ;; Two markers that point to the same position ;; are not `eq', but they are `equal'. (setq m2 (copy-marker m1)) => #<marker at 101 in markers.texi> (eq m1 m2) => nil (equal m1 m2) => t ;; When you are finished using a marker, make it point nowhere. (set-marker m1 nil) => #<marker in no buffer> File: elisp, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers Predicates on Markers ===================== You can test an object to see whether it is a marker, or whether it is either an integer or a marker. The latter test is useful when you are using the arithmetic functions that work with both markers and integers. - Function: markerp OBJECT This function returns `t' if OBJECT is a marker, `nil' otherwise. In particular, integers are not markers, even though many functions will accept either a marker or an integer. - Function: integer-or-marker-p OBJECT This function returns `t' if OBJECT is an integer or a marker, `nil' otherwise. - Function: number-or-marker-p OBJECT This function returns `t' if OBJECT is a number (of any type) or a marker, `nil' otherwise. File: elisp, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers Functions That Create Markers ============================= When you create a new marker, you can make it point nowhere, or point to the present position of point, or to the beginning or end of the accessible portion of the buffer, or to the same place as another given marker. - Function: make-marker This functions returns a newly allocated marker that does not point anywhere. (make-marker) => #<marker in no buffer> - Function: point-marker This function returns a new marker that points to the present position of point in the current buffer. *Note Point::. For an example, see `copy-marker', below. - Function: point-min-marker This function returns a new marker that points to the beginning of the accessible portion of the buffer. This will be the beginning of the buffer unless narrowing is in effect. *Note Narrowing::. - Function: point-max-marker This function returns a new marker that points to the end of the accessible portion of the buffer. This will be the end of the buffer unless narrowing is in effect. *Note Narrowing::. Here are examples of this function and `point-min-marker', shown in a buffer containing a version of the source file for the text of this chapter. (point-min-marker) => #<marker at 1 in markers.texi> (point-max-marker) => #<marker at 15573 in markers.texi> (narrow-to-region 100 200) => nil (point-min-marker) => #<marker at 100 in markers.texi> (point-max-marker) => #<marker at 200 in markers.texi> - Function: copy-marker MARKER-OR-INTEGER If passed a marker as its argument, `copy-marker' returns a new marker that points to the same place and the same buffer as does MARKER-OR-INTEGER. If passed an integer as its argument, `copy-marker' returns a new marker that points to position MARKER-OR-INTEGER in the current buffer. If passed an argument that is an integer whose value is less than 1, `copy-marker' returns a new marker that points to the beginning of the current buffer. If passed an argument that is an integer whose value is greater than the length of the buffer, then `copy-marker' returns a new marker that points to the end of the buffer. An error is signaled if MARKER is neither a marker nor an integer. (setq p (point-marker)) => #<marker at 2139 in markers.texi> (setq q (copy-marker p)) => #<marker at 2139 in markers.texi> (eq p q) => nil (equal p q) => t (copy-marker 0) => #<marker at 1 in markers.texi> (copy-marker 20000) => #<marker at 7572 in markers.texi> File: elisp, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers Information from Markers ======================== This section describes the functions for accessing the components of a marker object. - Function: marker-position MARKER This function returns the position that MARKER points to, or `nil' if it points nowhere. - Function: marker-buffer MARKER This function returns the buffer that MARKER points into, or `nil' if it points nowhere. (setq m (make-marker)) => #<marker in no buffer> (marker-position m) => nil (marker-buffer m) => nil (set-marker m 3770 (current-buffer)) => #<marker at 3770 in markers.texi> (marker-buffer m) => #<buffer markers.texi> (marker-position m) => 3770 Two distinct markers will be found `equal' (even though not `eq') to each other if they have the same position and buffer, or if they both point nowhere. File: elisp, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers Changing Markers ================ This section describes how to change the position of an existing marker. When you do this, be sure you know whether the marker is used outside of your program, and, if so, what effects will result from moving it--otherwise, confusing things may happen in other parts of Emacs. - Function: set-marker MARKER POSITION &optional BUFFER This function moves MARKER to POSITION in BUFFER. If BUFFER is not provided, it defaults to the current buffer. If POSITION is less than 1, `set-marker' moves marker to the beginning of the buffer. If the value of POSITION is greater than the size of the buffer, `set-marker' moves marker to the end of the buffer. If POSITION is `nil' or a marker that points nowhere, then MARKER is set to point nowhere. The value returned is MARKER. (setq m (point-marker)) => #<marker at 4714 in markers.texi> (set-marker m 55) => #<marker at 55 in markers.texi> (setq b (get-buffer "foo")) => #<buffer foo> (set-marker m 0 b) => #<marker at 1 in foo> - Function: move-marker MARKER POSITION &optional BUFFER This is another name for `set-marker'. File: elisp, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers The Mark ======== A 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 TAB'. 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. Many commands are designed so that when called interactively they operate on the text between point and the mark. If you are writing such a command, don't examine the mark directly; instead, use `interactive' with the `r' specification. This will provide the values of point and the mark as arguments to the command in an interactive call, but will permit other Lisp programs to specify arguments explicitly. *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". Once the mark "exists" in a buffer, it normally never ceases to exist. However, it may become "inactive", if Transient Mark mode is enabled. The variable `mark-active', which is always local in all buffers, indicates whether the mark is active: non-`nil' means yes. A command can request deactivation of the mark upon return to the editor command loop by setting `deactivate-mark' to a non-`nil' value (but this deactivation only follows if Transient Mark mode is enabled). The main motivation for using Transient Mark mode is that this mode also enables highlighting of the region when the mark is active. *Note Emacs Display::. In addition to the mark, each buffer has a "mark ring" which is a list of markers that are the 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 mark ring may contain no more than the maximum number of entries specified by the variable `mark-ring-max'; excess entries are discarded on a first-in-first-out basis. - Function: mark &optional FORCE This function returns the position of the current buffer's mark as an integer. Normally, if the mark is inactive `mark' signals an error. However, if FORCE is non-`nil', then it returns the mark position anyway--or `nil', if the mark is not yet set for this buffer. - Function: mark-marker This function returns the current buffer's mark. This is the very marker which records the mark location inside Emacs, 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. (setq m (mark-marker)) => #<marker at 3420 in markers.texi> (set-marker m 100) => #<marker at 100 in markers.texi> (mark-marker) => #<marker at 100 in markers.texi> 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, if rather odd, results. - Function: set-mark POSITION This function sets the mark to POSITION, and activates the mark. 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 Emacs 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))). - 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 => (#<marker at 11050 in markers.texi> #<marker at 10832 in markers.texi> ...) - 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', it discards marks on a first-in, first-out basis. - Function: push-mark &optional POSITION NOMSG ACTIVATE This function sets the current buffer's mark to POSITION, and pushes a copy of the previous mark onto `mark-ring'. If POSITION is `nil', then the value of point is used. `push-mark' returns `nil'. 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 change the buffer's point, and does nothing if `mark-ring' is empty. It deactivates the mark. The return value is not useful. - User Option: transient-mark-mode This variable enables Transient Mark mode, in which every buffer-modifying primitive sets `deactivate-mark'. The consequence of this is that commands that modify the buffer normally cause the mark to become inactive. - Variable: deactivate-mark If an editor command sets this variable non-`nil', then the editor command loop deactivates the mark after the command returns. - Variable: mark-active The mark is active when this variable is non-`nil'. This variable is always local in each buffer. - Variable: activate-mark-hook - Variable: deactivate-mark-hook These normal hooks are run, respectively, when the mark becomes active and when it becomes inactive. The hook `activate-mark-hook' is also run at the end of a command if the mark is active and the region may have changed. File: elisp, 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. - Function: region-beginning This function returns the position of the beginning of the region (as an integer). This is the position of either point or the mark, whichever is smaller. If the mark does not point anywhere, an error is signaled. - Function: region-end This function returns the position of the end of the region (as an integer). This is the position of either point or the mark, whichever is larger. If the mark does not point anywhere, an error is signaled. Few programs need to use the `region-beginning' and `region-end' functions. A command designed to operate on a region should instead use `interactive' with the `r' specification, so that the same function can be called with explicit bounds arguments from programs. (*Note Interactive Codes::.) File: elisp, 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 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)' perform identically. 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. * 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. * Auto Filling:: How auto-fill mode is implemented to break lines. * Filling:: Functions for explicit filling. * Sorting:: Functions for sorting parts of the buffer. * Indentation:: Functions to insert or adjust indentation. * Columns:: Computing horizontal positions, and using them. * 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. * Underlining:: Inserting or deleting underlining-by-overstrike. * Registers:: How registers are implemented. Accessing the text or position stored in a register. * Change Hooks:: Supplying functions to be run when text is changed. File: elisp, 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::. - Function: char-after POSITION This function returns the character in the current 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'. Remember that point is always between characters, and the terminal cursor normally appears over the character following point. Therefore, the character returned by `char-after' is the character the cursor is over. In the following example, assume that the first character in the buffer is `@': (char-to-string (char-after 1)) => "@" - Function: following-char This function returns the character following point in the current 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. 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 This function returns the character preceding point in the current buffer. See above, under `following-char', for an example. If point is at the beginning of the buffer, then the result of `preceding-char' is 0. - Function: bobp 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. See also `point-min' in *Note Point::. - Function: eobp 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. See also `point-max' in *Note Point::. - Function: bolp This function returns `t' if point is at the beginning of a line. *Note Text Lines::. - Function: eolp 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. File: elisp, 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 This function returns a string containing a copy of the text of the region defined by positions START and END in the current buffer. If the arguments are not positions in the accessible portion of the buffer, Emacs signals an `args-out-of-range' error. 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 " - Function: buffer-string This function returns the contents of the accessible portion of the current buffer as a string. This is the portion between `(point-min)' and `(point-max)' (*note Narrowing::.). ---------- Buffer: foo ---------- This is the contents of buffer foo ---------- Buffer: foo ---------- (buffer-string) => "This is the contents of buffer foo " File: elisp, 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'. 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 This function does not exist in Emacs version 18 and earlier. File: elisp, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text Insertion ========= Insertion takes place at point. Markers pointing at positions after the insertion point are relocated with the surrounding text (*note Markers::.). When a marker points at the place of insertion, it is normally not relocated, so that it points to the beginning of the inserted text; however, when `insert-before-markers' is used, all such markers are relocated to point after the inserted text. Point may end up either before or after inserted text, depending on the function used. If point is left after the inserted text, we speak of insertion "before point". Each of these functions signals an error if the current buffer is read-only. - Function: insert &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'. - 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 a marker whose position initially equals point is relocated to come after the newly inserted text. - Function: insert-char CHARACTER COUNT This function inserts COUNT instances of CHARACTER into the current buffer before point. COUNT must be a number, and CHARACTER must be a character. The value is `nil'. - Function: insert-buffer-substring FROM-BUFFER-OR-NAME &optional START END This function inserts a substring of the contents of buffer FROM-BUFFER-OR-NAME (which must already exist) into the current buffer before point. The text inserted consists of the characters in the region defined by START and END (These arguments default to the beginning and end of the accessible portion of that buffer). The 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: elisp, 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 function 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 function inserts the last character typed COUNT times and returns `nil'. Most printing characters are bound to this command. In routine use, `self-insert-command' is the most frequently called function in Emacs, but programs rarely use it except to install it on a keymap. In an interactive call, COUNT is the numeric prefix argument. This function calls `auto-fill-function' if the current column number is greater than the value of `fill-column' and the character inserted is a space (*note Auto Filling::.). This function 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 function 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 function inserts newlines into the current buffer before point. If NUMBER-OF-NEWLINES is supplied, that many newline characters are inserted. In Auto Fill mode, `newline' can break the preceding line if NUMBER-OF-NEWLINES is not supplied. When this happens, it actually inserts 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'. The value returned is `nil'. In an interactive call, COUNT is the numeric prefix argument. - Command: split-line This function 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: elisp, Node: Deletion, Next: User-Level Deletion, Prev: Commands for Insertion, Up: Text Deletion of Text ================ All of the deletion functions operate on the current buffer, and all return a value of `nil'. In addition to these functions, you can also delete text using the "kill" functions that save it in the kill ring; some of these functions save text in the kill ring in some cases but not in the usual case. *Note The Kill Ring::. - Function: erase-buffer This function deletes the entire text of the current 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. The value is always `nil'. 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 This function deletes the text in the current buffer in the region defined by START and END. The value is `nil'. - Command: delete-char COUNT &optional KILLP This function 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 function 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 function 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. If COUNT is negative, then tabs are not changed to spaces, and the characters are deleted by calling `delete-backward-char' with COUNT. 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: elisp, 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, assume that `delete-horizontal-space' is called four times, once on each line, with point between the second and third characters on the line. ---------- 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. 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 white space between the objects on either side of point with either one space or no space as appropriate. It returns `nil'. The appropriate amount of space is none at the beginning or end of the line. Otherwise, it is one space except when point is before a character with close parenthesis syntax or after a character with open parenthesis or expression-prefix syntax. *Note Syntax Class Table::. In the example below, when `fixup-whitespace' is called the first time, point is before the word `spaces' in the first line. It is located directly after the `(' for the second invocation. ---------- 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'.