2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
4 @c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/text
7 @node Text, Non-ASCII Characters, Markers, Top
11 This chapter describes the functions that deal with the text in a
12 buffer. Most examine, insert, or delete text in the current buffer,
13 often operating at point or on text adjacent to point. Many are
14 interactive. All the functions that change the text provide for undoing
15 the changes (@pxref{Undo}).
17 Many text-related functions operate on a region of text defined by two
18 buffer positions passed in arguments named @var{start} and @var{end}.
19 These arguments should be either markers (@pxref{Markers}) or numeric
20 character positions (@pxref{Positions}). The order of these arguments
21 does not matter; it is all right for @var{start} to be the end of the
22 region and @var{end} the beginning. For example, @code{(delete-region 1
23 10)} and @code{(delete-region 10 1)} are equivalent. An
24 @code{args-out-of-range} error is signaled if either @var{start} or
25 @var{end} is outside the accessible portion of the buffer. In an
26 interactive call, point and the mark are used for these arguments.
28 @cindex buffer contents
29 Throughout this chapter, ``text'' refers to the characters in the
30 buffer, together with their properties (when relevant). Keep in mind
31 that point is always between two characters, and the cursor appears on
32 the character after point.
35 * Near Point:: Examining text in the vicinity of point.
36 * Buffer Contents:: Examining text in a general fashion.
37 * Comparing Text:: Comparing substrings of buffers.
38 * Insertion:: Adding new text to a buffer.
39 * Commands for Insertion:: User-level commands to insert text.
40 * Deletion:: Removing text from a buffer.
41 * User-Level Deletion:: User-level commands to delete text.
42 * The Kill Ring:: Where removed text sometimes is saved for later use.
43 * Undo:: Undoing changes to the text of a buffer.
44 * Maintaining Undo:: How to enable and disable undo information.
45 How to control how much information is kept.
46 * Filling:: Functions for explicit filling.
47 * Margins:: How to specify margins for filling commands.
48 * Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context.
49 * Auto Filling:: How auto-fill mode is implemented to break lines.
50 * Sorting:: Functions for sorting parts of the buffer.
51 * Columns:: Computing horizontal positions, and using them.
52 * Indentation:: Functions to insert or adjust indentation.
53 * Case Changes:: Case conversion of parts of the buffer.
54 * Text Properties:: Assigning Lisp property lists to text characters.
55 * Substitution:: Replacing a given character wherever it appears.
56 * Transposition:: Swapping two portions of a buffer.
57 * Registers:: How registers are implemented. Accessing the text or
58 position stored in a register.
59 * Base 64:: Conversion to or from base 64 encoding.
60 * MD5 Checksum:: Compute the MD5 "message digest"/"checksum".
61 * Atomic Changes:: Installing several buffer changes "atomically".
62 * Change Hooks:: Supplying functions to be run when text is changed.
66 @section Examining Text Near Point
67 @cindex 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 cursor
108 normally appears over the character following point. Therefore, the
109 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 Here's an example which assumes Font-Lock mode is not enabled:
184 ---------- Buffer: foo ----------
185 This is the contents of buffer foo
187 ---------- Buffer: foo ----------
191 (buffer-substring 1 10)
192 @result{} "This is t"
195 (buffer-substring (point-max) 10)
196 @result{} "he contents of buffer foo\n"
200 If the text being copied has any text properties, these are copied into
201 the string along with the characters they belong to. @xref{Text
202 Properties}. However, overlays (@pxref{Overlays}) in the buffer and
203 their properties are ignored, not copied.
205 For example, if Font-Lock mode is enabled, you might get results like
210 (buffer-substring 1 10)
211 @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t))
216 @defun buffer-substring-no-properties start end
217 This is like @code{buffer-substring}, except that it does not copy text
218 properties, just the characters themselves. @xref{Text Properties}.
221 @defun filter-buffer-substring start end &optional delete noprops
222 This function passes the buffer text between @var{start} and @var{end}
223 through the filter functions specified by the variable
224 @code{buffer-substring-filters}, and returns the value from the last
225 filter function. If @code{buffer-substring-filters} is @code{nil},
226 the value is the unaltered text from the buffer, what
227 @code{buffer-substring} would return.
229 If @var{delete} is non-@code{nil}, this function deletes the text
230 between @var{start} and @var{end} after copying it, like
231 @code{delete-and-extract-region}.
233 If @var{noprops} is non-@code{nil}, the final string returned does not
234 include text properties, while the string passed through the filters
235 still includes text properties from the buffer text.
237 Lisp code should use this function instead of @code{buffer-substring},
238 @code{buffer-substring-no-properties},
239 or @code{delete-and-extract-region} when copying into user-accessible
240 data structures such as the kill-ring, X clipboard, and registers.
241 Major and minor modes can add functions to
242 @code{buffer-substring-filters} to alter such text as it is copied out
246 @defvar buffer-substring-filters
247 This variable should be a list of functions that accept a single
248 argument, a string, and return a string.
249 @code{filter-buffer-substring} passes the buffer substring to the
250 first function in this list, and the return value of each function is
251 passed to the next function. The return value of the last function is
252 used as the return value of @code{filter-buffer-substring}.
254 As a special convention, point is set to the start of the buffer text
255 being operated on (i.e., the @var{start} argument for
256 @code{filter-buffer-substring}) before these functions are called.
258 If this variable is @code{nil}, no filtering is performed.
262 This function returns the contents of the entire accessible portion of
263 the current buffer as a string. It is equivalent to
266 (buffer-substring (point-min) (point-max))
271 ---------- Buffer: foo ----------
272 This is the contents of buffer foo
274 ---------- Buffer: foo ----------
277 @result{} "This is the contents of buffer foo\n"
282 @defun current-word &optional strict really-word
283 This function returns the symbol (or word) at or near point, as a string.
284 The return value includes no text properties.
286 If the optional argument @var{really-word} is non-@code{nil}, it finds a
287 word; otherwise, it finds a symbol (which includes both word
288 characters and symbol constituent characters).
290 If the optional argument @var{strict} is non-@code{nil}, then point
291 must be in or next to the symbol or word---if no symbol or word is
292 there, the function returns @code{nil}. Otherwise, a nearby symbol or
293 word on the same line is acceptable.
296 @defun thing-at-point thing
297 Return the @var{thing} around or next to point, as a string.
299 The argument @var{thing} is a symbol which specifies a kind of syntactic
300 entity. Possibilities include @code{symbol}, @code{list}, @code{sexp},
301 @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
302 @code{whitespace}, @code{line}, @code{page}, and others.
305 ---------- Buffer: foo ----------
306 Gentlemen may cry ``Pea@point{}ce! Peace!,''
307 but there is no peace.
308 ---------- Buffer: foo ----------
310 (thing-at-point 'word)
312 (thing-at-point 'line)
313 @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
314 (thing-at-point 'whitespace)
320 @section Comparing Text
321 @cindex comparing buffer text
323 This function lets you compare portions of the text in a buffer, without
324 copying them into strings first.
326 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
327 This function lets you compare two substrings of the same buffer or two
328 different buffers. The first three arguments specify one substring,
329 giving a buffer (or a buffer name) and two positions within the
330 buffer. The last three arguments specify the other substring in the
331 same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or
332 both to stand for the current buffer.
334 The value is negative if the first substring is less, positive if the
335 first is greater, and zero if they are equal. The absolute value of
336 the result is one plus the index of the first differing characters
337 within the substrings.
339 This function ignores case when comparing characters
340 if @code{case-fold-search} is non-@code{nil}. It always ignores
343 Suppose the current buffer contains the text @samp{foobarbar
344 haha!rara!}; then in this example the two substrings are @samp{rbar }
345 and @samp{rara!}. The value is 2 because the first substring is greater
346 at the second character.
349 (compare-buffer-substrings nil 6 11 nil 16 21)
355 @section Inserting Text
356 @cindex insertion of text
357 @cindex text insertion
359 @cindex insertion before point
360 @cindex before point, insertion
361 @dfn{Insertion} means adding new text to a buffer. The inserted text
362 goes at point---between the character before point and the character
363 after point. Some insertion functions leave point before the inserted
364 text, while other functions leave it after. We call the former
365 insertion @dfn{after point} and the latter insertion @dfn{before point}.
367 Insertion relocates markers that point at positions after the
368 insertion point, so that they stay with the surrounding text
369 (@pxref{Markers}). When a marker points at the place of insertion,
370 insertion may or may not relocate the marker, depending on the marker's
371 insertion type (@pxref{Marker Insertion Types}). Certain special
372 functions such as @code{insert-before-markers} relocate all such markers
373 to point after the inserted text, regardless of the markers' insertion
376 Insertion functions signal an error if the current buffer is
377 read-only or if they insert within read-only text.
379 These functions copy text characters from strings and buffers along
380 with their properties. The inserted characters have exactly the same
381 properties as the characters they were copied from. By contrast,
382 characters specified as separate arguments, not part of a string or
383 buffer, inherit their text properties from the neighboring text.
385 The insertion functions convert text from unibyte to multibyte in
386 order to insert in a multibyte buffer, and vice versa---if the text
387 comes from a string or from a buffer. However, they do not convert
388 unibyte character codes 128 through 255 to multibyte characters, not
389 even if the current buffer is a multibyte buffer. @xref{Converting
392 @defun insert &rest args
393 This function inserts the strings and/or characters @var{args} into the
394 current buffer, at point, moving point forward. In other words, it
395 inserts the text before point. An error is signaled unless all
396 @var{args} are either strings or characters. The value is @code{nil}.
399 @defun insert-before-markers &rest args
400 This function inserts the strings and/or characters @var{args} into the
401 current buffer, at point, moving point forward. An error is signaled
402 unless all @var{args} are either strings or characters. The value is
405 This function is unlike the other insertion functions in that it
406 relocates markers initially pointing at the insertion point, to point
407 after the inserted text. If an overlay begins at the insertion point,
408 the inserted text falls outside the overlay; if a nonempty overlay
409 ends at the insertion point, the inserted text falls inside that
413 @defun insert-char character count &optional inherit
414 This function inserts @var{count} instances of @var{character} into the
415 current buffer before point. The argument @var{count} should be an
416 integer, and @var{character} must be a character. The value is @code{nil}.
418 This function does not convert unibyte character codes 128 through 255
419 to multibyte characters, not even if the current buffer is a multibyte
420 buffer. @xref{Converting Representations}.
422 If @var{inherit} is non-@code{nil}, then the inserted characters inherit
423 sticky text properties from the two characters before and after the
424 insertion point. @xref{Sticky Properties}.
427 @defun insert-buffer-substring from-buffer-or-name &optional start end
428 This function inserts a portion of buffer @var{from-buffer-or-name}
429 (which must already exist) into the current buffer before point. The
430 text inserted is the region between @var{start} and @var{end}. (These
431 arguments default to the beginning and end of the accessible portion of
432 that buffer.) This function returns @code{nil}.
434 In this example, the form is executed with buffer @samp{bar} as the
435 current buffer. We assume that buffer @samp{bar} is initially empty.
439 ---------- Buffer: foo ----------
440 We hold these truths to be self-evident, that all
441 ---------- Buffer: foo ----------
445 (insert-buffer-substring "foo" 1 20)
448 ---------- Buffer: bar ----------
449 We hold these truth@point{}
450 ---------- Buffer: bar ----------
455 @defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
456 This is like @code{insert-buffer-substring} except that it does not
457 copy any text properties.
460 @xref{Sticky Properties}, for other insertion functions that inherit
461 text properties from the nearby text in addition to inserting it.
462 Whitespace inserted by indentation functions also inherits text
465 @node Commands for Insertion
466 @section User-Level Insertion Commands
468 This section describes higher-level commands for inserting text,
469 commands intended primarily for the user but useful also in Lisp
472 @deffn Command insert-buffer from-buffer-or-name
473 This command inserts the entire accessible contents of
474 @var{from-buffer-or-name} (which must exist) into the current buffer
475 after point. It leaves the mark after the inserted text. The value
479 @deffn Command self-insert-command count
480 @cindex character insertion
481 @cindex self-insertion
482 This command inserts the last character typed; it does so @var{count}
483 times, before point, and returns @code{nil}. Most printing characters
484 are bound to this command. In routine use, @code{self-insert-command}
485 is the most frequently called function in Emacs, but programs rarely use
486 it except to install it on a keymap.
488 In an interactive call, @var{count} is the numeric prefix argument.
490 Self-insertion translates the input character through
491 @code{translation-table-for-input}. @xref{Translation of Characters}.
493 This command calls @code{auto-fill-function} whenever that is
494 non-@code{nil} and the character inserted is in the table
495 @code{auto-fill-chars} (@pxref{Auto Filling}).
497 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
498 This command performs abbrev expansion if Abbrev mode is enabled and
499 the inserted character does not have word-constituent
500 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also
501 responsible for calling @code{blink-paren-function} when the inserted
502 character has close parenthesis syntax (@pxref{Blinking}).
504 Do not try substituting your own definition of
505 @code{self-insert-command} for the standard one. The editor command
506 loop handles this function specially.
509 @deffn Command newline &optional number-of-newlines
510 This command inserts newlines into the current buffer before point.
511 If @var{number-of-newlines} is supplied, that many newline characters
514 @cindex newline and Auto Fill mode
515 This function calls @code{auto-fill-function} if the current column
516 number is greater than the value of @code{fill-column} and
517 @var{number-of-newlines} is @code{nil}. Typically what
518 @code{auto-fill-function} does is insert a newline; thus, the overall
519 result in this case is to insert two newlines at different places: one
520 at point, and another earlier in the line. @code{newline} does not
521 auto-fill if @var{number-of-newlines} is non-@code{nil}.
523 This command indents to the left margin if that is not zero.
526 The value returned is @code{nil}. In an interactive call, @var{count}
527 is the numeric prefix argument.
530 @defvar overwrite-mode
531 This variable controls whether overwrite mode is in effect. The value
532 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
533 or @code{nil}. @code{overwrite-mode-textual} specifies textual
534 overwrite mode (treats newlines and tabs specially), and
535 @code{overwrite-mode-binary} specifies binary overwrite mode (treats
536 newlines and tabs like any other characters).
540 @section Deleting Text
541 @cindex text deletion
543 @cindex deleting text vs killing
544 Deletion means removing part of the text in a buffer, without saving
545 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
546 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
547 Some deletion functions do save text in the kill ring in some special
550 All of the deletion functions operate on the current buffer.
552 @deffn Command erase-buffer
553 This function deletes the entire text of the current buffer
554 (@emph{not} just the accessible portion), leaving it
555 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
556 error; if some of the text in it is read-only, it signals a
557 @code{text-read-only} error. Otherwise, it deletes the text without
558 asking for any confirmation. It returns @code{nil}.
560 Normally, deleting a large amount of text from a buffer inhibits further
561 auto-saving of that buffer ``because it has shrunk.'' However,
562 @code{erase-buffer} does not do this, the idea being that the future
563 text is not really related to the former text, and its size should not
564 be compared with that of the former text.
567 @deffn Command delete-region start end
568 This command deletes the text between positions @var{start} and
569 @var{end} in the current buffer, and returns @code{nil}. If point was
570 inside the deleted region, its value afterward is @var{start}.
571 Otherwise, point relocates with the surrounding text, as markers do.
574 @defun delete-and-extract-region start end
575 This function deletes the text between positions @var{start} and
576 @var{end} in the current buffer, and returns a string containing the
579 If point was inside the deleted region, its value afterward is
580 @var{start}. Otherwise, point relocates with the surrounding text, as
584 @deffn Command delete-char count &optional killp
585 This command deletes @var{count} characters directly after point, or
586 before point if @var{count} is negative. If @var{killp} is
587 non-@code{nil}, then it saves the deleted characters in the kill ring.
589 In an interactive call, @var{count} is the numeric prefix argument, and
590 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
591 argument is supplied, the text is saved in the kill ring. If no prefix
592 argument is supplied, then one character is deleted, but not saved in
595 The value returned is always @code{nil}.
598 @deffn Command delete-backward-char count &optional killp
599 @cindex deleting previous char
600 This command deletes @var{count} characters directly before point, or
601 after point if @var{count} is negative. If @var{killp} is
602 non-@code{nil}, then it saves the deleted characters in the kill ring.
604 In an interactive call, @var{count} is the numeric prefix argument, and
605 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
606 argument is supplied, the text is saved in the kill ring. If no prefix
607 argument is supplied, then one character is deleted, but not saved in
610 The value returned is always @code{nil}.
613 @deffn Command backward-delete-char-untabify count &optional killp
615 This command deletes @var{count} characters backward, changing tabs
616 into spaces. When the next character to be deleted is a tab, it is
617 first replaced with the proper number of spaces to preserve alignment
618 and then one of those spaces is deleted instead of the tab. If
619 @var{killp} is non-@code{nil}, then the command saves the deleted
620 characters in the kill ring.
622 Conversion of tabs to spaces happens only if @var{count} is positive.
623 If it is negative, exactly @minus{}@var{count} characters after point
626 In an interactive call, @var{count} is the numeric prefix argument, and
627 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
628 argument is supplied, the text is saved in the kill ring. If no prefix
629 argument is supplied, then one character is deleted, but not saved in
632 The value returned is always @code{nil}.
635 @defopt backward-delete-char-untabify-method
636 This option specifies how @code{backward-delete-char-untabify} should
637 deal with whitespace. Possible values include @code{untabify}, the
638 default, meaning convert a tab to many spaces and delete one;
639 @code{hungry}, meaning delete all tabs and spaces before point with
640 one command; @code{all} meaning delete all tabs, spaces and newlines
641 before point, and @code{nil}, meaning do nothing special for
642 whitespace characters.
645 @node User-Level Deletion
646 @section User-Level Deletion Commands
648 This section describes higher-level commands for deleting text,
649 commands intended primarily for the user but useful also in Lisp
652 @deffn Command delete-horizontal-space &optional backward-only
653 @cindex deleting whitespace
654 This function deletes all spaces and tabs around point. It returns
657 If @var{backward-only} is non-@code{nil}, the function deletes
658 spaces and tabs before point, but not after point.
660 In the following examples, we call @code{delete-horizontal-space} four
661 times, once on each line, with point between the second and third
662 characters on the line each time.
666 ---------- Buffer: foo ----------
671 ---------- Buffer: foo ----------
675 (delete-horizontal-space) ; @r{Four times.}
678 ---------- Buffer: foo ----------
683 ---------- Buffer: foo ----------
688 @deffn Command delete-indentation &optional join-following-p
689 This function joins the line point is on to the previous line, deleting
690 any whitespace at the join and in some cases replacing it with one
691 space. If @var{join-following-p} is non-@code{nil},
692 @code{delete-indentation} joins this line to the following line
693 instead. The function returns @code{nil}.
695 If there is a fill prefix, and the second of the lines being joined
696 starts with the prefix, then @code{delete-indentation} deletes the
697 fill prefix before joining the lines. @xref{Margins}.
699 In the example below, point is located on the line starting
700 @samp{events}, and it makes no difference if there are trailing spaces
701 in the preceding line.
705 ---------- Buffer: foo ----------
706 When in the course of human
707 @point{} events, it becomes necessary
708 ---------- Buffer: foo ----------
715 ---------- Buffer: foo ----------
716 When in the course of human@point{} events, it becomes necessary
717 ---------- Buffer: foo ----------
721 After the lines are joined, the function @code{fixup-whitespace} is
722 responsible for deciding whether to leave a space at the junction.
725 @deffn Command fixup-whitespace
726 This function replaces all the horizontal whitespace surrounding point
727 with either one space or no space, according to the context. It
730 At the beginning or end of a line, the appropriate amount of space is
731 none. Before a character with close parenthesis syntax, or after a
732 character with open parenthesis or expression-prefix syntax, no space is
733 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
736 In the example below, @code{fixup-whitespace} is called the first time
737 with point before the word @samp{spaces} in the first line. For the
738 second invocation, point is directly after the @samp{(}.
742 ---------- Buffer: foo ----------
743 This has too many @point{}spaces
744 This has too many spaces at the start of (@point{} this list)
745 ---------- Buffer: foo ----------
756 ---------- Buffer: foo ----------
757 This has too many spaces
758 This has too many spaces at the start of (this list)
759 ---------- Buffer: foo ----------
764 @deffn Command just-one-space &optional n
765 @comment !!SourceFile simple.el
766 This command replaces any spaces and tabs around point with a single
767 space, or @var{n} spaces if @var{n} is specified. It returns
771 @deffn Command delete-blank-lines
772 This function deletes blank lines surrounding point. If point is on a
773 blank line with one or more blank lines before or after it, then all but
774 one of them are deleted. If point is on an isolated blank line, then it
775 is deleted. If point is on a nonblank line, the command deletes all
776 blank lines immediately following it.
778 A blank line is defined as a line containing only tabs and spaces.
780 @code{delete-blank-lines} returns @code{nil}.
784 @section The Kill Ring
787 @dfn{Kill functions} delete text like the deletion functions, but save
788 it so that the user can reinsert it by @dfn{yanking}. Most of these
789 functions have @samp{kill-} in their name. By contrast, the functions
790 whose names start with @samp{delete-} normally do not save text for
791 yanking (though they can still be undone); these are ``deletion''
794 Most of the kill commands are primarily for interactive use, and are
795 not described here. What we do describe are the functions provided for
796 use in writing such commands. You can use these functions to write
797 commands for killing text. When you need to delete text for internal
798 purposes within a Lisp function, you should normally use deletion
799 functions, so as not to disturb the kill ring contents.
802 Killed text is saved for later yanking in the @dfn{kill ring}. This
803 is a list that holds a number of recent kills, not just the last text
804 kill. We call this a ``ring'' because yanking treats it as having
805 elements in a cyclic order. The list is kept in the variable
806 @code{kill-ring}, and can be operated on with the usual functions for
807 lists; there are also specialized functions, described in this section,
808 that treat it as a ring.
810 Some people think this use of the word ``kill'' is unfortunate, since
811 it refers to operations that specifically @emph{do not} destroy the
812 entities ``killed.'' This is in sharp contrast to ordinary life, in
813 which death is permanent and ``killed'' entities do not come back to
814 life. Therefore, other metaphors have been proposed. For example, the
815 term ``cut ring'' makes sense to people who, in pre-computer days, used
816 scissors and paste to cut up and rearrange manuscripts. However, it
817 would be difficult to change the terminology now.
820 * Kill Ring Concepts:: What text looks like in the kill ring.
821 * Kill Functions:: Functions that kill text.
822 * Yanking:: How yanking is done.
823 * Yank Commands:: Commands that access the kill ring.
824 * Low-Level Kill Ring:: Functions and variables for kill ring access.
825 * Internals of Kill Ring:: Variables that hold kill ring data.
828 @node Kill Ring Concepts
829 @comment node-name, next, previous, up
830 @subsection Kill Ring Concepts
832 The kill ring records killed text as strings in a list, most recent
833 first. A short kill ring, for example, might look like this:
836 ("some text" "a different piece of text" "even older text")
840 When the list reaches @code{kill-ring-max} entries in length, adding a
841 new entry automatically deletes the last entry.
843 When kill commands are interwoven with other commands, each kill
844 command makes a new entry in the kill ring. Multiple kill commands in
845 succession build up a single kill ring entry, which would be yanked as a
846 unit; the second and subsequent consecutive kill commands add text to
847 the entry made by the first one.
849 For yanking, one entry in the kill ring is designated the ``front'' of
850 the ring. Some yank commands ``rotate'' the ring by designating a
851 different element as the ``front.'' But this virtual rotation doesn't
852 change the list itself---the most recent entry always comes first in the
856 @comment node-name, next, previous, up
857 @subsection Functions for Killing
859 @code{kill-region} is the usual subroutine for killing text. Any
860 command that calls this function is a ``kill command'' (and should
861 probably have @samp{kill} in its name). @code{kill-region} puts the
862 newly killed text in a new element at the beginning of the kill ring or
863 adds it to the most recent element. It determines automatically (using
864 @code{last-command}) whether the previous command was a kill command,
865 and if so appends the killed text to the most recent entry.
867 @deffn Command kill-region start end &optional yank-handler
868 This function kills the text in the region defined by @var{start} and
869 @var{end}. The text is deleted but saved in the kill ring, along with
870 its text properties. The value is always @code{nil}.
872 In an interactive call, @var{start} and @var{end} are point and
876 If the buffer or text is read-only, @code{kill-region} modifies the kill
877 ring just the same, then signals an error without modifying the buffer.
878 This is convenient because it lets the user use a series of kill
879 commands to copy text from a read-only buffer into the kill ring.
881 If @var{yank-handler} is non-@code{nil}, this puts that value onto
882 the string of killed text, as a @code{yank-handler} text property.
883 @xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, any
884 @code{yank-handler} properties present on the killed text are copied
885 onto the kill ring, like other text properties.
888 @defopt kill-read-only-ok
889 If this option is non-@code{nil}, @code{kill-region} does not signal an
890 error if the buffer or text is read-only. Instead, it simply returns,
891 updating the kill ring but not changing the buffer.
894 @deffn Command copy-region-as-kill start end
895 This command saves the region defined by @var{start} and @var{end} on
896 the kill ring (including text properties), but does not delete the text
897 from the buffer. It returns @code{nil}.
899 The command does not set @code{this-command} to @code{kill-region}, so a
900 subsequent kill command does not append to the same kill ring entry.
902 Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
903 support Emacs 18. For newer Emacs versions, it is better to use
904 @code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill
911 Yanking means inserting text from the kill ring, but it does
912 not insert the text blindly. Yank commands and some other commands
913 use @code{insert-for-yank} to perform special processing on the
914 text that they copy into the buffer.
916 @defun insert-for-yank string
917 This function normally works like @code{insert} except that it doesn't
918 insert the text properties in the @code{yank-excluded-properties}
919 list. However, if any part of @var{string} has a non-@code{nil}
920 @code{yank-handler} text property, that property can do various
921 special processing on that part of the text being inserted.
924 @defun insert-buffer-substring-as-yank buf &optional start end
925 This function resembles @code{insert-buffer-substring} except that it
926 doesn't insert the text properties in the
927 @code{yank-excluded-properties} list.
930 You can put a @code{yank-handler} text property on all or part of
931 the text to control how it will be inserted if it is yanked. The
932 @code{insert-for-yank} function looks for that property. The property
933 value must be a list of one to four elements, with the following
934 format (where elements after the first may be omitted):
937 (@var{function} @var{param} @var{noexclude} @var{undo})
940 Here is what the elements do:
944 When @var{function} is present and non-@code{nil}, it is called instead of
945 @code{insert} to insert the string. @var{function} takes one
946 argument---the string to insert.
949 If @var{param} is present and non-@code{nil}, it replaces @var{string}
950 (or the part of @var{string} being processed) as the object passed to
951 @var{function} (or @code{insert}); for example, if @var{function} is
952 @code{yank-rectangle}, @var{param} should be a list of strings to
953 insert as a rectangle.
956 If @var{noexclude} is present and non-@code{nil}, the normal removal of the
957 yank-excluded-properties is not performed; instead @var{function} is
958 responsible for removing those properties. This may be necessary
959 if @var{function} adjusts point before or after inserting the object.
962 If @var{undo} is present and non-@code{nil}, it is a function that will be
963 called by @code{yank-pop} to undo the insertion of the current object.
964 It is called with two arguments, the start and end of the current
965 region. @var{function} can set @code{yank-undo-function} to override
966 the @var{undo} value.
970 @comment node-name, next, previous, up
971 @subsection Functions for Yanking
973 This section describes higher-level commands for yanking, which are
974 intended primarily for the user but useful also in Lisp programs.
975 Both @code{yank} and @code{yank-pop} honor the
976 @code{yank-excluded-properties} variable and @code{yank-handler} text
977 property (@pxref{Yanking}).
979 @deffn Command yank &optional arg
980 @cindex inserting killed text
981 This command inserts before point the text at the front of the
982 kill ring. It positions the mark at the beginning of that text, and
985 If @var{arg} is a non-@code{nil} list (which occurs interactively when
986 the user types @kbd{C-u} with no digits), then @code{yank} inserts the
987 text as described above, but puts point before the yanked text and
988 puts the mark after it.
990 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th
991 most recently killed text---the @var{arg}th element of the kill ring
992 list, counted cyclically from the front, which is considered the
993 first element for this purpose.
995 @code{yank} does not alter the contents of the kill ring, unless it
996 used text provided by another program, in which case it pushes that text
997 onto the kill ring. However if @var{arg} is an integer different from
998 one, it rotates the kill ring to place the yanked string at the front.
1000 @code{yank} returns @code{nil}.
1003 @deffn Command yank-pop &optional arg
1004 This command replaces the just-yanked entry from the kill ring with a
1005 different entry from the kill ring.
1007 This is allowed only immediately after a @code{yank} or another
1008 @code{yank-pop}. At such a time, the region contains text that was just
1009 inserted by yanking. @code{yank-pop} deletes that text and inserts in
1010 its place a different piece of killed text. It does not add the deleted
1011 text to the kill ring, since it is already in the kill ring somewhere.
1012 It does however rotate the kill ring to place the newly yanked string at
1015 If @var{arg} is @code{nil}, then the replacement text is the previous
1016 element of the kill ring. If @var{arg} is numeric, the replacement is
1017 the @var{arg}th previous kill. If @var{arg} is negative, a more recent
1018 kill is the replacement.
1020 The sequence of kills in the kill ring wraps around, so that after the
1021 oldest one comes the newest one, and before the newest one goes the
1024 The return value is always @code{nil}.
1027 @defvar yank-undo-function
1028 If this variable is non-@code{nil}, the function @code{yank-pop} uses
1029 its value instead of @code{delete-region} to delete the text
1030 inserted by the previous @code{yank} or
1031 @code{yank-pop} command. The value must be a function of two
1032 arguments, the start and end of the current region.
1034 The function @code{insert-for-yank} automatically sets this variable
1035 according to the @var{undo} element of the @code{yank-handler}
1036 text property, if there is one.
1039 @node Low-Level Kill Ring
1040 @subsection Low-Level Kill Ring
1042 These functions and variables provide access to the kill ring at a
1043 lower level, but still convenient for use in Lisp programs, because they
1044 take care of interaction with window system selections
1045 (@pxref{Window System Selections}).
1047 @defun current-kill n &optional do-not-move
1048 The function @code{current-kill} rotates the yanking pointer, which
1049 designates the ``front'' of the kill ring, by @var{n} places (from newer
1050 kills to older ones), and returns the text at that place in the ring.
1052 If the optional second argument @var{do-not-move} is non-@code{nil},
1053 then @code{current-kill} doesn't alter the yanking pointer; it just
1054 returns the @var{n}th kill, counting from the current yanking pointer.
1056 If @var{n} is zero, indicating a request for the latest kill,
1057 @code{current-kill} calls the value of
1058 @code{interprogram-paste-function} (documented below) before
1059 consulting the kill ring. If that value is a function and calling it
1060 returns a string, @code{current-kill} pushes that string onto the kill
1061 ring and returns it. It also sets the yanking pointer to point to
1062 that new entry, regardless of the value of @var{do-not-move}.
1063 Otherwise, @code{current-kill} does not treat a zero value for @var{n}
1064 specially: it returns the entry pointed at by the yanking pointer and
1065 does not move the yanking pointer.
1068 @defun kill-new string &optional replace yank-handler
1069 This function pushes the text @var{string} onto the kill ring and
1070 makes the yanking pointer point to it. It discards the oldest entry
1071 if appropriate. It also invokes the value of
1072 @code{interprogram-cut-function} (see below).
1074 If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the
1075 first element of the kill ring with @var{string}, rather than pushing
1076 @var{string} onto the kill ring.
1078 If @var{yank-handler} is non-@code{nil}, this puts that value onto
1079 the string of killed text, as a @code{yank-handler} property.
1080 @xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, then
1081 @code{kill-new} copies any @code{yank-handler} properties present on
1082 @var{string} onto the kill ring, as it does with other text properties.
1085 @defun kill-append string before-p &optional yank-handler
1086 This function appends the text @var{string} to the first entry in the
1087 kill ring and makes the yanking pointer point to the combined entry.
1088 Normally @var{string} goes at the end of the entry, but if
1089 @var{before-p} is non-@code{nil}, it goes at the beginning. This
1090 function also invokes the value of @code{interprogram-cut-function}
1091 (see below). This handles @var{yank-handler} just like
1092 @code{kill-new}, except that if @var{yank-handler} is different from
1093 the @code{yank-handler} property of the first entry of the kill ring,
1094 @code{kill-append} pushes the concatenated string onto the kill ring,
1095 instead of replacing the original first entry with it.
1098 @defvar interprogram-paste-function
1099 This variable provides a way of transferring killed text from other
1100 programs, when you are using a window system. Its value should be
1101 @code{nil} or a function of no arguments.
1103 If the value is a function, @code{current-kill} calls it to get the
1104 ``most recent kill.'' If the function returns a non-@code{nil} value,
1105 then that value is used as the ``most recent kill.'' If it returns
1106 @code{nil}, then the front of the kill ring is used.
1108 The normal use of this hook is to get the window system's primary
1109 selection as the most recent kill, even if the selection belongs to
1110 another application. @xref{Window System Selections}.
1113 @defvar interprogram-cut-function
1114 This variable provides a way of communicating killed text to other
1115 programs, when you are using a window system. Its value should be
1116 @code{nil} or a function of one required and one optional argument.
1118 If the value is a function, @code{kill-new} and @code{kill-append} call
1119 it with the new first element of the kill ring as the first argument.
1120 The second, optional, argument has the same meaning as the @var{push}
1121 argument to @code{x-set-cut-buffer} (@pxref{Definition of
1122 x-set-cut-buffer}) and only affects the second and later cut buffers.
1124 The normal use of this hook is to set the window system's primary
1125 selection (and first cut buffer) from the newly killed text.
1126 @xref{Window System Selections}.
1129 @node Internals of Kill Ring
1130 @comment node-name, next, previous, up
1131 @subsection Internals of the Kill Ring
1133 The variable @code{kill-ring} holds the kill ring contents, in the
1134 form of a list of strings. The most recent kill is always at the front
1137 The @code{kill-ring-yank-pointer} variable points to a link in the
1138 kill ring list, whose @sc{car} is the text to yank next. We say it
1139 identifies the ``front'' of the ring. Moving
1140 @code{kill-ring-yank-pointer} to a different link is called
1141 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
1142 the functions that move the yank pointer wrap around from the end of the
1143 list to the beginning, or vice-versa. Rotation of the kill ring is
1144 virtual; it does not change the value of @code{kill-ring}.
1146 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
1147 variables whose values are normally lists. The word ``pointer'' in the
1148 name of the @code{kill-ring-yank-pointer} indicates that the variable's
1149 purpose is to identify one element of the list for use by the next yank
1152 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
1153 of the links in the kill ring list. The element it identifies is the
1154 @sc{car} of that link. Kill commands, which change the kill ring, also
1155 set this variable to the value of @code{kill-ring}. The effect is to
1156 rotate the ring so that the newly killed text is at the front.
1158 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
1159 pointing to the second entry in the kill ring @code{("some text" "a
1160 different piece of text" "yet older text")}.
1164 kill-ring ---- kill-ring-yank-pointer
1167 | --- --- --- --- --- ---
1168 --> | | |------> | | |--> | | |--> nil
1169 --- --- --- --- --- ---
1172 | | -->"yet older text"
1174 | --> "a different piece of text"
1181 This state of affairs might occur after @kbd{C-y} (@code{yank})
1182 immediately followed by @kbd{M-y} (@code{yank-pop}).
1185 This variable holds the list of killed text sequences, most recently
1189 @defvar kill-ring-yank-pointer
1190 This variable's value indicates which element of the kill ring is at the
1191 ``front'' of the ring for yanking. More precisely, the value is a tail
1192 of the value of @code{kill-ring}, and its @sc{car} is the kill string
1193 that @kbd{C-y} should yank.
1196 @defopt kill-ring-max
1197 The value of this variable is the maximum length to which the kill
1198 ring can grow, before elements are thrown away at the end. The default
1199 value for @code{kill-ring-max} is 60.
1203 @comment node-name, next, previous, up
1207 Most buffers have an @dfn{undo list}, which records all changes made
1208 to the buffer's text so that they can be undone. (The buffers that
1209 don't have one are usually special-purpose buffers for which Emacs
1210 assumes that undoing is not useful. In particular, any buffer whose
1211 name begins with a space has its undo recording off by default;
1212 see @ref{Buffer Names}.) All the primitives that modify the
1213 text in the buffer automatically add elements to the front of the undo
1214 list, which is in the variable @code{buffer-undo-list}.
1216 @defvar buffer-undo-list
1217 This buffer-local variable's value is the undo list of the current
1218 buffer. A value of @code{t} disables the recording of undo information.
1221 Here are the kinds of elements an undo list can have:
1224 @item @var{position}
1225 This kind of element records a previous value of point; undoing this
1226 element moves point to @var{position}. Ordinary cursor motion does not
1227 make any sort of undo record, but deletion operations use these entries
1228 to record where point was before the command.
1230 @item (@var{beg} . @var{end})
1231 This kind of element indicates how to delete text that was inserted.
1232 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
1235 @item (@var{text} . @var{position})
1236 This kind of element indicates how to reinsert text that was deleted.
1237 The deleted text itself is the string @var{text}. The place to
1238 reinsert it is @code{(abs @var{position})}. If @var{position} is
1239 positive, point was at the beginning of the deleted text, otherwise it
1242 @item (t @var{high} . @var{low})
1243 This kind of element indicates that an unmodified buffer became
1244 modified. The elements @var{high} and @var{low} are two integers, each
1245 recording 16 bits of the visited file's modification time as of when it
1246 was previously visited or saved. @code{primitive-undo} uses those
1247 values to determine whether to mark the buffer as unmodified once again;
1248 it does so only if the file's modification time matches those numbers.
1250 @item (nil @var{property} @var{value} @var{beg} . @var{end})
1251 This kind of element records a change in a text property.
1252 Here's how you might undo the change:
1255 (put-text-property @var{beg} @var{end} @var{property} @var{value})
1258 @item (@var{marker} . @var{adjustment})
1259 This kind of element records the fact that the marker @var{marker} was
1260 relocated due to deletion of surrounding text, and that it moved
1261 @var{adjustment} character positions. Undoing this element moves
1262 @var{marker} @minus{} @var{adjustment} characters.
1264 @item (apply @var{funname} . @var{args})
1265 This is an extensible undo item, which is undone by calling
1266 @var{funname} with arguments @var{args}.
1268 @item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
1269 This is an extensible undo item, which records a change limited to the
1270 range @var{beg} to @var{end}, which increased the size of the buffer
1271 by @var{delta}. It is undone by calling @var{funname} with arguments
1274 This kind of element enables undo limited to a region to determine
1275 whether the element pertains to that region.
1278 This element is a boundary. The elements between two boundaries are
1279 called a @dfn{change group}; normally, each change group corresponds to
1280 one keyboard command, and undo commands normally undo an entire group as
1284 @defun undo-boundary
1285 This function places a boundary element in the undo list. The undo
1286 command stops at such a boundary, and successive undo commands undo
1287 to earlier and earlier boundaries. This function returns @code{nil}.
1289 The editor command loop automatically creates an undo boundary before
1290 each key sequence is executed. Thus, each undo normally undoes the
1291 effects of one command. Self-inserting input characters are an
1292 exception. The command loop makes a boundary for the first such
1293 character; the next 19 consecutive self-inserting input characters do
1294 not make boundaries, and then the 20th does, and so on as long as
1295 self-inserting characters continue.
1297 All buffer modifications add a boundary whenever the previous undoable
1298 change was made in some other buffer. This is to ensure that
1299 each command makes a boundary in each buffer where it makes changes.
1301 Calling this function explicitly is useful for splitting the effects of
1302 a command into more than one unit. For example, @code{query-replace}
1303 calls @code{undo-boundary} after each replacement, so that the user can
1304 undo individual replacements one by one.
1307 @defvar undo-in-progress
1308 This variable is normally @code{nil}, but the undo commands bind it to
1309 @code{t}. This is so that various kinds of change hooks can tell when
1310 they're being called for the sake of undoing.
1313 @defun primitive-undo count list
1314 This is the basic function for undoing elements of an undo list.
1315 It undoes the first @var{count} elements of @var{list}, returning
1316 the rest of @var{list}.
1318 @code{primitive-undo} adds elements to the buffer's undo list when it
1319 changes the buffer. Undo commands avoid confusion by saving the undo
1320 list value at the beginning of a sequence of undo operations. Then the
1321 undo operations use and update the saved value. The new elements added
1322 by undoing are not part of this saved value, so they don't interfere with
1325 This function does not bind @code{undo-in-progress}.
1328 @node Maintaining Undo
1329 @section Maintaining Undo Lists
1331 This section describes how to enable and disable undo information for
1332 a given buffer. It also explains how the undo list is truncated
1333 automatically so it doesn't get too big.
1335 Recording of undo information in a newly created buffer is normally
1336 enabled to start with; but if the buffer name starts with a space, the
1337 undo recording is initially disabled. You can explicitly enable or
1338 disable undo recording with the following two functions, or by setting
1339 @code{buffer-undo-list} yourself.
1341 @deffn Command buffer-enable-undo &optional buffer-or-name
1342 This command enables recording undo information for buffer
1343 @var{buffer-or-name}, so that subsequent changes can be undone. If no
1344 argument is supplied, then the current buffer is used. This function
1345 does nothing if undo recording is already enabled in the buffer. It
1348 In an interactive call, @var{buffer-or-name} is the current buffer.
1349 You cannot specify any other buffer.
1352 @deffn Command buffer-disable-undo &optional buffer-or-name
1353 @cindex disabling undo
1354 This function discards the undo list of @var{buffer-or-name}, and disables
1355 further recording of undo information. As a result, it is no longer
1356 possible to undo either previous changes or any subsequent changes. If
1357 the undo list of @var{buffer-or-name} is already disabled, this function
1360 This function returns @code{nil}.
1363 As editing continues, undo lists get longer and longer. To prevent
1364 them from using up all available memory space, garbage collection trims
1365 them back to size limits you can set. (For this purpose, the ``size''
1366 of an undo list measures the cons cells that make up the list, plus the
1367 strings of deleted text.) Three variables control the range of acceptable
1368 sizes: @code{undo-limit}, @code{undo-strong-limit} and
1369 @code{undo-outer-limit}. In these variables, size is counted as the
1370 number of bytes occupied, which includes both saved text and other
1374 This is the soft limit for the acceptable size of an undo list. The
1375 change group at which this size is exceeded is the last one kept.
1378 @defopt undo-strong-limit
1379 This is the upper limit for the acceptable size of an undo list. The
1380 change group at which this size is exceeded is discarded itself (along
1381 with all older change groups). There is one exception: the very latest
1382 change group is only discarded if it exceeds @code{undo-outer-limit}.
1385 @defopt undo-outer-limit
1386 If at garbage collection time the undo info for the current command
1387 exceeds this limit, Emacs discards the info and displays a warning.
1388 This is a last ditch limit to prevent memory overflow.
1391 @defopt undo-ask-before-discard
1392 If this variable is non-@code{nil}, when the undo info exceeds
1393 @code{undo-outer-limit}, Emacs asks in the echo area whether to
1394 discard the info. The default value is @code{nil}, which means to
1395 discard it automatically.
1397 This option is mainly intended for debugging. Garbage collection is
1398 inhibited while the question is asked, which means that Emacs might
1399 leak memory if the user waits too long before answering the question.
1403 @comment node-name, next, previous, up
1405 @cindex filling text
1407 @dfn{Filling} means adjusting the lengths of lines (by moving the line
1408 breaks) so that they are nearly (but no greater than) a specified
1409 maximum width. Additionally, lines can be @dfn{justified}, which means
1410 inserting spaces to make the left and/or right margins line up
1411 precisely. The width is controlled by the variable @code{fill-column}.
1412 For ease of reading, lines should be no longer than 70 or so columns.
1414 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1415 automatically as you insert it, but changes to existing text may leave
1416 it improperly filled. Then you must fill the text explicitly.
1418 Most of the commands in this section return values that are not
1419 meaningful. All the functions that do filling take note of the current
1420 left margin, current right margin, and current justification style
1421 (@pxref{Margins}). If the current justification style is
1422 @code{none}, the filling functions don't actually do anything.
1424 Several of the filling functions have an argument @var{justify}.
1425 If it is non-@code{nil}, that requests some kind of justification. It
1426 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
1427 request a specific style of justification. If it is @code{t}, that
1428 means to use the current justification style for this part of the text
1429 (see @code{current-justification}, below). Any other value is treated
1432 When you call the filling functions interactively, using a prefix
1433 argument implies the value @code{full} for @var{justify}.
1435 @deffn Command fill-paragraph justify
1436 This command fills the paragraph at or after point. If
1437 @var{justify} is non-@code{nil}, each line is justified as well.
1438 It uses the ordinary paragraph motion commands to find paragraph
1439 boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
1442 @deffn Command fill-region start end &optional justify nosqueeze to-eop
1443 This command fills each of the paragraphs in the region from @var{start}
1444 to @var{end}. It justifies as well if @var{justify} is
1447 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1448 other than line breaks untouched. If @var{to-eop} is non-@code{nil},
1449 that means to keep filling to the end of the paragraph---or the next hard
1450 newline, if @code{use-hard-newlines} is enabled (see below).
1452 The variable @code{paragraph-separate} controls how to distinguish
1453 paragraphs. @xref{Standard Regexps}.
1456 @deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
1457 This command fills each paragraph in the region according to its
1458 individual fill prefix. Thus, if the lines of a paragraph were indented
1459 with spaces, the filled paragraph will remain indented in the same
1462 The first two arguments, @var{start} and @var{end}, are the beginning
1463 and end of the region to be filled. The third and fourth arguments,
1464 @var{justify} and @var{citation-regexp}, are optional. If
1465 @var{justify} is non-@code{nil}, the paragraphs are justified as
1466 well as filled. If @var{citation-regexp} is non-@code{nil}, it means the
1467 function is operating on a mail message and therefore should not fill
1468 the header lines. If @var{citation-regexp} is a string, it is used as
1469 a regular expression; if it matches the beginning of a line, that line
1470 is treated as a citation marker.
1472 Ordinarily, @code{fill-individual-paragraphs} regards each change in
1473 indentation as starting a new paragraph. If
1474 @code{fill-individual-varying-indent} is non-@code{nil}, then only
1475 separator lines separate paragraphs. That mode can handle indented
1476 paragraphs with additional indentation on the first line.
1479 @defopt fill-individual-varying-indent
1480 This variable alters the action of @code{fill-individual-paragraphs} as
1484 @deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
1485 This command considers a region of text as a single paragraph and fills
1486 it. If the region was made up of many paragraphs, the blank lines
1487 between paragraphs are removed. This function justifies as well as
1488 filling when @var{justify} is non-@code{nil}.
1490 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1491 other than line breaks untouched. If @var{squeeze-after} is
1492 non-@code{nil}, it specifies a position in the region, and means don't
1493 canonicalize spaces before that position.
1495 In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
1496 choose a fill prefix by default. @xref{Adaptive Fill}.
1499 @deffn Command justify-current-line &optional how eop nosqueeze
1500 This command inserts spaces between the words of the current line so
1501 that the line ends exactly at @code{fill-column}. It returns
1504 The argument @var{how}, if non-@code{nil} specifies explicitly the style
1505 of justification. It can be @code{left}, @code{right}, @code{full},
1506 @code{center}, or @code{none}. If it is @code{t}, that means to do
1507 follow specified justification style (see @code{current-justification},
1508 below). @code{nil} means to do full justification.
1510 If @var{eop} is non-@code{nil}, that means do only left-justification
1511 if @code{current-justification} specifies full justification. This is
1512 used for the last line of a paragraph; even if the paragraph as a
1513 whole is fully justified, the last line should not be.
1515 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1519 @defopt default-justification
1520 This variable's value specifies the style of justification to use for
1521 text that doesn't specify a style with a text property. The possible
1522 values are @code{left}, @code{right}, @code{full}, @code{center}, or
1523 @code{none}. The default value is @code{left}.
1526 @defun current-justification
1527 This function returns the proper justification style to use for filling
1528 the text around point.
1530 This returns the value of the @code{justification} text property at
1531 point, or the variable @var{default-justification} if there is no such
1532 text property. However, it returns @code{nil} rather than @code{none}
1533 to mean ``don't justify''.
1536 @defopt sentence-end-double-space
1537 @anchor{Definition of sentence-end-double-space}
1538 If this variable is non-@code{nil}, a period followed by just one space
1539 does not count as the end of a sentence, and the filling functions
1540 avoid breaking the line at such a place.
1543 @defopt sentence-end-without-period
1544 If this variable is non-@code{nil}, a sentence can end without a
1545 period. This is used for languages like Thai, where sentences end
1546 with a double space but without a period.
1549 @defopt sentence-end-without-space
1550 If this variable is non-@code{nil}, it should be a string of
1551 characters that can end a sentence without following spaces.
1554 @defvar fill-paragraph-function
1555 This variable provides a way for major modes to override the filling of
1556 paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
1557 this function to do the work. If the function returns a non-@code{nil}
1558 value, @code{fill-paragraph} assumes the job is done, and immediately
1561 The usual use of this feature is to fill comments in programming
1562 language modes. If the function needs to fill a paragraph in the usual
1563 way, it can do so as follows:
1566 (let ((fill-paragraph-function nil))
1567 (fill-paragraph arg))
1571 @defvar use-hard-newlines
1572 If this variable is non-@code{nil}, the filling functions do not delete
1573 newlines that have the @code{hard} text property. These ``hard
1574 newlines'' act as paragraph separators.
1578 @section Margins for Filling
1581 This buffer-local variable, if non-@code{nil}, specifies a string of
1582 text that appears at the beginning of normal text lines and should be
1583 disregarded when filling them. Any line that fails to start with the
1584 fill prefix is considered the start of a paragraph; so is any line
1585 that starts with the fill prefix followed by additional whitespace.
1586 Lines that start with the fill prefix but no additional whitespace are
1587 ordinary text lines that can be filled together. The resulting filled
1588 lines also start with the fill prefix.
1590 The fill prefix follows the left margin whitespace, if any.
1594 This buffer-local variable specifies the maximum width of filled lines.
1595 Its value should be an integer, which is a number of columns. All the
1596 filling, justification, and centering commands are affected by this
1597 variable, including Auto Fill mode (@pxref{Auto Filling}).
1599 As a practical matter, if you are writing text for other people to
1600 read, you should set @code{fill-column} to no more than 70. Otherwise
1601 the line will be too long for people to read comfortably, and this can
1602 make the text seem clumsy.
1605 @defvar default-fill-column
1606 The value of this variable is the default value for @code{fill-column} in
1607 buffers that do not override it. This is the same as
1608 @code{(default-value 'fill-column)}.
1610 The default value for @code{default-fill-column} is 70.
1613 @deffn Command set-left-margin from to margin
1614 This sets the @code{left-margin} property on the text from @var{from} to
1615 @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
1616 command also refills the region to fit the new margin.
1619 @deffn Command set-right-margin from to margin
1620 This sets the @code{right-margin} property on the text from @var{from}
1621 to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
1622 this command also refills the region to fit the new margin.
1625 @defun current-left-margin
1626 This function returns the proper left margin value to use for filling
1627 the text around point. The value is the sum of the @code{left-margin}
1628 property of the character at the start of the current line (or zero if
1629 none), and the value of the variable @code{left-margin}.
1632 @defun current-fill-column
1633 This function returns the proper fill column value to use for filling
1634 the text around point. The value is the value of the @code{fill-column}
1635 variable, minus the value of the @code{right-margin} property of the
1636 character after point.
1639 @deffn Command move-to-left-margin &optional n force
1640 This function moves point to the left margin of the current line. The
1641 column moved to is determined by calling the function
1642 @code{current-left-margin}. If the argument @var{n} is non-@code{nil},
1643 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
1645 If @var{force} is non-@code{nil}, that says to fix the line's
1646 indentation if that doesn't match the left margin value.
1649 @defun delete-to-left-margin &optional from to
1650 This function removes left margin indentation from the text between
1651 @var{from} and @var{to}. The amount of indentation to delete is
1652 determined by calling @code{current-left-margin}. In no case does this
1653 function delete non-whitespace. If @var{from} and @var{to} are omitted,
1654 they default to the whole buffer.
1657 @defun indent-to-left-margin
1658 This is the default @code{indent-line-function}, used in Fundamental
1659 mode, Text mode, etc. Its effect is to adjust the indentation at the
1660 beginning of the current line to the value specified by the variable
1661 @code{left-margin}. This may involve either inserting or deleting
1666 This variable specifies the base left margin column. In Fundamental
1667 mode, @kbd{C-j} indents to this column. This variable automatically
1668 becomes buffer-local when set in any fashion.
1671 @defvar fill-nobreak-predicate
1672 This variable gives major modes a way to specify not to break a line
1673 at certain places. Its value should be a list of functions. Whenever
1674 filling considers breaking the line at a certain place in the buffer,
1675 it calls each of these functions with no arguments and with point
1676 located at that place. If any of the functions returns
1677 non-@code{nil}, then the line won't be broken there.
1681 @section Adaptive Fill Mode
1682 @c @cindex Adaptive Fill mode "adaptive-fill-mode" is adjacent.
1684 When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill
1685 prefix automatically from the text in each paragraph being filled
1686 rather than using a predetermined value. During filling, this fill
1687 prefix gets inserted at the start of the second and subsequent lines
1688 of the paragraph as described in @ref{Filling}, and in @ref{Auto
1691 @defopt adaptive-fill-mode
1692 Adaptive Fill mode is enabled when this variable is non-@code{nil}.
1693 It is @code{t} by default.
1696 @defun fill-context-prefix from to
1697 This function implements the heart of Adaptive Fill mode; it chooses a
1698 fill prefix based on the text between @var{from} and @var{to},
1699 typically the start and end of a paragraph. It does this by looking
1700 at the first two lines of the paragraph, based on the variables
1702 @c The optional argument first-line-regexp is not documented
1703 @c because it exists for internal purposes and might be eliminated
1706 Usually, this function returns the fill prefix, a string. However,
1707 before doing this, the function makes a final check (not specially
1708 mentioned in the following) that a line starting with this prefix
1709 wouldn't look like the start of a paragraph. Should this happen, the
1710 function signals the anomaly by returning @code{nil} instead.
1712 In detail, @code{fill-context-prefix} does this:
1716 It takes a candidate for the fill prefix from the first line---it
1717 tries first the function in @code{adaptive-fill-function} (if any),
1718 then the regular expression @code{adaptive-fill-regexp} (see below).
1719 The first non-@code{nil} result of these, or the empty string if
1720 they're both @code{nil}, becomes the first line's candidate.
1722 If the paragraph has as yet only one line, the function tests the
1723 validity of the prefix candidate just found. The function then
1724 returns the candidate if it's valid, or a string of spaces otherwise.
1725 (see the description of @code{adaptive-fill-first-line-regexp} below).
1727 When the paragraph already has two lines, the function next looks for
1728 a prefix candidate on the second line, in just the same way it did for
1729 the first line. If it doesn't find one, it returns @code{nil}.
1731 The function now compares the two candidate prefixes heuristically: if
1732 the non-whitespace characters in the line 2 candidate occur in the
1733 same order in the line 1 candidate, the function returns the line 2
1734 candidate. Otherwise, it returns the largest initial substring which
1735 is common to both candidates (which might be the empty string).
1739 @defopt adaptive-fill-regexp
1740 Adaptive Fill mode matches this regular expression against the text
1741 starting after the left margin whitespace (if any) on a line; the
1742 characters it matches are that line's candidate for the fill prefix.
1744 The default value matches whitespace with certain punctuation
1745 characters intermingled.
1748 @defopt adaptive-fill-first-line-regexp
1749 Used only in one-line paragraphs, this regular expression acts as an
1750 additional check of the validity of the one available candidate fill
1751 prefix: the candidate must match this regular expression, or match
1752 @code{comment-start-skip}. If it doesn't, @code{fill-context-prefix}
1753 replaces the candidate with a string of spaces ``of the same width''
1756 The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which
1757 matches only a string of whitespace. The effect of this default is to
1758 force the fill prefixes found in one-line paragraphs always to be pure
1762 @defopt adaptive-fill-function
1763 You can specify more complex ways of choosing a fill prefix
1764 automatically by setting this variable to a function. The function is
1765 called with point after the left margin (if any) of a line, and it
1766 must preserve point. It should return either ``that line's'' fill
1767 prefix or @code{nil}, meaning it has failed to determine a prefix.
1771 @comment node-name, next, previous, up
1772 @section Auto Filling
1773 @cindex filling, automatic
1774 @cindex Auto Fill mode
1776 Auto Fill mode is a minor mode that fills lines automatically as text
1777 is inserted. This section describes the hook used by Auto Fill mode.
1778 For a description of functions that you can call explicitly to fill and
1779 justify existing text, see @ref{Filling}.
1781 Auto Fill mode also enables the functions that change the margins and
1782 justification style to refill portions of the text. @xref{Margins}.
1784 @defvar auto-fill-function
1785 The value of this buffer-local variable should be a function (of no
1786 arguments) to be called after self-inserting a character from the table
1787 @code{auto-fill-chars}. It may be @code{nil}, in which case nothing
1788 special is done in that case.
1790 The value of @code{auto-fill-function} is @code{do-auto-fill} when
1791 Auto-Fill mode is enabled. That is a function whose sole purpose is to
1792 implement the usual strategy for breaking a line.
1795 In older Emacs versions, this variable was named @code{auto-fill-hook},
1796 but since it is not called with the standard convention for hooks, it
1797 was renamed to @code{auto-fill-function} in version 19.
1801 @defvar normal-auto-fill-function
1802 This variable specifies the function to use for
1803 @code{auto-fill-function}, if and when Auto Fill is turned on. Major
1804 modes can set buffer-local values for this variable to alter how Auto
1808 @defvar auto-fill-chars
1809 A char table of characters which invoke @code{auto-fill-function} when
1810 self-inserted---space and newline in most language environments. They
1811 have an entry @code{t} in the table.
1815 @section Sorting Text
1816 @cindex sorting text
1818 The sorting functions described in this section all rearrange text in
1819 a buffer. This is in contrast to the function @code{sort}, which
1820 rearranges the order of the elements of a list (@pxref{Rearrangement}).
1821 The values returned by these functions are not meaningful.
1823 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate
1824 This function is the general text-sorting routine that subdivides a
1825 buffer into records and then sorts them. Most of the commands in this
1826 section use this function.
1828 To understand how @code{sort-subr} works, consider the whole accessible
1829 portion of the buffer as being divided into disjoint pieces called
1830 @dfn{sort records}. The records may or may not be contiguous, but they
1831 must not overlap. A portion of each sort record (perhaps all of it) is
1832 designated as the sort key. Sorting rearranges the records in order by
1835 Usually, the records are rearranged in order of ascending sort key.
1836 If the first argument to the @code{sort-subr} function, @var{reverse},
1837 is non-@code{nil}, the sort records are rearranged in order of
1838 descending sort key.
1840 The next four arguments to @code{sort-subr} are functions that are
1841 called to move point across a sort record. They are called many times
1842 from within @code{sort-subr}.
1846 @var{nextrecfun} is called with point at the end of a record. This
1847 function moves point to the start of the next record. The first record
1848 is assumed to start at the position of point when @code{sort-subr} is
1849 called. Therefore, you should usually move point to the beginning of
1850 the buffer before calling @code{sort-subr}.
1852 This function can indicate there are no more sort records by leaving
1853 point at the end of the buffer.
1856 @var{endrecfun} is called with point within a record. It moves point to
1857 the end of the record.
1860 @var{startkeyfun} is called to move point from the start of a record to
1861 the start of the sort key. This argument is optional; if it is omitted,
1862 the whole record is the sort key. If supplied, the function should
1863 either return a non-@code{nil} value to be used as the sort key, or
1864 return @code{nil} to indicate that the sort key is in the buffer
1865 starting at point. In the latter case, @var{endkeyfun} is called to
1866 find the end of the sort key.
1869 @var{endkeyfun} is called to move point from the start of the sort key
1870 to the end of the sort key. This argument is optional. If
1871 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
1872 @code{nil}), then the sort key extends to the end of the record. There
1873 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1874 non-@code{nil} value.
1877 The argument @var{predicate} is the function to use to compare keys.
1878 If keys are numbers, it defaults to @code{<}; otherwise it defaults to
1881 As an example of @code{sort-subr}, here is the complete function
1882 definition for @code{sort-lines}:
1886 ;; @r{Note that the first two lines of doc string}
1887 ;; @r{are effectively one line when viewed by a user.}
1888 (defun sort-lines (reverse beg end)
1889 "Sort lines in region alphabetically;\
1890 argument means descending order.
1891 Called from a program, there are three arguments:
1894 REVERSE (non-nil means reverse order),\
1895 BEG and END (region to sort).
1896 The variable `sort-fold-case' determines\
1897 whether alphabetic case affects
1901 (interactive "P\nr")
1904 (narrow-to-region beg end)
1905 (goto-char (point-min))
1906 (let ((inhibit-field-text-motion t))
1907 (sort-subr reverse 'forward-line 'end-of-line)))))
1911 Here @code{forward-line} moves point to the start of the next record,
1912 and @code{end-of-line} moves point to the end of record. We do not pass
1913 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
1914 record is used as the sort key.
1916 The @code{sort-paragraphs} function is very much the same, except that
1917 its @code{sort-subr} call looks like this:
1924 (while (and (not (eobp))
1925 (looking-at paragraph-separate))
1931 Markers pointing into any sort records are left with no useful
1932 position after @code{sort-subr} returns.
1935 @defopt sort-fold-case
1936 If this variable is non-@code{nil}, @code{sort-subr} and the other
1937 buffer sorting functions ignore case when comparing strings.
1940 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
1941 This command sorts the region between @var{start} and @var{end}
1942 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
1943 If @var{reverse} is a negative integer, then sorting is in reverse
1946 Alphabetical sorting means that two sort keys are compared by
1947 comparing the first characters of each, the second characters of each,
1948 and so on. If a mismatch is found, it means that the sort keys are
1949 unequal; the sort key whose character is less at the point of first
1950 mismatch is the lesser sort key. The individual characters are compared
1951 according to their numerical character codes in the Emacs character set.
1953 The value of the @var{record-regexp} argument specifies how to divide
1954 the buffer into sort records. At the end of each record, a search is
1955 done for this regular expression, and the text that matches it is taken
1956 as the next record. For example, the regular expression @samp{^.+$},
1957 which matches lines with at least one character besides a newline, would
1958 make each such line into a sort record. @xref{Regular Expressions}, for
1959 a description of the syntax and meaning of regular expressions.
1961 The value of the @var{key-regexp} argument specifies what part of each
1962 record is the sort key. The @var{key-regexp} could match the whole
1963 record, or only a part. In the latter case, the rest of the record has
1964 no effect on the sorted order of records, but it is carried along when
1965 the record moves to its new position.
1967 The @var{key-regexp} argument can refer to the text matched by a
1968 subexpression of @var{record-regexp}, or it can be a regular expression
1971 If @var{key-regexp} is:
1974 @item @samp{\@var{digit}}
1975 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
1976 grouping in @var{record-regexp} is the sort key.
1979 then the whole record is the sort key.
1981 @item a regular expression
1982 then @code{sort-regexp-fields} searches for a match for the regular
1983 expression within the record. If such a match is found, it is the sort
1984 key. If there is no match for @var{key-regexp} within a record then
1985 that record is ignored, which means its position in the buffer is not
1986 changed. (The other records may move around it.)
1989 For example, if you plan to sort all the lines in the region by the
1990 first word on each line starting with the letter @samp{f}, you should
1991 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
1992 @samp{\<f\w*\>}. The resulting expression looks like this:
1996 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
2002 If you call @code{sort-regexp-fields} interactively, it prompts for
2003 @var{record-regexp} and @var{key-regexp} in the minibuffer.
2006 @deffn Command sort-lines reverse start end
2007 This command alphabetically sorts lines in the region between
2008 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2009 is in reverse order.
2012 @deffn Command sort-paragraphs reverse start end
2013 This command alphabetically sorts paragraphs in the region between
2014 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2015 is in reverse order.
2018 @deffn Command sort-pages reverse start end
2019 This command alphabetically sorts pages in the region between
2020 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2021 is in reverse order.
2024 @deffn Command sort-fields field start end
2025 This command sorts lines in the region between @var{start} and
2026 @var{end}, comparing them alphabetically by the @var{field}th field
2027 of each line. Fields are separated by whitespace and numbered starting
2028 from 1. If @var{field} is negative, sorting is by the
2029 @w{@minus{}@var{field}th} field from the end of the line. This command
2030 is useful for sorting tables.
2033 @deffn Command sort-numeric-fields field start end
2034 This command sorts lines in the region between @var{start} and
2035 @var{end}, comparing them numerically by the @var{field}th field of
2036 each line. Fields are separated by whitespace and numbered starting
2037 from 1. The specified field must contain a number in each line of the
2038 region. Numbers starting with 0 are treated as octal, and numbers
2039 starting with @samp{0x} are treated as hexadecimal.
2041 If @var{field} is negative, sorting is by the
2042 @w{@minus{}@var{field}th} field from the end of the line. This
2043 command is useful for sorting tables.
2046 @defopt sort-numeric-base
2047 This variable specifies the default radix for
2048 @code{sort-numeric-fields} to parse numbers.
2051 @deffn Command sort-columns reverse &optional beg end
2052 This command sorts the lines in the region between @var{beg} and
2053 @var{end}, comparing them alphabetically by a certain range of
2054 columns. The column positions of @var{beg} and @var{end} bound the
2055 range of columns to sort on.
2057 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
2059 One unusual thing about this command is that the entire line
2060 containing position @var{beg}, and the entire line containing position
2061 @var{end}, are included in the region sorted.
2063 Note that @code{sort-columns} rejects text that contains tabs, because
2064 tabs could be split across the specified columns. Use @kbd{M-x
2065 untabify} to convert tabs to spaces before sorting.
2067 When possible, this command actually works by calling the @code{sort}
2072 @comment node-name, next, previous, up
2073 @section Counting Columns
2075 @cindex counting columns
2076 @cindex horizontal position
2078 The column functions convert between a character position (counting
2079 characters from the beginning of the buffer) and a column position
2080 (counting screen characters from the beginning of a line).
2082 These functions count each character according to the number of
2083 columns it occupies on the screen. This means control characters count
2084 as occupying 2 or 4 columns, depending upon the value of
2085 @code{ctl-arrow}, and tabs count as occupying a number of columns that
2086 depends on the value of @code{tab-width} and on the column where the tab
2087 begins. @xref{Usual Display}.
2089 Column number computations ignore the width of the window and the
2090 amount of horizontal scrolling. Consequently, a column value can be
2091 arbitrarily high. The first (or leftmost) column is numbered 0. They
2092 also ignore overlays and text properties, aside from invisibility.
2094 @defun current-column
2095 This function returns the horizontal position of point, measured in
2096 columns, counting from 0 at the left margin. The column position is the
2097 sum of the widths of all the displayed representations of the characters
2098 between the start of the current line and point.
2100 For an example of using @code{current-column}, see the description of
2101 @code{count-lines} in @ref{Text Lines}.
2104 @defun move-to-column column &optional force
2105 This function moves point to @var{column} in the current line. The
2106 calculation of @var{column} takes into account the widths of the
2107 displayed representations of the characters between the start of the
2110 If column @var{column} is beyond the end of the line, point moves to the
2111 end of the line. If @var{column} is negative, point moves to the
2112 beginning of the line.
2114 If it is impossible to move to column @var{column} because that is in
2115 the middle of a multicolumn character such as a tab, point moves to the
2116 end of that character. However, if @var{force} is non-@code{nil}, and
2117 @var{column} is in the middle of a tab, then @code{move-to-column}
2118 converts the tab into spaces so that it can move precisely to column
2119 @var{column}. Other multicolumn characters can cause anomalies despite
2120 @var{force}, since there is no way to split them.
2122 The argument @var{force} also has an effect if the line isn't long
2123 enough to reach column @var{column}; if it is @code{t}, that means to
2124 add whitespace at the end of the line to reach that column.
2126 If @var{column} is not an integer, an error is signaled.
2128 The return value is the column number actually moved to.
2132 @section Indentation
2135 The indentation functions are used to examine, move to, and change
2136 whitespace that is at the beginning of a line. Some of the functions
2137 can also change whitespace elsewhere on a line. Columns and indentation
2138 count from zero at the left margin.
2141 * Primitive Indent:: Functions used to count and insert indentation.
2142 * Mode-Specific Indent:: Customize indentation for different modes.
2143 * Region Indent:: Indent all the lines in a region.
2144 * Relative Indent:: Indent the current line based on previous lines.
2145 * Indent Tabs:: Adjustable, typewriter-like tab stops.
2146 * Motion by Indent:: Move to first non-blank character.
2149 @node Primitive Indent
2150 @subsection Indentation Primitives
2152 This section describes the primitive functions used to count and
2153 insert indentation. The functions in the following sections use these
2154 primitives. @xref{Width}, for related functions.
2156 @defun current-indentation
2157 @comment !!Type Primitive Function
2158 @comment !!SourceFile indent.c
2159 This function returns the indentation of the current line, which is
2160 the horizontal position of the first nonblank character. If the
2161 contents are entirely blank, then this is the horizontal position of the
2165 @deffn Command indent-to column &optional minimum
2166 @comment !!Type Primitive Function
2167 @comment !!SourceFile indent.c
2168 This function indents from point with tabs and spaces until @var{column}
2169 is reached. If @var{minimum} is specified and non-@code{nil}, then at
2170 least that many spaces are inserted even if this requires going beyond
2171 @var{column}. Otherwise the function does nothing if point is already
2172 beyond @var{column}. The value is the column at which the inserted
2175 The inserted whitespace characters inherit text properties from the
2176 surrounding text (usually, from the preceding text only). @xref{Sticky
2180 @defopt indent-tabs-mode
2181 @comment !!SourceFile indent.c
2182 If this variable is non-@code{nil}, indentation functions can insert
2183 tabs as well as spaces. Otherwise, they insert only spaces. Setting
2184 this variable automatically makes it buffer-local in the current buffer.
2187 @node Mode-Specific Indent
2188 @subsection Indentation Controlled by Major Mode
2190 An important function of each major mode is to customize the @key{TAB}
2191 key to indent properly for the language being edited. This section
2192 describes the mechanism of the @key{TAB} key and how to control it.
2193 The functions in this section return unpredictable values.
2195 @defvar indent-line-function
2196 This variable's value is the function to be used by @key{TAB} (and
2197 various commands) to indent the current line. The command
2198 @code{indent-according-to-mode} does no more than call this function.
2200 In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C
2201 mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
2202 In Fundamental mode, Text mode, and many other modes with no standard
2203 for indentation, the value is @code{indent-to-left-margin} (which is the
2207 @deffn Command indent-according-to-mode
2208 This command calls the function in @code{indent-line-function} to
2209 indent the current line in a way appropriate for the current major mode.
2212 @deffn Command indent-for-tab-command
2213 This command calls the function in @code{indent-line-function} to indent
2214 the current line; however, if that function is
2215 @code{indent-to-left-margin}, @code{insert-tab} is called instead. (That
2216 is a trivial command that inserts a tab character.)
2219 @deffn Command newline-and-indent
2220 @comment !!SourceFile simple.el
2221 This function inserts a newline, then indents the new line (the one
2222 following the newline just inserted) according to the major mode.
2224 It does indentation by calling the current @code{indent-line-function}.
2225 In programming language modes, this is the same thing @key{TAB} does,
2226 but in some text modes, where @key{TAB} inserts a tab,
2227 @code{newline-and-indent} indents to the column specified by
2231 @deffn Command reindent-then-newline-and-indent
2232 @comment !!SourceFile simple.el
2233 This command reindents the current line, inserts a newline at point,
2234 and then indents the new line (the one following the newline just
2237 This command does indentation on both lines according to the current
2238 major mode, by calling the current value of @code{indent-line-function}.
2239 In programming language modes, this is the same thing @key{TAB} does,
2240 but in some text modes, where @key{TAB} inserts a tab,
2241 @code{reindent-then-newline-and-indent} indents to the column specified
2242 by @code{left-margin}.
2246 @subsection Indenting an Entire Region
2248 This section describes commands that indent all the lines in the
2249 region. They return unpredictable values.
2251 @deffn Command indent-region start end to-column
2252 This command indents each nonblank line starting between @var{start}
2253 (inclusive) and @var{end} (exclusive). If @var{to-column} is
2254 @code{nil}, @code{indent-region} indents each nonblank line by calling
2255 the current mode's indentation function, the value of
2256 @code{indent-line-function}.
2258 If @var{to-column} is non-@code{nil}, it should be an integer
2259 specifying the number of columns of indentation; then this function
2260 gives each line exactly that much indentation, by either adding or
2261 deleting whitespace.
2263 If there is a fill prefix, @code{indent-region} indents each line
2264 by making it start with the fill prefix.
2267 @defvar indent-region-function
2268 The value of this variable is a function that can be used by
2269 @code{indent-region} as a short cut. It should take two arguments, the
2270 start and end of the region. You should design the function so
2271 that it will produce the same results as indenting the lines of the
2272 region one by one, but presumably faster.
2274 If the value is @code{nil}, there is no short cut, and
2275 @code{indent-region} actually works line by line.
2277 A short-cut function is useful in modes such as C mode and Lisp mode,
2278 where the @code{indent-line-function} must scan from the beginning of
2279 the function definition: applying it to each line would be quadratic in
2280 time. The short cut can update the scan information as it moves through
2281 the lines indenting them; this takes linear time. In a mode where
2282 indenting a line individually is fast, there is no need for a short cut.
2284 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
2285 a different meaning and does not use this variable.
2288 @deffn Command indent-rigidly start end count
2289 @comment !!SourceFile indent.el
2290 This command indents all lines starting between @var{start}
2291 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
2292 This ``preserves the shape'' of the affected region, moving it as a
2293 rigid unit. Consequently, this command is useful not only for indenting
2294 regions of unindented text, but also for indenting regions of formatted
2297 For example, if @var{count} is 3, this command adds 3 columns of
2298 indentation to each of the lines beginning in the region specified.
2300 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
2301 @code{indent-rigidly} to indent the text copied from the message being
2305 @defun indent-code-rigidly start end columns &optional nochange-regexp
2306 This is like @code{indent-rigidly}, except that it doesn't alter lines
2307 that start within strings or comments.
2309 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
2310 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
2313 @node Relative Indent
2314 @subsection Indentation Relative to Previous Lines
2316 This section describes two commands that indent the current line
2317 based on the contents of previous lines.
2319 @deffn Command indent-relative &optional unindented-ok
2320 This command inserts whitespace at point, extending to the same
2321 column as the next @dfn{indent point} of the previous nonblank line. An
2322 indent point is a non-whitespace character following whitespace. The
2323 next indent point is the first one at a column greater than the current
2324 column of point. For example, if point is underneath and to the left of
2325 the first non-blank character of a line of text, it moves to that column
2326 by inserting whitespace.
2328 If the previous nonblank line has no next indent point (i.e., none at a
2329 great enough column position), @code{indent-relative} either does
2330 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
2331 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right
2332 of the last column of a short line of text, this command ordinarily
2333 moves point to the next tab stop by inserting whitespace.
2335 The return value of @code{indent-relative} is unpredictable.
2337 In the following example, point is at the beginning of the second
2342 This line is indented twelve spaces.
2343 @point{}The quick brown fox jumped.
2348 Evaluation of the expression @code{(indent-relative nil)} produces the
2353 This line is indented twelve spaces.
2354 @point{}The quick brown fox jumped.
2358 In this next example, point is between the @samp{m} and @samp{p} of
2363 This line is indented twelve spaces.
2364 The quick brown fox jum@point{}ped.
2369 Evaluation of the expression @code{(indent-relative nil)} produces the
2374 This line is indented twelve spaces.
2375 The quick brown fox jum @point{}ped.
2380 @deffn Command indent-relative-maybe
2381 @comment !!SourceFile indent.el
2382 This command indents the current line like the previous nonblank line,
2383 by calling @code{indent-relative} with @code{t} as the
2384 @var{unindented-ok} argument. The return value is unpredictable.
2386 If the previous nonblank line has no indent points beyond the current
2387 column, this command does nothing.
2391 @comment node-name, next, previous, up
2392 @subsection Adjustable ``Tab Stops''
2393 @cindex tabs stops for indentation
2395 This section explains the mechanism for user-specified ``tab stops''
2396 and the mechanisms that use and set them. The name ``tab stops'' is
2397 used because the feature is similar to that of the tab stops on a
2398 typewriter. The feature works by inserting an appropriate number of
2399 spaces and tab characters to reach the next tab stop column; it does not
2400 affect the display of tab characters in the buffer (@pxref{Usual
2401 Display}). Note that the @key{TAB} character as input uses this tab
2402 stop feature only in a few major modes, such as Text mode.
2403 @xref{Tab Stops,,, emacs, The GNU Emacs Manual}.
2405 @deffn Command tab-to-tab-stop
2406 This command inserts spaces or tabs before point, up to the next tab
2407 stop column defined by @code{tab-stop-list}. It searches the list for
2408 an element greater than the current column number, and uses that element
2409 as the column to indent to. It does nothing if no such element is
2413 @defopt tab-stop-list
2414 This variable is the list of tab stop columns used by
2415 @code{tab-to-tab-stops}. The elements should be integers in increasing
2416 order. The tab stop columns need not be evenly spaced.
2418 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
2422 @node Motion by Indent
2423 @subsection Indentation-Based Motion Commands
2425 These commands, primarily for interactive use, act based on the
2426 indentation in the text.
2428 @deffn Command back-to-indentation
2429 @comment !!SourceFile simple.el
2430 This command moves point to the first non-whitespace character in the
2431 current line (which is the line in which point is located). It returns
2435 @deffn Command backward-to-indentation &optional arg
2436 @comment !!SourceFile simple.el
2437 This command moves point backward @var{arg} lines and then to the
2438 first nonblank character on that line. It returns @code{nil}.
2439 If @var{arg} is omitted or @code{nil}, it defaults to 1.
2442 @deffn Command forward-to-indentation &optional arg
2443 @comment !!SourceFile simple.el
2444 This command moves point forward @var{arg} lines and then to the first
2445 nonblank character on that line. It returns @code{nil}.
2446 If @var{arg} is omitted or @code{nil}, it defaults to 1.
2450 @comment node-name, next, previous, up
2451 @section Case Changes
2452 @cindex case conversion in buffers
2454 The case change commands described here work on text in the current
2455 buffer. @xref{Case Conversion}, for case conversion functions that work
2456 on strings and characters. @xref{Case Tables}, for how to customize
2457 which characters are upper or lower case and how to convert them.
2459 @deffn Command capitalize-region start end
2460 This function capitalizes all words in the region defined by
2461 @var{start} and @var{end}. To capitalize means to convert each word's
2462 first character to upper case and convert the rest of each word to lower
2463 case. The function returns @code{nil}.
2465 If one end of the region is in the middle of a word, the part of the
2466 word within the region is treated as an entire word.
2468 When @code{capitalize-region} is called interactively, @var{start} and
2469 @var{end} are point and the mark, with the smallest first.
2473 ---------- Buffer: foo ----------
2474 This is the contents of the 5th foo.
2475 ---------- Buffer: foo ----------
2479 (capitalize-region 1 44)
2482 ---------- Buffer: foo ----------
2483 This Is The Contents Of The 5th Foo.
2484 ---------- Buffer: foo ----------
2489 @deffn Command downcase-region start end
2490 This function converts all of the letters in the region defined by
2491 @var{start} and @var{end} to lower case. The function returns
2494 When @code{downcase-region} is called interactively, @var{start} and
2495 @var{end} are point and the mark, with the smallest first.
2498 @deffn Command upcase-region start end
2499 This function converts all of the letters in the region defined by
2500 @var{start} and @var{end} to upper case. The function returns
2503 When @code{upcase-region} is called interactively, @var{start} and
2504 @var{end} are point and the mark, with the smallest first.
2507 @deffn Command capitalize-word count
2508 This function capitalizes @var{count} words after point, moving point
2509 over as it does. To capitalize means to convert each word's first
2510 character to upper case and convert the rest of each word to lower case.
2511 If @var{count} is negative, the function capitalizes the
2512 @minus{}@var{count} previous words but does not move point. The value
2515 If point is in the middle of a word, the part of the word before point
2516 is ignored when moving forward. The rest is treated as an entire word.
2518 When @code{capitalize-word} is called interactively, @var{count} is
2519 set to the numeric prefix argument.
2522 @deffn Command downcase-word count
2523 This function converts the @var{count} words after point to all lower
2524 case, moving point over as it does. If @var{count} is negative, it
2525 converts the @minus{}@var{count} previous words but does not move point.
2526 The value is @code{nil}.
2528 When @code{downcase-word} is called interactively, @var{count} is set
2529 to the numeric prefix argument.
2532 @deffn Command upcase-word count
2533 This function converts the @var{count} words after point to all upper
2534 case, moving point over as it does. If @var{count} is negative, it
2535 converts the @minus{}@var{count} previous words but does not move point.
2536 The value is @code{nil}.
2538 When @code{upcase-word} is called interactively, @var{count} is set to
2539 the numeric prefix argument.
2542 @node Text Properties
2543 @section Text Properties
2544 @cindex text properties
2545 @cindex attributes of text
2546 @cindex properties of text
2548 Each character position in a buffer or a string can have a @dfn{text
2549 property list}, much like the property list of a symbol (@pxref{Property
2550 Lists}). The properties belong to a particular character at a
2551 particular place, such as, the letter @samp{T} at the beginning of this
2552 sentence or the first @samp{o} in @samp{foo}---if the same character
2553 occurs in two different places, the two occurrences in general have
2554 different properties.
2556 Each property has a name and a value. Both of these can be any Lisp
2557 object, but the name is normally a symbol. Typically each property
2558 name symbol is used for a particular purpose; for instance, the text
2559 property @code{face} specifies the faces for displaying the character
2560 (@pxref{Special Properties}). The usual way to access the property
2561 list is to specify a name and ask what value corresponds to it.
2563 If a character has a @code{category} property, we call it the
2564 @dfn{property category} of the character. It should be a symbol. The
2565 properties of the symbol serve as defaults for the properties of the
2568 Copying text between strings and buffers preserves the properties
2569 along with the characters; this includes such diverse functions as
2570 @code{substring}, @code{insert}, and @code{buffer-substring}.
2573 * Examining Properties:: Looking at the properties of one character.
2574 * Changing Properties:: Setting the properties of a range of text.
2575 * Property Search:: Searching for where a property changes value.
2576 * Special Properties:: Particular properties with special meanings.
2577 * Format Properties:: Properties for representing formatting of text.
2578 * Sticky Properties:: How inserted text gets properties from
2580 * Saving Properties:: Saving text properties in files, and reading
2582 * Lazy Properties:: Computing text properties in a lazy fashion
2583 only when text is examined.
2584 * Clickable Text:: Using text properties to make regions of text
2585 do something when you click on them.
2586 * Links and Mouse-1:: How to make @key{Mouse-1} follow a link.
2587 * Fields:: The @code{field} property defines
2588 fields within the buffer.
2589 * Not Intervals:: Why text properties do not use
2590 Lisp-visible text intervals.
2593 @node Examining Properties
2594 @subsection Examining Text Properties
2596 The simplest way to examine text properties is to ask for the value of
2597 a particular property of a particular character. For that, use
2598 @code{get-text-property}. Use @code{text-properties-at} to get the
2599 entire property list of a character. @xref{Property Search}, for
2600 functions to examine the properties of a number of characters at once.
2602 These functions handle both strings and buffers. Keep in mind that
2603 positions in a string start from 0, whereas positions in a buffer start
2606 @defun get-text-property pos prop &optional object
2607 This function returns the value of the @var{prop} property of the
2608 character after position @var{pos} in @var{object} (a buffer or
2609 string). The argument @var{object} is optional and defaults to the
2612 If there is no @var{prop} property strictly speaking, but the character
2613 has a property category that is a symbol, then @code{get-text-property} returns
2614 the @var{prop} property of that symbol.
2617 @defun get-char-property position prop &optional object
2618 This function is like @code{get-text-property}, except that it checks
2619 overlays first and then text properties. @xref{Overlays}.
2621 The argument @var{object} may be a string, a buffer, or a window. If it
2622 is a window, then the buffer displayed in that window is used for text
2623 properties and overlays, but only the overlays active for that window
2624 are considered. If @var{object} is a buffer, then all overlays in that
2625 buffer are considered, as well as text properties. If @var{object} is a
2626 string, only text properties are considered, since strings never have
2630 @defun get-char-property-and-overlay position prop &optional object
2631 This is like @code{get-char-property}, but gives extra information
2632 about the overlay that the property value comes from.
2634 Its value is a cons cell whose @sc{car} is the property value, the
2635 same value @code{get-char-property} would return with the same
2636 arguments. Its @sc{cdr} is the overlay in which the property was
2637 found, or @code{nil}, if it was found as a text property or not found
2640 If @var{position} is at the end of @var{object}, both the @sc{car} and
2641 the @sc{cdr} of the value are @code{nil}.
2644 @defvar char-property-alias-alist
2645 This variable holds an alist which maps property names to a list of
2646 alternative property names. If a character does not specify a direct
2647 value for a property, the alternative property names are consulted in
2648 order; the first non-@code{nil} value is used. This variable takes
2649 precedence over @code{default-text-properties}, and @code{category}
2650 properties take precedence over this variable.
2653 @defun text-properties-at position &optional object
2654 This function returns the entire property list of the character at
2655 @var{position} in the string or buffer @var{object}. If @var{object} is
2656 @code{nil}, it defaults to the current buffer.
2659 @defvar default-text-properties
2660 This variable holds a property list giving default values for text
2661 properties. Whenever a character does not specify a value for a
2662 property, neither directly, through a category symbol, or through
2663 @code{char-property-alias-alist}, the value stored in this list is
2664 used instead. Here is an example:
2667 (setq default-text-properties '(foo 69)
2668 char-property-alias-alist nil)
2669 ;; @r{Make sure character 1 has no properties of its own.}
2670 (set-text-properties 1 2 nil)
2671 ;; @r{What we get, when we ask, is the default value.}
2672 (get-text-property 1 'foo)
2677 @node Changing Properties
2678 @subsection Changing Text Properties
2680 The primitives for changing properties apply to a specified range of
2681 text in a buffer or string. The function @code{set-text-properties}
2682 (see end of section) sets the entire property list of the text in that
2683 range; more often, it is useful to add, change, or delete just certain
2684 properties specified by name.
2686 Since text properties are considered part of the contents of the
2687 buffer (or string), and can affect how a buffer looks on the screen,
2688 any change in buffer text properties marks the buffer as modified.
2689 Buffer text property changes are undoable also (@pxref{Undo}).
2690 Positions in a string start from 0, whereas positions in a buffer
2693 @defun put-text-property start end prop value &optional object
2694 This function sets the @var{prop} property to @var{value} for the text
2695 between @var{start} and @var{end} in the string or buffer @var{object}.
2696 If @var{object} is @code{nil}, it defaults to the current buffer.
2699 @defun add-text-properties start end props &optional object
2700 This function adds or overrides text properties for the text between
2701 @var{start} and @var{end} in the string or buffer @var{object}. If
2702 @var{object} is @code{nil}, it defaults to the current buffer.
2704 The argument @var{props} specifies which properties to add. It should
2705 have the form of a property list (@pxref{Property Lists}): a list whose
2706 elements include the property names followed alternately by the
2707 corresponding values.
2709 The return value is @code{t} if the function actually changed some
2710 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2711 its values agree with those in the text).
2713 For example, here is how to set the @code{comment} and @code{face}
2714 properties of a range of text:
2717 (add-text-properties @var{start} @var{end}
2718 '(comment t face highlight))
2722 @defun remove-text-properties start end props &optional object
2723 This function deletes specified text properties from the text between
2724 @var{start} and @var{end} in the string or buffer @var{object}. If
2725 @var{object} is @code{nil}, it defaults to the current buffer.
2727 The argument @var{props} specifies which properties to delete. It
2728 should have the form of a property list (@pxref{Property Lists}): a list
2729 whose elements are property names alternating with corresponding values.
2730 But only the names matter---the values that accompany them are ignored.
2731 For example, here's how to remove the @code{face} property.
2734 (remove-text-properties @var{start} @var{end} '(face nil))
2737 The return value is @code{t} if the function actually changed some
2738 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2739 if no character in the specified text had any of those properties).
2741 To remove all text properties from certain text, use
2742 @code{set-text-properties} and specify @code{nil} for the new property
2746 @defun remove-list-of-text-properties start end list-of-properties &optional object
2747 Like @code{remove-text-properties} except that
2748 @var{list-of-properties} is a list of property names only, not an
2749 alternating list of property names and values.
2752 @defun set-text-properties start end props &optional object
2753 This function completely replaces the text property list for the text
2754 between @var{start} and @var{end} in the string or buffer @var{object}.
2755 If @var{object} is @code{nil}, it defaults to the current buffer.
2757 The argument @var{props} is the new property list. It should be a list
2758 whose elements are property names alternating with corresponding values.
2760 After @code{set-text-properties} returns, all the characters in the
2761 specified range have identical properties.
2763 If @var{props} is @code{nil}, the effect is to get rid of all properties
2764 from the specified range of text. Here's an example:
2767 (set-text-properties @var{start} @var{end} nil)
2770 Do not rely on the return value of this function.
2773 The easiest way to make a string with text properties
2774 is with @code{propertize}:
2776 @defun propertize string &rest properties
2777 This function returns a copy of @var{string} which has the text
2778 properties @var{properties}. These properties apply to all the
2779 characters in the string that is returned. Here is an example that
2780 constructs a string with a @code{face} property and a @code{mouse-face}
2784 (propertize "foo" 'face 'italic
2785 'mouse-face 'bold-italic)
2786 @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
2789 To put different properties on various parts of a string, you can
2790 construct each part with @code{propertize} and then combine them with
2795 (propertize "foo" 'face 'italic
2796 'mouse-face 'bold-italic)
2798 (propertize "bar" 'face 'italic
2799 'mouse-face 'bold-italic))
2800 @result{} #("foo and bar"
2801 0 3 (face italic mouse-face bold-italic)
2803 8 11 (face italic mouse-face bold-italic))
2807 See also the function @code{buffer-substring-no-properties}
2808 (@pxref{Buffer Contents}) which copies text from the buffer
2809 but does not copy its properties.
2811 @node Property Search
2812 @subsection Text Property Search Functions
2814 In typical use of text properties, most of the time several or many
2815 consecutive characters have the same value for a property. Rather than
2816 writing your programs to examine characters one by one, it is much
2817 faster to process chunks of text that have the same property value.
2819 Here are functions you can use to do this. They use @code{eq} for
2820 comparing property values. In all cases, @var{object} defaults to the
2823 For high performance, it's very important to use the @var{limit}
2824 argument to these functions, especially the ones that search for a
2825 single property---otherwise, they may spend a long time scanning to the
2826 end of the buffer, if the property you are interested in does not change.
2828 These functions do not move point; instead, they return a position (or
2829 @code{nil}). Remember that a position is always between two characters;
2830 the position returned by these functions is between two characters with
2831 different properties.
2833 @defun next-property-change pos &optional object limit
2834 The function scans the text forward from position @var{pos} in the
2835 string or buffer @var{object} till it finds a change in some text
2836 property, then returns the position of the change. In other words, it
2837 returns the position of the first character beyond @var{pos} whose
2838 properties are not identical to those of the character just after
2841 If @var{limit} is non-@code{nil}, then the scan ends at position
2842 @var{limit}. If there is no property change before that point,
2843 @code{next-property-change} returns @var{limit}.
2845 The value is @code{nil} if the properties remain unchanged all the way
2846 to the end of @var{object} and @var{limit} is @code{nil}. If the value
2847 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
2848 The value equals @var{pos} only when @var{limit} equals @var{pos}.
2850 Here is an example of how to scan the buffer by chunks of text within
2851 which all properties are constant:
2855 (let ((plist (text-properties-at (point)))
2857 (or (next-property-change (point) (current-buffer))
2859 @r{Process text from point to @var{next-change}@dots{}}
2860 (goto-char next-change)))
2864 @defun previous-property-change pos &optional object limit
2865 This is like @code{next-property-change}, but scans back from @var{pos}
2866 instead of forward. If the value is non-@code{nil}, it is a position
2867 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
2871 @defun next-single-property-change pos prop &optional object limit
2872 The function scans text for a change in the @var{prop} property, then
2873 returns the position of the change. The scan goes forward from
2874 position @var{pos} in the string or buffer @var{object}. In other
2875 words, this function returns the position of the first character
2876 beyond @var{pos} whose @var{prop} property differs from that of the
2877 character just after @var{pos}.
2879 If @var{limit} is non-@code{nil}, then the scan ends at position
2880 @var{limit}. If there is no property change before that point,
2881 @code{next-single-property-change} returns @var{limit}.
2883 The value is @code{nil} if the property remains unchanged all the way to
2884 the end of @var{object} and @var{limit} is @code{nil}. If the value is
2885 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
2886 equals @var{pos} only if @var{limit} equals @var{pos}.
2889 @defun previous-single-property-change pos prop &optional object limit
2890 This is like @code{next-single-property-change}, but scans back from
2891 @var{pos} instead of forward. If the value is non-@code{nil}, it is a
2892 position less than or equal to @var{pos}; it equals @var{pos} only if
2893 @var{limit} equals @var{pos}.
2896 @defun next-char-property-change pos &optional limit
2897 This is like @code{next-property-change} except that it considers
2898 overlay properties as well as text properties, and if no change is
2899 found before the end of the buffer, it returns the maximum buffer
2900 position rather than @code{nil} (in this sense, it resembles the
2901 corresponding overlay function @code{next-overlay-change}, rather than
2902 @code{next-property-change}). There is no @var{object} operand
2903 because this function operates only on the current buffer. It returns
2904 the next address at which either kind of property changes.
2907 @defun previous-char-property-change pos &optional limit
2908 This is like @code{next-char-property-change}, but scans back from
2909 @var{pos} instead of forward, and returns the minimum buffer
2910 position if no change is found.
2913 @defun next-single-char-property-change pos prop &optional object limit
2914 This is like @code{next-single-property-change} except that it
2915 considers overlay properties as well as text properties, and if no
2916 change is found before the end of the @var{object}, it returns the
2917 maximum valid position in @var{object} rather than @code{nil}. Unlike
2918 @code{next-char-property-change}, this function @emph{does} have an
2919 @var{object} operand; if @var{object} is not a buffer, only
2920 text-properties are considered.
2923 @defun previous-single-char-property-change pos prop &optional object limit
2924 This is like @code{next-single-char-property-change}, but scans back
2925 from @var{pos} instead of forward, and returns the minimum valid
2926 position in @var{object} if no change is found.
2929 @defun text-property-any start end prop value &optional object
2930 This function returns non-@code{nil} if at least one character between
2931 @var{start} and @var{end} has a property @var{prop} whose value is
2932 @var{value}. More precisely, it returns the position of the first such
2933 character. Otherwise, it returns @code{nil}.
2935 The optional fifth argument, @var{object}, specifies the string or
2936 buffer to scan. Positions are relative to @var{object}. The default
2937 for @var{object} is the current buffer.
2940 @defun text-property-not-all start end prop value &optional object
2941 This function returns non-@code{nil} if at least one character between
2942 @var{start} and @var{end} does not have a property @var{prop} with value
2943 @var{value}. More precisely, it returns the position of the first such
2944 character. Otherwise, it returns @code{nil}.
2946 The optional fifth argument, @var{object}, specifies the string or
2947 buffer to scan. Positions are relative to @var{object}. The default
2948 for @var{object} is the current buffer.
2951 @node Special Properties
2952 @subsection Properties with Special Meanings
2954 Here is a table of text property names that have special built-in
2955 meanings. The following sections list a few additional special property
2956 names that control filling and property inheritance. All other names
2957 have no standard meaning, and you can use them as you like.
2960 @cindex property category of text character
2961 @kindex category @r{(text property)}
2963 If a character has a @code{category} property, we call it the
2964 @dfn{property category} of the character. It should be a symbol. The
2965 properties of this symbol serve as defaults for the properties of the
2969 @cindex face codes of text
2970 @kindex face @r{(text property)}
2971 You can use the property @code{face} to control the font and color of
2972 text. @xref{Faces}, for more information.
2974 In the simplest case, the value is a face name. It can also be a list;
2975 then each element can be any of these possibilities;
2979 A face name (a symbol or string).
2982 A property list of face attributes. This has the
2983 form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
2984 face attribute name and @var{value} is a meaningful value for that
2985 attribute. With this feature, you do not need to create a face each
2986 time you want to specify a particular attribute for certain text.
2987 @xref{Face Attributes}.
2990 A cons cell of the form @code{(foreground-color . @var{color-name})} or
2991 @code{(background-color . @var{color-name})}. These elements specify
2992 just the foreground color or just the background color. @xref{Color
2993 Names}, for the supported forms of @var{color-name}.
2995 @code{(foreground-color . @var{color-name})} is equivalent to
2996 specifying @code{(:foreground @var{color-name})}, and likewise for the
3000 You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically
3001 update @code{face} properties based on the contents of the text.
3003 @item font-lock-face
3004 @kindex font-lock-face @r{(text property)}
3005 The @code{font-lock-face} property is the same in all respects as the
3006 @code{face} property, but its state of activation is controlled by
3007 @code{font-lock-mode}. This can be advantageous for special buffers
3008 which are not intended to be user-editable, or for static areas of
3009 text which are always fontified in the same way.
3010 @xref{Precalculated Fontification}.
3012 Strictly speaking, @code{font-lock-face} is not a built-in text
3013 property; rather, it is implemented in Font Lock mode using
3014 @code{char-property-alias-alist}. @xref{Examining Properties}.
3016 This property is new in Emacs 22.1.
3019 @kindex mouse-face @r{(text property)}
3020 The property @code{mouse-face} is used instead of @code{face} when the
3021 mouse is on or near the character. For this purpose, ``near'' means
3022 that all text between the character and where the mouse is have the same
3023 @code{mouse-face} property value.
3026 @kindex fontified @r{(text property)}
3027 This property says whether the character has a face assigned to it by font
3028 locking. The display engine tests it to decide whether a buffer
3029 portion needs refontifying before display. @xref{Auto Faces}. It
3030 takes one of three values:
3034 Font locking is disabled, or the character's @code{face} property, if
3038 This value is only used when ``just in time'' font locking is enabled
3039 and it means that the character's @code{face} property is invalid and
3040 needs deferred fontification.
3043 The character's @code{face} property, or absence of one, is valid.
3047 This property activates various features that change the
3048 way text is displayed. For example, it can make text appear taller
3049 or shorter, higher or lower, wider or narrow, or replaced with an image.
3050 @xref{Display Property}.
3053 @kindex help-echo @r{(text property)}
3055 @anchor{Text help-echo}
3056 If text has a string as its @code{help-echo} property, then when you
3057 move the mouse onto that text, Emacs displays that string in the echo
3058 area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
3061 If the value of the @code{help-echo} property is a function, that
3062 function is called with three arguments, @var{window}, @var{object} and
3063 @var{pos} and should return a help string or @code{nil} for
3064 none. The first argument, @var{window} is the window in which
3065 the help was found. The second, @var{object}, is the buffer, overlay or
3066 string which had the @code{help-echo} property. The @var{pos}
3067 argument is as follows:
3071 If @var{object} is a buffer, @var{pos} is the position in the buffer.
3073 If @var{object} is an overlay, that overlay has a @code{help-echo}
3074 property, and @var{pos} is the position in the overlay's buffer.
3076 If @var{object} is a string (an overlay string or a string displayed
3077 with the @code{display} property), @var{pos} is the position in that
3081 If the value of the @code{help-echo} property is neither a function nor
3082 a string, it is evaluated to obtain a help string.
3084 You can alter the way help text is displayed by setting the variable
3085 @code{show-help-function} (@pxref{Help display}).
3087 This feature is used in the mode line and for other active text.
3090 @cindex keymap of character
3091 @kindex keymap @r{(text property)}
3092 The @code{keymap} property specifies an additional keymap for
3093 commands. When this keymap applies, it is used for key lookup before
3094 the minor mode keymaps and before the buffer's local map.
3095 @xref{Active Keymaps}. If the property value is a symbol, the
3096 symbol's function definition is used as the keymap.
3098 The property's value for the character before point applies if it is
3099 non-@code{nil} and rear-sticky, and the property's value for the
3100 character after point applies if it is non-@code{nil} and
3101 front-sticky. (For mouse clicks, the position of the click is used
3102 instead of the position of point.)
3105 @kindex local-map @r{(text property)}
3106 This property works like @code{keymap} except that it specifies a
3107 keymap to use @emph{instead of} the buffer's local map. For most
3108 purposes (perhaps all purposes), it is better to use the @code{keymap}
3112 The @code{syntax-table} property overrides what the syntax table says
3113 about this particular character. @xref{Syntax Properties}.
3116 @cindex read-only character
3117 @kindex read-only @r{(text property)}
3118 If a character has the property @code{read-only}, then modifying that
3119 character is not allowed. Any command that would do so gets an error,
3120 @code{text-read-only}. If the property value is a string, that string
3121 is used as the error message.
3123 Insertion next to a read-only character is an error if inserting
3124 ordinary text there would inherit the @code{read-only} property due to
3125 stickiness. Thus, you can control permission to insert next to
3126 read-only text by controlling the stickiness. @xref{Sticky Properties}.
3128 Since changing properties counts as modifying the buffer, it is not
3129 possible to remove a @code{read-only} property unless you know the
3130 special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
3131 and then remove the property. @xref{Read Only Buffers}.
3134 @kindex invisible @r{(text property)}
3135 A non-@code{nil} @code{invisible} property can make a character invisible
3136 on the screen. @xref{Invisible Text}, for details.
3139 @kindex intangible @r{(text property)}
3140 If a group of consecutive characters have equal and non-@code{nil}
3141 @code{intangible} properties, then you cannot place point between them.
3142 If you try to move point forward into the group, point actually moves to
3143 the end of the group. If you try to move point backward into the group,
3144 point actually moves to the start of the group.
3146 When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
3147 the @code{intangible} property is ignored.
3150 @kindex field @r{(text property)}
3151 Consecutive characters with the same @code{field} property constitute a
3152 @dfn{field}. Some motion functions including @code{forward-word} and
3153 @code{beginning-of-line} stop moving at a field boundary.
3157 @kindex cursor @r{(text property)}
3158 Normally, the cursor is displayed at the end of any overlay and text
3159 property strings present at the current window position. You can
3160 place the cursor on any desired character of these strings by giving
3161 that character a non-@code{nil} @var{cursor} text property.
3164 @kindex pointer @r{(text property)}
3165 This specifies a specific pointer shape when the mouse pointer is over
3166 this text or image. @xref{Pointer Shape}, for possible pointer
3170 @kindex line-spacing @r{(text property)}
3171 A newline can have a @code{line-spacing} text or overlay property that
3172 controls the height of the display line ending with that newline. The
3173 property value overrides the default frame line spacing and the buffer
3174 local @code{line-spacing} variable. @xref{Line Height}.
3177 @kindex line-height @r{(text property)}
3178 A newline can have a @code{line-height} text or overlay property that
3179 controls the total height of the display line ending in that newline.
3182 @item modification-hooks
3183 @cindex change hooks for a character
3184 @cindex hooks for changing a character
3185 @kindex modification-hooks @r{(text property)}
3186 If a character has the property @code{modification-hooks}, then its
3187 value should be a list of functions; modifying that character calls all
3188 of those functions. Each function receives two arguments: the beginning
3189 and end of the part of the buffer being modified. Note that if a
3190 particular modification hook function appears on several characters
3191 being modified by a single primitive, you can't predict how many times
3192 the function will be called.
3194 If these functions modify the buffer, they should bind
3195 @code{inhibit-modification-hooks} to @code{t} around doing so, to
3196 avoid confusing the internal mechanism that calls these hooks.
3198 @item insert-in-front-hooks
3199 @itemx insert-behind-hooks
3200 @kindex insert-in-front-hooks @r{(text property)}
3201 @kindex insert-behind-hooks @r{(text property)}
3202 The operation of inserting text in a buffer also calls the functions
3203 listed in the @code{insert-in-front-hooks} property of the following
3204 character and in the @code{insert-behind-hooks} property of the
3205 preceding character. These functions receive two arguments, the
3206 beginning and end of the inserted text. The functions are called
3207 @emph{after} the actual insertion takes place.
3209 See also @ref{Change Hooks}, for other hooks that are called
3210 when you change text in a buffer.
3214 @cindex hooks for motion of point
3215 @kindex point-entered @r{(text property)}
3216 @kindex point-left @r{(text property)}
3217 The special properties @code{point-entered} and @code{point-left}
3218 record hook functions that report motion of point. Each time point
3219 moves, Emacs compares these two property values:
3223 the @code{point-left} property of the character after the old location,
3226 the @code{point-entered} property of the character after the new
3231 If these two values differ, each of them is called (if not @code{nil})
3232 with two arguments: the old value of point, and the new one.
3234 The same comparison is made for the characters before the old and new
3235 locations. The result may be to execute two @code{point-left} functions
3236 (which may be the same function) and/or two @code{point-entered}
3237 functions (which may be the same function). In any case, all the
3238 @code{point-left} functions are called first, followed by all the
3239 @code{point-entered} functions.
3241 It is possible with @code{char-after} to examine characters at various
3242 buffer positions without moving point to those positions. Only an
3243 actual change in the value of point runs these hook functions.
3246 @defvar inhibit-point-motion-hooks
3247 When this variable is non-@code{nil}, @code{point-left} and
3248 @code{point-entered} hooks are not run, and the @code{intangible}
3249 property has no effect. Do not set this variable globally; bind it with
3253 @defvar show-help-function
3254 @anchor{Help display} If this variable is non-@code{nil}, it specifies a
3255 function called to display help strings. These may be @code{help-echo}
3256 properties, menu help strings (@pxref{Simple Menu Items},
3257 @pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
3258 Bar}). The specified function is called with one argument, the help
3259 string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs
3260 Manual}) provides an example.
3263 @node Format Properties
3264 @subsection Formatted Text Properties
3266 These text properties affect the behavior of the fill commands. They
3267 are used for representing formatted text. @xref{Filling}, and
3272 If a newline character has this property, it is a ``hard'' newline.
3273 The fill commands do not alter hard newlines and do not move words
3274 across them. However, this property takes effect only if the
3275 @code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft
3276 Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
3279 This property specifies an extra right margin for filling this part of the
3283 This property specifies an extra left margin for filling this part of the
3287 This property specifies the style of justification for filling this part
3291 @node Sticky Properties
3292 @subsection Stickiness of Text Properties
3293 @cindex sticky text properties
3294 @cindex inheritance of text properties
3296 Self-inserting characters normally take on the same properties as the
3297 preceding character. This is called @dfn{inheritance} of properties.
3299 In a Lisp program, you can do insertion with inheritance or without,
3300 depending on your choice of insertion primitive. The ordinary text
3301 insertion functions such as @code{insert} do not inherit any properties.
3302 They insert text with precisely the properties of the string being
3303 inserted, and no others. This is correct for programs that copy text
3304 from one context to another---for example, into or out of the kill ring.
3305 To insert with inheritance, use the special primitives described in this
3306 section. Self-inserting characters inherit properties because they work
3307 using these primitives.
3309 When you do insertion with inheritance, @emph{which} properties are
3310 inherited, and from where, depends on which properties are @dfn{sticky}.
3311 Insertion after a character inherits those of its properties that are
3312 @dfn{rear-sticky}. Insertion before a character inherits those of its
3313 properties that are @dfn{front-sticky}. When both sides offer different
3314 sticky values for the same property, the previous character's value
3317 By default, a text property is rear-sticky but not front-sticky; thus,
3318 the default is to inherit all the properties of the preceding character,
3319 and nothing from the following character.
3321 You can control the stickiness of various text properties with two
3322 specific text properties, @code{front-sticky} and @code{rear-nonsticky},
3323 and with the variable @code{text-property-default-nonsticky}. You can
3324 use the variable to specify a different default for a given property.
3325 You can use those two text properties to make any specific properties
3326 sticky or nonsticky in any particular part of the text.
3328 If a character's @code{front-sticky} property is @code{t}, then all
3329 its properties are front-sticky. If the @code{front-sticky} property is
3330 a list, then the sticky properties of the character are those whose
3331 names are in the list. For example, if a character has a
3332 @code{front-sticky} property whose value is @code{(face read-only)},
3333 then insertion before the character can inherit its @code{face} property
3334 and its @code{read-only} property, but no others.
3336 The @code{rear-nonsticky} property works the opposite way. Most
3337 properties are rear-sticky by default, so the @code{rear-nonsticky}
3338 property says which properties are @emph{not} rear-sticky. If a
3339 character's @code{rear-nonsticky} property is @code{t}, then none of its
3340 properties are rear-sticky. If the @code{rear-nonsticky} property is a
3341 list, properties are rear-sticky @emph{unless} their names are in the
3344 @defvar text-property-default-nonsticky
3345 This variable holds an alist which defines the default rear-stickiness
3346 of various text properties. Each element has the form
3347 @code{(@var{property} . @var{nonstickiness})}, and it defines the
3348 stickiness of a particular text property, @var{property}.
3350 If @var{nonstickiness} is non-@code{nil}, this means that the property
3351 @var{property} is rear-nonsticky by default. Since all properties are
3352 front-nonsticky by default, this makes @var{property} nonsticky in both
3353 directions by default.
3355 The text properties @code{front-sticky} and @code{rear-nonsticky}, when
3356 used, take precedence over the default @var{nonstickiness} specified in
3357 @code{text-property-default-nonsticky}.
3360 Here are the functions that insert text with inheritance of properties:
3362 @defun insert-and-inherit &rest strings
3363 Insert the strings @var{strings}, just like the function @code{insert},
3364 but inherit any sticky properties from the adjoining text.
3367 @defun insert-before-markers-and-inherit &rest strings
3368 Insert the strings @var{strings}, just like the function
3369 @code{insert-before-markers}, but inherit any sticky properties from the
3373 @xref{Insertion}, for the ordinary insertion functions which do not
3376 @node Saving Properties
3377 @subsection Saving Text Properties in Files
3378 @cindex text properties in files
3379 @cindex saving text properties
3381 You can save text properties in files (along with the text itself),
3382 and restore the same text properties when visiting or inserting the
3383 files, using these two hooks:
3385 @defvar write-region-annotate-functions
3386 This variable's value is a list of functions for @code{write-region} to
3387 run to encode text properties in some fashion as annotations to the text
3388 being written in the file. @xref{Writing to Files}.
3390 Each function in the list is called with two arguments: the start and
3391 end of the region to be written. These functions should not alter the
3392 contents of the buffer. Instead, they should return lists indicating
3393 annotations to write in the file in addition to the text in the
3396 Each function should return a list of elements of the form
3397 @code{(@var{position} . @var{string})}, where @var{position} is an
3398 integer specifying the relative position within the text to be written,
3399 and @var{string} is the annotation to add there.
3401 Each list returned by one of these functions must be already sorted in
3402 increasing order by @var{position}. If there is more than one function,
3403 @code{write-region} merges the lists destructively into one sorted list.
3405 When @code{write-region} actually writes the text from the buffer to the
3406 file, it intermixes the specified annotations at the corresponding
3407 positions. All this takes place without modifying the buffer.
3410 @defvar after-insert-file-functions
3411 This variable holds a list of functions for @code{insert-file-contents}
3412 to call after inserting a file's contents. These functions should scan
3413 the inserted text for annotations, and convert them to the text
3414 properties they stand for.
3416 Each function receives one argument, the length of the inserted text;
3417 point indicates the start of that text. The function should scan that
3418 text for annotations, delete them, and create the text properties that
3419 the annotations specify. The function should return the updated length
3420 of the inserted text, as it stands after those changes. The value
3421 returned by one function becomes the argument to the next function.
3423 These functions should always return with point at the beginning of
3426 The intended use of @code{after-insert-file-functions} is for converting
3427 some sort of textual annotations into actual text properties. But other
3428 uses may be possible.
3431 We invite users to write Lisp programs to store and retrieve text
3432 properties in files, using these hooks, and thus to experiment with
3433 various data formats and find good ones. Eventually we hope users
3434 will produce good, general extensions we can install in Emacs.
3436 We suggest not trying to handle arbitrary Lisp objects as text property
3437 names or values---because a program that general is probably difficult
3438 to write, and slow. Instead, choose a set of possible data types that
3439 are reasonably flexible, and not too hard to encode.
3441 @xref{Format Conversion}, for a related feature.
3443 @c ??? In next edition, merge this info Format Conversion.
3445 @node Lazy Properties
3446 @subsection Lazy Computation of Text Properties
3448 Instead of computing text properties for all the text in the buffer,
3449 you can arrange to compute the text properties for parts of the text
3450 when and if something depends on them.
3452 The primitive that extracts text from the buffer along with its
3453 properties is @code{buffer-substring}. Before examining the properties,
3454 this function runs the abnormal hook @code{buffer-access-fontify-functions}.
3456 @defvar buffer-access-fontify-functions
3457 This variable holds a list of functions for computing text properties.
3458 Before @code{buffer-substring} copies the text and text properties for a
3459 portion of the buffer, it calls all the functions in this list. Each of
3460 the functions receives two arguments that specify the range of the
3461 buffer being accessed. (The buffer itself is always the current
3465 The function @code{buffer-substring-no-properties} does not call these
3466 functions, since it ignores text properties anyway.
3468 In order to prevent the hook functions from being called more than
3469 once for the same part of the buffer, you can use the variable
3470 @code{buffer-access-fontified-property}.
3472 @defvar buffer-access-fontified-property
3473 If this value's variable is non-@code{nil}, it is a symbol which is used
3474 as a text property name. A non-@code{nil} value for that text property
3475 means, ``the other text properties for this character have already been
3478 If all the characters in the range specified for @code{buffer-substring}
3479 have a non-@code{nil} value for this property, @code{buffer-substring}
3480 does not call the @code{buffer-access-fontify-functions} functions. It
3481 assumes these characters already have the right text properties, and
3482 just copies the properties they already have.
3484 The normal way to use this feature is that the
3485 @code{buffer-access-fontify-functions} functions add this property, as
3486 well as others, to the characters they operate on. That way, they avoid
3487 being called over and over for the same text.
3490 @node Clickable Text
3491 @subsection Defining Clickable Text
3492 @cindex clickable text
3494 @dfn{Clickable text} is text that can be clicked, with either the
3495 the mouse or via keyboard commands, to produce some result. Many
3496 major modes use clickable text to implement features such as
3497 hyper-links. The @code{button} package provides an easy way to insert
3498 and manipulate clickable text. @xref{Buttons}.
3500 In this section, we will explain how to manually set up clickable
3501 text in a buffer using text properties. This involves two things: (1)
3502 indicating clickability when the mouse moves over the text, and (2)
3503 making @kbd{RET} or a mouse click on that text do something.
3505 Indicating clickability usually involves highlighting the text, and
3506 often involves displaying helpful information about the action, such
3507 as which mouse button to press, or a short summary of the action.
3508 This can be done with the @code{mouse-face} and @code{help-echo}
3509 text properties. @xref{Special Properties}.
3510 Here is an example of how Dired does it:
3514 (if (dired-move-to-filename)
3515 (add-text-properties
3518 (dired-move-to-end-of-filename)
3520 '(mouse-face highlight
3521 help-echo "mouse-2: visit this file in other window")))
3526 The first two arguments to @code{add-text-properties} specify the
3527 beginning and end of the text.
3529 The usual way to make the mouse do something when you click it
3530 on this text is to define @code{mouse-2} in the major mode's
3531 keymap. The job of checking whether the click was on clickable text
3532 is done by the command definition. Here is how Dired does it:
3535 (defun dired-mouse-find-file-other-window (event)
3536 "In Dired, visit the file or directory name you click on."
3538 (let (window pos file)
3540 (setq window (posn-window (event-end event))
3541 pos (posn-point (event-end event)))
3542 (if (not (windowp window))
3543 (error "No file chosen"))
3544 (set-buffer (window-buffer window))
3546 (setq file (dired-get-file-for-visit)))
3547 (if (file-directory-p file)
3548 (or (and (cdr dired-subdir-alist)
3549 (dired-goto-subdir file))
3551 (select-window window)
3552 (dired-other-window file)))
3553 (select-window window)
3554 (find-file-other-window (file-name-sans-versions file t)))))
3558 The reason for the @code{save-excursion} construct is to avoid
3559 changing the current buffer. In this case,
3560 Dired uses the functions @code{posn-window} and @code{posn-point}
3561 to determine which buffer the click happened in and where, and
3562 in that buffer, @code{dired-get-file-for-visit} to determine which
3565 Instead of defining a mouse command for the major mode, you can define
3566 a key binding for the clickable text itself, using the @code{keymap}
3570 (let ((map (make-sparse-keymap)))
3571 (define-key map [mouse-2] 'operate-this-button)
3572 (put-text-property (point)
3574 (dired-move-to-end-of-filename)
3580 This method makes it possible to define different commands for various
3581 clickable pieces of text. Also, the major mode definition (or the
3582 global definition) remains available for the rest of the text in the
3585 @node Links and Mouse-1
3586 @subsection Links and Mouse-1
3587 @cindex follow links
3590 The normal Emacs command for activating text in read-only buffers is
3591 @key{Mouse-2}, which includes following textual links. However, most
3592 graphical applications use @key{Mouse-1} for following links. For
3593 compatibility, @key{Mouse-1} follows links in Emacs too, when you
3594 click on a link quickly without moving the mouse. The user can
3595 customize this behavior through the variable
3596 @code{mouse-1-click-follows-link}.
3598 To define text as a link at the Lisp level, you should bind the
3599 @code{mouse-2} event to a command to follow the link. Then, to indicate that
3600 @key{Mouse-1} should also follow the link, you should specify a
3601 @code{follow-link} condition either as a text property or as a key
3605 @item @code{follow-link} property
3606 If the clickable text has a non-@code{nil} @code{follow-link} text or overlay
3607 property, that specifies the condition.
3609 @item @code{follow-link} event
3610 If there is a binding for the @code{follow-link} event, either on the
3611 clickable text or in the local keymap, the binding is the condition.
3614 Regardless of how you set the @code{follow-link} condition, its
3615 value is used as follows to determine whether the given position is
3616 inside a link, and (if so) to compute an @dfn{action code} saying how
3617 @key{Mouse-1} should handle the link.
3620 @item @code{mouse-face}
3621 If the condition is @code{mouse-face}, a position is inside a link if
3622 there is a non-@code{nil} @code{mouse-face} property at that position.
3623 The action code is always @code{t}.
3625 For example, here is how Info mode handles @key{Mouse-1}:
3628 (define-key Info-mode-map [follow-link] 'mouse-face)
3632 If the condition is a valid function, @var{func}, then a position
3633 @var{pos} is inside a link if @code{(@var{func} @var{pos})} evaluates
3634 to non-@code{nil}. The value returned by @var{func} serves as the
3637 For example, here is how pcvs enables @key{Mouse-1} to follow links on
3641 (define-key map [follow-link]
3643 (eq (get-char-property pos 'face) 'cvs-filename-face)))
3647 If the condition value is anything else, then the position is inside a
3648 link and the condition itself is the action code. Clearly you should
3649 only specify this kind of condition on the text that constitutes a
3654 The action code tells @key{Mouse-1} how to follow the link:
3657 @item a string or vector
3658 If the action code is a string or vector, the @key{Mouse-1} event is
3659 translated into the first element of the string or vector; i.e., the
3660 action of the @key{Mouse-1} click is the local or global binding of
3661 that character or symbol. Thus, if the action code is @code{"foo"},
3662 @key{Mouse-1} translates into @kbd{f}. If it is @code{[foo]},
3663 @key{Mouse-1} translates into @key{foo}.
3666 For any other non-@code{nil} action code, the @code{mouse-1} event is
3667 translated into a @code{mouse-2} event at the same position.
3670 To define @key{Mouse-1} to activate a button defined with
3671 @code{define-button-type}, give the button a @code{follow-link}
3672 property with a value as specified above to determine how to follow
3673 the link. For example, here is how Help mode handles @key{Mouse-1}:
3676 (define-button-type 'help-xref
3678 'action #'help-button-action)
3681 To define @key{Mouse-1} on a widget defined with
3682 @code{define-widget}, give the widget a @code{:follow-link} property
3683 with a value as specified above to determine how to follow the link.
3685 For example, here is how the @code{link} widget specifies that
3686 a @key{Mouse-1} click shall be translated to @key{RET}:
3689 (define-widget 'link 'item
3691 :button-prefix 'widget-link-prefix
3692 :button-suffix 'widget-link-suffix
3694 :help-echo "Follow the link."
3698 @defun mouse-on-link-p pos
3699 This function returns non-@code{nil} if position @var{pos} in the
3700 current buffer is on a link. @var{pos} can also be a mouse event
3701 location, as returned by @code{event-start} (@pxref{Accessing Events}).
3705 @subsection Defining and Using Fields
3708 A field is a range of consecutive characters in the buffer that are
3709 identified by having the same value (comparing with @code{eq}) of the
3710 @code{field} property (either a text-property or an overlay property).
3711 This section describes special functions that are available for
3712 operating on fields.
3714 You specify a field with a buffer position, @var{pos}. We think of
3715 each field as containing a range of buffer positions, so the position
3716 you specify stands for the field containing that position.
3718 When the characters before and after @var{pos} are part of the same
3719 field, there is no doubt which field contains @var{pos}: the one those
3720 characters both belong to. When @var{pos} is at a boundary between
3721 fields, which field it belongs to depends on the stickiness of the
3722 @code{field} properties of the two surrounding characters (@pxref{Sticky
3723 Properties}). The field whose property would be inherited by text
3724 inserted at @var{pos} is the field that contains @var{pos}.
3726 There is an anomalous case where newly inserted text at @var{pos}
3727 would not inherit the @code{field} property from either side. This
3728 happens if the previous character's @code{field} property is not
3729 rear-sticky, and the following character's @code{field} property is not
3730 front-sticky. In this case, @var{pos} belongs to neither the preceding
3731 field nor the following field; the field functions treat it as belonging
3732 to an empty field whose beginning and end are both at @var{pos}.
3734 In all of these functions, if @var{pos} is omitted or @code{nil}, the
3735 value of point is used by default. If narrowing is in effect, then
3736 @var{pos} should fall within the accessible portion. @xref{Narrowing}.
3738 @defun field-beginning &optional pos escape-from-edge limit
3739 This function returns the beginning of the field specified by @var{pos}.
3741 If @var{pos} is at the beginning of its field, and
3742 @var{escape-from-edge} is non-@code{nil}, then the return value is
3743 always the beginning of the preceding field that @emph{ends} at @var{pos},
3744 regardless of the stickiness of the @code{field} properties around
3747 If @var{limit} is non-@code{nil}, it is a buffer position; if the
3748 beginning of the field is before @var{limit}, then @var{limit} will be
3752 @defun field-end &optional pos escape-from-edge limit
3753 This function returns the end of the field specified by @var{pos}.
3755 If @var{pos} is at the end of its field, and @var{escape-from-edge} is
3756 non-@code{nil}, then the return value is always the end of the following
3757 field that @emph{begins} at @var{pos}, regardless of the stickiness of
3758 the @code{field} properties around @var{pos}.
3760 If @var{limit} is non-@code{nil}, it is a buffer position; if the end
3761 of the field is after @var{limit}, then @var{limit} will be returned
3765 @defun field-string &optional pos
3766 This function returns the contents of the field specified by @var{pos},
3770 @defun field-string-no-properties &optional pos
3771 This function returns the contents of the field specified by @var{pos},
3772 as a string, discarding text properties.
3775 @defun delete-field &optional pos
3776 This function deletes the text of the field specified by @var{pos}.
3779 @defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
3780 This function ``constrains'' @var{new-pos} to the field that
3781 @var{old-pos} belongs to---in other words, it returns the position
3782 closest to @var{new-pos} that is in the same field as @var{old-pos}.
3784 If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
3785 the value of point instead, and moves point to the resulting position
3786 as well as returning it.
3788 If @var{old-pos} is at the boundary of two fields, then the acceptable
3789 final positions depend on the argument @var{escape-from-edge}. If
3790 @var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in
3791 the field whose @code{field} property equals what new characters
3792 inserted at @var{old-pos} would inherit. (This depends on the
3793 stickiness of the @code{field} property for the characters before and
3794 after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
3795 @var{new-pos} can be anywhere in the two adjacent fields.
3796 Additionally, if two fields are separated by another field with the
3797 special value @code{boundary}, then any point within this special
3798 field is also considered to be ``on the boundary.''
3800 Commands like @kbd{C-a} with no argumemt, that normally move backward
3801 to a specific kind of location and stay there once there, probably
3802 should specify @code{nil} for @var{escape-from-edge}. Other motion
3803 commands that check fields should probably pass @code{t}.
3805 If the optional argument @var{only-in-line} is non-@code{nil}, and
3806 constraining @var{new-pos} in the usual way would move it to a different
3807 line, @var{new-pos} is returned unconstrained. This used in commands
3808 that move by line, such as @code{next-line} and
3809 @code{beginning-of-line}, so that they respect field boundaries only in
3810 the case where they can still move to the right line.
3812 If the optional argument @var{inhibit-capture-property} is
3813 non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that
3814 name, then any field boundaries are ignored.
3816 You can cause @code{constrain-to-field} to ignore all field boundaries
3817 (and so never constrain anything) by binding the variable
3818 @code{inhibit-field-text-motion} to a non-@code{nil} value.
3822 @subsection Why Text Properties are not Intervals
3825 Some editors that support adding attributes to text in the buffer do
3826 so by letting the user specify ``intervals'' within the text, and adding
3827 the properties to the intervals. Those editors permit the user or the
3828 programmer to determine where individual intervals start and end. We
3829 deliberately provided a different sort of interface in Emacs Lisp to
3830 avoid certain paradoxical behavior associated with text modification.
3832 If the actual subdivision into intervals is meaningful, that means you
3833 can distinguish between a buffer that is just one interval with a
3834 certain property, and a buffer containing the same text subdivided into
3835 two intervals, both of which have that property.
3837 Suppose you take the buffer with just one interval and kill part of
3838 the text. The text remaining in the buffer is one interval, and the
3839 copy in the kill ring (and the undo list) becomes a separate interval.
3840 Then if you yank back the killed text, you get two intervals with the
3841 same properties. Thus, editing does not preserve the distinction
3842 between one interval and two.
3844 Suppose we ``fix'' this problem by coalescing the two intervals when
3845 the text is inserted. That works fine if the buffer originally was a
3846 single interval. But suppose instead that we have two adjacent
3847 intervals with the same properties, and we kill the text of one interval
3848 and yank it back. The same interval-coalescence feature that rescues
3849 the other case causes trouble in this one: after yanking, we have just
3850 one interval. One again, editing does not preserve the distinction
3851 between one interval and two.
3853 Insertion of text at the border between intervals also raises
3854 questions that have no satisfactory answer.
3856 However, it is easy to arrange for editing to behave consistently for
3857 questions of the form, ``What are the properties of this character?''
3858 So we have decided these are the only questions that make sense; we have
3859 not implemented asking questions about where intervals start or end.
3861 In practice, you can usually use the text property search functions in
3862 place of explicit interval boundaries. You can think of them as finding
3863 the boundaries of intervals, assuming that intervals are always
3864 coalesced whenever possible. @xref{Property Search}.
3866 Emacs also provides explicit intervals as a presentation feature; see
3870 @section Substituting for a Character Code
3872 The following functions replace characters within a specified region
3873 based on their character codes.
3875 @defun subst-char-in-region start end old-char new-char &optional noundo
3876 @cindex replace characters
3877 This function replaces all occurrences of the character @var{old-char}
3878 with the character @var{new-char} in the region of the current buffer
3879 defined by @var{start} and @var{end}.
3881 @cindex undo avoidance
3882 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
3883 not record the change for undo and does not mark the buffer as modified.
3884 This was useful for controlling the old selective display feature
3885 (@pxref{Selective Display}).
3887 @code{subst-char-in-region} does not move point and returns
3892 ---------- Buffer: foo ----------
3893 This is the contents of the buffer before.
3894 ---------- Buffer: foo ----------
3898 (subst-char-in-region 1 20 ?i ?X)
3901 ---------- Buffer: foo ----------
3902 ThXs Xs the contents of the buffer before.
3903 ---------- Buffer: foo ----------
3908 @defun translate-region start end table
3909 This function applies a translation table to the characters in the
3910 buffer between positions @var{start} and @var{end}.
3912 The translation table @var{table} is a string or a char-table;
3913 @code{(aref @var{table} @var{ochar})} gives the translated character
3914 corresponding to @var{ochar}. If @var{table} is a string, any
3915 characters with codes larger than the length of @var{table} are not
3916 altered by the translation.
3918 The return value of @code{translate-region} is the number of
3919 characters that were actually changed by the translation. This does
3920 not count characters that were mapped into themselves in the
3928 A register is a sort of variable used in Emacs editing that can hold a
3929 variety of different kinds of values. Each register is named by a
3930 single character. All @acronym{ASCII} characters and their meta variants
3931 (but with the exception of @kbd{C-g}) can be used to name registers.
3932 Thus, there are 255 possible registers. A register is designated in
3933 Emacs Lisp by the character that is its name.
3935 @defvar register-alist
3936 This variable is an alist of elements of the form @code{(@var{name} .
3937 @var{contents})}. Normally, there is one element for each Emacs
3938 register that has been used.
3940 The object @var{name} is a character (an integer) identifying the
3944 The @var{contents} of a register can have several possible types:
3948 A number stands for itself. If @code{insert-register} finds a number
3949 in the register, it converts the number to decimal.
3952 A marker represents a buffer position to jump to.
3955 A string is text saved in the register.
3958 A rectangle is represented by a list of strings.
3960 @item @code{(@var{window-configuration} @var{position})}
3961 This represents a window configuration to restore in one frame, and a
3962 position to jump to in the current buffer.
3964 @item @code{(@var{frame-configuration} @var{position})}
3965 This represents a frame configuration to restore, and a position
3966 to jump to in the current buffer.
3968 @item (file @var{filename})
3969 This represents a file to visit; jumping to this value visits file
3972 @item (file-query @var{filename} @var{position})
3973 This represents a file to visit and a position in it; jumping to this
3974 value visits file @var{filename} and goes to buffer position
3975 @var{position}. Restoring this type of position asks the user for
3979 The functions in this section return unpredictable values unless
3982 @defun get-register reg
3983 This function returns the contents of the register
3984 @var{reg}, or @code{nil} if it has no contents.
3987 @defun set-register reg value
3988 This function sets the contents of register @var{reg} to @var{value}.
3989 A register can be set to any value, but the other register functions
3990 expect only certain data types. The return value is @var{value}.
3993 @deffn Command view-register reg
3994 This command displays what is contained in register @var{reg}.
3998 @deffn Command point-to-register reg
3999 This command stores both the current location of point and the current
4000 buffer in register @var{reg} as a marker.
4003 @deffn Command jump-to-register reg
4004 @deffnx Command register-to-point reg
4005 @comment !!SourceFile register.el
4006 This command restores the status recorded in register @var{reg}.
4008 If @var{reg} contains a marker, it moves point to the position stored in
4009 the marker. Since both the buffer and the location within the buffer
4010 are stored by the @code{point-to-register} function, this command can
4011 switch you to another buffer.
4013 If @var{reg} contains a window configuration or a frame configuration.
4014 @code{jump-to-register} restores that configuration.
4018 @deffn Command insert-register reg &optional beforep
4019 This command inserts contents of register @var{reg} into the current
4022 Normally, this command puts point before the inserted text, and the
4023 mark after it. However, if the optional second argument @var{beforep}
4024 is non-@code{nil}, it puts the mark before and point after.
4025 You can pass a non-@code{nil} second argument @var{beforep} to this
4026 function interactively by supplying any prefix argument.
4028 If the register contains a rectangle, then the rectangle is inserted
4029 with its upper left corner at point. This means that text is inserted
4030 in the current line and underneath it on successive lines.
4032 If the register contains something other than saved text (a string) or
4033 a rectangle (a list), currently useless things happen. This may be
4034 changed in the future.
4038 @deffn Command copy-to-register reg start end &optional delete-flag
4039 This command copies the region from @var{start} to @var{end} into
4040 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
4041 the region from the buffer after copying it into the register.
4044 @deffn Command prepend-to-register reg start end &optional delete-flag
4045 This command prepends the region from @var{start} to @var{end} into
4046 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
4047 the region from the buffer after copying it to the register.
4050 @deffn Command append-to-register reg start end &optional delete-flag
4051 This command appends the region from @var{start} to @var{end} to the
4052 text already in register @var{reg}. If @var{delete-flag} is
4053 non-@code{nil}, it deletes the region from the buffer after copying it
4057 @deffn Command copy-rectangle-to-register reg start end &optional delete-flag
4058 This command copies a rectangular region from @var{start} to @var{end}
4059 into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it
4060 deletes the region from the buffer after copying it to the register.
4063 @deffn Command window-configuration-to-register reg
4064 This function stores the window configuration of the selected frame in
4068 @deffn Command frame-configuration-to-register reg
4069 This function stores the current frame configuration in register
4075 @section Transposition of Text
4077 This subroutine is used by the transposition commands.
4079 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
4080 This function exchanges two nonoverlapping portions of the buffer.
4081 Arguments @var{start1} and @var{end1} specify the bounds of one portion
4082 and arguments @var{start2} and @var{end2} specify the bounds of the
4085 Normally, @code{transpose-regions} relocates markers with the transposed
4086 text; a marker previously positioned within one of the two transposed
4087 portions moves along with that portion, thus remaining between the same
4088 two characters in their new position. However, if @var{leave-markers}
4089 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
4090 all markers unrelocated.
4094 @section Base 64 Encoding
4095 @cindex base 64 encoding
4097 Base 64 code is used in email to encode a sequence of 8-bit bytes as
4098 a longer sequence of @acronym{ASCII} graphic characters. It is defined in
4099 Internet RFC@footnote{
4100 An RFC, an acronym for @dfn{Request for Comments}, is a numbered
4101 Internet informational document describing a standard. RFCs are
4102 usually written by technical experts acting on their own initiative,
4103 and are traditionally written in a pragmatic, experience-driven
4105 }2045. This section describes the functions for
4106 converting to and from this code.
4108 @defun base64-encode-region beg end &optional no-line-break
4109 This function converts the region from @var{beg} to @var{end} into base
4110 64 code. It returns the length of the encoded text. An error is
4111 signaled if a character in the region is multibyte, i.e.@: in a
4112 multibyte buffer the region must contain only characters from the
4113 charsets @code{ascii}, @code{eight-bit-control} and
4114 @code{eight-bit-graphic}.
4116 Normally, this function inserts newline characters into the encoded
4117 text, to avoid overlong lines. However, if the optional argument
4118 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
4119 the output is just one long line.
4122 @defun base64-encode-string string &optional no-line-break
4123 This function converts the string @var{string} into base 64 code. It
4124 returns a string containing the encoded text. As for
4125 @code{base64-encode-region}, an error is signaled if a character in the
4126 string is multibyte.
4128 Normally, this function inserts newline characters into the encoded
4129 text, to avoid overlong lines. However, if the optional argument
4130 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
4131 the result string is just one long line.
4134 @defun base64-decode-region beg end
4135 This function converts the region from @var{beg} to @var{end} from base
4136 64 code into the corresponding decoded text. It returns the length of
4139 The decoding functions ignore newline characters in the encoded text.
4142 @defun base64-decode-string string
4143 This function converts the string @var{string} from base 64 code into
4144 the corresponding decoded text. It returns a unibyte string containing the
4147 The decoding functions ignore newline characters in the encoded text.
4151 @section MD5 Checksum
4152 @cindex MD5 checksum
4153 @cindex message digest computation
4155 MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit
4156 ``fingerprints'' of a document or program. They are used to verify
4157 that you have an exact and unaltered copy of the data. The algorithm
4158 to calculate the MD5 message digest is defined in Internet
4160 For an explanation of what is an RFC, see the footnote in @ref{Base
4162 }1321. This section describes the Emacs facilities for computing
4165 @defun md5 object &optional start end coding-system noerror
4166 This function returns the MD5 message digest of @var{object}, which
4167 should be a buffer or a string.
4169 The two optional arguments @var{start} and @var{end} are character
4170 positions specifying the portion of @var{object} to compute the
4171 message digest for. If they are @code{nil} or omitted, the digest is
4172 computed for the whole of @var{object}.
4174 The function @code{md5} does not compute the message digest directly
4175 from the internal Emacs representation of the text (@pxref{Text
4176 Representations}). Instead, it encodes the text using a coding
4177 system, and computes the message digest from the encoded text. The
4178 optional fourth argument @var{coding-system} specifies which coding
4179 system to use for encoding the text. It should be the same coding
4180 system that you used to read the text, or that you used or will use
4181 when saving or sending the text. @xref{Coding Systems}, for more
4182 information about coding systems.
4184 If @var{coding-system} is @code{nil} or omitted, the default depends
4185 on @var{object}. If @var{object} is a buffer, the default for
4186 @var{coding-system} is whatever coding system would be chosen by
4187 default for writing this text into a file. If @var{object} is a
4188 string, the user's most preferred coding system (@pxref{Recognize
4189 Coding, prefer-coding-system, the description of
4190 @code{prefer-coding-system}, emacs, GNU Emacs Manual}) is used.
4192 Normally, @code{md5} signals an error if the text can't be encoded
4193 using the specified or chosen coding system. However, if
4194 @var{noerror} is non-@code{nil}, it silently uses @code{raw-text}
4198 @node Atomic Changes
4199 @section Atomic Change Groups
4200 @cindex atomic changes
4202 In data base terminology, an @dfn{atomic} change is an indivisible
4203 change---it can succeed entirely or it can fail entirely, but it
4204 cannot partly succeed. A Lisp program can make a series of changes to
4205 one or several buffers as an @dfn{atomic change group}, meaning that
4206 either the entire series of changes will be installed in their buffers
4207 or, in case of an error, none of them will be.
4209 To do this for one buffer, the one already current, simply write a
4210 call to @code{atomic-change-group} around the code that makes the
4214 (atomic-change-group
4216 (delete-region x y))
4220 If an error (or other nonlocal exit) occurs inside the body of
4221 @code{atomic-change-group}, it unmakes all the changes in that buffer
4222 that were during the execution of the body. This kind of change group
4223 has no effect on any other buffers---any such changes remain.
4225 If you need something more sophisticated, such as to make changes in
4226 various buffers constitute one atomic group, you must directly call
4227 lower-level functions that @code{atomic-change-group} uses.
4229 @defun prepare-change-group &optional buffer
4230 This function sets up a change group for buffer @var{buffer}, which
4231 defaults to the current buffer. It returns a ``handle'' that
4232 represents the change group. You must use this handle to activate the
4233 change group and subsequently to finish it.
4236 To use the change group, you must @dfn{activate} it. You must do
4237 this before making any changes in the text of @var{buffer}.
4239 @defun activate-change-group handle
4240 This function activates the change group that @var{handle} designates.
4243 After you activate the change group, any changes you make in that
4244 buffer become part of it. Once you have made all the desired changes
4245 in the buffer, you must @dfn{finish} the change group. There are two
4246 ways to do this: you can either accept (and finalize) all the changes,
4249 @defun accept-change-group handle
4250 This function accepts all the changes in the change group specified by
4251 @var{handle}, making them final.
4254 @defun cancel-change-group handle
4255 This function cancels and undoes all the changes in the change group
4256 specified by @var{handle}.
4259 Your code should use @code{unwind-protect} to make sure the group is
4260 always finished. The call to @code{activate-change-group} should be
4261 inside the @code{unwind-protect}, in case the user types @kbd{C-g}
4262 just after it runs. (This is one reason why
4263 @code{prepare-change-group} and @code{activate-change-group} are
4264 separate functions, because normally you would call
4265 @code{prepare-change-group} before the start of that
4266 @code{unwind-protect}.) Once you finish the group, don't use the
4267 handle again---in particular, don't try to finish the same group
4270 To make a multibuffer change group, call @code{prepare-change-group}
4271 once for each buffer you want to cover, then use @code{nconc} to
4272 combine the returned values, like this:
4275 (nconc (prepare-change-group buffer-1)
4276 (prepare-change-group buffer-2))
4279 You can then activate the multibuffer change group with a single call
4280 to @code{activate-change-group}, and finish it with a single call to
4281 @code{accept-change-group} or @code{cancel-change-group}.
4283 Nested use of several change groups for the same buffer works as you
4284 would expect. Non-nested use of change groups for the same buffer
4285 will get Emacs confused, so don't let it happen; the first change
4286 group you start for any given buffer should be the last one finished.
4289 @section Change Hooks
4290 @cindex change hooks
4291 @cindex hooks for text changes
4293 These hook variables let you arrange to take notice of all changes in
4294 all buffers (or in a particular buffer, if you make them buffer-local).
4295 See also @ref{Special Properties}, for how to detect changes to specific
4298 The functions you use in these hooks should save and restore the match
4299 data if they do anything that uses regular expressions; otherwise, they
4300 will interfere in bizarre ways with the editing operations that call
4303 @defvar before-change-functions
4304 This variable holds a list of functions to call before any buffer
4305 modification. Each function gets two arguments, the beginning and end
4306 of the region that is about to change, represented as integers. The
4307 buffer that is about to change is always the current buffer.
4310 @defvar after-change-functions
4311 This variable holds a list of functions to call after any buffer
4312 modification. Each function receives three arguments: the beginning and
4313 end of the region just changed, and the length of the text that existed
4314 before the change. All three arguments are integers. The buffer that's
4315 about to change is always the current buffer.
4317 The length of the old text is the difference between the buffer positions
4318 before and after that text as it was before the change. As for the
4319 changed text, its length is simply the difference between the first two
4323 Output of messages into the @samp{*Messages*} buffer does not
4324 call these functions.
4326 @defmac combine-after-change-calls body@dots{}
4327 The macro executes @var{body} normally, but arranges to call the
4328 after-change functions just once for a series of several changes---if
4331 If a program makes several text changes in the same area of the buffer,
4332 using the macro @code{combine-after-change-calls} around that part of
4333 the program can make it run considerably faster when after-change hooks
4334 are in use. When the after-change hooks are ultimately called, the
4335 arguments specify a portion of the buffer including all of the changes
4336 made within the @code{combine-after-change-calls} body.
4338 @strong{Warning:} You must not alter the values of
4339 @code{after-change-functions} within
4340 the body of a @code{combine-after-change-calls} form.
4342 @strong{Warning:} if the changes you combine occur in widely scattered
4343 parts of the buffer, this will still work, but it is not advisable,
4344 because it may lead to inefficient behavior for some change hook
4348 The two variables above are temporarily bound to @code{nil} during the
4349 time that any of these functions is running. This means that if one of
4350 these functions changes the buffer, that change won't run these
4351 functions. If you do want a hook function to make changes that run
4352 these functions, make it bind these variables back to their usual
4355 One inconvenient result of this protective feature is that you cannot
4356 have a function in @code{after-change-functions} or
4357 @code{before-change-functions} which changes the value of that variable.
4358 But that's not a real limitation. If you want those functions to change
4359 the list of functions to run, simply add one fixed function to the hook,
4360 and code that function to look in another variable for other functions
4361 to call. Here is an example:
4364 (setq my-own-after-change-functions nil)
4365 (defun indirect-after-change-function (beg end len)
4366 (let ((list my-own-after-change-functions))
4368 (funcall (car list) beg end len)
4369 (setq list (cdr list)))))
4372 (add-hooks 'after-change-functions
4373 'indirect-after-change-function)
4377 @defvar first-change-hook
4378 This variable is a normal hook that is run whenever a buffer is changed
4379 that was previously in the unmodified state.
4382 @defvar inhibit-modification-hooks
4383 If this variable is non-@code{nil}, all of the change hooks are
4384 disabled; none of them run. This affects all the hook variables
4385 described above in this section, as well as the hooks attached to
4386 certain special text properties (@pxref{Special Properties}) and overlay
4387 properties (@pxref{Overlay Properties}).
4391 arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b