2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/text
6 @node Text, Non-ASCII Characters, 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
29 buffer, together with their properties (when relevant).
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 * Margins:: How to specify margins for filling commands.
45 * Auto Filling:: How auto-fill mode is implemented to break lines.
46 * Sorting:: Functions for sorting parts of the buffer.
47 * Columns:: Computing horizontal positions, and using them.
48 * Indentation:: Functions to insert or adjust indentation.
49 * Case Changes:: Case conversion of parts of the buffer.
50 * Text Properties:: Assigning Lisp property lists to text characters.
51 * Substitution:: Replacing a given character wherever it appears.
52 * Transposition:: Swapping two portions of a buffer.
53 * Registers:: How registers are implemented. Accessing the text or
54 position stored in a register.
55 * Change Hooks:: Supplying functions to be run when text is changed.
59 @section Examining Text Near Point
61 Many functions are provided to look at the characters around point.
62 Several simple functions are described here. See also @code{looking-at}
63 in @ref{Regexp Search}.
65 @defun char-after position
66 This function returns the character in the current buffer at (i.e.,
67 immediately after) position @var{position}. If @var{position} is out of
68 range for this purpose, either before the beginning of the buffer, or at
69 or beyond the end, then the value is @code{nil}.
71 In the following example, assume that the first character in the
76 (char-to-string (char-after 1))
82 @defun char-before position
83 This function returns the character in the current buffer immediately
84 before position @var{position}. If @var{position} is out of range for
85 this purpose, either before the beginning of the buffer, or at or beyond
86 the end, then the value is @code{nil}.
90 This function returns the character following point in the current
91 buffer. This is similar to @code{(char-after (point))}. However, if
92 point is at the end of the buffer, then @code{following-char} returns 0.
94 Remember that point is always between characters, and the terminal
95 cursor normally appears over the character following point. Therefore,
96 the character returned by @code{following-char} is the character the
99 In this example, point is between the @samp{a} and the @samp{c}.
103 ---------- Buffer: foo ----------
104 Gentlemen may cry ``Pea@point{}ce! Peace!,''
105 but there is no peace.
106 ---------- Buffer: foo ----------
110 (char-to-string (preceding-char))
112 (char-to-string (following-char))
118 @defun preceding-char
119 This function returns the character preceding point in the current
120 buffer. See above, under @code{following-char}, for an example. If
121 point is at the beginning of the buffer, @code{preceding-char} returns
126 This function returns @code{t} if point is at the beginning of the
127 buffer. If narrowing is in effect, this means the beginning of the
128 accessible portion of the text. See also @code{point-min} in
133 This function returns @code{t} if point is at the end of the buffer.
134 If narrowing is in effect, this means the end of accessible portion of
135 the text. See also @code{point-max} in @xref{Point}.
139 This function returns @code{t} if point is at the beginning of a line.
140 @xref{Text Lines}. The beginning of the buffer (or of its accessible
141 portion) always counts as the beginning of a line.
145 This function returns @code{t} if point is at the end of a line. The
146 end of the buffer (or of its accessible portion) is always considered
150 @node Buffer Contents
151 @section Examining Buffer Contents
153 This section describes two functions that allow a Lisp program to
154 convert any portion of the text in the buffer into a string.
156 @defun buffer-substring start end
157 This function returns a string containing a copy of the text of the
158 region defined by positions @var{start} and @var{end} in the current
159 buffer. If the arguments are not positions in the accessible portion of
160 the buffer, @code{buffer-substring} signals an @code{args-out-of-range}
163 It is not necessary for @var{start} to be less than @var{end}; the
164 arguments can be given in either order. But most often the smaller
165 argument is written first.
167 If the text being copied has any text properties, these are copied into
168 the string along with the characters they belong to. @xref{Text
169 Properties}. However, overlays (@pxref{Overlays}) in the buffer and
170 their properties are ignored, not copied.
174 ---------- Buffer: foo ----------
175 This is the contents of buffer foo
177 ---------- Buffer: foo ----------
181 (buffer-substring 1 10)
182 @result{} "This is t"
185 (buffer-substring (point-max) 10)
186 @result{} "he contents of buffer foo
192 @defun buffer-substring-no-properties start end
193 This is like @code{buffer-substring}, except that it does not copy text
194 properties, just the characters themselves. @xref{Text Properties}.
198 This function returns the contents of the entire accessible portion of
199 the current buffer as a string. This is the portion between
200 @code{(point-min)} and @code{(point-max)} (@pxref{Narrowing}).
204 ---------- Buffer: foo ----------
205 This is the contents of buffer foo
207 ---------- Buffer: foo ----------
210 @result{} "This is the contents of buffer foo
216 @defun thing-at-point thing
217 Return the @var{thing} around or next to point, as a string.
219 The argument @var{thing} is a symbol which specifies a kind of syntactic
220 entity. Possibilities include @code{symbol}, @code{list}, @code{sexp},
221 @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
222 @code{whitespace}, @code{line}, @code{page}, and others.
225 ---------- Buffer: foo ----------
226 Gentlemen may cry ``Pea@point{}ce! Peace!,''
227 but there is no peace.
228 ---------- Buffer: foo ----------
230 (thing-at-point 'word)
232 (thing-at-point 'line)
233 @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
234 (thing-at-point 'whitespace)
240 @section Comparing Text
241 @cindex comparing buffer text
243 This function lets you compare portions of the text in a buffer, without
244 copying them into strings first.
246 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
247 This function lets you compare two substrings of the same buffer or two
248 different buffers. The first three arguments specify one substring,
249 giving a buffer and two positions within the buffer. The last three
250 arguments specify the other substring in the same way. You can use
251 @code{nil} for @var{buffer1}, @var{buffer2}, or both to stand for the
254 The value is negative if the first substring is less, positive if the
255 first is greater, and zero if they are equal. The absolute value of
256 the result is one plus the index of the first differing characters
257 within the substrings.
259 This function ignores case when comparing characters
260 if @code{case-fold-search} is non-@code{nil}. It always ignores
263 Suppose the current buffer contains the text @samp{foobarbar
264 haha!rara!}; then in this example the two substrings are @samp{rbar }
265 and @samp{rara!}. The value is 2 because the first substring is greater
266 at the second character.
269 (compare-buffer-substring nil 6 11 nil 16 21)
275 @section Inserting Text
276 @cindex insertion of text
277 @cindex text insertion
279 @cindex insertion before point
280 @cindex before point, insertion
281 @dfn{Insertion} means adding new text to a buffer. The inserted text
282 goes at point---between the character before point and the character
283 after point. Some insertion functions leave point before the inserted
284 text, while other functions leave it after. We call the former
285 insertion @dfn{after point} and the latter insertion @dfn{before point}.
287 Insertion relocates markers that point at positions after the
288 insertion point, so that they stay with the surrounding text
289 (@pxref{Markers}). When a marker points at the place of insertion,
290 insertion may or may not relocate the marker, depending on the marker's
291 insertion type (@pxref{Marker Insertion Types}). Certain special
292 functions such as @code{insert-before-markers} relocate all such markers
293 to point after the inserted text, regardless of the markers' insertion
296 Insertion functions signal an error if the current buffer is
299 These functions copy text characters from strings and buffers along
300 with their properties. The inserted characters have exactly the same
301 properties as the characters they were copied from. By contrast,
302 characters specified as separate arguments, not part of a string or
303 buffer, inherit their text properties from the neighboring text.
305 @defun insert &rest args
306 This function inserts the strings and/or characters @var{args} into the
307 current buffer, at point, moving point forward. In other words, it
308 inserts the text before point. An error is signaled unless all
309 @var{args} are either strings or characters. The value is @code{nil}.
312 @defun insert-before-markers &rest args
313 This function inserts the strings and/or characters @var{args} into the
314 current buffer, at point, moving point forward. An error is signaled
315 unless all @var{args} are either strings or characters. The value is
318 This function is unlike the other insertion functions in that it
319 relocates markers initially pointing at the insertion point, to point
320 after the inserted text. If an overlay begins the insertion point, the
321 inserted text falls outside the overlay; if a nonempty overlay ends at
322 the insertion point, the inserted text falls inside that overlay.
325 @defun insert-char character &optional count inherit
326 This function inserts @var{count} instances of @var{character} into the
327 current buffer before point. The argument @var{count} should be a
328 number (@code{nil} means 1), and @var{character} must be a character.
329 The value is @code{nil}.
331 If @var{inherit} is non-@code{nil}, then the inserted characters inherit
332 sticky text properties from the two characters before and after the
333 insertion point. @xref{Sticky Properties}.
336 @defun insert-buffer-substring from-buffer-or-name &optional start end
337 This function inserts a portion of buffer @var{from-buffer-or-name}
338 (which must already exist) into the current buffer before point. The
339 text inserted is the region from @var{start} and @var{end}. (These
340 arguments default to the beginning and end of the accessible portion of
341 that buffer.) This function returns @code{nil}.
343 In this example, the form is executed with buffer @samp{bar} as the
344 current buffer. We assume that buffer @samp{bar} is initially empty.
348 ---------- Buffer: foo ----------
349 We hold these truths to be self-evident, that all
350 ---------- Buffer: foo ----------
354 (insert-buffer-substring "foo" 1 20)
357 ---------- Buffer: bar ----------
358 We hold these truth@point{}
359 ---------- Buffer: bar ----------
364 @xref{Sticky Properties}, for other insertion functions that inherit
365 text properties from the nearby text in addition to inserting it.
366 Whitespace inserted by indentation functions also inherits text
369 @node Commands for Insertion
370 @section User-Level Insertion Commands
372 This section describes higher-level commands for inserting text,
373 commands intended primarily for the user but useful also in Lisp
376 @deffn Command insert-buffer from-buffer-or-name
377 This command inserts the entire contents of @var{from-buffer-or-name}
378 (which must exist) into the current buffer after point. It leaves
379 the mark after the inserted text. The value is @code{nil}.
382 @deffn Command self-insert-command count
383 @cindex character insertion
384 @cindex self-insertion
385 This command inserts the last character typed; it does so @var{count}
386 times, before point, and returns @code{nil}. Most printing characters
387 are bound to this command. In routine use, @code{self-insert-command}
388 is the most frequently called function in Emacs, but programs rarely use
389 it except to install it on a keymap.
391 In an interactive call, @var{count} is the numeric prefix argument.
393 This command calls @code{auto-fill-function} whenever that is
394 non-@code{nil} and the character inserted is a space or a newline
395 (@pxref{Auto Filling}).
397 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
398 This command performs abbrev expansion if Abbrev mode is enabled and
399 the inserted character does not have word-constituent
400 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
402 This is also responsible for calling @code{blink-paren-function} when
403 the inserted character has close parenthesis syntax (@pxref{Blinking}).
406 @deffn Command newline &optional number-of-newlines
407 This command inserts newlines into the current buffer before point.
408 If @var{number-of-newlines} is supplied, that many newline characters
411 @cindex newline and Auto Fill mode
412 This function calls @code{auto-fill-function} if the current column
413 number is greater than the value of @code{fill-column} and
414 @var{number-of-newlines} is @code{nil}. Typically what
415 @code{auto-fill-function} does is insert a newline; thus, the overall
416 result in this case is to insert two newlines at different places: one
417 at point, and another earlier in the line. @code{newline} does not
418 auto-fill if @var{number-of-newlines} is non-@code{nil}.
420 This command indents to the left margin if that is not zero.
423 The value returned is @code{nil}. In an interactive call, @var{count}
424 is the numeric prefix argument.
427 @deffn Command split-line
428 This command splits the current line, moving the portion of the line
429 after point down vertically so that it is on the next line directly
430 below where it was before. Whitespace is inserted as needed at the
431 beginning of the lower line, using the @code{indent-to} function.
432 @code{split-line} returns the position of point.
434 Programs hardly ever use this function.
437 @defvar overwrite-mode
438 This variable controls whether overwrite mode is in effect: a
439 non-@code{nil} value enables the mode. It is automatically made
440 buffer-local when set in any fashion.
444 @section Deleting Text
446 @cindex deletion vs killing
447 Deletion means removing part of the text in a buffer, without saving
448 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
449 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
450 Some deletion functions do save text in the kill ring in some special
453 All of the deletion functions operate on the current buffer, and all
454 return a value of @code{nil}.
457 This function deletes the entire text of the current buffer, leaving it
458 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
459 error. Otherwise, it deletes the text without asking for any
460 confirmation. It returns @code{nil}.
462 Normally, deleting a large amount of text from a buffer inhibits further
463 auto-saving of that buffer ``because it has shrunk''. However,
464 @code{erase-buffer} does not do this, the idea being that the future
465 text is not really related to the former text, and its size should not
466 be compared with that of the former text.
469 @deffn Command delete-region start end
470 This command deletes the text in the current buffer in the region
471 defined by @var{start} and @var{end}. The value is @code{nil}. If
472 point was inside the deleted region, its value afterward is @var{start}.
473 Otherwise, point relocates with the surrounding text, as markers do.
476 @deffn Command delete-char count &optional killp
477 This command deletes @var{count} characters directly after point, or
478 before point if @var{count} is negative. If @var{killp} is
479 non-@code{nil}, then it saves the deleted characters in the kill ring.
481 In an interactive call, @var{count} is the numeric prefix argument, and
482 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
483 argument is supplied, the text is saved in the kill ring. If no prefix
484 argument is supplied, then one character is deleted, but not saved in
487 The value returned is always @code{nil}.
490 @deffn Command delete-backward-char count &optional killp
491 @cindex delete previous char
492 This command deletes @var{count} characters directly before point, or
493 after point if @var{count} is negative. If @var{killp} is
494 non-@code{nil}, then it saves the deleted characters in the kill ring.
496 In an interactive call, @var{count} is the numeric prefix argument, and
497 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
498 argument is supplied, the text is saved in the kill ring. If no prefix
499 argument is supplied, then one character is deleted, but not saved in
502 The value returned is always @code{nil}.
505 @deffn Command backward-delete-char-untabify count &optional killp
507 This command deletes @var{count} characters backward, changing tabs
508 into spaces. When the next character to be deleted is a tab, it is
509 first replaced with the proper number of spaces to preserve alignment
510 and then one of those spaces is deleted instead of the tab. If
511 @var{killp} is non-@code{nil}, then the command saves the deleted
512 characters in the kill ring.
514 Conversion of tabs to spaces happens only if @var{count} is positive.
515 If it is negative, exactly @minus{}@var{count} characters after point
518 In an interactive call, @var{count} is the numeric prefix argument, and
519 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
520 argument is supplied, the text is saved in the kill ring. If no prefix
521 argument is supplied, then one character is deleted, but not saved in
524 The value returned is always @code{nil}.
527 @tindex backward-delete-char-untabify-method
528 @defopt backward-delete-char-untabify-method
529 This option specifies how @code{backward-delete-char-untabify} should
530 deal with whitespace. Possible values include @code{untabify}, the
531 default, meaning convert a tab to many spaces and delete one;
532 @code{hungry}, meaning delete all the whitespace characters before point
533 with one command, and @code{nil}, meaning do nothing special for
534 whitespace characters.
537 @node User-Level Deletion
538 @section User-Level Deletion Commands
540 This section describes higher-level commands for deleting text,
541 commands intended primarily for the user but useful also in Lisp
544 @deffn Command delete-horizontal-space
545 @cindex deleting whitespace
546 This function deletes all spaces and tabs around point. It returns
549 In the following examples, we call @code{delete-horizontal-space} four
550 times, once on each line, with point between the second and third
551 characters on the line each time.
555 ---------- Buffer: foo ----------
560 ---------- Buffer: foo ----------
564 (delete-horizontal-space) ; @r{Four times.}
567 ---------- Buffer: foo ----------
572 ---------- Buffer: foo ----------
577 @deffn Command delete-indentation &optional join-following-p
578 This function joins the line point is on to the previous line, deleting
579 any whitespace at the join and in some cases replacing it with one
580 space. If @var{join-following-p} is non-@code{nil},
581 @code{delete-indentation} joins this line to the following line
582 instead. The value is @code{nil}.
584 If there is a fill prefix, and the second of the lines being joined
585 starts with the prefix, then @code{delete-indentation} deletes the
586 fill prefix before joining the lines. @xref{Margins}.
588 In the example below, point is located on the line starting
589 @samp{events}, and it makes no difference if there are trailing spaces
590 in the preceding line.
594 ---------- Buffer: foo ----------
595 When in the course of human
596 @point{} events, it becomes necessary
597 ---------- Buffer: foo ----------
604 ---------- Buffer: foo ----------
605 When in the course of human@point{} events, it becomes necessary
606 ---------- Buffer: foo ----------
610 After the lines are joined, the function @code{fixup-whitespace} is
611 responsible for deciding whether to leave a space at the junction.
614 @defun fixup-whitespace
615 This function replaces all the white space surrounding point with either
616 one space or no space, according to the context. It returns @code{nil}.
618 At the beginning or end of a line, the appropriate amount of space is
619 none. Before a character with close parenthesis syntax, or after a
620 character with open parenthesis or expression-prefix syntax, no space is
621 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
624 In the example below, @code{fixup-whitespace} is called the first time
625 with point before the word @samp{spaces} in the first line. For the
626 second invocation, point is directly after the @samp{(}.
630 ---------- Buffer: foo ----------
631 This has too many @point{}spaces
632 This has too many spaces at the start of (@point{} this list)
633 ---------- Buffer: foo ----------
644 ---------- Buffer: foo ----------
645 This has too many spaces
646 This has too many spaces at the start of (this list)
647 ---------- Buffer: foo ----------
652 @deffn Command just-one-space
653 @comment !!SourceFile simple.el
654 This command replaces any spaces and tabs around point with a single
655 space. It returns @code{nil}.
658 @deffn Command delete-blank-lines
659 This function deletes blank lines surrounding point. If point is on a
660 blank line with one or more blank lines before or after it, then all but
661 one of them are deleted. If point is on an isolated blank line, then it
662 is deleted. If point is on a nonblank line, the command deletes all
663 blank lines following it.
665 A blank line is defined as a line containing only tabs and spaces.
667 @code{delete-blank-lines} returns @code{nil}.
671 @section The Kill Ring
674 @dfn{Kill functions} delete text like the deletion functions, but save
675 it so that the user can reinsert it by @dfn{yanking}. Most of these
676 functions have @samp{kill-} in their name. By contrast, the functions
677 whose names start with @samp{delete-} normally do not save text for
678 yanking (though they can still be undone); these are ``deletion''
681 Most of the kill commands are primarily for interactive use, and are
682 not described here. What we do describe are the functions provided for
683 use in writing such commands. You can use these functions to write
684 commands for killing text. When you need to delete text for internal
685 purposes within a Lisp function, you should normally use deletion
686 functions, so as not to disturb the kill ring contents.
689 Killed text is saved for later yanking in the @dfn{kill ring}. This
690 is a list that holds a number of recent kills, not just the last text
691 kill. We call this a ``ring'' because yanking treats it as having
692 elements in a cyclic order. The list is kept in the variable
693 @code{kill-ring}, and can be operated on with the usual functions for
694 lists; there are also specialized functions, described in this section,
695 that treat it as a ring.
697 Some people think this use of the word ``kill'' is unfortunate, since
698 it refers to operations that specifically @emph{do not} destroy the
699 entities ``killed''. This is in sharp contrast to ordinary life, in
700 which death is permanent and ``killed'' entities do not come back to
701 life. Therefore, other metaphors have been proposed. For example, the
702 term ``cut ring'' makes sense to people who, in pre-computer days, used
703 scissors and paste to cut up and rearrange manuscripts. However, it
704 would be difficult to change the terminology now.
707 * Kill Ring Concepts:: What text looks like in the kill ring.
708 * Kill Functions:: Functions that kill text.
709 * Yank Commands:: Commands that access the kill ring.
710 * Low-Level Kill Ring:: Functions and variables for kill ring access.
711 * Internals of Kill Ring:: Variables that hold kill-ring data.
714 @node Kill Ring Concepts
715 @comment node-name, next, previous, up
716 @subsection Kill Ring Concepts
718 The kill ring records killed text as strings in a list, most recent
719 first. A short kill ring, for example, might look like this:
722 ("some text" "a different piece of text" "even older text")
726 When the list reaches @code{kill-ring-max} entries in length, adding a
727 new entry automatically deletes the last entry.
729 When kill commands are interwoven with other commands, each kill
730 command makes a new entry in the kill ring. Multiple kill commands in
731 succession build up a single entry in the kill ring, which would be
732 yanked as a unit; the second and subsequent consecutive kill commands
733 add text to the entry made by the first one.
735 For yanking, one entry in the kill ring is designated the ``front'' of
736 the ring. Some yank commands ``rotate'' the ring by designating a
737 different element as the ``front.'' But this virtual rotation doesn't
738 change the list itself---the most recent entry always comes first in the
742 @comment node-name, next, previous, up
743 @subsection Functions for Killing
745 @code{kill-region} is the usual subroutine for killing text. Any
746 command that calls this function is a ``kill command'' (and should
747 probably have @samp{kill} in its name). @code{kill-region} puts the
748 newly killed text in a new element at the beginning of the kill ring or
749 adds it to the most recent element. It determines automatically (using
750 @code{last-command}) whether the previous command was a kill command,
751 and if so appends the killed text to the most recent entry.
753 @deffn Command kill-region start end
754 This function kills the text in the region defined by @var{start} and
755 @var{end}. The text is deleted but saved in the kill ring, along with
756 its text properties. The value is always @code{nil}.
758 In an interactive call, @var{start} and @var{end} are point and
762 If the buffer is read-only, @code{kill-region} modifies the kill ring
763 just the same, then signals an error without modifying the buffer. This
764 is convenient because it lets the user use all the kill commands to copy
765 text into the kill ring from a read-only buffer.
768 @deffn Command copy-region-as-kill start end
769 This command saves the region defined by @var{start} and @var{end} on
770 the kill ring (including text properties), but does not delete the text
771 from the buffer. It returns @code{nil}. It also indicates the extent
772 of the text copied by moving the cursor momentarily, or by displaying a
773 message in the echo area.
775 The command does not set @code{this-command} to @code{kill-region}, so a
776 subsequent kill command does not append to the same kill ring entry.
778 Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
779 support Emacs 18. For newer Emacs versions, it is better to use
780 @code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill
785 @comment node-name, next, previous, up
786 @subsection Functions for Yanking
788 @dfn{Yanking} means reinserting an entry of previously killed text
789 from the kill ring. The text properties are copied too.
791 @deffn Command yank &optional arg
792 @cindex inserting killed text
793 This command inserts before point the text in the first entry in the
794 kill ring. It positions the mark at the beginning of that text, and
797 If @var{arg} is a list (which occurs interactively when the user
798 types @kbd{C-u} with no digits), then @code{yank} inserts the text as
799 described above, but puts point before the yanked text and puts the mark
802 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most
803 recently killed text---the @var{arg}th element of the kill ring list.
805 @code{yank} does not alter the contents of the kill ring or rotate it.
806 It returns @code{nil}.
809 @deffn Command yank-pop arg
810 This command replaces the just-yanked entry from the kill ring with a
811 different entry from the kill ring.
813 This is allowed only immediately after a @code{yank} or another
814 @code{yank-pop}. At such a time, the region contains text that was just
815 inserted by yanking. @code{yank-pop} deletes that text and inserts in
816 its place a different piece of killed text. It does not add the deleted
817 text to the kill ring, since it is already in the kill ring somewhere.
819 If @var{arg} is @code{nil}, then the replacement text is the previous
820 element of the kill ring. If @var{arg} is numeric, the replacement is
821 the @var{arg}th previous kill. If @var{arg} is negative, a more recent
822 kill is the replacement.
824 The sequence of kills in the kill ring wraps around, so that after the
825 oldest one comes the newest one, and before the newest one goes the
828 The value is always @code{nil}.
831 @node Low-Level Kill Ring
832 @subsection Low-Level Kill Ring
834 These functions and variables provide access to the kill ring at a
835 lower level, but still convenient for use in Lisp programs, because they
836 take care of interaction with window system selections
837 (@pxref{Window System Selections}).
839 @defun current-kill n &optional do-not-move
840 The function @code{current-kill} rotates the yanking pointer which
841 designates the ``front'' of the kill ring by @var{n} places (from newer
842 kills to older ones), and returns the text at that place in the ring.
844 If the optional second argument @var{do-not-move} is non-@code{nil},
845 then @code{current-kill} doesn't alter the yanking pointer; it just
846 returns the @var{n}th kill, counting from the current yanking pointer.
848 If @var{n} is zero, indicating a request for the latest kill,
849 @code{current-kill} calls the value of
850 @code{interprogram-paste-function} (documented below) before consulting
854 @defun kill-new string
855 This function puts the text @var{string} into the kill ring as a new
856 entry at the front of the ring. It discards the oldest entry if
857 appropriate. It also invokes the value of
858 @code{interprogram-cut-function} (see below).
861 @defun kill-append string before-p
862 This function appends the text @var{string} to the first entry in the
863 kill ring. Normally @var{string} goes at the end of the entry, but if
864 @var{before-p} is non-@code{nil}, it goes at the beginning. This
865 function also invokes the value of @code{interprogram-cut-function} (see
869 @defvar interprogram-paste-function
870 This variable provides a way of transferring killed text from other
871 programs, when you are using a window system. Its value should be
872 @code{nil} or a function of no arguments.
874 If the value is a function, @code{current-kill} calls it to get the
875 ``most recent kill''. If the function returns a non-@code{nil} value,
876 then that value is used as the ``most recent kill''. If it returns
877 @code{nil}, then the first element of @code{kill-ring} is used.
879 The normal use of this hook is to get the window system's primary
880 selection as the most recent kill, even if the selection belongs to
881 another application. @xref{Window System Selections}.
884 @defvar interprogram-cut-function
885 This variable provides a way of communicating killed text to other
886 programs, when you are using a window system. Its value should be
887 @code{nil} or a function of one argument.
889 If the value is a function, @code{kill-new} and @code{kill-append} call
890 it with the new first element of the kill ring as an argument.
892 The normal use of this hook is to set the window system's primary
893 selection from the newly killed text. @xref{Window System Selections}.
896 @node Internals of Kill Ring
897 @comment node-name, next, previous, up
898 @subsection Internals of the Kill Ring
900 The variable @code{kill-ring} holds the kill ring contents, in the
901 form of a list of strings. The most recent kill is always at the front
904 The @code{kill-ring-yank-pointer} variable points to a link in the
905 kill ring list, whose @sc{car} is the text to yank next. We say it
906 identifies the ``front'' of the ring. Moving
907 @code{kill-ring-yank-pointer} to a different link is called
908 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
909 the functions that move the yank pointer wrap around from the end of the
910 list to the beginning, or vice-versa. Rotation of the kill ring is
911 virtual; it does not change the value of @code{kill-ring}.
913 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
914 variables whose values are normally lists. The word ``pointer'' in the
915 name of the @code{kill-ring-yank-pointer} indicates that the variable's
916 purpose is to identify one element of the list for use by the next yank
919 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
920 of the links in the kill ring list. The element it identifies is the
921 @sc{car} of that link. Kill commands, which change the kill ring, also
922 set this variable to the value of @code{kill-ring}. The effect is to
923 rotate the ring so that the newly killed text is at the front.
925 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
926 pointing to the second entry in the kill ring @code{("some text" "a
927 different piece of text" "yet older text")}.
931 kill-ring ---- kill-ring-yank-pointer
934 | --- --- --- --- --- ---
935 --> | | |------> | | |--> | | |--> nil
936 --- --- --- --- --- ---
939 | | -->"yet older text"
941 | --> "a different piece of text"
948 This state of affairs might occur after @kbd{C-y} (@code{yank})
949 immediately followed by @kbd{M-y} (@code{yank-pop}).
952 This variable holds the list of killed text sequences, most recently
956 @defvar kill-ring-yank-pointer
957 This variable's value indicates which element of the kill ring is at the
958 ``front'' of the ring for yanking. More precisely, the value is a tail
959 of the value of @code{kill-ring}, and its @sc{car} is the kill string
960 that @kbd{C-y} should yank.
963 @defopt kill-ring-max
964 The value of this variable is the maximum length to which the kill
965 ring can grow, before elements are thrown away at the end. The default
966 value for @code{kill-ring-max} is 30.
970 @comment node-name, next, previous, up
974 Most buffers have an @dfn{undo list}, which records all changes made
975 to the buffer's text so that they can be undone. (The buffers that
976 don't have one are usually special-purpose buffers for which Emacs
977 assumes that undoing is not useful.) All the primitives that modify the
978 text in the buffer automatically add elements to the front of the undo
979 list, which is in the variable @code{buffer-undo-list}.
981 @defvar buffer-undo-list
982 This variable's value is the undo list of the current buffer.
983 A value of @code{t} disables the recording of undo information.
986 Here are the kinds of elements an undo list can have:
990 This kind of element records a previous value of point. Ordinary cursor
991 motion does not get any sort of undo record, but deletion operations use
992 these entries to record where point was before the command.
994 @item (@var{beg} . @var{end})
995 This kind of element indicates how to delete text that was inserted.
996 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
999 @item (@var{text} . @var{position})
1000 This kind of element indicates how to reinsert text that was deleted.
1001 The deleted text itself is the string @var{text}. The place to
1002 reinsert it is @code{(abs @var{position})}.
1004 @item (t @var{high} . @var{low})
1005 This kind of element indicates that an unmodified buffer became
1006 modified. The elements @var{high} and @var{low} are two integers, each
1007 recording 16 bits of the visited file's modification time as of when it
1008 was previously visited or saved. @code{primitive-undo} uses those
1009 values to determine whether to mark the buffer as unmodified once again;
1010 it does so only if the file's modification time matches those numbers.
1012 @item (nil @var{property} @var{value} @var{beg} . @var{end})
1013 This kind of element records a change in a text property.
1014 Here's how you might undo the change:
1017 (put-text-property @var{beg} @var{end} @var{property} @var{value})
1020 @item (@var{marker} . @var{adjustment})
1021 This kind of element records the fact that the marker @var{marker} was
1022 relocated due to deletion of surrounding text, and that it moved
1023 @var{adjustment} character positions. Undoing this element moves
1024 @var{marker} @minus{} @var{adjustment} characters.
1026 @item @var{position}
1027 This element indicates where point was at an earlier time. Undoing this
1028 element sets point to @var{position}. Deletion normally creates an
1029 element of this kind as well as a reinsertion element.
1032 This element is a boundary. The elements between two boundaries are
1033 called a @dfn{change group}; normally, each change group corresponds to
1034 one keyboard command, and undo commands normally undo an entire group as
1038 @defun undo-boundary
1039 This function places a boundary element in the undo list. The undo
1040 command stops at such a boundary, and successive undo commands undo
1041 to earlier and earlier boundaries. This function returns @code{nil}.
1043 The editor command loop automatically creates an undo boundary before
1044 each key sequence is executed. Thus, each undo normally undoes the
1045 effects of one command. Self-inserting input characters are an
1046 exception. The command loop makes a boundary for the first such
1047 character; the next 19 consecutive self-inserting input characters do
1048 not make boundaries, and then the 20th does, and so on as long as
1049 self-inserting characters continue.
1051 All buffer modifications add a boundary whenever the previous undoable
1052 change was made in some other buffer. This way, a command that modifies
1053 several buffers makes a boundary in each buffer it changes.
1055 Calling this function explicitly is useful for splitting the effects of
1056 a command into more than one unit. For example, @code{query-replace}
1057 calls @code{undo-boundary} after each replacement, so that the user can
1058 undo individual replacements one by one.
1061 @defun primitive-undo count list
1062 This is the basic function for undoing elements of an undo list.
1063 It undoes the first @var{count} elements of @var{list}, returning
1064 the rest of @var{list}. You could write this function in Lisp,
1065 but it is convenient to have it in C.
1067 @code{primitive-undo} adds elements to the buffer's undo list when it
1068 changes the buffer. Undo commands avoid confusion by saving the undo
1069 list value at the beginning of a sequence of undo operations. Then the
1070 undo operations use and update the saved value. The new elements added
1071 by undoing are not part of this saved value, so they don't interfere with
1075 @node Maintaining Undo
1076 @section Maintaining Undo Lists
1078 This section describes how to enable and disable undo information for
1079 a given buffer. It also explains how the undo list is truncated
1080 automatically so it doesn't get too big.
1082 Recording of undo information in a newly created buffer is normally
1083 enabled to start with; but if the buffer name starts with a space, the
1084 undo recording is initially disabled. You can explicitly enable or
1085 disable undo recording with the following two functions, or by setting
1086 @code{buffer-undo-list} yourself.
1088 @deffn Command buffer-enable-undo &optional buffer-or-name
1089 This command enables recording undo information for buffer
1090 @var{buffer-or-name}, so that subsequent changes can be undone. If no
1091 argument is supplied, then the current buffer is used. This function
1092 does nothing if undo recording is already enabled in the buffer. It
1095 In an interactive call, @var{buffer-or-name} is the current buffer.
1096 You cannot specify any other buffer.
1099 @defun buffer-disable-undo &optional buffer
1100 @defunx buffer-flush-undo &optional buffer
1101 @cindex disable undo
1102 This function discards the undo list of @var{buffer}, and disables
1103 further recording of undo information. As a result, it is no longer
1104 possible to undo either previous changes or any subsequent changes. If
1105 the undo list of @var{buffer} is already disabled, this function
1108 This function returns @code{nil}. It cannot be called interactively.
1110 The name @code{buffer-flush-undo} is not considered obsolete, but the
1111 preferred name is @code{buffer-disable-undo}.
1114 As editing continues, undo lists get longer and longer. To prevent
1115 them from using up all available memory space, garbage collection trims
1116 them back to size limits you can set. (For this purpose, the ``size''
1117 of an undo list measures the cons cells that make up the list, plus the
1118 strings of deleted text.) Two variables control the range of acceptable
1119 sizes: @code{undo-limit} and @code{undo-strong-limit}.
1122 This is the soft limit for the acceptable size of an undo list. The
1123 change group at which this size is exceeded is the last one kept.
1126 @defvar undo-strong-limit
1127 This is the upper limit for the acceptable size of an undo list. The
1128 change group at which this size is exceeded is discarded itself (along
1129 with all older change groups). There is one exception: the very latest
1130 change group is never discarded no matter how big it is.
1134 @comment node-name, next, previous, up
1136 @cindex filling, explicit
1138 @dfn{Filling} means adjusting the lengths of lines (by moving the line
1139 breaks) so that they are nearly (but no greater than) a specified
1140 maximum width. Additionally, lines can be @dfn{justified}, which means
1141 inserting spaces to make the left and/or right margins line up
1142 precisely. The width is controlled by the variable @code{fill-column}.
1143 For ease of reading, lines should be no longer than 70 or so columns.
1145 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1146 automatically as you insert it, but changes to existing text may leave
1147 it improperly filled. Then you must fill the text explicitly.
1149 Most of the commands in this section return values that are not
1150 meaningful. All the functions that do filling take note of the current
1151 left margin, current right margin, and current justification style
1152 (@pxref{Margins}). If the current justification style is
1153 @code{none}, the filling functions don't actually do anything.
1155 Several of the filling functions have an argument @var{justify}.
1156 If it is non-@code{nil}, that requests some kind of justification. It
1157 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
1158 request a specific style of justification. If it is @code{t}, that
1159 means to use the current justification style for this part of the text
1160 (see @code{current-justification}, below). Any other value is treated
1163 When you call the filling functions interactively, using a prefix
1164 argument implies the value @code{full} for @var{justify}.
1166 @deffn Command fill-paragraph justify
1167 @cindex filling a paragraph
1168 This command fills the paragraph at or after point. If
1169 @var{justify} is non-@code{nil}, each line is justified as well.
1170 It uses the ordinary paragraph motion commands to find paragraph
1171 boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}.
1174 @deffn Command fill-region start end &optional justify
1175 This command fills each of the paragraphs in the region from @var{start}
1176 to @var{end}. It justifies as well if @var{justify} is
1179 The variable @code{paragraph-separate} controls how to distinguish
1180 paragraphs. @xref{Standard Regexps}.
1183 @deffn Command fill-individual-paragraphs start end &optional justify mail-flag
1184 This command fills each paragraph in the region according to its
1185 individual fill prefix. Thus, if the lines of a paragraph were indented
1186 with spaces, the filled paragraph will remain indented in the same
1189 The first two arguments, @var{start} and @var{end}, are the beginning
1190 and end of the region to be filled. The third and fourth arguments,
1191 @var{justify} and @var{mail-flag}, are optional. If
1192 @var{justify} is non-@code{nil}, the paragraphs are justified as
1193 well as filled. If @var{mail-flag} is non-@code{nil}, it means the
1194 function is operating on a mail message and therefore should not fill
1197 Ordinarily, @code{fill-individual-paragraphs} regards each change in
1198 indentation as starting a new paragraph. If
1199 @code{fill-individual-varying-indent} is non-@code{nil}, then only
1200 separator lines separate paragraphs. That mode can handle indented
1201 paragraphs with additional indentation on the first line.
1204 @defopt fill-individual-varying-indent
1205 This variable alters the action of @code{fill-individual-paragraphs} as
1209 @deffn Command fill-region-as-paragraph start end &optional justify
1210 This command considers a region of text as a single paragraph and fills
1211 it. If the region was made up of many paragraphs, the blank lines
1212 between paragraphs are removed. This function justifies as well as
1213 filling when @var{justify} is non-@code{nil}.
1215 In an interactive call, any prefix argument requests justification.
1217 In Adaptive Fill mode, which is enabled by default, calling the function
1218 @code{fill-region-as-paragraph} on an indented paragraph when there is
1219 no fill prefix uses the indentation of the second line of the paragraph
1223 @deffn Command justify-current-line how eop nosqueeze
1224 This command inserts spaces between the words of the current line so
1225 that the line ends exactly at @code{fill-column}. It returns
1228 The argument @var{how}, if non-@code{nil} specifies explicitly the style
1229 of justification. It can be @code{left}, @code{right}, @code{full},
1230 @code{center}, or @code{none}. If it is @code{t}, that means to do
1231 follow specified justification style (see @code{current-justification},
1232 below). @code{nil} means to do full justification.
1234 If @var{eop} is non-@code{nil}, that means do left-justification if
1235 @code{current-justification} specifies full justification. This is used
1236 for the last line of a paragraph; even if the paragraph as a whole is
1237 fully justified, the last line should not be.
1239 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1243 @defopt default-justification
1244 This variable's value specifies the style of justification to use for
1245 text that doesn't specify a style with a text property. The possible
1246 values are @code{left}, @code{right}, @code{full}, @code{center}, or
1247 @code{none}. The default value is @code{left}.
1250 @defun current-justification
1251 This function returns the proper justification style to use for filling
1252 the text around point.
1255 @defvar fill-paragraph-function
1256 This variable provides a way for major modes to override the filling of
1257 paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
1258 this function to do the work. If the function returns a non-@code{nil}
1259 value, @code{fill-paragraph} assumes the job is done, and immediately
1262 The usual use of this feature is to fill comments in programming
1263 language modes. If the function needs to fill a paragraph in the usual
1264 way, it can do so as follows:
1267 (let ((fill-paragraph-function nil))
1268 (fill-paragraph arg))
1272 @defvar use-hard-newlines
1273 If this variable is non-@code{nil}, the filling functions do not delete
1274 newlines that have the @code{hard} text property. These ``hard
1275 newlines'' act as paragraph separators.
1279 @section Margins for Filling
1282 This variable specifies a string of text that appears at the beginning
1283 of normal text lines and should be disregarded when filling them. Any
1284 line that fails to start with the fill prefix is considered the start of
1285 a paragraph; so is any line that starts with the fill prefix followed by
1286 additional whitespace. Lines that start with the fill prefix but no
1287 additional whitespace are ordinary text lines that can be filled
1288 together. The resulting filled lines also start with the fill prefix.
1290 The fill prefix follows the left margin whitespace, if any.
1294 This buffer-local variable specifies the maximum width of filled lines.
1295 Its value should be an integer, which is a number of columns. All the
1296 filling, justification, and centering commands are affected by this
1297 variable, including Auto Fill mode (@pxref{Auto Filling}).
1299 As a practical matter, if you are writing text for other people to
1300 read, you should set @code{fill-column} to no more than 70. Otherwise
1301 the line will be too long for people to read comfortably, and this can
1302 make the text seem clumsy.
1305 @defvar default-fill-column
1306 The value of this variable is the default value for @code{fill-column} in
1307 buffers that do not override it. This is the same as
1308 @code{(default-value 'fill-column)}.
1310 The default value for @code{default-fill-column} is 70.
1313 @deffn Command set-left-margin from to margin
1314 This sets the @code{left-margin} property on the text from @var{from} to
1315 @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
1316 command also refills the region to fit the new margin.
1319 @deffn Command set-right-margin from to margin
1320 This sets the @code{right-margin} property on the text from @var{from}
1321 to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
1322 this command also refills the region to fit the new margin.
1325 @defun current-left-margin
1326 This function returns the proper left margin value to use for filling
1327 the text around point. The value is the sum of the @code{left-margin}
1328 property of the character at the start of the current line (or zero if
1329 none), and the value of the variable @code{left-margin}.
1332 @defun current-fill-column
1333 This function returns the proper fill column value to use for filling
1334 the text around point. The value is the value of the @code{fill-column}
1335 variable, minus the value of the @code{right-margin} property of the
1336 character after point.
1339 @deffn Command move-to-left-margin &optional n force
1340 This function moves point to the left margin of the current line. The
1341 column moved to is determined by calling the function
1342 @code{current-left-margin}. If the argument @var{n} is non-@code{nil},
1343 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
1345 If @var{force} is non-@code{nil}, that says to fix the line's
1346 indentation if that doesn't match the left margin value.
1349 @defun delete-to-left-margin from to
1350 This function removes left margin indentation from the text
1351 between @var{from} and @var{to}. The amount of indentation
1352 to delete is determined by calling @code{current-left-margin}.
1353 In no case does this function delete non-whitespace.
1356 @defun indent-to-left-margin
1357 This is the default @code{indent-line-function}, used in Fundamental
1358 mode, Text mode, etc. Its effect is to adjust the indentation at the
1359 beginning of the current line to the value specified by the variable
1360 @code{left-margin}. This may involve either inserting or deleting
1365 This variable specifies the base left margin column. In Fundamental
1366 mode, @kbd{C-j} indents to this column. This variable automatically
1367 becomes buffer-local when set in any fashion.
1370 @tindex fill-nobreak-predicate
1371 @defvar fill-nobreak-predicate
1372 This variable gives major modes a way to specify not to break a line at
1373 certain places. Its value should be a function. This function is
1374 called during filling, with no arguments and with point located at the
1375 place where a break is being considered. If the function returns
1376 non-@code{nil}, then the line won't be broken there.
1380 @comment node-name, next, previous, up
1381 @section Auto Filling
1382 @cindex filling, automatic
1383 @cindex Auto Fill mode
1385 Auto Fill mode is a minor mode that fills lines automatically as text
1386 is inserted. This section describes the hook used by Auto Fill mode.
1387 For a description of functions that you can call explicitly to fill and
1388 justify existing text, see @ref{Filling}.
1390 Auto Fill mode also enables the functions that change the margins and
1391 justification style to refill portions of the text. @xref{Margins}.
1393 @defvar auto-fill-function
1394 The value of this variable should be a function (of no arguments) to be
1395 called after self-inserting a space or a newline. It may be @code{nil},
1396 in which case nothing special is done in that case.
1398 The value of @code{auto-fill-function} is @code{do-auto-fill} when
1399 Auto-Fill mode is enabled. That is a function whose sole purpose is to
1400 implement the usual strategy for breaking a line.
1403 In older Emacs versions, this variable was named @code{auto-fill-hook},
1404 but since it is not called with the standard convention for hooks, it
1405 was renamed to @code{auto-fill-function} in version 19.
1409 @defvar normal-auto-fill-function
1410 This variable specifies the function to use for
1411 @code{auto-fill-function}, if and when Auto Fill is turned on. Major
1412 modes can set buffer-local values for this variable to alter how Auto
1417 @section Sorting Text
1418 @cindex sorting text
1420 The sorting functions described in this section all rearrange text in
1421 a buffer. This is in contrast to the function @code{sort}, which
1422 rearranges the order of the elements of a list (@pxref{Rearrangement}).
1423 The values returned by these functions are not meaningful.
1425 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
1426 This function is the general text-sorting routine that subdivides a
1427 buffer into records and then sorts them. Most of the commands in this
1428 section use this function.
1430 To understand how @code{sort-subr} works, consider the whole accessible
1431 portion of the buffer as being divided into disjoint pieces called
1432 @dfn{sort records}. The records may or may not be contiguous, but they
1433 must not overlap. A portion of each sort record (perhaps all of it) is
1434 designated as the sort key. Sorting rearranges the records in order by
1437 Usually, the records are rearranged in order of ascending sort key.
1438 If the first argument to the @code{sort-subr} function, @var{reverse},
1439 is non-@code{nil}, the sort records are rearranged in order of
1440 descending sort key.
1442 The next four arguments to @code{sort-subr} are functions that are
1443 called to move point across a sort record. They are called many times
1444 from within @code{sort-subr}.
1448 @var{nextrecfun} is called with point at the end of a record. This
1449 function moves point to the start of the next record. The first record
1450 is assumed to start at the position of point when @code{sort-subr} is
1451 called. Therefore, you should usually move point to the beginning of
1452 the buffer before calling @code{sort-subr}.
1454 This function can indicate there are no more sort records by leaving
1455 point at the end of the buffer.
1458 @var{endrecfun} is called with point within a record. It moves point to
1459 the end of the record.
1462 @var{startkeyfun} is called to move point from the start of a record to
1463 the start of the sort key. This argument is optional; if it is omitted,
1464 the whole record is the sort key. If supplied, the function should
1465 either return a non-@code{nil} value to be used as the sort key, or
1466 return @code{nil} to indicate that the sort key is in the buffer
1467 starting at point. In the latter case, @var{endkeyfun} is called to
1468 find the end of the sort key.
1471 @var{endkeyfun} is called to move point from the start of the sort key
1472 to the end of the sort key. This argument is optional. If
1473 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
1474 @code{nil}), then the sort key extends to the end of the record. There
1475 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1476 non-@code{nil} value.
1479 As an example of @code{sort-subr}, here is the complete function
1480 definition for @code{sort-lines}:
1484 ;; @r{Note that the first two lines of doc string}
1485 ;; @r{are effectively one line when viewed by a user.}
1486 (defun sort-lines (reverse beg end)
1487 "Sort lines in region alphabetically;\
1488 argument means descending order.
1489 Called from a program, there are three arguments:
1492 REVERSE (non-nil means reverse order),\
1493 BEG and END (region to sort).
1494 The variable `sort-fold-case' determines\
1495 whether alphabetic case affects
1499 (interactive "P\nr")
1501 (narrow-to-region beg end)
1502 (goto-char (point-min))
1503 (sort-subr reverse 'forward-line 'end-of-line)))
1507 Here @code{forward-line} moves point to the start of the next record,
1508 and @code{end-of-line} moves point to the end of record. We do not pass
1509 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
1510 record is used as the sort key.
1512 The @code{sort-paragraphs} function is very much the same, except that
1513 its @code{sort-subr} call looks like this:
1519 (lambda () (skip-chars-forward "\n \t\f")))
1524 Markers pointing into any sort records are left with no useful
1525 position after @code{sort-subr} returns.
1528 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
1529 This command sorts the region between @var{start} and @var{end}
1530 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
1531 If @var{reverse} is a negative integer, then sorting is in reverse
1534 Alphabetical sorting means that two sort keys are compared by
1535 comparing the first characters of each, the second characters of each,
1536 and so on. If a mismatch is found, it means that the sort keys are
1537 unequal; the sort key whose character is less at the point of first
1538 mismatch is the lesser sort key. The individual characters are compared
1539 according to their numerical character codes in the Emacs character set.
1541 The value of the @var{record-regexp} argument specifies how to divide
1542 the buffer into sort records. At the end of each record, a search is
1543 done for this regular expression, and the text that matches it is taken
1544 as the next record. For example, the regular expression @samp{^.+$},
1545 which matches lines with at least one character besides a newline, would
1546 make each such line into a sort record. @xref{Regular Expressions}, for
1547 a description of the syntax and meaning of regular expressions.
1549 The value of the @var{key-regexp} argument specifies what part of each
1550 record is the sort key. The @var{key-regexp} could match the whole
1551 record, or only a part. In the latter case, the rest of the record has
1552 no effect on the sorted order of records, but it is carried along when
1553 the record moves to its new position.
1555 The @var{key-regexp} argument can refer to the text matched by a
1556 subexpression of @var{record-regexp}, or it can be a regular expression
1559 If @var{key-regexp} is:
1562 @item @samp{\@var{digit}}
1563 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
1564 grouping in @var{record-regexp} is the sort key.
1567 then the whole record is the sort key.
1569 @item a regular expression
1570 then @code{sort-regexp-fields} searches for a match for the regular
1571 expression within the record. If such a match is found, it is the sort
1572 key. If there is no match for @var{key-regexp} within a record then
1573 that record is ignored, which means its position in the buffer is not
1574 changed. (The other records may move around it.)
1577 For example, if you plan to sort all the lines in the region by the
1578 first word on each line starting with the letter @samp{f}, you should
1579 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
1580 @samp{\<f\w*\>}. The resulting expression looks like this:
1584 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
1590 If you call @code{sort-regexp-fields} interactively, it prompts for
1591 @var{record-regexp} and @var{key-regexp} in the minibuffer.
1594 @deffn Command sort-lines reverse start end
1595 This command alphabetically sorts lines in the region between
1596 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1597 is in reverse order.
1600 @deffn Command sort-paragraphs reverse start end
1601 This command alphabetically sorts paragraphs in the region between
1602 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1603 is in reverse order.
1606 @deffn Command sort-pages reverse start end
1607 This command alphabetically sorts pages in the region between
1608 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1609 is in reverse order.
1612 @deffn Command sort-fields field start end
1613 This command sorts lines in the region between @var{start} and
1614 @var{end}, comparing them alphabetically by the @var{field}th field
1615 of each line. Fields are separated by whitespace and numbered starting
1616 from 1. If @var{field} is negative, sorting is by the
1617 @w{@minus{}@var{field}th} field from the end of the line. This command
1618 is useful for sorting tables.
1621 @deffn Command sort-numeric-fields field start end
1622 This command sorts lines in the region between @var{start} and
1623 @var{end}, comparing them numerically by the @var{field}th field of each
1624 line. The specified field must contain a number in each line of the
1625 region. Fields are separated by whitespace and numbered starting from
1626 1. If @var{field} is negative, sorting is by the
1627 @w{@minus{}@var{field}th} field from the end of the line. This command
1628 is useful for sorting tables.
1631 @deffn Command sort-columns reverse &optional beg end
1632 This command sorts the lines in the region between @var{beg} and
1633 @var{end}, comparing them alphabetically by a certain range of columns.
1634 The column positions of @var{beg} and @var{end} bound the range of
1637 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
1639 One unusual thing about this command is that the entire line
1640 containing position @var{beg}, and the entire line containing position
1641 @var{end}, are included in the region sorted.
1643 Note that @code{sort-columns} uses the @code{sort} utility program,
1644 and so cannot work properly on text containing tab characters. Use
1645 @kbd{M-x untabify} to convert tabs to spaces before sorting.
1649 @comment node-name, next, previous, up
1650 @section Counting Columns
1652 @cindex counting columns
1653 @cindex horizontal position
1655 The column functions convert between a character position (counting
1656 characters from the beginning of the buffer) and a column position
1657 (counting screen characters from the beginning of a line).
1659 These functions count each character according to the number of
1660 columns it occupies on the screen. This means control characters count
1661 as occupying 2 or 4 columns, depending upon the value of
1662 @code{ctl-arrow}, and tabs count as occupying a number of columns that
1663 depends on the value of @code{tab-width} and on the column where the tab
1664 begins. @xref{Usual Display}.
1666 Column number computations ignore the width of the window and the
1667 amount of horizontal scrolling. Consequently, a column value can be
1668 arbitrarily high. The first (or leftmost) column is numbered 0.
1670 @defun current-column
1671 This function returns the horizontal position of point, measured in
1672 columns, counting from 0 at the left margin. The column position is the
1673 sum of the widths of all the displayed representations of the characters
1674 between the start of the current line and point.
1676 For an example of using @code{current-column}, see the description of
1677 @code{count-lines} in @ref{Text Lines}.
1680 @defun move-to-column column &optional force
1681 This function moves point to @var{column} in the current line. The
1682 calculation of @var{column} takes into account the widths of the
1683 displayed representations of the characters between the start of the
1686 If column @var{column} is beyond the end of the line, point moves to the
1687 end of the line. If @var{column} is negative, point moves to the
1688 beginning of the line.
1690 If it is impossible to move to column @var{column} because that is in
1691 the middle of a multicolumn character such as a tab, point moves to the
1692 end of that character. However, if @var{force} is non-@code{nil}, and
1693 @var{column} is in the middle of a tab, then @code{move-to-column}
1694 converts the tab into spaces so that it can move precisely to column
1695 @var{column}. Other multicolumn characters can cause anomalies despite
1696 @var{force}, since there is no way to split them.
1698 The argument @var{force} also has an effect if the line isn't long
1699 enough to reach column @var{column}; in that case, it says to add
1700 whitespace at the end of the line to reach that column.
1702 If @var{column} is not an integer, an error is signaled.
1704 The return value is the column number actually moved to.
1708 @section Indentation
1711 The indentation functions are used to examine, move to, and change
1712 whitespace that is at the beginning of a line. Some of the functions
1713 can also change whitespace elsewhere on a line. Columns and indentation
1714 count from zero at the left margin.
1717 * Primitive Indent:: Functions used to count and insert indentation.
1718 * Mode-Specific Indent:: Customize indentation for different modes.
1719 * Region Indent:: Indent all the lines in a region.
1720 * Relative Indent:: Indent the current line based on previous lines.
1721 * Indent Tabs:: Adjustable, typewriter-like tab stops.
1722 * Motion by Indent:: Move to first non-blank character.
1725 @node Primitive Indent
1726 @subsection Indentation Primitives
1728 This section describes the primitive functions used to count and
1729 insert indentation. The functions in the following sections use these
1730 primitives. @xref{Width}, for related functions.
1732 @defun current-indentation
1733 @comment !!Type Primitive Function
1734 @comment !!SourceFile indent.c
1735 This function returns the indentation of the current line, which is
1736 the horizontal position of the first nonblank character. If the
1737 contents are entirely blank, then this is the horizontal position of the
1741 @deffn Command indent-to column &optional minimum
1742 @comment !!Type Primitive Function
1743 @comment !!SourceFile indent.c
1744 This function indents from point with tabs and spaces until @var{column}
1745 is reached. If @var{minimum} is specified and non-@code{nil}, then at
1746 least that many spaces are inserted even if this requires going beyond
1747 @var{column}. Otherwise the function does nothing if point is already
1748 beyond @var{column}. The value is the column at which the inserted
1751 The inserted whitespace characters inherit text properties from the
1752 surrounding text (usually, from the preceding text only). @xref{Sticky
1756 @defopt indent-tabs-mode
1757 @comment !!SourceFile indent.c
1758 If this variable is non-@code{nil}, indentation functions can insert
1759 tabs as well as spaces. Otherwise, they insert only spaces. Setting
1760 this variable automatically makes it buffer-local in the current buffer.
1763 @node Mode-Specific Indent
1764 @subsection Indentation Controlled by Major Mode
1766 An important function of each major mode is to customize the @key{TAB}
1767 key to indent properly for the language being edited. This section
1768 describes the mechanism of the @key{TAB} key and how to control it.
1769 The functions in this section return unpredictable values.
1771 @defvar indent-line-function
1772 This variable's value is the function to be used by @key{TAB} (and
1773 various commands) to indent the current line. The command
1774 @code{indent-according-to-mode} does no more than call this function.
1776 In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C
1777 mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
1778 In Fundamental mode, Text mode, and many other modes with no standard
1779 for indentation, the value is @code{indent-to-left-margin} (which is the
1783 @deffn Command indent-according-to-mode
1784 This command calls the function in @code{indent-line-function} to
1785 indent the current line in a way appropriate for the current major mode.
1788 @deffn Command indent-for-tab-command
1789 This command calls the function in @code{indent-line-function} to indent
1790 the current line; except that if that function is
1791 @code{indent-to-left-margin}, it calls @code{insert-tab} instead. (That
1792 is a trivial command that inserts a tab character.)
1795 @deffn Command newline-and-indent
1796 @comment !!SourceFile simple.el
1797 This function inserts a newline, then indents the new line (the one
1798 following the newline just inserted) according to the major mode.
1800 It does indentation by calling the current @code{indent-line-function}.
1801 In programming language modes, this is the same thing @key{TAB} does,
1802 but in some text modes, where @key{TAB} inserts a tab,
1803 @code{newline-and-indent} indents to the column specified by
1807 @deffn Command reindent-then-newline-and-indent
1808 @comment !!SourceFile simple.el
1809 This command reindents the current line, inserts a newline at point,
1810 and then reindents the new line (the one following the newline just
1813 This command does indentation on both lines according to the current
1814 major mode, by calling the current value of @code{indent-line-function}.
1815 In programming language modes, this is the same thing @key{TAB} does,
1816 but in some text modes, where @key{TAB} inserts a tab,
1817 @code{reindent-then-newline-and-indent} indents to the column specified
1818 by @code{left-margin}.
1822 @subsection Indenting an Entire Region
1824 This section describes commands that indent all the lines in the
1825 region. They return unpredictable values.
1827 @deffn Command indent-region start end to-column
1828 This command indents each nonblank line starting between @var{start}
1829 (inclusive) and @var{end} (exclusive). If @var{to-column} is
1830 @code{nil}, @code{indent-region} indents each nonblank line by calling
1831 the current mode's indentation function, the value of
1832 @code{indent-line-function}.
1834 If @var{to-column} is non-@code{nil}, it should be an integer
1835 specifying the number of columns of indentation; then this function
1836 gives each line exactly that much indentation, by either adding or
1837 deleting whitespace.
1839 If there is a fill prefix, @code{indent-region} indents each line
1840 by making it start with the fill prefix.
1843 @defvar indent-region-function
1844 The value of this variable is a function that can be used by
1845 @code{indent-region} as a short cut. You should design the function so
1846 that it will produce the same results as indenting the lines of the
1847 region one by one, but presumably faster.
1849 If the value is @code{nil}, there is no short cut, and
1850 @code{indent-region} actually works line by line.
1852 A short-cut function is useful in modes such as C mode and Lisp mode,
1853 where the @code{indent-line-function} must scan from the beginning of
1854 the function definition: applying it to each line would be quadratic in
1855 time. The short cut can update the scan information as it moves through
1856 the lines indenting them; this takes linear time. In a mode where
1857 indenting a line individually is fast, there is no need for a short cut.
1859 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
1860 a different meaning and does not use this variable.
1863 @deffn Command indent-rigidly start end count
1864 @comment !!SourceFile indent.el
1865 This command indents all lines starting between @var{start}
1866 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
1867 This ``preserves the shape'' of the affected region, moving it as a
1868 rigid unit. Consequently, this command is useful not only for indenting
1869 regions of unindented text, but also for indenting regions of formatted
1872 For example, if @var{count} is 3, this command adds 3 columns of
1873 indentation to each of the lines beginning in the region specified.
1875 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
1876 @code{indent-rigidly} to indent the text copied from the message being
1880 @defun indent-code-rigidly start end columns &optional nochange-regexp
1881 This is like @code{indent-rigidly}, except that it doesn't alter lines
1882 that start within strings or comments.
1884 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
1885 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
1888 @node Relative Indent
1889 @subsection Indentation Relative to Previous Lines
1891 This section describes two commands that indent the current line
1892 based on the contents of previous lines.
1894 @deffn Command indent-relative &optional unindented-ok
1895 This command inserts whitespace at point, extending to the same
1896 column as the next @dfn{indent point} of the previous nonblank line. An
1897 indent point is a non-whitespace character following whitespace. The
1898 next indent point is the first one at a column greater than the current
1899 column of point. For example, if point is underneath and to the left of
1900 the first non-blank character of a line of text, it moves to that column
1901 by inserting whitespace.
1903 If the previous nonblank line has no next indent point (i.e., none at a
1904 great enough column position), @code{indent-relative} either does
1905 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
1906 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right
1907 of the last column of a short line of text, this command ordinarily
1908 moves point to the next tab stop by inserting whitespace.
1910 The return value of @code{indent-relative} is unpredictable.
1912 In the following example, point is at the beginning of the second
1917 This line is indented twelve spaces.
1918 @point{}The quick brown fox jumped.
1923 Evaluation of the expression @code{(indent-relative nil)} produces the
1928 This line is indented twelve spaces.
1929 @point{}The quick brown fox jumped.
1933 In this next example, point is between the @samp{m} and @samp{p} of
1938 This line is indented twelve spaces.
1939 The quick brown fox jum@point{}ped.
1944 Evaluation of the expression @code{(indent-relative nil)} produces the
1949 This line is indented twelve spaces.
1950 The quick brown fox jum @point{}ped.
1955 @deffn Command indent-relative-maybe
1956 @comment !!SourceFile indent.el
1957 This command indents the current line like the previous nonblank line,
1958 by calling @code{indent-relative} with @code{t} as the
1959 @var{unindented-ok} argument. The return value is unpredictable.
1961 If the previous nonblank line has no indent points beyond the current
1962 column, this command does nothing.
1966 @comment node-name, next, previous, up
1967 @subsection Adjustable ``Tab Stops''
1968 @cindex tabs stops for indentation
1970 This section explains the mechanism for user-specified ``tab stops''
1971 and the mechanisms that use and set them. The name ``tab stops'' is
1972 used because the feature is similar to that of the tab stops on a
1973 typewriter. The feature works by inserting an appropriate number of
1974 spaces and tab characters to reach the next tab stop column; it does not
1975 affect the display of tab characters in the buffer (@pxref{Usual
1976 Display}). Note that the @key{TAB} character as input uses this tab
1977 stop feature only in a few major modes, such as Text mode.
1979 @deffn Command tab-to-tab-stop
1980 This command inserts spaces or tabs before point, up to the next tab
1981 stop column defined by @code{tab-stop-list}. It searches the list for
1982 an element greater than the current column number, and uses that element
1983 as the column to indent to. It does nothing if no such element is
1987 @defopt tab-stop-list
1988 This variable is the list of tab stop columns used by
1989 @code{tab-to-tab-stops}. The elements should be integers in increasing
1990 order. The tab stop columns need not be evenly spaced.
1992 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
1996 @node Motion by Indent
1997 @subsection Indentation-Based Motion Commands
1999 These commands, primarily for interactive use, act based on the
2000 indentation in the text.
2002 @deffn Command back-to-indentation
2003 @comment !!SourceFile simple.el
2004 This command moves point to the first non-whitespace character in the
2005 current line (which is the line in which point is located). It returns
2009 @deffn Command backward-to-indentation arg
2010 @comment !!SourceFile simple.el
2011 This command moves point backward @var{arg} lines and then to the
2012 first nonblank character on that line. It returns @code{nil}.
2015 @deffn Command forward-to-indentation arg
2016 @comment !!SourceFile simple.el
2017 This command moves point forward @var{arg} lines and then to the first
2018 nonblank character on that line. It returns @code{nil}.
2022 @comment node-name, next, previous, up
2023 @section Case Changes
2024 @cindex case conversion in buffers
2026 The case change commands described here work on text in the current
2027 buffer. @xref{Case Conversion}, for case conversion functions that work
2028 on strings and characters. @xref{Case Tables}, for how to customize
2029 which characters are upper or lower case and how to convert them.
2031 @deffn Command capitalize-region start end
2032 This function capitalizes all words in the region defined by
2033 @var{start} and @var{end}. To capitalize means to convert each word's
2034 first character to upper case and convert the rest of each word to lower
2035 case. The function returns @code{nil}.
2037 If one end of the region is in the middle of a word, the part of the
2038 word within the region is treated as an entire word.
2040 When @code{capitalize-region} is called interactively, @var{start} and
2041 @var{end} are point and the mark, with the smallest first.
2045 ---------- Buffer: foo ----------
2046 This is the contents of the 5th foo.
2047 ---------- Buffer: foo ----------
2051 (capitalize-region 1 44)
2054 ---------- Buffer: foo ----------
2055 This Is The Contents Of The 5th Foo.
2056 ---------- Buffer: foo ----------
2061 @deffn Command downcase-region start end
2062 This function converts all of the letters in the region defined by
2063 @var{start} and @var{end} to lower case. The function returns
2066 When @code{downcase-region} is called interactively, @var{start} and
2067 @var{end} are point and the mark, with the smallest first.
2070 @deffn Command upcase-region start end
2071 This function converts all of the letters in the region defined by
2072 @var{start} and @var{end} to upper case. The function returns
2075 When @code{upcase-region} is called interactively, @var{start} and
2076 @var{end} are point and the mark, with the smallest first.
2079 @deffn Command capitalize-word count
2080 This function capitalizes @var{count} words after point, moving point
2081 over as it does. To capitalize means to convert each word's first
2082 character to upper case and convert the rest of each word to lower case.
2083 If @var{count} is negative, the function capitalizes the
2084 @minus{}@var{count} previous words but does not move point. The value
2087 If point is in the middle of a word, the part of the word before point
2088 is ignored when moving forward. The rest is treated as an entire word.
2090 When @code{capitalize-word} is called interactively, @var{count} is
2091 set to the numeric prefix argument.
2094 @deffn Command downcase-word count
2095 This function converts the @var{count} words after point to all lower
2096 case, moving point over as it does. If @var{count} is negative, it
2097 converts the @minus{}@var{count} previous words but does not move point.
2098 The value is @code{nil}.
2100 When @code{downcase-word} is called interactively, @var{count} is set
2101 to the numeric prefix argument.
2104 @deffn Command upcase-word count
2105 This function converts the @var{count} words after point to all upper
2106 case, moving point over as it does. If @var{count} is negative, it
2107 converts the @minus{}@var{count} previous words but does not move point.
2108 The value is @code{nil}.
2110 When @code{upcase-word} is called interactively, @var{count} is set to
2111 the numeric prefix argument.
2114 @node Text Properties
2115 @section Text Properties
2116 @cindex text properties
2117 @cindex attributes of text
2118 @cindex properties of text
2120 Each character position in a buffer or a string can have a @dfn{text
2121 property list}, much like the property list of a symbol (@pxref{Property
2122 Lists}). The properties belong to a particular character at a
2123 particular place, such as, the letter @samp{T} at the beginning of this
2124 sentence or the first @samp{o} in @samp{foo}---if the same character
2125 occurs in two different places, the two occurrences generally have
2126 different properties.
2128 Each property has a name and a value. Both of these can be any Lisp
2129 object, but the name is normally a symbol. The usual way to access the
2130 property list is to specify a name and ask what value corresponds to it.
2132 If a character has a @code{category} property, we call it the
2133 @dfn{category} of the character. It should be a symbol. The properties
2134 of the symbol serve as defaults for the properties of the character.
2136 Copying text between strings and buffers preserves the properties
2137 along with the characters; this includes such diverse functions as
2138 @code{substring}, @code{insert}, and @code{buffer-substring}.
2141 * Examining Properties:: Looking at the properties of one character.
2142 * Changing Properties:: Setting the properties of a range of text.
2143 * Property Search:: Searching for where a property changes value.
2144 * Special Properties:: Particular properties with special meanings.
2145 * Format Properties:: Properties for representing formatting of text.
2146 * Sticky Properties:: How inserted text gets properties from
2148 * Saving Properties:: Saving text properties in files, and reading
2150 * Lazy Properties:: Computing text properties in a lazy fashion
2151 only when text is examined.
2152 * Clickable Text:: Using text properties to make regions of text
2153 do something when you click on them.
2154 * Not Intervals:: Why text properties do not use
2155 Lisp-visible text intervals.
2158 @node Examining Properties
2159 @subsection Examining Text Properties
2161 The simplest way to examine text properties is to ask for the value of
2162 a particular property of a particular character. For that, use
2163 @code{get-text-property}. Use @code{text-properties-at} to get the
2164 entire property list of a character. @xref{Property Search}, for
2165 functions to examine the properties of a number of characters at once.
2167 These functions handle both strings and buffers. Keep in mind that
2168 positions in a string start from 0, whereas positions in a buffer start
2171 @defun get-text-property pos prop &optional object
2172 This function returns the value of the @var{prop} property of the
2173 character after position @var{pos} in @var{object} (a buffer or
2174 string). The argument @var{object} is optional and defaults to the
2177 If there is no @var{prop} property strictly speaking, but the character
2178 has a category that is a symbol, then @code{get-text-property} returns
2179 the @var{prop} property of that symbol.
2182 @defun get-char-property pos prop &optional object
2183 This function is like @code{get-text-property}, except that it checks
2184 overlays first and then text properties. @xref{Overlays}.
2186 The argument @var{object} may be a string, a buffer, or a window. If it
2187 is a window, then the buffer displayed in that window is used for text
2188 properties and overlays, but only the overlays active for that window
2189 are considered. If @var{object} is a buffer, then all overlays in that
2190 buffer are considered, as well as text properties. If @var{object} is a
2191 string, only text properties are considered, since strings never have
2195 @defun text-properties-at position &optional object
2196 This function returns the entire property list of the character at
2197 @var{position} in the string or buffer @var{object}. If @var{object} is
2198 @code{nil}, it defaults to the current buffer.
2201 @defvar default-text-properties
2202 This variable holds a property list giving default values for text
2203 properties. Whenever a character does not specify a value for a
2204 property, neither directly nor through a category symbol, the value
2205 stored in this list is used instead. Here is an example:
2208 (setq default-text-properties '(foo 69))
2209 ;; @r{Make sure character 1 has no properties of its own.}
2210 (set-text-properties 1 2 nil)
2211 ;; @r{What we get, when we ask, is the default value.}
2212 (get-text-property 1 'foo)
2217 @node Changing Properties
2218 @subsection Changing Text Properties
2220 The primitives for changing properties apply to a specified range of
2221 text in a buffer or string. The function @code{set-text-properties}
2222 (see end of section) sets the entire property list of the text in that
2223 range; more often, it is useful to add, change, or delete just certain
2224 properties specified by name.
2226 Since text properties are considered part of the contents of the
2227 buffer (or string), and can affect how a buffer looks on the screen, any
2228 change in buffer text properties mark the buffer as modified. Buffer
2229 text property changes are undoable also (@pxref{Undo}).
2231 @defun put-text-property start end prop value &optional object
2232 This function sets the @var{prop} property to @var{value} for the text
2233 between @var{start} and @var{end} in the string or buffer @var{object}.
2234 If @var{object} is @code{nil}, it defaults to the current buffer.
2237 @defun add-text-properties start end props &optional object
2238 This function adds or overrides text properties for the text between
2239 @var{start} and @var{end} in the string or buffer @var{object}. If
2240 @var{object} is @code{nil}, it defaults to the current buffer.
2242 The argument @var{props} specifies which properties to add. It should
2243 have the form of a property list (@pxref{Property Lists}): a list whose
2244 elements include the property names followed alternately by the
2245 corresponding values.
2247 The return value is @code{t} if the function actually changed some
2248 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2249 its values agree with those in the text).
2251 For example, here is how to set the @code{comment} and @code{face}
2252 properties of a range of text:
2255 (add-text-properties @var{start} @var{end}
2256 '(comment t face highlight))
2260 @defun remove-text-properties start end props &optional object
2261 This function deletes specified text properties from the text between
2262 @var{start} and @var{end} in the string or buffer @var{object}. If
2263 @var{object} is @code{nil}, it defaults to the current buffer.
2265 The argument @var{props} specifies which properties to delete. It
2266 should have the form of a property list (@pxref{Property Lists}): a list
2267 whose elements are property names alternating with corresponding values.
2268 But only the names matter---the values that accompany them are ignored.
2269 For example, here's how to remove the @code{face} property.
2272 (remove-text-properties @var{start} @var{end} '(face nil))
2275 The return value is @code{t} if the function actually changed some
2276 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2277 if no character in the specified text had any of those properties).
2279 To remove all text properties from certain text, use
2280 @code{set-text-properties} and specify @code{nil} for the new property
2284 @defun set-text-properties start end props &optional object
2285 This function completely replaces the text property list for the text
2286 between @var{start} and @var{end} in the string or buffer @var{object}.
2287 If @var{object} is @code{nil}, it defaults to the current buffer.
2289 The argument @var{props} is the new property list. It should be a list
2290 whose elements are property names alternating with corresponding values.
2292 After @code{set-text-properties} returns, all the characters in the
2293 specified range have identical properties.
2295 If @var{props} is @code{nil}, the effect is to get rid of all properties
2296 from the specified range of text. Here's an example:
2299 (set-text-properties @var{start} @var{end} nil)
2303 See also the function @code{buffer-substring-no-properties}
2304 (@pxref{Buffer Contents}) which copies text from the buffer
2305 but does not copy its properties.
2307 @node Property Search
2308 @subsection Text Property Search Functions
2310 In typical use of text properties, most of the time several or many
2311 consecutive characters have the same value for a property. Rather than
2312 writing your programs to examine characters one by one, it is much
2313 faster to process chunks of text that have the same property value.
2315 Here are functions you can use to do this. They use @code{eq} for
2316 comparing property values. In all cases, @var{object} defaults to the
2319 For high performance, it's very important to use the @var{limit}
2320 argument to these functions, especially the ones that search for a
2321 single property---otherwise, they may spend a long time scanning to the
2322 end of the buffer, if the property you are interested in does not change.
2324 These functions do not move point; instead, they return a position (or
2325 @code{nil}). Remember that a position is always between two characters;
2326 the position returned by these functions is between two characters with
2327 different properties.
2329 @defun next-property-change pos &optional object limit
2330 The function scans the text forward from position @var{pos} in the
2331 string or buffer @var{object} till it finds a change in some text
2332 property, then returns the position of the change. In other words, it
2333 returns the position of the first character beyond @var{pos} whose
2334 properties are not identical to those of the character just after
2337 If @var{limit} is non-@code{nil}, then the scan ends at position
2338 @var{limit}. If there is no property change before that point,
2339 @code{next-property-change} returns @var{limit}.
2341 The value is @code{nil} if the properties remain unchanged all the way
2342 to the end of @var{object} and @var{limit} is @code{nil}. If the value
2343 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
2344 The value equals @var{pos} only when @var{limit} equals @var{pos}.
2346 Here is an example of how to scan the buffer by chunks of text within
2347 which all properties are constant:
2351 (let ((plist (text-properties-at (point)))
2353 (or (next-property-change (point) (current-buffer))
2355 @r{Process text from point to @var{next-change}@dots{}}
2356 (goto-char next-change)))
2360 @defun next-single-property-change pos prop &optional object limit
2361 The function scans the text forward from position @var{pos} in the
2362 string or buffer @var{object} till it finds a change in the @var{prop}
2363 property, then returns the position of the change. In other words, it
2364 returns the position of the first character beyond @var{pos} whose
2365 @var{prop} property differs from that of the character just after
2368 If @var{limit} is non-@code{nil}, then the scan ends at position
2369 @var{limit}. If there is no property change before that point,
2370 @code{next-single-property-change} returns @var{limit}.
2372 The value is @code{nil} if the property remains unchanged all the way to
2373 the end of @var{object} and @var{limit} is @code{nil}. If the value is
2374 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
2375 equals @var{pos} only if @var{limit} equals @var{pos}.
2378 @defun previous-property-change pos &optional object limit
2379 This is like @code{next-property-change}, but scans back from @var{pos}
2380 instead of forward. If the value is non-@code{nil}, it is a position
2381 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
2385 @defun previous-single-property-change pos prop &optional object limit
2386 This is like @code{next-single-property-change}, but scans back from
2387 @var{pos} instead of forward. If the value is non-@code{nil}, it is a
2388 position less than or equal to @var{pos}; it equals @var{pos} only if
2389 @var{limit} equals @var{pos}.
2392 @tindex next-char-property-change
2393 @defun next-char-property-change position &optional limit
2394 This is like @code{next-property-change} except that it considers
2395 overlay properties as well as text properties. There is no @var{object}
2396 operand because this function operates only on the current buffer. It
2397 returns the next address at which either kind of property changes.
2400 @tindex previous-char-property-change
2401 @defun previous-char-property-change position &optional limit
2402 This is like @code{next-char-property-change}, but scans back from
2403 @var{position} instead of forward.
2406 @defun text-property-any start end prop value &optional object
2407 This function returns non-@code{nil} if at least one character between
2408 @var{start} and @var{end} has a property @var{prop} whose value is
2409 @var{value}. More precisely, it returns the position of the first such
2410 character. Otherwise, it returns @code{nil}.
2412 The optional fifth argument, @var{object}, specifies the string or
2413 buffer to scan. Positions are relative to @var{object}. The default
2414 for @var{object} is the current buffer.
2417 @defun text-property-not-all start end prop value &optional object
2418 This function returns non-@code{nil} if at least one character between
2419 @var{start} and @var{end} does not have a property @var{prop} with value
2420 @var{value}. More precisely, it returns the position of the first such
2421 character. Otherwise, it returns @code{nil}.
2423 The optional fifth argument, @var{object}, specifies the string or
2424 buffer to scan. Positions are relative to @var{object}. The default
2425 for @var{object} is the current buffer.
2428 @node Special Properties
2429 @subsection Properties with Special Meanings
2431 Here is a table of text property names that have special built-in
2432 meanings. The following sections list a few additional special property
2433 names that control filling and property inheritance. All other names
2434 have no standard meaning, and you can use them as you like.
2437 @cindex category of text character
2438 @kindex category @r{(text property)}
2440 If a character has a @code{category} property, we call it the
2441 @dfn{category} of the character. It should be a symbol. The properties
2442 of the symbol serve as defaults for the properties of the character.
2445 @cindex face codes of text
2446 @kindex face @r{(text property)}
2447 You can use the property @code{face} to control the font and color of
2448 text. Its value is a face name or a list of face names. @xref{Faces},
2449 for more information.
2451 If the property value is a list, elements may also have the form
2452 @code{(foreground-color . @var{color-name})} or @code{(background-color
2453 . @var{color-name})}. These elements specify just the foreground color
2454 or just the background color; therefore, there is no need to create a
2455 face for each color that you want to use.
2457 @xref{Font Lock Mode}, for information on how to update @code{face}
2458 properties automatically based on the contents of the text.
2461 @kindex mouse-face @r{(text property)}
2462 The property @code{mouse-face} is used instead of @code{face} when the
2463 mouse is on or near the character. For this purpose, ``near'' means
2464 that all text between the character and where the mouse is have the same
2465 @code{mouse-face} property value.
2468 @cindex keymap of character
2469 @kindex local-map @r{(text property)}
2470 You can specify a different keymap for some of the text in a buffer by
2471 means of the @code{local-map} property. The property's value for the
2472 character after point, if non-@code{nil}, is used for key lookup instead
2473 of the buffer's local map. If the property value is a symbol, the
2474 symbol's function definition is used as the keymap. @xref{Active
2478 The @code{syntax-table} property overrides what the syntax table says
2479 about this particular character. @xref{Syntax Properties}.
2482 @cindex read-only character
2483 @kindex read-only @r{(text property)}
2484 If a character has the property @code{read-only}, then modifying that
2485 character is not allowed. Any command that would do so gets an error.
2487 Insertion next to a read-only character is an error if inserting
2488 ordinary text there would inherit the @code{read-only} property due to
2489 stickiness. Thus, you can control permission to insert next to
2490 read-only text by controlling the stickiness. @xref{Sticky Properties}.
2492 Since changing properties counts as modifying the buffer, it is not
2493 possible to remove a @code{read-only} property unless you know the
2494 special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
2495 and then remove the property. @xref{Read Only Buffers}.
2498 @kindex invisible @r{(text property)}
2499 A non-@code{nil} @code{invisible} property can make a character invisible
2500 on the screen. @xref{Invisible Text}, for details.
2503 @kindex intangible @r{(text property)}
2504 If a group of consecutive characters have equal and non-@code{nil}
2505 @code{intangible} properties, then you cannot place point between them.
2506 If you try to move point forward into the group, point actually moves to
2507 the end of the group. If you try to move point backward into the group,
2508 point actually moves to the start of the group.
2510 When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
2511 the @code{intangible} property is ignored.
2513 @item modification-hooks
2514 @cindex change hooks for a character
2515 @cindex hooks for changing a character
2516 @kindex modification-hooks @r{(text property)}
2517 If a character has the property @code{modification-hooks}, then its
2518 value should be a list of functions; modifying that character calls all
2519 of those functions. Each function receives two arguments: the beginning
2520 and end of the part of the buffer being modified. Note that if a
2521 particular modification hook function appears on several characters
2522 being modified by a single primitive, you can't predict how many times
2523 the function will be called.
2525 @item insert-in-front-hooks
2526 @itemx insert-behind-hooks
2527 @kindex insert-in-front-hooks @r{(text property)}
2528 @kindex insert-behind-hooks @r{(text property)}
2529 The operation of inserting text in a buffer also calls the functions
2530 listed in the @code{insert-in-front-hooks} property of the following
2531 character and in the @code{insert-behind-hooks} property of the
2532 preceding character. These functions receive two arguments, the
2533 beginning and end of the inserted text. The functions are called
2534 @emph{after} the actual insertion takes place.
2536 See also @ref{Change Hooks}, for other hooks that are called
2537 when you change text in a buffer.
2541 @cindex hooks for motion of point
2542 @kindex point-entered @r{(text property)}
2543 @kindex point-left @r{(text property)}
2544 The special properties @code{point-entered} and @code{point-left}
2545 record hook functions that report motion of point. Each time point
2546 moves, Emacs compares these two property values:
2550 the @code{point-left} property of the character after the old location,
2553 the @code{point-entered} property of the character after the new
2558 If these two values differ, each of them is called (if not @code{nil})
2559 with two arguments: the old value of point, and the new one.
2561 The same comparison is made for the characters before the old and new
2562 locations. The result may be to execute two @code{point-left} functions
2563 (which may be the same function) and/or two @code{point-entered}
2564 functions (which may be the same function). In any case, all the
2565 @code{point-left} functions are called first, followed by all the
2566 @code{point-entered} functions.
2568 It is possible using @code{char-after} to examine characters at various
2569 positions without moving point to those positions. Only an actual
2570 change in the value of point runs these hook functions.
2573 @defvar inhibit-point-motion-hooks
2574 When this variable is non-@code{nil}, @code{point-left} and
2575 @code{point-entered} hooks are not run, and the @code{intangible}
2576 property has no effect. Do not set this variable globally; bind it with
2580 @node Format Properties
2581 @subsection Formatted Text Properties
2583 These text properties affect the behavior of the fill commands. They
2584 are used for representing formatted text. @xref{Filling}, and
2589 If a newline character has this property, it is a ``hard'' newline.
2590 The fill commands do not alter hard newlines and do not move words
2591 across them. However, this property takes effect only if the variable
2592 @code{use-hard-newlines} is non-@code{nil}.
2595 This property specifies an extra right margin for filling this part of the
2599 This property specifies an extra left margin for filling this part of the
2603 This property specifies the style of justification for filling this part
2607 @node Sticky Properties
2608 @subsection Stickiness of Text Properties
2609 @cindex sticky text properties
2610 @cindex inheritance of text properties
2612 Self-inserting characters normally take on the same properties as the
2613 preceding character. This is called @dfn{inheritance} of properties.
2615 In a Lisp program, you can do insertion with inheritance or without,
2616 depending on your choice of insertion primitive. The ordinary text
2617 insertion functions such as @code{insert} do not inherit any properties.
2618 They insert text with precisely the properties of the string being
2619 inserted, and no others. This is correct for programs that copy text
2620 from one context to another---for example, into or out of the kill ring.
2621 To insert with inheritance, use the special primitives described in this
2622 section. Self-inserting characters inherit properties because they work
2623 using these primitives.
2625 When you do insertion with inheritance, @emph{which} properties are
2626 inherited depends on two specific properties: @code{front-sticky} and
2627 @code{rear-nonsticky}.
2629 Insertion after a character inherits those of its properties that are
2630 @dfn{rear-sticky}. Insertion before a character inherits those of its
2631 properties that are @dfn{front-sticky}. By default, a text property is
2632 rear-sticky but not front-sticky. Thus, the default is to inherit all
2633 the properties of the preceding character, and nothing from the
2634 following character. You can request different behavior by specifying
2635 the stickiness of certain properties.
2637 If a character's @code{front-sticky} property is @code{t}, then all
2638 its properties are front-sticky. If the @code{front-sticky} property is
2639 a list, then the sticky properties of the character are those whose
2640 names are in the list. For example, if a character has a
2641 @code{front-sticky} property whose value is @code{(face read-only)},
2642 then insertion before the character can inherit its @code{face} property
2643 and its @code{read-only} property, but no others.
2645 The @code{rear-nonsticky} works the opposite way. Every property is
2646 rear-sticky by default, so the @code{rear-nonsticky} property says which
2647 properties are @emph{not} rear-sticky. If a character's
2648 @code{rear-nonsticky} property is @code{t}, then none of its properties
2649 are rear-sticky. If the @code{rear-nonsticky} property is a list,
2650 properties are rear-sticky @emph{unless} their names are in the list.
2652 When you insert text with inheritance, it inherits all the rear-sticky
2653 properties of the preceding character, and all the front-sticky
2654 properties of the following character. The previous character's
2655 properties take precedence when both sides offer different sticky values
2656 for the same property.
2658 Here are the functions that insert text with inheritance of properties:
2660 @defun insert-and-inherit &rest strings
2661 Insert the strings @var{strings}, just like the function @code{insert},
2662 but inherit any sticky properties from the adjoining text.
2665 @defun insert-before-markers-and-inherit &rest strings
2666 Insert the strings @var{strings}, just like the function
2667 @code{insert-before-markers}, but inherit any sticky properties from the
2671 @xref{Insertion}, for the ordinary insertion functions which do not
2674 @node Saving Properties
2675 @subsection Saving Text Properties in Files
2676 @cindex text properties in files
2677 @cindex saving text properties
2679 You can save text properties in files (along with the text itself),
2680 and restore the same text properties when visiting or inserting the
2681 files, using these two hooks:
2683 @defvar write-region-annotate-functions
2684 This variable's value is a list of functions for @code{write-region} to
2685 run to encode text properties in some fashion as annotations to the text
2686 being written in the file. @xref{Writing to Files}.
2688 Each function in the list is called with two arguments: the start and
2689 end of the region to be written. These functions should not alter the
2690 contents of the buffer. Instead, they should return lists indicating
2691 annotations to write in the file in addition to the text in the
2694 Each function should return a list of elements of the form
2695 @code{(@var{position} . @var{string})}, where @var{position} is an
2696 integer specifying the relative position within the text to be written,
2697 and @var{string} is the annotation to add there.
2699 Each list returned by one of these functions must be already sorted in
2700 increasing order by @var{position}. If there is more than one function,
2701 @code{write-region} merges the lists destructively into one sorted list.
2703 When @code{write-region} actually writes the text from the buffer to the
2704 file, it intermixes the specified annotations at the corresponding
2705 positions. All this takes place without modifying the buffer.
2708 @defvar after-insert-file-functions
2709 This variable holds a list of functions for @code{insert-file-contents}
2710 to call after inserting a file's contents. These functions should scan
2711 the inserted text for annotations, and convert them to the text
2712 properties they stand for.
2714 Each function receives one argument, the length of the inserted text;
2715 point indicates the start of that text. The function should scan that
2716 text for annotations, delete them, and create the text properties that
2717 the annotations specify. The function should return the updated length
2718 of the inserted text, as it stands after those changes. The value
2719 returned by one function becomes the argument to the next function.
2721 These functions should always return with point at the beginning of
2724 The intended use of @code{after-insert-file-functions} is for converting
2725 some sort of textual annotations into actual text properties. But other
2726 uses may be possible.
2729 We invite users to write Lisp programs to store and retrieve text
2730 properties in files, using these hooks, and thus to experiment with
2731 various data formats and find good ones. Eventually we hope users
2732 will produce good, general extensions we can install in Emacs.
2734 We suggest not trying to handle arbitrary Lisp objects as text property
2735 names or values---because a program that general is probably difficult
2736 to write, and slow. Instead, choose a set of possible data types that
2737 are reasonably flexible, and not too hard to encode.
2739 @xref{Format Conversion}, for a related feature.
2741 @c ??? In next edition, merge this info Format Conversion.
2743 @node Lazy Properties
2744 @subsection Lazy Computation of Text Properties
2746 Instead of computing text properties for all the text in the buffer,
2747 you can arrange to compute the text properties for parts of the text
2748 when and if something depends on them.
2750 The primitive that extracts text from the buffer along with its
2751 properties is @code{buffer-substring}. Before examining the properties,
2752 this function runs the abnormal hook @code{buffer-access-fontify-functions}.
2754 @defvar buffer-access-fontify-functions
2755 This variable holds a list of functions for computing text properties.
2756 Before @code{buffer-substring} copies the text and text properties for a
2757 portion of the buffer, it calls all the functions in this list. Each of
2758 the functions receives two arguments that specify the range of the
2759 buffer being accessed. (The buffer itself is always the current
2763 The function @code{buffer-substring-no-properties} does not call these
2764 functions, since it ignores text properties anyway.
2766 In order to prevent the hook functions from being called more than
2767 once for the same part of the buffer, you can use the variable
2768 @code{buffer-access-fontified-property}.
2770 @defvar buffer-access-fontified-property
2771 If this value's variable is non-@code{nil}, it is a symbol which is used
2772 as a text property name. A non-@code{nil} value for that text property
2773 means, ``the other text properties for this character have already been
2776 If all the characters in the range specified for @code{buffer-substring}
2777 have a non-@code{nil} value for this property, @code{buffer-substring}
2778 does not call the @code{buffer-access-fontify-functions} functions. It
2779 assumes these characters already have the right text properties, and
2780 just copies the properties they already have.
2782 The normal way to use this feature is that the
2783 @code{buffer-access-fontify-functions} functions add this property, as
2784 well as others, to the characters they operate on. That way, they avoid
2785 being called over and over for the same text.
2788 @node Clickable Text
2789 @subsection Defining Clickable Text
2790 @cindex clickable text
2792 There are two ways to set up @dfn{clickable text} in a buffer.
2793 There are typically two parts of this: to make the text highlight
2794 when the mouse is over it, and to make a mouse button do something
2795 when you click it on that part of the text.
2797 Highlighting is done with the @code{mouse-face} text property.
2798 Here is an example of how Dired does it:
2802 (if (dired-move-to-filename)
2803 (put-text-property (point)
2805 (dired-move-to-end-of-filename)
2807 'mouse-face 'highlight))
2812 The first two arguments to @code{put-text-property} specify the
2813 beginning and end of the text.
2815 The usual way to make the mouse do something when you click it
2816 on this text is to define @code{mouse-2} in the major mode's
2817 keymap. The job of checking whether the click was on clickable text
2818 is done by the command definition. Here is how Dired does it:
2821 (defun dired-mouse-find-file-other-window (event)
2822 "In dired, visit the file or directory name you click on."
2826 (set-buffer (window-buffer (posn-window (event-end event))))
2828 (goto-char (posn-point (event-end event)))
2829 (setq file (dired-get-filename))))
2830 (select-window (posn-window (event-end event)))
2831 (find-file-other-window (file-name-sans-versions file t))))
2835 The reason for the outer @code{save-excursion} construct is to avoid
2836 changing the current buffer; the reason for the inner one is to avoid
2837 permanently altering point in the buffer you click on. In this case,
2838 Dired uses the function @code{dired-get-filename} to determine which
2839 file to visit, based on the position found in the event.
2841 Instead of defining a mouse command for the major mode, you can define
2842 a key binding for the clickable text itself, using the @code{local-map}
2846 (let ((map (make-sparse-keymap)))
2847 (define-key-binding map [mouse-2] 'operate-this-button)
2848 (put-text-property (point)
2850 (dired-move-to-end-of-filename)
2856 This method makes it possible to define different commands for various
2857 clickable pieces of text. Also, the major mode definition (or the
2858 global definition) remains available for the rest of the text in the
2862 @subsection Why Text Properties are not Intervals
2865 Some editors that support adding attributes to text in the buffer do
2866 so by letting the user specify ``intervals'' within the text, and adding
2867 the properties to the intervals. Those editors permit the user or the
2868 programmer to determine where individual intervals start and end. We
2869 deliberately provided a different sort of interface in Emacs Lisp to
2870 avoid certain paradoxical behavior associated with text modification.
2872 If the actual subdivision into intervals is meaningful, that means you
2873 can distinguish between a buffer that is just one interval with a
2874 certain property, and a buffer containing the same text subdivided into
2875 two intervals, both of which have that property.
2877 Suppose you take the buffer with just one interval and kill part of
2878 the text. The text remaining in the buffer is one interval, and the
2879 copy in the kill ring (and the undo list) becomes a separate interval.
2880 Then if you yank back the killed text, you get two intervals with the
2881 same properties. Thus, editing does not preserve the distinction
2882 between one interval and two.
2884 Suppose we ``fix'' this problem by coalescing the two intervals when
2885 the text is inserted. That works fine if the buffer originally was a
2886 single interval. But suppose instead that we have two adjacent
2887 intervals with the same properties, and we kill the text of one interval
2888 and yank it back. The same interval-coalescence feature that rescues
2889 the other case causes trouble in this one: after yanking, we have just
2890 one interval. One again, editing does not preserve the distinction
2891 between one interval and two.
2893 Insertion of text at the border between intervals also raises
2894 questions that have no satisfactory answer.
2896 However, it is easy to arrange for editing to behave consistently for
2897 questions of the form, ``What are the properties of this character?''
2898 So we have decided these are the only questions that make sense; we have
2899 not implemented asking questions about where intervals start or end.
2901 In practice, you can usually use the text property search functions in
2902 place of explicit interval boundaries. You can think of them as finding
2903 the boundaries of intervals, assuming that intervals are always
2904 coalesced whenever possible. @xref{Property Search}.
2906 Emacs also provides explicit intervals as a presentation feature; see
2910 @section Substituting for a Character Code
2912 The following functions replace characters within a specified region
2913 based on their character codes.
2915 @defun subst-char-in-region start end old-char new-char &optional noundo
2916 @cindex replace characters
2917 This function replaces all occurrences of the character @var{old-char}
2918 with the character @var{new-char} in the region of the current buffer
2919 defined by @var{start} and @var{end}.
2921 @cindex Outline mode
2922 @cindex undo avoidance
2923 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
2924 not record the change for undo and does not mark the buffer as modified.
2925 This feature is used for controlling selective display (@pxref{Selective
2928 @code{subst-char-in-region} does not move point and returns
2933 ---------- Buffer: foo ----------
2934 This is the contents of the buffer before.
2935 ---------- Buffer: foo ----------
2939 (subst-char-in-region 1 20 ?i ?X)
2942 ---------- Buffer: foo ----------
2943 ThXs Xs the contents of the buffer before.
2944 ---------- Buffer: foo ----------
2949 @defun translate-region start end table
2950 This function applies a translation table to the characters in the
2951 buffer between positions @var{start} and @var{end}.
2953 The translation table @var{table} is a string; @code{(aref @var{table}
2954 @var{ochar})} gives the translated character corresponding to
2955 @var{ochar}. If the length of @var{table} is less than 256, any
2956 characters with codes larger than the length of @var{table} are not
2957 altered by the translation.
2959 The return value of @code{translate-region} is the number of
2960 characters that were actually changed by the translation. This does
2961 not count characters that were mapped into themselves in the
2969 A register is a sort of variable used in Emacs editing that can hold a
2970 variety of different kinds of values. Each register is named by a
2971 single character. All ASCII characters and their meta variants (but
2972 with the exception of @kbd{C-g}) can be used to name registers. Thus,
2973 there are 255 possible registers. A register is designated in Emacs
2974 Lisp by the character that is its name.
2976 @defvar register-alist
2977 This variable is an alist of elements of the form @code{(@var{name} .
2978 @var{contents})}. Normally, there is one element for each Emacs
2979 register that has been used.
2981 The object @var{name} is a character (an integer) identifying the
2985 The @var{contents} of a register can have several possible types:
2989 A number stands for itself. If @code{insert-register} finds a number
2990 in the register, it converts the number to decimal.
2993 A marker represents a buffer position to jump to.
2996 A string is text saved in the register.
2999 A rectangle is represented by a list of strings.
3001 @item @code{(@var{window-configuration} @var{position})}
3002 This represents a window configuration to restore in one frame, and a
3003 position to jump to in the current buffer.
3005 @item @code{(@var{frame-configuration} @var{position})}
3006 This represents a frame configuration to restore, and a position
3007 to jump to in the current buffer.
3009 @item (file @var{filename})
3010 This represents a file to visit; jumping to this value visits file
3013 @item (file-query @var{filename} @var{position})
3014 This represents a file to visit and a position in it; jumping to this
3015 value visits file @var{filename} and goes to buffer position
3016 @var{position}. Restoring this type of position asks the user for
3020 The functions in this section return unpredictable values unless
3023 @defun get-register reg
3024 This function returns the contents of the register
3025 @var{reg}, or @code{nil} if it has no contents.
3028 @defun set-register reg value
3029 This function sets the contents of register @var{reg} to @var{value}.
3030 A register can be set to any value, but the other register functions
3031 expect only certain data types. The return value is @var{value}.
3034 @deffn Command view-register reg
3035 This command displays what is contained in register @var{reg}.
3039 @deffn Command point-to-register reg
3040 This command stores both the current location of point and the current
3041 buffer in register @var{reg} as a marker.
3044 @deffn Command jump-to-register reg
3045 @deffnx Command register-to-point reg
3046 @comment !!SourceFile register.el
3047 This command restores the status recorded in register @var{reg}.
3049 If @var{reg} contains a marker, it moves point to the position stored in
3050 the marker. Since both the buffer and the location within the buffer
3051 are stored by the @code{point-to-register} function, this command can
3052 switch you to another buffer.
3054 If @var{reg} contains a window configuration or a frame configuration.
3055 @code{jump-to-register} restores that configuration.
3059 @deffn Command insert-register reg &optional beforep
3060 This command inserts contents of register @var{reg} into the current
3063 Normally, this command puts point before the inserted text, and the
3064 mark after it. However, if the optional second argument @var{beforep}
3065 is non-@code{nil}, it puts the mark before and point after.
3066 You can pass a non-@code{nil} second argument @var{beforep} to this
3067 function interactively by supplying any prefix argument.
3069 If the register contains a rectangle, then the rectangle is inserted
3070 with its upper left corner at point. This means that text is inserted
3071 in the current line and underneath it on successive lines.
3073 If the register contains something other than saved text (a string) or
3074 a rectangle (a list), currently useless things happen. This may be
3075 changed in the future.
3079 @deffn Command copy-to-register reg start end &optional delete-flag
3080 This command copies the region from @var{start} to @var{end} into
3081 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
3082 the region from the buffer after copying it into the register.
3085 @deffn Command prepend-to-register reg start end &optional delete-flag
3086 This command prepends the region from @var{start} to @var{end} into
3087 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
3088 the region from the buffer after copying it to the register.
3091 @deffn Command append-to-register reg start end &optional delete-flag
3092 This command appends the region from @var{start} to @var{end} to the
3093 text already in register @var{reg}. If @var{delete-flag} is
3094 non-@code{nil}, it deletes the region from the buffer after copying it
3098 @deffn Command copy-rectangle-to-register reg start end &optional delete-flag
3099 This command copies a rectangular region from @var{start} to @var{end}
3100 into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it
3101 deletes the region from the buffer after copying it to the register.
3104 @deffn Command window-configuration-to-register reg
3105 This function stores the window configuration of the selected frame in
3109 @deffn Command frame-configuration-to-register reg
3110 This function stores the current frame configuration in register
3116 @section Transposition of Text
3118 This subroutine is used by the transposition commands.
3120 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
3121 This function exchanges two nonoverlapping portions of the buffer.
3122 Arguments @var{start1} and @var{end1} specify the bounds of one portion
3123 and arguments @var{start2} and @var{end2} specify the bounds of the
3126 Normally, @code{transpose-regions} relocates markers with the transposed
3127 text; a marker previously positioned within one of the two transposed
3128 portions moves along with that portion, thus remaining between the same
3129 two characters in their new position. However, if @var{leave-markers}
3130 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
3131 all markers unrelocated.
3135 @section Change Hooks
3136 @cindex change hooks
3137 @cindex hooks for text changes
3139 These hook variables let you arrange to take notice of all changes in
3140 all buffers (or in a particular buffer, if you make them buffer-local).
3141 See also @ref{Special Properties}, for how to detect changes to specific
3144 The functions you use in these hooks should save and restore the match
3145 data if they do anything that uses regular expressions; otherwise, they
3146 will interfere in bizarre ways with the editing operations that call
3149 @defvar before-change-functions
3150 This variable holds a list of functions to call before any buffer
3151 modification. Each function gets two arguments, the beginning and end
3152 of the region that is about to change, represented as integers. The
3153 buffer that is about to change is always the current buffer.
3156 @defvar after-change-functions
3157 This variable holds a list of functions to call after any buffer
3158 modification. Each function receives three arguments: the beginning and
3159 end of the region just changed, and the length of the text that existed
3160 before the change. All three arguments are integers. The buffer that's
3161 about to change is always the current buffer.
3163 The length of the old text is measured in bytes; it is the difference
3164 between the buffer positions before and after that text, before the
3165 change. As for the changed text, its length in bytes is simply the
3166 difference between the first two arguments. If you want the length
3167 in @emph{characters} of the text before the change, you should use
3168 a @code{before-change-functions} function that calls @code{chars-in-region}
3169 (@pxref{Chars and Bytes}).
3172 @tindex combine-after-change-calls
3173 @defmac combine-after-change-calls body...
3174 The macro executes @var{body} normally, but arranges to call the
3175 after-change functions just once for a series of several changes---if
3178 If a program makes several text changes in the same area of the buffer,
3179 using the macro @code{combine-after-change-calls} around that part of
3180 the program can make it run considerably faster when after-change hooks
3181 are in use. When the after-change hooks are ultimately called, the
3182 arguments specify a portion of the buffer including all of the changes
3183 made within the @code{combine-after-change-calls} body.
3185 @strong{Warning:} You must not alter the values of
3186 @code{after-change-functions} and @code{after-change-function} within
3187 the body of a @code{combine-after-change-calls} form.
3189 @strong{Note:} If the changes you combine occur in widely scattered
3190 parts of the buffer, this will still work, but it is not advisable,
3191 because it may lead to inefficient behavior for some change hook
3195 @defvar before-change-function
3196 This obsolete variable holds one function to call before any buffer
3197 modification (or @code{nil} for no function). It is called just like
3198 the functions in @code{before-change-functions}.
3201 @defvar after-change-function
3202 This obsolete variable holds one function to call after any buffer modification
3203 (or @code{nil} for no function). It is called just like the functions in
3204 @code{after-change-functions}.
3207 The four variables above are temporarily bound to @code{nil} during the
3208 time that any of these functions is running. This means that if one of
3209 these functions changes the buffer, that change won't run these
3210 functions. If you do want a hook function to make changes that run
3211 these functions, make it bind these variables back to their usual
3214 One inconvenient result of this protective feature is that you cannot
3215 have a function in @code{after-change-functions} or
3216 @code{before-change-functions} which changes the value of that variable.
3217 But that's not a real limitation. If you want those functions to change
3218 the list of functions to run, simply add one fixed function to the hook,
3219 and code that function to look in another variable for other functions
3220 to call. Here is an example:
3223 (setq my-own-after-change-functions nil)
3224 (defun indirect-after-change-function (beg end len)
3225 (let ((list my-own-after-change-functions))
3227 (funcall (car list) beg end len)
3228 (setq list (cdr list)))))
3231 (add-hooks 'after-change-functions
3232 'indirect-after-change-function)
3236 @defvar first-change-hook
3237 This variable is a normal hook that is run whenever a buffer is changed
3238 that was previously in the unmodified state.