2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
4 @c 2000, 2001, 2004, 2005
5 @c Free Software Foundation, Inc.
6 @c See the file elisp.texi for copying conditions.
7 @setfilename ../info/text
8 @node Text, Non-ASCII Characters, Markers, Top
12 This chapter describes the functions that deal with the text in a
13 buffer. Most examine, insert, or delete text in the current buffer,
14 often operating at point or on text adjacent to point. Many are
15 interactive. All the functions that change the text provide for undoing
16 the changes (@pxref{Undo}).
18 Many text-related functions operate on a region of text defined by two
19 buffer positions passed in arguments named @var{start} and @var{end}.
20 These arguments should be either markers (@pxref{Markers}) or numeric
21 character positions (@pxref{Positions}). The order of these arguments
22 does not matter; it is all right for @var{start} to be the end of the
23 region and @var{end} the beginning. For example, @code{(delete-region 1
24 10)} and @code{(delete-region 10 1)} are equivalent. An
25 @code{args-out-of-range} error is signaled if either @var{start} or
26 @var{end} is outside the accessible portion of the buffer. In an
27 interactive call, point and the mark are used for these arguments.
29 @cindex buffer contents
30 Throughout this chapter, ``text'' refers to the characters in the
31 buffer, together with their properties (when relevant). Keep in mind
32 that point is always between two characters, and the cursor appears on
33 the character after point.
36 * Near Point:: Examining text in the vicinity of point.
37 * Buffer Contents:: Examining text in a general fashion.
38 * Comparing Text:: Comparing substrings of buffers.
39 * Insertion:: Adding new text to a buffer.
40 * Commands for Insertion:: User-level commands to insert text.
41 * Deletion:: Removing text from a buffer.
42 * User-Level Deletion:: User-level commands to delete text.
43 * The Kill Ring:: Where removed text sometimes is saved for later use.
44 * Undo:: Undoing changes to the text of a buffer.
45 * Maintaining Undo:: How to enable and disable undo information.
46 How to control how much information is kept.
47 * Filling:: Functions for explicit filling.
48 * Margins:: How to specify margins for filling commands.
49 * Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context.
50 * Auto Filling:: How auto-fill mode is implemented to break lines.
51 * Sorting:: Functions for sorting parts of the buffer.
52 * Columns:: Computing horizontal positions, and using them.
53 * Indentation:: Functions to insert or adjust indentation.
54 * Case Changes:: Case conversion of parts of the buffer.
55 * Text Properties:: Assigning Lisp property lists to text characters.
56 * Substitution:: Replacing a given character wherever it appears.
57 * Transposition:: Swapping two portions of a buffer.
58 * Registers:: How registers are implemented. Accessing the text or
59 position stored in a register.
60 * Base 64:: Conversion to or from base 64 encoding.
61 * MD5 Checksum:: Compute the MD5 ``message digest''/``checksum''.
62 * Atomic Changes:: Installing several buffer changes ``atomically''.
63 * Change Hooks:: Supplying functions to be run when text is changed.
67 @section Examining Text Near Point
69 Many functions are provided to look at the characters around point.
70 Several simple functions are described here. See also @code{looking-at}
71 in @ref{Regexp Search}.
73 In the following four functions, ``beginning'' or ``end'' of buffer
74 refers to the beginning or end of the accessible portion.
76 @defun char-after &optional position
77 This function returns the character in the current buffer at (i.e.,
78 immediately after) position @var{position}. If @var{position} is out of
79 range for this purpose, either before the beginning of the buffer, or at
80 or beyond the end, then the value is @code{nil}. The default for
81 @var{position} is point.
83 In the following example, assume that the first character in the
88 (char-to-string (char-after 1))
94 @defun char-before &optional position
95 This function returns the character in the current buffer immediately
96 before position @var{position}. If @var{position} is out of range for
97 this purpose, either at or before the beginning of the buffer, or beyond
98 the end, then the value is @code{nil}. The default for
99 @var{position} is point.
102 @defun following-char
103 This function returns the character following point in the current
104 buffer. This is similar to @code{(char-after (point))}. However, if
105 point is at the end of the buffer, then @code{following-char} returns 0.
107 Remember that point is always between characters, and the terminal
108 cursor normally appears over the character following point. Therefore,
109 the character returned by @code{following-char} is the character the
112 In this example, point is between the @samp{a} and the @samp{c}.
116 ---------- Buffer: foo ----------
117 Gentlemen may cry ``Pea@point{}ce! Peace!,''
118 but there is no peace.
119 ---------- Buffer: foo ----------
123 (char-to-string (preceding-char))
125 (char-to-string (following-char))
131 @defun preceding-char
132 This function returns the character preceding point in the current
133 buffer. See above, under @code{following-char}, for an example. If
134 point is at the beginning of the buffer, @code{preceding-char} returns
139 This function returns @code{t} if point is at the beginning of the
140 buffer. If narrowing is in effect, this means the beginning of the
141 accessible portion of the text. See also @code{point-min} in
146 This function returns @code{t} if point is at the end of the buffer.
147 If narrowing is in effect, this means the end of accessible portion of
148 the text. See also @code{point-max} in @xref{Point}.
152 This function returns @code{t} if point is at the beginning of a line.
153 @xref{Text Lines}. The beginning of the buffer (or of its accessible
154 portion) always counts as the beginning of a line.
158 This function returns @code{t} if point is at the end of a line. The
159 end of the buffer (or of its accessible portion) is always considered
163 @node Buffer Contents
164 @section Examining Buffer Contents
166 This section describes functions that allow a Lisp program to
167 convert any portion of the text in the buffer into a string.
169 @defun buffer-substring start end
170 This function returns a string containing a copy of the text of the
171 region defined by positions @var{start} and @var{end} in the current
172 buffer. If the arguments are not positions in the accessible portion of
173 the buffer, @code{buffer-substring} signals an @code{args-out-of-range}
176 It is not necessary for @var{start} to be less than @var{end}; the
177 arguments can be given in either order. But most often the smaller
178 argument is written first.
180 If the text being copied has any text properties, these are copied into
181 the string along with the characters they belong to. @xref{Text
182 Properties}. However, overlays (@pxref{Overlays}) in the buffer and
183 their properties are ignored, not copied.
187 ---------- Buffer: foo ----------
188 This is the contents of buffer foo
190 ---------- Buffer: foo ----------
194 (buffer-substring 1 10)
195 @result{} "This is t"
198 (buffer-substring (point-max) 10)
199 @result{} "he contents of buffer foo
205 @defun buffer-substring-no-properties start end
206 This is like @code{buffer-substring}, except that it does not copy text
207 properties, just the characters themselves. @xref{Text Properties}.
211 This function returns the contents of the entire accessible portion of
212 the current buffer as a string. It is equivalent to
215 (buffer-substring (point-min) (point-max))
220 ---------- Buffer: foo ----------
221 This is the contents of buffer foo
223 ---------- Buffer: foo ----------
226 @result{} "This is the contents of buffer foo
233 @defun current-word &optional strict really-word
234 This function returns the symbol (or word) at or near point, as a string.
235 The return value includes no text properties.
237 If the optional argument @var{really-word} is non-@code{nil}, it finds a
238 word; otherwise, it finds a symbol (which includes both word
239 characters and symbol constituent characters).
241 If the optional argument @var{strict} is non-@code{nil}, then point
242 must be in or next to the symbol or word---if no symbol or word is
243 there, the function returns @code{nil}. Otherwise, a nearby symbol or
244 word on the same line is acceptable.
247 @defun thing-at-point thing
248 Return the @var{thing} around or next to point, as a string.
250 The argument @var{thing} is a symbol which specifies a kind of syntactic
251 entity. Possibilities include @code{symbol}, @code{list}, @code{sexp},
252 @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
253 @code{whitespace}, @code{line}, @code{page}, and others.
256 ---------- Buffer: foo ----------
257 Gentlemen may cry ``Pea@point{}ce! Peace!,''
258 but there is no peace.
259 ---------- Buffer: foo ----------
261 (thing-at-point 'word)
263 (thing-at-point 'line)
264 @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
265 (thing-at-point 'whitespace)
271 @section Comparing Text
272 @cindex comparing buffer text
274 This function lets you compare portions of the text in a buffer, without
275 copying them into strings first.
277 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
278 This function lets you compare two substrings of the same buffer or two
279 different buffers. The first three arguments specify one substring,
280 giving a buffer (or a buffer name) and two positions within the
281 buffer. The last three arguments specify the other substring in the
282 same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or
283 both to stand for the current buffer.
285 The value is negative if the first substring is less, positive if the
286 first is greater, and zero if they are equal. The absolute value of
287 the result is one plus the index of the first differing characters
288 within the substrings.
290 This function ignores case when comparing characters
291 if @code{case-fold-search} is non-@code{nil}. It always ignores
294 Suppose the current buffer contains the text @samp{foobarbar
295 haha!rara!}; then in this example the two substrings are @samp{rbar }
296 and @samp{rara!}. The value is 2 because the first substring is greater
297 at the second character.
300 (compare-buffer-substrings nil 6 11 nil 16 21)
306 @section Inserting Text
307 @cindex insertion of text
308 @cindex text insertion
310 @cindex insertion before point
311 @cindex before point, insertion
312 @dfn{Insertion} means adding new text to a buffer. The inserted text
313 goes at point---between the character before point and the character
314 after point. Some insertion functions leave point before the inserted
315 text, while other functions leave it after. We call the former
316 insertion @dfn{after point} and the latter insertion @dfn{before point}.
318 Insertion relocates markers that point at positions after the
319 insertion point, so that they stay with the surrounding text
320 (@pxref{Markers}). When a marker points at the place of insertion,
321 insertion may or may not relocate the marker, depending on the marker's
322 insertion type (@pxref{Marker Insertion Types}). Certain special
323 functions such as @code{insert-before-markers} relocate all such markers
324 to point after the inserted text, regardless of the markers' insertion
327 Insertion functions signal an error if the current buffer is
328 read-only or if they insert within read-only text.
330 These functions copy text characters from strings and buffers along
331 with their properties. The inserted characters have exactly the same
332 properties as the characters they were copied from. By contrast,
333 characters specified as separate arguments, not part of a string or
334 buffer, inherit their text properties from the neighboring text.
336 The insertion functions convert text from unibyte to multibyte in
337 order to insert in a multibyte buffer, and vice versa---if the text
338 comes from a string or from a buffer. However, they do not convert
339 unibyte character codes 128 through 255 to multibyte characters, not
340 even if the current buffer is a multibyte buffer. @xref{Converting
343 @defun insert &rest args
344 This function inserts the strings and/or characters @var{args} into the
345 current buffer, at point, moving point forward. In other words, it
346 inserts the text before point. An error is signaled unless all
347 @var{args} are either strings or characters. The value is @code{nil}.
350 @defun insert-before-markers &rest args
351 This function inserts the strings and/or characters @var{args} into the
352 current buffer, at point, moving point forward. An error is signaled
353 unless all @var{args} are either strings or characters. The value is
356 This function is unlike the other insertion functions in that it
357 relocates markers initially pointing at the insertion point, to point
358 after the inserted text. If an overlay begins at the insertion point,
359 the inserted text falls outside the overlay; if a nonempty overlay
360 ends at the insertion point, the inserted text falls inside that
364 @defun insert-char character count &optional inherit
365 This function inserts @var{count} instances of @var{character} into the
366 current buffer before point. The argument @var{count} should be a
367 number, and @var{character} must be a character. The value is @code{nil}.
369 This function does not convert unibyte character codes 128 through 255
370 to multibyte characters, not even if the current buffer is a multibyte
371 buffer. @xref{Converting Representations}.
373 If @var{inherit} is non-@code{nil}, then the inserted characters inherit
374 sticky text properties from the two characters before and after the
375 insertion point. @xref{Sticky Properties}.
378 @defun insert-buffer-substring from-buffer-or-name &optional start end
379 This function inserts a portion of buffer @var{from-buffer-or-name}
380 (which must already exist) into the current buffer before point. The
381 text inserted is the region between @var{start} and @var{end}. (These
382 arguments default to the beginning and end of the accessible portion of
383 that buffer.) This function returns @code{nil}.
385 In this example, the form is executed with buffer @samp{bar} as the
386 current buffer. We assume that buffer @samp{bar} is initially empty.
390 ---------- Buffer: foo ----------
391 We hold these truths to be self-evident, that all
392 ---------- Buffer: foo ----------
396 (insert-buffer-substring "foo" 1 20)
399 ---------- Buffer: bar ----------
400 We hold these truth@point{}
401 ---------- Buffer: bar ----------
406 @defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
407 This is like @code{insert-buffer-substring} except that it does not
408 copy any text properties.
411 @xref{Sticky Properties}, for other insertion functions that inherit
412 text properties from the nearby text in addition to inserting it.
413 Whitespace inserted by indentation functions also inherits text
416 @node Commands for Insertion
417 @section User-Level Insertion Commands
419 This section describes higher-level commands for inserting text,
420 commands intended primarily for the user but useful also in Lisp
423 @deffn Command insert-buffer from-buffer-or-name
424 This command inserts the entire accessible contents of
425 @var{from-buffer-or-name} (which must exist) into the current buffer
426 after point. It leaves the mark after the inserted text. The value
430 @deffn Command self-insert-command count
431 @cindex character insertion
432 @cindex self-insertion
433 This command inserts the last character typed; it does so @var{count}
434 times, before point, and returns @code{nil}. Most printing characters
435 are bound to this command. In routine use, @code{self-insert-command}
436 is the most frequently called function in Emacs, but programs rarely use
437 it except to install it on a keymap.
439 In an interactive call, @var{count} is the numeric prefix argument.
441 This command calls @code{auto-fill-function} whenever that is
442 non-@code{nil} and the character inserted is in the table
443 @code{auto-fill-chars} (@pxref{Auto Filling}).
445 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
446 This command performs abbrev expansion if Abbrev mode is enabled and
447 the inserted character does not have word-constituent
448 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
450 This is also responsible for calling @code{blink-paren-function} when
451 the inserted character has close parenthesis syntax (@pxref{Blinking}).
453 Do not try substituting your own definition of
454 @code{self-insert-command} for the standard one. The editor command
455 loop handles this function specially.
458 @deffn Command newline &optional number-of-newlines
459 This command inserts newlines into the current buffer before point.
460 If @var{number-of-newlines} is supplied, that many newline characters
463 @cindex newline and Auto Fill mode
464 This function calls @code{auto-fill-function} if the current column
465 number is greater than the value of @code{fill-column} and
466 @var{number-of-newlines} is @code{nil}. Typically what
467 @code{auto-fill-function} does is insert a newline; thus, the overall
468 result in this case is to insert two newlines at different places: one
469 at point, and another earlier in the line. @code{newline} does not
470 auto-fill if @var{number-of-newlines} is non-@code{nil}.
472 This command indents to the left margin if that is not zero.
475 The value returned is @code{nil}. In an interactive call, @var{count}
476 is the numeric prefix argument.
479 @deffn Command split-line
480 This command splits the current line, moving the portion of the line
481 after point down vertically so that it is on the next line directly
482 below where it was before. Whitespace is inserted as needed at the
483 beginning of the lower line, using the @code{indent-to} function.
484 @code{split-line} returns the position of point.
486 Programs hardly ever use this function.
489 @defvar overwrite-mode
490 This variable controls whether overwrite mode is in effect. The value
491 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
492 or @code{nil}. @code{overwrite-mode-textual} specifies textual
493 overwrite mode (treats newlines and tabs specially), and
494 @code{overwrite-mode-binary} specifies binary overwrite mode (treats
495 newlines and tabs like any other characters).
499 @section Deleting Text
501 @cindex deletion vs killing
502 Deletion means removing part of the text in a buffer, without saving
503 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
504 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
505 Some deletion functions do save text in the kill ring in some special
508 All of the deletion functions operate on the current buffer.
510 @deffn Command erase-buffer
511 This function deletes the entire text of the current buffer
512 (@emph{not} just the accessible portion), leaving it
513 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
514 error; if some of the text in it is read-only, it signals a
515 @code{text-read-only} error. Otherwise, it deletes the text without
516 asking for any confirmation. It returns @code{nil}.
518 Normally, deleting a large amount of text from a buffer inhibits further
519 auto-saving of that buffer ``because it has shrunk''. However,
520 @code{erase-buffer} does not do this, the idea being that the future
521 text is not really related to the former text, and its size should not
522 be compared with that of the former text.
525 @deffn Command delete-region start end
526 This command deletes the text between positions @var{start} and
527 @var{end} in the current buffer, and returns @code{nil}. If point was
528 inside the deleted region, its value afterward is @var{start}.
529 Otherwise, point relocates with the surrounding text, as markers do.
532 @defun delete-and-extract-region start end
533 @tindex delete-and-extract-region
534 This function deletes the text between positions @var{start} and
535 @var{end} in the current buffer, and returns a string containing the
538 If point was inside the deleted region, its value afterward is
539 @var{start}. Otherwise, point relocates with the surrounding text, as
543 @deffn Command delete-char count &optional killp
544 This command deletes @var{count} characters directly after point, or
545 before point if @var{count} is negative. If @var{killp} is
546 non-@code{nil}, then it saves the deleted characters in the kill ring.
548 In an interactive call, @var{count} is the numeric prefix argument, and
549 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
550 argument is supplied, the text is saved in the kill ring. If no prefix
551 argument is supplied, then one character is deleted, but not saved in
554 The value returned is always @code{nil}.
557 @deffn Command delete-backward-char count &optional killp
558 @cindex delete previous char
559 This command deletes @var{count} characters directly before point, or
560 after point if @var{count} is negative. If @var{killp} is
561 non-@code{nil}, then it saves the deleted characters in the kill ring.
563 In an interactive call, @var{count} is the numeric prefix argument, and
564 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
565 argument is supplied, the text is saved in the kill ring. If no prefix
566 argument is supplied, then one character is deleted, but not saved in
569 The value returned is always @code{nil}.
572 @deffn Command backward-delete-char-untabify count &optional killp
574 This command deletes @var{count} characters backward, changing tabs
575 into spaces. When the next character to be deleted is a tab, it is
576 first replaced with the proper number of spaces to preserve alignment
577 and then one of those spaces is deleted instead of the tab. If
578 @var{killp} is non-@code{nil}, then the command saves the deleted
579 characters in the kill ring.
581 Conversion of tabs to spaces happens only if @var{count} is positive.
582 If it is negative, exactly @minus{}@var{count} characters after point
585 In an interactive call, @var{count} is the numeric prefix argument, and
586 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
587 argument is supplied, the text is saved in the kill ring. If no prefix
588 argument is supplied, then one character is deleted, but not saved in
591 The value returned is always @code{nil}.
594 @defopt backward-delete-char-untabify-method
595 This option specifies how @code{backward-delete-char-untabify} should
596 deal with whitespace. Possible values include @code{untabify}, the
597 default, meaning convert a tab to many spaces and delete one;
598 @code{hungry}, meaning delete all tabs and spaces before point with
599 one command; @code{all} meaning delete all tabs, spaces and newlines
600 before point, and @code{nil}, meaning do nothing special for
601 whitespace characters.
604 @node User-Level Deletion
605 @section User-Level Deletion Commands
607 This section describes higher-level commands for deleting text,
608 commands intended primarily for the user but useful also in Lisp
611 @deffn Command delete-horizontal-space &optional backward-only
612 @cindex deleting whitespace
613 This function deletes all spaces and tabs around point. It returns
616 If @var{backward-only} is non-@code{nil}, the function deletes
617 spaces and tabs before point, but not after point.
619 In the following examples, we call @code{delete-horizontal-space} four
620 times, once on each line, with point between the second and third
621 characters on the line each time.
625 ---------- Buffer: foo ----------
630 ---------- Buffer: foo ----------
634 (delete-horizontal-space) ; @r{Four times.}
637 ---------- Buffer: foo ----------
642 ---------- Buffer: foo ----------
647 @deffn Command delete-indentation &optional join-following-p
648 This function joins the line point is on to the previous line, deleting
649 any whitespace at the join and in some cases replacing it with one
650 space. If @var{join-following-p} is non-@code{nil},
651 @code{delete-indentation} joins this line to the following line
652 instead. The function returns @code{nil}.
654 If there is a fill prefix, and the second of the lines being joined
655 starts with the prefix, then @code{delete-indentation} deletes the
656 fill prefix before joining the lines. @xref{Margins}.
658 In the example below, point is located on the line starting
659 @samp{events}, and it makes no difference if there are trailing spaces
660 in the preceding line.
664 ---------- Buffer: foo ----------
665 When in the course of human
666 @point{} events, it becomes necessary
667 ---------- Buffer: foo ----------
674 ---------- Buffer: foo ----------
675 When in the course of human@point{} events, it becomes necessary
676 ---------- Buffer: foo ----------
680 After the lines are joined, the function @code{fixup-whitespace} is
681 responsible for deciding whether to leave a space at the junction.
684 @deffn Command fixup-whitespace
685 This function replaces all the horizontal whitespace surrounding point
686 with either one space or no space, according to the context. It
689 At the beginning or end of a line, the appropriate amount of space is
690 none. Before a character with close parenthesis syntax, or after a
691 character with open parenthesis or expression-prefix syntax, no space is
692 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
695 In the example below, @code{fixup-whitespace} is called the first time
696 with point before the word @samp{spaces} in the first line. For the
697 second invocation, point is directly after the @samp{(}.
701 ---------- Buffer: foo ----------
702 This has too many @point{}spaces
703 This has too many spaces at the start of (@point{} this list)
704 ---------- Buffer: foo ----------
715 ---------- Buffer: foo ----------
716 This has too many spaces
717 This has too many spaces at the start of (this list)
718 ---------- Buffer: foo ----------
723 @deffn Command just-one-space &optional n
724 @comment !!SourceFile simple.el
725 This command replaces any spaces and tabs around point with a single
726 space, or @var{n} spaces if @var{n} is specified. It returns
730 @deffn Command delete-blank-lines
731 This function deletes blank lines surrounding point. If point is on a
732 blank line with one or more blank lines before or after it, then all but
733 one of them are deleted. If point is on an isolated blank line, then it
734 is deleted. If point is on a nonblank line, the command deletes all
735 blank lines immediately following it.
737 A blank line is defined as a line containing only tabs and spaces.
739 @code{delete-blank-lines} returns @code{nil}.
743 @section The Kill Ring
746 @dfn{Kill functions} delete text like the deletion functions, but save
747 it so that the user can reinsert it by @dfn{yanking}. Most of these
748 functions have @samp{kill-} in their name. By contrast, the functions
749 whose names start with @samp{delete-} normally do not save text for
750 yanking (though they can still be undone); these are ``deletion''
753 Most of the kill commands are primarily for interactive use, and are
754 not described here. What we do describe are the functions provided for
755 use in writing such commands. You can use these functions to write
756 commands for killing text. When you need to delete text for internal
757 purposes within a Lisp function, you should normally use deletion
758 functions, so as not to disturb the kill ring contents.
761 Killed text is saved for later yanking in the @dfn{kill ring}. This
762 is a list that holds a number of recent kills, not just the last text
763 kill. We call this a ``ring'' because yanking treats it as having
764 elements in a cyclic order. The list is kept in the variable
765 @code{kill-ring}, and can be operated on with the usual functions for
766 lists; there are also specialized functions, described in this section,
767 that treat it as a ring.
769 Some people think this use of the word ``kill'' is unfortunate, since
770 it refers to operations that specifically @emph{do not} destroy the
771 entities ``killed''. This is in sharp contrast to ordinary life, in
772 which death is permanent and ``killed'' entities do not come back to
773 life. Therefore, other metaphors have been proposed. For example, the
774 term ``cut ring'' makes sense to people who, in pre-computer days, used
775 scissors and paste to cut up and rearrange manuscripts. However, it
776 would be difficult to change the terminology now.
779 * Kill Ring Concepts:: What text looks like in the kill ring.
780 * Kill Functions:: Functions that kill text.
781 * Yanking:: How yanking is done.
782 * Yank Commands:: Commands that access the kill ring.
783 * Low-Level Kill Ring:: Functions and variables for kill ring access.
784 * Internals of Kill Ring:: Variables that hold kill ring data.
787 @node Kill Ring Concepts
788 @comment node-name, next, previous, up
789 @subsection Kill Ring Concepts
791 The kill ring records killed text as strings in a list, most recent
792 first. A short kill ring, for example, might look like this:
795 ("some text" "a different piece of text" "even older text")
799 When the list reaches @code{kill-ring-max} entries in length, adding a
800 new entry automatically deletes the last entry.
802 When kill commands are interwoven with other commands, each kill
803 command makes a new entry in the kill ring. Multiple kill commands in
804 succession build up a single kill ring entry, which would be yanked as a
805 unit; the second and subsequent consecutive kill commands add text to
806 the entry made by the first one.
808 For yanking, one entry in the kill ring is designated the ``front'' of
809 the ring. Some yank commands ``rotate'' the ring by designating a
810 different element as the ``front.'' But this virtual rotation doesn't
811 change the list itself---the most recent entry always comes first in the
815 @comment node-name, next, previous, up
816 @subsection Functions for Killing
818 @code{kill-region} is the usual subroutine for killing text. Any
819 command that calls this function is a ``kill command'' (and should
820 probably have @samp{kill} in its name). @code{kill-region} puts the
821 newly killed text in a new element at the beginning of the kill ring or
822 adds it to the most recent element. It determines automatically (using
823 @code{last-command}) whether the previous command was a kill command,
824 and if so appends the killed text to the most recent entry.
826 @deffn Command kill-region start end &optional yank-handler
827 This function kills the text in the region defined by @var{start} and
828 @var{end}. The text is deleted but saved in the kill ring, along with
829 its text properties. The value is always @code{nil}.
831 In an interactive call, @var{start} and @var{end} are point and
835 If the buffer or text is read-only, @code{kill-region} modifies the kill
836 ring just the same, then signals an error without modifying the buffer.
837 This is convenient because it lets the user use a series of kill
838 commands to copy text from a read-only buffer into the kill ring.
840 If @var{yank-handler} is non-@code{nil}, this puts that value onto
841 the string of killed text, as a @code{yank-handler} text property.
842 @xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, any
843 @code{yank-handler} properties present on the killed text are copied
844 onto the kill ring, like other text properties.
847 @defopt kill-read-only-ok
848 If this option is non-@code{nil}, @code{kill-region} does not signal an
849 error if the buffer or text is read-only. Instead, it simply returns,
850 updating the kill ring but not changing the buffer.
853 @deffn Command copy-region-as-kill start end
854 This command saves the region defined by @var{start} and @var{end} on
855 the kill ring (including text properties), but does not delete the text
856 from the buffer. It returns @code{nil}.
858 The command does not set @code{this-command} to @code{kill-region}, so a
859 subsequent kill command does not append to the same kill ring entry.
861 Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
862 support Emacs 18. For newer Emacs versions, it is better to use
863 @code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill
870 Yanking means inserting text from the kill ring, but it does
871 not insert the text blindly. Yank commands and some other commands
872 use @code{insert-for-yank} to perform special processing on the
873 text that they copy into the buffer.
875 @defun insert-for-yank string
876 This function normally works like @code{insert} except that it doesn't
877 insert the text properties in the @code{yank-excluded-properties}
878 list. However, if any part of @var{string} has a non-@code{nil}
879 @code{yank-handler} text property, that property can do various
880 special processing on that part of the text being inserted.
883 @defun insert-buffer-substring-as-yank buf &optional start end
884 This function resembles @code{insert-buffer-substring} except that it
885 doesn't insert the text properties in the
886 @code{yank-excluded-properties} list.
889 You can put a @code{yank-handler} text property on all or part of
890 the text to control how it will be inserted if it is yanked. The
891 @code{insert-for-yank} function looks for that property. The property
892 value must be a list of one to four elements, with the following
893 format (where elements after the first may be omitted):
896 (@var{function} @var{param} @var{noexclude} @var{undo})
899 Here is what the elements do:
903 When @var{function} is present and non-@code{nil}, it is called instead of
904 @code{insert} to insert the string. @var{function} takes one
905 argument---the string to insert.
908 If @var{param} is present and non-@code{nil}, it replaces @var{string}
909 (or the part of @var{string} being processed) as the object passed to
910 @var{function} (or @code{insert}); for example, if @var{function} is
911 @code{yank-rectangle}, @var{param} should be a list of strings to
912 insert as a rectangle.
915 If @var{noexclude} is present and non-@code{nil}, the normal removal of the
916 yank-excluded-properties is not performed; instead @var{function} is
917 responsible for removing those properties. This may be necessary
918 if @var{function} adjusts point before or after inserting the object.
921 If @var{undo} is present and non-@code{nil}, it is a function that will be
922 called by @code{yank-pop} to undo the insertion of the current object.
923 It is called with two arguments, the start and end of the current
924 region. @var{function} can set @code{yank-undo-function} to override
925 the @var{undo} value.
929 @comment node-name, next, previous, up
930 @subsection Functions for Yanking
932 @dfn{Yanking} means reinserting an entry of previously killed text
933 from the kill ring. The text properties are copied too.
935 @deffn Command yank &optional arg
936 @cindex inserting killed text
937 This command inserts before point the text at the front of the
938 kill ring. It positions the mark at the beginning of that text, and
941 If @var{arg} is a non-@code{nil} list (which occurs interactively when
942 the user types @kbd{C-u} with no digits), then @code{yank} inserts the
943 text as described above, but puts point before the yanked text and
944 puts the mark after it.
946 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th
947 most recently killed text---the @var{arg}th element of the kill ring
948 list, counted cyclically from the front, which is considered the
949 first element for this purpose.
951 @code{yank} does not alter the contents of the kill ring, unless it
952 used text provided by another program, in which case it pushes that text
953 onto the kill ring. However if @var{arg} is an integer different from
954 one, it rotates the kill ring to place the yanked string at the front.
956 @code{yank} returns @code{nil}.
959 @deffn Command yank-pop &optional arg
960 This command replaces the just-yanked entry from the kill ring with a
961 different entry from the kill ring.
963 This is allowed only immediately after a @code{yank} or another
964 @code{yank-pop}. At such a time, the region contains text that was just
965 inserted by yanking. @code{yank-pop} deletes that text and inserts in
966 its place a different piece of killed text. It does not add the deleted
967 text to the kill ring, since it is already in the kill ring somewhere.
968 It does however rotate the kill ring to place the newly yanked string at
971 If @var{arg} is @code{nil}, then the replacement text is the previous
972 element of the kill ring. If @var{arg} is numeric, the replacement is
973 the @var{arg}th previous kill. If @var{arg} is negative, a more recent
974 kill is the replacement.
976 The sequence of kills in the kill ring wraps around, so that after the
977 oldest one comes the newest one, and before the newest one goes the
980 The return value is always @code{nil}.
983 @defvar yank-undo-function
984 If this variable is non-@code{nil}, the function @code{yank-pop} uses
985 its value instead of @code{delete-region} to delete the text
986 inserted by the previous @code{yank} or
987 @code{yank-pop} command. The value must be a function of two
988 arguments, the start and end of the current region.
990 The function @code{insert-for-yank} automatically sets this variable
991 according to the @var{undo} element of the @code{yank-handler}
992 text property, if there is one.
995 @node Low-Level Kill Ring
996 @subsection Low-Level Kill Ring
998 These functions and variables provide access to the kill ring at a
999 lower level, but still convenient for use in Lisp programs, because they
1000 take care of interaction with window system selections
1001 (@pxref{Window System Selections}).
1003 @defun current-kill n &optional do-not-move
1004 The function @code{current-kill} rotates the yanking pointer, which
1005 designates the ``front'' of the kill ring, by @var{n} places (from newer
1006 kills to older ones), and returns the text at that place in the ring.
1008 If the optional second argument @var{do-not-move} is non-@code{nil},
1009 then @code{current-kill} doesn't alter the yanking pointer; it just
1010 returns the @var{n}th kill, counting from the current yanking pointer.
1012 If @var{n} is zero, indicating a request for the latest kill,
1013 @code{current-kill} calls the value of
1014 @code{interprogram-paste-function} (documented below) before
1015 consulting the kill ring. If that value is a function and calling it
1016 returns a string, @code{current-kill} pushes that string onto the kill
1017 ring and returns it. It also sets the yanking pointer to point to
1018 that new entry, regardless of the value of @var{do-not-move}.
1019 Otherwise, @code{current-kill} does not treat a zero value for @var{n}
1020 specially: it returns the entry pointed at by the yanking pointer and
1021 does not move the yanking pointer.
1024 @defun kill-new string &optional replace yank-handler
1025 This function pushes the text @var{string} onto the kill ring and
1026 makes the yanking pointer point to it. It discards the oldest entry
1027 if appropriate. It also invokes the value of
1028 @code{interprogram-cut-function} (see below).
1030 If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the
1031 first element of the kill ring with @var{string}, rather than pushing
1032 @var{string} onto the kill ring.
1034 If @var{yank-handler} is non-@code{nil}, this puts that value onto
1035 the string of killed text, as a @code{yank-handler} property.
1036 @xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, then
1037 @code{kill-new} copies any @code{yank-handler} properties present on
1038 @var{string} onto the kill ring, as it does with other text properties.
1041 @defun kill-append string before-p &optional yank-handler
1042 This function appends the text @var{string} to the first entry in the
1043 kill ring and makes the yanking pointer point to the combined entry.
1044 Normally @var{string} goes at the end of the entry, but if
1045 @var{before-p} is non-@code{nil}, it goes at the beginning. This
1046 function also invokes the value of @code{interprogram-cut-function}
1047 (see below). This handles @var{yank-handler} just like
1048 @code{kill-new}, except that if @var{yank-handler} is different from
1049 the @code{yank-handler} property of the first entry of the kill ring,
1050 @code{kill-append} pushes the concatenated string onto the kill ring,
1051 instead of replacing the original first entry with it.
1054 @defvar interprogram-paste-function
1055 This variable provides a way of transferring killed text from other
1056 programs, when you are using a window system. Its value should be
1057 @code{nil} or a function of no arguments.
1059 If the value is a function, @code{current-kill} calls it to get the
1060 ``most recent kill''. If the function returns a non-@code{nil} value,
1061 then that value is used as the ``most recent kill''. If it returns
1062 @code{nil}, then the front of the kill ring is used.
1064 The normal use of this hook is to get the window system's primary
1065 selection as the most recent kill, even if the selection belongs to
1066 another application. @xref{Window System Selections}.
1069 @defvar interprogram-cut-function
1070 This variable provides a way of communicating killed text to other
1071 programs, when you are using a window system. Its value should be
1072 @code{nil} or a function of one required and one optional argument.
1074 If the value is a function, @code{kill-new} and @code{kill-append} call
1075 it with the new first element of the kill ring as the first argument.
1076 The second, optional, argument has the same meaning as the @var{push}
1077 argument to @code{x-set-cut-buffer} (@pxref{Definition of
1078 x-set-cut-buffer}) and only affects the second and later cut buffers.
1080 The normal use of this hook is to set the window system's primary
1081 selection (and first cut buffer) from the newly killed text.
1082 @xref{Window System Selections}.
1085 @node Internals of Kill Ring
1086 @comment node-name, next, previous, up
1087 @subsection Internals of the Kill Ring
1089 The variable @code{kill-ring} holds the kill ring contents, in the
1090 form of a list of strings. The most recent kill is always at the front
1093 The @code{kill-ring-yank-pointer} variable points to a link in the
1094 kill ring list, whose @sc{car} is the text to yank next. We say it
1095 identifies the ``front'' of the ring. Moving
1096 @code{kill-ring-yank-pointer} to a different link is called
1097 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
1098 the functions that move the yank pointer wrap around from the end of the
1099 list to the beginning, or vice-versa. Rotation of the kill ring is
1100 virtual; it does not change the value of @code{kill-ring}.
1102 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
1103 variables whose values are normally lists. The word ``pointer'' in the
1104 name of the @code{kill-ring-yank-pointer} indicates that the variable's
1105 purpose is to identify one element of the list for use by the next yank
1108 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
1109 of the links in the kill ring list. The element it identifies is the
1110 @sc{car} of that link. Kill commands, which change the kill ring, also
1111 set this variable to the value of @code{kill-ring}. The effect is to
1112 rotate the ring so that the newly killed text is at the front.
1114 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
1115 pointing to the second entry in the kill ring @code{("some text" "a
1116 different piece of text" "yet older text")}.
1120 kill-ring ---- kill-ring-yank-pointer
1123 | --- --- --- --- --- ---
1124 --> | | |------> | | |--> | | |--> nil
1125 --- --- --- --- --- ---
1128 | | -->"yet older text"
1130 | --> "a different piece of text"
1137 This state of affairs might occur after @kbd{C-y} (@code{yank})
1138 immediately followed by @kbd{M-y} (@code{yank-pop}).
1141 This variable holds the list of killed text sequences, most recently
1145 @defvar kill-ring-yank-pointer
1146 This variable's value indicates which element of the kill ring is at the
1147 ``front'' of the ring for yanking. More precisely, the value is a tail
1148 of the value of @code{kill-ring}, and its @sc{car} is the kill string
1149 that @kbd{C-y} should yank.
1152 @defopt kill-ring-max
1153 The value of this variable is the maximum length to which the kill
1154 ring can grow, before elements are thrown away at the end. The default
1155 value for @code{kill-ring-max} is 60.
1159 @comment node-name, next, previous, up
1163 Most buffers have an @dfn{undo list}, which records all changes made
1164 to the buffer's text so that they can be undone. (The buffers that
1165 don't have one are usually special-purpose buffers for which Emacs
1166 assumes that undoing is not useful.) All the primitives that modify the
1167 text in the buffer automatically add elements to the front of the undo
1168 list, which is in the variable @code{buffer-undo-list}.
1170 @defvar buffer-undo-list
1171 This variable's value is the undo list of the current buffer.
1172 A value of @code{t} disables the recording of undo information.
1175 Here are the kinds of elements an undo list can have:
1178 @item @var{position}
1179 This kind of element records a previous value of point; undoing this
1180 element moves point to @var{position}. Ordinary cursor motion does not
1181 make any sort of undo record, but deletion operations use these entries
1182 to record where point was before the command.
1184 @item (@var{beg} . @var{end})
1185 This kind of element indicates how to delete text that was inserted.
1186 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
1189 @item (@var{text} . @var{position})
1190 This kind of element indicates how to reinsert text that was deleted.
1191 The deleted text itself is the string @var{text}. The place to
1192 reinsert it is @code{(abs @var{position})}. If @var{position} is
1193 positive, point was at the beginning of the deleted text, otherwise it
1196 @item (t @var{high} . @var{low})
1197 This kind of element indicates that an unmodified buffer became
1198 modified. The elements @var{high} and @var{low} are two integers, each
1199 recording 16 bits of the visited file's modification time as of when it
1200 was previously visited or saved. @code{primitive-undo} uses those
1201 values to determine whether to mark the buffer as unmodified once again;
1202 it does so only if the file's modification time matches those numbers.
1204 @item (nil @var{property} @var{value} @var{beg} . @var{end})
1205 This kind of element records a change in a text property.
1206 Here's how you might undo the change:
1209 (put-text-property @var{beg} @var{end} @var{property} @var{value})
1212 @item (apply @var{funname} . @var{args})
1213 This kind of element records a change that can be undone by evaluating
1214 (@code{apply} @var{funname} @var{args}).
1216 @item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
1217 This kind of element records a change that can be undone by evaluating
1218 (@code{apply} @var{funname} @var{args}). The integer values @var{beg}
1219 and @var{end} is buffer positions of the range affected by this change
1220 and @var{delta} is an integer value which is the number of bytes added
1221 or deleted in that range by this change. This kind of element
1222 enables undo limited to a region to determine whether the element
1223 pertains to that region.
1225 @item (@var{marker} . @var{adjustment})
1226 This kind of element records the fact that the marker @var{marker} was
1227 relocated due to deletion of surrounding text, and that it moved
1228 @var{adjustment} character positions. Undoing this element moves
1229 @var{marker} @minus{} @var{adjustment} characters.
1231 @item (apply @var{funname} . @var{args})
1232 This is an extensible undo item, which is undone by calling
1233 @var{funname} with arguments @var{args}.
1235 @item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
1236 This is an extensible undo item, which records a change limited to the
1237 range @var{beg} to @var{end}, which increased the size of the buffer
1238 by @var{delta}. It is undone by calling @var{funname} with arguments
1242 This element is a boundary. The elements between two boundaries are
1243 called a @dfn{change group}; normally, each change group corresponds to
1244 one keyboard command, and undo commands normally undo an entire group as
1248 @defun undo-boundary
1249 This function places a boundary element in the undo list. The undo
1250 command stops at such a boundary, and successive undo commands undo
1251 to earlier and earlier boundaries. This function returns @code{nil}.
1253 The editor command loop automatically creates an undo boundary before
1254 each key sequence is executed. Thus, each undo normally undoes the
1255 effects of one command. Self-inserting input characters are an
1256 exception. The command loop makes a boundary for the first such
1257 character; the next 19 consecutive self-inserting input characters do
1258 not make boundaries, and then the 20th does, and so on as long as
1259 self-inserting characters continue.
1261 All buffer modifications add a boundary whenever the previous undoable
1262 change was made in some other buffer. This is to ensure that
1263 each command makes a boundary in each buffer where it makes changes.
1265 Calling this function explicitly is useful for splitting the effects of
1266 a command into more than one unit. For example, @code{query-replace}
1267 calls @code{undo-boundary} after each replacement, so that the user can
1268 undo individual replacements one by one.
1271 @defvar undo-in-progress
1272 This variable is normally @code{nil}, but the undo commands bind it to
1273 @code{t}. This is so that various kinds of change hooks can tell when
1274 they're being called for the sake of undoing.
1277 @defun primitive-undo count list
1278 This is the basic function for undoing elements of an undo list.
1279 It undoes the first @var{count} elements of @var{list}, returning
1280 the rest of @var{list}. You could write this function in Lisp,
1281 but it is convenient to have it in C.
1283 @code{primitive-undo} adds elements to the buffer's undo list when it
1284 changes the buffer. Undo commands avoid confusion by saving the undo
1285 list value at the beginning of a sequence of undo operations. Then the
1286 undo operations use and update the saved value. The new elements added
1287 by undoing are not part of this saved value, so they don't interfere with
1290 This function does not bind @code{undo-in-progress}.
1293 @node Maintaining Undo
1294 @section Maintaining Undo Lists
1296 This section describes how to enable and disable undo information for
1297 a given buffer. It also explains how the undo list is truncated
1298 automatically so it doesn't get too big.
1300 Recording of undo information in a newly created buffer is normally
1301 enabled to start with; but if the buffer name starts with a space, the
1302 undo recording is initially disabled. You can explicitly enable or
1303 disable undo recording with the following two functions, or by setting
1304 @code{buffer-undo-list} yourself.
1306 @deffn Command buffer-enable-undo &optional buffer-or-name
1307 This command enables recording undo information for buffer
1308 @var{buffer-or-name}, so that subsequent changes can be undone. If no
1309 argument is supplied, then the current buffer is used. This function
1310 does nothing if undo recording is already enabled in the buffer. It
1313 In an interactive call, @var{buffer-or-name} is the current buffer.
1314 You cannot specify any other buffer.
1317 @deffn Command buffer-disable-undo &optional buffer-or-name
1318 @cindex disable undo
1319 This function discards the undo list of @var{buffer-or-name}, and disables
1320 further recording of undo information. As a result, it is no longer
1321 possible to undo either previous changes or any subsequent changes. If
1322 the undo list of @var{buffer-or-name} is already disabled, this function
1325 This function returns @code{nil}.
1328 As editing continues, undo lists get longer and longer. To prevent
1329 them from using up all available memory space, garbage collection trims
1330 them back to size limits you can set. (For this purpose, the ``size''
1331 of an undo list measures the cons cells that make up the list, plus the
1332 strings of deleted text.) Three variables control the range of acceptable
1333 sizes: @code{undo-limit}, @code{undo-strong-limit} and
1334 @code{undo-outer-limit}.
1337 This is the soft limit for the acceptable size of an undo list. The
1338 change group at which this size is exceeded is the last one kept.
1341 @defopt undo-strong-limit
1342 This is the upper limit for the acceptable size of an undo list. The
1343 change group at which this size is exceeded is discarded itself (along
1344 with all older change groups). There is one exception: the very latest
1345 change group is only discarded if it exceeds @code{undo-outer-limit}.
1348 @defopt undo-outer-limit
1349 If at garbage collection time the undo info for the current command
1350 exceeds this limit, Emacs discards the info and displays a warning.
1351 This is a last ditch limit to prevent memory overflow.
1355 @comment node-name, next, previous, up
1357 @cindex filling, explicit
1359 @dfn{Filling} means adjusting the lengths of lines (by moving the line
1360 breaks) so that they are nearly (but no greater than) a specified
1361 maximum width. Additionally, lines can be @dfn{justified}, which means
1362 inserting spaces to make the left and/or right margins line up
1363 precisely. The width is controlled by the variable @code{fill-column}.
1364 For ease of reading, lines should be no longer than 70 or so columns.
1366 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1367 automatically as you insert it, but changes to existing text may leave
1368 it improperly filled. Then you must fill the text explicitly.
1370 Most of the commands in this section return values that are not
1371 meaningful. All the functions that do filling take note of the current
1372 left margin, current right margin, and current justification style
1373 (@pxref{Margins}). If the current justification style is
1374 @code{none}, the filling functions don't actually do anything.
1376 Several of the filling functions have an argument @var{justify}.
1377 If it is non-@code{nil}, that requests some kind of justification. It
1378 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
1379 request a specific style of justification. If it is @code{t}, that
1380 means to use the current justification style for this part of the text
1381 (see @code{current-justification}, below). Any other value is treated
1384 When you call the filling functions interactively, using a prefix
1385 argument implies the value @code{full} for @var{justify}.
1387 @deffn Command fill-paragraph justify
1388 @cindex filling a paragraph
1389 This command fills the paragraph at or after point. If
1390 @var{justify} is non-@code{nil}, each line is justified as well.
1391 It uses the ordinary paragraph motion commands to find paragraph
1392 boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
1395 @deffn Command fill-region start end &optional justify nosqueeze to-eop
1396 This command fills each of the paragraphs in the region from @var{start}
1397 to @var{end}. It justifies as well if @var{justify} is
1400 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1401 other than line breaks untouched. If @var{to-eop} is non-@code{nil},
1402 that means to keep filling to the end of the paragraph---or the next hard
1403 newline, if @code{use-hard-newlines} is enabled (see below).
1405 The variable @code{paragraph-separate} controls how to distinguish
1406 paragraphs. @xref{Standard Regexps}.
1409 @deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
1410 This command fills each paragraph in the region according to its
1411 individual fill prefix. Thus, if the lines of a paragraph were indented
1412 with spaces, the filled paragraph will remain indented in the same
1415 The first two arguments, @var{start} and @var{end}, are the beginning
1416 and end of the region to be filled. The third and fourth arguments,
1417 @var{justify} and @var{citation-regexp}, are optional. If
1418 @var{justify} is non-@code{nil}, the paragraphs are justified as
1419 well as filled. If @var{citation-regexp} is non-@code{nil}, it means the
1420 function is operating on a mail message and therefore should not fill
1421 the header lines. If @var{citation-regexp} is a string, it is used as
1422 a regular expression; if it matches the beginning of a line, that line
1423 is treated as a citation marker.
1425 Ordinarily, @code{fill-individual-paragraphs} regards each change in
1426 indentation as starting a new paragraph. If
1427 @code{fill-individual-varying-indent} is non-@code{nil}, then only
1428 separator lines separate paragraphs. That mode can handle indented
1429 paragraphs with additional indentation on the first line.
1432 @defopt fill-individual-varying-indent
1433 This variable alters the action of @code{fill-individual-paragraphs} as
1437 @deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
1438 This command considers a region of text as a single paragraph and fills
1439 it. If the region was made up of many paragraphs, the blank lines
1440 between paragraphs are removed. This function justifies as well as
1441 filling when @var{justify} is non-@code{nil}.
1443 In an interactive call, any prefix argument requests justification.
1445 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1446 other than line breaks untouched. If @var{squeeze-after} is
1447 non-@code{nil}, it specifies a position in the region, and means don't
1448 canonicalize spaces before that position.
1450 In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
1451 choose a fill prefix by default. @xref{Adaptive Fill}.
1454 @deffn Command justify-current-line &optional how eop nosqueeze
1455 This command inserts spaces between the words of the current line so
1456 that the line ends exactly at @code{fill-column}. It returns
1459 The argument @var{how}, if non-@code{nil} specifies explicitly the style
1460 of justification. It can be @code{left}, @code{right}, @code{full},
1461 @code{center}, or @code{none}. If it is @code{t}, that means to do
1462 follow specified justification style (see @code{current-justification},
1463 below). @code{nil} means to do full justification.
1465 If @var{eop} is non-@code{nil}, that means do left-justification if
1466 @code{current-justification} specifies full justification. This is used
1467 for the last line of a paragraph; even if the paragraph as a whole is
1468 fully justified, the last line should not be.
1470 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1474 @defopt default-justification
1475 This variable's value specifies the style of justification to use for
1476 text that doesn't specify a style with a text property. The possible
1477 values are @code{left}, @code{right}, @code{full}, @code{center}, or
1478 @code{none}. The default value is @code{left}.
1481 @defun current-justification
1482 This function returns the proper justification style to use for filling
1483 the text around point.
1486 @defopt sentence-end-double-space
1487 @anchor{Definition of sentence-end-double-space}
1488 If this variable is non-@code{nil}, a period followed by just one space
1489 does not count as the end of a sentence, and the filling functions
1490 avoid breaking the line at such a place.
1493 @defopt sentence-end-without-period
1494 If this variable is non-@code{nil}, a sentence can end without a
1495 period. This is used for languages like Thai, where sentences end
1496 with a double space but without a period.
1499 @defopt sentence-end-without-space
1500 If this variable is non-@code{nil}, it should be a string of
1501 characters that can end a sentence without following spaces.
1504 @defvar fill-paragraph-function
1505 This variable provides a way for major modes to override the filling of
1506 paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
1507 this function to do the work. If the function returns a non-@code{nil}
1508 value, @code{fill-paragraph} assumes the job is done, and immediately
1511 The usual use of this feature is to fill comments in programming
1512 language modes. If the function needs to fill a paragraph in the usual
1513 way, it can do so as follows:
1516 (let ((fill-paragraph-function nil))
1517 (fill-paragraph arg))
1521 @defvar use-hard-newlines
1522 If this variable is non-@code{nil}, the filling functions do not delete
1523 newlines that have the @code{hard} text property. These ``hard
1524 newlines'' act as paragraph separators.
1528 @section Margins for Filling
1531 This buffer-local variable specifies a string of text that appears at
1533 of normal text lines and should be disregarded when filling them. Any
1534 line that fails to start with the fill prefix is considered the start of
1535 a paragraph; so is any line that starts with the fill prefix followed by
1536 additional whitespace. Lines that start with the fill prefix but no
1537 additional whitespace are ordinary text lines that can be filled
1538 together. The resulting filled lines also start with the fill prefix.
1540 The fill prefix follows the left margin whitespace, if any.
1544 This buffer-local variable specifies the maximum width of filled lines.
1545 Its value should be an integer, which is a number of columns. All the
1546 filling, justification, and centering commands are affected by this
1547 variable, including Auto Fill mode (@pxref{Auto Filling}).
1549 As a practical matter, if you are writing text for other people to
1550 read, you should set @code{fill-column} to no more than 70. Otherwise
1551 the line will be too long for people to read comfortably, and this can
1552 make the text seem clumsy.
1555 @defvar default-fill-column
1556 The value of this variable is the default value for @code{fill-column} in
1557 buffers that do not override it. This is the same as
1558 @code{(default-value 'fill-column)}.
1560 The default value for @code{default-fill-column} is 70.
1563 @deffn Command set-left-margin from to margin
1564 This sets the @code{left-margin} property on the text from @var{from} to
1565 @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
1566 command also refills the region to fit the new margin.
1569 @deffn Command set-right-margin from to margin
1570 This sets the @code{right-margin} property on the text from @var{from}
1571 to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
1572 this command also refills the region to fit the new margin.
1575 @defun current-left-margin
1576 This function returns the proper left margin value to use for filling
1577 the text around point. The value is the sum of the @code{left-margin}
1578 property of the character at the start of the current line (or zero if
1579 none), and the value of the variable @code{left-margin}.
1582 @defun current-fill-column
1583 This function returns the proper fill column value to use for filling
1584 the text around point. The value is the value of the @code{fill-column}
1585 variable, minus the value of the @code{right-margin} property of the
1586 character after point.
1589 @deffn Command move-to-left-margin &optional n force
1590 This function moves point to the left margin of the current line. The
1591 column moved to is determined by calling the function
1592 @code{current-left-margin}. If the argument @var{n} is non-@code{nil},
1593 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
1595 If @var{force} is non-@code{nil}, that says to fix the line's
1596 indentation if that doesn't match the left margin value.
1599 @defun delete-to-left-margin &optional from to
1600 This function removes left margin indentation from the text between
1601 @var{from} and @var{to}. The amount of indentation to delete is
1602 determined by calling @code{current-left-margin}. In no case does this
1603 function delete non-whitespace. If @var{from} and @var{to} are omitted,
1604 they default to the whole buffer.
1607 @defun indent-to-left-margin
1608 This is the default @code{indent-line-function}, used in Fundamental
1609 mode, Text mode, etc. Its effect is to adjust the indentation at the
1610 beginning of the current line to the value specified by the variable
1611 @code{left-margin}. This may involve either inserting or deleting
1616 This variable specifies the base left margin column. In Fundamental
1617 mode, @kbd{C-j} indents to this column. This variable automatically
1618 becomes buffer-local when set in any fashion.
1621 @defvar fill-nobreak-predicate
1622 This variable gives major modes a way to specify not to break a line
1623 at certain places. Its value should be a list of functions, but a
1624 single function is also supported for compatibility. Whenever filling
1625 considers breaking the line at a certain place in the buffer, it calls
1626 each of these functions with no arguments and with point located at
1627 that place. If any of the functions returns non-@code{nil}, then the
1628 line won't be broken there.
1632 @section Adaptive Fill Mode
1633 @cindex Adaptive Fill mode
1635 Adaptive Fill mode chooses a fill prefix automatically from the text
1636 in each paragraph being filled.
1638 @defopt adaptive-fill-mode
1639 Adaptive Fill mode is enabled when this variable is non-@code{nil}.
1640 It is @code{t} by default.
1643 @defun fill-context-prefix from to
1644 This function implements the heart of Adaptive Fill mode; it chooses a
1645 fill prefix based on the text between @var{from} and @var{to}. It does
1646 this by looking at the first two lines of the paragraph, based on the
1647 variables described below.
1648 @c The optional argument first-line-regexp is not documented
1649 @c because it exists for internal purposes and might be eliminated
1653 @defopt adaptive-fill-regexp
1654 This variable holds a regular expression to control Adaptive Fill mode.
1655 Adaptive Fill mode matches this regular expression against the text
1656 starting after the left margin whitespace (if any) on a line; the
1657 characters it matches are that line's candidate for the fill prefix.
1660 @defopt adaptive-fill-first-line-regexp
1661 In a one-line paragraph, if the candidate fill prefix matches this
1662 regular expression, or if it matches @code{comment-start-skip}, then it
1663 is used---otherwise, spaces amounting to the same width are used
1666 However, the fill prefix is never taken from a one-line paragraph
1667 if it would act as a paragraph starter on subsequent lines.
1670 @defopt adaptive-fill-function
1671 You can specify more complex ways of choosing a fill prefix
1672 automatically by setting this variable to a function. The function is
1673 called when @code{adaptive-fill-regexp} does not match, with point after
1674 the left margin of a line, and it should return the appropriate fill
1675 prefix based on that line. If it returns @code{nil}, that means it sees
1676 no fill prefix in that line.
1680 @comment node-name, next, previous, up
1681 @section Auto Filling
1682 @cindex filling, automatic
1683 @cindex Auto Fill mode
1685 Auto Fill mode is a minor mode that fills lines automatically as text
1686 is inserted. This section describes the hook used by Auto Fill mode.
1687 For a description of functions that you can call explicitly to fill and
1688 justify existing text, see @ref{Filling}.
1690 Auto Fill mode also enables the functions that change the margins and
1691 justification style to refill portions of the text. @xref{Margins}.
1693 @defvar auto-fill-function
1694 The value of this variable should be a function (of no arguments) to be
1695 called after self-inserting a character from the table
1696 @code{auto-fill-chars}. It may be @code{nil}, in which case nothing
1697 special is done in that case.
1699 The value of @code{auto-fill-function} is @code{do-auto-fill} when
1700 Auto-Fill mode is enabled. That is a function whose sole purpose is to
1701 implement the usual strategy for breaking a line.
1704 In older Emacs versions, this variable was named @code{auto-fill-hook},
1705 but since it is not called with the standard convention for hooks, it
1706 was renamed to @code{auto-fill-function} in version 19.
1710 @defvar normal-auto-fill-function
1711 This variable specifies the function to use for
1712 @code{auto-fill-function}, if and when Auto Fill is turned on. Major
1713 modes can set buffer-local values for this variable to alter how Auto
1717 @defvar auto-fill-chars
1718 A char table of characters which invoke @code{auto-fill-function} when
1719 self-inserted---space and newline in most language environments. They
1720 have an entry @code{t} in the table.
1724 @section Sorting Text
1725 @cindex sorting text
1727 The sorting functions described in this section all rearrange text in
1728 a buffer. This is in contrast to the function @code{sort}, which
1729 rearranges the order of the elements of a list (@pxref{Rearrangement}).
1730 The values returned by these functions are not meaningful.
1732 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
1733 This function is the general text-sorting routine that subdivides a
1734 buffer into records and then sorts them. Most of the commands in this
1735 section use this function.
1737 To understand how @code{sort-subr} works, consider the whole accessible
1738 portion of the buffer as being divided into disjoint pieces called
1739 @dfn{sort records}. The records may or may not be contiguous, but they
1740 must not overlap. A portion of each sort record (perhaps all of it) is
1741 designated as the sort key. Sorting rearranges the records in order by
1744 Usually, the records are rearranged in order of ascending sort key.
1745 If the first argument to the @code{sort-subr} function, @var{reverse},
1746 is non-@code{nil}, the sort records are rearranged in order of
1747 descending sort key.
1749 The next four arguments to @code{sort-subr} are functions that are
1750 called to move point across a sort record. They are called many times
1751 from within @code{sort-subr}.
1755 @var{nextrecfun} is called with point at the end of a record. This
1756 function moves point to the start of the next record. The first record
1757 is assumed to start at the position of point when @code{sort-subr} is
1758 called. Therefore, you should usually move point to the beginning of
1759 the buffer before calling @code{sort-subr}.
1761 This function can indicate there are no more sort records by leaving
1762 point at the end of the buffer.
1765 @var{endrecfun} is called with point within a record. It moves point to
1766 the end of the record.
1769 @var{startkeyfun} is called to move point from the start of a record to
1770 the start of the sort key. This argument is optional; if it is omitted,
1771 the whole record is the sort key. If supplied, the function should
1772 either return a non-@code{nil} value to be used as the sort key, or
1773 return @code{nil} to indicate that the sort key is in the buffer
1774 starting at point. In the latter case, @var{endkeyfun} is called to
1775 find the end of the sort key.
1778 @var{endkeyfun} is called to move point from the start of the sort key
1779 to the end of the sort key. This argument is optional. If
1780 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
1781 @code{nil}), then the sort key extends to the end of the record. There
1782 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1783 non-@code{nil} value.
1786 As an example of @code{sort-subr}, here is the complete function
1787 definition for @code{sort-lines}:
1791 ;; @r{Note that the first two lines of doc string}
1792 ;; @r{are effectively one line when viewed by a user.}
1793 (defun sort-lines (reverse beg end)
1794 "Sort lines in region alphabetically;\
1795 argument means descending order.
1796 Called from a program, there are three arguments:
1799 REVERSE (non-nil means reverse order),\
1800 BEG and END (region to sort).
1801 The variable `sort-fold-case' determines\
1802 whether alphabetic case affects
1806 (interactive "P\nr")
1809 (narrow-to-region beg end)
1810 (goto-char (point-min))
1811 (sort-subr reverse 'forward-line 'end-of-line))))
1815 Here @code{forward-line} moves point to the start of the next record,
1816 and @code{end-of-line} moves point to the end of record. We do not pass
1817 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
1818 record is used as the sort key.
1820 The @code{sort-paragraphs} function is very much the same, except that
1821 its @code{sort-subr} call looks like this:
1828 (while (and (not (eobp))
1829 (looking-at paragraph-separate))
1835 Markers pointing into any sort records are left with no useful
1836 position after @code{sort-subr} returns.
1839 @defopt sort-fold-case
1840 If this variable is non-@code{nil}, @code{sort-subr} and the other
1841 buffer sorting functions ignore case when comparing strings.
1844 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
1845 This command sorts the region between @var{start} and @var{end}
1846 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
1847 If @var{reverse} is a negative integer, then sorting is in reverse
1850 Alphabetical sorting means that two sort keys are compared by
1851 comparing the first characters of each, the second characters of each,
1852 and so on. If a mismatch is found, it means that the sort keys are
1853 unequal; the sort key whose character is less at the point of first
1854 mismatch is the lesser sort key. The individual characters are compared
1855 according to their numerical character codes in the Emacs character set.
1857 The value of the @var{record-regexp} argument specifies how to divide
1858 the buffer into sort records. At the end of each record, a search is
1859 done for this regular expression, and the text that matches it is taken
1860 as the next record. For example, the regular expression @samp{^.+$},
1861 which matches lines with at least one character besides a newline, would
1862 make each such line into a sort record. @xref{Regular Expressions}, for
1863 a description of the syntax and meaning of regular expressions.
1865 The value of the @var{key-regexp} argument specifies what part of each
1866 record is the sort key. The @var{key-regexp} could match the whole
1867 record, or only a part. In the latter case, the rest of the record has
1868 no effect on the sorted order of records, but it is carried along when
1869 the record moves to its new position.
1871 The @var{key-regexp} argument can refer to the text matched by a
1872 subexpression of @var{record-regexp}, or it can be a regular expression
1875 If @var{key-regexp} is:
1878 @item @samp{\@var{digit}}
1879 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
1880 grouping in @var{record-regexp} is the sort key.
1883 then the whole record is the sort key.
1885 @item a regular expression
1886 then @code{sort-regexp-fields} searches for a match for the regular
1887 expression within the record. If such a match is found, it is the sort
1888 key. If there is no match for @var{key-regexp} within a record then
1889 that record is ignored, which means its position in the buffer is not
1890 changed. (The other records may move around it.)
1893 For example, if you plan to sort all the lines in the region by the
1894 first word on each line starting with the letter @samp{f}, you should
1895 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
1896 @samp{\<f\w*\>}. The resulting expression looks like this:
1900 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
1906 If you call @code{sort-regexp-fields} interactively, it prompts for
1907 @var{record-regexp} and @var{key-regexp} in the minibuffer.
1910 @deffn Command sort-lines reverse start end
1911 This command alphabetically sorts lines in the region between
1912 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1913 is in reverse order.
1916 @deffn Command sort-paragraphs reverse start end
1917 This command alphabetically sorts paragraphs in the region between
1918 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1919 is in reverse order.
1922 @deffn Command sort-pages reverse start end
1923 This command alphabetically sorts pages in the region between
1924 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1925 is in reverse order.
1928 @deffn Command sort-fields field start end
1929 This command sorts lines in the region between @var{start} and
1930 @var{end}, comparing them alphabetically by the @var{field}th field
1931 of each line. Fields are separated by whitespace and numbered starting
1932 from 1. If @var{field} is negative, sorting is by the
1933 @w{@minus{}@var{field}th} field from the end of the line. This command
1934 is useful for sorting tables.
1937 @deffn Command sort-numeric-fields field start end
1938 This command sorts lines in the region between @var{start} and
1939 @var{end}, comparing them numerically by the @var{field}th field of
1940 each line. Fields are separated by whitespace and numbered starting
1941 from 1. The specified field must contain a number in each line of the
1942 region. Numbers starting with 0 are treated as octal, and numbers
1943 starting with @samp{0x} are treated as hexadecimal.
1945 If @var{field} is negative, sorting is by the
1946 @w{@minus{}@var{field}th} field from the end of the line. This
1947 command is useful for sorting tables.
1950 @defopt sort-numeric-base
1951 This variable specifies the default radix for
1952 @code{sort-numeric-fields} to parse numbers.
1955 @deffn Command sort-columns reverse &optional beg end
1956 This command sorts the lines in the region between @var{beg} and
1957 @var{end}, comparing them alphabetically by a certain range of
1958 columns. The column positions of @var{beg} and @var{end} bound the
1959 range of columns to sort on.
1961 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
1963 One unusual thing about this command is that the entire line
1964 containing position @var{beg}, and the entire line containing position
1965 @var{end}, are included in the region sorted.
1967 Note that @code{sort-columns} uses the @code{sort} utility program,
1968 and so cannot work properly on text containing tab characters. Use
1969 @kbd{M-x untabify} to convert tabs to spaces before sorting.
1973 @comment node-name, next, previous, up
1974 @section Counting Columns
1976 @cindex counting columns
1977 @cindex horizontal position
1979 The column functions convert between a character position (counting
1980 characters from the beginning of the buffer) and a column position
1981 (counting screen characters from the beginning of a line).
1983 These functions count each character according to the number of
1984 columns it occupies on the screen. This means control characters count
1985 as occupying 2 or 4 columns, depending upon the value of
1986 @code{ctl-arrow}, and tabs count as occupying a number of columns that
1987 depends on the value of @code{tab-width} and on the column where the tab
1988 begins. @xref{Usual Display}.
1990 Column number computations ignore the width of the window and the
1991 amount of horizontal scrolling. Consequently, a column value can be
1992 arbitrarily high. The first (or leftmost) column is numbered 0. They
1993 also ignore overlays and text properties, aside from invisibility.
1995 @defun current-column
1996 This function returns the horizontal position of point, measured in
1997 columns, counting from 0 at the left margin. The column position is the
1998 sum of the widths of all the displayed representations of the characters
1999 between the start of the current line and point.
2001 For an example of using @code{current-column}, see the description of
2002 @code{count-lines} in @ref{Text Lines}.
2005 @defun move-to-column column &optional force
2006 This function moves point to @var{column} in the current line. The
2007 calculation of @var{column} takes into account the widths of the
2008 displayed representations of the characters between the start of the
2011 If column @var{column} is beyond the end of the line, point moves to the
2012 end of the line. If @var{column} is negative, point moves to the
2013 beginning of the line.
2015 If it is impossible to move to column @var{column} because that is in
2016 the middle of a multicolumn character such as a tab, point moves to the
2017 end of that character. However, if @var{force} is non-@code{nil}, and
2018 @var{column} is in the middle of a tab, then @code{move-to-column}
2019 converts the tab into spaces so that it can move precisely to column
2020 @var{column}. Other multicolumn characters can cause anomalies despite
2021 @var{force}, since there is no way to split them.
2023 The argument @var{force} also has an effect if the line isn't long
2024 enough to reach column @var{column}; if it is @code{t}, that means to
2025 add whitespace at the end of the line to reach that column.
2027 If @var{column} is not an integer, an error is signaled.
2029 The return value is the column number actually moved to.
2033 @section Indentation
2036 The indentation functions are used to examine, move to, and change
2037 whitespace that is at the beginning of a line. Some of the functions
2038 can also change whitespace elsewhere on a line. Columns and indentation
2039 count from zero at the left margin.
2042 * Primitive Indent:: Functions used to count and insert indentation.
2043 * Mode-Specific Indent:: Customize indentation for different modes.
2044 * Region Indent:: Indent all the lines in a region.
2045 * Relative Indent:: Indent the current line based on previous lines.
2046 * Indent Tabs:: Adjustable, typewriter-like tab stops.
2047 * Motion by Indent:: Move to first non-blank character.
2050 @node Primitive Indent
2051 @subsection Indentation Primitives
2053 This section describes the primitive functions used to count and
2054 insert indentation. The functions in the following sections use these
2055 primitives. @xref{Width}, for related functions.
2057 @defun current-indentation
2058 @comment !!Type Primitive Function
2059 @comment !!SourceFile indent.c
2060 This function returns the indentation of the current line, which is
2061 the horizontal position of the first nonblank character. If the
2062 contents are entirely blank, then this is the horizontal position of the
2066 @deffn Command indent-to column &optional minimum
2067 @comment !!Type Primitive Function
2068 @comment !!SourceFile indent.c
2069 This function indents from point with tabs and spaces until @var{column}
2070 is reached. If @var{minimum} is specified and non-@code{nil}, then at
2071 least that many spaces are inserted even if this requires going beyond
2072 @var{column}. Otherwise the function does nothing if point is already
2073 beyond @var{column}. The value is the column at which the inserted
2076 The inserted whitespace characters inherit text properties from the
2077 surrounding text (usually, from the preceding text only). @xref{Sticky
2081 @defopt indent-tabs-mode
2082 @comment !!SourceFile indent.c
2083 If this variable is non-@code{nil}, indentation functions can insert
2084 tabs as well as spaces. Otherwise, they insert only spaces. Setting
2085 this variable automatically makes it buffer-local in the current buffer.
2088 @node Mode-Specific Indent
2089 @subsection Indentation Controlled by Major Mode
2091 An important function of each major mode is to customize the @key{TAB}
2092 key to indent properly for the language being edited. This section
2093 describes the mechanism of the @key{TAB} key and how to control it.
2094 The functions in this section return unpredictable values.
2096 @defvar indent-line-function
2097 This variable's value is the function to be used by @key{TAB} (and
2098 various commands) to indent the current line. The command
2099 @code{indent-according-to-mode} does no more than call this function.
2101 In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C
2102 mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
2103 In Fundamental mode, Text mode, and many other modes with no standard
2104 for indentation, the value is @code{indent-to-left-margin} (which is the
2108 @deffn Command indent-according-to-mode
2109 This command calls the function in @code{indent-line-function} to
2110 indent the current line in a way appropriate for the current major mode.
2113 @deffn Command indent-for-tab-command
2114 This command calls the function in @code{indent-line-function} to indent
2115 the current line; however, if that function is
2116 @code{indent-to-left-margin}, @code{insert-tab} is called instead. (That
2117 is a trivial command that inserts a tab character.)
2120 @deffn Command newline-and-indent
2121 @comment !!SourceFile simple.el
2122 This function inserts a newline, then indents the new line (the one
2123 following the newline just inserted) according to the major mode.
2125 It does indentation by calling the current @code{indent-line-function}.
2126 In programming language modes, this is the same thing @key{TAB} does,
2127 but in some text modes, where @key{TAB} inserts a tab,
2128 @code{newline-and-indent} indents to the column specified by
2132 @deffn Command reindent-then-newline-and-indent
2133 @comment !!SourceFile simple.el
2134 This command reindents the current line, inserts a newline at point,
2135 and then indents the new line (the one following the newline just
2138 This command does indentation on both lines according to the current
2139 major mode, by calling the current value of @code{indent-line-function}.
2140 In programming language modes, this is the same thing @key{TAB} does,
2141 but in some text modes, where @key{TAB} inserts a tab,
2142 @code{reindent-then-newline-and-indent} indents to the column specified
2143 by @code{left-margin}.
2147 @subsection Indenting an Entire Region
2149 This section describes commands that indent all the lines in the
2150 region. They return unpredictable values.
2152 @deffn Command indent-region start end to-column
2153 This command indents each nonblank line starting between @var{start}
2154 (inclusive) and @var{end} (exclusive). If @var{to-column} is
2155 @code{nil}, @code{indent-region} indents each nonblank line by calling
2156 the current mode's indentation function, the value of
2157 @code{indent-line-function}.
2159 If @var{to-column} is non-@code{nil}, it should be an integer
2160 specifying the number of columns of indentation; then this function
2161 gives each line exactly that much indentation, by either adding or
2162 deleting whitespace.
2164 If there is a fill prefix, @code{indent-region} indents each line
2165 by making it start with the fill prefix.
2168 @defvar indent-region-function
2169 The value of this variable is a function that can be used by
2170 @code{indent-region} as a short cut. It should take two arguments, the
2171 start and end of the region. You should design the function so
2172 that it will produce the same results as indenting the lines of the
2173 region one by one, but presumably faster.
2175 If the value is @code{nil}, there is no short cut, and
2176 @code{indent-region} actually works line by line.
2178 A short-cut function is useful in modes such as C mode and Lisp mode,
2179 where the @code{indent-line-function} must scan from the beginning of
2180 the function definition: applying it to each line would be quadratic in
2181 time. The short cut can update the scan information as it moves through
2182 the lines indenting them; this takes linear time. In a mode where
2183 indenting a line individually is fast, there is no need for a short cut.
2185 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
2186 a different meaning and does not use this variable.
2189 @deffn Command indent-rigidly start end count
2190 @comment !!SourceFile indent.el
2191 This command indents all lines starting between @var{start}
2192 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
2193 This ``preserves the shape'' of the affected region, moving it as a
2194 rigid unit. Consequently, this command is useful not only for indenting
2195 regions of unindented text, but also for indenting regions of formatted
2198 For example, if @var{count} is 3, this command adds 3 columns of
2199 indentation to each of the lines beginning in the region specified.
2201 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
2202 @code{indent-rigidly} to indent the text copied from the message being
2206 @defun indent-code-rigidly start end columns &optional nochange-regexp
2207 This is like @code{indent-rigidly}, except that it doesn't alter lines
2208 that start within strings or comments.
2210 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
2211 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
2214 @node Relative Indent
2215 @subsection Indentation Relative to Previous Lines
2217 This section describes two commands that indent the current line
2218 based on the contents of previous lines.
2220 @deffn Command indent-relative &optional unindented-ok
2221 This command inserts whitespace at point, extending to the same
2222 column as the next @dfn{indent point} of the previous nonblank line. An
2223 indent point is a non-whitespace character following whitespace. The
2224 next indent point is the first one at a column greater than the current
2225 column of point. For example, if point is underneath and to the left of
2226 the first non-blank character of a line of text, it moves to that column
2227 by inserting whitespace.
2229 If the previous nonblank line has no next indent point (i.e., none at a
2230 great enough column position), @code{indent-relative} either does
2231 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
2232 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right
2233 of the last column of a short line of text, this command ordinarily
2234 moves point to the next tab stop by inserting whitespace.
2236 The return value of @code{indent-relative} is unpredictable.
2238 In the following example, point is at the beginning of the second
2243 This line is indented twelve spaces.
2244 @point{}The quick brown fox jumped.
2249 Evaluation of the expression @code{(indent-relative nil)} produces the
2254 This line is indented twelve spaces.
2255 @point{}The quick brown fox jumped.
2259 In this next example, point is between the @samp{m} and @samp{p} of
2264 This line is indented twelve spaces.
2265 The quick brown fox jum@point{}ped.
2270 Evaluation of the expression @code{(indent-relative nil)} produces the
2275 This line is indented twelve spaces.
2276 The quick brown fox jum @point{}ped.
2281 @deffn Command indent-relative-maybe
2282 @comment !!SourceFile indent.el
2283 This command indents the current line like the previous nonblank line,
2284 by calling @code{indent-relative} with @code{t} as the
2285 @var{unindented-ok} argument. The return value is unpredictable.
2287 If the previous nonblank line has no indent points beyond the current
2288 column, this command does nothing.
2292 @comment node-name, next, previous, up
2293 @subsection Adjustable ``Tab Stops''
2294 @cindex tabs stops for indentation
2296 This section explains the mechanism for user-specified ``tab stops''
2297 and the mechanisms that use and set them. The name ``tab stops'' is
2298 used because the feature is similar to that of the tab stops on a
2299 typewriter. The feature works by inserting an appropriate number of
2300 spaces and tab characters to reach the next tab stop column; it does not
2301 affect the display of tab characters in the buffer (@pxref{Usual
2302 Display}). Note that the @key{TAB} character as input uses this tab
2303 stop feature only in a few major modes, such as Text mode.
2305 @deffn Command tab-to-tab-stop
2306 This command inserts spaces or tabs before point, up to the next tab
2307 stop column defined by @code{tab-stop-list}. It searches the list for
2308 an element greater than the current column number, and uses that element
2309 as the column to indent to. It does nothing if no such element is
2313 @defopt tab-stop-list
2314 This variable is the list of tab stop columns used by
2315 @code{tab-to-tab-stops}. The elements should be integers in increasing
2316 order. The tab stop columns need not be evenly spaced.
2318 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
2322 @node Motion by Indent
2323 @subsection Indentation-Based Motion Commands
2325 These commands, primarily for interactive use, act based on the
2326 indentation in the text.
2328 @deffn Command back-to-indentation
2329 @comment !!SourceFile simple.el
2330 This command moves point to the first non-whitespace character in the
2331 current line (which is the line in which point is located). It returns
2335 @deffn Command backward-to-indentation &optional arg
2336 @comment !!SourceFile simple.el
2337 This command moves point backward @var{arg} lines and then to the
2338 first nonblank character on that line. It returns @code{nil}.
2339 If @var{arg} is omitted or @code{nil}, it defaults to 1.
2342 @deffn Command forward-to-indentation &optional arg
2343 @comment !!SourceFile simple.el
2344 This command moves point forward @var{arg} lines and then to the first
2345 nonblank character on that line. It returns @code{nil}.
2346 If @var{arg} is omitted or @code{nil}, it defaults to 1.
2350 @comment node-name, next, previous, up
2351 @section Case Changes
2352 @cindex case conversion in buffers
2354 The case change commands described here work on text in the current
2355 buffer. @xref{Case Conversion}, for case conversion functions that work
2356 on strings and characters. @xref{Case Tables}, for how to customize
2357 which characters are upper or lower case and how to convert them.
2359 @deffn Command capitalize-region start end
2360 This function capitalizes all words in the region defined by
2361 @var{start} and @var{end}. To capitalize means to convert each word's
2362 first character to upper case and convert the rest of each word to lower
2363 case. The function returns @code{nil}.
2365 If one end of the region is in the middle of a word, the part of the
2366 word within the region is treated as an entire word.
2368 When @code{capitalize-region} is called interactively, @var{start} and
2369 @var{end} are point and the mark, with the smallest first.
2373 ---------- Buffer: foo ----------
2374 This is the contents of the 5th foo.
2375 ---------- Buffer: foo ----------
2379 (capitalize-region 1 44)
2382 ---------- Buffer: foo ----------
2383 This Is The Contents Of The 5th Foo.
2384 ---------- Buffer: foo ----------
2389 @deffn Command downcase-region start end
2390 This function converts all of the letters in the region defined by
2391 @var{start} and @var{end} to lower case. The function returns
2394 When @code{downcase-region} is called interactively, @var{start} and
2395 @var{end} are point and the mark, with the smallest first.
2398 @deffn Command upcase-region start end
2399 This function converts all of the letters in the region defined by
2400 @var{start} and @var{end} to upper case. The function returns
2403 When @code{upcase-region} is called interactively, @var{start} and
2404 @var{end} are point and the mark, with the smallest first.
2407 @deffn Command capitalize-word count
2408 This function capitalizes @var{count} words after point, moving point
2409 over as it does. To capitalize means to convert each word's first
2410 character to upper case and convert the rest of each word to lower case.
2411 If @var{count} is negative, the function capitalizes the
2412 @minus{}@var{count} previous words but does not move point. The value
2415 If point is in the middle of a word, the part of the word before point
2416 is ignored when moving forward. The rest is treated as an entire word.
2418 When @code{capitalize-word} is called interactively, @var{count} is
2419 set to the numeric prefix argument.
2422 @deffn Command downcase-word count
2423 This function converts the @var{count} words after point to all lower
2424 case, moving point over as it does. If @var{count} is negative, it
2425 converts the @minus{}@var{count} previous words but does not move point.
2426 The value is @code{nil}.
2428 When @code{downcase-word} is called interactively, @var{count} is set
2429 to the numeric prefix argument.
2432 @deffn Command upcase-word count
2433 This function converts the @var{count} words after point to all upper
2434 case, moving point over as it does. If @var{count} is negative, it
2435 converts the @minus{}@var{count} previous words but does not move point.
2436 The value is @code{nil}.
2438 When @code{upcase-word} is called interactively, @var{count} is set to
2439 the numeric prefix argument.
2442 @node Text Properties
2443 @section Text Properties
2444 @cindex text properties
2445 @cindex attributes of text
2446 @cindex properties of text
2448 Each character position in a buffer or a string can have a @dfn{text
2449 property list}, much like the property list of a symbol (@pxref{Property
2450 Lists}). The properties belong to a particular character at a
2451 particular place, such as, the letter @samp{T} at the beginning of this
2452 sentence or the first @samp{o} in @samp{foo}---if the same character
2453 occurs in two different places, the two occurrences generally have
2454 different properties.
2456 Each property has a name and a value. Both of these can be any Lisp
2457 object, but the name is normally a symbol. The usual way to access the
2458 property list is to specify a name and ask what value corresponds to it.
2460 If a character has a @code{category} property, we call it the
2461 @dfn{category} of the character. It should be a symbol. The properties
2462 of the symbol serve as defaults for the properties of the character.
2464 Copying text between strings and buffers preserves the properties
2465 along with the characters; this includes such diverse functions as
2466 @code{substring}, @code{insert}, and @code{buffer-substring}.
2469 * Examining Properties:: Looking at the properties of one character.
2470 * Changing Properties:: Setting the properties of a range of text.
2471 * Property Search:: Searching for where a property changes value.
2472 * Special Properties:: Particular properties with special meanings.
2473 * Format Properties:: Properties for representing formatting of text.
2474 * Sticky Properties:: How inserted text gets properties from
2476 * Saving Properties:: Saving text properties in files, and reading
2478 * Lazy Properties:: Computing text properties in a lazy fashion
2479 only when text is examined.
2480 * Clickable Text:: Using text properties to make regions of text
2481 do something when you click on them.
2482 * Links and Mouse-1:: How to make @key{Mouse-1} follow a link.
2483 * Fields:: The @code{field} property defines
2484 fields within the buffer.
2485 * Not Intervals:: Why text properties do not use
2486 Lisp-visible text intervals.
2489 @node Examining Properties
2490 @subsection Examining Text Properties
2492 The simplest way to examine text properties is to ask for the value of
2493 a particular property of a particular character. For that, use
2494 @code{get-text-property}. Use @code{text-properties-at} to get the
2495 entire property list of a character. @xref{Property Search}, for
2496 functions to examine the properties of a number of characters at once.
2498 These functions handle both strings and buffers. Keep in mind that
2499 positions in a string start from 0, whereas positions in a buffer start
2502 @defun get-text-property pos prop &optional object
2503 This function returns the value of the @var{prop} property of the
2504 character after position @var{pos} in @var{object} (a buffer or
2505 string). The argument @var{object} is optional and defaults to the
2508 If there is no @var{prop} property strictly speaking, but the character
2509 has a category that is a symbol, then @code{get-text-property} returns
2510 the @var{prop} property of that symbol.
2513 @defun get-char-property position prop &optional object
2514 This function is like @code{get-text-property}, except that it checks
2515 overlays first and then text properties. @xref{Overlays}.
2517 The argument @var{object} may be a string, a buffer, or a window. If it
2518 is a window, then the buffer displayed in that window is used for text
2519 properties and overlays, but only the overlays active for that window
2520 are considered. If @var{object} is a buffer, then all overlays in that
2521 buffer are considered, as well as text properties. If @var{object} is a
2522 string, only text properties are considered, since strings never have
2526 @defun get-char-property-and-overlay position prop &optional object
2527 This is like @code{get-char-property}, but gives extra information
2528 about the overlay that the property value comes from.
2530 Its value is a cons cell whose @sc{car} is the property value, the
2531 same value @code{get-char-property} would return with the same
2532 arguments. Its @sc{cdr} is the overlay in which the property was
2533 found, or @code{nil}, if it was found as a text property or not found
2536 If @var{position} is at the end of @var{object}, both the @sc{car} and
2537 the @sc{cdr} of the value are @code{nil}.
2540 @defvar char-property-alias-alist
2541 This variable holds an alist which maps property names to a list of
2542 alternative property names. If a character does not specify a direct
2543 value for a property, the alternative property names are consulted in
2544 order; the first non-@code{nil} value is used. This variable takes
2545 precedence over @code{default-text-properties}, and @code{category}
2546 properties take precedence over this variable.
2549 @defun text-properties-at position &optional object
2550 This function returns the entire property list of the character at
2551 @var{position} in the string or buffer @var{object}. If @var{object} is
2552 @code{nil}, it defaults to the current buffer.
2555 @defvar default-text-properties
2556 This variable holds a property list giving default values for text
2557 properties. Whenever a character does not specify a value for a
2558 property, neither directly, through a category symbol, or through
2559 @code{char-property-alias-alist}, the value stored in this list is
2560 used instead. Here is an example:
2563 (setq default-text-properties '(foo 69)
2564 char-property-alias-alist nil)
2565 ;; @r{Make sure character 1 has no properties of its own.}
2566 (set-text-properties 1 2 nil)
2567 ;; @r{What we get, when we ask, is the default value.}
2568 (get-text-property 1 'foo)
2573 @node Changing Properties
2574 @subsection Changing Text Properties
2576 The primitives for changing properties apply to a specified range of
2577 text in a buffer or string. The function @code{set-text-properties}
2578 (see end of section) sets the entire property list of the text in that
2579 range; more often, it is useful to add, change, or delete just certain
2580 properties specified by name.
2582 Since text properties are considered part of the contents of the
2583 buffer (or string), and can affect how a buffer looks on the screen,
2584 any change in buffer text properties marks the buffer as modified.
2585 Buffer text property changes are undoable also (@pxref{Undo}).
2586 Positions in a string start from 0, whereas positions in a buffer
2589 @defun put-text-property start end prop value &optional object
2590 This function sets the @var{prop} property to @var{value} for the text
2591 between @var{start} and @var{end} in the string or buffer @var{object}.
2592 If @var{object} is @code{nil}, it defaults to the current buffer.
2595 @defun add-text-properties start end props &optional object
2596 This function adds or overrides text properties for the text between
2597 @var{start} and @var{end} in the string or buffer @var{object}. If
2598 @var{object} is @code{nil}, it defaults to the current buffer.
2600 The argument @var{props} specifies which properties to add. It should
2601 have the form of a property list (@pxref{Property Lists}): a list whose
2602 elements include the property names followed alternately by the
2603 corresponding values.
2605 The return value is @code{t} if the function actually changed some
2606 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2607 its values agree with those in the text).
2609 For example, here is how to set the @code{comment} and @code{face}
2610 properties of a range of text:
2613 (add-text-properties @var{start} @var{end}
2614 '(comment t face highlight))
2618 @defun remove-text-properties start end props &optional object
2619 This function deletes specified text properties from the text between
2620 @var{start} and @var{end} in the string or buffer @var{object}. If
2621 @var{object} is @code{nil}, it defaults to the current buffer.
2623 The argument @var{props} specifies which properties to delete. It
2624 should have the form of a property list (@pxref{Property Lists}): a list
2625 whose elements are property names alternating with corresponding values.
2626 But only the names matter---the values that accompany them are ignored.
2627 For example, here's how to remove the @code{face} property.
2630 (remove-text-properties @var{start} @var{end} '(face nil))
2633 The return value is @code{t} if the function actually changed some
2634 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2635 if no character in the specified text had any of those properties).
2637 To remove all text properties from certain text, use
2638 @code{set-text-properties} and specify @code{nil} for the new property
2642 @defun remove-list-of-text-properties start end list-of-properties &optional object
2643 Like @code{remove-text-properties} except that
2644 @var{list-of-properties} is a list property names only, not an
2645 alternating list of property names and values.
2648 @defun set-text-properties start end props &optional object
2649 This function completely replaces the text property list for the text
2650 between @var{start} and @var{end} in the string or buffer @var{object}.
2651 If @var{object} is @code{nil}, it defaults to the current buffer.
2653 The argument @var{props} is the new property list. It should be a list
2654 whose elements are property names alternating with corresponding values.
2656 After @code{set-text-properties} returns, all the characters in the
2657 specified range have identical properties.
2659 If @var{props} is @code{nil}, the effect is to get rid of all properties
2660 from the specified range of text. Here's an example:
2663 (set-text-properties @var{start} @var{end} nil)
2667 The easiest way to make a string with text properties
2668 is with @code{propertize}:
2670 @defun propertize string &rest properties
2672 This function returns a copy of @var{string} which has the text
2673 properties @var{properties}. These properties apply to all the
2674 characters in the string that is returned. Here is an example that
2675 constructs a string with a @code{face} property and a @code{mouse-face}
2679 (propertize "foo" 'face 'italic
2680 'mouse-face 'bold-italic)
2681 @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
2684 To put different properties on various parts of a string, you can
2685 construct each part with @code{propertize} and then combine them with
2690 (propertize "foo" 'face 'italic
2691 'mouse-face 'bold-italic)
2693 (propertize "bar" 'face 'italic
2694 'mouse-face 'bold-italic))
2695 @result{} #("foo and bar"
2696 0 3 (face italic mouse-face bold-italic)
2698 8 11 (face italic mouse-face bold-italic))
2702 See also the function @code{buffer-substring-no-properties}
2703 (@pxref{Buffer Contents}) which copies text from the buffer
2704 but does not copy its properties.
2706 @node Property Search
2707 @subsection Text Property Search Functions
2709 In typical use of text properties, most of the time several or many
2710 consecutive characters have the same value for a property. Rather than
2711 writing your programs to examine characters one by one, it is much
2712 faster to process chunks of text that have the same property value.
2714 Here are functions you can use to do this. They use @code{eq} for
2715 comparing property values. In all cases, @var{object} defaults to the
2718 For high performance, it's very important to use the @var{limit}
2719 argument to these functions, especially the ones that search for a
2720 single property---otherwise, they may spend a long time scanning to the
2721 end of the buffer, if the property you are interested in does not change.
2723 These functions do not move point; instead, they return a position (or
2724 @code{nil}). Remember that a position is always between two characters;
2725 the position returned by these functions is between two characters with
2726 different properties.
2728 @defun next-property-change pos &optional object limit
2729 The function scans the text forward from position @var{pos} in the
2730 string or buffer @var{object} till it finds a change in some text
2731 property, then returns the position of the change. In other words, it
2732 returns the position of the first character beyond @var{pos} whose
2733 properties are not identical to those of the character just after
2736 If @var{limit} is non-@code{nil}, then the scan ends at position
2737 @var{limit}. If there is no property change before that point,
2738 @code{next-property-change} returns @var{limit}.
2740 The value is @code{nil} if the properties remain unchanged all the way
2741 to the end of @var{object} and @var{limit} is @code{nil}. If the value
2742 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
2743 The value equals @var{pos} only when @var{limit} equals @var{pos}.
2745 Here is an example of how to scan the buffer by chunks of text within
2746 which all properties are constant:
2750 (let ((plist (text-properties-at (point)))
2752 (or (next-property-change (point) (current-buffer))
2754 @r{Process text from point to @var{next-change}@dots{}}
2755 (goto-char next-change)))
2759 @defun next-single-property-change pos prop &optional object limit
2760 The function scans the text forward from position @var{pos} in the
2761 string or buffer @var{object} till it finds a change in the @var{prop}
2762 property, then returns the position of the change. In other words, it
2763 returns the position of the first character beyond @var{pos} whose
2764 @var{prop} property differs from that of the character just after
2767 If @var{limit} is non-@code{nil}, then the scan ends at position
2768 @var{limit}. If there is no property change before that point,
2769 @code{next-single-property-change} returns @var{limit}.
2771 The value is @code{nil} if the property remains unchanged all the way to
2772 the end of @var{object} and @var{limit} is @code{nil}. If the value is
2773 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
2774 equals @var{pos} only if @var{limit} equals @var{pos}.
2777 @defun previous-property-change pos &optional object limit
2778 This is like @code{next-property-change}, but scans back from @var{pos}
2779 instead of forward. If the value is non-@code{nil}, it is a position
2780 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
2784 @defun previous-single-property-change pos prop &optional object limit
2785 This is like @code{next-single-property-change}, but scans back from
2786 @var{pos} instead of forward. If the value is non-@code{nil}, it is a
2787 position less than or equal to @var{pos}; it equals @var{pos} only if
2788 @var{limit} equals @var{pos}.
2791 @defun next-char-property-change pos &optional limit
2792 This is like @code{next-property-change} except that it considers
2793 overlay properties as well as text properties, and if no change is
2794 found before the end of the buffer, it returns the maximum buffer
2795 position rather than @code{nil} (in this sense, it resembles the
2796 corresponding overlay function @code{next-overlay-change}, rather than
2797 @code{next-property-change}). There is no @var{object} operand
2798 because this function operates only on the current buffer. It returns
2799 the next address at which either kind of property changes.
2802 @defun previous-char-property-change pos &optional limit
2803 This is like @code{next-char-property-change}, but scans back from
2804 @var{pos} instead of forward, and returns the minimum buffer
2805 position if no change is found.
2808 @defun next-single-char-property-change pos prop &optional object limit
2809 @tindex next-single-char-property-change
2810 This is like @code{next-single-property-change} except that it
2811 considers overlay properties as well as text properties, and if no
2812 change is found before the end of the @var{object}, it returns the
2813 maximum valid position in @var{object} rather than @code{nil}. Unlike
2814 @code{next-char-property-change}, this function @emph{does} have an
2815 @var{object} operand; if @var{object} is not a buffer, only
2816 text-properties are considered.
2819 @defun previous-single-char-property-change pos prop &optional object limit
2820 @tindex previous-single-char-property-change
2821 This is like @code{next-single-char-property-change}, but scans back
2822 from @var{pos} instead of forward, and returns the minimum valid
2823 position in @var{object} if no change is found.
2826 @defun text-property-any start end prop value &optional object
2827 This function returns non-@code{nil} if at least one character between
2828 @var{start} and @var{end} has a property @var{prop} whose value is
2829 @var{value}. More precisely, it returns the position of the first such
2830 character. Otherwise, it returns @code{nil}.
2832 The optional fifth argument, @var{object}, specifies the string or
2833 buffer to scan. Positions are relative to @var{object}. The default
2834 for @var{object} is the current buffer.
2837 @defun text-property-not-all start end prop value &optional object
2838 This function returns non-@code{nil} if at least one character between
2839 @var{start} and @var{end} does not have a property @var{prop} with value
2840 @var{value}. More precisely, it returns the position of the first such
2841 character. Otherwise, it returns @code{nil}.
2843 The optional fifth argument, @var{object}, specifies the string or
2844 buffer to scan. Positions are relative to @var{object}. The default
2845 for @var{object} is the current buffer.
2848 @node Special Properties
2849 @subsection Properties with Special Meanings
2851 Here is a table of text property names that have special built-in
2852 meanings. The following sections list a few additional special property
2853 names that control filling and property inheritance. All other names
2854 have no standard meaning, and you can use them as you like.
2857 @cindex category of text character
2858 @kindex category @r{(text property)}
2860 If a character has a @code{category} property, we call it the
2861 @dfn{category} of the character. It should be a symbol. The properties
2862 of the symbol serve as defaults for the properties of the character.
2865 @cindex face codes of text
2866 @kindex face @r{(text property)}
2867 You can use the property @code{face} to control the font and color of
2868 text. @xref{Faces}, for more information.
2870 In the simplest case, the value is a face name. It can also be a list;
2871 then each element can be any of these possibilities;
2875 A face name (a symbol or string).
2878 A property list of face attributes. This has the
2879 form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
2880 face attribute name and @var{value} is a meaningful value for that
2881 attribute. With this feature, you do not need to create a face each
2882 time you want to specify a particular attribute for certain text.
2883 @xref{Face Attributes}.
2886 A cons cell of the form @code{(foreground-color . @var{color-name})} or
2887 @code{(background-color . @var{color-name})}. These elements specify
2888 just the foreground color or just the background color.
2890 @code{(foreground-color . @var{color-name})} is equivalent to
2891 @code{(:foreground @var{color-name})}, and likewise for the background.
2894 You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically
2895 update @code{face} properties based on the contents of the text.
2897 @item font-lock-face
2898 @kindex font-lock-face @r{(text property)}
2899 The @code{font-lock-face} property is the same in all respects as the
2900 @code{face} property, but its state of activation is controlled by
2901 @code{font-lock-mode}. This can be advantageous for special buffers
2902 which are not intended to be user-editable, or for static areas of
2903 text which are always fontified in the same way.
2904 @xref{Precalculated Fontification}.
2906 Strictly speaking, @code{font-lock-face} is not a built-in text
2907 property; rather, it is implemented in Font Lock mode using
2908 @code{char-property-alias-alist}. @xref{Examining Properties}.
2910 This property is new in Emacs 22.1.
2913 @kindex mouse-face @r{(text property)}
2914 The property @code{mouse-face} is used instead of @code{face} when the
2915 mouse is on or near the character. For this purpose, ``near'' means
2916 that all text between the character and where the mouse is have the same
2917 @code{mouse-face} property value.
2920 @kindex fontified @r{(text property)}
2921 This property, if non-@code{nil}, says that text in the buffer has
2922 had faces assigned automatically by a feature such as Font-Lock mode.
2926 @kindex display @r{(text property)}
2927 This property activates various features that change the
2928 way text is displayed. For example, it can make text appear taller
2929 or shorter, higher or lower, wider or narrow, or replaced with an image.
2930 @xref{Display Property}.
2933 @kindex help-echo @r{(text property)}
2935 @anchor{Text help-echo}
2936 If text has a string as its @code{help-echo} property, then when you
2937 move the mouse onto that text, Emacs displays that string in the echo
2938 area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
2941 If the value of the @code{help-echo} property is a function, that
2942 function is called with three arguments, @var{window}, @var{object} and
2943 @var{pos} and should return a help string or @code{nil} for
2944 none. The first argument, @var{window} is the window in which
2945 the help was found. The second, @var{object}, is the buffer, overlay or
2946 string which had the @code{help-echo} property. The @var{pos}
2947 argument is as follows:
2951 If @var{object} is a buffer, @var{pos} is the position in the buffer
2952 where the @code{help-echo} text property was found.
2954 If @var{object} is an overlay, that overlay has a @code{help-echo}
2955 property, and @var{pos} is the position in the overlay's buffer under
2958 If @var{object} is a string (an overlay string or a string displayed
2959 with the @code{display} property), @var{pos} is the position in that
2960 string under the mouse.
2963 If the value of the @code{help-echo} property is neither a function nor
2964 a string, it is evaluated to obtain a help string.
2966 You can alter the way help text is displayed by setting the variable
2967 @code{show-help-function} (@pxref{Help display}).
2969 This feature is used in the mode line and for other active text.
2972 @cindex keymap of character
2973 @kindex keymap @r{(text property)}
2974 The @code{keymap} property specifies an additional keymap for
2975 commands. The property's value for the character before point applies
2976 if it is non-@code{nil} and rear-sticky, and the property's value for
2977 the character after point applies if it is non-@code{nil} and
2978 front-sticky. (For mouse clicks, the position of the click is used
2979 instead of the position of point.) If the property value is a symbol,
2980 the symbol's function definition is used as the keymap.
2982 When this keymap applies, it is used for key lookup before the minor
2983 mode keymaps and before the buffer's local map. @xref{Active
2987 @kindex local-map @r{(text property)}
2988 This property works like @code{keymap} except that it specifies a
2989 keymap to use @emph{instead of} the buffer's local map. For most
2990 purposes (perhaps all purposes), the @code{keymap} is superior.
2993 The @code{syntax-table} property overrides what the syntax table says
2994 about this particular character. @xref{Syntax Properties}.
2997 @cindex read-only character
2998 @kindex read-only @r{(text property)}
2999 If a character has the property @code{read-only}, then modifying that
3000 character is not allowed. Any command that would do so gets an error,
3001 @code{text-read-only}.
3003 Insertion next to a read-only character is an error if inserting
3004 ordinary text there would inherit the @code{read-only} property due to
3005 stickiness. Thus, you can control permission to insert next to
3006 read-only text by controlling the stickiness. @xref{Sticky Properties}.
3008 Since changing properties counts as modifying the buffer, it is not
3009 possible to remove a @code{read-only} property unless you know the
3010 special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
3011 and then remove the property. @xref{Read Only Buffers}.
3014 @kindex invisible @r{(text property)}
3015 A non-@code{nil} @code{invisible} property can make a character invisible
3016 on the screen. @xref{Invisible Text}, for details.
3019 @kindex intangible @r{(text property)}
3020 If a group of consecutive characters have equal and non-@code{nil}
3021 @code{intangible} properties, then you cannot place point between them.
3022 If you try to move point forward into the group, point actually moves to
3023 the end of the group. If you try to move point backward into the group,
3024 point actually moves to the start of the group.
3026 When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
3027 the @code{intangible} property is ignored.
3030 @kindex field @r{(text property)}
3031 Consecutive characters with the same @code{field} property constitute a
3032 @dfn{field}. Some motion functions including @code{forward-word} and
3033 @code{beginning-of-line} stop moving at a field boundary.
3037 @kindex cursor @r{(text property)}
3038 Normally, the cursor is displayed at the end of any overlay and text
3039 property strings present at the current window position. You can
3040 place the cursor on any desired character of these strings by giving
3041 that character a non-@code{nil} @var{cursor} text property.
3044 @kindex pointer @r{(text property)}
3045 This specifies a specific pointer shape when the mouse pointer is over
3046 this text or image. See the variable @var{void-area-text-pointer}
3047 for possible pointer shapes.
3050 @kindex line-spacing @r{(text property)}
3051 A newline can have a @code{line-spacing} text or overlay property that
3052 controls the height of the display line ending with that newline. The
3053 property value overrides the default frame line spacing and the buffer
3054 local @code{line-spacing} variable. @xref{Line Height}.
3057 @kindex line-height @r{(text property)}
3058 A newline can have a @code{line-height} text or overlay property that
3059 controls the total height of the display line ending in that newline.
3062 @item modification-hooks
3063 @cindex change hooks for a character
3064 @cindex hooks for changing a character
3065 @kindex modification-hooks @r{(text property)}
3066 If a character has the property @code{modification-hooks}, then its
3067 value should be a list of functions; modifying that character calls all
3068 of those functions. Each function receives two arguments: the beginning
3069 and end of the part of the buffer being modified. Note that if a
3070 particular modification hook function appears on several characters
3071 being modified by a single primitive, you can't predict how many times
3072 the function will be called.
3074 @item insert-in-front-hooks
3075 @itemx insert-behind-hooks
3076 @kindex insert-in-front-hooks @r{(text property)}
3077 @kindex insert-behind-hooks @r{(text property)}
3078 The operation of inserting text in a buffer also calls the functions
3079 listed in the @code{insert-in-front-hooks} property of the following
3080 character and in the @code{insert-behind-hooks} property of the
3081 preceding character. These functions receive two arguments, the
3082 beginning and end of the inserted text. The functions are called
3083 @emph{after} the actual insertion takes place.
3085 See also @ref{Change Hooks}, for other hooks that are called
3086 when you change text in a buffer.
3090 @cindex hooks for motion of point
3091 @kindex point-entered @r{(text property)}
3092 @kindex point-left @r{(text property)}
3093 The special properties @code{point-entered} and @code{point-left}
3094 record hook functions that report motion of point. Each time point
3095 moves, Emacs compares these two property values:
3099 the @code{point-left} property of the character after the old location,
3102 the @code{point-entered} property of the character after the new
3107 If these two values differ, each of them is called (if not @code{nil})
3108 with two arguments: the old value of point, and the new one.
3110 The same comparison is made for the characters before the old and new
3111 locations. The result may be to execute two @code{point-left} functions
3112 (which may be the same function) and/or two @code{point-entered}
3113 functions (which may be the same function). In any case, all the
3114 @code{point-left} functions are called first, followed by all the
3115 @code{point-entered} functions.
3117 It is possible with @code{char-after} to examine characters at various
3118 buffer positions without moving point to those positions. Only an
3119 actual change in the value of point runs these hook functions.
3122 @defvar inhibit-point-motion-hooks
3123 When this variable is non-@code{nil}, @code{point-left} and
3124 @code{point-entered} hooks are not run, and the @code{intangible}
3125 property has no effect. Do not set this variable globally; bind it with
3129 @defvar show-help-function
3130 @tindex show-help-function
3131 @anchor{Help display} If this variable is non-@code{nil}, it specifies a
3132 function called to display help strings. These may be @code{help-echo}
3133 properties, menu help strings (@pxref{Simple Menu Items},
3134 @pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
3135 Bar}). The specified function is called with one argument, the help
3136 string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs
3137 Manual}) provides an example.
3140 @node Format Properties
3141 @subsection Formatted Text Properties
3143 These text properties affect the behavior of the fill commands. They
3144 are used for representing formatted text. @xref{Filling}, and
3149 If a newline character has this property, it is a ``hard'' newline.
3150 The fill commands do not alter hard newlines and do not move words
3151 across them. However, this property takes effect only if the
3152 @code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft
3153 Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
3156 This property specifies an extra right margin for filling this part of the
3160 This property specifies an extra left margin for filling this part of the
3164 This property specifies the style of justification for filling this part
3168 @node Sticky Properties
3169 @subsection Stickiness of Text Properties
3170 @cindex sticky text properties
3171 @cindex inheritance of text properties
3173 Self-inserting characters normally take on the same properties as the
3174 preceding character. This is called @dfn{inheritance} of properties.
3176 In a Lisp program, you can do insertion with inheritance or without,
3177 depending on your choice of insertion primitive. The ordinary text
3178 insertion functions such as @code{insert} do not inherit any properties.
3179 They insert text with precisely the properties of the string being
3180 inserted, and no others. This is correct for programs that copy text
3181 from one context to another---for example, into or out of the kill ring.
3182 To insert with inheritance, use the special primitives described in this
3183 section. Self-inserting characters inherit properties because they work
3184 using these primitives.
3186 When you do insertion with inheritance, @emph{which} properties are
3187 inherited, and from where, depends on which properties are @dfn{sticky}.
3188 Insertion after a character inherits those of its properties that are
3189 @dfn{rear-sticky}. Insertion before a character inherits those of its
3190 properties that are @dfn{front-sticky}. When both sides offer different
3191 sticky values for the same property, the previous character's value
3194 By default, a text property is rear-sticky but not front-sticky; thus,
3195 the default is to inherit all the properties of the preceding character,
3196 and nothing from the following character.
3198 You can control the stickiness of various text properties with two
3199 specific text properties, @code{front-sticky} and @code{rear-nonsticky},
3200 and with the variable @code{text-property-default-nonsticky}. You can
3201 use the variable to specify a different default for a given property.
3202 You can use those two text properties to make any specific properties
3203 sticky or nonsticky in any particular part of the text.
3205 If a character's @code{front-sticky} property is @code{t}, then all
3206 its properties are front-sticky. If the @code{front-sticky} property is
3207 a list, then the sticky properties of the character are those whose
3208 names are in the list. For example, if a character has a
3209 @code{front-sticky} property whose value is @code{(face read-only)},
3210 then insertion before the character can inherit its @code{face} property
3211 and its @code{read-only} property, but no others.
3213 The @code{rear-nonsticky} property works the opposite way. Most
3214 properties are rear-sticky by default, so the @code{rear-nonsticky}
3215 property says which properties are @emph{not} rear-sticky. If a
3216 character's @code{rear-nonsticky} property is @code{t}, then none of its
3217 properties are rear-sticky. If the @code{rear-nonsticky} property is a
3218 list, properties are rear-sticky @emph{unless} their names are in the
3221 @defvar text-property-default-nonsticky
3222 @tindex text-property-default-nonsticky
3223 This variable holds an alist which defines the default rear-stickiness
3224 of various text properties. Each element has the form
3225 @code{(@var{property} . @var{nonstickiness})}, and it defines the
3226 stickiness of a particular text property, @var{property}.
3228 If @var{nonstickiness} is non-@code{nil}, this means that the property
3229 @var{property} is rear-nonsticky by default. Since all properties are
3230 front-nonsticky by default, this makes @var{property} nonsticky in both
3231 directions by default.
3233 The text properties @code{front-sticky} and @code{rear-nonsticky}, when
3234 used, take precedence over the default @var{nonstickiness} specified in
3235 @code{text-property-default-nonsticky}.
3238 Here are the functions that insert text with inheritance of properties:
3240 @defun insert-and-inherit &rest strings
3241 Insert the strings @var{strings}, just like the function @code{insert},
3242 but inherit any sticky properties from the adjoining text.
3245 @defun insert-before-markers-and-inherit &rest strings
3246 Insert the strings @var{strings}, just like the function
3247 @code{insert-before-markers}, but inherit any sticky properties from the
3251 @xref{Insertion}, for the ordinary insertion functions which do not
3254 @node Saving Properties
3255 @subsection Saving Text Properties in Files
3256 @cindex text properties in files
3257 @cindex saving text properties
3259 You can save text properties in files (along with the text itself),
3260 and restore the same text properties when visiting or inserting the
3261 files, using these two hooks:
3263 @defvar write-region-annotate-functions
3264 This variable's value is a list of functions for @code{write-region} to
3265 run to encode text properties in some fashion as annotations to the text
3266 being written in the file. @xref{Writing to Files}.
3268 Each function in the list is called with two arguments: the start and
3269 end of the region to be written. These functions should not alter the
3270 contents of the buffer. Instead, they should return lists indicating
3271 annotations to write in the file in addition to the text in the
3274 Each function should return a list of elements of the form
3275 @code{(@var{position} . @var{string})}, where @var{position} is an
3276 integer specifying the relative position within the text to be written,
3277 and @var{string} is the annotation to add there.
3279 Each list returned by one of these functions must be already sorted in
3280 increasing order by @var{position}. If there is more than one function,
3281 @code{write-region} merges the lists destructively into one sorted list.
3283 When @code{write-region} actually writes the text from the buffer to the
3284 file, it intermixes the specified annotations at the corresponding
3285 positions. All this takes place without modifying the buffer.
3288 @defvar after-insert-file-functions
3289 This variable holds a list of functions for @code{insert-file-contents}
3290 to call after inserting a file's contents. These functions should scan
3291 the inserted text for annotations, and convert them to the text
3292 properties they stand for.
3294 Each function receives one argument, the length of the inserted text;
3295 point indicates the start of that text. The function should scan that
3296 text for annotations, delete them, and create the text properties that
3297 the annotations specify. The function should return the updated length
3298 of the inserted text, as it stands after those changes. The value
3299 returned by one function becomes the argument to the next function.
3301 These functions should always return with point at the beginning of
3304 The intended use of @code{after-insert-file-functions} is for converting
3305 some sort of textual annotations into actual text properties. But other
3306 uses may be possible.
3309 We invite users to write Lisp programs to store and retrieve text
3310 properties in files, using these hooks, and thus to experiment with
3311 various data formats and find good ones. Eventually we hope users
3312 will produce good, general extensions we can install in Emacs.
3314 We suggest not trying to handle arbitrary Lisp objects as text property
3315 names or values---because a program that general is probably difficult
3316 to write, and slow. Instead, choose a set of possible data types that
3317 are reasonably flexible, and not too hard to encode.
3319 @xref{Format Conversion}, for a related feature.
3321 @c ??? In next edition, merge this info Format Conversion.
3323 @node Lazy Properties
3324 @subsection Lazy Computation of Text Properties
3326 Instead of computing text properties for all the text in the buffer,
3327 you can arrange to compute the text properties for parts of the text
3328 when and if something depends on them.
3330 The primitive that extracts text from the buffer along with its
3331 properties is @code{buffer-substring}. Before examining the properties,
3332 this function runs the abnormal hook @code{buffer-access-fontify-functions}.
3334 @defvar buffer-access-fontify-functions
3335 This variable holds a list of functions for computing text properties.
3336 Before @code{buffer-substring} copies the text and text properties for a
3337 portion of the buffer, it calls all the functions in this list. Each of
3338 the functions receives two arguments that specify the range of the
3339 buffer being accessed. (The buffer itself is always the current
3343 The function @code{buffer-substring-no-properties} does not call these
3344 functions, since it ignores text properties anyway.
3346 In order to prevent the hook functions from being called more than
3347 once for the same part of the buffer, you can use the variable
3348 @code{buffer-access-fontified-property}.
3350 @defvar buffer-access-fontified-property
3351 If this value's variable is non-@code{nil}, it is a symbol which is used
3352 as a text property name. A non-@code{nil} value for that text property
3353 means, ``the other text properties for this character have already been
3356 If all the characters in the range specified for @code{buffer-substring}
3357 have a non-@code{nil} value for this property, @code{buffer-substring}
3358 does not call the @code{buffer-access-fontify-functions} functions. It
3359 assumes these characters already have the right text properties, and
3360 just copies the properties they already have.
3362 The normal way to use this feature is that the
3363 @code{buffer-access-fontify-functions} functions add this property, as
3364 well as others, to the characters they operate on. That way, they avoid
3365 being called over and over for the same text.
3368 @node Clickable Text
3369 @subsection Defining Clickable Text
3370 @cindex clickable text
3372 There are two ways to set up @dfn{clickable text} in a buffer.
3373 There are typically two parts of this: to make the text highlight
3374 when the mouse is over it, and to make a mouse button do something
3375 when you click it on that part of the text.
3377 Highlighting is done with the @code{mouse-face} text property.
3378 Here is an example of how Dired does it:
3382 (if (dired-move-to-filename)
3383 (put-text-property (point)
3385 (dired-move-to-end-of-filename)
3387 'mouse-face 'highlight))
3392 The first two arguments to @code{put-text-property} specify the
3393 beginning and end of the text.
3395 The usual way to make the mouse do something when you click it
3396 on this text is to define @code{mouse-2} in the major mode's
3397 keymap. The job of checking whether the click was on clickable text
3398 is done by the command definition. Here is how Dired does it:
3401 (defun dired-mouse-find-file-other-window (event)
3402 "In dired, visit the file or directory name you click on."
3406 (set-buffer (window-buffer (posn-window (event-end event))))
3408 (goto-char (posn-point (event-end event)))
3409 (setq file (dired-get-filename))))
3410 (select-window (posn-window (event-end event)))
3411 (find-file-other-window (file-name-sans-versions file t))))
3415 The reason for the outer @code{save-excursion} construct is to avoid
3416 changing the current buffer; the reason for the inner one is to avoid
3417 permanently altering point in the buffer you click on. In this case,
3418 Dired uses the function @code{dired-get-filename} to determine which
3419 file to visit, based on the position found in the event.
3421 Instead of defining a mouse command for the major mode, you can define
3422 a key binding for the clickable text itself, using the @code{keymap}
3426 (let ((map (make-sparse-keymap)))
3427 (define-key map [mouse-2] 'operate-this-button)
3428 (put-text-property (point)
3430 (dired-move-to-end-of-filename)
3436 This method makes it possible to define different commands for various
3437 clickable pieces of text. Also, the major mode definition (or the
3438 global definition) remains available for the rest of the text in the
3441 @node Links and Mouse-1
3442 @subsection Links and Mouse-1
3443 @cindex follow links
3446 The normal Emacs command for activating text in read-only buffers is
3447 @key{Mouse-2}, which includes following textual links. However, most
3448 graphical applications use @key{Mouse-1} for following links. For
3449 compatibility, @key{Mouse-1} follows links in Emacs too, when you
3450 click on a link quickly without moving the mouse. The user can
3451 customize this behaviour through the variable
3452 @code{mouse-1-click-follows-link}.
3454 To define text as a link at the Lisp level, you should bind the
3455 @code{mouse-2} event to a command to follow the link. Then, to indicate that
3456 @key{Mouse-1} should also follow the link, you should specify a
3457 @code{follow-link} condition either as a text property or as a key
3461 @item @code{follow-link} property
3462 If the clickable text has a non-@code{nil} @code{follow-link} text or overlay
3463 property, that specifies the condition.
3465 @item @code{follow-link} event
3466 If there is a binding for the @code{follow-link} event, either on the
3467 clickable text or in the local keymap, the binding is the condition.
3470 Regardless of how you set the @code{follow-link} condition, its
3471 value is used as follows to determine whether the given position is
3472 inside a link, and (if so) to compute an @dfn{action code} saying how
3473 @key{Mouse-1} should handle the link.
3476 @item @code{mouse-face}
3477 If the condition is @code{mouse-face}, a position is inside a link if
3478 there is a non-@code{nil} @code{mouse-face} property at that position.
3479 The action code is always @code{t}.
3481 For example, here is how Info mode handles @key{Mouse-1}:
3484 (define-key Info-mode-map [follow-link] 'mouse-face)
3488 If the condition is a valid function, @var{func}, then a position
3489 @var{pos} is inside a link if @code{(@var{func} @var{pos})} evaluates
3490 to non-@code{nil}. The value returned by @var{func} serves as the
3493 For example, here is how pcvs enables @key{Mouse-1} to follow links on
3497 (define-key map [follow-link]
3499 (if (eq (get-char-property pos 'face) 'cvs-filename-face) t)))
3503 If the condition value is anything else, then the position is inside a
3504 link and the condition itself is the action code. Clearly you should
3505 only specify this kind of condition on the text that constitutes a
3510 The action code tells @key{Mouse-1} how to follow the link:
3513 @item a string or vector
3514 If the action code is a string or vector, the @key{Mouse-1} event is
3515 translated into the first element of the string or vector; i.e., the
3516 action of the @key{Mouse-1} click is the local or global binding of
3517 that character or symbol. Thus, if the action code is @code{"foo"},
3518 @key{Mouse-1} translates into @kbd{f}. If it is @code{[foo]},
3519 @key{Mouse-1} translates into @key{foo}.
3522 For any other non-@code{nil} action code, the @code{mouse-1} event is
3523 translated into a @code{mouse-2} event at the same position.
3526 To define @key{Mouse-1} to activate a button defined with
3527 @code{define-button-type}, give the button a @code{follow-link}
3528 property with a value as specified above to determine how to follow
3529 the link. For example, here is how Help mode handles @key{Mouse-1}:
3532 (define-button-type 'help-xref
3534 'action #'help-button-action)
3537 To define @key{Mouse-1} on a widget defined with
3538 @code{define-widget}, give the widget a @code{:follow-link} property
3539 with a value as specified above to determine how to follow the link.
3541 For example, here is how the @code{link} widget specifies that
3542 a @key{Mouse-1} click shall be translated to @key{RET}:
3545 (define-widget 'link 'item
3547 :button-prefix 'widget-link-prefix
3548 :button-suffix 'widget-link-suffix
3550 :help-echo "Follow the link."
3554 @defun mouse-on-link-p pos
3555 @tindex mouse-on-link-p
3556 This function returns non-@code{nil} if position @var{pos} in the
3557 current buffer is on a link.
3561 @subsection Defining and Using Fields
3564 A field is a range of consecutive characters in the buffer that are
3565 identified by having the same value (comparing with @code{eq}) of the
3566 @code{field} property (either a text-property or an overlay property).
3567 This section describes special functions that are available for
3568 operating on fields.
3570 You specify a field with a buffer position, @var{pos}. We think of
3571 each field as containing a range of buffer positions, so the position
3572 you specify stands for the field containing that position.
3574 When the characters before and after @var{pos} are part of the same
3575 field, there is no doubt which field contains @var{pos}: the one those
3576 characters both belong to. When @var{pos} is at a boundary between
3577 fields, which field it belongs to depends on the stickiness of the
3578 @code{field} properties of the two surrounding characters (@pxref{Sticky
3579 Properties}). The field whose property would be inherited by text
3580 inserted at @var{pos} is the field that contains @var{pos}.
3582 There is an anomalous case where newly inserted text at @var{pos}
3583 would not inherit the @code{field} property from either side. This
3584 happens if the previous character's @code{field} property is not
3585 rear-sticky, and the following character's @code{field} property is not
3586 front-sticky. In this case, @var{pos} belongs to neither the preceding
3587 field nor the following field; the field functions treat it as belonging
3588 to an empty field whose beginning and end are both at @var{pos}.
3590 In all of these functions, if @var{pos} is omitted or @code{nil}, the
3591 value of point is used by default.
3593 @defun field-beginning &optional pos escape-from-edge limit
3594 @tindex field-beginning
3595 This function returns the beginning of the field specified by @var{pos}.
3597 If @var{pos} is at the beginning of its field, and
3598 @var{escape-from-edge} is non-@code{nil}, then the return value is
3599 always the beginning of the preceding field that @emph{ends} at @var{pos},
3600 regardless of the stickiness of the @code{field} properties around
3603 If @var{limit} is non-@code{nil}, it is a buffer position; if the
3604 beginning of the field is before @var{limit}, then @var{limit} will be
3608 @defun field-end &optional pos escape-from-edge limit
3610 This function returns the end of the field specified by @var{pos}.
3612 If @var{pos} is at the end of its field, and @var{escape-from-edge} is
3613 non-@code{nil}, then the return value is always the end of the following
3614 field that @emph{begins} at @var{pos}, regardless of the stickiness of
3615 the @code{field} properties around @var{pos}.
3617 If @var{limit} is non-@code{nil}, it is a buffer position; if the end
3618 of the field is after @var{limit}, then @var{limit} will be returned
3622 @defun field-string &optional pos
3623 @tindex field-string
3624 This function returns the contents of the field specified by @var{pos},
3628 @defun field-string-no-properties &optional pos
3629 @tindex field-string-no-properties
3630 This function returns the contents of the field specified by @var{pos},
3631 as a string, discarding text properties.
3634 @defun delete-field &optional pos
3635 @tindex delete-field
3636 This function deletes the text of the field specified by @var{pos}.
3639 @defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
3640 @tindex constrain-to-field
3641 This function ``constrains'' @var{new-pos} to the field that
3642 @var{old-pos} belongs to---in other words, it returns the position
3643 closest to @var{new-pos} that is in the same field as @var{old-pos}.
3645 If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
3646 the value of point instead, and moves point to the resulting position.
3648 If @var{old-pos} is at the boundary of two fields, then the acceptable
3649 positions for @var{new-pos} depend on the value of the optional argument
3650 @var{escape-from-edge}. If @var{escape-from-edge} is @code{nil}, then
3651 @var{new-pos} is constrained to the field that has the same @code{field}
3652 property (either a text-property or an overlay property) that new
3653 characters inserted at @var{old-pos} would get. (This depends on the
3654 stickiness of the @code{field} property for the characters before and
3655 after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
3656 @var{new-pos} is constrained to the union of the two adjacent fields.
3657 Additionally, if two fields are separated by another field with the
3658 special value @code{boundary}, then any point within this special field
3659 is also considered to be ``on the boundary.''
3661 If the optional argument @var{only-in-line} is non-@code{nil}, and
3662 constraining @var{new-pos} in the usual way would move it to a different
3663 line, @var{new-pos} is returned unconstrained. This used in commands
3664 that move by line, such as @code{next-line} and
3665 @code{beginning-of-line}, so that they respect field boundaries only in
3666 the case where they can still move to the right line.
3668 If the optional argument @var{inhibit-capture-property} is
3669 non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that
3670 name, then any field boundaries are ignored.
3672 You can cause @code{constrain-to-field} to ignore all field boundaries
3673 (and so never constrain anything) by binding the variable
3674 @code{inhibit-field-text-motion} to a non-@code{nil} value.
3678 @subsection Why Text Properties are not Intervals
3681 Some editors that support adding attributes to text in the buffer do
3682 so by letting the user specify ``intervals'' within the text, and adding
3683 the properties to the intervals. Those editors permit the user or the
3684 programmer to determine where individual intervals start and end. We
3685 deliberately provided a different sort of interface in Emacs Lisp to
3686 avoid certain paradoxical behavior associated with text modification.
3688 If the actual subdivision into intervals is meaningful, that means you
3689 can distinguish between a buffer that is just one interval with a
3690 certain property, and a buffer containing the same text subdivided into
3691 two intervals, both of which have that property.
3693 Suppose you take the buffer with just one interval and kill part of
3694 the text. The text remaining in the buffer is one interval, and the
3695 copy in the kill ring (and the undo list) becomes a separate interval.
3696 Then if you yank back the killed text, you get two intervals with the
3697 same properties. Thus, editing does not preserve the distinction
3698 between one interval and two.
3700 Suppose we ``fix'' this problem by coalescing the two intervals when
3701 the text is inserted. That works fine if the buffer originally was a
3702 single interval. But suppose instead that we have two adjacent
3703 intervals with the same properties, and we kill the text of one interval
3704 and yank it back. The same interval-coalescence feature that rescues
3705 the other case causes trouble in this one: after yanking, we have just
3706 one interval. One again, editing does not preserve the distinction
3707 between one interval and two.
3709 Insertion of text at the border between intervals also raises
3710 questions that have no satisfactory answer.
3712 However, it is easy to arrange for editing to behave consistently for
3713 questions of the form, ``What are the properties of this character?''
3714 So we have decided these are the only questions that make sense; we have
3715 not implemented asking questions about where intervals start or end.
3717 In practice, you can usually use the text property search functions in
3718 place of explicit interval boundaries. You can think of them as finding
3719 the boundaries of intervals, assuming that intervals are always
3720 coalesced whenever possible. @xref{Property Search}.
3722 Emacs also provides explicit intervals as a presentation feature; see
3726 @section Substituting for a Character Code
3728 The following functions replace characters within a specified region
3729 based on their character codes.
3731 @defun subst-char-in-region start end old-char new-char &optional noundo
3732 @cindex replace characters
3733 This function replaces all occurrences of the character @var{old-char}
3734 with the character @var{new-char} in the region of the current buffer
3735 defined by @var{start} and @var{end}.
3737 @cindex undo avoidance
3738 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
3739 not record the change for undo and does not mark the buffer as modified.
3740 This was useful for controlling the old selective display feature
3741 (@pxref{Selective Display}).
3743 @code{subst-char-in-region} does not move point and returns
3748 ---------- Buffer: foo ----------
3749 This is the contents of the buffer before.
3750 ---------- Buffer: foo ----------
3754 (subst-char-in-region 1 20 ?i ?X)
3757 ---------- Buffer: foo ----------
3758 ThXs Xs the contents of the buffer before.
3759 ---------- Buffer: foo ----------
3764 @defun translate-region start end table
3765 This function applies a translation table to the characters in the
3766 buffer between positions @var{start} and @var{end}.
3768 The translation table @var{table} is a string or a char-table;
3769 @code{(aref @var{table} @var{ochar})} gives the translated character
3770 corresponding to @var{ochar}. If @var{table} is a string, any
3771 characters with codes larger than the length of @var{table} are not
3772 altered by the translation.
3774 The return value of @code{translate-region} is the number of
3775 characters that were actually changed by the translation. This does
3776 not count characters that were mapped into themselves in the
3784 A register is a sort of variable used in Emacs editing that can hold a
3785 variety of different kinds of values. Each register is named by a
3786 single character. All @acronym{ASCII} characters and their meta variants
3787 (but with the exception of @kbd{C-g}) can be used to name registers.
3788 Thus, there are 255 possible registers. A register is designated in
3789 Emacs Lisp by the character that is its name.
3791 @defvar register-alist
3792 This variable is an alist of elements of the form @code{(@var{name} .
3793 @var{contents})}. Normally, there is one element for each Emacs
3794 register that has been used.
3796 The object @var{name} is a character (an integer) identifying the
3800 The @var{contents} of a register can have several possible types:
3804 A number stands for itself. If @code{insert-register} finds a number
3805 in the register, it converts the number to decimal.
3808 A marker represents a buffer position to jump to.
3811 A string is text saved in the register.
3814 A rectangle is represented by a list of strings.
3816 @item @code{(@var{window-configuration} @var{position})}
3817 This represents a window configuration to restore in one frame, and a
3818 position to jump to in the current buffer.
3820 @item @code{(@var{frame-configuration} @var{position})}
3821 This represents a frame configuration to restore, and a position
3822 to jump to in the current buffer.
3824 @item (file @var{filename})
3825 This represents a file to visit; jumping to this value visits file
3828 @item (file-query @var{filename} @var{position})
3829 This represents a file to visit and a position in it; jumping to this
3830 value visits file @var{filename} and goes to buffer position
3831 @var{position}. Restoring this type of position asks the user for
3835 The functions in this section return unpredictable values unless
3838 @defun get-register reg
3839 This function returns the contents of the register
3840 @var{reg}, or @code{nil} if it has no contents.
3843 @defun set-register reg value
3844 This function sets the contents of register @var{reg} to @var{value}.
3845 A register can be set to any value, but the other register functions
3846 expect only certain data types. The return value is @var{value}.
3849 @deffn Command view-register reg
3850 This command displays what is contained in register @var{reg}.
3854 @deffn Command point-to-register reg
3855 This command stores both the current location of point and the current
3856 buffer in register @var{reg} as a marker.
3859 @deffn Command jump-to-register reg
3860 @deffnx Command register-to-point reg
3861 @comment !!SourceFile register.el
3862 This command restores the status recorded in register @var{reg}.
3864 If @var{reg} contains a marker, it moves point to the position stored in
3865 the marker. Since both the buffer and the location within the buffer
3866 are stored by the @code{point-to-register} function, this command can
3867 switch you to another buffer.
3869 If @var{reg} contains a window configuration or a frame configuration.
3870 @code{jump-to-register} restores that configuration.
3874 @deffn Command insert-register reg &optional beforep
3875 This command inserts contents of register @var{reg} into the current
3878 Normally, this command puts point before the inserted text, and the
3879 mark after it. However, if the optional second argument @var{beforep}
3880 is non-@code{nil}, it puts the mark before and point after.
3881 You can pass a non-@code{nil} second argument @var{beforep} to this
3882 function interactively by supplying any prefix argument.
3884 If the register contains a rectangle, then the rectangle is inserted
3885 with its upper left corner at point. This means that text is inserted
3886 in the current line and underneath it on successive lines.
3888 If the register contains something other than saved text (a string) or
3889 a rectangle (a list), currently useless things happen. This may be
3890 changed in the future.
3894 @deffn Command copy-to-register reg start end &optional delete-flag
3895 This command copies the region from @var{start} to @var{end} into
3896 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
3897 the region from the buffer after copying it into the register.
3900 @deffn Command prepend-to-register reg start end &optional delete-flag
3901 This command prepends the region from @var{start} to @var{end} into
3902 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
3903 the region from the buffer after copying it to the register.
3906 @deffn Command append-to-register reg start end &optional delete-flag
3907 This command appends the region from @var{start} to @var{end} to the
3908 text already in register @var{reg}. If @var{delete-flag} is
3909 non-@code{nil}, it deletes the region from the buffer after copying it
3913 @deffn Command copy-rectangle-to-register reg start end &optional delete-flag
3914 This command copies a rectangular region from @var{start} to @var{end}
3915 into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it
3916 deletes the region from the buffer after copying it to the register.
3919 @deffn Command window-configuration-to-register reg
3920 This function stores the window configuration of the selected frame in
3924 @deffn Command frame-configuration-to-register reg
3925 This function stores the current frame configuration in register
3931 @section Transposition of Text
3933 This subroutine is used by the transposition commands.
3935 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
3936 This function exchanges two nonoverlapping portions of the buffer.
3937 Arguments @var{start1} and @var{end1} specify the bounds of one portion
3938 and arguments @var{start2} and @var{end2} specify the bounds of the
3941 Normally, @code{transpose-regions} relocates markers with the transposed
3942 text; a marker previously positioned within one of the two transposed
3943 portions moves along with that portion, thus remaining between the same
3944 two characters in their new position. However, if @var{leave-markers}
3945 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
3946 all markers unrelocated.
3950 @section Base 64 Encoding
3951 @cindex base 64 encoding
3953 Base 64 code is used in email to encode a sequence of 8-bit bytes as
3954 a longer sequence of @acronym{ASCII} graphic characters. It is defined in
3955 Internet RFC@footnote{
3956 An RFC, an acronym for @dfn{Request for Comments}, is a numbered
3957 Internet informational document describing a standard. RFCs are
3958 usually written by technical experts acting on their own initiative,
3959 and are traditionally written in a pragmatic, experience-driven
3961 }2045. This section describes the functions for
3962 converting to and from this code.
3964 @defun base64-encode-region beg end &optional no-line-break
3965 @tindex base64-encode-region
3966 This function converts the region from @var{beg} to @var{end} into base
3967 64 code. It returns the length of the encoded text. An error is
3968 signaled if a character in the region is multibyte, i.e.@: in a
3969 multibyte buffer the region must contain only characters from the
3970 charsets @code{ascii}, @code{eight-bit-control} and
3971 @code{eight-bit-graphic}.
3973 Normally, this function inserts newline characters into the encoded
3974 text, to avoid overlong lines. However, if the optional argument
3975 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
3976 the output is just one long line.
3979 @defun base64-encode-string string &optional no-line-break
3980 @tindex base64-encode-string
3981 This function converts the string @var{string} into base 64 code. It
3982 returns a string containing the encoded text. As for
3983 @code{base64-encode-region}, an error is signaled if a character in the
3984 string is multibyte.
3986 Normally, this function inserts newline characters into the encoded
3987 text, to avoid overlong lines. However, if the optional argument
3988 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
3989 the result string is just one long line.
3992 @defun base64-decode-region beg end
3993 @tindex base64-decode-region
3994 This function converts the region from @var{beg} to @var{end} from base
3995 64 code into the corresponding decoded text. It returns the length of
3998 The decoding functions ignore newline characters in the encoded text.
4001 @defun base64-decode-string string
4002 @tindex base64-decode-string
4003 This function converts the string @var{string} from base 64 code into
4004 the corresponding decoded text. It returns a unibyte string containing the
4007 The decoding functions ignore newline characters in the encoded text.
4011 @section MD5 Checksum
4012 @cindex MD5 checksum
4013 @cindex message digest computation
4015 MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit
4016 ``fingerprints'' of a document or program. They are used to verify
4017 that you have an exact and unaltered copy of the data. The algorithm
4018 to calculate the MD5 message digest is defined in Internet
4020 For an explanation of what is an RFC, see the footnote in @ref{Base
4022 }1321. This section describes the Emacs facilities for computing
4025 @defun md5 object &optional start end coding-system noerror
4026 This function returns the MD5 message digest of @var{object}, which
4027 should be a buffer or a string.
4029 The two optional arguments @var{start} and @var{end} are character
4030 positions specifying the portion of @var{object} to compute the
4031 message digest for. If they are @code{nil} or omitted, the digest is
4032 computed for the whole of @var{object}.
4034 The function @code{md5} does not compute the message digest directly
4035 from the internal Emacs representation of the text (@pxref{Text
4036 Representations}). Instead, it encodes the text using a coding
4037 system, and computes the message digest from the encoded text. The
4038 optional fourth argument @var{coding-system} specifies which coding
4039 system to use for encoding the text. It should be the same coding
4040 system that you used to read the text, or that you used or will use
4041 when saving or sending the text. @xref{Coding Systems}, for more
4042 information about coding systems.
4044 If @var{coding-system} is @code{nil} or omitted, the default depends
4045 on @var{object}. If @var{object} is a buffer, the default for
4046 @var{coding-system} is whatever coding system would be chosen by
4047 default for writing this text into a file. If @var{object} is a
4048 string, the user's most preferred coding system (@pxref{Recognize
4049 Coding, prefer-coding-system, the description of
4050 @code{prefer-coding-system}, emacs, GNU Emacs Manual}) is used.
4052 Normally, @code{md5} signals an error if the text can't be encoded
4053 using the specified or chosen coding system. However, if
4054 @var{noerror} is non-@code{nil}, it silently uses @code{raw-text}
4058 @node Atomic Changes
4059 @section Atomic Change Groups
4060 @cindex atomic changes
4062 In data base terminology, an @dfn{atomic} change is an indivisible
4063 change---it can succeed entirely or it can fail entirely, but it
4064 cannot partly succeed. A Lisp program can make a series of changes to
4065 one or several buffers as an @dfn{atomic change group}, meaning that
4066 either the entire series of changes will be installed in their buffers
4067 or, in case of an error, none of them will be.
4069 To do this for one buffer, the one already current, simply write a
4070 call to @code{atomic-change-group} around the code that makes the
4074 (atomic-change-group
4076 (delete-region x y))
4080 If an error (or other nonlocal exit) occurs inside the body of
4081 @code{atomic-change-group}, it unmakes all the changes in that buffer
4082 that were during the execution of the body. This kind of change group
4083 has no effect on any other buffers---any such changes remain.
4085 If you need something more sophisticated, such as to make changes in
4086 various buffers constitute one atomic group, you must directly call
4087 lower-level functions that @code{atomic-change-group} uses.
4089 @defun prepare-change-group &optional buffer
4090 This function sets up a change group for buffer @var{buffer}, which
4091 defaults to the current buffer. It returns a ``handle'' that
4092 represents the change group. You must use this handle to activate the
4093 change group and subsequently to finish it.
4096 To use the change group, you must @dfn{activate} it. You must do
4097 this before making any changes in the text of @var{buffer}.
4099 @defun activate-change-group handle
4100 This function activates the change group that @var{handle} designates.
4103 After you activate the change group, any changes you make in that
4104 buffer become part of it. Once you have made all the desired changes
4105 in the buffer, you must @dfn{finish} the change group. There are two
4106 ways to do this: you can either accept (and finalize) all the changes,
4109 @defun accept-change-group handle
4110 This function accepts all the changes in the change group specified by
4111 @var{handle}, making them final.
4114 @defun cancel-change-group handle
4115 This function cancels and undoes all the changes in the change group
4116 specified by @var{handle}.
4119 Your code should use @code{unwind-protect} to make sure the group is
4120 always finished. The call to @code{activate-change-group} should be
4121 inside the @code{unwind-protect}, in case the user types @kbd{C-g}
4122 just after it runs. (This is one reason why
4123 @code{prepare-change-group} and @code{activate-change-group} are
4124 separate functions, because normally you would call
4125 @code{prepare-change-group} before the start of that
4126 @code{unwind-protect}.) Once you finish the group, don't use the
4127 handle again---in particular, don't try to finish the same group
4130 To make a multibuffer change group, call @code{prepare-change-group}
4131 once for each buffer you want to cover, then use @code{nconc} to
4132 combine the returned values, like this:
4135 (nconc (prepare-change-group buffer-1)
4136 (prepare-change-group buffer-2))
4139 You can then activate the multibuffer change group with a single call
4140 to @code{activate-change-group}, and finish it with a single call to
4141 @code{accept-change-group} or @code{cancel-change-group}.
4143 Nested use of several change groups for the same buffer works as you
4144 would expect. Non-nested use of change groups for the same buffer
4145 will get Emacs confused, so don't let it happen; the first change
4146 group you start for any given buffer should be the last one finished.
4149 @section Change Hooks
4150 @cindex change hooks
4151 @cindex hooks for text changes
4153 These hook variables let you arrange to take notice of all changes in
4154 all buffers (or in a particular buffer, if you make them buffer-local).
4155 See also @ref{Special Properties}, for how to detect changes to specific
4158 The functions you use in these hooks should save and restore the match
4159 data if they do anything that uses regular expressions; otherwise, they
4160 will interfere in bizarre ways with the editing operations that call
4163 @defvar before-change-functions
4164 This variable holds a list of functions to call before any buffer
4165 modification. Each function gets two arguments, the beginning and end
4166 of the region that is about to change, represented as integers. The
4167 buffer that is about to change is always the current buffer.
4170 @defvar after-change-functions
4171 This variable holds a list of functions to call after any buffer
4172 modification. Each function receives three arguments: the beginning and
4173 end of the region just changed, and the length of the text that existed
4174 before the change. All three arguments are integers. The buffer that's
4175 about to change is always the current buffer.
4177 The length of the old text is the difference between the buffer positions
4178 before and after that text as it was before the change. As for the
4179 changed text, its length is simply the difference between the first two
4183 Output of messages into the @samp{*Messages*} buffer does not
4184 call these functions.
4186 @defmac combine-after-change-calls body...
4187 The macro executes @var{body} normally, but arranges to call the
4188 after-change functions just once for a series of several changes---if
4191 If a program makes several text changes in the same area of the buffer,
4192 using the macro @code{combine-after-change-calls} around that part of
4193 the program can make it run considerably faster when after-change hooks
4194 are in use. When the after-change hooks are ultimately called, the
4195 arguments specify a portion of the buffer including all of the changes
4196 made within the @code{combine-after-change-calls} body.
4198 @strong{Warning:} You must not alter the values of
4199 @code{after-change-functions} within
4200 the body of a @code{combine-after-change-calls} form.
4202 @strong{Warning:} if the changes you combine occur in widely scattered
4203 parts of the buffer, this will still work, but it is not advisable,
4204 because it may lead to inefficient behavior for some change hook
4208 The two variables above are temporarily bound to @code{nil} during the
4209 time that any of these functions is running. This means that if one of
4210 these functions changes the buffer, that change won't run these
4211 functions. If you do want a hook function to make changes that run
4212 these functions, make it bind these variables back to their usual
4215 One inconvenient result of this protective feature is that you cannot
4216 have a function in @code{after-change-functions} or
4217 @code{before-change-functions} which changes the value of that variable.
4218 But that's not a real limitation. If you want those functions to change
4219 the list of functions to run, simply add one fixed function to the hook,
4220 and code that function to look in another variable for other functions
4221 to call. Here is an example:
4224 (setq my-own-after-change-functions nil)
4225 (defun indirect-after-change-function (beg end len)
4226 (let ((list my-own-after-change-functions))
4228 (funcall (car list) beg end len)
4229 (setq list (cdr list)))))
4232 (add-hooks 'after-change-functions
4233 'indirect-after-change-function)
4237 @defvar first-change-hook
4238 This variable is a normal hook that is run whenever a buffer is changed
4239 that was previously in the unmodified state.
4242 @defvar inhibit-modification-hooks
4243 @tindex inhibit-modification-hooks
4244 If this variable is non-@code{nil}, all of the change hooks are
4245 disabled; none of them run. This affects all the hook variables
4246 described above in this section, as well as the hooks attached to
4247 certain special text properties (@pxref{Special Properties}) and overlay
4248 properties (@pxref{Overlay Properties}).
4252 arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b