2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/text
6 @node Text, Searching and Matching, Markers, Top
10 This chapter describes the functions that deal with the text in a
11 buffer. Most examine, insert, or delete text in the current buffer,
12 often in the vicinity of point. Many are interactive. All the
13 functions that change the text provide for undoing the changes
16 Many text-related functions operate on a region of text defined by two
17 buffer positions passed in arguments named @var{start} and @var{end}.
18 These arguments should be either markers (@pxref{Markers}) or numeric
19 character positions (@pxref{Positions}). The order of these arguments
20 does not matter; it is all right for @var{start} to be the end of the
21 region and @var{end} the beginning. For example, @code{(delete-region 1
22 10)} and @code{(delete-region 10 1)} are equivalent. An
23 @code{args-out-of-range} error is signaled if either @var{start} or
24 @var{end} is outside the accessible portion of the buffer. In an
25 interactive call, point and the mark are used for these arguments.
27 @cindex buffer contents
28 Throughout this chapter, ``text'' refers to the characters in the
32 * Near Point:: Examining text in the vicinity of point.
33 * Buffer Contents:: Examining text in a general fashion.
34 * Comparing Text:: Comparing substrings of buffers.
35 * Insertion:: Adding new text to a buffer.
36 * Commands for Insertion:: User-level commands to insert text.
37 * Deletion:: Removing text from a buffer.
38 * User-Level Deletion:: User-level commands to delete text.
39 * The Kill Ring:: Where removed text sometimes is saved for later use.
40 * Undo:: Undoing changes to the text of a buffer.
41 * Maintaining Undo:: How to enable and disable undo information.
42 How to control how much information is kept.
43 * Filling:: Functions for explicit filling.
44 * Auto Filling:: How auto-fill mode is implemented to break lines.
45 * Sorting:: Functions for sorting parts of the buffer.
46 * Columns:: Computing horizontal positions, and using them.
47 * Indentation:: Functions to insert or adjust indentation.
48 * Case Changes:: Case conversion of parts of the buffer.
49 * Text Properties:: Assigning Lisp property lists to text characters.
50 * Substitution:: Replacing a given character wherever it appears.
51 * Transposition:: Swapping two portions of a buffer.
52 * Registers:: How registers are implemented. Accessing the text or
53 position stored in a register.
54 * Change Hooks:: Supplying functions to be run when text is changed.
58 @section Examining Text Near Point
60 Many functions are provided to look at the characters around point.
61 Several simple functions are described here. See also @code{looking-at}
62 in @ref{Regexp Search}.
64 @defun char-after position
65 This function returns the character in the current buffer at (i.e.,
66 immediately after) position @var{position}. If @var{position} is out of
67 range for this purpose, either before the beginning of the buffer, or at
68 or beyond the end, then the value is @code{nil}.
70 In the following example, assume that the first character in the
75 (char-to-string (char-after 1))
82 This function returns the character following point in the current
83 buffer. This is similar to @code{(char-after (point))}. However, if
84 point is at the end of the buffer, then @code{following-char} returns 0.
86 Remember that point is always between characters, and the terminal
87 cursor normally appears over the character following point. Therefore,
88 the character returned by @code{following-char} is the character the
91 In this example, point is between the @samp{a} and the @samp{c}.
95 ---------- Buffer: foo ----------
96 Gentlemen may cry ``Pea@point{}ce! Peace!,''
97 but there is no peace.
98 ---------- Buffer: foo ----------
102 (char-to-string (preceding-char))
104 (char-to-string (following-char))
110 @defun preceding-char
111 This function returns the character preceding point in the current
112 buffer. See above, under @code{following-char}, for an example. If
113 point is at the beginning of the buffer, @code{preceding-char} returns
118 This function returns @code{t} if point is at the beginning of the
119 buffer. If narrowing is in effect, this means the beginning of the
120 accessible portion of the text. See also @code{point-min} in
125 This function returns @code{t} if point is at the end of the buffer.
126 If narrowing is in effect, this means the end of accessible portion of
127 the text. See also @code{point-max} in @xref{Point}.
131 This function returns @code{t} if point is at the beginning of a line.
132 @xref{Text Lines}. The beginning of the buffer (or its accessible
133 portion) always counts as the beginning of a line.
137 This function returns @code{t} if point is at the end of a line. The
138 end of the buffer (or of its accessible portion) is always considered
142 @node Buffer Contents
143 @section Examining Buffer Contents
145 This section describes two functions that allow a Lisp program to
146 convert any portion of the text in the buffer into a string.
148 @defun buffer-substring start end
149 This function returns a string containing a copy of the text of the
150 region defined by positions @var{start} and @var{end} in the current
151 buffer. If the arguments are not positions in the accessible portion of
152 the buffer, @code{buffer-substring} signals an @code{args-out-of-range}
155 It is not necessary for @var{start} to be less than @var{end}; the
156 arguments can be given in either order. But most often the smaller
157 argument is written first.
161 ---------- Buffer: foo ----------
162 This is the contents of buffer foo
164 ---------- Buffer: foo ----------
168 (buffer-substring 1 10)
169 @result{} "This is t"
172 (buffer-substring (point-max) 10)
173 @result{} "he contents of buffer foo
180 This function returns the contents of the accessible portion of the
181 current buffer as a string. This is the portion between
182 @code{(point-min)} and @code{(point-max)} (@pxref{Narrowing}).
186 ---------- Buffer: foo ----------
187 This is the contents of buffer foo
189 ---------- Buffer: foo ----------
192 @result{} "This is the contents of buffer foo
199 @section Comparing Text
200 @cindex comparing buffer text
202 This function lets you compare portions of the text in a buffer, without
203 copying them into strings first.
205 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
206 This function lets you compare two substrings of the same buffer or two
207 different buffers. The first three arguments specify one substring,
208 giving a buffer and two positions within the buffer. The last three
209 arguments specify the other substring in the same way. You can use
210 @code{nil} for @var{buffer1}, @var{buffer2}, or both to stand for the
213 The value is negative if the first substring is less, positive if the
214 first is greater, and zero if they are equal. The absolute value of
215 the result is one plus the index of the first differing characters
216 within the substrings.
218 This function ignores case when comparing characters
219 if @code{case-fold-search} is non-@code{nil}.
221 Suppose the current buffer contains the text @samp{foobarbar
222 haha!rara!}; then in this example the two substrings are @samp{rbar }
223 and @samp{rara!}. The value is 2 because the first substring is greater
224 at the second character.
227 (compare-buffer-substring nil 6 11 nil 16 21)
231 This function does not exist in Emacs version 18 and earlier.
236 @cindex insertion of text
237 @cindex text insertion
239 @dfn{Insertion} means adding new text to a buffer. The inserted text
240 goes at point---between the character before point and the character
243 Insertion relocates markers that point at positions after the
244 insertion point, so that they stay with the surrounding text
245 (@pxref{Markers}). When a marker points at the place of insertion,
246 insertion normally doesn't relocate the marker, so that it points to the
247 beginning of the inserted text; however, certain special functions such
248 as @code{insert-before-markers} relocate such markers to point after the
251 @cindex insertion before point
252 @cindex before point, insertion
253 Some insertion functions leave point before the inserted text, while
254 other functions leave it after. We call the former insertion @dfn{after
255 point} and the latter insertion @dfn{before point}.
257 Insertion functions signal an error if the current buffer is
260 @defun insert &rest args
261 This function inserts the strings and/or characters @var{args} into the
262 current buffer, at point, moving point forward. In other words, it
263 inserts the text before point. An error is signaled unless all
264 @var{args} are either strings or characters. The value is @code{nil}.
267 @defun insert-before-markers &rest args
268 This function inserts the strings and/or characters @var{args} into the
269 current buffer, at point, moving point forward. An error is signaled
270 unless all @var{args} are either strings or characters. The value is
273 This function is unlike the other insertion functions in that it
274 relocates markers initially pointing at the insertion point, to point
275 after the inserted text.
278 @defun insert-char character count &optional inherit
279 This function inserts @var{count} instances of @var{character} into the
280 current buffer before point. The argument @var{count} must be a number,
281 and @var{character} must be a character. The value is @code{nil}.
282 @c It's unfortunate that count comes second. Not like make-string, etc.
284 If @var{inherit} is non-@code{nil}, then the inserted characters inherit
285 sticky text properties from the two characters before and after the
286 insertion point. @xref{Sticky Properties}.
289 @defun insert-buffer-substring from-buffer-or-name &optional start end
290 This function inserts a portion of buffer @var{from-buffer-or-name}
291 (which must already exist) into the current buffer before point. The
292 text inserted is the region from @var{start} and @var{end}. (These
293 arguments default to the beginning and end of the accessible portion of
294 that buffer.) This function returns @code{nil}.
296 In this example, the form is executed with buffer @samp{bar} as the
297 current buffer. We assume that buffer @samp{bar} is initially empty.
301 ---------- Buffer: foo ----------
302 We hold these truths to be self-evident, that all
303 ---------- Buffer: foo ----------
307 (insert-buffer-substring "foo" 1 20)
310 ---------- Buffer: bar ----------
311 We hold these truth@point{}
312 ---------- Buffer: bar ----------
317 @xref{Sticky Properties}, for other insertion functions that inherit
318 text properties from the nearby text in addition to inserting it.
319 Whitespace inserted by indentation functions also inherits text
322 @node Commands for Insertion
323 @section User-Level Insertion Commands
325 This section describes higher-level commands for inserting text,
326 commands intended primarily for the user but useful also in Lisp
329 @deffn Command insert-buffer from-buffer-or-name
330 This command inserts the entire contents of @var{from-buffer-or-name}
331 (which must exist) into the current buffer after point. It leaves
332 the mark after the inserted text. The value is @code{nil}.
335 @deffn Command self-insert-command count
336 @cindex character insertion
337 @cindex self-insertion
338 This command inserts the last character typed; it does so @var{count}
339 times, before point, and returns @code{nil}. Most printing characters
340 are bound to this command. In routine use, @code{self-insert-command}
341 is the most frequently called function in Emacs, but programs rarely use
342 it except to install it on a keymap.
344 In an interactive call, @var{count} is the numeric prefix argument.
346 This function calls @code{auto-fill-function} if the current column number
347 is greater than the value of @code{fill-column} and the character
348 inserted is a space (@pxref{Auto Filling}).
350 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
351 This function performs abbrev expansion if Abbrev mode is enabled and
352 the inserted character does not have word-constituent
353 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
355 This function is also responsible for calling
356 @code{blink-paren-function} when the inserted character has close
357 parenthesis syntax (@pxref{Blinking}).
360 @deffn Command newline &optional number-of-newlines
361 This command inserts newlines into the current buffer before point.
362 If @var{number-of-newlines} is supplied, that many newline characters
365 @cindex newline and Auto Fill mode
366 This function calls @code{auto-fill-function} if the current column
367 number is greater than the value of @code{fill-column} and
368 @var{number-of-newlines} is @code{nil}. Typically what
369 @code{auto-fill-function} does is insert a newline; thus, the overall
370 result in this case is to insert two newlines at different places: one
371 at point, and another earlier in the line. @code{newline} does not
372 auto-fill if @var{number-of-newlines} is non-@code{nil}.
374 The value returned is @code{nil}. In an interactive call, @var{count}
375 is the numeric prefix argument.
378 @deffn Command split-line
379 This command splits the current line, moving the portion of the line
380 after point down vertically so that it is on the next line directly
381 below where it was before. Whitespace is inserted as needed at the
382 beginning of the lower line, using the @code{indent-to} function.
383 @code{split-line} returns the position of point.
385 Programs hardly ever use this function.
388 @defvar overwrite-mode
389 This variable controls whether overwrite mode is in effect: a
390 non-@code{nil} value enables the mode. It is automatically made
391 buffer-local when set in any fashion.
395 @section Deletion of Text
397 @cindex deletion vs killing
398 Deletion means removing part of the text in a buffer, without saving
399 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
400 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
401 Some deletion functions do save text in the kill ring in some special
404 All of the deletion functions operate on the current buffer, and all
405 return a value of @code{nil}.
408 This function deletes the entire text of the current buffer, leaving it
409 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
410 error. Otherwise, it deletes the text without asking for any
411 confirmation. It returns @code{nil}.
413 Normally, deleting a large amount of text from a buffer inhibits further
414 auto-saving of that buffer ``because it has shrunk''. However,
415 @code{erase-buffer} does not do this, the idea being that the future
416 text is not really related to the former text, and its size should not
417 be compared with that of the former text.
420 @deffn Command delete-region start end
421 This command deletes the text in the current buffer in the region
422 defined by @var{start} and @var{end}. The value is @code{nil}.
425 @deffn Command delete-char count &optional killp
426 This command deletes @var{count} characters directly after point, or
427 before point if @var{count} is negative. If @var{killp} is
428 non-@code{nil}, then it saves the deleted characters in the kill ring.
430 In an interactive call, @var{count} is the numeric prefix argument, and
431 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
432 argument is supplied, the text is saved in the kill ring. If no prefix
433 argument is supplied, then one character is deleted, but not saved in
436 The value returned is always @code{nil}.
439 @deffn Command delete-backward-char count &optional killp
440 @cindex delete previous char
441 This command deletes @var{count} characters directly before point, or
442 after point if @var{count} is negative. If @var{killp} is
443 non-@code{nil}, then it saves the deleted characters in the kill ring.
445 In an interactive call, @var{count} is the numeric prefix argument, and
446 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
447 argument is supplied, the text is saved in the kill ring. If no prefix
448 argument is supplied, then one character is deleted, but not saved in
451 The value returned is always @code{nil}.
454 @deffn Command backward-delete-char-untabify count &optional killp
456 This command deletes @var{count} characters backward, changing tabs
457 into spaces. When the next character to be deleted is a tab, it is
458 first replaced with the proper number of spaces to preserve alignment
459 and then one of those spaces is deleted instead of the tab. If
460 @var{killp} is non-@code{nil}, then the command saves the deleted
461 characters in the kill ring.
463 Conversion of tabs to spaces happens only if @var{count} is positive.
464 If it is negative, exactly @minus{}@var{count} characters after point
467 In an interactive call, @var{count} is the numeric prefix argument, and
468 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
469 argument is supplied, the text is saved in the kill ring. If no prefix
470 argument is supplied, then one character is deleted, but not saved in
473 The value returned is always @code{nil}.
476 @node User-Level Deletion
477 @section User-Level Deletion Commands
479 This section describes higher-level commands for deleting text,
480 commands intended primarily for the user but useful also in Lisp
483 @deffn Command delete-horizontal-space
484 @cindex deleting whitespace
485 This function deletes all spaces and tabs around point. It returns
488 In the following examples, we call @code{delete-horizontal-space} four
489 times, once on each line, with point between the second and third
490 characters on the line each time.
494 ---------- Buffer: foo ----------
499 ---------- Buffer: foo ----------
503 (delete-horizontal-space) ; @r{Four times.}
506 ---------- Buffer: foo ----------
511 ---------- Buffer: foo ----------
516 @deffn Command delete-indentation &optional join-following-p
517 This function joins the line point is on to the previous line, deleting
518 any whitespace at the join and in some cases replacing it with one
519 space. If @var{join-following-p} is non-@code{nil},
520 @code{delete-indentation} joins this line to the following line
521 instead. The value is @code{nil}.
523 If there is a fill prefix, and the second of the lines being joined
524 starts with the prefix, then @code{delete-indentation} deletes the
525 fill prefix before joining the lines. @xref{Filling}.
527 In the example below, point is located on the line starting
528 @samp{events}, and it makes no difference if there are trailing spaces
529 in the preceding line.
533 ---------- Buffer: foo ----------
534 When in the course of human
535 @point{} events, it becomes necessary
536 ---------- Buffer: foo ----------
543 ---------- Buffer: foo ----------
544 When in the course of human@point{} events, it becomes necessary
545 ---------- Buffer: foo ----------
549 After the lines are joined, the function @code{fixup-whitespace} is
550 responsible for deciding whether to leave a space at the junction.
553 @defun fixup-whitespace
554 This function replaces all the white space surrounding point with either
555 one space or no space, according to the context. It returns @code{nil}.
557 At the beginning or end of a line, the appropriate amount of space is
558 none. Before a character with close parenthesis syntax, or after a
559 character with open parenthesis or expression-prefix syntax, no space is
560 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
563 In the example below, @code{fixup-whitespace} is called the first time
564 with point before the word @samp{spaces} in the first line. For the
565 second invocation, point is directly after the @samp{(}.
569 ---------- Buffer: foo ----------
570 This has too many @point{}spaces
571 This has too many spaces at the start of (@point{} this list)
572 ---------- Buffer: foo ----------
583 ---------- Buffer: foo ----------
584 This has too many spaces
585 This has too many spaces at the start of (this list)
586 ---------- Buffer: foo ----------
591 @deffn Command just-one-space
592 @comment !!SourceFile simple.el
593 This command replaces any spaces and tabs around point with a single
594 space. It returns @code{nil}.
597 @deffn Command delete-blank-lines
598 This function deletes blank lines surrounding point. If point is on a
599 blank line with one or more blank lines before or after it, then all but
600 one of them are deleted. If point is on an isolated blank line, then it
601 is deleted. If point is on a nonblank line, the command deletes all
602 blank lines following it.
604 A blank line is defined as a line containing only tabs and spaces.
606 @code{delete-blank-lines} returns @code{nil}.
610 @section The Kill Ring
613 @dfn{Kill} functions delete text like the deletion functions, but save
614 it so that the user can reinsert it by @dfn{yanking}. Most of these
615 functions have @samp{kill-} in their name. By contrast, the functions
616 whose names start with @samp{delete-} normally do not save text for
617 yanking (though they can still be undone); these are ``deletion''
620 Most of the kill commands are primarily for interactive use, and are
621 not described here. What we do describe are the functions provided for
622 use in writing such commands. You can use these functions to write
623 commands for killing text. When you need to delete text for internal
624 purposes within a Lisp function, you should normally use deletion
625 functions, so as not to disturb the kill ring contents.
628 Killed text is saved for later yanking in the @dfn{kill ring}. This
629 is a list that holds a number of recent kills, not just the last text
630 kill. We call this a ``ring'' because yanking treats it as having
631 elements in a cyclic order. The list is kept in the variable
632 @code{kill-ring}, and can be operated on with the usual functions for
633 lists; there are also specialized functions, described in this section,
634 that treat it as a ring.
636 Some people think this use of the word ``kill'' is unfortunate, since
637 it refers to operations that specifically @emph{do not} destroy the
638 entities ``killed''. This is in sharp contrast to ordinary life, in
639 which death is permanent and ``killed'' entities do not come back to
640 life. Therefore, other metaphors have been proposed. For example, the
641 term ``cut ring'' makes sense to people who, in pre-computer days, used
642 scissors and paste to cut up and rearrange manuscripts. However, it
643 would be difficult to change the terminology now.
646 * Kill Ring Concepts:: What text looks like in the kill ring.
647 * Kill Functions:: Functions that kill text.
648 * Yank Commands:: Commands that access the kill ring.
649 * Low-Level Kill Ring:: Functions and variables for kill ring access.
650 * Internals of Kill Ring:: Variables that hold kill-ring data.
653 @node Kill Ring Concepts
654 @comment node-name, next, previous, up
655 @subsection Kill Ring Concepts
657 The kill ring records killed text as strings in a list, most recent
658 first. A short kill ring, for example, might look like this:
661 ("some text" "a different piece of text" "even older text")
665 When the list reaches @code{kill-ring-max} entries in length, adding a
666 new entry automatically deletes the last entry.
668 When kill commands are interwoven with other commands, each kill
669 command makes a new entry in the kill ring. Multiple kill commands in
670 succession build up a single entry in the kill ring, which would be
671 yanked as a unit; the second and subsequent consecutive kill commands
672 add text to the entry made by the first one.
674 For yanking, one entry in the kill ring is designated the ``front'' of
675 the ring. Some yank commands ``rotate'' the ring by designating a
676 different element as the ``front.'' But this virtual rotation doesn't
677 change the list itself---the most recent entry always comes first in the
681 @comment node-name, next, previous, up
682 @subsection Functions for Killing
684 @code{kill-region} is the usual subroutine for killing text. Any
685 command that calls this function is a ``kill command'' (and should
686 probably have @samp{kill} in its name). @code{kill-region} puts the
687 newly killed text in a new element at the beginning of the kill ring or
688 adds it to the most recent element. It uses the @code{last-command}
689 variable to determine whether the previous command was a kill command,
690 and if so appends the killed text to the most recent entry.
692 @deffn Command kill-region start end
693 This function kills the text in the region defined by @var{start} and
694 @var{end}. The text is deleted but saved in the kill ring. The value
695 is always @code{nil}.
697 In an interactive call, @var{start} and @var{end} are point and
701 If the buffer is read-only, @code{kill-region} modifies the kill ring
702 just the same, then signals an error without modifying the buffer. This
703 is convenient because it lets the user use all the kill commands to copy
704 text into the kill ring from a read-only buffer.
707 @deffn Command copy-region-as-kill start end
708 This command saves the region defined by @var{start} and @var{end} on
709 the kill ring, but does not delete the text from the buffer. It returns
710 @code{nil}. It also indicates the extent of the text copied by moving
711 the cursor momentarily, or by displaying a message in the echo area.
713 Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
714 support Emacs 18. For Emacs 19, it is better to use @code{kill-new} or
715 @code{kill-append} instead. @xref{Low-Level Kill Ring}.
719 @comment node-name, next, previous, up
720 @subsection Functions for Yanking
722 @dfn{Yanking} means reinserting an entry of previously killed text
725 @deffn Command yank &optional arg
726 @cindex inserting killed text
727 This command inserts before point the text in the first entry in the
728 kill ring. It positions the mark at the beginning of that text, and
731 If @var{arg} is a list (which occurs interactively when the user
732 types @kbd{C-u} with no digits), then @code{yank} inserts the text as
733 described above, but puts point before the yanked text and puts the mark
736 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most
737 recently killed text---the @var{arg}th element of the kill ring list.
739 @code{yank} does not alter the contents of the kill ring or rotate it.
740 It returns @code{nil}.
743 @deffn Command yank-pop arg
744 This command replaces the just-yanked entry from the kill ring with a
745 different entry from the kill ring.
747 This is allowed only immediately after a @code{yank} or another
748 @code{yank-pop}. At such a time, the region contains text that was just
749 inserted by yanking. @code{yank-pop} deletes that text and inserts in
750 its place a different piece of killed text. It does not add the deleted
751 text to the kill ring, since it is already in the kill ring somewhere.
753 If @var{arg} is @code{nil}, then the replacement text is the previous
754 element of the kill ring. If @var{arg} is numeric, the replacement is
755 the @var{arg}th previous kill. If @var{arg} is negative, a more recent
756 kill is the replacement.
758 The sequence of kills in the kill ring wraps around, so that after the
759 oldest one comes the newest one, and before the newest one goes the
762 The value is always @code{nil}.
765 @node Low-Level Kill Ring
766 @subsection Low-Level Kill Ring
768 These functions and variables provide access to the kill ring at a lower
769 level, but still convenient for use in Lisp programs. They take care of
770 interaction with X Window selections. They do not exist in Emacs
773 @defun current-kill n &optional do-not-move
774 The function @code{current-kill} rotates the yanking pointer which
775 designates the ``front'' of the kill ring by @var{n} places (from newer
776 kills to older ones), and returns the text at that place in the ring.
778 If the optional second argument @var{do-not-move} is non-@code{nil},
779 then @code{current-kill} doesn't alter the yanking pointer; it just
780 returns the @var{n}th kill, counting from the current yanking pointer.
782 If @var{n} is zero, indicating a request for the latest kill,
783 @code{current-kill} calls the value of
784 @code{interprogram-paste-function} (documented below) before consulting
788 @defun kill-new string
789 This function puts the text @var{string} into the kill ring as a new
790 entry at the front of the ring. It discards the oldest entry if
791 appropriate. It also invokes the value of
792 @code{interprogram-cut-function} (see below).
795 @defun kill-append string before-p
796 This function appends the text @var{string} to the first entry in the
797 kill ring. Normally @var{string} goes at the end of the entry, but if
798 @var{before-p} is non-@code{nil}, it goes at the beginning. This
799 function also invokes the value of @code{interprogram-cut-function} (see
803 @defvar interprogram-paste-function
804 This variable provides a way of transferring killed text from other
805 programs, when you are using a window system. Its value should be
806 @code{nil} or a function of no arguments.
808 If the value is a function, @code{current-kill} calls it to get the
809 ``most recent kill''. If the function returns a non-@code{nil} value,
810 then that value is used as the ``most recent kill''. If it returns
811 @code{nil}, then the first element of @code{kill-ring} is used.
813 The normal use of this hook is to get the X server's primary selection
814 as the most recent kill, even if the selection belongs to another X
815 client. @xref{X Selections}.
818 @defvar interprogram-cut-function
819 This variable provides a way of communicating killed text to other
820 programs, when you are using a window system. Its value should be
821 @code{nil} or a function of one argument.
823 If the value is a function, @code{kill-new} and @code{kill-append} call
824 it with the new first element of the kill ring as an argument.
826 The normal use of this hook is to set the X server's primary selection
827 to the newly killed text.
830 @node Internals of Kill Ring
831 @comment node-name, next, previous, up
832 @subsection Internals of the Kill Ring
834 The variable @code{kill-ring} holds the kill ring contents, in the
835 form of a list of strings. The most recent kill is always at the front
838 The @code{kill-ring-yank-pointer} variable points to a link in the
839 kill ring list, whose @sc{car} is the text to yank next. We say it
840 identifies the ``front'' of the ring. Moving
841 @code{kill-ring-yank-pointer} to a different link is called
842 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
843 the functions that move the yank pointer wrap around from the end of the
844 list to the beginning, or vice-versa. Rotation of the kill ring is
845 virtual; it does not change the value of @code{kill-ring}.
847 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
848 variables whose values are normally lists. The word ``pointer'' in the
849 name of the @code{kill-ring-yank-pointer} indicates that the variable's
850 purpose is to identify one element of the list for use by the next yank
853 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
854 of the links in the kill ring list. The element it identifies is the
855 @sc{car} of that link. Kill commands, which change the kill ring, also
856 set this variable to the value of @code{kill-ring}. The effect is to
857 rotate the ring so that the newly killed text is at the front.
859 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
860 pointing to the second entry in the kill ring @code{("some text" "a
861 different piece of text" "yet older text")}.
865 kill-ring kill-ring-yank-pointer
867 | ___ ___ ---> ___ ___ ___ ___
868 --> |___|___|------> |___|___|--> |___|___|--> nil
871 | | -->"yet older text"
873 | --> "a different piece of text"
880 This state of affairs might occur after @kbd{C-y} (@code{yank})
881 immediately followed by @kbd{M-y} (@code{yank-pop}).
884 This variable holds the list of killed text sequences, most recently
888 @defvar kill-ring-yank-pointer
889 This variable's value indicates which element of the kill ring is at the
890 ``front'' of the ring for yanking. More precisely, the value is a tail
891 of the value of @code{kill-ring}, and its @sc{car} is the kill string
892 that @kbd{C-y} should yank.
895 @defopt kill-ring-max
896 The value of this variable is the maximum length to which the kill
897 ring can grow, before elements are thrown away at the end. The default
898 value for @code{kill-ring-max} is 30.
902 @comment node-name, next, previous, up
906 Most buffers have an @dfn{undo list}, which records all changes made
907 to the buffer's text so that they can be undone. (The buffers that
908 don't have one are usually special-purpose buffers for which Emacs
909 assumes that undoing is not useful.) All the primitives that modify the
910 text in the buffer automatically add elements to the front of the undo
911 list, which is in the variable @code{buffer-undo-list}.
913 @defvar buffer-undo-list
914 This variable's value is the undo list of the current buffer.
915 A value of @code{t} disables the recording of undo information.
918 Here are the kinds of elements an undo list can have:
922 This kind of element records a previous value of point. Ordinary cursor
923 motion does not get any sort of undo record, but deletion commands use
924 these entries to record where point was before the command.
926 @item (@var{beg} . @var{end})
927 This kind of element indicates how to delete text that was inserted.
928 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
931 @item (@var{pos} . @var{deleted})
932 This kind of element indicates how to reinsert text that was deleted.
933 The deleted text itself is the string @var{deleted}. The place to
934 reinsert it is @var{pos}.
936 @item (t @var{high} . @var{low})
937 This kind of element indicates that an unmodified buffer became
938 modified. The elements @var{high} and @var{low} are two integers, each
939 recording 16 bits of the visited file's modification time as of when it
940 was previously visited or saved. @code{primitive-undo} uses those
941 values to determine whether to mark the buffer as unmodified once again;
942 it does so only if the file's modification time matches those numbers.
944 @item (nil @var{property} @var{value} @var{beg} . @var{end})
945 This kind of element records a change in a text property.
946 Here's how you might undo the change:
949 (put-text-property @var{beg} @var{end} @var{property} @var{value})
953 This element is a boundary. The elements between two boundaries are
954 called a @dfn{change group}; normally, each change group corresponds to
955 one keyboard command, and undo commands normally undo an entire group as
960 This function places a boundary element in the undo list. The undo
961 command stops at such a boundary, and successive undo commands undo
962 to earlier and earlier boundaries. This function returns @code{nil}.
964 The editor command loop automatically creates an undo boundary between
965 keystroke commands. Thus, each undo normally undoes the effects of one
966 command. Calling this function explicitly is useful for splitting the
967 effects of a command into more than one unit. For example,
968 @code{query-replace} calls this function after each replacement so that
969 the user can undo individual replacements one by one.
972 @defun primitive-undo count list
973 This is the basic function for undoing elements of an undo list.
974 It undoes the first @var{count} elements of @var{list}, returning
975 the rest of @var{list}. You could write this function in Lisp,
976 but it is convenient to have it in C.
978 @code{primitive-undo} adds elements to the buffer's undo list when it
979 changes the buffer. Undo commands avoid confusion by saving the undo
980 list value at the beginning of a sequence of undo operations. Then the
981 undo operations use and update the saved value. The new elements added
982 by undoing are not part of the saved value, so they don't interfere with
986 @node Maintaining Undo
987 @section Maintaining Undo Lists
989 This section describes how to enable and disable undo information for
990 a given buffer. It also explains how the undo list is truncated
991 automatically so it doesn't get too big.
993 Recording of undo information in a newly created buffer is normally
994 enabled to start with; but if the buffer name starts with a space, the
995 undo recording is initially disabled. You can explicitly enable or
996 disable undo recording with the following two functions, or by setting
997 @code{buffer-undo-list} yourself.
999 @deffn Command buffer-enable-undo &optional buffer-or-name
1000 This command enables recording undo information for buffer
1001 @var{buffer-or-name}, so that subsequent changes can be undone. If no
1002 argument is supplied, then the current buffer is used. This function
1003 does nothing if undo recording is already enabled in the buffer. It
1006 In an interactive call, @var{buffer-or-name} is the current buffer.
1007 You cannot specify any other buffer.
1010 @defun buffer-disable-undo &optional buffer
1011 @defunx buffer-flush-undo &optional buffer
1012 @cindex disable undo
1013 This function discards the undo list of @var{buffer}, and disables
1014 further recording of undo information. As a result, it is no longer
1015 possible to undo either previous changes or any subsequent changes. If
1016 the undo list of @var{buffer} is already disabled, this function
1019 This function returns @code{nil}. It cannot be called interactively.
1021 The name @code{buffer-flush-undo} is not considered obsolete, but the
1022 preferred name @code{buffer-disable-undo} is new as of Emacs versions
1026 As editing continues, undo lists get longer and longer. To prevent
1027 them from using up all available memory space, garbage collection trims
1028 them back to size limits you can set. (For this purpose, the ``size''
1029 of an undo list measures the cons cells that make up the list, plus the
1030 strings of deleted text.) Two variables control the range of acceptable
1031 sizes: @code{undo-limit} and @code{undo-strong-limit}.
1034 This is the soft limit for the acceptable size of an undo list. The
1035 change group at which this size is exceeded is the last one kept.
1038 @defvar undo-strong-limit
1039 This is the upper limit for the acceptable size of an undo list. The
1040 change group at which this size is exceeded is discarded itself (along
1041 with all older change groups). There is one exception: the very latest
1042 change group is never discarded separate no matter how big it is.
1046 @comment node-name, next, previous, up
1048 @cindex filling, explicit
1050 @dfn{Filling} means adjusting the lengths of lines (by moving the line
1051 breaks) so that they are nearly (but no greater than) a specified
1052 maximum width. Additionally, lines can be @dfn{justified}, which means
1053 that spaces are inserted between words to make the line exactly the
1054 specified width. The width is controlled by the variable
1055 @code{fill-column}. For ease of reading, lines should be no longer than
1058 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1059 automatically as you insert it, but changes to existing text may leave
1060 it improperly filled. Then you must fill the text explicitly.
1062 Most of the functions in this section return values that are not
1065 @deffn Command fill-paragraph justify-flag
1066 @cindex filling a paragraph
1067 This command fills the paragraph at or after point. If
1068 @var{justify-flag} is non-@code{nil}, each line is justified as well.
1069 It uses the ordinary paragraph motion commands to find paragraph
1070 boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}.
1073 @deffn Command fill-region start end &optional justify-flag
1074 This command fills each of the paragraphs in the region from @var{start}
1075 to @var{end}. It justifies as well if @var{justify-flag} is
1078 The variable @code{paragraph-separate} controls how to distinguish
1079 paragraphs. @xref{Standard Regexps}.
1082 @deffn Command fill-individual-paragraphs start end &optional justify-flag mail-flag
1083 This command fills each paragraph in the region according to its
1084 individual fill prefix. Thus, if the lines of a paragraph were indented
1085 with spaces, the filled paragraph will remain indented in the same
1088 The first two arguments, @var{start} and @var{end}, are the beginning
1089 and end of the region to be filled. The third and fourth arguments,
1090 @var{justify-flag} and @var{mail-flag}, are optional. If
1091 @var{justify-flag} is non-@code{nil}, the paragraphs are justified as
1092 well as filled. If @var{mail-flag} is non-@code{nil}, it means the
1093 function is operating on a mail message and therefore should not fill
1096 Ordinarily, @code{fill-individual-paragraphs} regards each change in
1097 indentation as starting a new paragraph. If
1098 @code{fill-individual-varying-indent} is non-@code{nil}, then only
1099 separator lines separate paragraphs. That mode can handle indented
1100 paragraphs with additional indentation on the first line.
1103 @defopt fill-individual-varying-indent
1104 This variable alters the action of @code{fill-individual-paragraphs} as
1108 @deffn Command fill-region-as-paragraph start end &optional justify-flag
1109 This command considers a region of text as a paragraph and fills it. If
1110 the region was made up of many paragraphs, the blank lines between
1111 paragraphs are removed. This function justifies as well as filling when
1112 @var{justify-flag} is non-@code{nil}. In an interactive call, any
1113 prefix argument requests justification.
1115 In Adaptive Fill mode, which is enabled by default,
1116 @code{fill-region-as-paragraph} on an indented paragraph when there is
1117 no fill prefix uses the indentation of the second line of the paragraph
1121 @deffn Command justify-current-line
1122 This command inserts spaces between the words of the current line so
1123 that the line ends exactly at @code{fill-column}. It returns
1128 This variable specifies a string of text that appears at the beginning
1129 of normal text lines and should be disregarded when filling them. Any
1130 line that fails to start with the fill prefix is considered the start of
1131 a paragraph; so is any line that starts with the fill prefix followed by
1132 additional whitespace. Lines that start with the fill prefix but no
1133 additional whitespace are ordinary text lines that can be filled
1134 together. The resulting filled lines also start with the fill prefix.
1138 This buffer-local variable specifies the maximum width of filled
1139 lines. Its value should be an integer, which is a number of columns.
1140 All the filling, justification and centering commands are affected by
1141 this variable, including Auto Fill mode (@pxref{Auto Filling}).
1143 As a practical matter, if you are writing text for other people to
1144 read, you should set @code{fill-column} to no more than 70. Otherwise
1145 the line will be too long for people to read comfortably, and this can
1146 make the text seem clumsy.
1149 @defvar default-fill-column
1150 The value of this variable is the default value for @code{fill-column} in
1151 buffers that do not override it. This is the same as
1152 @code{(default-value 'fill-column)}.
1154 The default value for @code{default-fill-column} is 70.
1158 @comment node-name, next, previous, up
1159 @section Auto Filling
1160 @cindex filling, automatic
1161 @cindex Auto Fill mode
1163 Auto Fill mode is a minor mode that fills lines automatically as text
1164 as inserted. This section describes the hook used by Auto Fill mode.
1165 For a description of functions that you can call explicitly to fill and
1166 justify existing text, see @ref{Filling}.
1168 @defvar auto-fill-function
1169 The value of this variable should be a function (of no arguments) to
1170 be called after self-inserting a space at a column beyond
1171 @code{fill-column}. It may be @code{nil}, in which case nothing
1174 The value of @code{auto-fill-function} is @code{do-auto-fill} when
1175 Auto-Fill mode is enabled. That is a function whose sole purpose is to
1176 implement the usual strategy for breaking a line.
1179 In older Emacs versions, this variable was named @code{auto-fill-hook},
1180 but since it is not called with the standard convention for hooks, it
1181 was renamed to @code{auto-fill-function} in version 19.
1186 @section Sorting Text
1187 @cindex sorting text
1189 The sorting functions described in this section all rearrange text in
1190 a buffer. This is in contrast to the function @code{sort}, which
1191 rearranges the order of the elements of a list (@pxref{Rearrangement}).
1192 The values returned by these functions are not meaningful.
1194 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
1195 This function is the general text-sorting routine that divides a buffer
1196 into records and sorts them. Most of the commands in this section use
1199 To understand how @code{sort-subr} works, consider the whole accessible
1200 portion of the buffer as being divided into disjoint pieces called
1201 @dfn{sort records}. The records may or may not be contiguous; they may
1202 not overlap. A portion of each sort record (perhaps all of it) is
1203 designated as the sort key. Sorting rearranges the records in order by
1206 Usually, the records are rearranged in order of ascending sort key.
1207 If the first argument to the @code{sort-subr} function, @var{reverse},
1208 is non-@code{nil}, the sort records are rearranged in order of
1209 descending sort key.
1211 The next four arguments to @code{sort-subr} are functions that are
1212 called to move point across a sort record. They are called many times
1213 from within @code{sort-subr}.
1217 @var{nextrecfun} is called with point at the end of a record. This
1218 function moves point to the start of the next record. The first record
1219 is assumed to start at the position of point when @code{sort-subr} is
1220 called. Therefore, you should usually move point to the beginning of
1221 the buffer before calling @code{sort-subr}.
1223 This function can indicate there are no more sort records by leaving
1224 point at the end of the buffer.
1227 @var{endrecfun} is called with point within a record. It moves point to
1228 the end of the record.
1231 @var{startkeyfun} is called to move point from the start of a record to
1232 the start of the sort key. This argument is optional; if it is omitted,
1233 the whole record is the sort key. If supplied, the function should
1234 either return a non-@code{nil} value to be used as the sort key, or
1235 return @code{nil} to indicate that the sort key is in the buffer
1236 starting at point. In the latter case, @var{endkeyfun} is called to
1237 find the end of the sort key.
1240 @var{endkeyfun} is called to move point from the start of the sort key
1241 to the end of the sort key. This argument is optional. If
1242 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
1243 @code{nil}), then the sort key extends to the end of the record. There
1244 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1245 non-@code{nil} value.
1248 As an example of @code{sort-subr}, here is the complete function
1249 definition for @code{sort-lines}:
1253 ;; @r{Note that the first two lines of doc string}
1254 ;; @r{are effectively one line when viewed by a user.}
1255 (defun sort-lines (reverse beg end)
1256 "Sort lines in region alphabetically.
1257 Called from a program, there are three arguments:
1260 REVERSE (non-nil means reverse order),
1261 and BEG and END (the region to sort)."
1262 (interactive "P\nr")
1264 (narrow-to-region beg end)
1265 (goto-char (point-min))
1272 Here @code{forward-line} moves point to the start of the next record,
1273 and @code{end-of-line} moves point to the end of record. We do not pass
1274 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
1275 record is used as the sort key.
1277 The @code{sort-paragraphs} function is very much the same, except that
1278 its @code{sort-subr} call looks like this:
1285 (skip-chars-forward "\n \t\f")))
1291 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
1292 This command sorts the region between @var{start} and @var{end}
1293 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
1294 If @var{reverse} is a negative integer, then sorting is in reverse
1297 Alphabetical sorting means that two sort keys are compared by
1298 comparing the first characters of each, the second characters of each,
1299 and so on. If a mismatch is found, it means that the sort keys are
1300 unequal; the sort key whose character is less at the point of first
1301 mismatch is the lesser sort key. The individual characters are compared
1302 according to their numerical values. Since Emacs uses the @sc{ASCII}
1303 character set, the ordering in that set determines alphabetical order.
1304 @c version 19 change
1306 The value of the @var{record-regexp} argument specifies how to divide
1307 the buffer into sort records. At the end of each record, a search is
1308 done for this regular expression, and the text that matches it is the
1309 next record. For example, the regular expression @samp{^.+$}, which
1310 matches lines with at least one character besides a newline, would make
1311 each such line into a sort record. @xref{Regular Expressions}, for a
1312 description of the syntax and meaning of regular expressions.
1314 The value of the @var{key-regexp} argument specifies what part of each
1315 record is the sort key. The @var{key-regexp} could match the whole
1316 record, or only a part. In the latter case, the rest of the record has
1317 no effect on the sorted order of records, but it is carried along when
1318 the record moves to its new position.
1320 The @var{key-regexp} argument can refer to the text matched by a
1321 subexpression of @var{record-regexp}, or it can be a regular expression
1324 If @var{key-regexp} is:
1327 @item @samp{\@var{digit}}
1328 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
1329 grouping in @var{record-regexp} is the sort key.
1332 then the whole record is the sort key.
1334 @item a regular expression
1335 then @code{sort-regexp-fields} searches for a match for the regular
1336 expression within the record. If such a match is found, it is the sort
1337 key. If there is no match for @var{key-regexp} within a record then
1338 that record is ignored, which means its position in the buffer is not
1339 changed. (The other records may move around it.)
1342 For example, if you plan to sort all the lines in the region by the
1343 first word on each line starting with the letter @samp{f}, you should
1344 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
1345 @samp{\<f\w*\>}. The resulting expression looks like this:
1349 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
1355 If you call @code{sort-regexp-fields} interactively, it prompts for
1356 @var{record-regexp} and @var{key-regexp} in the minibuffer.
1359 @deffn Command sort-lines reverse start end
1360 This command alphabetically sorts lines in the region between
1361 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1362 is in reverse order.
1365 @deffn Command sort-paragraphs reverse start end
1366 This command alphabetically sorts paragraphs in the region between
1367 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1368 is in reverse order.
1371 @deffn Command sort-pages reverse start end
1372 This command alphabetically sorts pages in the region between
1373 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1374 is in reverse order.
1377 @deffn Command sort-fields field start end
1378 This command sorts lines in the region between @var{start} and
1379 @var{end}, comparing them alphabetically by the @var{field}th field
1380 of each line. Fields are separated by whitespace and numbered starting
1381 from 1. If @var{field} is negative, sorting is by the
1382 @w{@minus{}@var{field}th} field from the end of the line. This command
1383 is useful for sorting tables.
1386 @deffn Command sort-numeric-fields field start end
1387 This command sorts lines in the region between @var{start} and
1388 @var{end}, comparing them numerically by the @var{field}th field of each
1389 line. The specified field must contain a number in each line of the
1390 region. Fields are separated by whitespace and numbered starting from
1391 1. If @var{field} is negative, sorting is by the
1392 @w{@minus{}@var{field}th} field from the end of the line. This command
1393 is useful for sorting tables.
1396 @deffn Command sort-columns reverse &optional beg end
1397 This command sorts the lines in the region between @var{beg} and
1398 @var{end}, comparing them alphabetically by a certain range of columns.
1399 The column positions of @var{beg} and @var{end} bound the range of
1402 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
1404 One unusual thing about this command is that the entire line
1405 containing position @var{beg}, and the entire line containing position
1406 @var{end}, are included in the region sorted.
1408 Note that @code{sort-columns} uses the @code{sort} utility program,
1409 and so cannot work properly on text containing tab characters. Use
1410 @kbd{M-x @code{untabify}} to convert tabs to spaces before sorting.
1412 The @code{sort-columns} function did not work on VMS prior to Emacs 19.
1416 @comment node-name, next, previous, up
1417 @section Counting Columns
1419 @cindex counting columns
1420 @cindex horizontal position
1422 The column functions convert between a character position (counting
1423 characters from the beginning of the buffer) and a column position
1424 (counting screen characters from the beginning of a line).
1426 A character counts according to the number of columns it occupies on
1427 the screen. This means control characters count as occupying 2 or 4
1428 columns, depending upon the value of @code{ctl-arrow}, and tabs count as
1429 occupying a number of columns that depends on the value of
1430 @code{tab-width} and on the column where the tab begins. @xref{Usual Display}.
1432 Column number computations ignore the width of the window and the
1433 amount of horizontal scrolling. Consequently, a column value can be
1434 arbitrarily high. The first (or leftmost) column is numbered 0.
1436 @defun current-column
1437 This function returns the horizontal position of point, measured in
1438 columns, counting from 0 at the left margin. The column position is the
1439 sum of the widths of all the displayed representations of the characters
1440 between the start of the current line and point.
1442 For an example of using @code{current-column}, see the description of
1443 @code{count-lines} in @ref{Text Lines}.
1446 @defun move-to-column column &optional force
1447 This function moves point to @var{column} in the current line. The
1448 calculation of @var{column} takes into account the widths of the
1449 displayed representations of the characters between the start of the
1452 If column @var{column} is beyond the end of the line, point moves to the
1453 end of the line. If @var{column} is negative, point moves to the
1454 beginning of the line.
1456 If it is impossible to move to column @var{column} because that is in
1457 the middle of a multicolumn character such as a tab, point moves to the
1458 end of that character. However, if @var{force} is non-@code{nil}, and
1459 @var{column} is in the middle of a tab, then @code{move-to-column}
1460 converts the tab into spaces so that it can move precisely to column
1461 @var{column}. Other multicolumn characters can cause anomalies despite
1462 @var{force}, since there is no way to split them.
1464 The argument @var{force} also has an effect if the line isn't long
1465 enough to reach column @var{column}; in that case, it says to add
1466 whitespace at the end of the line to reach that column.
1468 If @var{column} is not an integer, an error is signaled.
1470 The return value is the column number actually moved to.
1474 @section Indentation
1477 The indentation functions are used to examine, move to, and change
1478 whitespace that is at the beginning of a line. Some of the functions
1479 can also change whitespace elsewhere on a line. Columns and indentation
1480 count from zero at the left margin.
1483 * Primitive Indent:: Functions used to count and insert indentation.
1484 * Mode-Specific Indent:: Customize indentation for different modes.
1485 * Region Indent:: Indent all the lines in a region.
1486 * Relative Indent:: Indent the current line based on previous lines.
1487 * Indent Tabs:: Adjustable, typewriter-like tab stops.
1488 * Motion by Indent:: Move to first non-blank character.
1491 @node Primitive Indent
1492 @subsection Indentation Primitives
1494 This section describes the primitive functions used to count and
1495 insert indentation. The functions in the following sections use these
1498 @defun current-indentation
1499 @comment !!Type Primitive Function
1500 @comment !!SourceFile indent.c
1501 This function returns the indentation of the current line, which is
1502 the horizontal position of the first nonblank character. If the
1503 contents are entirely blank, then this is the horizontal position of the
1507 @deffn Command indent-to column &optional minimum
1508 @comment !!Type Primitive Function
1509 @comment !!SourceFile indent.c
1510 This function indents from point with tabs and spaces until @var{column}
1511 is reached. If @var{minimum} is specified and non-@code{nil}, then at
1512 least that many spaces are inserted even if this requires going beyond
1513 @var{column}. Otherwise the function does nothing if point is already
1514 beyond @var{column}. The value is the column at which the inserted
1517 The inserted whitespace characters inherit text properties from the
1518 surrounding text (usually, from the preceding text only). @xref{Sticky
1522 @defopt indent-tabs-mode
1523 @comment !!SourceFile indent.c
1524 If this variable is non-@code{nil}, indentation functions can insert
1525 tabs as well as spaces. Otherwise, they insert only spaces. Setting
1526 this variable automatically makes it local to the current buffer.
1529 @node Mode-Specific Indent
1530 @subsection Indentation Controlled by Major Mode
1532 An important function of each major mode is to customize the @key{TAB}
1533 key to indent properly for the language being edited. This section
1534 describes the mechanism of the @key{TAB} key and how to control it.
1535 The functions in this section return unpredictable values.
1537 @defvar indent-line-function
1538 This variable's value is the function to be used by @key{TAB} (and
1539 various commands) to indent the current line. The command
1540 @code{indent-according-to-mode} does no more than call this function.
1542 In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C
1543 mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
1544 In Fundamental mode, Text mode, and many other modes with no standard
1545 for indentation, the value is @code{indent-to-left-margin} (which is the
1549 @deffn Command indent-according-to-mode
1550 This command calls the function in @code{indent-line-function} to
1551 indent the current line in a way appropriate for the current major mode.
1554 @deffn Command indent-for-tab-command
1555 This command calls the function in @code{indent-line-function} to indent
1556 the current line; except that if that function is
1557 @code{indent-to-left-margin}, it calls @code{insert-tab} instead. (That
1558 is a trivial command that inserts a tab character.)
1561 @defun indent-to-left-margin
1562 This is the default @code{indent-line-function}, used in Fundamental
1563 mode, Text mode, etc. Its effect is to adjust the indentation at the
1564 beginning of the current line to the value specified by the variable
1565 @code{left-margin}. This may involve either inserting or deleting
1570 This variable specifies the column for @code{indent-to-left-margin} to
1571 indent to. In Fundamental mode, @key{LFD} indents to this column. This
1572 variable automatically becomes buffer-local when set in any fashion.
1575 @deffn Command newline-and-indent
1576 @comment !!SourceFile simple.el
1577 This function inserts a newline, then indents the new line (the one
1578 following the newline just inserted) according to the major mode.
1580 It does indentation by calling the current @code{indent-line-function}.
1581 In programming language modes, this is the same thing @key{TAB} does,
1582 but in some text modes, where @key{TAB} inserts a tab,
1583 @code{newline-and-indent} indents to the column specified by
1587 @deffn Command reindent-then-newline-and-indent
1588 @comment !!SourceFile simple.el
1589 This command reindents the current line, inserts a newline at point,
1590 and then reindents the new line (the one following the newline just
1593 This command does indentation on both lines according to the current
1594 major mode, by calling the current value of @code{indent-line-function}.
1595 In programming language modes, this is the same thing @key{TAB} does,
1596 but in some text modes, where @key{TAB} inserts a tab,
1597 @code{reindent-then-newline-and-indent} indents to the column specified
1598 by @code{left-margin}.
1602 @subsection Indenting an Entire Region
1604 This section describes commands that indent all the lines in the
1605 region. They return unpredictable values.
1607 @deffn Command indent-region start end to-column
1608 This command indents each nonblank line starting between @var{start}
1609 (inclusive) and @var{end} (exclusive). If @var{to-column} is
1610 @code{nil}, @code{indent-region} indents each nonblank line by calling
1611 the current mode's indentation function, the value of
1612 @code{indent-line-function}.
1614 If @var{to-column} is non-@code{nil}, it should be an integer
1615 specifying the number of columns of indentation; then this function
1616 gives each line exactly that much indentation, by either adding or
1617 deleting whitespace.
1619 If there is a fill prefix, @code{indent-region} indents each line
1620 by making it start with the fill prefix.
1623 @defvar indent-region-function
1624 The value of this variable is a function that can be used by
1625 @code{indent-region} as a short cut. You should design the function so
1626 that it will produce the same results as indenting the lines of the
1627 region one by one, but presumably faster.
1629 If the value is @code{nil}, there is no short cut, and
1630 @code{indent-region} actually works line by line.
1632 A short-cut function is useful in modes such as C mode and Lisp mode,
1633 where the @code{indent-line-function} must scan from the beginning of
1634 the function definition: applying it to each line would be quadratic in
1635 time. The short cut can update the scan information as it moves through
1636 the lines indenting them; this takes linear time. In a mode where
1637 indenting a line individually is fast, there is no need for a short cut.
1639 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
1640 a different meaning and does not use this variable.
1643 @deffn Command indent-rigidly start end count
1644 @comment !!SourceFile indent.el
1645 This command indents all lines starting between @var{start}
1646 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
1647 This ``preserves the shape'' of the affected region, moving it as a
1648 rigid unit. Consequently, this command is useful not only for indenting
1649 regions of unindented text, but also for indenting regions of formatted
1652 For example, if @var{count} is 3, this command adds 3 columns of
1653 indentation to each of the lines beginning in the region specified.
1655 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
1656 @code{indent-rigidly} to indent the text copied from the message being
1660 @defun indent-code-rigidly start end columns &optional nochange-regexp
1661 This is like @code{indent-rigidly}, except that it doesn't alter lines
1662 that start within strings or comments.
1664 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
1665 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
1668 @node Relative Indent
1669 @subsection Indentation Relative to Previous Lines
1671 This section describes two commands that indent the current line
1672 based on the contents of previous lines.
1674 @deffn Command indent-relative &optional unindented-ok
1675 This command inserts whitespace at point, extending to the same
1676 column as the next @dfn{indent point} of the previous nonblank line. An
1677 indent point is a non-whitespace character following whitespace. The
1678 next indent point is the first one at a column greater than the current
1679 column of point. For example, if point is underneath and to the left of
1680 the first non-blank character of a line of text, it moves to that column
1681 by inserting whitespace.
1683 If the previous nonblank line has no next indent point (i.e., none at a
1684 great enough column position), @code{indent-relative} either does
1685 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
1686 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right
1687 of the last column of a short line of text, this command ordinarily
1688 moves point to the next tab stop by inserting whitespace.
1690 The return value of @code{indent-relative} is unpredictable.
1692 In the following example, point is at the beginning of the second
1697 This line is indented twelve spaces.
1698 @point{}The quick brown fox jumped.
1703 Evaluation of the expression @code{(indent-relative nil)} produces the
1708 This line is indented twelve spaces.
1709 @point{}The quick brown fox jumped.
1713 In this example, point is between the @samp{m} and @samp{p} of
1718 This line is indented twelve spaces.
1719 The quick brown fox jum@point{}ped.
1724 Evaluation of the expression @code{(indent-relative nil)} produces the
1729 This line is indented twelve spaces.
1730 The quick brown fox jum @point{}ped.
1735 @deffn Command indent-relative-maybe
1736 @comment !!SourceFile indent.el
1737 This command indents the current line like the previous nonblank line.
1738 It calls @code{indent-relative} with @code{t} as the @var{unindented-ok}
1739 argument. The return value is unpredictable.
1741 If the previous nonblank line has no indent points beyond the current
1742 column, this command does nothing.
1746 @comment node-name, next, previous, up
1747 @subsection Adjustable ``Tab Stops''
1748 @cindex tabs stops for indentation
1750 This section explains the mechanism for user-specified ``tab stops''
1751 and the mechanisms that use and set them. The name ``tab stops'' is
1752 used because the feature is similar to that of the tab stops on a
1753 typewriter. The feature works by inserting an appropriate number of
1754 spaces and tab characters to reach the next tab stop column; it does not
1755 affect the display of tab characters in the buffer (@pxref{Usual
1756 Display}). Note that the @key{TAB} character as input uses this tab
1757 stop feature only in a few major modes, such as Text mode.
1759 @deffn Command tab-to-tab-stop
1760 This command inserts spaces or tabs up to the next tab stop column
1761 defined by @code{tab-stop-list}. It searches the list for an element
1762 greater than the current column number, and uses that element as the
1763 column to indent to. It does nothing if no such element is found.
1766 @defopt tab-stop-list
1767 This variable is the list of tab stop columns used by
1768 @code{tab-to-tab-stops}. The elements should be integers in increasing
1769 order. The tab stop columns need not be evenly spaced.
1771 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
1775 @node Motion by Indent
1776 @subsection Indentation-Based Motion Commands
1778 These commands, primarily for interactive use, act based on the
1779 indentation in the text.
1781 @deffn Command back-to-indentation
1782 @comment !!SourceFile simple.el
1783 This command moves point to the first non-whitespace character in the
1784 current line (which is the line in which point is located). It returns
1788 @deffn Command backward-to-indentation arg
1789 @comment !!SourceFile simple.el
1790 This command moves point backward @var{arg} lines and then to the
1791 first nonblank character on that line. It returns @code{nil}.
1794 @deffn Command forward-to-indentation arg
1795 @comment !!SourceFile simple.el
1796 This command moves point forward @var{arg} lines and then to the first
1797 nonblank character on that line. It returns @code{nil}.
1801 @comment node-name, next, previous, up
1802 @section Case Changes
1803 @cindex case changes
1805 The case change commands described here work on text in the current
1806 buffer. @xref{Character Case}, for case conversion commands that work
1807 on strings and characters. @xref{Case Table}, for how to customize
1808 which characters are upper or lower case and how to convert them.
1810 @deffn Command capitalize-region start end
1811 This function capitalizes all words in the region defined by
1812 @var{start} and @var{end}. To capitalize means to convert each word's
1813 first character to upper case and convert the rest of each word to lower
1814 case. The function returns @code{nil}.
1816 If one end of the region is in the middle of a word, the part of the
1817 word within the region is treated as an entire word.
1819 When @code{capitalize-region} is called interactively, @var{start} and
1820 @var{end} are point and the mark, with the smallest first.
1824 ---------- Buffer: foo ----------
1825 This is the contents of the 5th foo.
1826 ---------- Buffer: foo ----------
1830 (capitalize-region 1 44)
1833 ---------- Buffer: foo ----------
1834 This Is The Contents Of The 5th Foo.
1835 ---------- Buffer: foo ----------
1840 @deffn Command downcase-region start end
1841 This function converts all of the letters in the region defined by
1842 @var{start} and @var{end} to lower case. The function returns
1845 When @code{downcase-region} is called interactively, @var{start} and
1846 @var{end} are point and the mark, with the smallest first.
1849 @deffn Command upcase-region start end
1850 This function converts all of the letters in the region defined by
1851 @var{start} and @var{end} to upper case. The function returns
1854 When @code{upcase-region} is called interactively, @var{start} and
1855 @var{end} are point and the mark, with the smallest first.
1858 @deffn Command capitalize-word count
1859 This function capitalizes @var{count} words after point, moving point
1860 over as it does. To capitalize means to convert each word's first
1861 character to upper case and convert the rest of each word to lower case.
1862 If @var{count} is negative, the function capitalizes the
1863 @minus{}@var{count} previous words but does not move point. The value
1866 If point is in the middle of a word, the part of the word before point
1867 is ignored when moving forward. The rest is treated as an entire word.
1869 When @code{capitalize-word} is called interactively, @var{count} is
1870 set to the numeric prefix argument.
1873 @deffn Command downcase-word count
1874 This function converts the @var{count} words after point to all lower
1875 case, moving point over as it does. If @var{count} is negative, it
1876 converts the @minus{}@var{count} previous words but does not move point.
1877 The value is @code{nil}.
1879 When @code{downcase-word} is called interactively, @var{count} is set
1880 to the numeric prefix argument.
1883 @deffn Command upcase-word count
1884 This function converts the @var{count} words after point to all upper
1885 case, moving point over as it does. If @var{count} is negative, it
1886 converts the @minus{}@var{count} previous words but does not move point.
1887 The value is @code{nil}.
1889 When @code{upcase-word} is called interactively, @var{count} is set to
1890 the numeric prefix argument.
1893 @node Text Properties
1894 @section Text Properties
1895 @cindex text properties
1896 @cindex attributes of text
1897 @cindex properties of text
1899 Each character position in a buffer or a string can have a @dfn{text
1900 property list}, much like the property list of a symbol (@pxref{Property
1901 Lists}). The properties belong to a particular character at a
1902 particular place, such as, the letter @samp{T} at the beginning of this
1903 sentence or the first @samp{o} in @samp{foo}---if the same character
1904 occurs in two different places, the two occurrences generally have
1905 different properties.
1907 Each property has a name and a value. Both of these can be any Lisp
1908 object, but the name is normally a symbol. The usual way to access the
1909 property list is to specify a name and ask what value corresponds to it.
1911 If a character has a @code{category} property, we call it the
1912 @dfn{category} of the character. It should be a symbol. The properties
1913 of the symbol serve as defaults for the properties of the character.
1915 Copying text between strings and buffers preserves the properties
1916 along with the characters; this includes such diverse functions as
1917 @code{substring}, @code{insert}, and @code{buffer-substring}.
1920 * Examining Properties:: Looking at the properties of one character.
1921 * Changing Properties:: Setting the properties of a range of text.
1922 * Property Search:: Searching for where a property changes value.
1923 * Special Properties:: Particular properties with special meanings.
1924 * Sticky Properties:: How inserted text gets properties from
1926 * Saving Properties:: Saving text properties in files, and reading
1928 * Not Intervals:: Why text properties do not use
1929 Lisp-visible text intervals.
1932 @node Examining Properties
1933 @subsection Examining Text Properties
1935 The simplest way to examine text properties is to ask for the value of
1936 a particular property of a particular character. For that, use
1937 @code{get-text-property}. Use @code{text-properties-at} to get the
1938 entire property list of a character. @xref{Property Search}, for
1939 functions to examine the properties of a number of characters at once.
1941 These functions handle both strings and buffers. Keep in mind that
1942 positions in a string start from 0, whereas positions in a buffer start
1945 @defun get-text-property pos prop &optional object
1946 This function returns the value of the @var{prop} property of the
1947 character after position @var{pos} in @var{object} (a buffer or
1948 string). The argument @var{object} is optional and defaults to the
1951 If there is no @var{prop} property strictly speaking, but the character
1952 has a category that is a symbol, then @code{get-text-property} returns
1953 the @var{prop} property of that symbol.
1956 @defun get-char-property pos prop &optional object
1957 This function is like @code{get-text-property}, except that it checks
1958 overlays first and then text properties. @xref{Overlays}.
1960 The argument @var{object} may be a string, a buffer, or a window. If it
1961 is a window, then the buffer displayed in that window is used for text
1962 properties and overlays, but only the overlays active for that window
1963 are considered. If @var{object} is a buffer, then all overlays in that
1964 buffer are considered, as well as text properties. If @var{object} is a
1965 string, only text properties are considered, since strings never have
1969 @defun text-properties-at position &optional object
1970 This function returns the entire property list of the character at
1971 @var{position} in the string or buffer @var{object}. If @var{object} is
1972 @code{nil}, it defaults to the current buffer.
1975 @node Changing Properties
1976 @subsection Changing Text Properties
1978 The primitives for changing properties apply to a specified range of
1979 text. The function @code{set-text-properties} (see end of section) sets
1980 the entire property list of the text in that range; more often, it is
1981 useful to add, change, or delete just certain properties specified by
1984 Since text properties are considered part of the buffer's contents, and
1985 can affect how the buffer looks on the screen, any change in the text
1986 properties is considered a buffer modification. Buffer text property
1987 changes are undoable (@pxref{Undo}).
1989 @defun add-text-properties start end props &optional object
1990 This function modifies the text properties for the text between
1991 @var{start} and @var{end} in the string or buffer @var{object}. If
1992 @var{object} is @code{nil}, it defaults to the current buffer.
1994 The argument @var{props} specifies which properties to change. It
1995 should have the form of a property list (@pxref{Property Lists}): a list
1996 whose elements include the property names followed alternately by the
1997 corresponding values.
1999 The return value is @code{t} if the function actually changed some
2000 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2001 its values agree with those in the text).
2003 For example, here is how to set the @code{comment} and @code{face}
2004 properties of a range of text:
2007 (add-text-properties @var{start} @var{end}
2008 '(comment t face highlight))
2012 @defun put-text-property start end prop value &optional object
2013 This function sets the @var{prop} property to @var{value} for the text
2014 between @var{start} and @var{end} in the string or buffer @var{object}.
2015 If @var{object} is @code{nil}, it defaults to the current buffer.
2018 @defun remove-text-properties start end props &optional object
2019 This function deletes specified text properties from the text between
2020 @var{start} and @var{end} in the string or buffer @var{object}. If
2021 @var{object} is @code{nil}, it defaults to the current buffer.
2023 The argument @var{props} specifies which properties to delete. It
2024 should have the form of a property list (@pxref{Property Lists}): a list
2025 whose elements are property names alternating with corresponding values.
2026 But only the names matter---the values that accompany them are ignored.
2027 For example, here's how to remove the @code{face} property.
2030 (remove-text-properties @var{start} @var{end} '(face nil))
2033 The return value is @code{t} if the function actually changed some
2034 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2035 if no character in the specified text had any of those properties).
2038 @defun set-text-properties start end props &optional object
2039 This function completely replaces the text property list for the text
2040 between @var{start} and @var{end} in the string or buffer @var{object}.
2041 If @var{object} is @code{nil}, it defaults to the current buffer.
2043 The argument @var{props} is the new property list. It should be a list
2044 whose elements are property names alternating with corresponding values.
2046 After @code{set-text-properties} returns, all the characters in the
2047 specified range have identical properties.
2049 If @var{props} is @code{nil}, the effect is to get rid of all properties
2050 from the specified range of text. Here's an example:
2053 (set-text-properties @var{start} @var{end} nil)
2057 @node Property Search
2058 @subsection Property Search Functions
2060 In typical use of text properties, most of the time several or many
2061 consecutive characters have the same value for a property. Rather than
2062 writing your programs to examine characters one by one, it is much
2063 faster to process chunks of text that have the same property value.
2065 Here are functions you can use to do this. In all cases, @var{object}
2066 defaults to the current buffer.
2068 For high performance, it's very important to use the @var{limit}
2069 argument to these functions, especially the ones that search for a
2070 single property---otherwise, they may spend a long time considering
2071 changes in other properties while scanning to the end of the buffer.
2073 Remember that a position is always between two characters; the position
2074 returned by these functions is between two characters with different
2077 @defun next-property-change pos &optional object limit
2078 The function scans the text forward from position @var{pos} in the
2079 string or buffer @var{object} till it finds a change in some text
2080 property, then returns the position of the change. In other words, it
2081 returns the position of the first character beyond @var{pos} whose
2082 properties are not identical to those of the character just after
2085 If @var{limit} is non-@code{nil}, then the scan ends at position
2086 @var{limit}. If there is no property change before that point,
2087 @code{next-property-change} returns @var{limit}.
2089 The value is @code{nil} if the properties remain unchanged all the way
2090 to the end of @var{object} and @var{limit} is @code{nil}. If the value
2091 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
2092 The value equals @var{pos} only when @var{limit} equals @var{pos}.
2094 Here is an example of how to scan the buffer by chunks of text within
2095 which all properties are constant:
2099 (let ((plist (text-properties-at (point)))
2101 (or (next-property-change (point) (current-buffer))
2103 @r{Process text from point to @var{next-change}@dots{}}
2104 (goto-char next-change)))
2108 @defun next-single-property-change pos prop &optional object limit
2109 The function scans the text forward from position @var{pos} in the
2110 string or buffer @var{object} till it finds a change in the @var{prop}
2111 property, then returns the position of the change. In other words, it
2112 returns the position of the first character beyond @var{pos} whose
2113 @var{prop} property differs from that of the character just after
2116 If @var{limit} is non-@code{nil}, then the scan ends at position
2117 @var{limit}. If there is no property change before that point,
2118 @code{next-single-property-change} returns @var{limit}.
2120 The value is @code{nil} if the property remains unchanged all the way to
2121 the end of @var{object} and @var{limit} is @code{nil}. If the value is
2122 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
2123 equals @var{pos} only if @var{limit} equals @var{pos}.
2126 @defun previous-property-change pos &optional object limit
2127 This is like @code{next-property-change}, but scans back from @var{pos}
2128 instead of forward. If the value is non-@code{nil}, it is a position
2129 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
2133 @defun previous-single-property-change pos prop &optional object limit
2134 This is like @code{next-single-property-change}, but scans back from
2135 @var{pos} instead of forward. If the value is non-@code{nil}, it is a
2136 position less than or equal to @var{pos}; it equals @var{pos} only if
2137 @var{limit} equals @var{pos}.
2140 @defun text-property-any start end prop value &optional object
2141 This function returns non-@code{nil} if at least one character between
2142 @var{start} and @var{end} has a property @var{prop} whose value is
2143 @var{value}. More precisely, it returns the position of the first such
2144 character. Otherwise, it returns @code{nil}.
2146 The optional fifth argument, @var{object}, specifies the string or
2147 buffer to scan. Positions are relative to @var{object}. The default
2148 for @var{object} is the current buffer.
2151 @defun text-property-not-all start end prop value &optional object
2152 This function returns non-@code{nil} if at least one character between
2153 @var{start} and @var{end} has a property @var{prop} whose value differs
2154 from @var{value}. More precisely, it returns the position of the
2155 first such character. Otherwise, it returns @code{nil}.
2157 The optional fifth argument, @var{object}, specifies the string or
2158 buffer to scan. Positions are relative to @var{object}. The default
2159 for @var{object} is the current buffer.
2162 @node Special Properties
2163 @subsection Properties with Special Meanings
2166 @cindex category of text character
2167 @kindex category @r{(text property)}
2169 If a character has a @code{category} property, we call it the
2170 @dfn{category} of the character. It should be a symbol. The properties
2171 of the symbol serve as defaults for the properties of the character.
2174 @cindex face codes of text
2175 @kindex face @r{(text property)}
2176 You can use the property @code{face} to control the font and color of
2177 text. @xref{Faces}, for more information. This feature is temporary;
2178 in the future, we may replace it with other ways of specifying how to
2182 @kindex mouse-face @r{(text property)}
2183 The property @code{mouse-face} is used instead of @code{face} when the
2184 mouse is on or near the character. For this purpose, ``near'' means
2185 that all text between the character and where the mouse is have the same
2186 @code{mouse-face} property value.
2189 @cindex keymap of character
2190 @kindex local-map @r{(text property)}
2191 You can specify a different keymap for a portion of the text by means of
2192 a @code{local-map} property. The property's value for the character
2193 after point, if non-@code{nil}, replaces the buffer's local map.
2194 @xref{Active Keymaps}.
2197 @cindex read-only character
2198 @kindex read-only @r{(text property)}
2199 If a character has the property @code{read-only}, then modifying that
2200 character is not allowed. Any command that would do so gets an error.
2202 Insertion next to a read-only character is an error if inserting
2203 ordinary text there would inherit the @code{read-only} property due to
2204 stickiness. Thus, you can control permission to insert next to
2205 read-only text by controlling the stickiness. @xref{Sticky Properties}.
2207 Since changing properties counts as modifying the buffer, it is not
2208 possible to remove a @code{read-only} property unless you know the
2209 special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
2210 and then remove the property. @xref{Read Only Buffers}.
2213 @kindex invisible @r{(text property)}
2214 A non-@code{nil} @code{invisible} property means a character does not
2215 appear on the screen. This works much like selective display. Details
2216 of this feature are likely to change in future versions, so check the
2217 @file{etc/NEWS} file in the version you are using.
2220 @kindex intangible @r{(text property)}
2221 A non-@code{nil} @code{intangible} property on a character prevents
2222 putting point before that character. If you try, point actually goes
2223 after the character (and after all succeeding intangible characters).
2225 @item modification-hooks
2226 @cindex change hooks for a character
2227 @cindex hooks for changing a character
2228 @kindex modification-hooks @r{(text property)}
2229 If a character has the property @code{modification-hooks}, then its
2230 value should be a list of functions; modifying that character calls all
2231 of those functions. Each function receives two arguments: the beginning
2232 and end of the part of the buffer being modified. Note that if a
2233 particular modification hook function appears on several characters
2234 being modified by a single primitive, you can't predict how many times
2235 the function will be called.
2237 @item insert-in-front-hooks
2238 @itemx insert-behind-hooks
2239 @kindex insert-in-front-hooks @r{(text property)}
2240 @kindex insert-behind-hooks @r{(text property)}
2241 The operation of inserting text in a buffer, after actually modifying
2242 the buffer, calls the functions listed in the
2243 @code{insert-in-front-hooks} property of the following character and in
2244 the @code{insert-behind-hooks} property of the preceding character.
2245 These functions receive two arguments, the beginning and end of the
2248 See also @ref{Change Hooks}, for other hooks that are called
2249 when you change text in a buffer.
2253 @cindex hooks for motion of point
2254 @kindex point-entered @r{(text property)}
2255 @kindex point-left @r{(text property)}
2256 The special properties @code{point-entered} and @code{point-left}
2257 record hook functions that report motion of point. Each time point
2258 moves, Emacs compares these two property values:
2262 the @code{point-left} property of the character after the old location,
2265 the @code{point-entered} property of the character after the new
2270 If these two values differ, each of them is called (if not @code{nil})
2271 with two arguments: the old value of point, and the new one.
2273 The same comparison is made for the characters before the old and new
2274 locations. The result may be to execute two @code{point-left} functions
2275 (which may be the same function) and/or two @code{point-entered}
2276 functions (which may be the same function). In any case, all the
2277 @code{point-left} functions are called first, followed by all the
2278 @code{point-entered} functions.
2280 A primitive function may examine characters at various positions
2281 without moving point to those positions. Only an actual change in the
2282 value of point runs these hook functions.
2285 @defvar inhibit-point-motion-hooks
2286 When this variable is non-@code{nil}, @code{point-left} and
2287 @code{point-entered} hooks are not run.
2290 @node Sticky Properties
2291 @subsection Stickiness of Text Properties
2292 @cindex sticky text properties
2293 @cindex inheritance of text properties
2295 Self-inserting characters normally take on the same properties as the
2296 preceding character. This is called @dfn{inheritance} of properties.
2298 In a Lisp program, you can do insertion with inheritance or without,
2299 depending on your choice of insertion primitive. The ordinary text
2300 insertion functions such as @code{insert} do not inherit any properties.
2301 They insert text with precisely the properties of the string being
2302 inserted, and no others. This is correct for programs that copy text
2303 from one context to another---for example, into or out of the kill ring.
2304 To insert with inheritance, use the special primitives described in this
2305 section. Self-inserting characters inherit properties because they work
2306 using these primitives.
2308 When you do insertion with inheritance, @emph{which} properties are
2309 inherited depends on two specific properties: @code{front-sticky} and
2310 @code{rear-nonsticky}.
2312 Insertion after a character inherits those of its properties that are
2313 @dfn{rear-sticky}. Insertion before a character inherits those of its
2314 properties that are @dfn{front-sticky}. By default, a text property is
2315 rear-sticky but not front-sticky. Thus, the default is to inherit all
2316 the properties of the preceding character, and nothing from the
2317 following character. You can request different behavior by specifying
2318 the stickiness of certain properties.
2320 If a character's @code{front-sticky} property is @code{t}, then all
2321 its properties are front-sticky. If the @code{front-sticky} property is
2322 a list, then the sticky properties of the character are those whose
2323 names are in the list. For example, if a character has a
2324 @code{front-sticky} property whose value is @code{(face read-only)},
2325 then insertion before the character can inherit its @code{face} property
2326 and its @code{read-only} property, but no others.
2328 The @code{rear-nonsticky} works the opposite way. Every property is
2329 rear-sticky by default, so the @code{rear-nonsticky} property says which
2330 properties are @emph{not} rear-sticky. If a character's
2331 @code{rear-nonsticky} property is @code{t}, then none of its properties
2332 are rear-sticky. If the @code{rear-nonsticky} property is a list,
2333 properties are rear-sticky @emph{unless} their names are in the list.
2335 When you insert text with inheritance, it inherits all the rear-sticky
2336 properties of the preceding character, and all the front-sticky
2337 properties of the following character. The previous character's
2338 properties take precedence when both sides offer different sticky values
2339 for the same property.
2341 Here are the functions that insert text with inheritance of properties:
2343 @defun insert-and-inherit &rest strings
2344 Insert the strings @var{strings}, just like the function @code{insert},
2345 but inherit any sticky properties from the adjoining text.
2348 @defun insert-before-markers-and-inherit &rest strings
2349 Insert the strings @var{strings}, just like the function
2350 @code{insert-before-markers}, but inherit any sticky properties from the
2354 @node Saving Properties
2355 @subsection Saving Text Properties in Files
2356 @cindex text properties in files
2357 @cindex saving text properties
2359 You can save text properties in files, and restore text properties
2360 when inserting the files, using these two hooks:
2362 @defvar write-region-annotation-functions
2363 This variable's value is a list of functions for @code{write-region} to
2364 run to encode text properties in some fashion as annotations to the text
2365 being written in the file. @xref{Writing to Files}.
2367 Each function in the list is called with two arguments: the start and
2368 end of the region to be written. These functions should not alter the
2369 contents of the buffer. Instead, they should return lists indicating
2370 annotations to write in the file in addition to the text in the
2373 Each function should return a list of elements of the form
2374 @code{(@var{position} . @var{string})}, where @var{position} is an
2375 integer specifying the relative position in the text to be written, and
2376 @var{string} is the annotation to add there.
2378 Each list returned by one of these functions must be already sorted in
2379 increasing order by @var{position}. If there is more than one function,
2380 @code{write-region} merges the lists destructively into one sorted list.
2382 When @code{write-region} actually writes the text from the buffer to the
2383 file, it intermixes the specified annotations at the corresponding
2384 positions. All this takes place without modifying the buffer.
2387 @defvar after-insert-file-functions
2388 This variable holds a list of functions for @code{insert-file-contents}
2389 to call after inserting a file's contents. These functions should scan
2390 the inserted text for annotations, and convert them to the text
2391 properties they stand for.
2393 Each function receives one argument, the length of the inserted text;
2394 point indicates the start of that text. The function should scan that
2395 text for annotations, delete them, and create the text properties that
2396 the annotations specify. The function should return the updated length
2397 of the inserted text, as it stands after those changes. The value
2398 returned by one function becomes the argument to the next function.
2400 These functions should always return with point at the beginning of
2403 The intended use of @code{after-insert-file-functions} is for converting
2404 some sort of textual annotations into actual text properties. But other
2405 uses may be possible.
2408 We invite users to write Lisp programs to store and retrieve text
2409 properties in files, using these hooks, and thus to experiment with
2410 various data formats and find good ones. Eventually we hope users
2411 will produce good, general extensions we can install in Emacs.
2413 We suggest not trying to handle arbitrary Lisp objects as property
2414 names or property values---because a program that general is probably
2415 difficult to write, and slow. Instead, choose a set of possible data
2416 types that are reasonably flexible, and not too hard to encode.
2419 @subsection Why Text Properties are not Intervals
2422 Some editors that support adding attributes to text in the buffer do
2423 so by letting the user specify ``intervals'' within the text, and adding
2424 the properties to the intervals. Those editors permit the user or the
2425 programmer to determine where individual intervals start and end. We
2426 deliberately provided a different sort of interface in Emacs Lisp to
2427 avoid certain paradoxical behavior associated with text modification.
2429 If the actual subdivision into intervals is meaningful, that means you
2430 can distinguish between a buffer that is just one interval with a
2431 certain property, and a buffer containing the same text subdivided into
2432 two intervals, both of which have that property.
2434 Suppose you take the buffer with just one interval and kill part of
2435 the text. The text remaining in the buffer is one interval, and the
2436 copy in the kill ring (and the undo list) becomes a separate interval.
2437 Then if you yank back the killed text, you get two intervals with the
2438 same properties. Thus, editing does not preserve the distinction
2439 between one interval and two.
2441 Suppose we ``fix'' this problem by coalescing the two intervals when
2442 the text is inserted. That works fine if the buffer originally was a
2443 single interval. But suppose instead that we have two adjacent
2444 intervals with the same properties, and we kill the text of one interval
2445 and yank it back. The same interval-coalescence feature that rescues
2446 the other case causes trouble in this one: after yanking, we have just
2447 one interval. One again, editing does not preserve the distinction
2448 between one interval and two.
2450 Insertion of text at the border between intervals also raises
2451 questions that have no satisfactory answer.
2453 However, it is easy to arrange for editing to behave consistently for
2454 questions of the form, ``What are the properties of this character?''
2455 So we have decided these are the only questions that make sense; we have
2456 not implemented asking questions about where intervals start or end.
2458 In practice, you can usually use the property search functions in
2459 place of explicit interval boundaries. You can think of them as finding
2460 the boundaries of intervals, assuming that intervals are always
2461 coalesced whenever possible. @xref{Property Search}.
2463 Emacs also provides explicit intervals as a presentation feature; see
2467 @section Substituting for a Character Code
2469 The following functions replace characters within a specified region
2470 based on their character codes.
2472 @defun subst-char-in-region start end old-char new-char &optional noundo
2473 @cindex replace characters
2474 This function replaces all occurrences of the character @var{old-char}
2475 with the character @var{new-char} in the region of the current buffer
2476 defined by @var{start} and @var{end}.
2478 @cindex Outline mode
2479 @cindex undo avoidance
2480 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region}
2481 does not record the change for undo and does not mark the buffer as
2482 modified. This feature is useful for changes that are not considered
2483 significant, such as when Outline mode changes visible lines to
2484 invisible lines and vice versa.
2486 @code{subst-char-in-region} does not move point and returns
2491 ---------- Buffer: foo ----------
2492 This is the contents of the buffer before.
2493 ---------- Buffer: foo ----------
2497 (subst-char-in-region 1 20 ?i ?X)
2500 ---------- Buffer: foo ----------
2501 ThXs Xs the contents of the buffer before.
2502 ---------- Buffer: foo ----------
2507 @defun translate-region start end table
2508 This function applies a translation table to the characters in the
2509 buffer between positions @var{start} and @var{end}.
2511 The translation table @var{table} is a string; @code{(aref @var{table}
2512 @var{ochar})} gives the translated character corresponding to
2513 @var{ochar}. If the length of @var{table} is less than 256, any
2514 characters with codes larger than the length of @var{table} are not
2515 altered by the translation.
2517 The return value of @code{translate-region} is the number of
2518 characters that were actually changed by the translation. This does
2519 not count characters that were mapped into themselves in the
2522 This function is available in Emacs versions 19 and later.
2529 A register is a sort of variable used in Emacs editing that can hold a
2530 marker, a string, a rectangle, a window configuration (of one frame), or
2531 a frame configuration (of all frames). Each register is named by a
2532 single character. All characters, including control and meta characters
2533 (but with the exception of @kbd{C-g}), can be used to name registers.
2534 Thus, there are 255 possible registers. A register is designated in
2535 Emacs Lisp by a character that is its name.
2537 The functions in this section return unpredictable values unless
2539 @c Will change in version 19
2541 @defvar register-alist
2542 This variable is an alist of elements of the form @code{(@var{name} .
2543 @var{contents})}. Normally, there is one element for each Emacs
2544 register that has been used.
2546 The object @var{name} is a character (an integer) identifying the
2547 register. The object @var{contents} is a string, marker, or list
2548 representing the register contents. A string represents text stored in
2549 the register. A marker represents a position. A list represents a
2550 rectangle; its elements are strings, one per line of the rectangle.
2553 @defun get-register reg
2554 This function returns the contents of the register
2555 @var{reg}, or @code{nil} if it has no contents.
2558 @defun set-register reg value
2559 This function sets the contents of register @var{reg} to @var{value}.
2560 A register can be set to any value, but the other register functions
2561 expect only certain data types. The return value is @var{value}.
2564 @deffn Command view-register reg
2565 This command displays what is contained in register @var{reg}.
2569 @deffn Command point-to-register reg
2570 This command stores both the current location of point and the current
2571 buffer in register @var{reg} as a marker.
2574 @deffn Command jump-to-register reg
2575 @deffnx Command register-to-point reg
2576 @comment !!SourceFile register.el
2577 This command restores the status recorded in register @var{reg}.
2579 If @var{reg} contains a marker, it moves point to the position stored in
2580 the marker. Since both the buffer and the location within the buffer
2581 are stored by the @code{point-to-register} function, this command can
2582 switch you to another buffer.
2584 If @var{reg} contains a window configuration or a frame configuration.
2585 @code{jump-to-register} restores that configuration.
2589 @deffn Command insert-register reg &optional beforep
2590 This command inserts contents of register @var{reg} into the current
2593 Normally, this command puts point before the inserted text, and the
2594 mark after it. However, if the optional second argument @var{beforep}
2595 is non-@code{nil}, it puts the mark before and point after.
2596 You can pass a non-@code{nil} second argument @var{beforep} to this
2597 function interactively by supplying any prefix argument.
2599 If the register contains a rectangle, then the rectangle is inserted
2600 with its upper left corner at point. This means that text is inserted
2601 in the current line and underneath it on successive lines.
2603 If the register contains something other than saved text (a string) or
2604 a rectangle (a list), currently useless things happen. This may be
2605 changed in the future.
2609 @deffn Command copy-to-register reg start end &optional delete-flag
2610 This command copies the region from @var{start} to @var{end} into
2611 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
2612 the region from the buffer after copying it into the register.
2615 @deffn Command prepend-to-register reg start end &optional delete-flag
2616 This command prepends the region from @var{start} to @var{end} into
2617 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
2618 the region from the buffer after copying it to the register.
2621 @deffn Command append-to-register reg start end &optional delete-flag
2622 This command appends the region from @var{start} to @var{end} to the
2623 text already in register @var{reg}. If @var{delete-flag} is
2624 non-@code{nil}, it deletes the region from the buffer after copying it
2628 @deffn Command copy-rectangle-to-register reg start end &optional delete-flag
2629 This command copies a rectangular region from @var{start} to @var{end}
2630 into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it
2631 deletes the region from the buffer after copying it to the register.
2634 @deffn Command window-configuration-to-register reg
2635 This function stores the window configuration of the selected frame in
2639 @deffn Command frame-configuration-to-register reg
2640 This function stores the current frame configuration in register
2646 @section Transposition of Text
2648 This subroutine is used by the transposition commands.
2650 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
2651 This function exchanges two nonoverlapping portions of the buffer.
2652 Arguments @var{start1} and @var{end1} specify the bounds of one portion
2653 and arguments @var{start2} and @var{end2} specify the bounds of the
2656 Normally, @code{transpose-regions} relocates markers with the transposed
2657 text; a marker previously positioned within one of the two transposed
2658 portions moves along with that portion, thus remaining between the same
2659 two characters in their new position. However, if @var{leave-markers}
2660 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
2661 all markers unrelocated.
2665 @section Change Hooks
2666 @cindex change hooks
2667 @cindex hooks for text changes
2669 These hook variables let you arrange to take notice of all changes in
2670 all buffers (or in a particular buffer, if you make them buffer-local).
2671 See also @ref{Special Properties}, for how to detect changes to specific
2674 The functions you use in these hooks should save and restore the match
2675 data if they do anything that uses regular expressions; otherwise, they
2676 will interfere in bizarre ways with the editing operations that call
2679 @defvar before-change-functions
2680 This variable holds a list of a functions to call before any buffer
2681 modification. Each function gets two arguments, the beginning and end
2682 of the region that is about to change, represented as integers. The
2683 buffer that is about to change is always the current buffer.
2686 @defvar after-change-functions
2687 This variable holds a list of a functions to call after any buffer
2688 modification. Each function receives three arguments: the beginning and
2689 end of the region just changed, and the length of the text that existed
2690 before the change. (To get the current length, subtract the region
2691 beginning from the region end.) All three arguments are integers. The
2692 buffer that's about to change is always the current buffer.
2695 @defvar before-change-function
2696 This variable holds one function to call before any buffer modification
2697 (or @code{nil} for no function). It is called just like the functions
2698 in @code{before-change-functions}.
2701 @defvar after-change-function
2702 This variable holds one function to call after any buffer modification
2703 (or @code{nil} for no function). It is called just like the functions in
2704 @code{after-change-functions}.
2707 The four variables above are temporarily bound to @code{nil} during the
2708 time that any of these functions is running. This means that if one of
2709 these functions changes the buffer, that change won't run these
2710 functions. If you do want a hook function to make changes that run
2711 these functions, make it bind these variables back to their usual
2714 One inconvenient result of this protective feature is that you cannot
2715 have a function in @code{after-change-functions} or
2716 @code{before-change-functions} which changes the value of that variable.
2717 But that's not a real limitation. If you want those functions to change
2718 the list of functions to run, simply add one fixed function to the hook,
2719 and code that function to look in another variable for other functions
2720 to call. Here is an example:
2723 (setq my-own-after-change-functions nil)
2724 (defun indirect-after-change-function (beg end len)
2725 (let ((list my-own-after-change-functions))
2727 (funcall (car list) beg end len)
2728 (setq list (cdr list)))))
2729 (add-hooks 'after-change-functions
2730 'indirect-after-change-function)
2733 @defvar first-change-hook
2734 This variable is a normal hook that is run whenever a buffer is changed
2735 that was previously in the unmodified state.
2738 The variables described in this section are meaningful only starting
2739 with Emacs version 19.