2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-2017 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
9 This chapter describes the functions that deal with the text in a
10 buffer. Most examine, insert, or delete text in the current buffer,
11 often operating at point or on text adjacent to point. Many are
12 interactive. All the functions that change the text provide for undoing
13 the changes (@pxref{Undo}).
15 Many text-related functions operate on a region of text defined by two
16 buffer positions passed in arguments named @var{start} and @var{end}.
17 These arguments should be either markers (@pxref{Markers}) or numeric
18 character positions (@pxref{Positions}). The order of these arguments
19 does not matter; it is all right for @var{start} to be the end of the
20 region and @var{end} the beginning. For example, @code{(delete-region 1
21 10)} and @code{(delete-region 10 1)} are equivalent. An
22 @code{args-out-of-range} error is signaled if either @var{start} or
23 @var{end} is outside the accessible portion of the buffer. In an
24 interactive call, point and the mark are used for these arguments.
26 @cindex buffer contents
27 Throughout this chapter, ``text'' refers to the characters in the
28 buffer, together with their properties (when relevant). Keep in mind
29 that point is always between two characters, and the cursor appears on
30 the character after point.
33 * Near Point:: Examining text in the vicinity of point.
34 * Buffer Contents:: Examining text in a general fashion.
35 * Comparing Text:: Comparing substrings of buffers.
36 * Insertion:: Adding new text to a buffer.
37 * Commands for Insertion:: User-level commands to insert text.
38 * Deletion:: Removing text from a buffer.
39 * User-Level Deletion:: User-level commands to delete text.
40 * The Kill Ring:: Where removed text sometimes is saved for later use.
41 * Undo:: Undoing changes to the text of a buffer.
42 * Maintaining Undo:: How to enable and disable undo information.
43 How to control how much information is kept.
44 * Filling:: Functions for explicit filling.
45 * Margins:: How to specify margins for filling commands.
46 * Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context.
47 * Auto Filling:: How auto-fill mode is implemented to break lines.
48 * Sorting:: Functions for sorting parts of the buffer.
49 * Columns:: Computing horizontal positions, and using them.
50 * Indentation:: Functions to insert or adjust indentation.
51 * Case Changes:: Case conversion of parts of the buffer.
52 * Text Properties:: Assigning Lisp property lists to text characters.
53 * Substitution:: Replacing a given character wherever it appears.
54 * Registers:: How registers are implemented. Accessing the text or
55 position stored in a register.
56 * Transposition:: Swapping two portions of a buffer.
57 * Decompression:: Dealing with compressed data.
58 * Base 64:: Conversion to or from base 64 encoding.
59 * Checksum/Hash:: Computing cryptographic hashes.
60 * Parsing HTML/XML:: Parsing HTML and XML.
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 (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 (string (preceding-char))
125 (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
165 @cindex buffer portion as string
167 This section describes functions that allow a Lisp program to
168 convert any portion of the text in the buffer into a string.
170 @defun buffer-substring start end
171 This function returns a string containing a copy of the text of the
172 region defined by positions @var{start} and @var{end} in the current
173 buffer. If the arguments are not positions in the accessible portion
174 of the buffer, @code{buffer-substring} signals an
175 @code{args-out-of-range} error.
177 Here's an example which assumes Font-Lock mode is not enabled:
181 ---------- Buffer: foo ----------
182 This is the contents of buffer foo
184 ---------- Buffer: foo ----------
188 (buffer-substring 1 10)
189 @result{} "This is t"
192 (buffer-substring (point-max) 10)
193 @result{} "he contents of buffer foo\n"
197 If the text being copied has any text properties, these are copied into
198 the string along with the characters they belong to. @xref{Text
199 Properties}. However, overlays (@pxref{Overlays}) in the buffer and
200 their properties are ignored, not copied.
202 For example, if Font-Lock mode is enabled, you might get results like
207 (buffer-substring 1 10)
208 @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t))
213 @defun buffer-substring-no-properties start end
214 This is like @code{buffer-substring}, except that it does not copy text
215 properties, just the characters themselves. @xref{Text Properties}.
219 This function returns the contents of the entire accessible portion of
220 the current buffer, as a string.
223 If you need to make sure the resulting string, when copied to a
224 different location, will not change its visual appearance due to
225 reordering of bidirectional text, use the
226 @code{buffer-substring-with-bidi-context} function
227 (@pxref{Bidirectional Display, buffer-substring-with-bidi-context}).
229 @defun filter-buffer-substring start end &optional delete
230 This function filters the buffer text between @var{start} and @var{end}
231 using a function specified by the variable
232 @code{filter-buffer-substring-function}, and returns the result.
234 The default filter function consults the obsolete wrapper hook
235 @code{filter-buffer-substring-functions} (see the documentation string
236 of the macro @code{with-wrapper-hook} for the details about this
237 obsolete facility), and the obsolete variable
238 @code{buffer-substring-filters}. If both of these are @code{nil}, it
239 returns the unaltered text from the buffer, i.e., what
240 @code{buffer-substring} would return.
242 If @var{delete} is non-@code{nil}, the function deletes the text
243 between @var{start} and @var{end} after copying it, like
244 @code{delete-and-extract-region}.
246 Lisp code should use this function instead of @code{buffer-substring},
247 @code{buffer-substring-no-properties},
248 or @code{delete-and-extract-region} when copying into user-accessible
249 data structures such as the kill-ring, X clipboard, and registers.
250 Major and minor modes can modify @code{filter-buffer-substring-function}
251 to alter such text as it is copied out of the buffer.
254 @defvar filter-buffer-substring-function
255 The value of this variable is a function that @code{filter-buffer-substring}
256 will call to do the actual work. The function receives three
257 arguments, the same as those of @code{filter-buffer-substring},
258 which it should treat as per the documentation of that function. It
259 should return the filtered text (and optionally delete the source text).
262 @noindent The following two variables are obsoleted by
263 @code{filter-buffer-substring-function}, but are still supported for
264 backward compatibility.
266 @defvar filter-buffer-substring-functions
267 This obsolete variable is a wrapper hook, whose members should be functions
268 that accept four arguments: @var{fun}, @var{start}, @var{end}, and
269 @var{delete}. @var{fun} is a function that takes three arguments
270 (@var{start}, @var{end}, and @var{delete}), and returns a string. In
271 both cases, the @var{start}, @var{end}, and @var{delete} arguments are
272 the same as those of @code{filter-buffer-substring}.
274 The first hook function is passed a @var{fun} that is equivalent to
275 the default operation of @code{filter-buffer-substring}, i.e., it
276 returns the buffer-substring between @var{start} and @var{end}
277 (processed by any @code{buffer-substring-filters}) and optionally
278 deletes the original text from the buffer. In most cases, the hook
279 function will call @var{fun} once, and then do its own processing of
280 the result. The next hook function receives a @var{fun} equivalent to
281 this, and so on. The actual return value is the result of all the
282 hook functions acting in sequence.
285 @defvar buffer-substring-filters
286 The value of this obsolete variable should be a list of functions
287 that accept a single string argument and return another string.
288 The default @code{filter-buffer-substring} function passes the buffer
289 substring to the first function in this list, and the return value of
290 each function is passed to the next function. The return value of the
291 last function is passed to @code{filter-buffer-substring-functions}.
294 @defun current-word &optional strict really-word
295 This function returns the symbol (or word) at or near point, as a
296 string. The return value includes no text properties.
298 If the optional argument @var{really-word} is non-@code{nil}, it finds a
299 word; otherwise, it finds a symbol (which includes both word
300 characters and symbol constituent characters).
302 If the optional argument @var{strict} is non-@code{nil}, then point
303 must be in or next to the symbol or word---if no symbol or word is
304 there, the function returns @code{nil}. Otherwise, a nearby symbol or
305 word on the same line is acceptable.
308 @defun thing-at-point thing &optional no-properties
309 Return the @var{thing} around or next to point, as a string.
311 The argument @var{thing} is a symbol which specifies a kind of syntactic
312 entity. Possibilities include @code{symbol}, @code{list}, @code{sexp},
313 @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
314 @code{whitespace}, @code{line}, @code{page}, and others.
316 When the optional argument @var{no-properties} is non-@code{nil}, this
317 function strips text properties from the return value.
320 ---------- Buffer: foo ----------
321 Gentlemen may cry ``Pea@point{}ce! Peace!,''
322 but there is no peace.
323 ---------- Buffer: foo ----------
325 (thing-at-point 'word)
327 (thing-at-point 'line)
328 @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
329 (thing-at-point 'whitespace)
335 @section Comparing Text
336 @cindex comparing buffer text
338 This function lets you compare portions of the text in a buffer, without
339 copying them into strings first.
341 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
342 This function lets you compare two substrings of the same buffer or two
343 different buffers. The first three arguments specify one substring,
344 giving a buffer (or a buffer name) and two positions within the
345 buffer. The last three arguments specify the other substring in the
346 same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or
347 both to stand for the current buffer.
349 The value is negative if the first substring is less, positive if the
350 first is greater, and zero if they are equal. The absolute value of
351 the result is one plus the index of the first differing characters
352 within the substrings.
354 This function ignores case when comparing characters
355 if @code{case-fold-search} is non-@code{nil}. It always ignores
358 Suppose you have the text @w{@samp{foobarbar haha!rara!}} in the
359 current buffer; then in this example the two substrings are @samp{rbar
360 } and @samp{rara!}. The value is 2 because the first substring is
361 greater at the second character.
364 (compare-buffer-substrings nil 6 11 nil 16 21)
370 @section Inserting Text
371 @cindex insertion of text
372 @cindex text insertion
374 @cindex insertion before point
375 @cindex before point, insertion
376 @dfn{Insertion} means adding new text to a buffer. The inserted text
377 goes at point---between the character before point and the character
378 after point. Some insertion functions leave point before the inserted
379 text, while other functions leave it after. We call the former
380 insertion @dfn{after point} and the latter insertion @dfn{before point}.
382 Insertion moves markers located at positions after the insertion
383 point, so that they stay with the surrounding text (@pxref{Markers}).
384 When a marker points at the place of insertion, insertion may or may
385 not relocate the marker, depending on the marker's insertion type
386 (@pxref{Marker Insertion Types}). Certain special functions such as
387 @code{insert-before-markers} relocate all such markers to point after
388 the inserted text, regardless of the markers' insertion type.
390 Insertion functions signal an error if the current buffer is
391 read-only (@pxref{Read Only Buffers}) or if they insert within
392 read-only text (@pxref{Special Properties}).
394 These functions copy text characters from strings and buffers along
395 with their properties. The inserted characters have exactly the same
396 properties as the characters they were copied from. By contrast,
397 characters specified as separate arguments, not part of a string or
398 buffer, inherit their text properties from the neighboring text.
400 The insertion functions convert text from unibyte to multibyte in
401 order to insert in a multibyte buffer, and vice versa---if the text
402 comes from a string or from a buffer. However, they do not convert
403 unibyte character codes 128 through 255 to multibyte characters, not
404 even if the current buffer is a multibyte buffer. @xref{Converting
407 @defun insert &rest args
408 This function inserts the strings and/or characters @var{args} into the
409 current buffer, at point, moving point forward. In other words, it
410 inserts the text before point. An error is signaled unless all
411 @var{args} are either strings or characters. The value is @code{nil}.
414 @defun insert-before-markers &rest args
415 This function inserts the strings and/or characters @var{args} into the
416 current buffer, at point, moving point forward. An error is signaled
417 unless all @var{args} are either strings or characters. The value is
420 This function is unlike the other insertion functions in that it
421 relocates markers initially pointing at the insertion point, to point
422 after the inserted text. If an overlay begins at the insertion point,
423 the inserted text falls outside the overlay; if a nonempty overlay
424 ends at the insertion point, the inserted text falls inside that
428 @deffn Command insert-char character &optional count inherit
429 This command inserts @var{count} instances of @var{character} into the
430 current buffer before point. The argument @var{count} must be an
431 integer, and @var{character} must be a character.
433 If called interactively, this command prompts for @var{character}
434 using its Unicode name or its code point. @xref{Inserting Text,,,
435 emacs, The GNU Emacs Manual}.
437 This function does not convert unibyte character codes 128 through 255
438 to multibyte characters, not even if the current buffer is a multibyte
439 buffer. @xref{Converting Representations}.
441 If @var{inherit} is non-@code{nil}, the inserted characters inherit
442 sticky text properties from the two characters before and after the
443 insertion point. @xref{Sticky Properties}.
446 @defun insert-buffer-substring from-buffer-or-name &optional start end
447 This function inserts a portion of buffer @var{from-buffer-or-name}
448 into the current buffer before point. The text inserted is the region
449 between @var{start} (inclusive) and @var{end} (exclusive). (These
450 arguments default to the beginning and end of the accessible portion
451 of that buffer.) This function returns @code{nil}.
453 In this example, the form is executed with buffer @samp{bar} as the
454 current buffer. We assume that buffer @samp{bar} is initially empty.
458 ---------- Buffer: foo ----------
459 We hold these truths to be self-evident, that all
460 ---------- Buffer: foo ----------
464 (insert-buffer-substring "foo" 1 20)
467 ---------- Buffer: bar ----------
468 We hold these truth@point{}
469 ---------- Buffer: bar ----------
474 @defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
475 This is like @code{insert-buffer-substring} except that it does not
476 copy any text properties.
479 @xref{Sticky Properties}, for other insertion functions that inherit
480 text properties from the nearby text in addition to inserting it.
481 Whitespace inserted by indentation functions also inherits text
484 @node Commands for Insertion
485 @section User-Level Insertion Commands
487 This section describes higher-level commands for inserting text,
488 commands intended primarily for the user but useful also in Lisp
491 @deffn Command insert-buffer from-buffer-or-name
492 This command inserts the entire accessible contents of
493 @var{from-buffer-or-name} (which must exist) into the current buffer
494 after point. It leaves the mark after the inserted text. The value
498 @deffn Command self-insert-command count
499 @cindex character insertion
500 @cindex self-insertion
501 This command inserts the last character typed; it does so @var{count}
502 times, before point, and returns @code{nil}. Most printing characters
503 are bound to this command. In routine use, @code{self-insert-command}
504 is the most frequently called function in Emacs, but programs rarely use
505 it except to install it on a keymap.
507 In an interactive call, @var{count} is the numeric prefix argument.
509 @c FIXME: This variable is obsolete since 23.1.
510 Self-insertion translates the input character through
511 @code{translation-table-for-input}. @xref{Translation of Characters}.
513 This command calls @code{auto-fill-function} whenever that is
514 non-@code{nil} and the character inserted is in the table
515 @code{auto-fill-chars} (@pxref{Auto Filling}).
517 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
518 This command performs abbrev expansion if Abbrev mode is enabled and
519 the inserted character does not have word-constituent
520 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also
521 responsible for calling @code{blink-paren-function} when the inserted
522 character has close parenthesis syntax (@pxref{Blinking}).
524 @vindex post-self-insert-hook
525 The final thing this command does is to run the hook
526 @code{post-self-insert-hook}. You could use this to automatically
527 reindent text as it is typed, for example.
529 Do not try substituting your own definition of
530 @code{self-insert-command} for the standard one. The editor command
531 loop handles this function specially.
534 @deffn Command newline &optional number-of-newlines
535 This command inserts newlines into the current buffer before point.
536 If @var{number-of-newlines} is supplied, that many newline characters
539 @cindex newline and Auto Fill mode
540 This function calls @code{auto-fill-function} if the current column
541 number is greater than the value of @code{fill-column} and
542 @var{number-of-newlines} is @code{nil}. Typically what
543 @code{auto-fill-function} does is insert a newline; thus, the overall
544 result in this case is to insert two newlines at different places: one
545 at point, and another earlier in the line. @code{newline} does not
546 auto-fill if @var{number-of-newlines} is non-@code{nil}.
548 This command indents to the left margin if that is not zero.
551 The value returned is @code{nil}. In an interactive call, @var{count}
552 is the numeric prefix argument.
555 @defvar overwrite-mode
556 This variable controls whether overwrite mode is in effect. The value
557 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
558 or @code{nil}. @code{overwrite-mode-textual} specifies textual
559 overwrite mode (treats newlines and tabs specially), and
560 @code{overwrite-mode-binary} specifies binary overwrite mode (treats
561 newlines and tabs like any other characters).
565 @section Deleting Text
566 @cindex text deletion
568 @cindex deleting text vs killing
569 Deletion means removing part of the text in a buffer, without saving
570 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
571 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
572 Some deletion functions do save text in the kill ring in some special
575 All of the deletion functions operate on the current buffer.
577 @deffn Command erase-buffer
578 This function deletes the entire text of the current buffer
579 (@emph{not} just the accessible portion), leaving it
580 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
581 error; if some of the text in it is read-only, it signals a
582 @code{text-read-only} error. Otherwise, it deletes the text without
583 asking for any confirmation. It returns @code{nil}.
585 Normally, deleting a large amount of text from a buffer inhibits further
586 auto-saving of that buffer because it has shrunk. However,
587 @code{erase-buffer} does not do this, the idea being that the future
588 text is not really related to the former text, and its size should not
589 be compared with that of the former text.
592 @deffn Command delete-region start end
593 This command deletes the text between positions @var{start} and
594 @var{end} in the current buffer, and returns @code{nil}. If point was
595 inside the deleted region, its value afterward is @var{start}.
596 Otherwise, point relocates with the surrounding text, as markers do.
599 @defun delete-and-extract-region start end
600 This function deletes the text between positions @var{start} and
601 @var{end} in the current buffer, and returns a string containing the
604 If point was inside the deleted region, its value afterward is
605 @var{start}. Otherwise, point relocates with the surrounding text, as
609 @deffn Command delete-char count &optional killp
610 This command deletes @var{count} characters directly after point, or
611 before point if @var{count} is negative. If @var{killp} is
612 non-@code{nil}, then it saves the deleted characters in the kill ring.
614 In an interactive call, @var{count} is the numeric prefix argument, and
615 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
616 argument is supplied, the text is saved in the kill ring. If no prefix
617 argument is supplied, then one character is deleted, but not saved in
620 The value returned is always @code{nil}.
623 @deffn Command delete-backward-char count &optional killp
624 @cindex deleting previous char
625 This command deletes @var{count} characters directly before point, or
626 after point if @var{count} is negative. If @var{killp} is
627 non-@code{nil}, then it saves the deleted characters in the kill ring.
629 In an interactive call, @var{count} is the numeric prefix argument, and
630 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
631 argument is supplied, the text is saved in the kill ring. If no prefix
632 argument is supplied, then one character is deleted, but not saved in
635 The value returned is always @code{nil}.
638 @deffn Command backward-delete-char-untabify count &optional killp
640 This command deletes @var{count} characters backward, changing tabs
641 into spaces. When the next character to be deleted is a tab, it is
642 first replaced with the proper number of spaces to preserve alignment
643 and then one of those spaces is deleted instead of the tab. If
644 @var{killp} is non-@code{nil}, then the command saves the deleted
645 characters in the kill ring.
647 Conversion of tabs to spaces happens only if @var{count} is positive.
648 If it is negative, exactly @minus{}@var{count} characters after point
651 In an interactive call, @var{count} is the numeric prefix argument, and
652 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
653 argument is supplied, the text is saved in the kill ring. If no prefix
654 argument is supplied, then one character is deleted, but not saved in
657 The value returned is always @code{nil}.
660 @defopt backward-delete-char-untabify-method
661 This option specifies how @code{backward-delete-char-untabify} should
662 deal with whitespace. Possible values include @code{untabify}, the
663 default, meaning convert a tab to many spaces and delete one;
664 @code{hungry}, meaning delete all tabs and spaces before point with
665 one command; @code{all} meaning delete all tabs, spaces and newlines
666 before point, and @code{nil}, meaning do nothing special for
667 whitespace characters.
670 @node User-Level Deletion
671 @section User-Level Deletion Commands
673 This section describes higher-level commands for deleting text,
674 commands intended primarily for the user but useful also in Lisp
677 @deffn Command delete-horizontal-space &optional backward-only
678 @cindex deleting whitespace
679 This function deletes all spaces and tabs around point. It returns
682 If @var{backward-only} is non-@code{nil}, the function deletes
683 spaces and tabs before point, but not after point.
685 In the following examples, we call @code{delete-horizontal-space} four
686 times, once on each line, with point between the second and third
687 characters on the line each time.
691 ---------- Buffer: foo ----------
696 ---------- Buffer: foo ----------
700 (delete-horizontal-space) ; @r{Four times.}
703 ---------- Buffer: foo ----------
708 ---------- Buffer: foo ----------
713 @deffn Command delete-indentation &optional join-following-p
714 This function joins the line point is on to the previous line, deleting
715 any whitespace at the join and in some cases replacing it with one
716 space. If @var{join-following-p} is non-@code{nil},
717 @code{delete-indentation} joins this line to the following line
718 instead. The function returns @code{nil}.
720 If there is a fill prefix, and the second of the lines being joined
721 starts with the prefix, then @code{delete-indentation} deletes the
722 fill prefix before joining the lines. @xref{Margins}.
724 In the example below, point is located on the line starting
725 @samp{events}, and it makes no difference if there are trailing spaces
726 in the preceding line.
730 ---------- Buffer: foo ----------
731 When in the course of human
732 @point{} events, it becomes necessary
733 ---------- Buffer: foo ----------
740 ---------- Buffer: foo ----------
741 When in the course of human@point{} events, it becomes necessary
742 ---------- Buffer: foo ----------
746 After the lines are joined, the function @code{fixup-whitespace} is
747 responsible for deciding whether to leave a space at the junction.
750 @deffn Command fixup-whitespace
751 This function replaces all the horizontal whitespace surrounding point
752 with either one space or no space, according to the context. It
755 At the beginning or end of a line, the appropriate amount of space is
756 none. Before a character with close parenthesis syntax, or after a
757 character with open parenthesis or expression-prefix syntax, no space is
758 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
761 In the example below, @code{fixup-whitespace} is called the first time
762 with point before the word @samp{spaces} in the first line. For the
763 second invocation, point is directly after the @samp{(}.
767 ---------- Buffer: foo ----------
768 This has too many @point{}spaces
769 This has too many spaces at the start of (@point{} this list)
770 ---------- Buffer: foo ----------
781 ---------- Buffer: foo ----------
782 This has too many spaces
783 This has too many spaces at the start of (this list)
784 ---------- Buffer: foo ----------
789 @deffn Command just-one-space &optional n
790 @comment !!SourceFile simple.el
791 This command replaces any spaces and tabs around point with a single
792 space, or @var{n} spaces if @var{n} is specified. It returns
796 @c There is also cycle-spacing, but I cannot see it being useful in
797 @c Lisp programs, so it is not mentioned here.
799 @deffn Command delete-blank-lines
800 This function deletes blank lines surrounding point. If point is on a
801 blank line with one or more blank lines before or after it, then all but
802 one of them are deleted. If point is on an isolated blank line, then it
803 is deleted. If point is on a nonblank line, the command deletes all
804 blank lines immediately following it.
806 A blank line is defined as a line containing only tabs and spaces.
807 @c and the Newline character?
809 @code{delete-blank-lines} returns @code{nil}.
812 @deffn Command delete-trailing-whitespace &optional start end
813 Delete trailing whitespace in the region defined by @var{start} and
816 This command deletes whitespace characters after the last
817 non-whitespace character in each line in the region.
819 If this command acts on the entire buffer (i.e., if called
820 interactively with the mark inactive, or called from Lisp with
821 @var{end} @code{nil}), it also deletes all trailing lines at the end of the
822 buffer if the variable @code{delete-trailing-lines} is non-@code{nil}.
826 @section The Kill Ring
829 @dfn{Kill functions} delete text like the deletion functions, but save
830 it so that the user can reinsert it by @dfn{yanking}. Most of these
831 functions have @samp{kill-} in their name. By contrast, the functions
832 whose names start with @samp{delete-} normally do not save text for
833 yanking (though they can still be undone); these are deletion
836 Most of the kill commands are primarily for interactive use, and are
837 not described here. What we do describe are the functions provided for
838 use in writing such commands. You can use these functions to write
839 commands for killing text. When you need to delete text for internal
840 purposes within a Lisp function, you should normally use deletion
841 functions, so as not to disturb the kill ring contents.
844 Killed text is saved for later yanking in the @dfn{kill ring}. This
845 is a list that holds a number of recent kills, not just the last text
846 kill. We call this a ``ring'' because yanking treats it as having
847 elements in a cyclic order. The list is kept in the variable
848 @code{kill-ring}, and can be operated on with the usual functions for
849 lists; there are also specialized functions, described in this section,
850 that treat it as a ring.
852 Some people think this use of the word ``kill'' is unfortunate, since
853 it refers to operations that specifically @emph{do not} destroy the
854 entities killed. This is in sharp contrast to ordinary life, in
855 which death is permanent and killed entities do not come back to
856 life. Therefore, other metaphors have been proposed. For example, the
857 term ``cut ring'' makes sense to people who, in pre-computer days, used
858 scissors and paste to cut up and rearrange manuscripts. However, it
859 would be difficult to change the terminology now.
862 * Kill Ring Concepts:: What text looks like in the kill ring.
863 * Kill Functions:: Functions that kill text.
864 * Yanking:: How yanking is done.
865 * Yank Commands:: Commands that access the kill ring.
866 * Low-Level Kill Ring:: Functions and variables for kill ring access.
867 * Internals of Kill Ring:: Variables that hold kill ring data.
870 @node Kill Ring Concepts
871 @subsection Kill Ring Concepts
873 The kill ring records killed text as strings in a list, most recent
874 first. A short kill ring, for example, might look like this:
877 ("some text" "a different piece of text" "even older text")
881 When the list reaches @code{kill-ring-max} entries in length, adding a
882 new entry automatically deletes the last entry.
884 When kill commands are interwoven with other commands, each kill
885 command makes a new entry in the kill ring. Multiple kill commands in
886 succession build up a single kill ring entry, which would be yanked as a
887 unit; the second and subsequent consecutive kill commands add text to
888 the entry made by the first one.
890 For yanking, one entry in the kill ring is designated the front of
891 the ring. Some yank commands rotate the ring by designating a
892 different element as the front. But this virtual rotation doesn't
893 change the list itself---the most recent entry always comes first in the
897 @subsection Functions for Killing
899 @code{kill-region} is the usual subroutine for killing text. Any
900 command that calls this function is a kill command (and should
901 probably have @samp{kill} in its name). @code{kill-region} puts the
902 newly killed text in a new element at the beginning of the kill ring or
903 adds it to the most recent element. It determines automatically (using
904 @code{last-command}) whether the previous command was a kill command,
905 and if so appends the killed text to the most recent entry.
907 @cindex filtering killed text
908 The commands described below can filter the killed text before they
909 save it in the kill ring. They call @code{filter-buffer-substring}
910 (@pxref{Buffer Contents}) to perform the filtering. By default,
911 there's no filtering, but major and minor modes and hook functions can
912 set up filtering, so that text saved in the kill ring is different
913 from what was in the buffer.
915 @deffn Command kill-region start end &optional region
916 This function kills the stretch of text between @var{start} and
917 @var{end}; but if the optional argument @var{region} is
918 non-@code{nil}, it ignores @var{start} and @var{end}, and kills the
919 text in the current region instead. The text is deleted but saved in
920 the kill ring, along with its text properties. The value is always
923 In an interactive call, @var{start} and @var{end} are point and
924 the mark, and @var{region} is always non-@code{nil}, so the command
925 always kills the text in the current region.
927 If the buffer or text is read-only, @code{kill-region} modifies the kill
928 ring just the same, then signals an error without modifying the buffer.
929 This is convenient because it lets the user use a series of kill
930 commands to copy text from a read-only buffer into the kill ring.
933 @defopt kill-read-only-ok
934 If this option is non-@code{nil}, @code{kill-region} does not signal an
935 error if the buffer or text is read-only. Instead, it simply returns,
936 updating the kill ring but not changing the buffer.
939 @deffn Command copy-region-as-kill start end &optional region
940 This function saves the stretch of text between @var{start} and
941 @var{end} on the kill ring (including text properties), but does not
942 delete the text from the buffer. However, if the optional argument
943 @var{region} is non-@code{nil}, the function ignores @var{start} and
944 @var{end}, and saves the current region instead. It always returns
947 In an interactive call, @var{start} and @var{end} are point and
948 the mark, and @var{region} is always non-@code{nil}, so the command
949 always saves the text in the current region.
951 The command does not set @code{this-command} to @code{kill-region}, so a
952 subsequent kill command does not append to the same kill ring entry.
958 Yanking means inserting text from the kill ring, but it does not
959 insert the text blindly. The @code{yank} command, and related
960 commands, use @code{insert-for-yank} to perform special processing on
961 the text before it is inserted.
963 @defun insert-for-yank string
964 This function works like @code{insert}, except that it processes the
965 text in @var{string} according to the @code{yank-handler} text
966 property, as well as the variables @code{yank-handled-properties} and
967 @code{yank-excluded-properties} (see below), before inserting the
968 result into the current buffer.
971 @defun insert-buffer-substring-as-yank buf &optional start end
972 This function resembles @code{insert-buffer-substring}, except that it
973 processes the text according to @code{yank-handled-properties} and
974 @code{yank-excluded-properties}. (It does not handle the
975 @code{yank-handler} property, which does not normally occur in buffer
979 @c FIXME: Add an index for yank-handler.
980 If you put a @code{yank-handler} text property on all or part of a
981 string, that alters how @code{insert-for-yank} inserts the string. If
982 different parts of the string have different @code{yank-handler}
983 values (comparison being done with @code{eq}), each substring is
984 handled separately. The property value must be a list of one to four
985 elements, with the following format (where elements after the first
989 (@var{function} @var{param} @var{noexclude} @var{undo})
992 Here is what the elements do:
996 When @var{function} is non-@code{nil}, it is called instead of
997 @code{insert} to insert the string, with one argument---the string to
1001 If @var{param} is present and non-@code{nil}, it replaces @var{string}
1002 (or the substring of @var{string} being processed) as the object
1003 passed to @var{function} (or @code{insert}). For example, if
1004 @var{function} is @code{yank-rectangle}, @var{param} should be a list
1005 of strings to insert as a rectangle.
1008 If @var{noexclude} is present and non-@code{nil}, that disables the
1009 normal action of @code{yank-handled-properties} and
1010 @code{yank-excluded-properties} on the inserted string.
1013 If @var{undo} is present and non-@code{nil}, it is a function that will be
1014 called by @code{yank-pop} to undo the insertion of the current object.
1015 It is called with two arguments, the start and end of the current
1016 region. @var{function} can set @code{yank-undo-function} to override
1017 the @var{undo} value.
1020 @cindex yanking and text properties
1021 @defopt yank-handled-properties
1022 This variable specifies special text property handling conditions for
1023 yanked text. It takes effect after the text has been inserted (either
1024 normally, or via the @code{yank-handler} property), and prior to
1025 @code{yank-excluded-properties} taking effect.
1027 The value should be an alist of elements @code{(@var{prop}
1028 . @var{fun})}. Each alist element is handled in order. The inserted
1029 text is scanned for stretches of text having text properties @code{eq}
1030 to @var{prop}; for each such stretch, @var{fun} is called with three
1031 arguments: the value of the property, and the start and end positions
1035 @defopt yank-excluded-properties
1036 The value of this variable is the list of properties to remove from
1037 inserted text. Its default value contains properties that might lead
1038 to annoying results, such as causing the text to respond to the mouse
1039 or specifying key bindings. It takes effect after
1040 @code{yank-handled-properties}.
1045 @subsection Functions for Yanking
1047 This section describes higher-level commands for yanking, which are
1048 intended primarily for the user but useful also in Lisp programs.
1049 Both @code{yank} and @code{yank-pop} honor the
1050 @code{yank-excluded-properties} variable and @code{yank-handler} text
1051 property (@pxref{Yanking}).
1053 @deffn Command yank &optional arg
1054 @cindex inserting killed text
1055 This command inserts before point the text at the front of the kill
1056 ring. It sets the mark at the beginning of that text, using
1057 @code{push-mark} (@pxref{The Mark}), and puts point at the end.
1059 If @var{arg} is a non-@code{nil} list (which occurs interactively when
1060 the user types @kbd{C-u} with no digits), then @code{yank} inserts the
1061 text as described above, but puts point before the yanked text and
1062 sets the mark after it.
1064 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th
1065 most recently killed text---the @var{arg}th element of the kill ring
1066 list, counted cyclically from the front, which is considered the
1067 first element for this purpose.
1069 @code{yank} does not alter the contents of the kill ring, unless it
1070 used text provided by another program, in which case it pushes that text
1071 onto the kill ring. However if @var{arg} is an integer different from
1072 one, it rotates the kill ring to place the yanked string at the front.
1074 @code{yank} returns @code{nil}.
1077 @deffn Command yank-pop &optional arg
1078 This command replaces the just-yanked entry from the kill ring with a
1079 different entry from the kill ring.
1081 This is allowed only immediately after a @code{yank} or another
1082 @code{yank-pop}. At such a time, the region contains text that was just
1083 inserted by yanking. @code{yank-pop} deletes that text and inserts in
1084 its place a different piece of killed text. It does not add the deleted
1085 text to the kill ring, since it is already in the kill ring somewhere.
1086 It does however rotate the kill ring to place the newly yanked string at
1089 If @var{arg} is @code{nil}, then the replacement text is the previous
1090 element of the kill ring. If @var{arg} is numeric, the replacement is
1091 the @var{arg}th previous kill. If @var{arg} is negative, a more recent
1092 kill is the replacement.
1094 The sequence of kills in the kill ring wraps around, so that after the
1095 oldest one comes the newest one, and before the newest one goes the
1098 The return value is always @code{nil}.
1101 @defvar yank-undo-function
1102 If this variable is non-@code{nil}, the function @code{yank-pop} uses
1103 its value instead of @code{delete-region} to delete the text
1104 inserted by the previous @code{yank} or
1105 @code{yank-pop} command. The value must be a function of two
1106 arguments, the start and end of the current region.
1108 The function @code{insert-for-yank} automatically sets this variable
1109 according to the @var{undo} element of the @code{yank-handler}
1110 text property, if there is one.
1113 @node Low-Level Kill Ring
1114 @subsection Low-Level Kill Ring
1116 These functions and variables provide access to the kill ring at a
1117 lower level, but are still convenient for use in Lisp programs,
1118 because they take care of interaction with window system selections
1119 (@pxref{Window System Selections}).
1121 @defun current-kill n &optional do-not-move
1122 The function @code{current-kill} rotates the yanking pointer, which
1123 designates the front of the kill ring, by @var{n} places (from newer
1124 kills to older ones), and returns the text at that place in the ring.
1126 If the optional second argument @var{do-not-move} is non-@code{nil},
1127 then @code{current-kill} doesn't alter the yanking pointer; it just
1128 returns the @var{n}th kill, counting from the current yanking pointer.
1130 If @var{n} is zero, indicating a request for the latest kill,
1131 @code{current-kill} calls the value of
1132 @code{interprogram-paste-function} (documented below) before
1133 consulting the kill ring. If that value is a function and calling it
1134 returns a string or a list of several string, @code{current-kill}
1135 pushes the strings onto the kill ring and returns the first string.
1136 It also sets the yanking pointer to point to the kill-ring entry of
1137 the first string returned by @code{interprogram-paste-function},
1138 regardless of the value of @var{do-not-move}. Otherwise,
1139 @code{current-kill} does not treat a zero value for @var{n} specially:
1140 it returns the entry pointed at by the yanking pointer and does not
1141 move the yanking pointer.
1144 @defun kill-new string &optional replace
1145 This function pushes the text @var{string} onto the kill ring and
1146 makes the yanking pointer point to it. It discards the oldest entry
1147 if appropriate. It also invokes the value of
1148 @code{interprogram-cut-function} (see below).
1150 If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the
1151 first element of the kill ring with @var{string}, rather than pushing
1152 @var{string} onto the kill ring.
1155 @defun kill-append string before-p
1156 This function appends the text @var{string} to the first entry in the
1157 kill ring and makes the yanking pointer point to the combined entry.
1158 Normally @var{string} goes at the end of the entry, but if
1159 @var{before-p} is non-@code{nil}, it goes at the beginning. This
1160 function also invokes the value of @code{interprogram-cut-function}
1164 @defvar interprogram-paste-function
1165 This variable provides a way of transferring killed text from other
1166 programs, when you are using a window system. Its value should be
1167 @code{nil} or a function of no arguments.
1169 If the value is a function, @code{current-kill} calls it to get the
1170 most recent kill. If the function returns a non-@code{nil} value,
1171 then that value is used as the most recent kill. If it returns
1172 @code{nil}, then the front of the kill ring is used.
1174 To facilitate support for window systems that support multiple
1175 selections, this function may also return a list of strings. In that
1176 case, the first string is used as the most recent kill, and all
1177 the other strings are pushed onto the kill ring, for easy access by
1180 The normal use of this function is to get the window system's
1181 clipboard as the most recent kill, even if the selection belongs to
1182 another application. @xref{Window System Selections}. However, if
1183 the clipboard contents come from the current Emacs session, this
1184 function should return @code{nil}.
1187 @defvar interprogram-cut-function
1188 This variable provides a way of communicating killed text to other
1189 programs, when you are using a window system. Its value should be
1190 @code{nil} or a function of one required argument.
1192 If the value is a function, @code{kill-new} and @code{kill-append} call
1193 it with the new first element of the kill ring as the argument.
1195 The normal use of this function is to put newly killed text in the
1196 window system's clipboard. @xref{Window System Selections}.
1199 @node Internals of Kill Ring
1200 @subsection Internals of the Kill Ring
1202 The variable @code{kill-ring} holds the kill ring contents, in the
1203 form of a list of strings. The most recent kill is always at the front
1206 The @code{kill-ring-yank-pointer} variable points to a link in the
1207 kill ring list, whose @sc{car} is the text to yank next. We say it
1208 identifies the front of the ring. Moving
1209 @code{kill-ring-yank-pointer} to a different link is called
1210 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
1211 the functions that move the yank pointer wrap around from the end of the
1212 list to the beginning, or vice-versa. Rotation of the kill ring is
1213 virtual; it does not change the value of @code{kill-ring}.
1215 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
1216 variables whose values are normally lists. The word ``pointer'' in the
1217 name of the @code{kill-ring-yank-pointer} indicates that the variable's
1218 purpose is to identify one element of the list for use by the next yank
1221 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
1222 of the links in the kill ring list. The element it identifies is the
1223 @sc{car} of that link. Kill commands, which change the kill ring, also
1224 set this variable to the value of @code{kill-ring}. The effect is to
1225 rotate the ring so that the newly killed text is at the front.
1227 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
1228 pointing to the second entry in the kill ring @code{("some text" "a
1229 different piece of text" "yet older text")}.
1233 kill-ring ---- kill-ring-yank-pointer
1236 | --- --- --- --- --- ---
1237 --> | | |------> | | |--> | | |--> nil
1238 --- --- --- --- --- ---
1241 | | -->"yet older text"
1243 | --> "a different piece of text"
1250 This state of affairs might occur after @kbd{C-y} (@code{yank})
1251 immediately followed by @kbd{M-y} (@code{yank-pop}).
1254 This variable holds the list of killed text sequences, most recently
1258 @defvar kill-ring-yank-pointer
1259 This variable's value indicates which element of the kill ring is at the
1260 front of the ring for yanking. More precisely, the value is a tail
1261 of the value of @code{kill-ring}, and its @sc{car} is the kill string
1262 that @kbd{C-y} should yank.
1265 @defopt kill-ring-max
1266 The value of this variable is the maximum length to which the kill
1267 ring can grow, before elements are thrown away at the end. The default
1268 value for @code{kill-ring-max} is 60.
1275 Most buffers have an @dfn{undo list}, which records all changes made
1276 to the buffer's text so that they can be undone. (The buffers that
1277 don't have one are usually special-purpose buffers for which Emacs
1278 assumes that undoing is not useful. In particular, any buffer whose
1279 name begins with a space has its undo recording off by default;
1280 see @ref{Buffer Names}.) All the primitives that modify the
1281 text in the buffer automatically add elements to the front of the undo
1282 list, which is in the variable @code{buffer-undo-list}.
1284 @defvar buffer-undo-list
1285 This buffer-local variable's value is the undo list of the current
1286 buffer. A value of @code{t} disables the recording of undo information.
1289 Here are the kinds of elements an undo list can have:
1292 @item @var{position}
1293 This kind of element records a previous value of point; undoing this
1294 element moves point to @var{position}. Ordinary cursor motion does not
1295 make any sort of undo record, but deletion operations use these entries
1296 to record where point was before the command.
1298 @item (@var{beg} . @var{end})
1299 This kind of element indicates how to delete text that was inserted.
1300 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
1303 @item (@var{text} . @var{position})
1304 This kind of element indicates how to reinsert text that was deleted.
1305 The deleted text itself is the string @var{text}. The place to
1306 reinsert it is @code{(abs @var{position})}. If @var{position} is
1307 positive, point was at the beginning of the deleted text, otherwise it
1308 was at the end. Zero or more (@var{marker} . @var{adjustment})
1309 elements follow immediately after this element.
1311 @item (t . @var{time-flag})
1312 This kind of element indicates that an unmodified buffer became
1313 modified. A @var{time-flag} of the form
1314 @code{(@var{sec-high} @var{sec-low} @var{microsec}
1315 @var{picosec})} represents the visited file's modification time as of
1316 when it was previously visited or saved, using the same format as
1317 @code{current-time}; see @ref{Time of Day}.
1318 A @var{time-flag} of 0 means the buffer does not correspond to any file;
1319 @minus{}1 means the visited file previously did not exist.
1320 @code{primitive-undo} uses these
1321 values to determine whether to mark the buffer as unmodified once again;
1322 it does so only if the file's status matches that of @var{time-flag}.
1324 @item (nil @var{property} @var{value} @var{beg} . @var{end})
1325 This kind of element records a change in a text property.
1326 Here's how you might undo the change:
1329 (put-text-property @var{beg} @var{end} @var{property} @var{value})
1332 @item (@var{marker} . @var{adjustment})
1333 This kind of element records the fact that the marker @var{marker} was
1334 relocated due to deletion of surrounding text, and that it moved
1335 @var{adjustment} character positions. If the marker's location is
1336 consistent with the (@var{text} . @var{position}) element preceding it
1337 in the undo list, then undoing this element moves @var{marker}
1338 @minus{} @var{adjustment} characters.
1340 @item (apply @var{funname} . @var{args})
1341 This is an extensible undo item, which is undone by calling
1342 @var{funname} with arguments @var{args}.
1344 @item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
1345 This is an extensible undo item, which records a change limited to the
1346 range @var{beg} to @var{end}, which increased the size of the buffer
1347 by @var{delta} characters. It is undone by calling @var{funname} with
1348 arguments @var{args}.
1350 This kind of element enables undo limited to a region to determine
1351 whether the element pertains to that region.
1354 This element is a boundary. The elements between two boundaries are
1355 called a @dfn{change group}; normally, each change group corresponds to
1356 one keyboard command, and undo commands normally undo an entire group as
1360 @defun undo-boundary
1361 This function places a boundary element in the undo list. The undo
1362 command stops at such a boundary, and successive undo commands undo
1363 to earlier and earlier boundaries. This function returns @code{nil}.
1365 Calling this function explicitly is useful for splitting the effects of
1366 a command into more than one unit. For example, @code{query-replace}
1367 calls @code{undo-boundary} after each replacement, so that the user can
1368 undo individual replacements one by one.
1370 Mostly, however, this function is called automatically at an
1374 @defun undo-auto-amalgamate
1375 @cindex amalgamating commands, and undo
1376 The editor command loop automatically calls @code{undo-boundary} just
1377 before executing each key sequence, so that each undo normally undoes
1378 the effects of one command. A few exceptional commands are
1379 @dfn{amalgamating}: these commands generally cause small changes to
1380 buffers, so with these a boundary is inserted only every 20th command,
1381 allowing the changes to be undone as a group. By default, the commands
1382 @code{self-insert-command}, which produces self-inserting input
1383 characters (@pxref{Commands for Insertion}), and @code{delete-char},
1384 which deletes characters (@pxref{Deletion}), are amalgamating.
1385 Where a command affects the contents of several buffers, as may happen,
1386 for example, when a function on the @code{post-command-hook} affects a
1387 buffer other than the @code{current-buffer}, then @code{undo-boundary}
1388 will be called in each of the affected buffers.
1391 @defvar undo-auto-current-boundary-timer
1392 Some buffers, such as process buffers, can change even when no
1393 commands are executing. In these cases, @code{undo-boundary} is
1394 normally called periodically by the timer in this variable. Setting
1395 this variable to non-@code{nil} prevents this behavior.
1398 @defvar undo-in-progress
1399 This variable is normally @code{nil}, but the undo commands bind it to
1400 @code{t}. This is so that various kinds of change hooks can tell when
1401 they're being called for the sake of undoing.
1404 @defun primitive-undo count list
1405 This is the basic function for undoing elements of an undo list.
1406 It undoes the first @var{count} elements of @var{list}, returning
1407 the rest of @var{list}.
1409 @code{primitive-undo} adds elements to the buffer's undo list when it
1410 changes the buffer. Undo commands avoid confusion by saving the undo
1411 list value at the beginning of a sequence of undo operations. Then the
1412 undo operations use and update the saved value. The new elements added
1413 by undoing are not part of this saved value, so they don't interfere with
1416 This function does not bind @code{undo-in-progress}.
1419 @node Maintaining Undo
1420 @section Maintaining Undo Lists
1422 This section describes how to enable and disable undo information for
1423 a given buffer. It also explains how the undo list is truncated
1424 automatically so it doesn't get too big.
1426 Recording of undo information in a newly created buffer is normally
1427 enabled to start with; but if the buffer name starts with a space, the
1428 undo recording is initially disabled. You can explicitly enable or
1429 disable undo recording with the following two functions, or by setting
1430 @code{buffer-undo-list} yourself.
1432 @deffn Command buffer-enable-undo &optional buffer-or-name
1433 This command enables recording undo information for buffer
1434 @var{buffer-or-name}, so that subsequent changes can be undone. If no
1435 argument is supplied, then the current buffer is used. This function
1436 does nothing if undo recording is already enabled in the buffer. It
1439 In an interactive call, @var{buffer-or-name} is the current buffer.
1440 You cannot specify any other buffer.
1443 @deffn Command buffer-disable-undo &optional buffer-or-name
1444 @cindex disabling undo
1445 This function discards the undo list of @var{buffer-or-name}, and disables
1446 further recording of undo information. As a result, it is no longer
1447 possible to undo either previous changes or any subsequent changes. If
1448 the undo list of @var{buffer-or-name} is already disabled, this function
1451 In an interactive call, BUFFER-OR-NAME is the current buffer. You
1452 cannot specify any other buffer. This function returns @code{nil}.
1455 As editing continues, undo lists get longer and longer. To prevent
1456 them from using up all available memory space, garbage collection trims
1457 them back to size limits you can set. (For this purpose, the size
1458 of an undo list measures the cons cells that make up the list, plus the
1459 strings of deleted text.) Three variables control the range of acceptable
1460 sizes: @code{undo-limit}, @code{undo-strong-limit} and
1461 @code{undo-outer-limit}. In these variables, size is counted as the
1462 number of bytes occupied, which includes both saved text and other
1466 This is the soft limit for the acceptable size of an undo list. The
1467 change group at which this size is exceeded is the last one kept.
1470 @defopt undo-strong-limit
1471 This is the upper limit for the acceptable size of an undo list. The
1472 change group at which this size is exceeded is discarded itself (along
1473 with all older change groups). There is one exception: the very latest
1474 change group is only discarded if it exceeds @code{undo-outer-limit}.
1477 @defopt undo-outer-limit
1478 If at garbage collection time the undo info for the current command
1479 exceeds this limit, Emacs discards the info and displays a warning.
1480 This is a last ditch limit to prevent memory overflow.
1483 @defopt undo-ask-before-discard
1484 If this variable is non-@code{nil}, when the undo info exceeds
1485 @code{undo-outer-limit}, Emacs asks in the echo area whether to
1486 discard the info. The default value is @code{nil}, which means to
1487 discard it automatically.
1489 This option is mainly intended for debugging. Garbage collection is
1490 inhibited while the question is asked, which means that Emacs might
1491 leak memory if the user waits too long before answering the question.
1496 @cindex filling text
1498 @dfn{Filling} means adjusting the lengths of lines (by moving the line
1499 breaks) so that they are nearly (but no greater than) a specified
1500 maximum width. Additionally, lines can be @dfn{justified}, which means
1501 inserting spaces to make the left and/or right margins line up
1502 precisely. The width is controlled by the variable @code{fill-column}.
1503 For ease of reading, lines should be no longer than 70 or so columns.
1505 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1506 automatically as you insert it, but changes to existing text may leave
1507 it improperly filled. Then you must fill the text explicitly.
1509 Most of the commands in this section return values that are not
1510 meaningful. All the functions that do filling take note of the current
1511 left margin, current right margin, and current justification style
1512 (@pxref{Margins}). If the current justification style is
1513 @code{none}, the filling functions don't actually do anything.
1515 Several of the filling functions have an argument @var{justify}.
1516 If it is non-@code{nil}, that requests some kind of justification. It
1517 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
1518 request a specific style of justification. If it is @code{t}, that
1519 means to use the current justification style for this part of the text
1520 (see @code{current-justification}, below). Any other value is treated
1523 When you call the filling functions interactively, using a prefix
1524 argument implies the value @code{full} for @var{justify}.
1526 @deffn Command fill-paragraph &optional justify region
1527 This command fills the paragraph at or after point. If
1528 @var{justify} is non-@code{nil}, each line is justified as well.
1529 It uses the ordinary paragraph motion commands to find paragraph
1530 boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
1532 When @var{region} is non-@code{nil}, then if Transient Mark mode is
1533 enabled and the mark is active, this command calls @code{fill-region}
1534 to fill all the paragraphs in the region, instead of filling only the
1535 current paragraph. When this command is called interactively,
1536 @var{region} is @code{t}.
1539 @deffn Command fill-region start end &optional justify nosqueeze to-eop
1540 This command fills each of the paragraphs in the region from @var{start}
1541 to @var{end}. It justifies as well if @var{justify} is
1544 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1545 other than line breaks untouched. If @var{to-eop} is non-@code{nil},
1546 that means to keep filling to the end of the paragraph---or the next hard
1547 newline, if @code{use-hard-newlines} is enabled (see below).
1549 The variable @code{paragraph-separate} controls how to distinguish
1550 paragraphs. @xref{Standard Regexps}.
1553 @deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
1554 This command fills each paragraph in the region according to its
1555 individual fill prefix. Thus, if the lines of a paragraph were indented
1556 with spaces, the filled paragraph will remain indented in the same
1559 The first two arguments, @var{start} and @var{end}, are the beginning
1560 and end of the region to be filled. The third and fourth arguments,
1561 @var{justify} and @var{citation-regexp}, are optional. If
1562 @var{justify} is non-@code{nil}, the paragraphs are justified as
1563 well as filled. If @var{citation-regexp} is non-@code{nil}, it means the
1564 function is operating on a mail message and therefore should not fill
1565 the header lines. If @var{citation-regexp} is a string, it is used as
1566 a regular expression; if it matches the beginning of a line, that line
1567 is treated as a citation marker.
1569 @c FIXME: "That mode" is confusing. It isn't a major/minor mode.
1570 Ordinarily, @code{fill-individual-paragraphs} regards each change in
1571 indentation as starting a new paragraph. If
1572 @code{fill-individual-varying-indent} is non-@code{nil}, then only
1573 separator lines separate paragraphs. That mode can handle indented
1574 paragraphs with additional indentation on the first line.
1577 @defopt fill-individual-varying-indent
1578 This variable alters the action of @code{fill-individual-paragraphs} as
1582 @deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
1583 This command considers a region of text as a single paragraph and fills
1584 it. If the region was made up of many paragraphs, the blank lines
1585 between paragraphs are removed. This function justifies as well as
1586 filling when @var{justify} is non-@code{nil}.
1588 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1589 other than line breaks untouched. If @var{squeeze-after} is
1590 non-@code{nil}, it specifies a position in the region, and means don't
1591 canonicalize spaces before that position.
1593 In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
1594 choose a fill prefix by default. @xref{Adaptive Fill}.
1597 @deffn Command justify-current-line &optional how eop nosqueeze
1598 This command inserts spaces between the words of the current line so
1599 that the line ends exactly at @code{fill-column}. It returns
1602 The argument @var{how}, if non-@code{nil} specifies explicitly the style
1603 of justification. It can be @code{left}, @code{right}, @code{full},
1604 @code{center}, or @code{none}. If it is @code{t}, that means to do
1605 follow specified justification style (see @code{current-justification},
1606 below). @code{nil} means to do full justification.
1608 If @var{eop} is non-@code{nil}, that means do only left-justification
1609 if @code{current-justification} specifies full justification. This is
1610 used for the last line of a paragraph; even if the paragraph as a
1611 whole is fully justified, the last line should not be.
1613 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1617 @defopt default-justification
1618 This variable's value specifies the style of justification to use for
1619 text that doesn't specify a style with a text property. The possible
1620 values are @code{left}, @code{right}, @code{full}, @code{center}, or
1621 @code{none}. The default value is @code{left}.
1624 @defun current-justification
1625 This function returns the proper justification style to use for filling
1626 the text around point.
1628 This returns the value of the @code{justification} text property at
1629 point, or the variable @var{default-justification} if there is no such
1630 text property. However, it returns @code{nil} rather than @code{none}
1631 to mean ``don't justify''.
1634 @defopt sentence-end-double-space
1635 @anchor{Definition of sentence-end-double-space}
1636 If this variable is non-@code{nil}, a period followed by just one space
1637 does not count as the end of a sentence, and the filling functions
1638 avoid breaking the line at such a place.
1641 @defopt sentence-end-without-period
1642 If this variable is non-@code{nil}, a sentence can end without a
1643 period. This is used for languages like Thai, where sentences end
1644 with a double space but without a period.
1647 @defopt sentence-end-without-space
1648 If this variable is non-@code{nil}, it should be a string of
1649 characters that can end a sentence without following spaces.
1652 @defopt fill-separate-heterogeneous-words-with-space
1653 If this variable is non-@code{nil}, two words of different kind (e.g.,
1654 English and CJK) will be separated with a space when concatenating one
1655 that is in the end of a line and the other that is in the beginning of
1656 the next line for filling.
1659 @defvar fill-paragraph-function
1660 This variable provides a way to override the filling of paragraphs.
1661 If its value is non-@code{nil}, @code{fill-paragraph} calls this
1662 function to do the work. If the function returns a non-@code{nil}
1663 value, @code{fill-paragraph} assumes the job is done, and immediately
1666 The usual use of this feature is to fill comments in programming
1667 language modes. If the function needs to fill a paragraph in the usual
1668 way, it can do so as follows:
1671 (let ((fill-paragraph-function nil))
1672 (fill-paragraph arg))
1676 @defvar fill-forward-paragraph-function
1677 This variable provides a way to override how the filling functions,
1678 such as @code{fill-region} and @code{fill-paragraph}, move forward to
1679 the next paragraph. Its value should be a function, which is called
1680 with a single argument @var{n}, the number of paragraphs to move, and
1681 should return the difference between @var{n} and the number of
1682 paragraphs actually moved. The default value of this variable is
1683 @code{forward-paragraph}. @xref{Paragraphs,,, emacs, The GNU Emacs
1687 @defvar use-hard-newlines
1688 If this variable is non-@code{nil}, the filling functions do not delete
1689 newlines that have the @code{hard} text property. These hard
1690 newlines act as paragraph separators. @xref{Hard and Soft
1691 Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
1695 @section Margins for Filling
1696 @cindex margins, filling
1699 This buffer-local variable, if non-@code{nil}, specifies a string of
1700 text that appears at the beginning of normal text lines and should be
1701 disregarded when filling them. Any line that fails to start with the
1702 fill prefix is considered the start of a paragraph; so is any line
1703 that starts with the fill prefix followed by additional whitespace.
1704 Lines that start with the fill prefix but no additional whitespace are
1705 ordinary text lines that can be filled together. The resulting filled
1706 lines also start with the fill prefix.
1708 The fill prefix follows the left margin whitespace, if any.
1712 This buffer-local variable specifies the maximum width of filled lines.
1713 Its value should be an integer, which is a number of columns. All the
1714 filling, justification, and centering commands are affected by this
1715 variable, including Auto Fill mode (@pxref{Auto Filling}).
1717 As a practical matter, if you are writing text for other people to
1718 read, you should set @code{fill-column} to no more than 70. Otherwise
1719 the line will be too long for people to read comfortably, and this can
1720 make the text seem clumsy.
1722 The default value for @code{fill-column} is 70.
1725 @deffn Command set-left-margin from to margin
1726 This sets the @code{left-margin} property on the text from @var{from} to
1727 @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
1728 command also refills the region to fit the new margin.
1731 @deffn Command set-right-margin from to margin
1732 This sets the @code{right-margin} property on the text from @var{from}
1733 to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
1734 this command also refills the region to fit the new margin.
1737 @defun current-left-margin
1738 This function returns the proper left margin value to use for filling
1739 the text around point. The value is the sum of the @code{left-margin}
1740 property of the character at the start of the current line (or zero if
1741 none), and the value of the variable @code{left-margin}.
1744 @defun current-fill-column
1745 This function returns the proper fill column value to use for filling
1746 the text around point. The value is the value of the @code{fill-column}
1747 variable, minus the value of the @code{right-margin} property of the
1748 character after point.
1751 @deffn Command move-to-left-margin &optional n force
1752 This function moves point to the left margin of the current line. The
1753 column moved to is determined by calling the function
1754 @code{current-left-margin}. If the argument @var{n} is non-@code{nil},
1755 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
1757 If @var{force} is non-@code{nil}, that says to fix the line's
1758 indentation if that doesn't match the left margin value.
1761 @defun delete-to-left-margin &optional from to
1762 This function removes left margin indentation from the text between
1763 @var{from} and @var{to}. The amount of indentation to delete is
1764 determined by calling @code{current-left-margin}. In no case does this
1765 function delete non-whitespace. If @var{from} and @var{to} are omitted,
1766 they default to the whole buffer.
1769 @defun indent-to-left-margin
1770 This function adjusts the indentation at the beginning of the current
1771 line to the value specified by the variable @code{left-margin}. (That
1772 may involve either inserting or deleting whitespace.) This function
1773 is value of @code{indent-line-function} in Paragraph-Indent Text mode.
1777 This variable specifies the base left margin column. In Fundamental
1778 mode, @key{RET} indents to this column. This variable automatically
1779 becomes buffer-local when set in any fashion.
1782 @defopt fill-nobreak-predicate
1783 This variable gives major modes a way to specify not to break a line
1784 at certain places. Its value should be a list of functions. Whenever
1785 filling considers breaking the line at a certain place in the buffer,
1786 it calls each of these functions with no arguments and with point
1787 located at that place. If any of the functions returns
1788 non-@code{nil}, then the line won't be broken there.
1792 @section Adaptive Fill Mode
1793 @c @cindex Adaptive Fill mode "adaptive-fill-mode" is adjacent.
1795 When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill
1796 prefix automatically from the text in each paragraph being filled
1797 rather than using a predetermined value. During filling, this fill
1798 prefix gets inserted at the start of the second and subsequent lines
1799 of the paragraph as described in @ref{Filling}, and in @ref{Auto
1802 @defopt adaptive-fill-mode
1803 Adaptive Fill mode is enabled when this variable is non-@code{nil}.
1804 It is @code{t} by default.
1807 @defun fill-context-prefix from to
1808 This function implements the heart of Adaptive Fill mode; it chooses a
1809 fill prefix based on the text between @var{from} and @var{to},
1810 typically the start and end of a paragraph. It does this by looking
1811 at the first two lines of the paragraph, based on the variables
1813 @c The optional argument first-line-regexp is not documented
1814 @c because it exists for internal purposes and might be eliminated
1817 Usually, this function returns the fill prefix, a string. However,
1818 before doing this, the function makes a final check (not specially
1819 mentioned in the following) that a line starting with this prefix
1820 wouldn't look like the start of a paragraph. Should this happen, the
1821 function signals the anomaly by returning @code{nil} instead.
1823 In detail, @code{fill-context-prefix} does this:
1827 It takes a candidate for the fill prefix from the first line---it
1828 tries first the function in @code{adaptive-fill-function} (if any),
1829 then the regular expression @code{adaptive-fill-regexp} (see below).
1830 The first non-@code{nil} result of these, or the empty string if
1831 they're both @code{nil}, becomes the first line's candidate.
1833 If the paragraph has as yet only one line, the function tests the
1834 validity of the prefix candidate just found. The function then
1835 returns the candidate if it's valid, or a string of spaces otherwise.
1836 (see the description of @code{adaptive-fill-first-line-regexp} below).
1838 When the paragraph already has two lines, the function next looks for
1839 a prefix candidate on the second line, in just the same way it did for
1840 the first line. If it doesn't find one, it returns @code{nil}.
1842 The function now compares the two candidate prefixes heuristically: if
1843 the non-whitespace characters in the line 2 candidate occur in the
1844 same order in the line 1 candidate, the function returns the line 2
1845 candidate. Otherwise, it returns the largest initial substring which
1846 is common to both candidates (which might be the empty string).
1850 @defopt adaptive-fill-regexp
1851 Adaptive Fill mode matches this regular expression against the text
1852 starting after the left margin whitespace (if any) on a line; the
1853 characters it matches are that line's candidate for the fill prefix.
1855 The default value matches whitespace with certain punctuation
1856 characters intermingled.
1859 @defopt adaptive-fill-first-line-regexp
1860 Used only in one-line paragraphs, this regular expression acts as an
1861 additional check of the validity of the one available candidate fill
1862 prefix: the candidate must match this regular expression, or match
1863 @code{comment-start-skip}. If it doesn't, @code{fill-context-prefix}
1864 replaces the candidate with a string of spaces of the same width
1867 The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which
1868 matches only a string of whitespace. The effect of this default is to
1869 force the fill prefixes found in one-line paragraphs always to be pure
1873 @defopt adaptive-fill-function
1874 You can specify more complex ways of choosing a fill prefix
1875 automatically by setting this variable to a function. The function is
1876 called with point after the left margin (if any) of a line, and it
1877 must preserve point. It should return either that line's fill
1878 prefix or @code{nil}, meaning it has failed to determine a prefix.
1882 @section Auto Filling
1883 @cindex filling, automatic
1884 @cindex Auto Fill mode
1886 @c FIXME: I don't think any of the variables below is a/an normal/abnormal hook.
1887 Auto Fill mode is a minor mode that fills lines automatically as text
1888 is inserted. This section describes the hook used by Auto Fill mode.
1889 For a description of functions that you can call explicitly to fill and
1890 justify existing text, see @ref{Filling}.
1892 Auto Fill mode also enables the functions that change the margins and
1893 justification style to refill portions of the text. @xref{Margins}.
1895 @defvar auto-fill-function
1896 The value of this buffer-local variable should be a function (of no
1897 arguments) to be called after self-inserting a character from the table
1898 @code{auto-fill-chars}. It may be @code{nil}, in which case nothing
1899 special is done in that case.
1901 The value of @code{auto-fill-function} is @code{do-auto-fill} when
1902 Auto-Fill mode is enabled. That is a function whose sole purpose is to
1903 implement the usual strategy for breaking a line.
1906 @defvar normal-auto-fill-function
1907 This variable specifies the function to use for
1908 @code{auto-fill-function}, if and when Auto Fill is turned on. Major
1909 modes can set buffer-local values for this variable to alter how Auto
1913 @defvar auto-fill-chars
1914 A char table of characters which invoke @code{auto-fill-function} when
1915 self-inserted---space and newline in most language environments. They
1916 have an entry @code{t} in the table.
1920 @section Sorting Text
1921 @cindex sorting text
1923 The sorting functions described in this section all rearrange text in
1924 a buffer. This is in contrast to the function @code{sort}, which
1925 rearranges the order of the elements of a list (@pxref{Rearrangement}).
1926 The values returned by these functions are not meaningful.
1928 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate
1929 This function is the general text-sorting routine that subdivides a
1930 buffer into records and then sorts them. Most of the commands in this
1931 section use this function.
1933 To understand how @code{sort-subr} works, consider the whole accessible
1934 portion of the buffer as being divided into disjoint pieces called
1935 @dfn{sort records}. The records may or may not be contiguous, but they
1936 must not overlap. A portion of each sort record (perhaps all of it) is
1937 designated as the sort key. Sorting rearranges the records in order by
1940 Usually, the records are rearranged in order of ascending sort key.
1941 If the first argument to the @code{sort-subr} function, @var{reverse},
1942 is non-@code{nil}, the sort records are rearranged in order of
1943 descending sort key.
1945 The next four arguments to @code{sort-subr} are functions that are
1946 called to move point across a sort record. They are called many times
1947 from within @code{sort-subr}.
1951 @var{nextrecfun} is called with point at the end of a record. This
1952 function moves point to the start of the next record. The first record
1953 is assumed to start at the position of point when @code{sort-subr} is
1954 called. Therefore, you should usually move point to the beginning of
1955 the buffer before calling @code{sort-subr}.
1957 This function can indicate there are no more sort records by leaving
1958 point at the end of the buffer.
1961 @var{endrecfun} is called with point within a record. It moves point to
1962 the end of the record.
1965 @var{startkeyfun} is called to move point from the start of a record to
1966 the start of the sort key. This argument is optional; if it is omitted,
1967 the whole record is the sort key. If supplied, the function should
1968 either return a non-@code{nil} value to be used as the sort key, or
1969 return @code{nil} to indicate that the sort key is in the buffer
1970 starting at point. In the latter case, @var{endkeyfun} is called to
1971 find the end of the sort key.
1974 @var{endkeyfun} is called to move point from the start of the sort key
1975 to the end of the sort key. This argument is optional. If
1976 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
1977 @code{nil}), then the sort key extends to the end of the record. There
1978 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1979 non-@code{nil} value.
1982 The argument @var{predicate} is the function to use to compare keys.
1983 If keys are numbers, it defaults to @code{<}; otherwise it defaults to
1986 As an example of @code{sort-subr}, here is the complete function
1987 definition for @code{sort-lines}:
1991 ;; @r{Note that the first two lines of doc string}
1992 ;; @r{are effectively one line when viewed by a user.}
1993 (defun sort-lines (reverse beg end)
1994 "Sort lines in region alphabetically;\
1995 argument means descending order.
1996 Called from a program, there are three arguments:
1999 REVERSE (non-nil means reverse order),\
2000 BEG and END (region to sort).
2001 The variable `sort-fold-case' determines\
2002 whether alphabetic case affects
2006 (interactive "P\nr")
2009 (narrow-to-region beg end)
2010 (goto-char (point-min))
2011 (let ((inhibit-field-text-motion t))
2012 (sort-subr reverse 'forward-line 'end-of-line)))))
2016 Here @code{forward-line} moves point to the start of the next record,
2017 and @code{end-of-line} moves point to the end of record. We do not pass
2018 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
2019 record is used as the sort key.
2021 The @code{sort-paragraphs} function is very much the same, except that
2022 its @code{sort-subr} call looks like this:
2029 (while (and (not (eobp))
2030 (looking-at paragraph-separate))
2036 Markers pointing into any sort records are left with no useful
2037 position after @code{sort-subr} returns.
2040 @defopt sort-fold-case
2041 If this variable is non-@code{nil}, @code{sort-subr} and the other
2042 buffer sorting functions ignore case when comparing strings.
2045 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
2046 This command sorts the region between @var{start} and @var{end}
2047 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
2048 If @var{reverse} is a negative integer, then sorting is in reverse
2051 Alphabetical sorting means that two sort keys are compared by
2052 comparing the first characters of each, the second characters of each,
2053 and so on. If a mismatch is found, it means that the sort keys are
2054 unequal; the sort key whose character is less at the point of first
2055 mismatch is the lesser sort key. The individual characters are compared
2056 according to their numerical character codes in the Emacs character set.
2058 The value of the @var{record-regexp} argument specifies how to divide
2059 the buffer into sort records. At the end of each record, a search is
2060 done for this regular expression, and the text that matches it is taken
2061 as the next record. For example, the regular expression @samp{^.+$},
2062 which matches lines with at least one character besides a newline, would
2063 make each such line into a sort record. @xref{Regular Expressions}, for
2064 a description of the syntax and meaning of regular expressions.
2066 The value of the @var{key-regexp} argument specifies what part of each
2067 record is the sort key. The @var{key-regexp} could match the whole
2068 record, or only a part. In the latter case, the rest of the record has
2069 no effect on the sorted order of records, but it is carried along when
2070 the record moves to its new position.
2072 The @var{key-regexp} argument can refer to the text matched by a
2073 subexpression of @var{record-regexp}, or it can be a regular expression
2076 If @var{key-regexp} is:
2079 @item @samp{\@var{digit}}
2080 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
2081 grouping in @var{record-regexp} is the sort key.
2084 then the whole record is the sort key.
2086 @item a regular expression
2087 then @code{sort-regexp-fields} searches for a match for the regular
2088 expression within the record. If such a match is found, it is the sort
2089 key. If there is no match for @var{key-regexp} within a record then
2090 that record is ignored, which means its position in the buffer is not
2091 changed. (The other records may move around it.)
2094 For example, if you plan to sort all the lines in the region by the
2095 first word on each line starting with the letter @samp{f}, you should
2096 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
2097 @samp{\<f\w*\>}. The resulting expression looks like this:
2101 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
2107 If you call @code{sort-regexp-fields} interactively, it prompts for
2108 @var{record-regexp} and @var{key-regexp} in the minibuffer.
2111 @deffn Command sort-lines reverse start end
2112 This command alphabetically sorts lines in the region between
2113 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2114 is in reverse order.
2117 @deffn Command sort-paragraphs reverse start end
2118 This command alphabetically sorts paragraphs in the region between
2119 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2120 is in reverse order.
2123 @deffn Command sort-pages reverse start end
2124 This command alphabetically sorts pages in the region between
2125 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2126 is in reverse order.
2129 @deffn Command sort-fields field start end
2130 This command sorts lines in the region between @var{start} and
2131 @var{end}, comparing them alphabetically by the @var{field}th field
2132 of each line. Fields are separated by whitespace and numbered starting
2133 from 1. If @var{field} is negative, sorting is by the
2134 @w{@minus{}@var{field}th} field from the end of the line. This command
2135 is useful for sorting tables.
2138 @deffn Command sort-numeric-fields field start end
2139 This command sorts lines in the region between @var{start} and
2140 @var{end}, comparing them numerically by the @var{field}th field of
2141 each line. Fields are separated by whitespace and numbered starting
2142 from 1. The specified field must contain a number in each line of the
2143 region. Numbers starting with 0 are treated as octal, and numbers
2144 starting with @samp{0x} are treated as hexadecimal.
2146 If @var{field} is negative, sorting is by the
2147 @w{@minus{}@var{field}th} field from the end of the line. This
2148 command is useful for sorting tables.
2151 @defopt sort-numeric-base
2152 This variable specifies the default radix for
2153 @code{sort-numeric-fields} to parse numbers.
2156 @deffn Command sort-columns reverse &optional beg end
2157 This command sorts the lines in the region between @var{beg} and
2158 @var{end}, comparing them alphabetically by a certain range of
2159 columns. The column positions of @var{beg} and @var{end} bound the
2160 range of columns to sort on.
2162 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
2164 One unusual thing about this command is that the entire line
2165 containing position @var{beg}, and the entire line containing position
2166 @var{end}, are included in the region sorted.
2168 Note that @code{sort-columns} rejects text that contains tabs, because
2169 tabs could be split across the specified columns. Use @kbd{M-x
2170 untabify} to convert tabs to spaces before sorting.
2172 When possible, this command actually works by calling the @code{sort}
2177 @section Counting Columns
2179 @cindex counting columns
2180 @cindex horizontal position
2182 The column functions convert between a character position (counting
2183 characters from the beginning of the buffer) and a column position
2184 (counting screen characters from the beginning of a line).
2186 These functions count each character according to the number of
2187 columns it occupies on the screen. This means control characters count
2188 as occupying 2 or 4 columns, depending upon the value of
2189 @code{ctl-arrow}, and tabs count as occupying a number of columns that
2190 depends on the value of @code{tab-width} and on the column where the tab
2191 begins. @xref{Usual Display}.
2193 Column number computations ignore the width of the window and the
2194 amount of horizontal scrolling. Consequently, a column value can be
2195 arbitrarily high. The first (or leftmost) column is numbered 0. They
2196 also ignore overlays and text properties, aside from invisibility.
2198 @defun current-column
2199 This function returns the horizontal position of point, measured in
2200 columns, counting from 0 at the left margin. The column position is the
2201 sum of the widths of all the displayed representations of the characters
2202 between the start of the current line and point.
2205 @deffn Command move-to-column column &optional force
2206 This function moves point to @var{column} in the current line. The
2207 calculation of @var{column} takes into account the widths of the
2208 displayed representations of the characters between the start of the
2211 When called interactively, @var{column} is the value of prefix numeric
2212 argument. If @var{column} is not an integer, an error is signaled.
2214 @c This behavior used to be documented until 2013/08.
2216 If column @var{column} is beyond the end of the line, point moves to
2217 the end of the line. If @var{column} is negative, point moves to the
2218 beginning of the line.
2221 If it is impossible to move to column @var{column} because that is in
2222 the middle of a multicolumn character such as a tab, point moves to the
2223 end of that character. However, if @var{force} is non-@code{nil}, and
2224 @var{column} is in the middle of a tab, then @code{move-to-column}
2225 converts the tab into spaces so that it can move precisely to column
2226 @var{column}. Other multicolumn characters can cause anomalies despite
2227 @var{force}, since there is no way to split them.
2229 The argument @var{force} also has an effect if the line isn't long
2230 enough to reach column @var{column}; if it is @code{t}, that means to
2231 add whitespace at the end of the line to reach that column.
2233 The return value is the column number actually moved to.
2237 @section Indentation
2240 The indentation functions are used to examine, move to, and change
2241 whitespace that is at the beginning of a line. Some of the functions
2242 can also change whitespace elsewhere on a line. Columns and indentation
2243 count from zero at the left margin.
2246 * Primitive Indent:: Functions used to count and insert indentation.
2247 * Mode-Specific Indent:: Customize indentation for different modes.
2248 * Region Indent:: Indent all the lines in a region.
2249 * Relative Indent:: Indent the current line based on previous lines.
2250 * Indent Tabs:: Adjustable, typewriter-like tab stops.
2251 * Motion by Indent:: Move to first non-blank character.
2254 @node Primitive Indent
2255 @subsection Indentation Primitives
2257 This section describes the primitive functions used to count and
2258 insert indentation. The functions in the following sections use these
2259 primitives. @xref{Size of Displayed Text}, for related functions.
2261 @defun current-indentation
2262 @comment !!Type Primitive Function
2263 @comment !!SourceFile indent.c
2264 This function returns the indentation of the current line, which is
2265 the horizontal position of the first nonblank character. If the
2266 contents are entirely blank, then this is the horizontal position of the
2270 @deffn Command indent-to column &optional minimum
2271 @comment !!Type Primitive Function
2272 @comment !!SourceFile indent.c
2273 This function indents from point with tabs and spaces until @var{column}
2274 is reached. If @var{minimum} is specified and non-@code{nil}, then at
2275 least that many spaces are inserted even if this requires going beyond
2276 @var{column}. Otherwise the function does nothing if point is already
2277 beyond @var{column}. The value is the column at which the inserted
2280 The inserted whitespace characters inherit text properties from the
2281 surrounding text (usually, from the preceding text only). @xref{Sticky
2285 @defopt indent-tabs-mode
2286 @comment !!SourceFile indent.c
2287 If this variable is non-@code{nil}, indentation functions can insert
2288 tabs as well as spaces. Otherwise, they insert only spaces. Setting
2289 this variable automatically makes it buffer-local in the current buffer.
2292 @node Mode-Specific Indent
2293 @subsection Indentation Controlled by Major Mode
2295 An important function of each major mode is to customize the @key{TAB}
2296 key to indent properly for the language being edited. This section
2297 describes the mechanism of the @key{TAB} key and how to control it.
2298 The functions in this section return unpredictable values.
2300 @deffn Command indent-for-tab-command &optional rigid
2301 This is the command bound to @key{TAB} in most editing modes. Its
2302 usual action is to indent the current line, but it can alternatively
2303 insert a tab character or indent a region.
2305 Here is what it does:
2309 First, it checks whether Transient Mark mode is enabled and the region
2310 is active. If so, it called @code{indent-region} to indent all the
2311 text in the region (@pxref{Region Indent}).
2314 Otherwise, if the indentation function in @code{indent-line-function}
2315 is @code{indent-to-left-margin} (a trivial command that inserts a tab
2316 character), or if the variable @code{tab-always-indent} specifies that
2317 a tab character ought to be inserted (see below), then it inserts a
2321 Otherwise, it indents the current line; this is done by calling the
2322 function in @code{indent-line-function}. If the line is already
2323 indented, and the value of @code{tab-always-indent} is @code{complete}
2324 (see below), it tries completing the text at point.
2327 If @var{rigid} is non-@code{nil} (interactively, with a prefix
2328 argument), then after this command indents a line or inserts a tab, it
2329 also rigidly indents the entire balanced expression which starts at
2330 the beginning of the current line, in order to reflect the new
2331 indentation. This argument is ignored if the command indents the
2335 @defvar indent-line-function
2336 This variable's value is the function to be used by
2337 @code{indent-for-tab-command}, and various other indentation commands,
2338 to indent the current line. It is usually assigned by the major mode;
2339 for instance, Lisp mode sets it to @code{lisp-indent-line}, C mode
2340 sets it to @code{c-indent-line}, and so on. The default value is
2341 @code{indent-relative}. @xref{Auto-Indentation}.
2344 @deffn Command indent-according-to-mode
2345 This command calls the function in @code{indent-line-function} to
2346 indent the current line in a way appropriate for the current major mode.
2349 @deffn Command newline-and-indent
2350 This function inserts a newline, then indents the new line (the one
2351 following the newline just inserted) according to the major mode. It
2352 does indentation by calling @code{indent-according-to-mode}.
2355 @deffn Command reindent-then-newline-and-indent
2356 This command reindents the current line, inserts a newline at point,
2357 and then indents the new line (the one following the newline just
2358 inserted). It does indentation on both lines by calling
2359 @code{indent-according-to-mode}.
2362 @defopt tab-always-indent
2363 This variable can be used to customize the behavior of the @key{TAB}
2364 (@code{indent-for-tab-command}) command. If the value is @code{t}
2365 (the default), the command normally just indents the current line. If
2366 the value is @code{nil}, the command indents the current line only if
2367 point is at the left margin or in the line's indentation; otherwise,
2368 it inserts a tab character. If the value is @code{complete}, the
2369 command first tries to indent the current line, and if the line was
2370 already indented, it calls @code{completion-at-point} to complete the
2371 text at point (@pxref{Completion in Buffers}).
2374 @cindex literate programming
2375 @cindex multi-mode indentation
2376 Some major modes need to support embedded regions of text whose
2377 syntax belongs to a different major mode. Examples include
2378 @dfn{literate programming} source files that combine documentation and
2379 snippets of source code, Yacc/Bison programs that include snippets of
2380 plain C code, etc. To correctly indent the embedded chunks, the major
2381 mode needs to delegate the indentation to another mode's indentation
2382 engine (e.g., call @code{c-indent-defun} for C code or
2383 @code{python-indent-line} for Python), while providing it with some
2384 context to guide the indentation. The following facilities support
2385 such multi-mode indentation.
2387 @defvar prog-indentation-context
2388 This variable, when non-@code{nil}, holds the indentation context for
2389 the sub-mode's indentation engine provided by the superior major mode.
2390 The value should be a list of the form @code{(@var{first-column}
2391 @w{(@var{start} . @var{end})} @code{prev-chunk})}. The members of the
2392 list have the following meaning:
2396 The column to be used for top-level constructs. This replaces the
2397 default value of the top-level column used by the sub-mode, usually
2401 The region of the code chunk to be indented by the sub-mode. The
2402 value of @var{end} can be @code{nil}, which stands for the value of
2405 If this is non-@code{nil}, it should provide the sub-mode's
2406 indentation engine with a virtual context of the code chunk. Valid
2411 A string whose contents is the text the sub-mode's indentation engine
2412 should consider to precede the code chunk. The sub-mode's indentation
2413 engine can add text properties to that string, to be reused in
2414 repeated calls with the same string, thus using it as a cache. An
2415 example where this is useful is code chunks that need to be indented
2416 as function bodies, but lack the function's preamble---the string
2417 could then include that missing preamble.
2419 A function. It is expected to be called with the start position of
2420 the current chunk, and should return a cons cell
2421 @w{@code{(@var{prev-start} . @var{prev-end})}} that specifies the
2422 region of the previous code chunk, or @code{nil} if there is no previous
2423 chunk. This is useful in literate-programming sources, where code is
2424 split into chunks, and correct indentation needs to access previous
2430 The following convenience functions should be used by major mode's
2431 indentation engine in support of invocations as sub-modes of another
2434 @defun prog-first-column
2435 Call this function instead of using a literal value (usually, zero) of
2436 the column number for indenting top-level program constructs. The
2437 function's value is the column number to use for top-level constructs.
2438 When no superior mode is in effect, this function returns zero.
2442 Call this function instead of @code{widen} to remove any restrictions
2443 imposed by the mode's indentation engine and restore the restrictions
2444 recorded in @code{prog-indentation-context}. This prevents the
2445 indentation engine of a sub-mode from inadvertently operating on text
2446 outside of the chunk it was supposed to indent, and preserves the
2447 restriction imposed by the superior mode. When no superior mode is in
2448 effect, this function just calls @code{widen}.
2453 @subsection Indenting an Entire Region
2455 This section describes commands that indent all the lines in the
2456 region. They return unpredictable values.
2458 @deffn Command indent-region start end &optional to-column
2459 This command indents each nonblank line starting between @var{start}
2460 (inclusive) and @var{end} (exclusive). If @var{to-column} is
2461 @code{nil}, @code{indent-region} indents each nonblank line by calling
2462 the current mode's indentation function, the value of
2463 @code{indent-line-function}.
2465 If @var{to-column} is non-@code{nil}, it should be an integer
2466 specifying the number of columns of indentation; then this function
2467 gives each line exactly that much indentation, by either adding or
2468 deleting whitespace.
2470 If there is a fill prefix, @code{indent-region} indents each line
2471 by making it start with the fill prefix.
2474 @defvar indent-region-function
2475 The value of this variable is a function that can be used by
2476 @code{indent-region} as a short cut. It should take two arguments, the
2477 start and end of the region. You should design the function so
2478 that it will produce the same results as indenting the lines of the
2479 region one by one, but presumably faster.
2481 If the value is @code{nil}, there is no short cut, and
2482 @code{indent-region} actually works line by line.
2484 A short-cut function is useful in modes such as C mode and Lisp mode,
2485 where the @code{indent-line-function} must scan from the beginning of
2486 the function definition: applying it to each line would be quadratic in
2487 time. The short cut can update the scan information as it moves through
2488 the lines indenting them; this takes linear time. In a mode where
2489 indenting a line individually is fast, there is no need for a short cut.
2491 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
2492 a different meaning and does not use this variable.
2495 @deffn Command indent-rigidly start end count
2496 This function indents all lines starting between @var{start}
2497 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
2498 This preserves the shape of the affected region, moving it as a
2501 This is useful not only for indenting regions of unindented text, but
2502 also for indenting regions of formatted code. For example, if
2503 @var{count} is 3, this command adds 3 columns of indentation to every
2504 line that begins in the specified region.
2506 If called interactively with no prefix argument, this command invokes
2507 a transient mode for adjusting indentation rigidly. @xref{Indentation
2508 Commands,,, emacs, The GNU Emacs Manual}.
2511 @deffn Command indent-code-rigidly start end columns &optional nochange-regexp
2512 This is like @code{indent-rigidly}, except that it doesn't alter lines
2513 that start within strings or comments.
2515 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
2516 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
2519 @node Relative Indent
2520 @subsection Indentation Relative to Previous Lines
2522 This section describes two commands that indent the current line
2523 based on the contents of previous lines.
2525 @deffn Command indent-relative &optional unindented-ok
2526 This command inserts whitespace at point, extending to the same
2527 column as the next @dfn{indent point} of the previous nonblank line. An
2528 indent point is a non-whitespace character following whitespace. The
2529 next indent point is the first one at a column greater than the current
2530 column of point. For example, if point is underneath and to the left of
2531 the first non-blank character of a line of text, it moves to that column
2532 by inserting whitespace.
2534 If the previous nonblank line has no next indent point (i.e., none at a
2535 great enough column position), @code{indent-relative} either does
2536 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
2537 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right
2538 of the last column of a short line of text, this command ordinarily
2539 moves point to the next tab stop by inserting whitespace.
2541 The return value of @code{indent-relative} is unpredictable.
2543 In the following example, point is at the beginning of the second
2548 This line is indented twelve spaces.
2549 @point{}The quick brown fox jumped.
2554 Evaluation of the expression @code{(indent-relative nil)} produces the
2559 This line is indented twelve spaces.
2560 @point{}The quick brown fox jumped.
2564 In this next example, point is between the @samp{m} and @samp{p} of
2569 This line is indented twelve spaces.
2570 The quick brown fox jum@point{}ped.
2575 Evaluation of the expression @code{(indent-relative nil)} produces the
2580 This line is indented twelve spaces.
2581 The quick brown fox jum @point{}ped.
2586 @deffn Command indent-relative-maybe
2587 @comment !!SourceFile indent.el
2588 This command indents the current line like the previous nonblank line,
2589 by calling @code{indent-relative} with @code{t} as the
2590 @var{unindented-ok} argument. The return value is unpredictable.
2592 If the previous nonblank line has no indent points beyond the current
2593 column, this command does nothing.
2597 @subsection Adjustable Tab Stops
2598 @cindex tabs stops for indentation
2600 This section explains the mechanism for user-specified tab stops
2601 and the mechanisms that use and set them. The name ``tab stops'' is
2602 used because the feature is similar to that of the tab stops on a
2603 typewriter. The feature works by inserting an appropriate number of
2604 spaces and tab characters to reach the next tab stop column; it does not
2605 affect the display of tab characters in the buffer (@pxref{Usual
2606 Display}). Note that the @key{TAB} character as input uses this tab
2607 stop feature only in a few major modes, such as Text mode.
2608 @xref{Tab Stops,,, emacs, The GNU Emacs Manual}.
2610 @deffn Command tab-to-tab-stop
2611 This command inserts spaces or tabs before point, up to the next tab
2612 stop column defined by @code{tab-stop-list}.
2615 @defopt tab-stop-list
2616 This variable defines the tab stop columns used by @code{tab-to-tab-stop}.
2617 It should be either @code{nil}, or a list of increasing integers,
2618 which need not be evenly spaced. The list is implicitly
2619 extended to infinity through repetition of the interval between the
2620 last and penultimate elements (or @code{tab-width} if the list has
2621 fewer than two elements). A value of @code{nil} means a tab stop
2622 every @code{tab-width} columns.
2624 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops interactively.
2627 @node Motion by Indent
2628 @subsection Indentation-Based Motion Commands
2630 These commands, primarily for interactive use, act based on the
2631 indentation in the text.
2633 @deffn Command back-to-indentation
2634 @comment !!SourceFile simple.el
2635 This command moves point to the first non-whitespace character in the
2636 current line (which is the line in which point is located). It returns
2640 @deffn Command backward-to-indentation &optional arg
2641 @comment !!SourceFile simple.el
2642 This command moves point backward @var{arg} lines and then to the
2643 first nonblank character on that line. It returns @code{nil}.
2644 If @var{arg} is omitted or @code{nil}, it defaults to 1.
2647 @deffn Command forward-to-indentation &optional arg
2648 @comment !!SourceFile simple.el
2649 This command moves point forward @var{arg} lines and then to the first
2650 nonblank character on that line. It returns @code{nil}.
2651 If @var{arg} is omitted or @code{nil}, it defaults to 1.
2655 @section Case Changes
2656 @cindex case conversion in buffers
2658 The case change commands described here work on text in the current
2659 buffer. @xref{Case Conversion}, for case conversion functions that work
2660 on strings and characters. @xref{Case Tables}, for how to customize
2661 which characters are upper or lower case and how to convert them.
2663 @deffn Command capitalize-region start end
2664 This function capitalizes all words in the region defined by
2665 @var{start} and @var{end}. To capitalize means to convert each word's
2666 first character to upper case and convert the rest of each word to lower
2667 case. The function returns @code{nil}.
2669 If one end of the region is in the middle of a word, the part of the
2670 word within the region is treated as an entire word.
2672 When @code{capitalize-region} is called interactively, @var{start} and
2673 @var{end} are point and the mark, with the smallest first.
2677 ---------- Buffer: foo ----------
2678 This is the contents of the 5th foo.
2679 ---------- Buffer: foo ----------
2683 (capitalize-region 1 37)
2686 ---------- Buffer: foo ----------
2687 This Is The Contents Of The 5th Foo.
2688 ---------- Buffer: foo ----------
2693 @deffn Command downcase-region start end
2694 This function converts all of the letters in the region defined by
2695 @var{start} and @var{end} to lower case. The function returns
2698 When @code{downcase-region} is called interactively, @var{start} and
2699 @var{end} are point and the mark, with the smallest first.
2702 @deffn Command upcase-region start end
2703 This function converts all of the letters in the region defined by
2704 @var{start} and @var{end} to upper case. The function returns
2707 When @code{upcase-region} is called interactively, @var{start} and
2708 @var{end} are point and the mark, with the smallest first.
2711 @deffn Command capitalize-word count
2712 This function capitalizes @var{count} words after point, moving point
2713 over as it does. To capitalize means to convert each word's first
2714 character to upper case and convert the rest of each word to lower case.
2715 If @var{count} is negative, the function capitalizes the
2716 @minus{}@var{count} previous words but does not move point. The value
2719 If point is in the middle of a word, the part of the word before point
2720 is ignored when moving forward. The rest is treated as an entire word.
2722 When @code{capitalize-word} is called interactively, @var{count} is
2723 set to the numeric prefix argument.
2726 @deffn Command downcase-word count
2727 This function converts the @var{count} words after point to all lower
2728 case, moving point over as it does. If @var{count} is negative, it
2729 converts the @minus{}@var{count} previous words but does not move point.
2730 The value is @code{nil}.
2732 When @code{downcase-word} is called interactively, @var{count} is set
2733 to the numeric prefix argument.
2736 @deffn Command upcase-word count
2737 This function converts the @var{count} words after point to all upper
2738 case, moving point over as it does. If @var{count} is negative, it
2739 converts the @minus{}@var{count} previous words but does not move point.
2740 The value is @code{nil}.
2742 When @code{upcase-word} is called interactively, @var{count} is set to
2743 the numeric prefix argument.
2746 @node Text Properties
2747 @section Text Properties
2748 @cindex text properties
2749 @cindex attributes of text
2750 @cindex properties of text
2752 Each character position in a buffer or a string can have a @dfn{text
2753 property list}, much like the property list of a symbol (@pxref{Property
2754 Lists}). The properties belong to a particular character at a
2755 particular place, such as, the letter @samp{T} at the beginning of this
2756 sentence or the first @samp{o} in @samp{foo}---if the same character
2757 occurs in two different places, the two occurrences in general have
2758 different properties.
2760 Each property has a name and a value. Both of these can be any Lisp
2761 object, but the name is normally a symbol. Typically each property
2762 name symbol is used for a particular purpose; for instance, the text
2763 property @code{face} specifies the faces for displaying the character
2764 (@pxref{Special Properties}). The usual way to access the property
2765 list is to specify a name and ask what value corresponds to it.
2767 If a character has a @code{category} property, we call it the
2768 @dfn{property category} of the character. It should be a symbol. The
2769 properties of the symbol serve as defaults for the properties of the
2772 Copying text between strings and buffers preserves the properties
2773 along with the characters; this includes such diverse functions as
2774 @code{substring}, @code{insert}, and @code{buffer-substring}.
2777 * Examining Properties:: Looking at the properties of one character.
2778 * Changing Properties:: Setting the properties of a range of text.
2779 * Property Search:: Searching for where a property changes value.
2780 * Special Properties:: Particular properties with special meanings.
2781 * Format Properties:: Properties for representing formatting of text.
2782 * Sticky Properties:: How inserted text gets properties from
2784 * Lazy Properties:: Computing text properties in a lazy fashion
2785 only when text is examined.
2786 * Clickable Text:: Using text properties to make regions of text
2787 do something when you click on them.
2788 * Fields:: The @code{field} property defines
2789 fields within the buffer.
2790 * Not Intervals:: Why text properties do not use
2791 Lisp-visible text intervals.
2794 @node Examining Properties
2795 @subsection Examining Text Properties
2796 @cindex examining text properties
2797 @cindex text properties, examining
2799 The simplest way to examine text properties is to ask for the value of
2800 a particular property of a particular character. For that, use
2801 @code{get-text-property}. Use @code{text-properties-at} to get the
2802 entire property list of a character. @xref{Property Search}, for
2803 functions to examine the properties of a number of characters at once.
2805 These functions handle both strings and buffers. Keep in mind that
2806 positions in a string start from 0, whereas positions in a buffer start
2809 @defun get-text-property pos prop &optional object
2810 This function returns the value of the @var{prop} property of the
2811 character after position @var{pos} in @var{object} (a buffer or
2812 string). The argument @var{object} is optional and defaults to the
2815 If there is no @var{prop} property strictly speaking, but the character
2816 has a property category that is a symbol, then @code{get-text-property} returns
2817 the @var{prop} property of that symbol.
2820 @defun get-char-property position prop &optional object
2821 This function is like @code{get-text-property}, except that it checks
2822 overlays first and then text properties. @xref{Overlays}.
2824 The argument @var{object} may be a string, a buffer, or a window. If
2825 it is a window, then the buffer displayed in that window is used for
2826 text properties and overlays, but only the overlays active for that
2827 window are considered. If @var{object} is a buffer, then overlays in
2828 that buffer are considered first, in order of decreasing priority,
2829 followed by the text properties. If @var{object} is a string, only
2830 text properties are considered, since strings never have overlays.
2833 @defun get-pos-property position prop &optional object
2834 This function is like @code{get-char-property}, except that it pays
2835 attention to properties' stickiness and overlays' advancement settings
2836 instead of the property of the character at (i.e., right after)
2840 @defun get-char-property-and-overlay position prop &optional object
2841 This is like @code{get-char-property}, but gives extra information
2842 about the overlay that the property value comes from.
2844 Its value is a cons cell whose @sc{car} is the property value, the
2845 same value @code{get-char-property} would return with the same
2846 arguments. Its @sc{cdr} is the overlay in which the property was
2847 found, or @code{nil}, if it was found as a text property or not found
2850 If @var{position} is at the end of @var{object}, both the @sc{car} and
2851 the @sc{cdr} of the value are @code{nil}.
2854 @defvar char-property-alias-alist
2855 This variable holds an alist which maps property names to a list of
2856 alternative property names. If a character does not specify a direct
2857 value for a property, the alternative property names are consulted in
2858 order; the first non-@code{nil} value is used. This variable takes
2859 precedence over @code{default-text-properties}, and @code{category}
2860 properties take precedence over this variable.
2863 @defun text-properties-at position &optional object
2864 This function returns the entire property list of the character at
2865 @var{position} in the string or buffer @var{object}. If @var{object} is
2866 @code{nil}, it defaults to the current buffer.
2869 @defvar default-text-properties
2870 This variable holds a property list giving default values for text
2871 properties. Whenever a character does not specify a value for a
2872 property, neither directly, through a category symbol, or through
2873 @code{char-property-alias-alist}, the value stored in this list is
2874 used instead. Here is an example:
2877 (setq default-text-properties '(foo 69)
2878 char-property-alias-alist nil)
2879 ;; @r{Make sure character 1 has no properties of its own.}
2880 (set-text-properties 1 2 nil)
2881 ;; @r{What we get, when we ask, is the default value.}
2882 (get-text-property 1 'foo)
2887 @node Changing Properties
2888 @subsection Changing Text Properties
2889 @cindex changing text properties
2890 @cindex text properties, changing
2892 The primitives for changing properties apply to a specified range of
2893 text in a buffer or string. The function @code{set-text-properties}
2894 (see end of section) sets the entire property list of the text in that
2895 range; more often, it is useful to add, change, or delete just certain
2896 properties specified by name.
2898 Since text properties are considered part of the contents of the
2899 buffer (or string), and can affect how a buffer looks on the screen,
2900 any change in buffer text properties marks the buffer as modified.
2901 Buffer text property changes are undoable also (@pxref{Undo}).
2902 Positions in a string start from 0, whereas positions in a buffer
2905 @defun put-text-property start end prop value &optional object
2906 This function sets the @var{prop} property to @var{value} for the text
2907 between @var{start} and @var{end} in the string or buffer @var{object}.
2908 If @var{object} is @code{nil}, it defaults to the current buffer.
2911 @defun add-text-properties start end props &optional object
2912 This function adds or overrides text properties for the text between
2913 @var{start} and @var{end} in the string or buffer @var{object}. If
2914 @var{object} is @code{nil}, it defaults to the current buffer.
2916 The argument @var{props} specifies which properties to add. It should
2917 have the form of a property list (@pxref{Property Lists}): a list whose
2918 elements include the property names followed alternately by the
2919 corresponding values.
2921 The return value is @code{t} if the function actually changed some
2922 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2923 its values agree with those in the text).
2925 For example, here is how to set the @code{comment} and @code{face}
2926 properties of a range of text:
2929 (add-text-properties @var{start} @var{end}
2930 '(comment t face highlight))
2934 @defun remove-text-properties start end props &optional object
2935 This function deletes specified text properties from the text between
2936 @var{start} and @var{end} in the string or buffer @var{object}. If
2937 @var{object} is @code{nil}, it defaults to the current buffer.
2939 The argument @var{props} specifies which properties to delete. It
2940 should have the form of a property list (@pxref{Property Lists}): a list
2941 whose elements are property names alternating with corresponding values.
2942 But only the names matter---the values that accompany them are ignored.
2943 For example, here's how to remove the @code{face} property.
2946 (remove-text-properties @var{start} @var{end} '(face nil))
2949 The return value is @code{t} if the function actually changed some
2950 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2951 if no character in the specified text had any of those properties).
2953 To remove all text properties from certain text, use
2954 @code{set-text-properties} and specify @code{nil} for the new property
2958 @defun remove-list-of-text-properties start end list-of-properties &optional object
2959 Like @code{remove-text-properties} except that
2960 @var{list-of-properties} is a list of property names only, not an
2961 alternating list of property names and values.
2964 @defun set-text-properties start end props &optional object
2965 This function completely replaces the text property list for the text
2966 between @var{start} and @var{end} in the string or buffer @var{object}.
2967 If @var{object} is @code{nil}, it defaults to the current buffer.
2969 The argument @var{props} is the new property list. It should be a list
2970 whose elements are property names alternating with corresponding values.
2972 After @code{set-text-properties} returns, all the characters in the
2973 specified range have identical properties.
2975 If @var{props} is @code{nil}, the effect is to get rid of all properties
2976 from the specified range of text. Here's an example:
2979 (set-text-properties @var{start} @var{end} nil)
2982 Do not rely on the return value of this function.
2985 @defun add-face-text-property start end face &optional appendp object
2986 This function acts on the text between @var{start} and @var{end},
2987 adding the face @var{face} to the @code{face} text property.
2988 @var{face} should be a valid value for the @code{face} property
2989 (@pxref{Special Properties}), such as a face name or an anonymous face
2992 If any text in the region already has a non-@code{nil} @code{face} property,
2993 those face(s) are retained. This function sets the @code{face}
2994 property to a list of faces, with @var{face} as the first element (by
2995 default) and the pre-existing faces as the remaining elements. If the
2996 optional argument @var{append} is non-@code{nil}, @var{face} is
2997 appended to the end of the list instead. Note that in a face list,
2998 the first occurring value for each attribute takes precedence.
3000 For example, the following code would assign a italicized green face
3001 to the text between @var{start} and @var{end}:
3004 (add-face-text-property @var{start} @var{end} 'italic)
3005 (add-face-text-property @var{start} @var{end} '(:foreground "red"))
3006 (add-face-text-property @var{start} @var{end} '(:foreground "green"))
3009 The optional argument @var{object}, if non-@code{nil}, specifies a
3010 buffer or string to act on, rather than the current buffer. If
3011 @var{object} is a string, then @var{start} and @var{end} are
3012 zero-based indices into the string.
3015 The easiest way to make a string with text properties is with
3018 @defun propertize string &rest properties
3019 This function returns a copy of @var{string} with the text properties
3020 @var{properties} added. These properties apply to all the characters
3021 in the string that is returned. Here is an example that constructs a
3022 string with a @code{face} property and a @code{mouse-face} property:
3025 (propertize "foo" 'face 'italic
3026 'mouse-face 'bold-italic)
3027 @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
3030 To put different properties on various parts of a string, you can
3031 construct each part with @code{propertize} and then combine them with
3036 (propertize "foo" 'face 'italic
3037 'mouse-face 'bold-italic)
3039 (propertize "bar" 'face 'italic
3040 'mouse-face 'bold-italic))
3041 @result{} #("foo and bar"
3042 0 3 (face italic mouse-face bold-italic)
3044 8 11 (face italic mouse-face bold-italic))
3048 @xref{Buffer Contents}, for the function
3049 @code{buffer-substring-no-properties}, which copies text from the
3050 buffer but does not copy its properties.
3052 @findex with-silent-modifications
3053 If you wish to add or remove text properties to a buffer without
3054 marking the buffer as modified, you can wrap the calls above in the
3055 @code{with-silent-modifications} macro.
3057 @node Property Search
3058 @subsection Text Property Search Functions
3059 @cindex searching text properties
3060 @cindex text properties, searching
3062 In typical use of text properties, most of the time several or many
3063 consecutive characters have the same value for a property. Rather than
3064 writing your programs to examine characters one by one, it is much
3065 faster to process chunks of text that have the same property value.
3067 Here are functions you can use to do this. They use @code{eq} for
3068 comparing property values. In all cases, @var{object} defaults to the
3071 For good performance, it's very important to use the @var{limit}
3072 argument to these functions, especially the ones that search for a
3073 single property---otherwise, they may spend a long time scanning to the
3074 end of the buffer, if the property you are interested in does not change.
3076 These functions do not move point; instead, they return a position (or
3077 @code{nil}). Remember that a position is always between two characters;
3078 the position returned by these functions is between two characters with
3079 different properties.
3081 @defun next-property-change pos &optional object limit
3082 The function scans the text forward from position @var{pos} in the
3083 string or buffer @var{object} until it finds a change in some text
3084 property, then returns the position of the change. In other words, it
3085 returns the position of the first character beyond @var{pos} whose
3086 properties are not identical to those of the character just after
3089 If @var{limit} is non-@code{nil}, then the scan ends at position
3090 @var{limit}. If there is no property change before that point, this
3091 function returns @var{limit}.
3093 The value is @code{nil} if the properties remain unchanged all the way
3094 to the end of @var{object} and @var{limit} is @code{nil}. If the value
3095 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
3096 The value equals @var{pos} only when @var{limit} equals @var{pos}.
3098 Here is an example of how to scan the buffer by chunks of text within
3099 which all properties are constant:
3103 (let ((plist (text-properties-at (point)))
3105 (or (next-property-change (point) (current-buffer))
3107 @r{Process text from point to @var{next-change}@dots{}}
3108 (goto-char next-change)))
3112 @defun previous-property-change pos &optional object limit
3113 This is like @code{next-property-change}, but scans back from @var{pos}
3114 instead of forward. If the value is non-@code{nil}, it is a position
3115 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
3119 @defun next-single-property-change pos prop &optional object limit
3120 The function scans text for a change in the @var{prop} property, then
3121 returns the position of the change. The scan goes forward from
3122 position @var{pos} in the string or buffer @var{object}. In other
3123 words, this function returns the position of the first character
3124 beyond @var{pos} whose @var{prop} property differs from that of the
3125 character just after @var{pos}.
3127 If @var{limit} is non-@code{nil}, then the scan ends at position
3128 @var{limit}. If there is no property change before that point,
3129 @code{next-single-property-change} returns @var{limit}.
3131 The value is @code{nil} if the property remains unchanged all the way to
3132 the end of @var{object} and @var{limit} is @code{nil}. If the value is
3133 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
3134 equals @var{pos} only if @var{limit} equals @var{pos}.
3137 @defun previous-single-property-change pos prop &optional object limit
3138 This is like @code{next-single-property-change}, but scans back from
3139 @var{pos} instead of forward. If the value is non-@code{nil}, it is a
3140 position less than or equal to @var{pos}; it equals @var{pos} only if
3141 @var{limit} equals @var{pos}.
3144 @defun next-char-property-change pos &optional limit
3145 This is like @code{next-property-change} except that it considers
3146 overlay properties as well as text properties, and if no change is
3147 found before the end of the buffer, it returns the maximum buffer
3148 position rather than @code{nil} (in this sense, it resembles the
3149 corresponding overlay function @code{next-overlay-change}, rather than
3150 @code{next-property-change}). There is no @var{object} operand
3151 because this function operates only on the current buffer. It returns
3152 the next address at which either kind of property changes.
3155 @defun previous-char-property-change pos &optional limit
3156 This is like @code{next-char-property-change}, but scans back from
3157 @var{pos} instead of forward, and returns the minimum buffer
3158 position if no change is found.
3161 @defun next-single-char-property-change pos prop &optional object limit
3162 This is like @code{next-single-property-change} except that it
3163 considers overlay properties as well as text properties, and if no
3164 change is found before the end of the @var{object}, it returns the
3165 maximum valid position in @var{object} rather than @code{nil}. Unlike
3166 @code{next-char-property-change}, this function @emph{does} have an
3167 @var{object} operand; if @var{object} is not a buffer, only
3168 text-properties are considered.
3171 @defun previous-single-char-property-change pos prop &optional object limit
3172 This is like @code{next-single-char-property-change}, but scans back
3173 from @var{pos} instead of forward, and returns the minimum valid
3174 position in @var{object} if no change is found.
3177 @defun text-property-any start end prop value &optional object
3178 This function returns non-@code{nil} if at least one character between
3179 @var{start} and @var{end} has a property @var{prop} whose value is
3180 @var{value}. More precisely, it returns the position of the first such
3181 character. Otherwise, it returns @code{nil}.
3183 The optional fifth argument, @var{object}, specifies the string or
3184 buffer to scan. Positions are relative to @var{object}. The default
3185 for @var{object} is the current buffer.
3188 @defun text-property-not-all start end prop value &optional object
3189 This function returns non-@code{nil} if at least one character between
3190 @var{start} and @var{end} does not have a property @var{prop} with value
3191 @var{value}. More precisely, it returns the position of the first such
3192 character. Otherwise, it returns @code{nil}.
3194 The optional fifth argument, @var{object}, specifies the string or
3195 buffer to scan. Positions are relative to @var{object}. The default
3196 for @var{object} is the current buffer.
3199 @node Special Properties
3200 @subsection Properties with Special Meanings
3202 Here is a table of text property names that have special built-in
3203 meanings. The following sections list a few additional special property
3204 names that control filling and property inheritance. All other names
3205 have no standard meaning, and you can use them as you like.
3207 Note: the properties @code{composition}, @code{display},
3208 @code{invisible} and @code{intangible} can also cause point to move to
3209 an acceptable place, after each Emacs command. @xref{Adjusting
3213 @cindex property category of text character
3214 @c FIXME: Isn't @kindex for keyboard commands?
3215 @kindex category @r{(text property)}
3217 If a character has a @code{category} property, we call it the
3218 @dfn{property category} of the character. It should be a symbol. The
3219 properties of this symbol serve as defaults for the properties of the
3223 @cindex face codes of text
3224 @kindex face @r{(text property)}
3225 The @code{face} property controls the appearance of the character
3226 (@pxref{Faces}). The value of the property can be the following:
3230 A face name (a symbol or string).
3233 An anonymous face: a property list of the form @code{(@var{keyword}
3234 @var{value} @dots{})}, where each @var{keyword} is a face attribute
3235 name and @var{value} is a value for that attribute.
3238 A list of faces. Each list element should be either a face name or an
3239 anonymous face. This specifies a face which is an aggregate of the
3240 attributes of each of the listed faces. Faces occurring earlier in
3241 the list have higher priority.
3244 A cons cell of the form @code{(foreground-color . @var{color-name})}
3245 or @code{(background-color . @var{color-name})}. This specifies the
3246 foreground or background color, similar to @code{(:foreground
3247 @var{color-name})} or @code{(:background @var{color-name})}. This
3248 form is supported for backward compatibility only, and should be
3252 Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
3253 dynamically updating the @code{face} property of characters based on
3256 The @code{add-face-text-property} function provides a convenient way
3257 to set this text property. @xref{Changing Properties}.
3259 @item font-lock-face
3260 @kindex font-lock-face @r{(text property)}
3261 This property specifies a value for the @code{face} property that Font
3262 Lock mode should apply to the underlying text. It is one of the
3263 fontification methods used by Font Lock mode, and is useful for
3264 special modes that implement their own highlighting.
3265 @xref{Precalculated Fontification}. When Font Lock mode is disabled,
3266 @code{font-lock-face} has no effect.
3269 @kindex mouse-face @r{(text property)}
3270 This property is used instead of @code{face} when the mouse is on or
3271 near the character. For this purpose, ``near'' means that all text
3272 between the character and where the mouse is have the same
3273 @code{mouse-face} property value.
3275 Emacs ignores all face attributes from the @code{mouse-face} property
3276 that alter the text size (e.g., @code{:height}, @code{:weight}, and
3277 @code{:slant}). Those attributes are always the same as for the
3281 @kindex fontified @r{(text property)}
3282 This property says whether the text is ready for display. If
3283 @code{nil}, Emacs's redisplay routine calls the functions in
3284 @code{fontification-functions} (@pxref{Auto Faces}) to prepare this
3285 part of the buffer before it is displayed. It is used internally by
3286 the just-in-time font locking code.
3289 This property activates various features that change the
3290 way text is displayed. For example, it can make text appear taller
3291 or shorter, higher or lower, wider or narrow, or replaced with an image.
3292 @xref{Display Property}.
3295 @kindex help-echo @r{(text property)}
3296 @cindex tooltip for help strings
3297 @anchor{Text help-echo}
3298 If text has a string as its @code{help-echo} property, then when you
3299 move the mouse onto that text, Emacs displays that string in the echo
3300 area, or in the tooltip window (@pxref{Tooltips}).
3302 If the value of the @code{help-echo} property is a function, that
3303 function is called with three arguments, @var{window}, @var{object} and
3304 @var{pos} and should return a help string or @code{nil} for
3305 none. The first argument, @var{window} is the window in which
3306 the help was found. The second, @var{object}, is the buffer, overlay or
3307 string which had the @code{help-echo} property. The @var{pos}
3308 argument is as follows:
3312 If @var{object} is a buffer, @var{pos} is the position in the buffer.
3314 If @var{object} is an overlay, that overlay has a @code{help-echo}
3315 property, and @var{pos} is the position in the overlay's buffer.
3317 If @var{object} is a string (an overlay string or a string displayed
3318 with the @code{display} property), @var{pos} is the position in that
3322 If the value of the @code{help-echo} property is neither a function nor
3323 a string, it is evaluated to obtain a help string.
3325 You can alter the way help text is displayed by setting the variable
3326 @code{show-help-function} (@pxref{Help display}).
3328 This feature is used in the mode line and for other active text.
3331 @cindex keymap of character
3332 @kindex keymap @r{(text property)}
3333 The @code{keymap} property specifies an additional keymap for
3334 commands. When this keymap applies, it is used for key lookup before
3335 the minor mode keymaps and before the buffer's local map.
3336 @xref{Active Keymaps}. If the property value is a symbol, the
3337 symbol's function definition is used as the keymap.
3339 The property's value for the character before point applies if it is
3340 non-@code{nil} and rear-sticky, and the property's value for the
3341 character after point applies if it is non-@code{nil} and
3342 front-sticky. (For mouse clicks, the position of the click is used
3343 instead of the position of point.)
3346 @kindex local-map @r{(text property)}
3347 This property works like @code{keymap} except that it specifies a
3348 keymap to use @emph{instead of} the buffer's local map. For most
3349 purposes (perhaps all purposes), it is better to use the @code{keymap}
3353 The @code{syntax-table} property overrides what the syntax table says
3354 about this particular character. @xref{Syntax Properties}.
3357 @cindex read-only character
3358 @kindex read-only @r{(text property)}
3359 If a character has the property @code{read-only}, then modifying that
3360 character is not allowed. Any command that would do so gets an error,
3361 @code{text-read-only}. If the property value is a string, that string
3362 is used as the error message.
3364 Insertion next to a read-only character is an error if inserting
3365 ordinary text there would inherit the @code{read-only} property due to
3366 stickiness. Thus, you can control permission to insert next to
3367 read-only text by controlling the stickiness. @xref{Sticky Properties}.
3369 Since changing properties counts as modifying the buffer, it is not
3370 possible to remove a @code{read-only} property unless you know the
3371 special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
3372 and then remove the property. @xref{Read Only Buffers}.
3374 @item inhibit-read-only
3375 @kindex inhibit-read-only @r{(text property)}
3376 Characters that have the property @code{inhibit-read-only} can be
3377 edited even in read-only buffers. @xref{Read Only Buffers}.
3380 @kindex invisible @r{(text property)}
3381 A non-@code{nil} @code{invisible} property can make a character invisible
3382 on the screen. @xref{Invisible Text}, for details.
3385 @kindex intangible @r{(text property)}
3386 If a group of consecutive characters have equal and non-@code{nil}
3387 @code{intangible} properties, then you cannot place point between them.
3388 If you try to move point forward into the group, point actually moves to
3389 the end of the group. If you try to move point backward into the group,
3390 point actually moves to the start of the group.
3392 If consecutive characters have unequal non-@code{nil}
3393 @code{intangible} properties, they belong to separate groups; each
3394 group is separately treated as described above.
3396 When the variable @code{inhibit-point-motion-hooks} is non-@code{nil}
3397 (as it is by default), the @code{intangible} property is ignored.
3399 Beware: this property operates at a very low level, and affects a lot of code
3400 in unexpected ways. So use it with extreme caution. A common misuse is to put
3401 an intangible property on invisible text, which is actually unnecessary since
3402 the command loop will move point outside of the invisible text at the end of
3403 each command anyway. @xref{Adjusting Point}. For these reasons, this
3404 property is obsolete; use the @code{cursor-intangible} property instead.
3406 @item cursor-intangible
3407 @kindex cursor-intangible @r{(text property)}
3408 @findex cursor-intangible-mode
3409 When the minor mode @code{cursor-intangible-mode} is turned on, point
3410 is moved away of any position that has a non-@code{nil}
3411 @code{cursor-intangible} property, just before redisplay happens.
3414 @kindex field @r{(text property)}
3415 Consecutive characters with the same @code{field} property constitute a
3416 @dfn{field}. Some motion functions including @code{forward-word} and
3417 @code{beginning-of-line} stop moving at a field boundary.
3421 @kindex cursor @r{(text property)}
3422 Normally, the cursor is displayed at the beginning or the end of any
3423 overlay and text property strings present at the current buffer
3424 position. You can place the cursor on any desired character of these
3425 strings by giving that character a non-@code{nil} @code{cursor} text
3426 property. In addition, if the value of the @code{cursor} property is
3427 an integer, it specifies the number of buffer's character
3428 positions, starting with the position where the overlay or the
3429 @code{display} property begins, for which the cursor should be
3430 displayed on that character. Specifically, if the value of the
3431 @code{cursor} property of a character is the number @var{n}, the
3432 cursor will be displayed on this character for any buffer position in
3433 the range @code{[@var{ovpos}..@var{ovpos}+@var{n})}, where @var{ovpos}
3434 is the overlay's starting position given by @code{overlay-start}
3435 (@pxref{Managing Overlays}), or the position where the @code{display}
3436 text property begins in the buffer.
3438 In other words, the string character with the @code{cursor} property
3439 of any non-@code{nil} value is the character where to display the
3440 cursor. The value of the property says for which buffer positions to
3441 display the cursor there. If the value is an integer @var{n},
3442 the cursor is displayed there when point is anywhere between the
3443 beginning of the overlay or @code{display} property and @var{n}
3444 positions after that. If the value is anything else and
3445 non-@code{nil}, the cursor is displayed there only when point is at
3446 the beginning of the @code{display} property or at
3447 @code{overlay-start}.
3449 @cindex cursor position for @code{display} properties and overlays
3450 When the buffer has many overlay strings (e.g., @pxref{Overlay
3451 Properties, before-string}) that conceal some of the buffer text or
3452 @code{display} properties that are strings, it is a good idea to use
3453 the @code{cursor} property on these strings to cue the Emacs display
3454 about the places where to put the cursor while traversing these
3455 strings. This directly communicates to the display engine where the
3456 Lisp program wants to put the cursor, or where the user would expect
3457 the cursor, when point is located on some buffer position that is
3458 ``covered'' by the display or overlay string.
3461 @kindex pointer @r{(text property)}
3462 This specifies a specific pointer shape when the mouse pointer is over
3463 this text or image. @xref{Pointer Shape}, for possible pointer
3467 @kindex line-spacing @r{(text property)}
3468 A newline can have a @code{line-spacing} text or overlay property that
3469 controls the height of the display line ending with that newline. The
3470 property value overrides the default frame line spacing and the buffer
3471 local @code{line-spacing} variable. @xref{Line Height}.
3474 @kindex line-height @r{(text property)}
3475 A newline can have a @code{line-height} text or overlay property that
3476 controls the total height of the display line ending in that newline.
3480 If text has a @code{wrap-prefix} property, the prefix it defines will
3481 be added at display time to the beginning of every continuation line
3482 due to text wrapping (so if lines are truncated, the wrap-prefix is
3483 never used). It may be a string or an image (@pxref{Other Display
3484 Specs}), or a stretch of whitespace such as specified by the
3485 @code{:width} or @code{:align-to} display properties (@pxref{Specified
3488 A wrap-prefix may also be specified for an entire buffer using the
3489 @code{wrap-prefix} buffer-local variable (however, a
3490 @code{wrap-prefix} text-property takes precedence over the value of
3491 the @code{wrap-prefix} variable). @xref{Truncation}.
3494 If text has a @code{line-prefix} property, the prefix it defines will
3495 be added at display time to the beginning of every non-continuation
3496 line. It may be a string or an image (@pxref{Other Display
3497 Specs}), or a stretch of whitespace such as specified by the
3498 @code{:width} or @code{:align-to} display properties (@pxref{Specified
3501 A line-prefix may also be specified for an entire buffer using the
3502 @code{line-prefix} buffer-local variable (however, a
3503 @code{line-prefix} text-property takes precedence over the value of
3504 the @code{line-prefix} variable). @xref{Truncation}.
3506 @item modification-hooks
3507 @cindex change hooks for a character
3508 @cindex hooks for changing a character
3509 @kindex modification-hooks @r{(text property)}
3510 If a character has the property @code{modification-hooks}, then its
3511 value should be a list of functions; modifying that character calls
3512 all of those functions before the actual modification. Each function
3513 receives two arguments: the beginning and end of the part of the
3514 buffer being modified. Note that if a particular modification hook
3515 function appears on several characters being modified by a single
3516 primitive, you can't predict how many times the function will
3518 Furthermore, insertion will not modify any existing character, so this
3519 hook will only be run when removing some characters, replacing them
3520 with others, or changing their text-properties.
3522 If these functions modify the buffer, they should bind
3523 @code{inhibit-modification-hooks} to @code{t} around doing so, to
3524 avoid confusing the internal mechanism that calls these hooks.
3526 Overlays also support the @code{modification-hooks} property, but the
3527 details are somewhat different (@pxref{Overlay Properties}).
3529 @item insert-in-front-hooks
3530 @itemx insert-behind-hooks
3531 @kindex insert-in-front-hooks @r{(text property)}
3532 @kindex insert-behind-hooks @r{(text property)}
3533 The operation of inserting text in a buffer also calls the functions
3534 listed in the @code{insert-in-front-hooks} property of the following
3535 character and in the @code{insert-behind-hooks} property of the
3536 preceding character. These functions receive two arguments, the
3537 beginning and end of the inserted text. The functions are called
3538 @emph{after} the actual insertion takes place.
3540 See also @ref{Change Hooks}, for other hooks that are called
3541 when you change text in a buffer.
3545 @cindex hooks for motion of point
3546 @kindex point-entered @r{(text property)}
3547 @kindex point-left @r{(text property)}
3548 The special properties @code{point-entered} and @code{point-left}
3549 record hook functions that report motion of point. Each time point
3550 moves, Emacs compares these two property values:
3554 the @code{point-left} property of the character after the old location,
3557 the @code{point-entered} property of the character after the new
3562 If these two values differ, each of them is called (if not @code{nil})
3563 with two arguments: the old value of point, and the new one.
3565 The same comparison is made for the characters before the old and new
3566 locations. The result may be to execute two @code{point-left} functions
3567 (which may be the same function) and/or two @code{point-entered}
3568 functions (which may be the same function). In any case, all the
3569 @code{point-left} functions are called first, followed by all the
3570 @code{point-entered} functions.
3572 It is possible to use @code{char-after} to examine characters at various
3573 buffer positions without moving point to those positions. Only an
3574 actual change in the value of point runs these hook functions.
3576 The variable @code{inhibit-point-motion-hooks} by default inhibits
3577 running the @code{point-left} and @code{point-entered} hooks, see
3578 @ref{Inhibit point motion hooks}.
3580 These properties are obsolete; please use
3581 @code{cursor-sensor-functions} instead.
3583 @item cursor-sensor-functions
3584 @kindex cursor-sensor-functions @r{(text property)}
3585 @findex cursor-sensor-mode
3586 This special property records a list of functions that react to cursor
3587 motion. Each function in the list is called, just before redisplay,
3588 with 3 arguments: the affected window, the previous known position of
3589 the cursor, and one of the symbols @code{entered} or @code{left},
3590 depending on whether the cursor is entering the text that has this
3591 property or leaving it. The functions are called only when the minor
3592 mode @code{cursor-sensor-mode} is turned on.
3595 @kindex composition @r{(text property)}
3596 This text property is used to display a sequence of characters as a
3597 single glyph composed from components. But the value of the property
3598 itself is completely internal to Emacs and should not be manipulated
3599 directly by, for instance, @code{put-text-property}.
3603 @defvar inhibit-point-motion-hooks
3604 @anchor{Inhibit point motion hooks} When this obsolete variable is
3605 non-@code{nil}, @code{point-left} and @code{point-entered} hooks are
3606 not run, and the @code{intangible} property has no effect. Do not set
3607 this variable globally; bind it with @code{let}. Since the affected
3608 properties are obsolete, this variable's default value is @code{t}, to
3609 effectively disable them.
3612 @defvar show-help-function
3613 @anchor{Help display} If this variable is non-@code{nil}, it specifies a
3614 function called to display help strings. These may be @code{help-echo}
3615 properties, menu help strings (@pxref{Simple Menu Items},
3616 @pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
3617 Bar}). The specified function is called with one argument, the help
3618 string to display, which is passed through
3619 @code{substitute-command-keys} before being given to the function; see
3620 @ref{Keys in Documentation}. Tooltip mode (@pxref{Tooltips,,, emacs,
3621 The GNU Emacs Manual}) provides an example.
3624 @node Format Properties
3625 @subsection Formatted Text Properties
3627 These text properties affect the behavior of the fill commands. They
3628 are used for representing formatted text. @xref{Filling}, and
3633 If a newline character has this property, it is a ``hard'' newline.
3634 The fill commands do not alter hard newlines and do not move words
3635 across them. However, this property takes effect only if the
3636 @code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft
3637 Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
3640 This property specifies an extra right margin for filling this part of the
3644 This property specifies an extra left margin for filling this part of the
3648 This property specifies the style of justification for filling this part
3652 @node Sticky Properties
3653 @subsection Stickiness of Text Properties
3654 @cindex sticky text properties
3655 @cindex inheritance, text property
3657 Self-inserting characters, the ones that get inserted into a buffer
3658 when the user types them (@pxref{Commands for Insertion}), normally
3659 take on the same properties as the preceding character. This is
3660 called @dfn{inheritance} of properties.
3662 By contrast, a Lisp program can do insertion with inheritance or without,
3663 depending on the choice of insertion primitive. The ordinary text
3664 insertion functions, such as @code{insert}, do not inherit any
3665 properties. They insert text with precisely the properties of the
3666 string being inserted, and no others. This is correct for programs
3667 that copy text from one context to another---for example, into or out
3668 of the kill ring. To insert with inheritance, use the special
3669 primitives described in this section. Self-inserting characters
3670 inherit properties because they work using these primitives.
3672 When you do insertion with inheritance, @emph{which} properties are
3673 inherited, and from where, depends on which properties are @dfn{sticky}.
3674 Insertion after a character inherits those of its properties that are
3675 @dfn{rear-sticky}. Insertion before a character inherits those of its
3676 properties that are @dfn{front-sticky}. When both sides offer different
3677 sticky values for the same property, the previous character's value
3680 By default, a text property is rear-sticky but not front-sticky; thus,
3681 the default is to inherit all the properties of the preceding character,
3682 and nothing from the following character.
3684 You can control the stickiness of various text properties with two
3685 specific text properties, @code{front-sticky} and @code{rear-nonsticky},
3686 and with the variable @code{text-property-default-nonsticky}. You can
3687 use the variable to specify a different default for a given property.
3688 You can use those two text properties to make any specific properties
3689 sticky or nonsticky in any particular part of the text.
3691 If a character's @code{front-sticky} property is @code{t}, then all
3692 its properties are front-sticky. If the @code{front-sticky} property is
3693 a list, then the sticky properties of the character are those whose
3694 names are in the list. For example, if a character has a
3695 @code{front-sticky} property whose value is @code{(face read-only)},
3696 then insertion before the character can inherit its @code{face} property
3697 and its @code{read-only} property, but no others.
3699 The @code{rear-nonsticky} property works the opposite way. Most
3700 properties are rear-sticky by default, so the @code{rear-nonsticky}
3701 property says which properties are @emph{not} rear-sticky. If a
3702 character's @code{rear-nonsticky} property is @code{t}, then none of its
3703 properties are rear-sticky. If the @code{rear-nonsticky} property is a
3704 list, properties are rear-sticky @emph{unless} their names are in the
3707 @defvar text-property-default-nonsticky
3708 This variable holds an alist which defines the default rear-stickiness
3709 of various text properties. Each element has the form
3710 @code{(@var{property} . @var{nonstickiness})}, and it defines the
3711 stickiness of a particular text property, @var{property}.
3713 If @var{nonstickiness} is non-@code{nil}, this means that the property
3714 @var{property} is rear-nonsticky by default. Since all properties are
3715 front-nonsticky by default, this makes @var{property} nonsticky in both
3716 directions by default.
3718 The text properties @code{front-sticky} and @code{rear-nonsticky}, when
3719 used, take precedence over the default @var{nonstickiness} specified in
3720 @code{text-property-default-nonsticky}.
3723 Here are the functions that insert text with inheritance of properties:
3725 @defun insert-and-inherit &rest strings
3726 Insert the strings @var{strings}, just like the function @code{insert},
3727 but inherit any sticky properties from the adjoining text.
3730 @defun insert-before-markers-and-inherit &rest strings
3731 Insert the strings @var{strings}, just like the function
3732 @code{insert-before-markers}, but inherit any sticky properties from the
3736 @xref{Insertion}, for the ordinary insertion functions which do not
3739 @node Lazy Properties
3740 @subsection Lazy Computation of Text Properties
3742 Instead of computing text properties for all the text in the buffer,
3743 you can arrange to compute the text properties for parts of the text
3744 when and if something depends on them.
3746 The primitive that extracts text from the buffer along with its
3747 properties is @code{buffer-substring}. Before examining the properties,
3748 this function runs the abnormal hook @code{buffer-access-fontify-functions}.
3750 @defvar buffer-access-fontify-functions
3751 This variable holds a list of functions for computing text properties.
3752 Before @code{buffer-substring} copies the text and text properties for a
3753 portion of the buffer, it calls all the functions in this list. Each of
3754 the functions receives two arguments that specify the range of the
3755 buffer being accessed. (The buffer itself is always the current
3759 The function @code{buffer-substring-no-properties} does not call these
3760 functions, since it ignores text properties anyway.
3762 In order to prevent the hook functions from being called more than
3763 once for the same part of the buffer, you can use the variable
3764 @code{buffer-access-fontified-property}.
3766 @defvar buffer-access-fontified-property
3767 If this variable's value is non-@code{nil}, it is a symbol which is used
3768 as a text property name. A non-@code{nil} value for that text property
3769 means the other text properties for this character have already been
3772 If all the characters in the range specified for @code{buffer-substring}
3773 have a non-@code{nil} value for this property, @code{buffer-substring}
3774 does not call the @code{buffer-access-fontify-functions} functions. It
3775 assumes these characters already have the right text properties, and
3776 just copies the properties they already have.
3778 The normal way to use this feature is that the
3779 @code{buffer-access-fontify-functions} functions add this property, as
3780 well as others, to the characters they operate on. That way, they avoid
3781 being called over and over for the same text.
3784 @node Clickable Text
3785 @subsection Defining Clickable Text
3786 @cindex clickable text
3787 @cindex follow links
3790 @dfn{Clickable text} is text that can be clicked, with either the
3791 mouse or via a keyboard command, to produce some result. Many major
3792 modes use clickable text to implement textual hyper-links, or
3793 @dfn{links} for short.
3795 The easiest way to insert and manipulate links is to use the
3796 @code{button} package. @xref{Buttons}. In this section, we will
3797 explain how to manually set up clickable text in a buffer, using text
3798 properties. For simplicity, we will refer to the clickable text as a
3801 Implementing a link involves three separate steps: (1) indicating
3802 clickability when the mouse moves over the link; (2) making @key{RET}
3803 or @kbd{mouse-2} on that link do something; and (3) setting up a
3804 @code{follow-link} condition so that the link obeys
3805 @code{mouse-1-click-follows-link}.
3807 To indicate clickability, add the @code{mouse-face} text property to
3808 the text of the link; then Emacs will highlight the link when the
3809 mouse moves over it. In addition, you should define a tooltip or echo
3810 area message, using the @code{help-echo} text property. @xref{Special
3811 Properties}. For instance, here is how Dired indicates that file
3812 names are clickable:
3815 (if (dired-move-to-filename)
3816 (add-text-properties
3819 (dired-move-to-end-of-filename)
3821 '(mouse-face highlight
3822 help-echo "mouse-2: visit this file in other window")))
3825 To make the link clickable, bind @key{RET} and @kbd{mouse-2} to
3826 commands that perform the desired action. Each command should check
3827 to see whether it was called on a link, and act accordingly. For
3828 instance, Dired's major mode keymap binds @kbd{mouse-2} to the
3832 (defun dired-mouse-find-file-other-window (event)
3833 "In Dired, visit the file or directory name you click on."
3835 (let ((window (posn-window (event-end event)))
3836 (pos (posn-point (event-end event)))
3838 (if (not (windowp window))
3839 (error "No file chosen"))
3840 (with-current-buffer (window-buffer window)
3842 (setq file (dired-get-file-for-visit)))
3843 (if (file-directory-p file)
3844 (or (and (cdr dired-subdir-alist)
3845 (dired-goto-subdir file))
3847 (select-window window)
3848 (dired-other-window file)))
3849 (select-window window)
3850 (find-file-other-window (file-name-sans-versions file t)))))
3854 This command uses the functions @code{posn-window} and
3855 @code{posn-point} to determine where the click occurred, and
3856 @code{dired-get-file-for-visit} to determine which file to visit.
3858 Instead of binding the mouse command in a major mode keymap, you can
3859 bind it within the link text, using the @code{keymap} text property
3860 (@pxref{Special Properties}). For instance:
3863 (let ((map (make-sparse-keymap)))
3864 (define-key map [mouse-2] 'operate-this-button)
3865 (put-text-property link-start link-end 'keymap map))
3869 With this method, you can easily define different commands for
3870 different links. Furthermore, the global definition of @key{RET} and
3871 @kbd{mouse-2} remain available for the rest of the text in the buffer.
3873 @vindex mouse-1-click-follows-link
3874 The basic Emacs command for clicking on links is @kbd{mouse-2}.
3875 However, for compatibility with other graphical applications, Emacs
3876 also recognizes @kbd{mouse-1} clicks on links, provided the user
3877 clicks on the link quickly without moving the mouse. This behavior is
3878 controlled by the user option @code{mouse-1-click-follows-link}.
3879 @xref{Mouse References,,, emacs, The GNU Emacs Manual}.
3881 @cindex follow-link (text or overlay property)
3882 To set up the link so that it obeys
3883 @code{mouse-1-click-follows-link}, you must either (1) apply a
3884 @code{follow-link} text or overlay property to the link text, or (2)
3885 bind the @code{follow-link} event to a keymap (which can be a major
3886 mode keymap or a local keymap specified via the @code{keymap} text
3887 property). The value of the @code{follow-link} property, or the
3888 binding for the @code{follow-link} event, acts as a condition for
3889 the link action. This condition tells Emacs two things: the
3890 circumstances under which a @kbd{mouse-1} click should be regarded as
3891 occurring inside the link, and how to compute an action code
3892 that says what to translate the @kbd{mouse-1} click into. The link
3893 action condition can be one of the following:
3896 @item @code{mouse-face}
3897 If the condition is the symbol @code{mouse-face}, a position is inside
3898 a link if there is a non-@code{nil} @code{mouse-face} property at that
3899 position. The action code is always @code{t}.
3901 For example, here is how Info mode handles @key{mouse-1}:
3904 (define-key Info-mode-map [follow-link] 'mouse-face)
3908 If the condition is a function, @var{func}, then a position @var{pos}
3909 is inside a link if @code{(@var{func} @var{pos})} evaluates to
3910 non-@code{nil}. The value returned by @var{func} serves as the action
3913 For example, here is how pcvs enables @kbd{mouse-1} to follow links on
3917 (define-key map [follow-link]
3919 (eq (get-char-property pos 'face) 'cvs-filename-face)))
3923 If the condition value is anything else, then the position is inside a
3924 link and the condition itself is the action code. Clearly, you should
3925 specify this kind of condition only when applying the condition via a
3926 text or property overlay on the link text (so that it does not apply
3927 to the entire buffer).
3931 The action code tells @kbd{mouse-1} how to follow the link:
3934 @item a string or vector
3935 If the action code is a string or vector, the @kbd{mouse-1} event is
3936 translated into the first element of the string or vector; i.e., the
3937 action of the @kbd{mouse-1} click is the local or global binding of
3938 that character or symbol. Thus, if the action code is @code{"foo"},
3939 @kbd{mouse-1} translates into @kbd{f}. If it is @code{[foo]},
3940 @kbd{mouse-1} translates into @key{foo}.
3943 For any other non-@code{nil} action code, the @kbd{mouse-1} event is
3944 translated into a @kbd{mouse-2} event at the same position.
3947 To define @kbd{mouse-1} to activate a button defined with
3948 @code{define-button-type}, give the button a @code{follow-link}
3949 property. The property value should be a link action condition, as
3950 described above. @xref{Buttons}. For example, here is how Help mode
3951 handles @kbd{mouse-1}:
3954 (define-button-type 'help-xref
3956 'action #'help-button-action)
3959 To define @kbd{mouse-1} on a widget defined with
3960 @code{define-widget}, give the widget a @code{:follow-link} property.
3961 The property value should be a link action condition, as described
3962 above. For example, here is how the @code{link} widget specifies that
3963 a @key{mouse-1} click shall be translated to @key{RET}:
3966 (define-widget 'link 'item
3968 :button-prefix 'widget-link-prefix
3969 :button-suffix 'widget-link-suffix
3971 :help-echo "Follow the link."
3975 @defun mouse-on-link-p pos
3976 This function returns non-@code{nil} if position @var{pos} in the
3977 current buffer is on a link. @var{pos} can also be a mouse event
3978 location, as returned by @code{event-start} (@pxref{Accessing Mouse}).
3982 @subsection Defining and Using Fields
3985 A field is a range of consecutive characters in the buffer that are
3986 identified by having the same value (comparing with @code{eq}) of the
3987 @code{field} property (either a text-property or an overlay property).
3988 This section describes special functions that are available for
3989 operating on fields.
3991 You specify a field with a buffer position, @var{pos}. We think of
3992 each field as containing a range of buffer positions, so the position
3993 you specify stands for the field containing that position.
3995 When the characters before and after @var{pos} are part of the same
3996 field, there is no doubt which field contains @var{pos}: the one those
3997 characters both belong to. When @var{pos} is at a boundary between
3998 fields, which field it belongs to depends on the stickiness of the
3999 @code{field} properties of the two surrounding characters (@pxref{Sticky
4000 Properties}). The field whose property would be inherited by text
4001 inserted at @var{pos} is the field that contains @var{pos}.
4003 There is an anomalous case where newly inserted text at @var{pos}
4004 would not inherit the @code{field} property from either side. This
4005 happens if the previous character's @code{field} property is not
4006 rear-sticky, and the following character's @code{field} property is not
4007 front-sticky. In this case, @var{pos} belongs to neither the preceding
4008 field nor the following field; the field functions treat it as belonging
4009 to an empty field whose beginning and end are both at @var{pos}.
4011 In all of these functions, if @var{pos} is omitted or @code{nil}, the
4012 value of point is used by default. If narrowing is in effect, then
4013 @var{pos} should fall within the accessible portion. @xref{Narrowing}.
4015 @defun field-beginning &optional pos escape-from-edge limit
4016 This function returns the beginning of the field specified by @var{pos}.
4018 If @var{pos} is at the beginning of its field, and
4019 @var{escape-from-edge} is non-@code{nil}, then the return value is
4020 always the beginning of the preceding field that @emph{ends} at @var{pos},
4021 regardless of the stickiness of the @code{field} properties around
4024 If @var{limit} is non-@code{nil}, it is a buffer position; if the
4025 beginning of the field is before @var{limit}, then @var{limit} will be
4029 @defun field-end &optional pos escape-from-edge limit
4030 This function returns the end of the field specified by @var{pos}.
4032 If @var{pos} is at the end of its field, and @var{escape-from-edge} is
4033 non-@code{nil}, then the return value is always the end of the following
4034 field that @emph{begins} at @var{pos}, regardless of the stickiness of
4035 the @code{field} properties around @var{pos}.
4037 If @var{limit} is non-@code{nil}, it is a buffer position; if the end
4038 of the field is after @var{limit}, then @var{limit} will be returned
4042 @defun field-string &optional pos
4043 This function returns the contents of the field specified by @var{pos},
4047 @defun field-string-no-properties &optional pos
4048 This function returns the contents of the field specified by @var{pos},
4049 as a string, discarding text properties.
4052 @defun delete-field &optional pos
4053 This function deletes the text of the field specified by @var{pos}.
4056 @defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
4057 This function constrains @var{new-pos} to the field that
4058 @var{old-pos} belongs to---in other words, it returns the position
4059 closest to @var{new-pos} that is in the same field as @var{old-pos}.
4061 If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
4062 the value of point instead, and moves point to the resulting position
4063 in addition to returning that position.
4065 If @var{old-pos} is at the boundary of two fields, then the acceptable
4066 final positions depend on the argument @var{escape-from-edge}. If
4067 @var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in
4068 the field whose @code{field} property equals what new characters
4069 inserted at @var{old-pos} would inherit. (This depends on the
4070 stickiness of the @code{field} property for the characters before and
4071 after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
4072 @var{new-pos} can be anywhere in the two adjacent fields.
4073 Additionally, if two fields are separated by another field with the
4074 special value @code{boundary}, then any point within this special
4075 field is also considered to be on the boundary.
4077 Commands like @kbd{C-a} with no argument, that normally move backward
4078 to a specific kind of location and stay there once there, probably
4079 should specify @code{nil} for @var{escape-from-edge}. Other motion
4080 commands that check fields should probably pass @code{t}.
4082 If the optional argument @var{only-in-line} is non-@code{nil}, and
4083 constraining @var{new-pos} in the usual way would move it to a different
4084 line, @var{new-pos} is returned unconstrained. This used in commands
4085 that move by line, such as @code{next-line} and
4086 @code{beginning-of-line}, so that they respect field boundaries only in
4087 the case where they can still move to the right line.
4089 If the optional argument @var{inhibit-capture-property} is
4090 non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that
4091 name, then any field boundaries are ignored.
4093 You can cause @code{constrain-to-field} to ignore all field boundaries
4094 (and so never constrain anything) by binding the variable
4095 @code{inhibit-field-text-motion} to a non-@code{nil} value.
4099 @subsection Why Text Properties are not Intervals
4102 Some editors that support adding attributes to text in the buffer do
4103 so by letting the user specify intervals within the text, and adding
4104 the properties to the intervals. Those editors permit the user or the
4105 programmer to determine where individual intervals start and end. We
4106 deliberately provided a different sort of interface in Emacs Lisp to
4107 avoid certain paradoxical behavior associated with text modification.
4109 If the actual subdivision into intervals is meaningful, that means you
4110 can distinguish between a buffer that is just one interval with a
4111 certain property, and a buffer containing the same text subdivided into
4112 two intervals, both of which have that property.
4114 Suppose you take the buffer with just one interval and kill part of
4115 the text. The text remaining in the buffer is one interval, and the
4116 copy in the kill ring (and the undo list) becomes a separate interval.
4117 Then if you yank back the killed text, you get two intervals with the
4118 same properties. Thus, editing does not preserve the distinction
4119 between one interval and two.
4121 Suppose we attempt to fix this problem by coalescing the two intervals when
4122 the text is inserted. That works fine if the buffer originally was a
4123 single interval. But suppose instead that we have two adjacent
4124 intervals with the same properties, and we kill the text of one interval
4125 and yank it back. The same interval-coalescence feature that rescues
4126 the other case causes trouble in this one: after yanking, we have just
4127 one interval. Once again, editing does not preserve the distinction
4128 between one interval and two.
4130 Insertion of text at the border between intervals also raises
4131 questions that have no satisfactory answer.
4133 However, it is easy to arrange for editing to behave consistently
4134 for questions of the form, ``What are the properties of text at this
4135 buffer or string position?'' So we have decided these are the only
4136 questions that make sense; we have not implemented asking questions
4137 about where intervals start or end.
4139 In practice, you can usually use the text property search functions in
4140 place of explicit interval boundaries. You can think of them as finding
4141 the boundaries of intervals, assuming that intervals are always
4142 coalesced whenever possible. @xref{Property Search}.
4144 Emacs also provides explicit intervals as a presentation feature; see
4148 @section Substituting for a Character Code
4149 @cindex replace characters in region
4150 @cindex substitute characters
4152 The following functions replace characters within a specified region
4153 based on their character codes.
4155 @defun subst-char-in-region start end old-char new-char &optional noundo
4156 @cindex replace characters
4157 This function replaces all occurrences of the character @var{old-char}
4158 with the character @var{new-char} in the region of the current buffer
4159 defined by @var{start} and @var{end}.
4161 @cindex undo avoidance
4162 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
4163 not record the change for undo and does not mark the buffer as modified.
4164 This was useful for controlling the old selective display feature
4165 (@pxref{Selective Display}).
4167 @code{subst-char-in-region} does not move point and returns
4172 ---------- Buffer: foo ----------
4173 This is the contents of the buffer before.
4174 ---------- Buffer: foo ----------
4178 (subst-char-in-region 1 20 ?i ?X)
4181 ---------- Buffer: foo ----------
4182 ThXs Xs the contents of the buffer before.
4183 ---------- Buffer: foo ----------
4188 @deffn Command translate-region start end table
4189 This function applies a translation table to the characters in the
4190 buffer between positions @var{start} and @var{end}.
4192 The translation table @var{table} is a string or a char-table;
4193 @code{(aref @var{table} @var{ochar})} gives the translated character
4194 corresponding to @var{ochar}. If @var{table} is a string, any
4195 characters with codes larger than the length of @var{table} are not
4196 altered by the translation.
4198 The return value of @code{translate-region} is the number of
4199 characters that were actually changed by the translation. This does
4200 not count characters that were mapped into themselves in the
4208 A register is a sort of variable used in Emacs editing that can hold a
4209 variety of different kinds of values. Each register is named by a
4210 single character. All @acronym{ASCII} characters and their meta variants
4211 (but with the exception of @kbd{C-g}) can be used to name registers.
4212 Thus, there are 255 possible registers. A register is designated in
4213 Emacs Lisp by the character that is its name.
4215 @defvar register-alist
4216 This variable is an alist of elements of the form @code{(@var{name} .
4217 @var{contents})}. Normally, there is one element for each Emacs
4218 register that has been used.
4220 The object @var{name} is a character (an integer) identifying the
4224 The @var{contents} of a register can have several possible types:
4228 A number stands for itself. If @code{insert-register} finds a number
4229 in the register, it converts the number to decimal.
4232 A marker represents a buffer position to jump to.
4235 A string is text saved in the register.
4238 A rectangle is represented by a list of strings.
4240 @item @code{(@var{window-configuration} @var{position})}
4241 This represents a window configuration to restore in one frame, and a
4242 position to jump to in the current buffer.
4244 @c FIXME: Mention frameset here.
4245 @item @code{(@var{frame-configuration} @var{position})}
4246 This represents a frame configuration to restore, and a position
4247 to jump to in the current buffer.
4249 @item (file @var{filename})
4250 This represents a file to visit; jumping to this value visits file
4253 @item (file-query @var{filename} @var{position})
4254 This represents a file to visit and a position in it; jumping to this
4255 value visits file @var{filename} and goes to buffer position
4256 @var{position}. Restoring this type of position asks the user for
4260 The functions in this section return unpredictable values unless
4263 @defun get-register reg
4264 This function returns the contents of the register
4265 @var{reg}, or @code{nil} if it has no contents.
4268 @defun set-register reg value
4269 This function sets the contents of register @var{reg} to @var{value}.
4270 A register can be set to any value, but the other register functions
4271 expect only certain data types. The return value is @var{value}.
4274 @deffn Command view-register reg
4275 This command displays what is contained in register @var{reg}.
4278 @deffn Command insert-register reg &optional beforep
4279 This command inserts contents of register @var{reg} into the current
4282 Normally, this command puts point before the inserted text, and the
4283 mark after it. However, if the optional second argument @var{beforep}
4284 is non-@code{nil}, it puts the mark before and point after.
4286 When called interactively, the command defaults to putting point after
4287 text, and a prefix argument inverts this behavior.
4289 If the register contains a rectangle, then the rectangle is inserted
4290 with its upper left corner at point. This means that text is inserted
4291 in the current line and underneath it on successive lines.
4293 If the register contains something other than saved text (a string) or
4294 a rectangle (a list), currently useless things happen. This may be
4295 changed in the future.
4298 @defun register-read-with-preview prompt
4299 @cindex register preview
4300 This function reads and returns a register name, prompting with
4301 @var{prompt} and possibly showing a preview of the existing registers
4302 and their contents. The preview is shown in a temporary window, after
4303 the delay specified by the user option @code{register-preview-delay},
4304 if its value and @code{register-alist} are both non-@code{nil}. The
4305 preview is also shown if the user requests help (e.g., by typing the
4306 help character). We recommend that all interactive commands which
4307 read register names use this function.
4311 @section Transposition of Text
4313 This function can be used to transpose stretches of text:
4315 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
4316 This function exchanges two nonoverlapping portions of the buffer.
4317 Arguments @var{start1} and @var{end1} specify the bounds of one portion
4318 and arguments @var{start2} and @var{end2} specify the bounds of the
4321 Normally, @code{transpose-regions} relocates markers with the transposed
4322 text; a marker previously positioned within one of the two transposed
4323 portions moves along with that portion, thus remaining between the same
4324 two characters in their new position. However, if @var{leave-markers}
4325 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
4326 all markers unrelocated.
4330 @section Dealing With Compressed Data
4332 When @code{auto-compression-mode} is enabled, Emacs automatically
4333 uncompresses compressed files when you visit them, and automatically
4334 recompresses them if you alter and save them. @xref{Compressed
4335 Files,,, emacs, The GNU Emacs Manual}.
4337 The above feature works by calling an external executable (e.g.,
4338 @command{gzip}). Emacs can also be compiled with support for built-in
4339 decompression using the zlib library, which is faster than calling an
4342 @defun zlib-available-p
4343 This function returns non-@code{nil} if built-in zlib decompression is
4347 @defun zlib-decompress-region start end
4348 This function decompresses the region between @var{start} and
4349 @var{end}, using built-in zlib decompression. The region should
4350 contain data that were compressed with gzip or zlib. On success, the
4351 function replaces the contents of the region with the decompressed
4352 data. On failure, the function leaves the region unchanged and
4353 returns @code{nil}. This function can be called only in unibyte
4359 @section Base 64 Encoding
4360 @cindex base 64 encoding
4362 Base 64 code is used in email to encode a sequence of 8-bit bytes as
4363 a longer sequence of @acronym{ASCII} graphic characters. It is defined in
4364 Internet RFC@footnote{
4365 An RFC, an acronym for @dfn{Request for Comments}, is a numbered
4366 Internet informational document describing a standard. RFCs are
4367 usually written by technical experts acting on their own initiative,
4368 and are traditionally written in a pragmatic, experience-driven
4370 }2045. This section describes the functions for
4371 converting to and from this code.
4373 @deffn Command base64-encode-region beg end &optional no-line-break
4374 This function converts the region from @var{beg} to @var{end} into base
4375 64 code. It returns the length of the encoded text. An error is
4376 signaled if a character in the region is multibyte, i.e., in a
4377 multibyte buffer the region must contain only characters from the
4378 charsets @code{ascii}, @code{eight-bit-control} and
4379 @code{eight-bit-graphic}.
4381 Normally, this function inserts newline characters into the encoded
4382 text, to avoid overlong lines. However, if the optional argument
4383 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
4384 the output is just one long line.
4387 @defun base64-encode-string string &optional no-line-break
4388 This function converts the string @var{string} into base 64 code. It
4389 returns a string containing the encoded text. As for
4390 @code{base64-encode-region}, an error is signaled if a character in the
4391 string is multibyte.
4393 Normally, this function inserts newline characters into the encoded
4394 text, to avoid overlong lines. However, if the optional argument
4395 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
4396 the result string is just one long line.
4399 @deffn Command base64-decode-region beg end
4400 This function converts the region from @var{beg} to @var{end} from base
4401 64 code into the corresponding decoded text. It returns the length of
4404 The decoding functions ignore newline characters in the encoded text.
4407 @defun base64-decode-string string
4408 This function converts the string @var{string} from base 64 code into
4409 the corresponding decoded text. It returns a unibyte string containing the
4412 The decoding functions ignore newline characters in the encoded text.
4416 @section Checksum/Hash
4417 @cindex MD5 checksum
4419 @cindex hash, cryptographic
4420 @cindex cryptographic hash
4422 Emacs has built-in support for computing @dfn{cryptographic hashes}.
4423 A cryptographic hash, or @dfn{checksum}, is a digital fingerprint
4424 of a piece of data (e.g., a block of text) which can be used to check
4425 that you have an unaltered copy of that data.
4427 @cindex message digest
4428 Emacs supports several common cryptographic hash algorithms: MD5,
4429 SHA-1, SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512. MD5 is the
4430 oldest of these algorithms, and is commonly used in @dfn{message
4431 digests} to check the integrity of messages transmitted over a
4432 network. MD5 is not collision resistant (i.e., it is possible to
4433 deliberately design different pieces of data which have the same MD5
4434 hash), so you should not used it for anything security-related. A
4435 similar theoretical weakness also exists in SHA-1. Therefore, for
4436 security-related applications you should use the other hash types,
4439 @defun secure-hash algorithm object &optional start end binary
4440 This function returns a hash for @var{object}. The argument
4441 @var{algorithm} is a symbol stating which hash to compute: one of
4442 @code{md5}, @code{sha1}, @code{sha224}, @code{sha256}, @code{sha384}
4443 or @code{sha512}. The argument @var{object} should be a buffer or a
4446 The optional arguments @var{start} and @var{end} are character
4447 positions specifying the portion of @var{object} to compute the
4448 message digest for. If they are @code{nil} or omitted, the hash is
4449 computed for the whole of @var{object}.
4451 If the argument @var{binary} is omitted or @code{nil}, the function
4452 returns the @dfn{text form} of the hash, as an ordinary Lisp string.
4453 If @var{binary} is non-@code{nil}, it returns the hash in @dfn{binary
4454 form}, as a sequence of bytes stored in a unibyte string.
4456 This function does not compute the hash directly from the internal
4457 representation of @var{object}'s text (@pxref{Text Representations}).
4458 Instead, it encodes the text using a coding system (@pxref{Coding
4459 Systems}), and computes the hash from that encoded text. If
4460 @var{object} is a buffer, the coding system used is the one which
4461 would be chosen by default for writing the text into a file. If
4462 @var{object} is a string, the user's preferred coding system is used
4463 (@pxref{Recognize Coding,,, emacs, GNU Emacs Manual}).
4466 @defun md5 object &optional start end coding-system noerror
4467 This function returns an MD5 hash. It is semi-obsolete, since for
4468 most purposes it is equivalent to calling @code{secure-hash} with
4469 @code{md5} as the @var{algorithm} argument. The @var{object},
4470 @var{start} and @var{end} arguments have the same meanings as in
4473 If @var{coding-system} is non-@code{nil}, it specifies a coding system
4474 to use to encode the text; if omitted or @code{nil}, the default
4475 coding system is used, like in @code{secure-hash}.
4477 Normally, @code{md5} signals an error if the text can't be encoded
4478 using the specified or chosen coding system. However, if
4479 @var{noerror} is non-@code{nil}, it silently uses @code{raw-text}
4483 @defun buffer-hash &optional buffer-or-name
4484 Return a hash of @var{buffer-or-name}. If @code{nil}, this defaults
4485 to the current buffer. As opposed to @code{secure-hash}, this
4486 function computes the hash based on the internal representation of the
4487 buffer, disregarding any coding systems. It's therefore only useful
4488 when comparing two buffers running in the same Emacs, and is not
4489 guaranteed to return the same hash between different Emacs versions.
4490 It should be somewhat more efficient on larger buffers than
4491 @code{secure-hash} is, and should not allocate more memory.
4492 @c Note that we do not document what hashing function we're using, or
4493 @c even whether it's a cryptographic hash, since that may change
4494 @c according to what we find useful.
4497 @node Parsing HTML/XML
4498 @section Parsing HTML and XML
4499 @cindex parsing html
4501 When Emacs is compiled with libxml2 support, the following functions
4502 are available to parse HTML or XML text into Lisp object trees.
4504 @defun libxml-parse-html-region start end &optional base-url discard-comments
4505 This function parses the text between @var{start} and @var{end} as
4506 HTML, and returns a list representing the HTML @dfn{parse tree}. It
4507 attempts to handle real-world HTML by robustly coping with syntax
4510 The optional argument @var{base-url}, if non-@code{nil}, should be a
4511 string specifying the base URL for relative URLs occurring in links.
4513 If the optional argument @var{discard-comments} is non-@code{nil},
4514 then the parse tree is created without any comments.
4516 In the parse tree, each HTML node is represented by a list in which
4517 the first element is a symbol representing the node name, the second
4518 element is an alist of node attributes, and the remaining elements are
4521 The following example demonstrates this. Given this (malformed) HTML
4525 <html><head></head><body width=101><div class=thing>Foo<div>Yes
4529 A call to @code{libxml-parse-html-region} returns this @acronym{DOM}
4530 (document object model):
4535 (body ((width . "101"))
4536 (div ((class . "thing"))
4543 @cindex rendering html
4544 @defun shr-insert-document dom
4545 This function renders the parsed HTML in @var{dom} into the current
4546 buffer. The argument @var{dom} should be a list as generated by
4547 @code{libxml-parse-html-region}. This function is, e.g., used by
4548 @ref{Top, EWW,, eww, The Emacs Web Wowser Manual}.
4552 @defun libxml-parse-xml-region start end &optional base-url discard-comments
4553 This function is the same as @code{libxml-parse-html-region}, except
4554 that it parses the text as XML rather than HTML (so it is stricter
4559 * Document Object Model:: Access, manipulate and search the @acronym{DOM}.
4562 @node Document Object Model
4563 @subsection Document Object Model
4567 @cindex Document Object Model
4569 The @acronym{DOM} returned by @code{libxml-parse-html-region} (and the
4570 other @acronym{XML} parsing functions) is a tree structure where each
4571 node has a node name (called a @dfn{tag}), and optional key/value
4572 @dfn{attribute} list, and then a list of @dfn{child nodes}. The child
4573 nodes are either strings or @acronym{DOM} objects.
4576 (body ((width . "101"))
4577 (div ((class . "thing"))
4583 @defun dom-node tag &optional attributes &rest children
4584 This function creates a @acronym{DOM} node of type @var{tag}. If
4585 given, @var{attributes} should be a key/value pair list.
4586 If given, @var{children} should be @acronym{DOM} nodes.
4589 The following functions can be used to work with this structure. Each
4590 function takes a @acronym{DOM} node, or a list of nodes. In the
4591 latter case, only the first node in the list is used.
4596 @item dom-tag @var{node}
4597 Return the @dfn{tag} (also called ``node name'') of the node.
4599 @item dom-attr @var{node} @var{attribute}
4600 Return the value of @var{attribute} in the node. A common usage
4604 (dom-attr img 'href)
4605 => "http://fsf.org/logo.png"
4608 @item dom-children @var{node}
4609 Return all the children of the node.
4611 @item dom-non-text-children @var{node}
4612 Return all the non-string children of the node.
4614 @item dom-attributes @var{node}
4615 Return the key/value pair list of attributes of the node.
4617 @item dom-text @var{node}
4618 Return all the textual elements of the node as a concatenated string.
4620 @item dom-texts @var{node}
4621 Return all the textual elements of the node, as well as the textual
4622 elements of all the children of the node, recursively, as a
4623 concatenated string. This function also takes an optional separator
4624 to be inserted between the textual elements.
4626 @item dom-parent @var{dom} @var{node}
4627 Return the parent of @var{node} in @var{dom}.
4629 @item dom-remove @var{dom} @var{node}
4630 Remove @var{node} from @var{dom}.
4633 The following are functions for altering the @acronym{DOM}.
4636 @item dom-set-attribute @var{node} @var{attribute} @var{value}
4637 Set the @var{attribute} of the node to @var{value}.
4639 @item dom-append-child @var{node} @var{child}
4640 Append @var{child} as the last child of @var{node}.
4642 @item dom-add-child-before @var{node} @var{child} @var{before}
4643 Add @var{child} to @var{node}'s child list before the @var{before}
4644 node. If @var{before} is @code{nil}, make @var{child} the first child.
4646 @item dom-set-attributes @var{node} @var{attributes}
4647 Replace all the attributes of the node with a new key/value list.
4650 The following are functions for searching for elements in the
4651 @acronym{DOM}. They all return lists of matching nodes.
4654 @item dom-by-tag @var{dom} @var{tag}
4655 Return all nodes in @var{dom} that are of type @var{tag}. A typical
4659 (dom-by-tag dom 'td)
4660 => '((td ...) (td ...) (td ...))
4663 @item dom-by-class @var{dom} @var{match}
4664 Return all nodes in @var{dom} that have class names that match
4665 @var{match}, which is a regular expression.
4667 @item dom-by-style @var{dom} @var{style}
4668 Return all nodes in @var{dom} that have styles that match @var{match},
4669 which is a regular expression.
4671 @item dom-by-id @var{dom} @var{style}
4672 Return all nodes in @var{dom} that have IDs that match @var{match},
4673 which is a regular expression.
4675 @item dom-strings @var{dom}
4676 Return all strings in @var{dom}.
4683 @item dom-pp @var{dom} &optional @var{remove-empty}
4684 Pretty-print @var{dom} at point. If @var{remove-empty}, don't print
4685 textual nodes that just contain white-space.
4689 @node Atomic Changes
4690 @section Atomic Change Groups
4691 @cindex atomic changes
4693 In database terminology, an @dfn{atomic} change is an indivisible
4694 change---it can succeed entirely or it can fail entirely, but it
4695 cannot partly succeed. A Lisp program can make a series of changes to
4696 one or several buffers as an @dfn{atomic change group}, meaning that
4697 either the entire series of changes will be installed in their buffers
4698 or, in case of an error, none of them will be.
4700 To do this for one buffer, the one already current, simply write a
4701 call to @code{atomic-change-group} around the code that makes the
4705 (atomic-change-group
4707 (delete-region x y))
4711 If an error (or other nonlocal exit) occurs inside the body of
4712 @code{atomic-change-group}, it unmakes all the changes in that buffer
4713 that were during the execution of the body. This kind of change group
4714 has no effect on any other buffers---any such changes remain.
4716 If you need something more sophisticated, such as to make changes in
4717 various buffers constitute one atomic group, you must directly call
4718 lower-level functions that @code{atomic-change-group} uses.
4720 @defun prepare-change-group &optional buffer
4721 This function sets up a change group for buffer @var{buffer}, which
4722 defaults to the current buffer. It returns a handle that
4723 represents the change group. You must use this handle to activate the
4724 change group and subsequently to finish it.
4727 To use the change group, you must @dfn{activate} it. You must do
4728 this before making any changes in the text of @var{buffer}.
4730 @defun activate-change-group handle
4731 This function activates the change group that @var{handle} designates.
4734 After you activate the change group, any changes you make in that
4735 buffer become part of it. Once you have made all the desired changes
4736 in the buffer, you must @dfn{finish} the change group. There are two
4737 ways to do this: you can either accept (and finalize) all the changes,
4740 @defun accept-change-group handle
4741 This function accepts all the changes in the change group specified by
4742 @var{handle}, making them final.
4745 @defun cancel-change-group handle
4746 This function cancels and undoes all the changes in the change group
4747 specified by @var{handle}.
4750 Your code should use @code{unwind-protect} to make sure the group is
4751 always finished. The call to @code{activate-change-group} should be
4752 inside the @code{unwind-protect}, in case the user types @kbd{C-g}
4753 just after it runs. (This is one reason why
4754 @code{prepare-change-group} and @code{activate-change-group} are
4755 separate functions, because normally you would call
4756 @code{prepare-change-group} before the start of that
4757 @code{unwind-protect}.) Once you finish the group, don't use the
4758 handle again---in particular, don't try to finish the same group
4761 To make a multibuffer change group, call @code{prepare-change-group}
4762 once for each buffer you want to cover, then use @code{nconc} to
4763 combine the returned values, like this:
4766 (nconc (prepare-change-group buffer-1)
4767 (prepare-change-group buffer-2))
4770 You can then activate the multibuffer change group with a single call
4771 to @code{activate-change-group}, and finish it with a single call to
4772 @code{accept-change-group} or @code{cancel-change-group}.
4774 Nested use of several change groups for the same buffer works as you
4775 would expect. Non-nested use of change groups for the same buffer
4776 will get Emacs confused, so don't let it happen; the first change
4777 group you start for any given buffer should be the last one finished.
4780 @section Change Hooks
4781 @cindex change hooks
4782 @cindex hooks for text changes
4784 These hook variables let you arrange to take notice of changes in
4785 buffers (or in a particular buffer, if you make them buffer-local).
4786 See also @ref{Special Properties}, for how to detect changes to
4787 specific parts of the text.
4789 The functions you use in these hooks should save and restore the match
4790 data if they do anything that uses regular expressions; otherwise, they
4791 will interfere in bizarre ways with the editing operations that call
4794 @defvar before-change-functions
4795 This variable holds a list of functions to call when Emacs is about to
4796 modify a buffer. Each function gets two arguments, the beginning and
4797 end of the region that is about to change, represented as integers.
4798 The buffer that is about to change is always the current buffer when
4799 the function is called.
4802 @defvar after-change-functions
4803 This variable holds a list of functions to call after Emacs modifies a
4804 buffer. Each function receives three arguments: the beginning and end
4805 of the region just changed, and the length of the text that existed
4806 before the change. All three arguments are integers. The buffer that
4807 has been changed is always the current buffer when the function is
4810 The length of the old text is the difference between the buffer
4811 positions before and after that text as it was before the change. As
4812 for the changed text, its length is simply the difference between the
4813 first two arguments.
4816 Output of messages into the @file{*Messages*} buffer does not call
4817 these functions, and neither do certain internal buffer changes, such
4818 as changes in buffers created by Emacs internally for certain jobs,
4819 that should not be visible to Lisp programs.
4821 Do @emph{not} expect the before-change hooks and the after-change
4822 hooks be called in balanced pairs around each buffer change. Also
4823 don't expect the before-change hooks to be called for every chunk of
4824 text Emacs is about to delete. These hooks are provided on the
4825 assumption that Lisp programs will use either before- or the
4826 after-change hooks, but not both, and the boundaries of the region
4827 where the changes happen might include more than just the actual
4828 changed text, or even lump together several changes done piecemeal.
4830 @defmac combine-after-change-calls body@dots{}
4831 The macro executes @var{body} normally, but arranges to call the
4832 after-change functions just once for a series of several changes---if
4835 If a program makes several text changes in the same area of the buffer,
4836 using the macro @code{combine-after-change-calls} around that part of
4837 the program can make it run considerably faster when after-change hooks
4838 are in use. When the after-change hooks are ultimately called, the
4839 arguments specify a portion of the buffer including all of the changes
4840 made within the @code{combine-after-change-calls} body.
4842 @strong{Warning:} You must not alter the values of
4843 @code{after-change-functions} within
4844 the body of a @code{combine-after-change-calls} form.
4846 @strong{Warning:} if the changes you combine occur in widely scattered
4847 parts of the buffer, this will still work, but it is not advisable,
4848 because it may lead to inefficient behavior for some change hook
4852 @defvar first-change-hook
4853 This variable is a normal hook that is run whenever a buffer is changed
4854 that was previously in the unmodified state.
4857 @defvar inhibit-modification-hooks
4858 If this variable is non-@code{nil}, all of the change hooks are
4859 disabled; none of them run. This affects all the hook variables
4860 described above in this section, as well as the hooks attached to
4861 certain special text properties (@pxref{Special Properties}) and overlay
4862 properties (@pxref{Overlay Properties}).
4864 Also, this variable is bound to non-@code{nil} while running those
4865 same hook variables, so that by default modifying the buffer from
4866 a modification hook does not cause other modification hooks to be run.
4867 If you do want modification hooks to be run in a particular piece of
4868 code that is itself run from a modification hook, then rebind locally
4869 @code{inhibit-modification-hooks} to @code{nil}.