Conflate Qnil and Qunbound for `symbol-function'.
[emacs.git] / doc / lispref / text.texi
blob57df02b74a0a805ed387fc7c1db1baddbcb87d15
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @node Text
6 @chapter Text
7 @cindex text
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.
32 @menu
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 * Base 64::          Conversion to or from base 64 encoding.
58 * Checksum/Hash::    Computing cryptographic hashes.
59 * Parsing HTML/XML:: Parsing HTML and XML.
60 * Atomic Changes::   Installing several buffer changes "atomically".
61 * Change Hooks::     Supplying functions to be run when text is changed.
62 @end menu
64 @node Near Point
65 @section Examining Text Near Point
66 @cindex text near point
68   Many functions are provided to look at the characters around point.
69 Several simple functions are described here.  See also @code{looking-at}
70 in @ref{Regexp Search}.
72 In the following four functions, ``beginning'' or ``end'' of buffer
73 refers to the beginning or end of the accessible portion.
75 @defun char-after &optional position
76 This function returns the character in the current buffer at (i.e.,
77 immediately after) position @var{position}.  If @var{position} is out of
78 range for this purpose, either before the beginning of the buffer, or at
79 or beyond the end, then the value is @code{nil}.  The default for
80 @var{position} is point.
82 In the following example, assume that the first character in the
83 buffer is @samp{@@}:
85 @example
86 @group
87 (string (char-after 1))
88      @result{} "@@"
89 @end group
90 @end example
91 @end defun
93 @defun char-before &optional position
94 This function returns the character in the current buffer immediately
95 before position @var{position}.  If @var{position} is out of range for
96 this purpose, either at or before the beginning of the buffer, or beyond
97 the end, then the value is @code{nil}.  The default for
98 @var{position} is point.
99 @end defun
101 @defun following-char
102 This function returns the character following point in the current
103 buffer.  This is similar to @code{(char-after (point))}.  However, if
104 point is at the end of the buffer, then @code{following-char} returns 0.
106 Remember that point is always between characters, and the cursor
107 normally appears over the character following point.  Therefore, the
108 character returned by @code{following-char} is the character the
109 cursor is over.
111 In this example, point is between the @samp{a} and the @samp{c}.
113 @example
114 @group
115 ---------- Buffer: foo ----------
116 Gentlemen may cry ``Pea@point{}ce! Peace!,''
117 but there is no peace.
118 ---------- Buffer: foo ----------
119 @end group
121 @group
122 (string (preceding-char))
123      @result{} "a"
124 (string (following-char))
125      @result{} "c"
126 @end group
127 @end example
128 @end defun
130 @defun preceding-char
131 This function returns the character preceding point in the current
132 buffer.  See above, under @code{following-char}, for an example.  If
133 point is at the beginning of the buffer, @code{preceding-char} returns
135 @end defun
137 @defun bobp
138 This function returns @code{t} if point is at the beginning of the
139 buffer.  If narrowing is in effect, this means the beginning of the
140 accessible portion of the text.  See also @code{point-min} in
141 @ref{Point}.
142 @end defun
144 @defun eobp
145 This function returns @code{t} if point is at the end of the buffer.
146 If narrowing is in effect, this means the end of accessible portion of
147 the text.  See also @code{point-max} in @xref{Point}.
148 @end defun
150 @defun bolp
151 This function returns @code{t} if point is at the beginning of a line.
152 @xref{Text Lines}.  The beginning of the buffer (or of its accessible
153 portion) always counts as the beginning of a line.
154 @end defun
156 @defun eolp
157 This function returns @code{t} if point is at the end of a line.  The
158 end of the buffer (or of its accessible portion) is always considered
159 the end of a line.
160 @end defun
162 @node Buffer Contents
163 @section Examining Buffer Contents
165   This section describes functions that allow a Lisp program to
166 convert any portion of the text in the buffer into a string.
168 @defun buffer-substring start end
169 This function returns a string containing a copy of the text of the
170 region defined by positions @var{start} and @var{end} in the current
171 buffer.  If the arguments are not positions in the accessible portion
172 of the buffer, @code{buffer-substring} signals an
173 @code{args-out-of-range} error.
175 Here's an example which assumes Font-Lock mode is not enabled:
177 @example
178 @group
179 ---------- Buffer: foo ----------
180 This is the contents of buffer foo
182 ---------- Buffer: foo ----------
183 @end group
185 @group
186 (buffer-substring 1 10)
187      @result{} "This is t"
188 @end group
189 @group
190 (buffer-substring (point-max) 10)
191      @result{} "he contents of buffer foo\n"
192 @end group
193 @end example
195 If the text being copied has any text properties, these are copied into
196 the string along with the characters they belong to.  @xref{Text
197 Properties}.  However, overlays (@pxref{Overlays}) in the buffer and
198 their properties are ignored, not copied.
200 For example, if Font-Lock mode is enabled, you might get results like
201 these:
203 @example
204 @group
205 (buffer-substring 1 10)
206      @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t))
207 @end group
208 @end example
209 @end defun
211 @defun buffer-substring-no-properties start end
212 This is like @code{buffer-substring}, except that it does not copy text
213 properties, just the characters themselves.  @xref{Text Properties}.
214 @end defun
216 @defun buffer-string
217 This function returns the contents of the entire accessible portion of
218 the current buffer, as a string.
219 @end defun
221 @defun filter-buffer-substring start end &optional delete
222 This function passes the buffer text between @var{start} and @var{end}
223 through the filter functions specified by the wrapper hook
224 @code{filter-buffer-substring-functions}, and returns the result.  The
225 obsolete variable @code{buffer-substring-filters} is also consulted.
226 If both of these variables are @code{nil}, the value is the unaltered
227 text from the buffer, i.e.@: what @code{buffer-substring} would
228 return.
230 If @var{delete} is non-@code{nil}, this function deletes the text
231 between @var{start} and @var{end} after copying it, like
232 @code{delete-and-extract-region}.
234 Lisp code should use this function instead of @code{buffer-substring},
235 @code{buffer-substring-no-properties},
236 or @code{delete-and-extract-region} when copying into user-accessible
237 data structures such as the kill-ring, X clipboard, and registers.
238 Major and minor modes can add functions to
239 @code{filter-buffer-substring-functions} to alter such text as it is
240 copied out of the buffer.
241 @end defun
243 @defvar filter-buffer-substring-functions
244 This variable is a wrapper hook (@pxref{Running Hooks}), whose members
245 should be functions that accept four arguments: @var{fun},
246 @var{start}, @var{end}, and @var{delete}.  @var{fun} is a function
247 that takes three arguments (@var{start}, @var{end}, and @var{delete}),
248 and returns a string.  In both cases, the @var{start}, @var{end}, and
249 @var{delete} arguments are the same as those of
250 @code{filter-buffer-substring}.
252 The first hook function is passed a @var{fun} that is equivalent to
253 the default operation of @code{filter-buffer-substring}, i.e. it
254 returns the buffer-substring between @var{start} and @var{end}
255 (processed by any @code{buffer-substring-filters}) and optionally
256 deletes the original text from the buffer.  In most cases, the hook
257 function will call @var{fun} once, and then do its own processing of
258 the result.  The next hook function receives a @var{fun} equivalent to
259 this, and so on.  The actual return value is the result of all the
260 hook functions acting in sequence.
261 @end defvar
263 @defvar buffer-substring-filters
264 This variable is obsoleted by
265 @code{filter-buffer-substring-functions}, but is still supported for
266 backward compatibility.  Its value should should be a list of
267 functions which accept a single string argument and return another
268 string.  @code{filter-buffer-substring} passes the buffer substring to
269 the first function in this list, and the return value of each function
270 is passed to the next function.  The return value of the last function
271 is passed to @code{filter-buffer-substring-functions}.
272 @end defvar
274 @defun current-word &optional strict really-word
275 This function returns the symbol (or word) at or near point, as a
276 string.  The return value includes no text properties.
278 If the optional argument @var{really-word} is non-@code{nil}, it finds a
279 word; otherwise, it finds a symbol (which includes both word
280 characters and symbol constituent characters).
282 If the optional argument @var{strict} is non-@code{nil}, then point
283 must be in or next to the symbol or word---if no symbol or word is
284 there, the function returns @code{nil}.  Otherwise, a nearby symbol or
285 word on the same line is acceptable.
286 @end defun
288 @defun thing-at-point thing
289 Return the @var{thing} around or next to point, as a string.
291 The argument @var{thing} is a symbol which specifies a kind of syntactic
292 entity.  Possibilities include @code{symbol}, @code{list}, @code{sexp},
293 @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
294 @code{whitespace}, @code{line}, @code{page}, and others.
296 @example
297 ---------- Buffer: foo ----------
298 Gentlemen may cry ``Pea@point{}ce! Peace!,''
299 but there is no peace.
300 ---------- Buffer: foo ----------
302 (thing-at-point 'word)
303      @result{} "Peace"
304 (thing-at-point 'line)
305      @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
306 (thing-at-point 'whitespace)
307      @result{} nil
308 @end example
309 @end defun
311 @node Comparing Text
312 @section Comparing Text
313 @cindex comparing buffer text
315   This function lets you compare portions of the text in a buffer, without
316 copying them into strings first.
318 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
319 This function lets you compare two substrings of the same buffer or two
320 different buffers.  The first three arguments specify one substring,
321 giving a buffer (or a buffer name) and two positions within the
322 buffer.  The last three arguments specify the other substring in the
323 same way.  You can use @code{nil} for @var{buffer1}, @var{buffer2}, or
324 both to stand for the current buffer.
326 The value is negative if the first substring is less, positive if the
327 first is greater, and zero if they are equal.  The absolute value of
328 the result is one plus the index of the first differing characters
329 within the substrings.
331 This function ignores case when comparing characters
332 if @code{case-fold-search} is non-@code{nil}.  It always ignores
333 text properties.
335 Suppose the current buffer contains the text @samp{foobarbar
336 haha!rara!}; then in this example the two substrings are @samp{rbar }
337 and @samp{rara!}.  The value is 2 because the first substring is greater
338 at the second character.
340 @example
341 (compare-buffer-substrings nil 6 11 nil 16 21)
342      @result{} 2
343 @end example
344 @end defun
346 @node Insertion
347 @section Inserting Text
348 @cindex insertion of text
349 @cindex text insertion
351 @cindex insertion before point
352 @cindex before point, insertion
353   @dfn{Insertion} means adding new text to a buffer.  The inserted text
354 goes at point---between the character before point and the character
355 after point.  Some insertion functions leave point before the inserted
356 text, while other functions leave it after.  We call the former
357 insertion @dfn{after point} and the latter insertion @dfn{before point}.
359   Insertion moves markers located at positions after the insertion
360 point, so that they stay with the surrounding text (@pxref{Markers}).
361 When a marker points at the place of insertion, insertion may or may
362 not relocate the marker, depending on the marker's insertion type
363 (@pxref{Marker Insertion Types}).  Certain special functions such as
364 @code{insert-before-markers} relocate all such markers to point after
365 the inserted text, regardless of the markers' insertion type.
367   Insertion functions signal an error if the current buffer is
368 read-only or if they insert within read-only text.
370   These functions copy text characters from strings and buffers along
371 with their properties.  The inserted characters have exactly the same
372 properties as the characters they were copied from.  By contrast,
373 characters specified as separate arguments, not part of a string or
374 buffer, inherit their text properties from the neighboring text.
376   The insertion functions convert text from unibyte to multibyte in
377 order to insert in a multibyte buffer, and vice versa---if the text
378 comes from a string or from a buffer.  However, they do not convert
379 unibyte character codes 128 through 255 to multibyte characters, not
380 even if the current buffer is a multibyte buffer.  @xref{Converting
381 Representations}.
383 @defun insert &rest args
384 This function inserts the strings and/or characters @var{args} into the
385 current buffer, at point, moving point forward.  In other words, it
386 inserts the text before point.  An error is signaled unless all
387 @var{args} are either strings or characters.  The value is @code{nil}.
388 @end defun
390 @defun insert-before-markers &rest args
391 This function inserts the strings and/or characters @var{args} into the
392 current buffer, at point, moving point forward.  An error is signaled
393 unless all @var{args} are either strings or characters.  The value is
394 @code{nil}.
396 This function is unlike the other insertion functions in that it
397 relocates markers initially pointing at the insertion point, to point
398 after the inserted text.  If an overlay begins at the insertion point,
399 the inserted text falls outside the overlay; if a nonempty overlay
400 ends at the insertion point, the inserted text falls inside that
401 overlay.
402 @end defun
404 @deffn Command insert-char character &optional count inherit
405 This command inserts @var{count} instances of @var{character} into the
406 current buffer before point.  The argument @var{count} must be an
407 integer, and @var{character} must be a character.
409 If called interactively, this command prompts for @var{character}
410 using its Unicode name or its code point.  @xref{Inserting Text,,,
411 emacs, The GNU Emacs Manual}.
413 This function does not convert unibyte character codes 128 through 255
414 to multibyte characters, not even if the current buffer is a multibyte
415 buffer.  @xref{Converting Representations}.
417 If @var{inherit} is non-@code{nil}, the inserted characters inherit
418 sticky text properties from the two characters before and after the
419 insertion point.  @xref{Sticky Properties}.
420 @end deffn
422 @defun insert-buffer-substring from-buffer-or-name &optional start end
423 This function inserts a portion of buffer @var{from-buffer-or-name}
424 (which must already exist) into the current buffer before point.  The
425 text inserted is the region between @var{start} and @var{end}.  (These
426 arguments default to the beginning and end of the accessible portion of
427 that buffer.)  This function returns @code{nil}.
429 In this example, the form is executed with buffer @samp{bar} as the
430 current buffer.  We assume that buffer @samp{bar} is initially empty.
432 @example
433 @group
434 ---------- Buffer: foo ----------
435 We hold these truths to be self-evident, that all
436 ---------- Buffer: foo ----------
437 @end group
439 @group
440 (insert-buffer-substring "foo" 1 20)
441      @result{} nil
443 ---------- Buffer: bar ----------
444 We hold these truth@point{}
445 ---------- Buffer: bar ----------
446 @end group
447 @end example
448 @end defun
450 @defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
451 This is like @code{insert-buffer-substring} except that it does not
452 copy any text properties.
453 @end defun
455   @xref{Sticky Properties}, for other insertion functions that inherit
456 text properties from the nearby text in addition to inserting it.
457 Whitespace inserted by indentation functions also inherits text
458 properties.
460 @node Commands for Insertion
461 @section User-Level Insertion Commands
463   This section describes higher-level commands for inserting text,
464 commands intended primarily for the user but useful also in Lisp
465 programs.
467 @deffn Command insert-buffer from-buffer-or-name
468 This command inserts the entire accessible contents of
469 @var{from-buffer-or-name} (which must exist) into the current buffer
470 after point.  It leaves the mark after the inserted text.  The value
471 is @code{nil}.
472 @end deffn
474 @deffn Command self-insert-command count
475 @cindex character insertion
476 @cindex self-insertion
477 This command inserts the last character typed; it does so @var{count}
478 times, before point, and returns @code{nil}.  Most printing characters
479 are bound to this command.  In routine use, @code{self-insert-command}
480 is the most frequently called function in Emacs, but programs rarely use
481 it except to install it on a keymap.
483 In an interactive call, @var{count} is the numeric prefix argument.
485 Self-insertion translates the input character through
486 @code{translation-table-for-input}.  @xref{Translation of Characters}.
488 This command calls @code{auto-fill-function} whenever that is
489 non-@code{nil} and the character inserted is in the table
490 @code{auto-fill-chars} (@pxref{Auto Filling}).
492 @c Cross refs reworded to prevent overfull hbox.  --rjc 15mar92
493 This command performs abbrev expansion if Abbrev mode is enabled and
494 the inserted character does not have word-constituent
495 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)  It is also
496 responsible for calling @code{blink-paren-function} when the inserted
497 character has close parenthesis syntax (@pxref{Blinking}).
499 @vindex post-self-insert-hook
500 The final thing this command does is to run the hook
501 @code{post-self-insert-hook}.  You could use this to automatically
502 reindent text as it is typed, for example.
504 Do not try substituting your own definition of
505 @code{self-insert-command} for the standard one.  The editor command
506 loop handles this function specially.
507 @end deffn
509 @deffn Command newline &optional number-of-newlines
510 This command inserts newlines into the current buffer before point.
511 If @var{number-of-newlines} is supplied, that many newline characters
512 are inserted.
514 @cindex newline and Auto Fill mode
515 This function calls @code{auto-fill-function} if the current column
516 number is greater than the value of @code{fill-column} and
517 @var{number-of-newlines} is @code{nil}.  Typically what
518 @code{auto-fill-function} does is insert a newline; thus, the overall
519 result in this case is to insert two newlines at different places: one
520 at point, and another earlier in the line.  @code{newline} does not
521 auto-fill if @var{number-of-newlines} is non-@code{nil}.
523 This command indents to the left margin if that is not zero.
524 @xref{Margins}.
526 The value returned is @code{nil}.  In an interactive call, @var{count}
527 is the numeric prefix argument.
528 @end deffn
530 @defvar overwrite-mode
531 This variable controls whether overwrite mode is in effect.  The value
532 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
533 or @code{nil}.  @code{overwrite-mode-textual} specifies textual
534 overwrite mode (treats newlines and tabs specially), and
535 @code{overwrite-mode-binary} specifies binary overwrite mode (treats
536 newlines and tabs like any other characters).
537 @end defvar
539 @node Deletion
540 @section Deleting Text
541 @cindex text deletion
543 @cindex deleting text vs killing
544   Deletion means removing part of the text in a buffer, without saving
545 it in the kill ring (@pxref{The Kill Ring}).  Deleted text can't be
546 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
547 Some deletion functions do save text in the kill ring in some special
548 cases.
550   All of the deletion functions operate on the current buffer.
552 @deffn Command erase-buffer
553 This function deletes the entire text of the current buffer
554 (@emph{not} just the accessible portion), leaving it
555 empty.  If the buffer is read-only, it signals a @code{buffer-read-only}
556 error; if some of the text in it is read-only, it signals a
557 @code{text-read-only} error.  Otherwise, it deletes the text without
558 asking for any confirmation.  It returns @code{nil}.
560 Normally, deleting a large amount of text from a buffer inhibits further
561 auto-saving of that buffer ``because it has shrunk''.  However,
562 @code{erase-buffer} does not do this, the idea being that the future
563 text is not really related to the former text, and its size should not
564 be compared with that of the former text.
565 @end deffn
567 @deffn Command delete-region start end
568 This command deletes the text between positions @var{start} and
569 @var{end} in the current buffer, and returns @code{nil}.  If point was
570 inside the deleted region, its value afterward is @var{start}.
571 Otherwise, point relocates with the surrounding text, as markers do.
572 @end deffn
574 @defun delete-and-extract-region start end
575 This function deletes the text between positions @var{start} and
576 @var{end} in the current buffer, and returns a string containing the
577 text just deleted.
579 If point was inside the deleted region, its value afterward is
580 @var{start}.  Otherwise, point relocates with the surrounding text, as
581 markers do.
582 @end defun
584 @deffn Command delete-char count &optional killp
585 This command deletes @var{count} characters directly after point, or
586 before point if @var{count} is negative.  If @var{killp} is
587 non-@code{nil}, then it saves the deleted characters in the kill ring.
589 In an interactive call, @var{count} is the numeric prefix argument, and
590 @var{killp} is the unprocessed prefix argument.  Therefore, if a prefix
591 argument is supplied, the text is saved in the kill ring.  If no prefix
592 argument is supplied, then one character is deleted, but not saved in
593 the kill ring.
595 The value returned is always @code{nil}.
596 @end deffn
598 @deffn Command delete-backward-char count &optional killp
599 @cindex deleting previous char
600 This command deletes @var{count} characters directly before point, or
601 after point if @var{count} is negative.  If @var{killp} is
602 non-@code{nil}, then it saves the deleted characters in the kill ring.
604 In an interactive call, @var{count} is the numeric prefix argument, and
605 @var{killp} is the unprocessed prefix argument.  Therefore, if a prefix
606 argument is supplied, the text is saved in the kill ring.  If no prefix
607 argument is supplied, then one character is deleted, but not saved in
608 the kill ring.
610 The value returned is always @code{nil}.
611 @end deffn
613 @deffn Command backward-delete-char-untabify count &optional killp
614 @cindex tab deletion
615 This command deletes @var{count} characters backward, changing tabs
616 into spaces.  When the next character to be deleted is a tab, it is
617 first replaced with the proper number of spaces to preserve alignment
618 and then one of those spaces is deleted instead of the tab.  If
619 @var{killp} is non-@code{nil}, then the command saves the deleted
620 characters in the kill ring.
622 Conversion of tabs to spaces happens only if @var{count} is positive.
623 If it is negative, exactly @minus{}@var{count} characters after point
624 are deleted.
626 In an interactive call, @var{count} is the numeric prefix argument, and
627 @var{killp} is the unprocessed prefix argument.  Therefore, if a prefix
628 argument is supplied, the text is saved in the kill ring.  If no prefix
629 argument is supplied, then one character is deleted, but not saved in
630 the kill ring.
632 The value returned is always @code{nil}.
633 @end deffn
635 @defopt backward-delete-char-untabify-method
636 This option specifies how @code{backward-delete-char-untabify} should
637 deal with whitespace.  Possible values include @code{untabify}, the
638 default, meaning convert a tab to many spaces and delete one;
639 @code{hungry}, meaning delete all tabs and spaces before point with
640 one command; @code{all} meaning delete all tabs, spaces and newlines
641 before point, and @code{nil}, meaning do nothing special for
642 whitespace characters.
643 @end defopt
645 @node User-Level Deletion
646 @section User-Level Deletion Commands
648   This section describes higher-level commands for deleting text,
649 commands intended primarily for the user but useful also in Lisp
650 programs.
652 @deffn Command delete-horizontal-space &optional backward-only
653 @cindex deleting whitespace
654 This function deletes all spaces and tabs around point.  It returns
655 @code{nil}.
657 If @var{backward-only} is non-@code{nil}, the function deletes
658 spaces and tabs before point, but not after point.
660 In the following examples, we call @code{delete-horizontal-space} four
661 times, once on each line, with point between the second and third
662 characters on the line each time.
664 @example
665 @group
666 ---------- Buffer: foo ----------
667 I @point{}thought
668 I @point{}     thought
669 We@point{} thought
670 Yo@point{}u thought
671 ---------- Buffer: foo ----------
672 @end group
674 @group
675 (delete-horizontal-space)   ; @r{Four times.}
676      @result{} nil
678 ---------- Buffer: foo ----------
679 Ithought
680 Ithought
681 Wethought
682 You thought
683 ---------- Buffer: foo ----------
684 @end group
685 @end example
686 @end deffn
688 @deffn Command delete-indentation &optional join-following-p
689 This function joins the line point is on to the previous line, deleting
690 any whitespace at the join and in some cases replacing it with one
691 space.  If @var{join-following-p} is non-@code{nil},
692 @code{delete-indentation} joins this line to the following line
693 instead.  The function returns @code{nil}.
695 If there is a fill prefix, and the second of the lines being joined
696 starts with the prefix, then @code{delete-indentation} deletes the
697 fill prefix before joining the lines.  @xref{Margins}.
699 In the example below, point is located on the line starting
700 @samp{events}, and it makes no difference if there are trailing spaces
701 in the preceding line.
703 @smallexample
704 @group
705 ---------- Buffer: foo ----------
706 When in the course of human
707 @point{}    events, it becomes necessary
708 ---------- Buffer: foo ----------
709 @end group
711 (delete-indentation)
712      @result{} nil
714 @group
715 ---------- Buffer: foo ----------
716 When in the course of human@point{} events, it becomes necessary
717 ---------- Buffer: foo ----------
718 @end group
719 @end smallexample
721 After the lines are joined, the function @code{fixup-whitespace} is
722 responsible for deciding whether to leave a space at the junction.
723 @end deffn
725 @deffn Command fixup-whitespace
726 This function replaces all the horizontal whitespace surrounding point
727 with either one space or no space, according to the context.  It
728 returns @code{nil}.
730 At the beginning or end of a line, the appropriate amount of space is
731 none.  Before a character with close parenthesis syntax, or after a
732 character with open parenthesis or expression-prefix syntax, no space is
733 also appropriate.  Otherwise, one space is appropriate.  @xref{Syntax
734 Class Table}.
736 In the example below, @code{fixup-whitespace} is called the first time
737 with point before the word @samp{spaces} in the first line.  For the
738 second invocation, point is directly after the @samp{(}.
740 @smallexample
741 @group
742 ---------- Buffer: foo ----------
743 This has too many     @point{}spaces
744 This has too many spaces at the start of (@point{}   this list)
745 ---------- Buffer: foo ----------
746 @end group
748 @group
749 (fixup-whitespace)
750      @result{} nil
751 (fixup-whitespace)
752      @result{} nil
753 @end group
755 @group
756 ---------- Buffer: foo ----------
757 This has too many spaces
758 This has too many spaces at the start of (this list)
759 ---------- Buffer: foo ----------
760 @end group
761 @end smallexample
762 @end deffn
764 @deffn Command just-one-space &optional n
765 @comment !!SourceFile simple.el
766 This command replaces any spaces and tabs around point with a single
767 space, or @var{n} spaces if @var{n} is specified.  It returns
768 @code{nil}.
769 @end deffn
771 @deffn Command delete-blank-lines
772 This function deletes blank lines surrounding point.  If point is on a
773 blank line with one or more blank lines before or after it, then all but
774 one of them are deleted.  If point is on an isolated blank line, then it
775 is deleted.  If point is on a nonblank line, the command deletes all
776 blank lines immediately following it.
778 A blank line is defined as a line containing only tabs and spaces.
780 @code{delete-blank-lines} returns @code{nil}.
781 @end deffn
783 @node The Kill Ring
784 @section The Kill Ring
785 @cindex kill ring
787   @dfn{Kill functions} delete text like the deletion functions, but save
788 it so that the user can reinsert it by @dfn{yanking}.  Most of these
789 functions have @samp{kill-} in their name.  By contrast, the functions
790 whose names start with @samp{delete-} normally do not save text for
791 yanking (though they can still be undone); these are ``deletion''
792 functions.
794   Most of the kill commands are primarily for interactive use, and are
795 not described here.  What we do describe are the functions provided for
796 use in writing such commands.  You can use these functions to write
797 commands for killing text.  When you need to delete text for internal
798 purposes within a Lisp function, you should normally use deletion
799 functions, so as not to disturb the kill ring contents.
800 @xref{Deletion}.
802   Killed text is saved for later yanking in the @dfn{kill ring}.  This
803 is a list that holds a number of recent kills, not just the last text
804 kill.  We call this a ``ring'' because yanking treats it as having
805 elements in a cyclic order.  The list is kept in the variable
806 @code{kill-ring}, and can be operated on with the usual functions for
807 lists; there are also specialized functions, described in this section,
808 that treat it as a ring.
810   Some people think this use of the word ``kill'' is unfortunate, since
811 it refers to operations that specifically @emph{do not} destroy the
812 entities ``killed''.  This is in sharp contrast to ordinary life, in
813 which death is permanent and ``killed'' entities do not come back to
814 life.  Therefore, other metaphors have been proposed.  For example, the
815 term ``cut ring'' makes sense to people who, in pre-computer days, used
816 scissors and paste to cut up and rearrange manuscripts.  However, it
817 would be difficult to change the terminology now.
819 @menu
820 * Kill Ring Concepts::     What text looks like in the kill ring.
821 * Kill Functions::         Functions that kill text.
822 * Yanking::                How yanking is done.
823 * Yank Commands::          Commands that access the kill ring.
824 * Low-Level Kill Ring::    Functions and variables for kill ring access.
825 * Internals of Kill Ring:: Variables that hold kill ring data.
826 @end menu
828 @node Kill Ring Concepts
829 @subsection Kill Ring Concepts
831   The kill ring records killed text as strings in a list, most recent
832 first.  A short kill ring, for example, might look like this:
834 @example
835 ("some text" "a different piece of text" "even older text")
836 @end example
838 @noindent
839 When the list reaches @code{kill-ring-max} entries in length, adding a
840 new entry automatically deletes the last entry.
842   When kill commands are interwoven with other commands, each kill
843 command makes a new entry in the kill ring.  Multiple kill commands in
844 succession build up a single kill ring entry, which would be yanked as a
845 unit; the second and subsequent consecutive kill commands add text to
846 the entry made by the first one.
848   For yanking, one entry in the kill ring is designated the ``front'' of
849 the ring.  Some yank commands ``rotate'' the ring by designating a
850 different element as the ``front''.  But this virtual rotation doesn't
851 change the list itself---the most recent entry always comes first in the
852 list.
854 @node Kill Functions
855 @subsection Functions for Killing
857   @code{kill-region} is the usual subroutine for killing text.  Any
858 command that calls this function is a ``kill command'' (and should
859 probably have @samp{kill} in its name).  @code{kill-region} puts the
860 newly killed text in a new element at the beginning of the kill ring or
861 adds it to the most recent element.  It determines automatically (using
862 @code{last-command}) whether the previous command was a kill command,
863 and if so appends the killed text to the most recent entry.
865 @deffn Command kill-region start end
866 This function kills the text in the region defined by @var{start} and
867 @var{end}.  The text is deleted but saved in the kill ring, along with
868 its text properties.  The value is always @code{nil}.
870 In an interactive call, @var{start} and @var{end} are point and
871 the mark.
873 If the buffer or text is read-only, @code{kill-region} modifies the kill
874 ring just the same, then signals an error without modifying the buffer.
875 This is convenient because it lets the user use a series of kill
876 commands to copy text from a read-only buffer into the kill ring.
877 @end deffn
879 @defopt kill-read-only-ok
880 If this option is non-@code{nil}, @code{kill-region} does not signal an
881 error if the buffer or text is read-only.  Instead, it simply returns,
882 updating the kill ring but not changing the buffer.
883 @end defopt
885 @deffn Command copy-region-as-kill start end
886 This command saves the region defined by @var{start} and @var{end} on
887 the kill ring (including text properties), but does not delete the text
888 from the buffer.  It returns @code{nil}.
890 The command does not set @code{this-command} to @code{kill-region}, so a
891 subsequent kill command does not append to the same kill ring entry.
893 @c FIXME Why is it better?  Why isn't copy-region-as-kill obsolete then?
894 @c Why is it used in many places in Emacs?
895 In Lisp programs, it is better to use @code{kill-new} or
896 @code{kill-append} instead of this command.  @xref{Low-Level Kill Ring}.
897 @end deffn
899 @node Yanking
900 @subsection Yanking
902   Yanking means inserting text from the kill ring, but it does not
903 insert the text blindly.  The @code{yank} command, and related
904 commands, use @code{insert-for-yank} to perform special processing on
905 the text before it is inserted.
907 @defun insert-for-yank string
908 This function works like @code{insert}, except that it processes the
909 text in @var{string} according to the @code{yank-handler} text
910 property, as well as the variables @code{yank-handled-properties} and
911 @code{yank-excluded-properties} (see below), before inserting the
912 result into the current buffer.
913 @end defun
915 @defun insert-buffer-substring-as-yank buf &optional start end
916 This function resembles @code{insert-buffer-substring}, except that it
917 processes the text according to @code{yank-handled-properties} and
918 @code{yank-excluded-properties}.  (It does not handle the
919 @code{yank-handler} property, which does not normally occur in buffer
920 text anyway.)
921 @end defun
923   If you put a @code{yank-handler} text property on all or part of a
924 string, that alters how @code{insert-for-yank} inserts the string.  If
925 different parts of the string have different @code{yank-handler}
926 values (comparison being done with @code{eq}), each substring is
927 handled separately.  The property value must be a list of one to four
928 elements, with the following format (where elements after the first
929 may be omitted):
931 @example
932 (@var{function} @var{param} @var{noexclude} @var{undo})
933 @end example
935   Here is what the elements do:
937 @table @var
938 @item function
939 When @var{function} is non-@code{nil}, it is called instead of
940 @code{insert} to insert the string, with one argument---the string to
941 insert.
943 @item param
944 If @var{param} is present and non-@code{nil}, it replaces @var{string}
945 (or the substring of @var{string} being processed) as the object
946 passed to @var{function} (or @code{insert}).  For example, if
947 @var{function} is @code{yank-rectangle}, @var{param} should be a list
948 of strings to insert as a rectangle.
950 @item noexclude
951 If @var{noexclude} is present and non-@code{nil}, that disables the
952 normal action of @code{yank-handled-properties} and
953 @code{yank-excluded-properties} on the inserted string.
955 @item undo
956 If @var{undo} is present and non-@code{nil}, it is a function that will be
957 called by @code{yank-pop} to undo the insertion of the current object.
958 It is called with two arguments, the start and end of the current
959 region.  @var{function} can set @code{yank-undo-function} to override
960 the @var{undo} value.
961 @end table
963 @cindex yanking and text properties
964 @defopt yank-handled-properties
965 This variable specifies special text property handling conditions for
966 yanked text.  It takes effect after the text has been inserted (either
967 normally, or via the @code{yank-handler} property), and prior to
968 @code{yank-excluded-properties} taking effect.
970 The value should be an alist of elements @code{(@var{prop}
971 . @var{fun})}.  Each alist element is handled in order.  The inserted
972 text is scanned for stretches of text having text properties @code{eq}
973 to @var{prop}; for each such stretch, @var{fun} is called with three
974 arguments: the value of the property, and the start and end positions
975 of the text.
976 @end defopt
978 @defopt yank-excluded-properties
979 The value of this variable is the list of properties to remove from
980 inserted text.  Its default value contains properties that might lead
981 to annoying results, such as causing the text to respond to the mouse
982 or specifying key bindings.  It takes effect after
983 @code{yank-handled-properties}.
984 @end defopt
987 @node Yank Commands
988 @subsection Functions for Yanking
990   This section describes higher-level commands for yanking, which are
991 intended primarily for the user but useful also in Lisp programs.
992 Both @code{yank} and @code{yank-pop} honor the
993 @code{yank-excluded-properties} variable and @code{yank-handler} text
994 property (@pxref{Yanking}).
996 @deffn Command yank &optional arg
997 @cindex inserting killed text
998 This command inserts before point the text at the front of the kill
999 ring.  It sets the mark at the beginning of that text, using
1000 @code{push-mark} (@pxref{The Mark}), and puts point at the end.
1002 If @var{arg} is a non-@code{nil} list (which occurs interactively when
1003 the user types @kbd{C-u} with no digits), then @code{yank} inserts the
1004 text as described above, but puts point before the yanked text and
1005 sets the mark after it.
1007 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th
1008 most recently killed text---the @var{arg}th element of the kill ring
1009 list, counted cyclically from the front, which is considered the
1010 first element for this purpose.
1012 @code{yank} does not alter the contents of the kill ring, unless it
1013 used text provided by another program, in which case it pushes that text
1014 onto the kill ring.  However if @var{arg} is an integer different from
1015 one, it rotates the kill ring to place the yanked string at the front.
1017 @code{yank} returns @code{nil}.
1018 @end deffn
1020 @deffn Command yank-pop &optional arg
1021 This command replaces the just-yanked entry from the kill ring with a
1022 different entry from the kill ring.
1024 This is allowed only immediately after a @code{yank} or another
1025 @code{yank-pop}.  At such a time, the region contains text that was just
1026 inserted by yanking.  @code{yank-pop} deletes that text and inserts in
1027 its place a different piece of killed text.  It does not add the deleted
1028 text to the kill ring, since it is already in the kill ring somewhere.
1029 It does however rotate the kill ring to place the newly yanked string at
1030 the front.
1032 If @var{arg} is @code{nil}, then the replacement text is the previous
1033 element of the kill ring.  If @var{arg} is numeric, the replacement is
1034 the @var{arg}th previous kill.  If @var{arg} is negative, a more recent
1035 kill is the replacement.
1037 The sequence of kills in the kill ring wraps around, so that after the
1038 oldest one comes the newest one, and before the newest one goes the
1039 oldest.
1041 The return value is always @code{nil}.
1042 @end deffn
1044 @defvar yank-undo-function
1045 If this variable is non-@code{nil}, the function @code{yank-pop} uses
1046 its value instead of @code{delete-region} to delete the text
1047 inserted by the previous @code{yank} or
1048 @code{yank-pop} command.  The value must be a function of two
1049 arguments, the start and end of the current region.
1051 The function @code{insert-for-yank} automatically sets this variable
1052 according to the @var{undo} element of the @code{yank-handler}
1053 text property, if there is one.
1054 @end defvar
1056 @node Low-Level Kill Ring
1057 @subsection Low-Level Kill Ring
1059   These functions and variables provide access to the kill ring at a
1060 lower level, but are still convenient for use in Lisp programs,
1061 because they take care of interaction with window system selections
1062 (@pxref{Window System Selections}).
1064 @defun current-kill n &optional do-not-move
1065 The function @code{current-kill} rotates the yanking pointer, which
1066 designates the ``front'' of the kill ring, by @var{n} places (from newer
1067 kills to older ones), and returns the text at that place in the ring.
1069 If the optional second argument @var{do-not-move} is non-@code{nil},
1070 then @code{current-kill} doesn't alter the yanking pointer; it just
1071 returns the @var{n}th kill, counting from the current yanking pointer.
1073 If @var{n} is zero, indicating a request for the latest kill,
1074 @code{current-kill} calls the value of
1075 @code{interprogram-paste-function} (documented below) before
1076 consulting the kill ring.  If that value is a function and calling it
1077 returns a string or a list of several string, @code{current-kill}
1078 pushes the strings onto the kill ring and returns the first string.
1079 It also sets the yanking pointer to point to the kill-ring entry of
1080 the first string returned by @code{interprogram-paste-function},
1081 regardless of the value of @var{do-not-move}.  Otherwise,
1082 @code{current-kill} does not treat a zero value for @var{n} specially:
1083 it returns the entry pointed at by the yanking pointer and does not
1084 move the yanking pointer.
1085 @end defun
1087 @defun kill-new string &optional replace
1088 This function pushes the text @var{string} onto the kill ring and
1089 makes the yanking pointer point to it.  It discards the oldest entry
1090 if appropriate.  It also invokes the value of
1091 @code{interprogram-cut-function} (see below).
1093 If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the
1094 first element of the kill ring with @var{string}, rather than pushing
1095 @var{string} onto the kill ring.
1096 @end defun
1098 @defun kill-append string before-p
1099 This function appends the text @var{string} to the first entry in the
1100 kill ring and makes the yanking pointer point to the combined entry.
1101 Normally @var{string} goes at the end of the entry, but if
1102 @var{before-p} is non-@code{nil}, it goes at the beginning.  This
1103 function also invokes the value of @code{interprogram-cut-function}
1104 (see below).
1105 @end defun
1107 @defvar interprogram-paste-function
1108 This variable provides a way of transferring killed text from other
1109 programs, when you are using a window system.  Its value should be
1110 @code{nil} or a function of no arguments.
1112 If the value is a function, @code{current-kill} calls it to get the
1113 ``most recent kill''.  If the function returns a non-@code{nil} value,
1114 then that value is used as the ``most recent kill''.  If it returns
1115 @code{nil}, then the front of the kill ring is used.
1117 To facilitate support for window systems that support multiple
1118 selections, this function may also return a list of strings.  In that
1119 case, the first string is used as the ``most recent kill'', and all
1120 the other strings are pushed onto the kill ring, for easy access by
1121 @code{yank-pop}.
1123 The normal use of this function is to get the window system's
1124 clipboard as the most recent kill, even if the selection belongs to
1125 another application.  @xref{Window System Selections}.  However, if
1126 the clipboard contents come from the current Emacs session, this
1127 function should return @code{nil}.
1128 @end defvar
1130 @defvar interprogram-cut-function
1131 This variable provides a way of communicating killed text to other
1132 programs, when you are using a window system.  Its value should be
1133 @code{nil} or a function of one required argument.
1135 If the value is a function, @code{kill-new} and @code{kill-append} call
1136 it with the new first element of the kill ring as the argument.
1138 The normal use of this function is to put newly killed text in the
1139 window system's clipboard.  @xref{Window System Selections}.
1140 @end defvar
1142 @node Internals of Kill Ring
1143 @subsection Internals of the Kill Ring
1145   The variable @code{kill-ring} holds the kill ring contents, in the
1146 form of a list of strings.  The most recent kill is always at the front
1147 of the list.
1149   The @code{kill-ring-yank-pointer} variable points to a link in the
1150 kill ring list, whose @sc{car} is the text to yank next.  We say it
1151 identifies the ``front'' of the ring.  Moving
1152 @code{kill-ring-yank-pointer} to a different link is called
1153 @dfn{rotating the kill ring}.  We call the kill ring a ``ring'' because
1154 the functions that move the yank pointer wrap around from the end of the
1155 list to the beginning, or vice-versa.  Rotation of the kill ring is
1156 virtual; it does not change the value of @code{kill-ring}.
1158   Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
1159 variables whose values are normally lists.  The word ``pointer'' in the
1160 name of the @code{kill-ring-yank-pointer} indicates that the variable's
1161 purpose is to identify one element of the list for use by the next yank
1162 command.
1164   The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
1165 of the links in the kill ring list.  The element it identifies is the
1166 @sc{car} of that link.  Kill commands, which change the kill ring, also
1167 set this variable to the value of @code{kill-ring}.  The effect is to
1168 rotate the ring so that the newly killed text is at the front.
1170   Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
1171 pointing to the second entry in the kill ring @code{("some text" "a
1172 different piece of text" "yet older text")}.
1174 @example
1175 @group
1176 kill-ring                  ---- kill-ring-yank-pointer
1177   |                       |
1178   |                       v
1179   |     --- ---          --- ---      --- ---
1180    --> |   |   |------> |   |   |--> |   |   |--> nil
1181         --- ---          --- ---      --- ---
1182          |                |            |
1183          |                |            |
1184          |                |             -->"yet older text"
1185          |                |
1186          |                 --> "a different piece of text"
1187          |
1188           --> "some text"
1189 @end group
1190 @end example
1192 @noindent
1193 This state of affairs might occur after @kbd{C-y} (@code{yank})
1194 immediately followed by @kbd{M-y} (@code{yank-pop}).
1196 @defvar kill-ring
1197 This variable holds the list of killed text sequences, most recently
1198 killed first.
1199 @end defvar
1201 @defvar kill-ring-yank-pointer
1202 This variable's value indicates which element of the kill ring is at the
1203 ``front'' of the ring for yanking.  More precisely, the value is a tail
1204 of the value of @code{kill-ring}, and its @sc{car} is the kill string
1205 that @kbd{C-y} should yank.
1206 @end defvar
1208 @defopt kill-ring-max
1209 The value of this variable is the maximum length to which the kill
1210 ring can grow, before elements are thrown away at the end.  The default
1211 value for @code{kill-ring-max} is 60.
1212 @end defopt
1214 @node Undo
1215 @section Undo
1216 @cindex redo
1218   Most buffers have an @dfn{undo list}, which records all changes made
1219 to the buffer's text so that they can be undone.  (The buffers that
1220 don't have one are usually special-purpose buffers for which Emacs
1221 assumes that undoing is not useful.  In particular, any buffer whose
1222 name begins with a space has its undo recording off by default;
1223 see @ref{Buffer Names}.)  All the primitives that modify the
1224 text in the buffer automatically add elements to the front of the undo
1225 list, which is in the variable @code{buffer-undo-list}.
1227 @defvar buffer-undo-list
1228 This buffer-local variable's value is the undo list of the current
1229 buffer. A value of @code{t} disables the recording of undo information.
1230 @end defvar
1232 Here are the kinds of elements an undo list can have:
1234 @table @code
1235 @item @var{position}
1236 This kind of element records a previous value of point; undoing this
1237 element moves point to @var{position}.  Ordinary cursor motion does not
1238 make any sort of undo record, but deletion operations use these entries
1239 to record where point was before the command.
1241 @item (@var{beg} . @var{end})
1242 This kind of element indicates how to delete text that was inserted.
1243 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
1244 buffer.
1246 @item (@var{text} . @var{position})
1247 This kind of element indicates how to reinsert text that was deleted.
1248 The deleted text itself is the string @var{text}.  The place to
1249 reinsert it is @code{(abs @var{position})}.  If @var{position} is
1250 positive, point was at the beginning of the deleted text, otherwise it
1251 was at the end.
1253 @item (t @var{sec-high} @var{sec-low} @var{microsec} @var{picosec})
1254 This kind of element indicates that an unmodified buffer became
1255 modified.  The list @code{(@var{sec-high} @var{sec-low} @var{microsec}
1256 @var{picosec})} represents the visited file's modification time as of
1257 when it was previously visited or saved, using the same format as
1258 @code{current-time}; see @ref{Time of Day}.  @code{primitive-undo} uses those
1259 values to determine whether to mark the buffer as unmodified once again;
1260 it does so only if the file's modification time matches those numbers.
1262 @item (nil @var{property} @var{value} @var{beg} . @var{end})
1263 This kind of element records a change in a text property.
1264 Here's how you might undo the change:
1266 @example
1267 (put-text-property @var{beg} @var{end} @var{property} @var{value})
1268 @end example
1270 @item (@var{marker} . @var{adjustment})
1271 This kind of element records the fact that the marker @var{marker} was
1272 relocated due to deletion of surrounding text, and that it moved
1273 @var{adjustment} character positions.  Undoing this element moves
1274 @var{marker} @minus{} @var{adjustment} characters.
1276 @item (apply @var{funname} . @var{args})
1277 This is an extensible undo item, which is undone by calling
1278 @var{funname} with arguments @var{args}.
1280 @item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
1281 This is an extensible undo item, which records a change limited to the
1282 range @var{beg} to @var{end}, which increased the size of the buffer
1283 by @var{delta}.  It is undone by calling @var{funname} with arguments
1284 @var{args}.
1286 This kind of element enables undo limited to a region to determine
1287 whether the element pertains to that region.
1289 @item nil
1290 This element is a boundary.  The elements between two boundaries are
1291 called a @dfn{change group}; normally, each change group corresponds to
1292 one keyboard command, and undo commands normally undo an entire group as
1293 a unit.
1294 @end table
1296 @defun undo-boundary
1297 This function places a boundary element in the undo list.  The undo
1298 command stops at such a boundary, and successive undo commands undo
1299 to earlier and earlier boundaries.  This function returns @code{nil}.
1301 The editor command loop automatically calls @code{undo-boundary} just
1302 before executing each key sequence, so that each undo normally undoes
1303 the effects of one command.  As an exception, the command
1304 @code{self-insert-command}, which produces self-inserting input
1305 characters (@pxref{Commands for Insertion}), may remove the boundary
1306 inserted by the command loop: a boundary is accepted for the first
1307 such character, the next 19 consecutive self-inserting input
1308 characters do not have boundaries, and then the 20th does; and so on
1309 as long as the self-inserting characters continue.  Hence, sequences
1310 of consecutive character insertions can be undone as a group.
1312 All buffer modifications add a boundary whenever the previous undoable
1313 change was made in some other buffer.  This is to ensure that
1314 each command makes a boundary in each buffer where it makes changes.
1316 Calling this function explicitly is useful for splitting the effects of
1317 a command into more than one unit.  For example, @code{query-replace}
1318 calls @code{undo-boundary} after each replacement, so that the user can
1319 undo individual replacements one by one.
1320 @end defun
1322 @defvar undo-in-progress
1323 This variable is normally @code{nil}, but the undo commands bind it to
1324 @code{t}.  This is so that various kinds of change hooks can tell when
1325 they're being called for the sake of undoing.
1326 @end defvar
1328 @defun primitive-undo count list
1329 This is the basic function for undoing elements of an undo list.
1330 It undoes the first @var{count} elements of @var{list}, returning
1331 the rest of @var{list}.
1333 @code{primitive-undo} adds elements to the buffer's undo list when it
1334 changes the buffer.  Undo commands avoid confusion by saving the undo
1335 list value at the beginning of a sequence of undo operations.  Then the
1336 undo operations use and update the saved value.  The new elements added
1337 by undoing are not part of this saved value, so they don't interfere with
1338 continuing to undo.
1340 This function does not bind @code{undo-in-progress}.
1341 @end defun
1343 @node Maintaining Undo
1344 @section Maintaining Undo Lists
1346   This section describes how to enable and disable undo information for
1347 a given buffer.  It also explains how the undo list is truncated
1348 automatically so it doesn't get too big.
1350   Recording of undo information in a newly created buffer is normally
1351 enabled to start with; but if the buffer name starts with a space, the
1352 undo recording is initially disabled.  You can explicitly enable or
1353 disable undo recording with the following two functions, or by setting
1354 @code{buffer-undo-list} yourself.
1356 @deffn Command buffer-enable-undo &optional buffer-or-name
1357 This command enables recording undo information for buffer
1358 @var{buffer-or-name}, so that subsequent changes can be undone.  If no
1359 argument is supplied, then the current buffer is used.  This function
1360 does nothing if undo recording is already enabled in the buffer.  It
1361 returns @code{nil}.
1363 In an interactive call, @var{buffer-or-name} is the current buffer.
1364 You cannot specify any other buffer.
1365 @end deffn
1367 @deffn Command buffer-disable-undo &optional buffer-or-name
1368 @cindex disabling undo
1369 This function discards the undo list of @var{buffer-or-name}, and disables
1370 further recording of undo information.  As a result, it is no longer
1371 possible to undo either previous changes or any subsequent changes.  If
1372 the undo list of @var{buffer-or-name} is already disabled, this function
1373 has no effect.
1375 This function returns @code{nil}.
1376 @end deffn
1378   As editing continues, undo lists get longer and longer.  To prevent
1379 them from using up all available memory space, garbage collection trims
1380 them back to size limits you can set.  (For this purpose, the ``size''
1381 of an undo list measures the cons cells that make up the list, plus the
1382 strings of deleted text.)  Three variables control the range of acceptable
1383 sizes: @code{undo-limit}, @code{undo-strong-limit} and
1384 @code{undo-outer-limit}.  In these variables, size is counted as the
1385 number of bytes occupied, which includes both saved text and other
1386 data.
1388 @defopt undo-limit
1389 This is the soft limit for the acceptable size of an undo list.  The
1390 change group at which this size is exceeded is the last one kept.
1391 @end defopt
1393 @defopt undo-strong-limit
1394 This is the upper limit for the acceptable size of an undo list.  The
1395 change group at which this size is exceeded is discarded itself (along
1396 with all older change groups).  There is one exception: the very latest
1397 change group is only discarded if it exceeds @code{undo-outer-limit}.
1398 @end defopt
1400 @defopt undo-outer-limit
1401 If at garbage collection time the undo info for the current command
1402 exceeds this limit, Emacs discards the info and displays a warning.
1403 This is a last ditch limit to prevent memory overflow.
1404 @end defopt
1406 @defopt undo-ask-before-discard
1407 If this variable is non-@code{nil}, when the undo info exceeds
1408 @code{undo-outer-limit}, Emacs asks in the echo area whether to
1409 discard the info.  The default value is @code{nil}, which means to
1410 discard it automatically.
1412 This option is mainly intended for debugging.  Garbage collection is
1413 inhibited while the question is asked, which means that Emacs might
1414 leak memory if the user waits too long before answering the question.
1415 @end defopt
1417 @node Filling
1418 @section Filling
1419 @cindex filling text
1421   @dfn{Filling} means adjusting the lengths of lines (by moving the line
1422 breaks) so that they are nearly (but no greater than) a specified
1423 maximum width.  Additionally, lines can be @dfn{justified}, which means
1424 inserting spaces to make the left and/or right margins line up
1425 precisely.  The width is controlled by the variable @code{fill-column}.
1426 For ease of reading, lines should be no longer than 70 or so columns.
1428   You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1429 automatically as you insert it, but changes to existing text may leave
1430 it improperly filled.  Then you must fill the text explicitly.
1432   Most of the commands in this section return values that are not
1433 meaningful.  All the functions that do filling take note of the current
1434 left margin, current right margin, and current justification style
1435 (@pxref{Margins}).  If the current justification style is
1436 @code{none}, the filling functions don't actually do anything.
1438   Several of the filling functions have an argument @var{justify}.
1439 If it is non-@code{nil}, that requests some kind of justification.  It
1440 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
1441 request a specific style of justification.  If it is @code{t}, that
1442 means to use the current justification style for this part of the text
1443 (see @code{current-justification}, below).  Any other value is treated
1444 as @code{full}.
1446   When you call the filling functions interactively, using a prefix
1447 argument implies the value @code{full} for @var{justify}.
1449 @deffn Command fill-paragraph &optional justify region
1450 This command fills the paragraph at or after point.  If
1451 @var{justify} is non-@code{nil}, each line is justified as well.
1452 It uses the ordinary paragraph motion commands to find paragraph
1453 boundaries.  @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
1455 When @var{region} is non-@code{nil}, then if Transient Mark mode is
1456 enabled and the mark is active, this command calls @code{fill-region}
1457 to fill all the paragraphs in the region, instead of filling only the
1458 current paragraph.  When this command is called interactively,
1459 @var{region} is @code{t}.
1460 @end deffn
1462 @deffn Command fill-region start end &optional justify nosqueeze to-eop
1463 This command fills each of the paragraphs in the region from @var{start}
1464 to @var{end}.  It justifies as well if @var{justify} is
1465 non-@code{nil}.
1467 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1468 other than line breaks untouched.  If @var{to-eop} is non-@code{nil},
1469 that means to keep filling to the end of the paragraph---or the next hard
1470 newline, if @code{use-hard-newlines} is enabled (see below).
1472 The variable @code{paragraph-separate} controls how to distinguish
1473 paragraphs.  @xref{Standard Regexps}.
1474 @end deffn
1476 @deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
1477 This command fills each paragraph in the region according to its
1478 individual fill prefix.  Thus, if the lines of a paragraph were indented
1479 with spaces, the filled paragraph will remain indented in the same
1480 fashion.
1482 The first two arguments, @var{start} and @var{end}, are the beginning
1483 and end of the region to be filled.  The third and fourth arguments,
1484 @var{justify} and @var{citation-regexp}, are optional.  If
1485 @var{justify} is non-@code{nil}, the paragraphs are justified as
1486 well as filled.  If @var{citation-regexp} is non-@code{nil}, it means the
1487 function is operating on a mail message and therefore should not fill
1488 the header lines.  If @var{citation-regexp} is a string, it is used as
1489 a regular expression; if it matches the beginning of a line, that line
1490 is treated as a citation marker.
1492 Ordinarily, @code{fill-individual-paragraphs} regards each change in
1493 indentation as starting a new paragraph.  If
1494 @code{fill-individual-varying-indent} is non-@code{nil}, then only
1495 separator lines separate paragraphs.  That mode can handle indented
1496 paragraphs with additional indentation on the first line.
1497 @end deffn
1499 @defopt fill-individual-varying-indent
1500 This variable alters the action of @code{fill-individual-paragraphs} as
1501 described above.
1502 @end defopt
1504 @deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
1505 This command considers a region of text as a single paragraph and fills
1506 it.  If the region was made up of many paragraphs, the blank lines
1507 between paragraphs are removed.  This function justifies as well as
1508 filling when @var{justify} is non-@code{nil}.
1510 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1511 other than line breaks untouched.  If @var{squeeze-after} is
1512 non-@code{nil}, it specifies a position in the region, and means don't
1513 canonicalize spaces before that position.
1515 In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
1516 choose a fill prefix by default.  @xref{Adaptive Fill}.
1517 @end deffn
1519 @deffn Command justify-current-line &optional how eop nosqueeze
1520 This command inserts spaces between the words of the current line so
1521 that the line ends exactly at @code{fill-column}.  It returns
1522 @code{nil}.
1524 The argument @var{how}, if non-@code{nil} specifies explicitly the style
1525 of justification.  It can be @code{left}, @code{right}, @code{full},
1526 @code{center}, or @code{none}.  If it is @code{t}, that means to do
1527 follow specified justification style (see @code{current-justification},
1528 below).  @code{nil} means to do full justification.
1530 If @var{eop} is non-@code{nil}, that means do only left-justification
1531 if @code{current-justification} specifies full justification.  This is
1532 used for the last line of a paragraph; even if the paragraph as a
1533 whole is fully justified, the last line should not be.
1535 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1536 whitespace.
1537 @end deffn
1539 @defopt default-justification
1540 This variable's value specifies the style of justification to use for
1541 text that doesn't specify a style with a text property.  The possible
1542 values are @code{left}, @code{right}, @code{full}, @code{center}, or
1543 @code{none}.  The default value is @code{left}.
1544 @end defopt
1546 @defun current-justification
1547 This function returns the proper justification style to use for filling
1548 the text around point.
1550 This returns the value of the @code{justification} text property at
1551 point, or the variable @var{default-justification} if there is no such
1552 text property.  However, it returns @code{nil} rather than @code{none}
1553 to mean ``don't justify''.
1554 @end defun
1556 @defopt sentence-end-double-space
1557 @anchor{Definition of sentence-end-double-space}
1558 If this variable is non-@code{nil}, a period followed by just one space
1559 does not count as the end of a sentence, and the filling functions
1560 avoid breaking the line at such a place.
1561 @end defopt
1563 @defopt sentence-end-without-period
1564 If this variable is non-@code{nil}, a sentence can end without a
1565 period.  This is used for languages like Thai, where sentences end
1566 with a double space but without a period.
1567 @end defopt
1569 @defopt sentence-end-without-space
1570 If this variable is non-@code{nil}, it should be a string of
1571 characters that can end a sentence without following spaces.
1572 @end defopt
1574 @defvar fill-paragraph-function
1575 This variable provides a way to override the filling of paragraphs.
1576 If its value is non-@code{nil}, @code{fill-paragraph} calls this
1577 function to do the work.  If the function returns a non-@code{nil}
1578 value, @code{fill-paragraph} assumes the job is done, and immediately
1579 returns that value.
1581 The usual use of this feature is to fill comments in programming
1582 language modes.  If the function needs to fill a paragraph in the usual
1583 way, it can do so as follows:
1585 @example
1586 (let ((fill-paragraph-function nil))
1587   (fill-paragraph arg))
1588 @end example
1589 @end defvar
1591 @defvar fill-forward-paragraph-function
1592 This variable provides a way to override how the filling functions,
1593 such as @code{fill-region} and @code{fill-paragraph}, move forward to
1594 the next paragraph.  Its value should be a function, which is called
1595 with a single argument @var{n}, the number of paragraphs to move, and
1596 should return the difference between @var{n} and the number of
1597 paragraphs actually moved.  The default value of this variable is
1598 @code{forward-paragraph}.  @xref{Paragraphs,,, emacs, The GNU Emacs
1599 Manual}.
1600 @end defvar
1602 @defvar use-hard-newlines
1603 If this variable is non-@code{nil}, the filling functions do not delete
1604 newlines that have the @code{hard} text property.  These ``hard
1605 newlines'' act as paragraph separators.
1606 @end defvar
1608 @node Margins
1609 @section Margins for Filling
1611 @defopt fill-prefix
1612 This buffer-local variable, if non-@code{nil}, specifies a string of
1613 text that appears at the beginning of normal text lines and should be
1614 disregarded when filling them.  Any line that fails to start with the
1615 fill prefix is considered the start of a paragraph; so is any line
1616 that starts with the fill prefix followed by additional whitespace.
1617 Lines that start with the fill prefix but no additional whitespace are
1618 ordinary text lines that can be filled together.  The resulting filled
1619 lines also start with the fill prefix.
1621 The fill prefix follows the left margin whitespace, if any.
1622 @end defopt
1624 @defopt fill-column
1625 This buffer-local variable specifies the maximum width of filled lines.
1626 Its value should be an integer, which is a number of columns.  All the
1627 filling, justification, and centering commands are affected by this
1628 variable, including Auto Fill mode (@pxref{Auto Filling}).
1630 As a practical matter, if you are writing text for other people to
1631 read, you should set @code{fill-column} to no more than 70.  Otherwise
1632 the line will be too long for people to read comfortably, and this can
1633 make the text seem clumsy.
1635 The default value for @code{fill-column} is 70.
1636 @end defopt
1638 @deffn Command set-left-margin from to margin
1639 This sets the @code{left-margin} property on the text from @var{from} to
1640 @var{to} to the value @var{margin}.  If Auto Fill mode is enabled, this
1641 command also refills the region to fit the new margin.
1642 @end deffn
1644 @deffn Command set-right-margin from to margin
1645 This sets the @code{right-margin} property on the text from @var{from}
1646 to @var{to} to the value @var{margin}.  If Auto Fill mode is enabled,
1647 this command also refills the region to fit the new margin.
1648 @end deffn
1650 @defun current-left-margin
1651 This function returns the proper left margin value to use for filling
1652 the text around point.  The value is the sum of the @code{left-margin}
1653 property of the character at the start of the current line (or zero if
1654 none), and the value of the variable @code{left-margin}.
1655 @end defun
1657 @defun current-fill-column
1658 This function returns the proper fill column value to use for filling
1659 the text around point.  The value is the value of the @code{fill-column}
1660 variable, minus the value of the @code{right-margin} property of the
1661 character after point.
1662 @end defun
1664 @deffn Command move-to-left-margin &optional n force
1665 This function moves point to the left margin of the current line.  The
1666 column moved to is determined by calling the function
1667 @code{current-left-margin}.  If the argument @var{n} is non-@code{nil},
1668 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
1670 If @var{force} is non-@code{nil}, that says to fix the line's
1671 indentation if that doesn't match the left margin value.
1672 @end deffn
1674 @defun delete-to-left-margin &optional from to
1675 This function removes left margin indentation from the text between
1676 @var{from} and @var{to}.  The amount of indentation to delete is
1677 determined by calling @code{current-left-margin}.  In no case does this
1678 function delete non-whitespace.  If @var{from} and @var{to} are omitted,
1679 they default to the whole buffer.
1680 @end defun
1682 @defun indent-to-left-margin
1683 This function adjusts the indentation at the beginning of the current
1684 line to the value specified by the variable @code{left-margin}.  (That
1685 may involve either inserting or deleting whitespace.)  This function
1686 is value of @code{indent-line-function} in Paragraph-Indent Text mode.
1687 @end defun
1689 @defopt left-margin
1690 This variable specifies the base left margin column.  In Fundamental
1691 mode, @kbd{C-j} indents to this column.  This variable automatically
1692 becomes buffer-local when set in any fashion.
1693 @end defopt
1695 @defopt fill-nobreak-predicate
1696 This variable gives major modes a way to specify not to break a line
1697 at certain places.  Its value should be a list of functions.  Whenever
1698 filling considers breaking the line at a certain place in the buffer,
1699 it calls each of these functions with no arguments and with point
1700 located at that place.  If any of the functions returns
1701 non-@code{nil}, then the line won't be broken there.
1702 @end defopt
1704 @node Adaptive Fill
1705 @section Adaptive Fill Mode
1706 @c @cindex Adaptive Fill mode  "adaptive-fill-mode" is adjacent.
1708   When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill
1709 prefix automatically from the text in each paragraph being filled
1710 rather than using a predetermined value.  During filling, this fill
1711 prefix gets inserted at the start of the second and subsequent lines
1712 of the paragraph as described in @ref{Filling}, and in @ref{Auto
1713 Filling}.
1715 @defopt adaptive-fill-mode
1716 Adaptive Fill mode is enabled when this variable is non-@code{nil}.
1717 It is @code{t} by default.
1718 @end defopt
1720 @defun fill-context-prefix from to
1721 This function implements the heart of Adaptive Fill mode; it chooses a
1722 fill prefix based on the text between @var{from} and @var{to},
1723 typically the start and end of a paragraph.  It does this by looking
1724 at the first two lines of the paragraph, based on the variables
1725 described below.
1726 @c The optional argument first-line-regexp is not documented
1727 @c because it exists for internal purposes and might be eliminated
1728 @c in the future.
1730 Usually, this function returns the fill prefix, a string.  However,
1731 before doing this, the function makes a final check (not specially
1732 mentioned in the following) that a line starting with this prefix
1733 wouldn't look like the start of a paragraph.  Should this happen, the
1734 function signals the anomaly by returning @code{nil} instead.
1736 In detail, @code{fill-context-prefix} does this:
1738 @enumerate
1739 @item
1740 It takes a candidate for the fill prefix from the first line---it
1741 tries first the function in @code{adaptive-fill-function} (if any),
1742 then the regular expression @code{adaptive-fill-regexp} (see below).
1743 The first non-@code{nil} result of these, or the empty string if
1744 they're both @code{nil}, becomes the first line's candidate.
1745 @item
1746 If the paragraph has as yet only one line, the function tests the
1747 validity of the prefix candidate just found.  The function then
1748 returns the candidate if it's valid, or a string of spaces otherwise.
1749 (see the description of @code{adaptive-fill-first-line-regexp} below).
1750 @item
1751 When the paragraph already has two lines, the function next looks for
1752 a prefix candidate on the second line, in just the same way it did for
1753 the first line.  If it doesn't find one, it returns @code{nil}.
1754 @item
1755 The function now compares the two candidate prefixes heuristically: if
1756 the non-whitespace characters in the line 2 candidate occur in the
1757 same order in the line 1 candidate, the function returns the line 2
1758 candidate.  Otherwise, it returns the largest initial substring which
1759 is common to both candidates (which might be the empty string).
1760 @end enumerate
1761 @end defun
1763 @defopt adaptive-fill-regexp
1764 Adaptive Fill mode matches this regular expression against the text
1765 starting after the left margin whitespace (if any) on a line; the
1766 characters it matches are that line's candidate for the fill prefix.
1768 The default value matches whitespace with certain punctuation
1769 characters intermingled.
1770 @end defopt
1772 @defopt adaptive-fill-first-line-regexp
1773 Used only in one-line paragraphs, this regular expression acts as an
1774 additional check of the validity of the one available candidate fill
1775 prefix: the candidate must match this regular expression, or match
1776 @code{comment-start-skip}.  If it doesn't, @code{fill-context-prefix}
1777 replaces the candidate with a string of spaces ``of the same width''
1778 as it.
1780 The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which
1781 matches only a string of whitespace.  The effect of this default is to
1782 force the fill prefixes found in one-line paragraphs always to be pure
1783 whitespace.
1784 @end defopt
1786 @defopt adaptive-fill-function
1787 You can specify more complex ways of choosing a fill prefix
1788 automatically by setting this variable to a function.  The function is
1789 called with point after the left margin (if any) of a line, and it
1790 must preserve point.  It should return either ``that line's'' fill
1791 prefix or @code{nil}, meaning it has failed to determine a prefix.
1792 @end defopt
1794 @node Auto Filling
1795 @section Auto Filling
1796 @cindex filling, automatic
1797 @cindex Auto Fill mode
1799   Auto Fill mode is a minor mode that fills lines automatically as text
1800 is inserted.  This section describes the hook used by Auto Fill mode.
1801 For a description of functions that you can call explicitly to fill and
1802 justify existing text, see @ref{Filling}.
1804   Auto Fill mode also enables the functions that change the margins and
1805 justification style to refill portions of the text.  @xref{Margins}.
1807 @defvar auto-fill-function
1808 The value of this buffer-local variable should be a function (of no
1809 arguments) to be called after self-inserting a character from the table
1810 @code{auto-fill-chars}.  It may be @code{nil}, in which case nothing
1811 special is done in that case.
1813 The value of @code{auto-fill-function} is @code{do-auto-fill} when
1814 Auto-Fill mode is enabled.  That is a function whose sole purpose is to
1815 implement the usual strategy for breaking a line.
1816 @end defvar
1818 @defvar normal-auto-fill-function
1819 This variable specifies the function to use for
1820 @code{auto-fill-function}, if and when Auto Fill is turned on.  Major
1821 modes can set buffer-local values for this variable to alter how Auto
1822 Fill works.
1823 @end defvar
1825 @defvar auto-fill-chars
1826 A char table of characters which invoke @code{auto-fill-function} when
1827 self-inserted---space and newline in most language environments.  They
1828 have an entry @code{t} in the table.
1829 @end defvar
1831 @node Sorting
1832 @section Sorting Text
1833 @cindex sorting text
1835   The sorting functions described in this section all rearrange text in
1836 a buffer.  This is in contrast to the function @code{sort}, which
1837 rearranges the order of the elements of a list (@pxref{Rearrangement}).
1838 The values returned by these functions are not meaningful.
1840 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate
1841 This function is the general text-sorting routine that subdivides a
1842 buffer into records and then sorts them.  Most of the commands in this
1843 section use this function.
1845 To understand how @code{sort-subr} works, consider the whole accessible
1846 portion of the buffer as being divided into disjoint pieces called
1847 @dfn{sort records}.  The records may or may not be contiguous, but they
1848 must not overlap.  A portion of each sort record (perhaps all of it) is
1849 designated as the sort key.  Sorting rearranges the records in order by
1850 their sort keys.
1852 Usually, the records are rearranged in order of ascending sort key.
1853 If the first argument to the @code{sort-subr} function, @var{reverse},
1854 is non-@code{nil}, the sort records are rearranged in order of
1855 descending sort key.
1857 The next four arguments to @code{sort-subr} are functions that are
1858 called to move point across a sort record.  They are called many times
1859 from within @code{sort-subr}.
1861 @enumerate
1862 @item
1863 @var{nextrecfun} is called with point at the end of a record.  This
1864 function moves point to the start of the next record.  The first record
1865 is assumed to start at the position of point when @code{sort-subr} is
1866 called.  Therefore, you should usually move point to the beginning of
1867 the buffer before calling @code{sort-subr}.
1869 This function can indicate there are no more sort records by leaving
1870 point at the end of the buffer.
1872 @item
1873 @var{endrecfun} is called with point within a record.  It moves point to
1874 the end of the record.
1876 @item
1877 @var{startkeyfun} is called to move point from the start of a record to
1878 the start of the sort key.  This argument is optional; if it is omitted,
1879 the whole record is the sort key.  If supplied, the function should
1880 either return a non-@code{nil} value to be used as the sort key, or
1881 return @code{nil} to indicate that the sort key is in the buffer
1882 starting at point.  In the latter case, @var{endkeyfun} is called to
1883 find the end of the sort key.
1885 @item
1886 @var{endkeyfun} is called to move point from the start of the sort key
1887 to the end of the sort key.  This argument is optional.  If
1888 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
1889 @code{nil}), then the sort key extends to the end of the record.  There
1890 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1891 non-@code{nil} value.
1892 @end enumerate
1894 The argument @var{predicate} is the function to use to compare keys.
1895 If keys are numbers, it defaults to @code{<}; otherwise it defaults to
1896 @code{string<}.
1898 As an example of @code{sort-subr}, here is the complete function
1899 definition for @code{sort-lines}:
1901 @example
1902 @group
1903 ;; @r{Note that the first two lines of doc string}
1904 ;; @r{are effectively one line when viewed by a user.}
1905 (defun sort-lines (reverse beg end)
1906   "Sort lines in region alphabetically;\
1907  argument means descending order.
1908 Called from a program, there are three arguments:
1909 @end group
1910 @group
1911 REVERSE (non-nil means reverse order),\
1912  BEG and END (region to sort).
1913 The variable `sort-fold-case' determines\
1914  whether alphabetic case affects
1915 the sort order."
1916 @end group
1917 @group
1918   (interactive "P\nr")
1919   (save-excursion
1920     (save-restriction
1921       (narrow-to-region beg end)
1922       (goto-char (point-min))
1923       (let ((inhibit-field-text-motion t))
1924         (sort-subr reverse 'forward-line 'end-of-line)))))
1925 @end group
1926 @end example
1928 Here @code{forward-line} moves point to the start of the next record,
1929 and @code{end-of-line} moves point to the end of record.  We do not pass
1930 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
1931 record is used as the sort key.
1933 The @code{sort-paragraphs} function is very much the same, except that
1934 its @code{sort-subr} call looks like this:
1936 @example
1937 @group
1938 (sort-subr reverse
1939            (function
1940              (lambda ()
1941                (while (and (not (eobp))
1942                       (looking-at paragraph-separate))
1943                  (forward-line 1))))
1944            'forward-paragraph)
1945 @end group
1946 @end example
1948 Markers pointing into any sort records are left with no useful
1949 position after @code{sort-subr} returns.
1950 @end defun
1952 @defopt sort-fold-case
1953 If this variable is non-@code{nil}, @code{sort-subr} and the other
1954 buffer sorting functions ignore case when comparing strings.
1955 @end defopt
1957 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
1958 This command sorts the region between @var{start} and @var{end}
1959 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
1960 If @var{reverse} is a negative integer, then sorting is in reverse
1961 order.
1963 Alphabetical sorting means that two sort keys are compared by
1964 comparing the first characters of each, the second characters of each,
1965 and so on.  If a mismatch is found, it means that the sort keys are
1966 unequal; the sort key whose character is less at the point of first
1967 mismatch is the lesser sort key.  The individual characters are compared
1968 according to their numerical character codes in the Emacs character set.
1970 The value of the @var{record-regexp} argument specifies how to divide
1971 the buffer into sort records.  At the end of each record, a search is
1972 done for this regular expression, and the text that matches it is taken
1973 as the next record.  For example, the regular expression @samp{^.+$},
1974 which matches lines with at least one character besides a newline, would
1975 make each such line into a sort record.  @xref{Regular Expressions}, for
1976 a description of the syntax and meaning of regular expressions.
1978 The value of the @var{key-regexp} argument specifies what part of each
1979 record is the sort key.  The @var{key-regexp} could match the whole
1980 record, or only a part.  In the latter case, the rest of the record has
1981 no effect on the sorted order of records, but it is carried along when
1982 the record moves to its new position.
1984 The @var{key-regexp} argument can refer to the text matched by a
1985 subexpression of @var{record-regexp}, or it can be a regular expression
1986 on its own.
1988 If @var{key-regexp} is:
1990 @table @asis
1991 @item @samp{\@var{digit}}
1992 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
1993 grouping in @var{record-regexp} is the sort key.
1995 @item @samp{\&}
1996 then the whole record is the sort key.
1998 @item a regular expression
1999 then @code{sort-regexp-fields} searches for a match for the regular
2000 expression within the record.  If such a match is found, it is the sort
2001 key.  If there is no match for @var{key-regexp} within a record then
2002 that record is ignored, which means its position in the buffer is not
2003 changed.  (The other records may move around it.)
2004 @end table
2006 For example, if you plan to sort all the lines in the region by the
2007 first word on each line starting with the letter @samp{f}, you should
2008 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
2009 @samp{\<f\w*\>}.  The resulting expression looks like this:
2011 @example
2012 @group
2013 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
2014                     (region-beginning)
2015                     (region-end))
2016 @end group
2017 @end example
2019 If you call @code{sort-regexp-fields} interactively, it prompts for
2020 @var{record-regexp} and @var{key-regexp} in the minibuffer.
2021 @end deffn
2023 @deffn Command sort-lines reverse start end
2024 This command alphabetically sorts lines in the region between
2025 @var{start} and @var{end}.  If @var{reverse} is non-@code{nil}, the sort
2026 is in reverse order.
2027 @end deffn
2029 @deffn Command sort-paragraphs reverse start end
2030 This command alphabetically sorts paragraphs in the region between
2031 @var{start} and @var{end}.  If @var{reverse} is non-@code{nil}, the sort
2032 is in reverse order.
2033 @end deffn
2035 @deffn Command sort-pages reverse start end
2036 This command alphabetically sorts pages in the region between
2037 @var{start} and @var{end}.  If @var{reverse} is non-@code{nil}, the sort
2038 is in reverse order.
2039 @end deffn
2041 @deffn Command sort-fields field start end
2042 This command sorts lines in the region between @var{start} and
2043 @var{end}, comparing them alphabetically by the @var{field}th field
2044 of each line.  Fields are separated by whitespace and numbered starting
2045 from 1.  If @var{field} is negative, sorting is by the
2046 @w{@minus{}@var{field}th} field from the end of the line.  This command
2047 is useful for sorting tables.
2048 @end deffn
2050 @deffn Command sort-numeric-fields field start end
2051 This command sorts lines in the region between @var{start} and
2052 @var{end}, comparing them numerically by the @var{field}th field of
2053 each line.  Fields are separated by whitespace and numbered starting
2054 from 1.  The specified field must contain a number in each line of the
2055 region.  Numbers starting with 0 are treated as octal, and numbers
2056 starting with @samp{0x} are treated as hexadecimal.
2058 If @var{field} is negative, sorting is by the
2059 @w{@minus{}@var{field}th} field from the end of the line.  This
2060 command is useful for sorting tables.
2061 @end deffn
2063 @defopt sort-numeric-base
2064 This variable specifies the default radix for
2065 @code{sort-numeric-fields} to parse numbers.
2066 @end defopt
2068 @deffn Command sort-columns reverse &optional beg end
2069 This command sorts the lines in the region between @var{beg} and
2070 @var{end}, comparing them alphabetically by a certain range of
2071 columns.  The column positions of @var{beg} and @var{end} bound the
2072 range of columns to sort on.
2074 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
2076 One unusual thing about this command is that the entire line
2077 containing position @var{beg}, and the entire line containing position
2078 @var{end}, are included in the region sorted.
2080 Note that @code{sort-columns} rejects text that contains tabs, because
2081 tabs could be split across the specified columns.  Use @kbd{M-x
2082 untabify} to convert tabs to spaces before sorting.
2084 When possible, this command actually works by calling the @code{sort}
2085 utility program.
2086 @end deffn
2088 @node Columns
2089 @section Counting Columns
2090 @cindex columns
2091 @cindex counting columns
2092 @cindex horizontal position
2094   The column functions convert between a character position (counting
2095 characters from the beginning of the buffer) and a column position
2096 (counting screen characters from the beginning of a line).
2098   These functions count each character according to the number of
2099 columns it occupies on the screen.  This means control characters count
2100 as occupying 2 or 4 columns, depending upon the value of
2101 @code{ctl-arrow}, and tabs count as occupying a number of columns that
2102 depends on the value of @code{tab-width} and on the column where the tab
2103 begins.  @xref{Usual Display}.
2105   Column number computations ignore the width of the window and the
2106 amount of horizontal scrolling.  Consequently, a column value can be
2107 arbitrarily high.  The first (or leftmost) column is numbered 0.  They
2108 also ignore overlays and text properties, aside from invisibility.
2110 @defun current-column
2111 This function returns the horizontal position of point, measured in
2112 columns, counting from 0 at the left margin.  The column position is the
2113 sum of the widths of all the displayed representations of the characters
2114 between the start of the current line and point.
2116 For an example of using @code{current-column}, see the description of
2117 @code{count-lines} in @ref{Text Lines}.
2118 @end defun
2120 @deffn Command move-to-column column &optional force
2121 This function moves point to @var{column} in the current line.  The
2122 calculation of @var{column} takes into account the widths of the
2123 displayed representations of the characters between the start of the
2124 line and point.
2126 When called interactively, @var{column} is the value of prefix numeric
2127 argument.  If @var{column} is not an integer, an error is signaled.
2129 If column @var{column} is beyond the end of the line, point moves to
2130 the end of the line.  If @var{column} is negative, point moves to the
2131 beginning of the line.
2133 If it is impossible to move to column @var{column} because that is in
2134 the middle of a multicolumn character such as a tab, point moves to the
2135 end of that character.  However, if @var{force} is non-@code{nil}, and
2136 @var{column} is in the middle of a tab, then @code{move-to-column}
2137 converts the tab into spaces so that it can move precisely to column
2138 @var{column}.  Other multicolumn characters can cause anomalies despite
2139 @var{force}, since there is no way to split them.
2141 The argument @var{force} also has an effect if the line isn't long
2142 enough to reach column @var{column}; if it is @code{t}, that means to
2143 add whitespace at the end of the line to reach that column.
2145 The return value is the column number actually moved to.
2146 @end deffn
2148 @node Indentation
2149 @section Indentation
2150 @cindex indentation
2152   The indentation functions are used to examine, move to, and change
2153 whitespace that is at the beginning of a line.  Some of the functions
2154 can also change whitespace elsewhere on a line.  Columns and indentation
2155 count from zero at the left margin.
2157 @menu
2158 * Primitive Indent::      Functions used to count and insert indentation.
2159 * Mode-Specific Indent::  Customize indentation for different modes.
2160 * Region Indent::         Indent all the lines in a region.
2161 * Relative Indent::       Indent the current line based on previous lines.
2162 * Indent Tabs::           Adjustable, typewriter-like tab stops.
2163 * Motion by Indent::      Move to first non-blank character.
2164 @end menu
2166 @node Primitive Indent
2167 @subsection Indentation Primitives
2169   This section describes the primitive functions used to count and
2170 insert indentation.  The functions in the following sections use these
2171 primitives.  @xref{Width}, for related functions.
2173 @defun current-indentation
2174 @comment !!Type Primitive Function
2175 @comment !!SourceFile indent.c
2176 This function returns the indentation of the current line, which is
2177 the horizontal position of the first nonblank character.  If the
2178 contents are entirely blank, then this is the horizontal position of the
2179 end of the line.
2180 @end defun
2182 @deffn Command indent-to column &optional minimum
2183 @comment !!Type Primitive Function
2184 @comment !!SourceFile indent.c
2185 This function indents from point with tabs and spaces until @var{column}
2186 is reached.  If @var{minimum} is specified and non-@code{nil}, then at
2187 least that many spaces are inserted even if this requires going beyond
2188 @var{column}.  Otherwise the function does nothing if point is already
2189 beyond @var{column}.  The value is the column at which the inserted
2190 indentation ends.
2192 The inserted whitespace characters inherit text properties from the
2193 surrounding text (usually, from the preceding text only).  @xref{Sticky
2194 Properties}.
2195 @end deffn
2197 @defopt indent-tabs-mode
2198 @comment !!SourceFile indent.c
2199 If this variable is non-@code{nil}, indentation functions can insert
2200 tabs as well as spaces.  Otherwise, they insert only spaces.  Setting
2201 this variable automatically makes it buffer-local in the current buffer.
2202 @end defopt
2204 @node Mode-Specific Indent
2205 @subsection Indentation Controlled by Major Mode
2207   An important function of each major mode is to customize the @key{TAB}
2208 key to indent properly for the language being edited.  This section
2209 describes the mechanism of the @key{TAB} key and how to control it.
2210 The functions in this section return unpredictable values.
2212 @deffn Command indent-for-tab-command &optional rigid
2213 This is the command bound to @key{TAB} in most editing modes.  Its
2214 usual action is to indent the current line, but it can alternatively
2215 insert a tab character or indent a region.
2217 Here is what it does:
2219 @itemize
2220 @item
2221 First, it checks whether Transient Mark mode is enabled and the region
2222 is active.  If so, it called @code{indent-region} to indent all the
2223 text in the region (@pxref{Region Indent}).
2225 @item
2226 Otherwise, if the indentation function in @code{indent-line-function}
2227 is @code{indent-to-left-margin} (a trivial command that inserts a tab
2228 character), or if the variable @code{tab-always-indent} specifies that
2229 a tab character ought to be inserted (see below), then it inserts a
2230 tab character.
2232 @item
2233 Otherwise, it indents the current line; this is done by calling the
2234 function in @code{indent-line-function}.  If the line is already
2235 indented, and the value of @code{tab-always-indent} is @code{complete}
2236 (see below), it tries completing the text at point.
2237 @end itemize
2239 If @var{rigid} is non-@code{nil} (interactively, with a prefix
2240 argument), then after this command indents a line or inserts a tab, it
2241 also rigidly indents the entire balanced expression which starts at
2242 the beginning of the current line, in order to reflect the new
2243 indentation.  This argument is ignored if the command indents the
2244 region.
2245 @end deffn
2247 @defvar indent-line-function
2248 This variable's value is the function to be used by
2249 @code{indent-for-tab-command}, and various other indentation commands,
2250 to indent the current line.  It is usually assigned by the major mode;
2251 for instance, Lisp mode sets it to @code{lisp-indent-line}, C mode
2252 sets it to @code{c-indent-line}, and so on.  The default value is
2253 @code{indent-relative}.  @xref{Auto-Indentation}.
2254 @end defvar
2256 @deffn Command indent-according-to-mode
2257 This command calls the function in @code{indent-line-function} to
2258 indent the current line in a way appropriate for the current major mode.
2259 @end deffn
2261 @deffn Command newline-and-indent
2262 This function inserts a newline, then indents the new line (the one
2263 following the newline just inserted) according to the major mode.  It
2264 does indentation by calling @code{indent-according-to-mode}.
2265 @end deffn
2267 @deffn Command reindent-then-newline-and-indent
2268 This command reindents the current line, inserts a newline at point,
2269 and then indents the new line (the one following the newline just
2270 inserted).  It does indentation on both lines by calling
2271 @code{indent-according-to-mode}.
2272 @end deffn
2274 @defopt tab-always-indent
2275 This variable can be used to customize the behavior of the @key{TAB}
2276 (@code{indent-for-tab-command}) command.  If the value is @code{t}
2277 (the default), the command normally just indents the current line.  If
2278 the value is @code{nil}, the command indents the current line only if
2279 point is at the left margin or in the line's indentation; otherwise,
2280 it inserts a tab character.  If the value is @code{complete}, the
2281 command first tries to indent the current line, and if the line was
2282 already indented, it calls @code{completion-at-point} to complete the
2283 text at point (@pxref{Completion in Buffers}).
2284 @end defopt
2286 @node Region Indent
2287 @subsection Indenting an Entire Region
2289   This section describes commands that indent all the lines in the
2290 region.  They return unpredictable values.
2292 @deffn Command indent-region start end &optional to-column
2293 This command indents each nonblank line starting between @var{start}
2294 (inclusive) and @var{end} (exclusive).  If @var{to-column} is
2295 @code{nil}, @code{indent-region} indents each nonblank line by calling
2296 the current mode's indentation function, the value of
2297 @code{indent-line-function}.
2299 If @var{to-column} is non-@code{nil}, it should be an integer
2300 specifying the number of columns of indentation; then this function
2301 gives each line exactly that much indentation, by either adding or
2302 deleting whitespace.
2304 If there is a fill prefix, @code{indent-region} indents each line
2305 by making it start with the fill prefix.
2306 @end deffn
2308 @defvar indent-region-function
2309 The value of this variable is a function that can be used by
2310 @code{indent-region} as a short cut.  It should take two arguments, the
2311 start and end of the region.  You should design the function so
2312 that it will produce the same results as indenting the lines of the
2313 region one by one, but presumably faster.
2315 If the value is @code{nil}, there is no short cut, and
2316 @code{indent-region} actually works line by line.
2318 A short-cut function is useful in modes such as C mode and Lisp mode,
2319 where the @code{indent-line-function} must scan from the beginning of
2320 the function definition: applying it to each line would be quadratic in
2321 time.  The short cut can update the scan information as it moves through
2322 the lines indenting them; this takes linear time.  In a mode where
2323 indenting a line individually is fast, there is no need for a short cut.
2325 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
2326 a different meaning and does not use this variable.
2327 @end defvar
2329 @deffn Command indent-rigidly start end count
2330 This command indents all lines starting between @var{start}
2331 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
2332 This ``preserves the shape'' of the affected region, moving it as a
2333 rigid unit.  Consequently, this command is useful not only for indenting
2334 regions of unindented text, but also for indenting regions of formatted
2335 code.
2337 For example, if @var{count} is 3, this command adds 3 columns of
2338 indentation to each of the lines beginning in the region specified.
2340 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
2341 @code{indent-rigidly} to indent the text copied from the message being
2342 replied to.
2343 @end deffn
2345 @deffn Command indent-code-rigidly start end columns &optional nochange-regexp
2346 This is like @code{indent-rigidly}, except that it doesn't alter lines
2347 that start within strings or comments.
2349 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
2350 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
2351 @end deffn
2353 @node Relative Indent
2354 @subsection Indentation Relative to Previous Lines
2356   This section describes two commands that indent the current line
2357 based on the contents of previous lines.
2359 @deffn Command indent-relative &optional unindented-ok
2360 This command inserts whitespace at point, extending to the same
2361 column as the next @dfn{indent point} of the previous nonblank line.  An
2362 indent point is a non-whitespace character following whitespace.  The
2363 next indent point is the first one at a column greater than the current
2364 column of point.  For example, if point is underneath and to the left of
2365 the first non-blank character of a line of text, it moves to that column
2366 by inserting whitespace.
2368 If the previous nonblank line has no next indent point (i.e., none at a
2369 great enough column position), @code{indent-relative} either does
2370 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
2371 @code{tab-to-tab-stop}.  Thus, if point is underneath and to the right
2372 of the last column of a short line of text, this command ordinarily
2373 moves point to the next tab stop by inserting whitespace.
2375 The return value of @code{indent-relative} is unpredictable.
2377 In the following example, point is at the beginning of the second
2378 line:
2380 @example
2381 @group
2382             This line is indented twelve spaces.
2383 @point{}The quick brown fox jumped.
2384 @end group
2385 @end example
2387 @noindent
2388 Evaluation of the expression @code{(indent-relative nil)} produces the
2389 following:
2391 @example
2392 @group
2393             This line is indented twelve spaces.
2394             @point{}The quick brown fox jumped.
2395 @end group
2396 @end example
2398   In this next example, point is between the @samp{m} and @samp{p} of
2399 @samp{jumped}:
2401 @example
2402 @group
2403             This line is indented twelve spaces.
2404 The quick brown fox jum@point{}ped.
2405 @end group
2406 @end example
2408 @noindent
2409 Evaluation of the expression @code{(indent-relative nil)} produces the
2410 following:
2412 @example
2413 @group
2414             This line is indented twelve spaces.
2415 The quick brown fox jum  @point{}ped.
2416 @end group
2417 @end example
2418 @end deffn
2420 @deffn Command indent-relative-maybe
2421 @comment !!SourceFile indent.el
2422 This command indents the current line like the previous nonblank line,
2423 by calling @code{indent-relative} with @code{t} as the
2424 @var{unindented-ok} argument.  The return value is unpredictable.
2426 If the previous nonblank line has no indent points beyond the current
2427 column, this command does nothing.
2428 @end deffn
2430 @node Indent Tabs
2431 @subsection Adjustable ``Tab Stops''
2432 @cindex tabs stops for indentation
2434   This section explains the mechanism for user-specified ``tab stops''
2435 and the mechanisms that use and set them.  The name ``tab stops'' is
2436 used because the feature is similar to that of the tab stops on a
2437 typewriter.  The feature works by inserting an appropriate number of
2438 spaces and tab characters to reach the next tab stop column; it does not
2439 affect the display of tab characters in the buffer (@pxref{Usual
2440 Display}).  Note that the @key{TAB} character as input uses this tab
2441 stop feature only in a few major modes, such as Text mode.
2442 @xref{Tab Stops,,, emacs, The GNU Emacs Manual}.
2444 @deffn Command tab-to-tab-stop
2445 This command inserts spaces or tabs before point, up to the next tab
2446 stop column defined by @code{tab-stop-list}.  It searches the list for
2447 an element greater than the current column number, and uses that element
2448 as the column to indent to.  It does nothing if no such element is
2449 found.
2450 @end deffn
2452 @defopt tab-stop-list
2453 This variable is the list of tab stop columns used by
2454 @code{tab-to-tab-stops}.  The elements should be integers in increasing
2455 order.  The tab stop columns need not be evenly spaced.
2457 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
2458 interactively.
2459 @end defopt
2461 @node Motion by Indent
2462 @subsection Indentation-Based Motion Commands
2464   These commands, primarily for interactive use, act based on the
2465 indentation in the text.
2467 @deffn Command back-to-indentation
2468 @comment !!SourceFile simple.el
2469 This command moves point to the first non-whitespace character in the
2470 current line (which is the line in which point is located).  It returns
2471 @code{nil}.
2472 @end deffn
2474 @deffn Command backward-to-indentation &optional arg
2475 @comment !!SourceFile simple.el
2476 This command moves point backward @var{arg} lines and then to the
2477 first nonblank character on that line.  It returns @code{nil}.
2478 If @var{arg} is omitted or @code{nil}, it defaults to 1.
2479 @end deffn
2481 @deffn Command forward-to-indentation &optional arg
2482 @comment !!SourceFile simple.el
2483 This command moves point forward @var{arg} lines and then to the first
2484 nonblank character on that line.  It returns @code{nil}.
2485 If @var{arg} is omitted or @code{nil}, it defaults to 1.
2486 @end deffn
2488 @node Case Changes
2489 @section Case Changes
2490 @cindex case conversion in buffers
2492   The case change commands described here work on text in the current
2493 buffer.  @xref{Case Conversion}, for case conversion functions that work
2494 on strings and characters.  @xref{Case Tables}, for how to customize
2495 which characters are upper or lower case and how to convert them.
2497 @deffn Command capitalize-region start end
2498 This function capitalizes all words in the region defined by
2499 @var{start} and @var{end}.  To capitalize means to convert each word's
2500 first character to upper case and convert the rest of each word to lower
2501 case.  The function returns @code{nil}.
2503 If one end of the region is in the middle of a word, the part of the
2504 word within the region is treated as an entire word.
2506 When @code{capitalize-region} is called interactively, @var{start} and
2507 @var{end} are point and the mark, with the smallest first.
2509 @example
2510 @group
2511 ---------- Buffer: foo ----------
2512 This is the contents of the 5th foo.
2513 ---------- Buffer: foo ----------
2514 @end group
2516 @group
2517 (capitalize-region 1 44)
2518 @result{} nil
2520 ---------- Buffer: foo ----------
2521 This Is The Contents Of The 5th Foo.
2522 ---------- Buffer: foo ----------
2523 @end group
2524 @end example
2525 @end deffn
2527 @deffn Command downcase-region start end
2528 This function converts all of the letters in the region defined by
2529 @var{start} and @var{end} to lower case.  The function returns
2530 @code{nil}.
2532 When @code{downcase-region} is called interactively, @var{start} and
2533 @var{end} are point and the mark, with the smallest first.
2534 @end deffn
2536 @deffn Command upcase-region start end
2537 This function converts all of the letters in the region defined by
2538 @var{start} and @var{end} to upper case.  The function returns
2539 @code{nil}.
2541 When @code{upcase-region} is called interactively, @var{start} and
2542 @var{end} are point and the mark, with the smallest first.
2543 @end deffn
2545 @deffn Command capitalize-word count
2546 This function capitalizes @var{count} words after point, moving point
2547 over as it does.  To capitalize means to convert each word's first
2548 character to upper case and convert the rest of each word to lower case.
2549 If @var{count} is negative, the function capitalizes the
2550 @minus{}@var{count} previous words but does not move point.  The value
2551 is @code{nil}.
2553 If point is in the middle of a word, the part of the word before point
2554 is ignored when moving forward.  The rest is treated as an entire word.
2556 When @code{capitalize-word} is called interactively, @var{count} is
2557 set to the numeric prefix argument.
2558 @end deffn
2560 @deffn Command downcase-word count
2561 This function converts the @var{count} words after point to all lower
2562 case, moving point over as it does.  If @var{count} is negative, it
2563 converts the @minus{}@var{count} previous words but does not move point.
2564 The value is @code{nil}.
2566 When @code{downcase-word} is called interactively, @var{count} is set
2567 to the numeric prefix argument.
2568 @end deffn
2570 @deffn Command upcase-word count
2571 This function converts the @var{count} words after point to all upper
2572 case, moving point over as it does.  If @var{count} is negative, it
2573 converts the @minus{}@var{count} previous words but does not move point.
2574 The value is @code{nil}.
2576 When @code{upcase-word} is called interactively, @var{count} is set to
2577 the numeric prefix argument.
2578 @end deffn
2580 @node Text Properties
2581 @section Text Properties
2582 @cindex text properties
2583 @cindex attributes of text
2584 @cindex properties of text
2586   Each character position in a buffer or a string can have a @dfn{text
2587 property list}, much like the property list of a symbol (@pxref{Property
2588 Lists}).  The properties belong to a particular character at a
2589 particular place, such as, the letter @samp{T} at the beginning of this
2590 sentence or the first @samp{o} in @samp{foo}---if the same character
2591 occurs in two different places, the two occurrences in general have
2592 different properties.
2594   Each property has a name and a value.  Both of these can be any Lisp
2595 object, but the name is normally a symbol.  Typically each property
2596 name symbol is used for a particular purpose; for instance, the text
2597 property @code{face} specifies the faces for displaying the character
2598 (@pxref{Special Properties}).  The usual way to access the property
2599 list is to specify a name and ask what value corresponds to it.
2601   If a character has a @code{category} property, we call it the
2602 @dfn{property category} of the character.  It should be a symbol.  The
2603 properties of the symbol serve as defaults for the properties of the
2604 character.
2606   Copying text between strings and buffers preserves the properties
2607 along with the characters; this includes such diverse functions as
2608 @code{substring}, @code{insert}, and @code{buffer-substring}.
2610 @menu
2611 * Examining Properties::   Looking at the properties of one character.
2612 * Changing Properties::    Setting the properties of a range of text.
2613 * Property Search::        Searching for where a property changes value.
2614 * Special Properties::     Particular properties with special meanings.
2615 * Format Properties::      Properties for representing formatting of text.
2616 * Sticky Properties::      How inserted text gets properties from
2617                              neighboring text.
2618 * Lazy Properties::        Computing text properties in a lazy fashion
2619                              only when text is examined.
2620 * Clickable Text::         Using text properties to make regions of text
2621                              do something when you click on them.
2622 * Fields::                 The @code{field} property defines
2623                              fields within the buffer.
2624 * Not Intervals::          Why text properties do not use
2625                              Lisp-visible text intervals.
2626 @end menu
2628 @node Examining Properties
2629 @subsection Examining Text Properties
2631   The simplest way to examine text properties is to ask for the value of
2632 a particular property of a particular character.  For that, use
2633 @code{get-text-property}.  Use @code{text-properties-at} to get the
2634 entire property list of a character.  @xref{Property Search}, for
2635 functions to examine the properties of a number of characters at once.
2637   These functions handle both strings and buffers.  Keep in mind that
2638 positions in a string start from 0, whereas positions in a buffer start
2639 from 1.
2641 @defun get-text-property pos prop &optional object
2642 This function returns the value of the @var{prop} property of the
2643 character after position @var{pos} in @var{object} (a buffer or
2644 string).  The argument @var{object} is optional and defaults to the
2645 current buffer.
2647 If there is no @var{prop} property strictly speaking, but the character
2648 has a property category that is a symbol, then @code{get-text-property} returns
2649 the @var{prop} property of that symbol.
2650 @end defun
2652 @defun get-char-property position prop &optional object
2653 This function is like @code{get-text-property}, except that it checks
2654 overlays first and then text properties.  @xref{Overlays}.
2656 The argument @var{object} may be a string, a buffer, or a window.  If
2657 it is a window, then the buffer displayed in that window is used for
2658 text properties and overlays, but only the overlays active for that
2659 window are considered.  If @var{object} is a buffer, then overlays in
2660 that buffer are considered first, in order of decreasing priority,
2661 followed by the text properties.  If @var{object} is a string, only
2662 text properties are considered, since strings never have overlays.
2663 @end defun
2665 @defun get-char-property-and-overlay position prop &optional object
2666 This is like @code{get-char-property}, but gives extra information
2667 about the overlay that the property value comes from.
2669 Its value is a cons cell whose @sc{car} is the property value, the
2670 same value @code{get-char-property} would return with the same
2671 arguments.  Its @sc{cdr} is the overlay in which the property was
2672 found, or @code{nil}, if it was found as a text property or not found
2673 at all.
2675 If @var{position} is at the end of @var{object}, both the @sc{car} and
2676 the @sc{cdr} of the value are @code{nil}.
2677 @end defun
2679 @defvar char-property-alias-alist
2680 This variable holds an alist which maps property names to a list of
2681 alternative property names.  If a character does not specify a direct
2682 value for a property, the alternative property names are consulted in
2683 order; the first non-@code{nil} value is used.  This variable takes
2684 precedence over @code{default-text-properties}, and @code{category}
2685 properties take precedence over this variable.
2686 @end defvar
2688 @defun text-properties-at position &optional object
2689 This function returns the entire property list of the character at
2690 @var{position} in the string or buffer @var{object}.  If @var{object} is
2691 @code{nil}, it defaults to the current buffer.
2692 @end defun
2694 @defvar default-text-properties
2695 This variable holds a property list giving default values for text
2696 properties.  Whenever a character does not specify a value for a
2697 property, neither directly, through a category symbol, or through
2698 @code{char-property-alias-alist}, the value stored in this list is
2699 used instead.  Here is an example:
2701 @example
2702 (setq default-text-properties '(foo 69)
2703       char-property-alias-alist nil)
2704 ;; @r{Make sure character 1 has no properties of its own.}
2705 (set-text-properties 1 2 nil)
2706 ;; @r{What we get, when we ask, is the default value.}
2707 (get-text-property 1 'foo)
2708      @result{} 69
2709 @end example
2710 @end defvar
2712 @node Changing Properties
2713 @subsection Changing Text Properties
2715   The primitives for changing properties apply to a specified range of
2716 text in a buffer or string.  The function @code{set-text-properties}
2717 (see end of section) sets the entire property list of the text in that
2718 range; more often, it is useful to add, change, or delete just certain
2719 properties specified by name.
2721   Since text properties are considered part of the contents of the
2722 buffer (or string), and can affect how a buffer looks on the screen,
2723 any change in buffer text properties marks the buffer as modified.
2724 Buffer text property changes are undoable also (@pxref{Undo}).
2725 Positions in a string start from 0, whereas positions in a buffer
2726 start from 1.
2728 @defun put-text-property start end prop value &optional object
2729 This function sets the @var{prop} property to @var{value} for the text
2730 between @var{start} and @var{end} in the string or buffer @var{object}.
2731 If @var{object} is @code{nil}, it defaults to the current buffer.
2732 @end defun
2734 @defun add-text-properties start end props &optional object
2735 This function adds or overrides text properties for the text between
2736 @var{start} and @var{end} in the string or buffer @var{object}.  If
2737 @var{object} is @code{nil}, it defaults to the current buffer.
2739 The argument @var{props} specifies which properties to add.  It should
2740 have the form of a property list (@pxref{Property Lists}): a list whose
2741 elements include the property names followed alternately by the
2742 corresponding values.
2744 The return value is @code{t} if the function actually changed some
2745 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2746 its values agree with those in the text).
2748 For example, here is how to set the @code{comment} and @code{face}
2749 properties of a range of text:
2751 @example
2752 (add-text-properties @var{start} @var{end}
2753                      '(comment t face highlight))
2754 @end example
2755 @end defun
2757 @defun remove-text-properties start end props &optional object
2758 This function deletes specified text properties from the text between
2759 @var{start} and @var{end} in the string or buffer @var{object}.  If
2760 @var{object} is @code{nil}, it defaults to the current buffer.
2762 The argument @var{props} specifies which properties to delete.  It
2763 should have the form of a property list (@pxref{Property Lists}): a list
2764 whose elements are property names alternating with corresponding values.
2765 But only the names matter---the values that accompany them are ignored.
2766 For example, here's how to remove the @code{face} property.
2768 @example
2769 (remove-text-properties @var{start} @var{end} '(face nil))
2770 @end example
2772 The return value is @code{t} if the function actually changed some
2773 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2774 if no character in the specified text had any of those properties).
2776 To remove all text properties from certain text, use
2777 @code{set-text-properties} and specify @code{nil} for the new property
2778 list.
2779 @end defun
2781 @defun remove-list-of-text-properties start end list-of-properties &optional object
2782 Like @code{remove-text-properties} except that
2783 @var{list-of-properties} is a list of property names only, not an
2784 alternating list of property names and values.
2785 @end defun
2787 @defun set-text-properties start end props &optional object
2788 This function completely replaces the text property list for the text
2789 between @var{start} and @var{end} in the string or buffer @var{object}.
2790 If @var{object} is @code{nil}, it defaults to the current buffer.
2792 The argument @var{props} is the new property list.  It should be a list
2793 whose elements are property names alternating with corresponding values.
2795 After @code{set-text-properties} returns, all the characters in the
2796 specified range have identical properties.
2798 If @var{props} is @code{nil}, the effect is to get rid of all properties
2799 from the specified range of text.  Here's an example:
2801 @example
2802 (set-text-properties @var{start} @var{end} nil)
2803 @end example
2805 Do not rely on the return value of this function.
2806 @end defun
2808   The easiest way to make a string with text properties
2809 is with @code{propertize}:
2811 @defun propertize string &rest properties
2812 This function returns a copy of @var{string} which has the text
2813 properties @var{properties}.  These properties apply to all the
2814 characters in the string that is returned.  Here is an example that
2815 constructs a string with a @code{face} property and a @code{mouse-face}
2816 property:
2818 @smallexample
2819 (propertize "foo" 'face 'italic
2820             'mouse-face 'bold-italic)
2821      @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
2822 @end smallexample
2824 To put different properties on various parts of a string, you can
2825 construct each part with @code{propertize} and then combine them with
2826 @code{concat}:
2828 @smallexample
2829 (concat
2830  (propertize "foo" 'face 'italic
2831              'mouse-face 'bold-italic)
2832  " and "
2833  (propertize "bar" 'face 'italic
2834              'mouse-face 'bold-italic))
2835      @result{} #("foo and bar"
2836                  0 3 (face italic mouse-face bold-italic)
2837                  3 8 nil
2838                  8 11 (face italic mouse-face bold-italic))
2839 @end smallexample
2840 @end defun
2842   @xref{Buffer Contents}, for the function
2843 @code{buffer-substring-no-properties}, which copies text from the
2844 buffer but does not copy its properties.
2846 @node Property Search
2847 @subsection Text Property Search Functions
2849   In typical use of text properties, most of the time several or many
2850 consecutive characters have the same value for a property.  Rather than
2851 writing your programs to examine characters one by one, it is much
2852 faster to process chunks of text that have the same property value.
2854   Here are functions you can use to do this.  They use @code{eq} for
2855 comparing property values.  In all cases, @var{object} defaults to the
2856 current buffer.
2858   For good performance, it's very important to use the @var{limit}
2859 argument to these functions, especially the ones that search for a
2860 single property---otherwise, they may spend a long time scanning to the
2861 end of the buffer, if the property you are interested in does not change.
2863   These functions do not move point; instead, they return a position (or
2864 @code{nil}).  Remember that a position is always between two characters;
2865 the position returned by these functions is between two characters with
2866 different properties.
2868 @defun next-property-change pos &optional object limit
2869 The function scans the text forward from position @var{pos} in the
2870 string or buffer @var{object} until it finds a change in some text
2871 property, then returns the position of the change.  In other words, it
2872 returns the position of the first character beyond @var{pos} whose
2873 properties are not identical to those of the character just after
2874 @var{pos}.
2876 If @var{limit} is non-@code{nil}, then the scan ends at position
2877 @var{limit}.  If there is no property change before that point, this
2878 function returns @var{limit}.
2880 The value is @code{nil} if the properties remain unchanged all the way
2881 to the end of @var{object} and @var{limit} is @code{nil}.  If the value
2882 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
2883 The value equals @var{pos} only when @var{limit} equals @var{pos}.
2885 Here is an example of how to scan the buffer by chunks of text within
2886 which all properties are constant:
2888 @smallexample
2889 (while (not (eobp))
2890   (let ((plist (text-properties-at (point)))
2891         (next-change
2892          (or (next-property-change (point) (current-buffer))
2893              (point-max))))
2894     @r{Process text from point to @var{next-change}@dots{}}
2895     (goto-char next-change)))
2896 @end smallexample
2897 @end defun
2899 @defun previous-property-change pos &optional object limit
2900 This is like @code{next-property-change}, but scans back from @var{pos}
2901 instead of forward.  If the value is non-@code{nil}, it is a position
2902 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
2903 equals @var{pos}.
2904 @end defun
2906 @defun next-single-property-change pos prop &optional object limit
2907 The function scans text for a change in the @var{prop} property, then
2908 returns the position of the change.  The scan goes forward from
2909 position @var{pos} in the string or buffer @var{object}.  In other
2910 words, this function returns the position of the first character
2911 beyond @var{pos} whose @var{prop} property differs from that of the
2912 character just after @var{pos}.
2914 If @var{limit} is non-@code{nil}, then the scan ends at position
2915 @var{limit}.  If there is no property change before that point,
2916 @code{next-single-property-change} returns @var{limit}.
2918 The value is @code{nil} if the property remains unchanged all the way to
2919 the end of @var{object} and @var{limit} is @code{nil}.  If the value is
2920 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
2921 equals @var{pos} only if @var{limit} equals @var{pos}.
2922 @end defun
2924 @defun previous-single-property-change pos prop &optional object limit
2925 This is like @code{next-single-property-change}, but scans back from
2926 @var{pos} instead of forward.  If the value is non-@code{nil}, it is a
2927 position less than or equal to @var{pos}; it equals @var{pos} only if
2928 @var{limit} equals @var{pos}.
2929 @end defun
2931 @defun next-char-property-change pos &optional limit
2932 This is like @code{next-property-change} except that it considers
2933 overlay properties as well as text properties, and if no change is
2934 found before the end of the buffer, it returns the maximum buffer
2935 position rather than @code{nil} (in this sense, it resembles the
2936 corresponding overlay function @code{next-overlay-change}, rather than
2937 @code{next-property-change}).  There is no @var{object} operand
2938 because this function operates only on the current buffer.  It returns
2939 the next address at which either kind of property changes.
2940 @end defun
2942 @defun previous-char-property-change pos &optional limit
2943 This is like @code{next-char-property-change}, but scans back from
2944 @var{pos} instead of forward, and returns the minimum buffer
2945 position if no change is found.
2946 @end defun
2948 @defun next-single-char-property-change pos prop &optional object limit
2949 This is like @code{next-single-property-change} except that it
2950 considers overlay properties as well as text properties, and if no
2951 change is found before the end of the @var{object}, it returns the
2952 maximum valid position in @var{object} rather than @code{nil}.  Unlike
2953 @code{next-char-property-change}, this function @emph{does} have an
2954 @var{object} operand; if @var{object} is not a buffer, only
2955 text-properties are considered.
2956 @end defun
2958 @defun previous-single-char-property-change pos prop &optional object limit
2959 This is like @code{next-single-char-property-change}, but scans back
2960 from @var{pos} instead of forward, and returns the minimum valid
2961 position in @var{object} if no change is found.
2962 @end defun
2964 @defun text-property-any start end prop value &optional object
2965 This function returns non-@code{nil} if at least one character between
2966 @var{start} and @var{end} has a property @var{prop} whose value is
2967 @var{value}.  More precisely, it returns the position of the first such
2968 character.  Otherwise, it returns @code{nil}.
2970 The optional fifth argument, @var{object}, specifies the string or
2971 buffer to scan.  Positions are relative to @var{object}.  The default
2972 for @var{object} is the current buffer.
2973 @end defun
2975 @defun text-property-not-all start end prop value &optional object
2976 This function returns non-@code{nil} if at least one character between
2977 @var{start} and @var{end} does not have a property @var{prop} with value
2978 @var{value}.  More precisely, it returns the position of the first such
2979 character.  Otherwise, it returns @code{nil}.
2981 The optional fifth argument, @var{object}, specifies the string or
2982 buffer to scan.  Positions are relative to @var{object}.  The default
2983 for @var{object} is the current buffer.
2984 @end defun
2986 @node Special Properties
2987 @subsection Properties with Special Meanings
2989   Here is a table of text property names that have special built-in
2990 meanings.  The following sections list a few additional special property
2991 names that control filling and property inheritance.  All other names
2992 have no standard meaning, and you can use them as you like.
2994   Note: the properties @code{composition}, @code{display},
2995 @code{invisible} and @code{intangible} can also cause point to move to
2996 an acceptable place, after each Emacs command.  @xref{Adjusting
2997 Point}.
2999 @table @code
3000 @cindex property category of text character
3001 @kindex category @r{(text property)}
3002 @item category
3003 If a character has a @code{category} property, we call it the
3004 @dfn{property category} of the character.  It should be a symbol.  The
3005 properties of this symbol serve as defaults for the properties of the
3006 character.
3008 @item face
3009 @cindex face codes of text
3010 @kindex face @r{(text property)}
3011 The @code{face} property controls the appearance of the character,
3012 such as its font and color.  @xref{Faces}.  The value of the property
3013 can be the following:
3015 @itemize @bullet
3016 @item
3017 A face name (a symbol or string).
3019 @item
3020 A property list of face attributes.  This has the form (@var{keyword}
3021 @var{value} @dots{}), where each @var{keyword} is a face attribute
3022 name and @var{value} is a meaningful value for that attribute.  With
3023 this feature, you do not need to create a face each time you want to
3024 specify a particular attribute for certain text.
3026 @item
3027 A list of faces.  This specifies a face which is an aggregate of the
3028 attributes of each of the listed faces.  Faces occurring earlier in
3029 the list have higher priority.  Each list element must have one of the
3030 two above forms (i.e.@: either a face name or a property list of face
3031 attributes).
3032 @end itemize
3034 Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
3035 dynamically updating the @code{face} property of characters based on
3036 the context.
3038 @item font-lock-face
3039 @kindex font-lock-face @r{(text property)}
3040 This property specifies a value for the @code{face} property that Font
3041 Lock mode should apply to the underlying text.  It is one of the
3042 fontification methods used by Font Lock mode, and is useful for
3043 special modes that implement their own highlighting.
3044 @xref{Precalculated Fontification}.  When Font Lock mode is disabled,
3045 @code{font-lock-face} has no effect.
3047 @item mouse-face
3048 @kindex mouse-face @r{(text property)}
3049 This property is used instead of @code{face} when the mouse is on or
3050 near the character.  For this purpose, ``near'' means that all text
3051 between the character and where the mouse is have the same
3052 @code{mouse-face} property value.
3054 Emacs ignores all face attributes from the @code{mouse-face} property
3055 that alter the text size (e.g. @code{:height}, @code{:weight}, and
3056 @code{:slant}).  Those attributes are always the same as for the
3057 unhighlighted text.
3059 @item fontified
3060 @kindex fontified @r{(text property)}
3061 This property says whether the text is ready for display.  If
3062 @code{nil}, Emacs's redisplay routine calls the functions in
3063 @code{fontification-functions} (@pxref{Auto Faces}) to prepare this
3064 part of the buffer before it is displayed.  It is used internally by
3065 the ``just in time'' font locking code.
3067 @item display
3068 This property activates various features that change the
3069 way text is displayed.  For example, it can make text appear taller
3070 or shorter, higher or lower, wider or narrow, or replaced with an image.
3071 @xref{Display Property}.
3073 @item help-echo
3074 @kindex help-echo @r{(text property)}
3075 @cindex tooltip
3076 @anchor{Text help-echo}
3077 If text has a string as its @code{help-echo} property, then when you
3078 move the mouse onto that text, Emacs displays that string in the echo
3079 area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
3080 Manual}).
3082 If the value of the @code{help-echo} property is a function, that
3083 function is called with three arguments, @var{window}, @var{object} and
3084 @var{pos} and should return a help string or @code{nil} for
3085 none.  The first argument, @var{window} is the window in which
3086 the help was found.  The second, @var{object}, is the buffer, overlay or
3087 string which had the @code{help-echo} property.  The @var{pos}
3088 argument is as follows:
3090 @itemize @bullet{}
3091 @item
3092 If @var{object} is a buffer, @var{pos} is the position in the buffer.
3093 @item
3094 If @var{object} is an overlay, that overlay has a @code{help-echo}
3095 property, and @var{pos} is the position in the overlay's buffer.
3096 @item
3097 If @var{object} is a string (an overlay string or a string displayed
3098 with the @code{display} property), @var{pos} is the position in that
3099 string.
3100 @end itemize
3102 If the value of the @code{help-echo} property is neither a function nor
3103 a string, it is evaluated to obtain a help string.
3105 You can alter the way help text is displayed by setting the variable
3106 @code{show-help-function} (@pxref{Help display}).
3108 This feature is used in the mode line and for other active text.
3110 @item keymap
3111 @cindex keymap of character
3112 @kindex keymap @r{(text property)}
3113 The @code{keymap} property specifies an additional keymap for
3114 commands.  When this keymap applies, it is used for key lookup before
3115 the minor mode keymaps and before the buffer's local map.
3116 @xref{Active Keymaps}.  If the property value is a symbol, the
3117 symbol's function definition is used as the keymap.
3119 The property's value for the character before point applies if it is
3120 non-@code{nil} and rear-sticky, and the property's value for the
3121 character after point applies if it is non-@code{nil} and
3122 front-sticky.  (For mouse clicks, the position of the click is used
3123 instead of the position of point.)
3125 @item local-map
3126 @kindex local-map @r{(text property)}
3127 This property works like @code{keymap} except that it specifies a
3128 keymap to use @emph{instead of} the buffer's local map.  For most
3129 purposes (perhaps all purposes), it is better to use the @code{keymap}
3130 property.
3132 @item syntax-table
3133 The @code{syntax-table} property overrides what the syntax table says
3134 about this particular character.  @xref{Syntax Properties}.
3136 @item read-only
3137 @cindex read-only character
3138 @kindex read-only @r{(text property)}
3139 If a character has the property @code{read-only}, then modifying that
3140 character is not allowed.  Any command that would do so gets an error,
3141 @code{text-read-only}.  If the property value is a string, that string
3142 is used as the error message.
3144 Insertion next to a read-only character is an error if inserting
3145 ordinary text there would inherit the @code{read-only} property due to
3146 stickiness.  Thus, you can control permission to insert next to
3147 read-only text by controlling the stickiness.  @xref{Sticky Properties}.
3149 Since changing properties counts as modifying the buffer, it is not
3150 possible to remove a @code{read-only} property unless you know the
3151 special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
3152 and then remove the property.  @xref{Read Only Buffers}.
3154 @item invisible
3155 @kindex invisible @r{(text property)}
3156 A non-@code{nil} @code{invisible} property can make a character invisible
3157 on the screen.  @xref{Invisible Text}, for details.
3159 @item intangible
3160 @kindex intangible @r{(text property)}
3161 If a group of consecutive characters have equal and non-@code{nil}
3162 @code{intangible} properties, then you cannot place point between them.
3163 If you try to move point forward into the group, point actually moves to
3164 the end of the group.  If you try to move point backward into the group,
3165 point actually moves to the start of the group.
3167 If consecutive characters have unequal non-@code{nil}
3168 @code{intangible} properties, they belong to separate groups; each
3169 group is separately treated as described above.
3171 When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
3172 the @code{intangible} property is ignored.
3174 Beware: this property operates at a very low level, and affects a lot of code
3175 in unexpected ways.  So use it with extreme caution.  A common misuse is to put
3176 an intangible property on invisible text, which is actually unnecessary since
3177 the command loop will move point outside of the invisible text at the end of
3178 each command anyway.  @xref{Adjusting Point}.
3180 @item field
3181 @kindex field @r{(text property)}
3182 Consecutive characters with the same @code{field} property constitute a
3183 @dfn{field}.  Some motion functions including @code{forward-word} and
3184 @code{beginning-of-line} stop moving at a field boundary.
3185 @xref{Fields}.
3187 @item cursor
3188 @kindex cursor @r{(text property)}
3189 Normally, the cursor is displayed at the beginning or the end of any
3190 overlay and text property strings present at the current buffer
3191 position.  You can place the cursor on any desired character of these
3192 strings by giving that character a non-@code{nil} @code{cursor} text
3193 property.  In addition, if the value of the @code{cursor} property is
3194 an integer number, it specifies the number of buffer's character
3195 positions, starting with the position where the overlay or the
3196 @code{display} property begins, for which the cursor should be
3197 displayed on that character.  Specifically, if the value of the
3198 @code{cursor} property of a character is the number @var{n}, the
3199 cursor will be displayed on this character for any buffer position in
3200 the range @code{[@var{ovpos}..@var{ovpos}+@var{n})}, where @var{ovpos}
3201 is the overlay's starting position given by @code{overlay-start}
3202 (@pxref{Managing Overlays}), or the position where the @code{display}
3203 text property begins in the buffer.
3205 In other words, the string character with the @code{cursor} property
3206 of any non-@code{nil} value is the character where to display the
3207 cursor.  The value of the property says for which buffer positions to
3208 display the cursor there.  If the value is an integer number @var{n},
3209 the cursor is displayed there when point is anywhere between the
3210 beginning of the overlay or @code{display} property and @var{n}
3211 positions after that.  If the value is anything else and
3212 non-@code{nil}, the cursor is displayed there only when point is at
3213 the beginning of the @code{display} property or at
3214 @code{overlay-start}.
3216 @cindex cursor position for @code{display} properties and overlays
3217 When the buffer has many overlay strings (e.g., @pxref{Overlay
3218 Properties, before-string}) or @code{display} properties that are
3219 strings, it is a good idea to use the @code{cursor} property on these
3220 strings to cue the Emacs display about the places where to put the
3221 cursor while traversing these strings.  This directly communicates to
3222 the display engine where the Lisp program wants to put the cursor, or
3223 where the user would expect the cursor.
3225 @item pointer
3226 @kindex pointer @r{(text property)}
3227 This specifies a specific pointer shape when the mouse pointer is over
3228 this text or image.  @xref{Pointer Shape}, for possible pointer
3229 shapes.
3231 @item line-spacing
3232 @kindex line-spacing @r{(text property)}
3233 A newline can have a @code{line-spacing} text or overlay property that
3234 controls the height of the display line ending with that newline.  The
3235 property value overrides the default frame line spacing and the buffer
3236 local @code{line-spacing} variable.  @xref{Line Height}.
3238 @item line-height
3239 @kindex line-height @r{(text property)}
3240 A newline can have a @code{line-height} text or overlay property that
3241 controls the total height of the display line ending in that newline.
3242 @xref{Line Height}.
3244 @item wrap-prefix
3245 If text has a @code{wrap-prefix} property, the prefix it defines will
3246 be added at display time to the beginning of every continuation line
3247 due to text wrapping (so if lines are truncated, the wrap-prefix is
3248 never used).  It may be a string or an image (@pxref{Other Display
3249 Specs}), or a stretch of whitespace such as specified by the
3250 @code{:width} or @code{:align-to} display properties (@pxref{Specified
3251 Space}).
3253 A wrap-prefix may also be specified for an entire buffer using the
3254 @code{wrap-prefix} buffer-local variable (however, a
3255 @code{wrap-prefix} text-property takes precedence over the value of
3256 the @code{wrap-prefix} variable).  @xref{Truncation}.
3258 @item line-prefix
3259 If text has a @code{line-prefix} property, the prefix it defines will
3260 be added at display time to the beginning of every non-continuation
3261 line.  It may be a string or an image (@pxref{Other Display
3262 Specs}), or a stretch of whitespace such as specified by the
3263 @code{:width} or @code{:align-to} display properties (@pxref{Specified
3264 Space}).
3266 A line-prefix may also be specified for an entire buffer using the
3267 @code{line-prefix} buffer-local variable (however, a
3268 @code{line-prefix} text-property takes precedence over the value of
3269 the @code{line-prefix} variable).  @xref{Truncation}.
3271 @item modification-hooks
3272 @cindex change hooks for a character
3273 @cindex hooks for changing a character
3274 @kindex modification-hooks @r{(text property)}
3275 If a character has the property @code{modification-hooks}, then its
3276 value should be a list of functions; modifying that character calls
3277 all of those functions before the actual modification.  Each function
3278 receives two arguments: the beginning and end of the part of the
3279 buffer being modified.  Note that if a particular modification hook
3280 function appears on several characters being modified by a single
3281 primitive, you can't predict how many times the function will
3282 be called.
3283 Furthermore, insertion will not modify any existing character, so this
3284 hook will only be run when removing some characters, replacing them
3285 with others, or changing their text-properties.
3287 If these functions modify the buffer, they should bind
3288 @code{inhibit-modification-hooks} to @code{t} around doing so, to
3289 avoid confusing the internal mechanism that calls these hooks.
3291 Overlays also support the @code{modification-hooks} property, but the
3292 details are somewhat different (@pxref{Overlay Properties}).
3294 @item insert-in-front-hooks
3295 @itemx insert-behind-hooks
3296 @kindex insert-in-front-hooks @r{(text property)}
3297 @kindex insert-behind-hooks @r{(text property)}
3298 The operation of inserting text in a buffer also calls the functions
3299 listed in the @code{insert-in-front-hooks} property of the following
3300 character and in the @code{insert-behind-hooks} property of the
3301 preceding character.  These functions receive two arguments, the
3302 beginning and end of the inserted text.  The functions are called
3303 @emph{after} the actual insertion takes place.
3305 See also @ref{Change Hooks}, for other hooks that are called
3306 when you change text in a buffer.
3308 @item point-entered
3309 @itemx point-left
3310 @cindex hooks for motion of point
3311 @kindex point-entered @r{(text property)}
3312 @kindex point-left @r{(text property)}
3313 The special properties @code{point-entered} and @code{point-left}
3314 record hook functions that report motion of point.  Each time point
3315 moves, Emacs compares these two property values:
3317 @itemize @bullet
3318 @item
3319 the @code{point-left} property of the character after the old location,
3321 @item
3322 the @code{point-entered} property of the character after the new
3323 location.
3324 @end itemize
3326 @noindent
3327 If these two values differ, each of them is called (if not @code{nil})
3328 with two arguments: the old value of point, and the new one.
3330 The same comparison is made for the characters before the old and new
3331 locations.  The result may be to execute two @code{point-left} functions
3332 (which may be the same function) and/or two @code{point-entered}
3333 functions (which may be the same function).  In any case, all the
3334 @code{point-left} functions are called first, followed by all the
3335 @code{point-entered} functions.
3337 It is possible to use @code{char-after} to examine characters at various
3338 buffer positions without moving point to those positions.  Only an
3339 actual change in the value of point runs these hook functions.
3341 The variable @code{inhibit-point-motion-hooks} can inhibit running the
3342 @code{point-left} and @code{point-entered} hooks, see @ref{Inhibit
3343 point motion hooks}.
3345 @item composition
3346 @kindex composition @r{(text property)}
3347 This text property is used to display a sequence of characters as a
3348 single glyph composed from components.  But the value of the property
3349 itself is completely internal to Emacs and should not be manipulated
3350 directly by, for instance, @code{put-text-property}.
3352 @end table
3354 @defvar inhibit-point-motion-hooks
3355 @anchor{Inhibit point motion hooks} When this variable is
3356 non-@code{nil}, @code{point-left} and @code{point-entered} hooks are
3357 not run, and the @code{intangible} property has no effect.  Do not set
3358 this variable globally; bind it with @code{let}.
3359 @end defvar
3361 @defvar show-help-function
3362 @anchor{Help display} If this variable is non-@code{nil}, it specifies a
3363 function called to display help strings.  These may be @code{help-echo}
3364 properties, menu help strings (@pxref{Simple Menu Items},
3365 @pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
3366 Bar}).  The specified function is called with one argument, the help
3367 string to display.  Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs
3368 Manual}) provides an example.
3369 @end defvar
3371 @node Format Properties
3372 @subsection Formatted Text Properties
3374   These text properties affect the behavior of the fill commands.  They
3375 are used for representing formatted text.  @xref{Filling}, and
3376 @ref{Margins}.
3378 @table @code
3379 @item hard
3380 If a newline character has this property, it is a ``hard'' newline.
3381 The fill commands do not alter hard newlines and do not move words
3382 across them.  However, this property takes effect only if the
3383 @code{use-hard-newlines} minor mode is enabled.  @xref{Hard and Soft
3384 Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
3386 @item right-margin
3387 This property specifies an extra right margin for filling this part of the
3388 text.
3390 @item left-margin
3391 This property specifies an extra left margin for filling this part of the
3392 text.
3394 @item justification
3395 This property specifies the style of justification for filling this part
3396 of the text.
3397 @end table
3399 @node Sticky Properties
3400 @subsection Stickiness of Text Properties
3401 @cindex sticky text properties
3402 @cindex inheritance, text property
3404   Self-inserting characters normally take on the same properties as the
3405 preceding character.  This is called @dfn{inheritance} of properties.
3407   A Lisp program can do insertion with inheritance or without,
3408 depending on the choice of insertion primitive.  The ordinary text
3409 insertion functions, such as @code{insert}, do not inherit any
3410 properties.  They insert text with precisely the properties of the
3411 string being inserted, and no others.  This is correct for programs
3412 that copy text from one context to another---for example, into or out
3413 of the kill ring.  To insert with inheritance, use the special
3414 primitives described in this section.  Self-inserting characters
3415 inherit properties because they work using these primitives.
3417   When you do insertion with inheritance, @emph{which} properties are
3418 inherited, and from where, depends on which properties are @dfn{sticky}.
3419 Insertion after a character inherits those of its properties that are
3420 @dfn{rear-sticky}.  Insertion before a character inherits those of its
3421 properties that are @dfn{front-sticky}.  When both sides offer different
3422 sticky values for the same property, the previous character's value
3423 takes precedence.
3425   By default, a text property is rear-sticky but not front-sticky; thus,
3426 the default is to inherit all the properties of the preceding character,
3427 and nothing from the following character.
3429   You can control the stickiness of various text properties with two
3430 specific text properties, @code{front-sticky} and @code{rear-nonsticky},
3431 and with the variable @code{text-property-default-nonsticky}.  You can
3432 use the variable to specify a different default for a given property.
3433 You can use those two text properties to make any specific properties
3434 sticky or nonsticky in any particular part of the text.
3436   If a character's @code{front-sticky} property is @code{t}, then all
3437 its properties are front-sticky.  If the @code{front-sticky} property is
3438 a list, then the sticky properties of the character are those whose
3439 names are in the list.  For example, if a character has a
3440 @code{front-sticky} property whose value is @code{(face read-only)},
3441 then insertion before the character can inherit its @code{face} property
3442 and its @code{read-only} property, but no others.
3444   The @code{rear-nonsticky} property works the opposite way.  Most
3445 properties are rear-sticky by default, so the @code{rear-nonsticky}
3446 property says which properties are @emph{not} rear-sticky.  If a
3447 character's @code{rear-nonsticky} property is @code{t}, then none of its
3448 properties are rear-sticky.  If the @code{rear-nonsticky} property is a
3449 list, properties are rear-sticky @emph{unless} their names are in the
3450 list.
3452 @defvar text-property-default-nonsticky
3453 This variable holds an alist which defines the default rear-stickiness
3454 of various text properties.  Each element has the form
3455 @code{(@var{property} . @var{nonstickiness})}, and it defines the
3456 stickiness of a particular text property, @var{property}.
3458 If @var{nonstickiness} is non-@code{nil}, this means that the property
3459 @var{property} is rear-nonsticky by default.  Since all properties are
3460 front-nonsticky by default, this makes @var{property} nonsticky in both
3461 directions by default.
3463 The text properties @code{front-sticky} and @code{rear-nonsticky}, when
3464 used, take precedence over the default @var{nonstickiness} specified in
3465 @code{text-property-default-nonsticky}.
3466 @end defvar
3468   Here are the functions that insert text with inheritance of properties:
3470 @defun insert-and-inherit &rest strings
3471 Insert the strings @var{strings}, just like the function @code{insert},
3472 but inherit any sticky properties from the adjoining text.
3473 @end defun
3475 @defun insert-before-markers-and-inherit &rest strings
3476 Insert the strings @var{strings}, just like the function
3477 @code{insert-before-markers}, but inherit any sticky properties from the
3478 adjoining text.
3479 @end defun
3481   @xref{Insertion}, for the ordinary insertion functions which do not
3482 inherit.
3484 @node Lazy Properties
3485 @subsection Lazy Computation of Text Properties
3487   Instead of computing text properties for all the text in the buffer,
3488 you can arrange to compute the text properties for parts of the text
3489 when and if something depends on them.
3491   The primitive that extracts text from the buffer along with its
3492 properties is @code{buffer-substring}.  Before examining the properties,
3493 this function runs the abnormal hook @code{buffer-access-fontify-functions}.
3495 @defvar buffer-access-fontify-functions
3496 This variable holds a list of functions for computing text properties.
3497 Before @code{buffer-substring} copies the text and text properties for a
3498 portion of the buffer, it calls all the functions in this list.  Each of
3499 the functions receives two arguments that specify the range of the
3500 buffer being accessed.  (The buffer itself is always the current
3501 buffer.)
3502 @end defvar
3504   The function @code{buffer-substring-no-properties} does not call these
3505 functions, since it ignores text properties anyway.
3507   In order to prevent the hook functions from being called more than
3508 once for the same part of the buffer, you can use the variable
3509 @code{buffer-access-fontified-property}.
3511 @defvar buffer-access-fontified-property
3512 If this variable's value is non-@code{nil}, it is a symbol which is used
3513 as a text property name.  A non-@code{nil} value for that text property
3514 means, ``the other text properties for this character have already been
3515 computed''.
3517 If all the characters in the range specified for @code{buffer-substring}
3518 have a non-@code{nil} value for this property, @code{buffer-substring}
3519 does not call the @code{buffer-access-fontify-functions} functions.  It
3520 assumes these characters already have the right text properties, and
3521 just copies the properties they already have.
3523 The normal way to use this feature is that the
3524 @code{buffer-access-fontify-functions} functions add this property, as
3525 well as others, to the characters they operate on.  That way, they avoid
3526 being called over and over for the same text.
3527 @end defvar
3529 @node Clickable Text
3530 @subsection Defining Clickable Text
3531 @cindex clickable text
3532 @cindex follow links
3533 @cindex mouse-1
3535   @dfn{Clickable text} is text that can be clicked, with either the
3536 mouse or via a keyboard command, to produce some result.  Many major
3537 modes use clickable text to implement textual hyper-links, or
3538 @dfn{links} for short.
3540   The easiest way to insert and manipulate links is to use the
3541 @code{button} package.  @xref{Buttons}.  In this section, we will
3542 explain how to manually set up clickable text in a buffer, using text
3543 properties.  For simplicity, we will refer to the clickable text as a
3544 @dfn{link}.
3546   Implementing a link involves three separate steps: (1) indicating
3547 clickability when the mouse moves over the link; (2) making @key{RET}
3548 or @kbd{Mouse-2} on that link do something; and (3) setting up a
3549 @code{follow-link} condition so that the link obeys
3550 @code{mouse-1-click-follows-link}.
3552   To indicate clickability, add the @code{mouse-face} text property to
3553 the text of the link; then Emacs will highlight the link when the
3554 mouse moves over it.  In addition, you should define a tooltip or echo
3555 area message, using the @code{help-echo} text property.  @xref{Special
3556 Properties}.  For instance, here is how Dired indicates that file
3557 names are clickable:
3559 @smallexample
3560  (if (dired-move-to-filename)
3561      (add-text-properties
3562        (point)
3563        (save-excursion
3564          (dired-move-to-end-of-filename)
3565          (point))
3566        '(mouse-face highlight
3567          help-echo "mouse-2: visit this file in other window")))
3568 @end smallexample
3570   To make the link clickable, bind @key{RET} and @kbd{Mouse-2} to
3571 commands that perform the desired action.  Each command should check
3572 to see whether it was called on a link, and act accordingly.  For
3573 instance, Dired's major mode keymap binds @kbd{Mouse-2} to the
3574 following command:
3576 @smallexample
3577 (defun dired-mouse-find-file-other-window (event)
3578   "In Dired, visit the file or directory name you click on."
3579   (interactive "e")
3580   (let ((window (posn-window (event-end event)))
3581         (pos (posn-point (event-end event)))
3582         file)
3583     (if (not (windowp window))
3584         (error "No file chosen"))
3585     (with-current-buffer (window-buffer window)
3586       (goto-char pos)
3587       (setq file (dired-get-file-for-visit)))
3588     (if (file-directory-p file)
3589         (or (and (cdr dired-subdir-alist)
3590                  (dired-goto-subdir file))
3591             (progn
3592               (select-window window)
3593               (dired-other-window file)))
3594       (select-window window)
3595       (find-file-other-window (file-name-sans-versions file t)))))
3596 @end smallexample
3598 @noindent
3599 This command uses the functions @code{posn-window} and
3600 @code{posn-point} to determine where the click occurred, and
3601 @code{dired-get-file-for-visit} to determine which file to visit.
3603   Instead of binding the mouse command in a major mode keymap, you can
3604 bind it within the link text, using the @code{keymap} text property
3605 (@pxref{Special Properties}).  For instance:
3607 @example
3608 (let ((map (make-sparse-keymap)))
3609   (define-key map [mouse-2] 'operate-this-button)
3610   (put-text-property link-start link-end 'keymap map))
3611 @end example
3613 @noindent
3614 With this method, you can easily define different commands for
3615 different links.  Furthermore, the global definition of @key{RET} and
3616 @kbd{Mouse-2} remain available for the rest of the text in the buffer.
3618 @vindex mouse-1-click-follows-link
3619   The basic Emacs command for clicking on links is @kbd{Mouse-2}.
3620 However, for compatibility with other graphical applications, Emacs
3621 also recognizes @kbd{Mouse-1} clicks on links, provided the user
3622 clicks on the link quickly without moving the mouse.  This behavior is
3623 controlled by the user option @code{mouse-1-click-follows-link}.
3624 @xref{Mouse References,,, emacs, The GNU Emacs Manual}.
3626   To set up the link so that it obeys
3627 @code{mouse-1-click-follows-link}, you must either (1) apply a
3628 @code{follow-link} text or overlay property to the link text, or (2)
3629 bind the @code{follow-link} event to a keymap (which can be a major
3630 mode keymap or a local keymap specified via the @code{keymap} text
3631 property).  The value of the @code{follow-link} property, or the
3632 binding for the @code{follow-link} event, acts as a ``condition'' for
3633 the link action.  This condition tells Emacs two things: the
3634 circumstances under which a @kbd{Mouse-1} click should be regarded as
3635 occurring ``inside'' the link, and how to compute an ``action code''
3636 that says what to translate the @kbd{Mouse-1} click into.  The link
3637 action condition can be one of the following:
3639 @table @asis
3640 @item @code{mouse-face}
3641 If the condition is the symbol @code{mouse-face}, a position is inside
3642 a link if there is a non-@code{nil} @code{mouse-face} property at that
3643 position.  The action code is always @code{t}.
3645 For example, here is how Info mode handles @key{Mouse-1}:
3647 @smallexample
3648 (define-key Info-mode-map [follow-link] 'mouse-face)
3649 @end smallexample
3651 @item a function
3652 If the condition is a function, @var{func}, then a position @var{pos}
3653 is inside a link if @code{(@var{func} @var{pos})} evaluates to
3654 non-@code{nil}.  The value returned by @var{func} serves as the action
3655 code.
3657 For example, here is how pcvs enables @kbd{Mouse-1} to follow links on
3658 file names only:
3660 @smallexample
3661 (define-key map [follow-link]
3662   (lambda (pos)
3663     (eq (get-char-property pos 'face) 'cvs-filename-face)))
3664 @end smallexample
3666 @item anything else
3667 If the condition value is anything else, then the position is inside a
3668 link and the condition itself is the action code.  Clearly, you should
3669 specify this kind of condition only when applying the condition via a
3670 text or property overlay on the link text (so that it does not apply
3671 to the entire buffer).
3672 @end table
3674 @noindent
3675 The action code tells @kbd{Mouse-1} how to follow the link:
3677 @table @asis
3678 @item a string or vector
3679 If the action code is a string or vector, the @kbd{Mouse-1} event is
3680 translated into the first element of the string or vector; i.e., the
3681 action of the @kbd{Mouse-1} click is the local or global binding of
3682 that character or symbol.  Thus, if the action code is @code{"foo"},
3683 @kbd{Mouse-1} translates into @kbd{f}.  If it is @code{[foo]},
3684 @kbd{Mouse-1} translates into @key{foo}.
3686 @item anything else
3687 For any other non-@code{nil} action code, the @kbd{Mouse-1} event is
3688 translated into a @kbd{Mouse-2} event at the same position.
3689 @end table
3691   To define @kbd{Mouse-1} to activate a button defined with
3692 @code{define-button-type}, give the button a @code{follow-link}
3693 property.  The property value should be a link action condition, as
3694 described above.  @xref{Buttons}.  For example, here is how Help mode
3695 handles @kbd{Mouse-1}:
3697 @smallexample
3698 (define-button-type 'help-xref
3699   'follow-link t
3700   'action #'help-button-action)
3701 @end smallexample
3703   To define @kbd{Mouse-1} on a widget defined with
3704 @code{define-widget}, give the widget a @code{:follow-link} property.
3705 The property value should be a link action condition, as described
3706 above.  For example, here is how the @code{link} widget specifies that
3707 a @key{Mouse-1} click shall be translated to @key{RET}:
3709 @smallexample
3710 (define-widget 'link 'item
3711   "An embedded link."
3712   :button-prefix 'widget-link-prefix
3713   :button-suffix 'widget-link-suffix
3714   :follow-link "\C-m"
3715   :help-echo "Follow the link."
3716   :format "%[%t%]")
3717 @end smallexample
3719 @defun mouse-on-link-p pos
3720 This function returns non-@code{nil} if position @var{pos} in the
3721 current buffer is on a link.  @var{pos} can also be a mouse event
3722 location, as returned by @code{event-start} (@pxref{Accessing Mouse}).
3723 @end defun
3725 @node Fields
3726 @subsection Defining and Using Fields
3727 @cindex fields
3729   A field is a range of consecutive characters in the buffer that are
3730 identified by having the same value (comparing with @code{eq}) of the
3731 @code{field} property (either a text-property or an overlay property).
3732 This section describes special functions that are available for
3733 operating on fields.
3735   You specify a field with a buffer position, @var{pos}.  We think of
3736 each field as containing a range of buffer positions, so the position
3737 you specify stands for the field containing that position.
3739   When the characters before and after @var{pos} are part of the same
3740 field, there is no doubt which field contains @var{pos}: the one those
3741 characters both belong to.  When @var{pos} is at a boundary between
3742 fields, which field it belongs to depends on the stickiness of the
3743 @code{field} properties of the two surrounding characters (@pxref{Sticky
3744 Properties}).  The field whose property would be inherited by text
3745 inserted at @var{pos} is the field that contains @var{pos}.
3747   There is an anomalous case where newly inserted text at @var{pos}
3748 would not inherit the @code{field} property from either side.  This
3749 happens if the previous character's @code{field} property is not
3750 rear-sticky, and the following character's @code{field} property is not
3751 front-sticky.  In this case, @var{pos} belongs to neither the preceding
3752 field nor the following field; the field functions treat it as belonging
3753 to an empty field whose beginning and end are both at @var{pos}.
3755   In all of these functions, if @var{pos} is omitted or @code{nil}, the
3756 value of point is used by default.  If narrowing is in effect, then
3757 @var{pos} should fall within the accessible portion.  @xref{Narrowing}.
3759 @defun field-beginning &optional pos escape-from-edge limit
3760 This function returns the beginning of the field specified by @var{pos}.
3762 If @var{pos} is at the beginning of its field, and
3763 @var{escape-from-edge} is non-@code{nil}, then the return value is
3764 always the beginning of the preceding field that @emph{ends} at @var{pos},
3765 regardless of the stickiness of the @code{field} properties around
3766 @var{pos}.
3768 If @var{limit} is non-@code{nil}, it is a buffer position; if the
3769 beginning of the field is before @var{limit}, then @var{limit} will be
3770 returned instead.
3771 @end defun
3773 @defun field-end &optional pos escape-from-edge limit
3774 This function returns the end of the field specified by @var{pos}.
3776 If @var{pos} is at the end of its field, and @var{escape-from-edge} is
3777 non-@code{nil}, then the return value is always the end of the following
3778 field that @emph{begins} at @var{pos}, regardless of the stickiness of
3779 the @code{field} properties around @var{pos}.
3781 If @var{limit} is non-@code{nil}, it is a buffer position; if the end
3782 of the field is after @var{limit}, then @var{limit} will be returned
3783 instead.
3784 @end defun
3786 @defun field-string &optional pos
3787 This function returns the contents of the field specified by @var{pos},
3788 as a string.
3789 @end defun
3791 @defun field-string-no-properties &optional pos
3792 This function returns the contents of the field specified by @var{pos},
3793 as a string, discarding text properties.
3794 @end defun
3796 @defun delete-field &optional pos
3797 This function deletes the text of the field specified by @var{pos}.
3798 @end defun
3800 @defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
3801 This function ``constrains'' @var{new-pos} to the field that
3802 @var{old-pos} belongs to---in other words, it returns the position
3803 closest to @var{new-pos} that is in the same field as @var{old-pos}.
3805 If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
3806 the value of point instead, and moves point to the resulting position
3807 in addition to returning that position.
3809 If @var{old-pos} is at the boundary of two fields, then the acceptable
3810 final positions depend on the argument @var{escape-from-edge}.  If
3811 @var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in
3812 the field whose @code{field} property equals what new characters
3813 inserted at @var{old-pos} would inherit.  (This depends on the
3814 stickiness of the @code{field} property for the characters before and
3815 after @var{old-pos}.)  If @var{escape-from-edge} is non-@code{nil},
3816 @var{new-pos} can be anywhere in the two adjacent fields.
3817 Additionally, if two fields are separated by another field with the
3818 special value @code{boundary}, then any point within this special
3819 field is also considered to be ``on the boundary''.
3821 Commands like @kbd{C-a} with no argument, that normally move backward
3822 to a specific kind of location and stay there once there, probably
3823 should specify @code{nil} for @var{escape-from-edge}.  Other motion
3824 commands that check fields should probably pass @code{t}.
3826 If the optional argument @var{only-in-line} is non-@code{nil}, and
3827 constraining @var{new-pos} in the usual way would move it to a different
3828 line, @var{new-pos} is returned unconstrained.  This used in commands
3829 that move by line, such as @code{next-line} and
3830 @code{beginning-of-line}, so that they respect field boundaries only in
3831 the case where they can still move to the right line.
3833 If the optional argument @var{inhibit-capture-property} is
3834 non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that
3835 name, then any field boundaries are ignored.
3837 You can cause @code{constrain-to-field} to ignore all field boundaries
3838 (and so never constrain anything) by binding the variable
3839 @code{inhibit-field-text-motion} to a non-@code{nil} value.
3840 @end defun
3842 @node Not Intervals
3843 @subsection Why Text Properties are not Intervals
3844 @cindex intervals
3846   Some editors that support adding attributes to text in the buffer do
3847 so by letting the user specify ``intervals'' within the text, and adding
3848 the properties to the intervals.  Those editors permit the user or the
3849 programmer to determine where individual intervals start and end.  We
3850 deliberately provided a different sort of interface in Emacs Lisp to
3851 avoid certain paradoxical behavior associated with text modification.
3853   If the actual subdivision into intervals is meaningful, that means you
3854 can distinguish between a buffer that is just one interval with a
3855 certain property, and a buffer containing the same text subdivided into
3856 two intervals, both of which have that property.
3858   Suppose you take the buffer with just one interval and kill part of
3859 the text.  The text remaining in the buffer is one interval, and the
3860 copy in the kill ring (and the undo list) becomes a separate interval.
3861 Then if you yank back the killed text, you get two intervals with the
3862 same properties.  Thus, editing does not preserve the distinction
3863 between one interval and two.
3865   Suppose we ``fix'' this problem by coalescing the two intervals when
3866 the text is inserted.  That works fine if the buffer originally was a
3867 single interval.  But suppose instead that we have two adjacent
3868 intervals with the same properties, and we kill the text of one interval
3869 and yank it back.  The same interval-coalescence feature that rescues
3870 the other case causes trouble in this one: after yanking, we have just
3871 one interval.  One again, editing does not preserve the distinction
3872 between one interval and two.
3874   Insertion of text at the border between intervals also raises
3875 questions that have no satisfactory answer.
3877   However, it is easy to arrange for editing to behave consistently for
3878 questions of the form, ``What are the properties of this character?''
3879 So we have decided these are the only questions that make sense; we have
3880 not implemented asking questions about where intervals start or end.
3882   In practice, you can usually use the text property search functions in
3883 place of explicit interval boundaries.  You can think of them as finding
3884 the boundaries of intervals, assuming that intervals are always
3885 coalesced whenever possible.  @xref{Property Search}.
3887   Emacs also provides explicit intervals as a presentation feature; see
3888 @ref{Overlays}.
3890 @node Substitution
3891 @section Substituting for a Character Code
3893   The following functions replace characters within a specified region
3894 based on their character codes.
3896 @defun subst-char-in-region start end old-char new-char &optional noundo
3897 @cindex replace characters
3898 This function replaces all occurrences of the character @var{old-char}
3899 with the character @var{new-char} in the region of the current buffer
3900 defined by @var{start} and @var{end}.
3902 @cindex undo avoidance
3903 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
3904 not record the change for undo and does not mark the buffer as modified.
3905 This was useful for controlling the old selective display feature
3906 (@pxref{Selective Display}).
3908 @code{subst-char-in-region} does not move point and returns
3909 @code{nil}.
3911 @example
3912 @group
3913 ---------- Buffer: foo ----------
3914 This is the contents of the buffer before.
3915 ---------- Buffer: foo ----------
3916 @end group
3918 @group
3919 (subst-char-in-region 1 20 ?i ?X)
3920      @result{} nil
3922 ---------- Buffer: foo ----------
3923 ThXs Xs the contents of the buffer before.
3924 ---------- Buffer: foo ----------
3925 @end group
3926 @end example
3927 @end defun
3929 @deffn Command translate-region start end table
3930 This function applies a translation table to the characters in the
3931 buffer between positions @var{start} and @var{end}.
3933 The translation table @var{table} is a string or a char-table;
3934 @code{(aref @var{table} @var{ochar})} gives the translated character
3935 corresponding to @var{ochar}.  If @var{table} is a string, any
3936 characters with codes larger than the length of @var{table} are not
3937 altered by the translation.
3939 The return value of @code{translate-region} is the number of
3940 characters that were actually changed by the translation.  This does
3941 not count characters that were mapped into themselves in the
3942 translation table.
3943 @end deffn
3945 @node Registers
3946 @section Registers
3947 @cindex registers
3949   A register is a sort of variable used in Emacs editing that can hold a
3950 variety of different kinds of values.  Each register is named by a
3951 single character.  All @acronym{ASCII} characters and their meta variants
3952 (but with the exception of @kbd{C-g}) can be used to name registers.
3953 Thus, there are 255 possible registers.  A register is designated in
3954 Emacs Lisp by the character that is its name.
3956 @defvar register-alist
3957 This variable is an alist of elements of the form @code{(@var{name} .
3958 @var{contents})}.  Normally, there is one element for each Emacs
3959 register that has been used.
3961 The object @var{name} is a character (an integer) identifying the
3962 register.
3963 @end defvar
3965   The @var{contents} of a register can have several possible types:
3967 @table @asis
3968 @item a number
3969 A number stands for itself.  If @code{insert-register} finds a number
3970 in the register, it converts the number to decimal.
3972 @item a marker
3973 A marker represents a buffer position to jump to.
3975 @item a string
3976 A string is text saved in the register.
3978 @item a rectangle
3979 A rectangle is represented by a list of strings.
3981 @item @code{(@var{window-configuration} @var{position})}
3982 This represents a window configuration to restore in one frame, and a
3983 position to jump to in the current buffer.
3985 @item @code{(@var{frame-configuration} @var{position})}
3986 This represents a frame configuration to restore, and a position
3987 to jump to in the current buffer.
3989 @item (file @var{filename})
3990 This represents a file to visit; jumping to this value visits file
3991 @var{filename}.
3993 @item (file-query @var{filename} @var{position})
3994 This represents a file to visit and a position in it; jumping to this
3995 value visits file @var{filename} and goes to buffer position
3996 @var{position}.  Restoring this type of position asks the user for
3997 confirmation first.
3998 @end table
4000   The functions in this section return unpredictable values unless
4001 otherwise stated.
4003 @defun get-register reg
4004 This function returns the contents of the register
4005 @var{reg}, or @code{nil} if it has no contents.
4006 @end defun
4008 @defun set-register reg value
4009 This function sets the contents of register @var{reg} to @var{value}.
4010 A register can be set to any value, but the other register functions
4011 expect only certain data types.  The return value is @var{value}.
4012 @end defun
4014 @deffn Command view-register reg
4015 This command displays what is contained in register @var{reg}.
4016 @end deffn
4018 @deffn Command insert-register reg &optional beforep
4019 This command inserts contents of register @var{reg} into the current
4020 buffer.
4022 Normally, this command puts point before the inserted text, and the
4023 mark after it.  However, if the optional second argument @var{beforep}
4024 is non-@code{nil}, it puts the mark before and point after.
4025 You can pass a non-@code{nil} second argument @var{beforep} to this
4026 function interactively by supplying any prefix argument.
4028 If the register contains a rectangle, then the rectangle is inserted
4029 with its upper left corner at point.  This means that text is inserted
4030 in the current line and underneath it on successive lines.
4032 If the register contains something other than saved text (a string) or
4033 a rectangle (a list), currently useless things happen.  This may be
4034 changed in the future.
4035 @end deffn
4037 @node Transposition
4038 @section Transposition of Text
4040   This function can be used to transpose stretches of text:
4042 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
4043 This function exchanges two nonoverlapping portions of the buffer.
4044 Arguments @var{start1} and @var{end1} specify the bounds of one portion
4045 and arguments @var{start2} and @var{end2} specify the bounds of the
4046 other portion.
4048 Normally, @code{transpose-regions} relocates markers with the transposed
4049 text; a marker previously positioned within one of the two transposed
4050 portions moves along with that portion, thus remaining between the same
4051 two characters in their new position.  However, if @var{leave-markers}
4052 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
4053 all markers unrelocated.
4054 @end defun
4056 @node Base 64
4057 @section Base 64 Encoding
4058 @cindex base 64 encoding
4060   Base 64 code is used in email to encode a sequence of 8-bit bytes as
4061 a longer sequence of @acronym{ASCII} graphic characters.  It is defined in
4062 Internet RFC@footnote{
4063 An RFC, an acronym for @dfn{Request for Comments}, is a numbered
4064 Internet informational document describing a standard.  RFCs are
4065 usually written by technical experts acting on their own initiative,
4066 and are traditionally written in a pragmatic, experience-driven
4067 manner.
4068 }2045.  This section describes the functions for
4069 converting to and from this code.
4071 @deffn Command base64-encode-region beg end &optional no-line-break
4072 This function converts the region from @var{beg} to @var{end} into base
4073 64 code.  It returns the length of the encoded text.  An error is
4074 signaled if a character in the region is multibyte, i.e.@: in a
4075 multibyte buffer the region must contain only characters from the
4076 charsets @code{ascii}, @code{eight-bit-control} and
4077 @code{eight-bit-graphic}.
4079 Normally, this function inserts newline characters into the encoded
4080 text, to avoid overlong lines.  However, if the optional argument
4081 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
4082 the output is just one long line.
4083 @end deffn
4085 @defun base64-encode-string string &optional no-line-break
4086 This function converts the string @var{string} into base 64 code.  It
4087 returns a string containing the encoded text.  As for
4088 @code{base64-encode-region}, an error is signaled if a character in the
4089 string is multibyte.
4091 Normally, this function inserts newline characters into the encoded
4092 text, to avoid overlong lines.  However, if the optional argument
4093 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
4094 the result string is just one long line.
4095 @end defun
4097 @deffn Command base64-decode-region beg end
4098 This function converts the region from @var{beg} to @var{end} from base
4099 64 code into the corresponding decoded text.  It returns the length of
4100 the decoded text.
4102 The decoding functions ignore newline characters in the encoded text.
4103 @end deffn
4105 @defun base64-decode-string string
4106 This function converts the string @var{string} from base 64 code into
4107 the corresponding decoded text.  It returns a unibyte string containing the
4108 decoded text.
4110 The decoding functions ignore newline characters in the encoded text.
4111 @end defun
4113 @node Checksum/Hash
4114 @section Checksum/Hash
4115 @cindex MD5 checksum
4116 @cindex SHA hash
4117 @cindex hash, cryptographic
4118 @cindex cryptographic hash
4120   Emacs has built-in support for computing @dfn{cryptographic hashes}.
4121 A cryptographic hash, or @dfn{checksum}, is a digital ``fingerprint''
4122 of a piece of data (e.g.@: a block of text) which can be used to check
4123 that you have an unaltered copy of that data.
4125 @cindex message digest
4126   Emacs supports several common cryptographic hash algorithms: MD5,
4127 SHA-1, SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512.  MD5 is the
4128 oldest of these algorithms, and is commonly used in @dfn{message
4129 digests} to check the integrity of messages transmitted over a
4130 network.  MD5 is not ``collision resistant'' (i.e.@: it is possible to
4131 deliberately design different pieces of data which have the same MD5
4132 hash), so you should not used it for anything security-related.  A
4133 similar theoretical weakness also exists in SHA-1.  Therefore, for
4134 security-related applications you should use the other hash types,
4135 such as SHA-2.
4137 @defun secure-hash algorithm object &optional start end binary
4138 This function returns a hash for @var{object}.  The argument
4139 @var{algorithm} is a symbol stating which hash to compute: one of
4140 @code{md5}, @code{sha1}, @code{sha224}, @code{sha256}, @code{sha384}
4141 or @code{sha512}.  The argument @var{object} should be a buffer or a
4142 string.
4144 The optional arguments @var{start} and @var{end} are character
4145 positions specifying the portion of @var{object} to compute the
4146 message digest for.  If they are @code{nil} or omitted, the hash is
4147 computed for the whole of @var{object}.
4149 If the argument @var{binary} is omitted or @code{nil}, the function
4150 returns the @dfn{text form} of the hash, as an ordinary Lisp string.
4151 If @var{binary} is non-@code{nil}, it returns the hash in @dfn{binary
4152 form}, as a sequence of bytes stored in a unibyte string.
4154 This function does not compute the hash directly from the internal
4155 representation of @var{object}'s text (@pxref{Text Representations}).
4156 Instead, it encodes the text using a coding system (@pxref{Coding
4157 Systems}), and computes the hash from that encoded text.  If
4158 @var{object} is a buffer, the coding system used is the one which
4159 would be chosen by default for writing the text into a file.  If
4160 @var{object} is a string, the user's preferred coding system is used
4161 (@pxref{Recognize Coding,,, emacs, GNU Emacs Manual}).
4162 @end defun
4164 @defun md5 object &optional start end coding-system noerror
4165 This function returns an MD5 hash.  It is semi-obsolete, since for
4166 most purposes it is equivalent to calling @code{secure-hash} with
4167 @code{md5} as the @var{algorithm} argument.  The @var{object},
4168 @var{start} and @var{end} arguments have the same meanings as in
4169 @code{secure-hash}.
4171 If @var{coding-system} is non-@code{nil}, it specifies a coding system
4172 to use to encode the text; if omitted or @code{nil}, the default
4173 coding system is used, like in @code{secure-hash}.
4175 Normally, @code{md5} signals an error if the text can't be encoded
4176 using the specified or chosen coding system.  However, if
4177 @var{noerror} is non-@code{nil}, it silently uses @code{raw-text}
4178 coding instead.
4179 @end defun
4181 @node Parsing HTML/XML
4182 @section Parsing HTML and XML
4183 @cindex parsing html
4185 When Emacs is compiled with libxml2 support, the following functions
4186 are available to parse HTML or XML text into Lisp object trees.
4188 @defun libxml-parse-html-region start end &optional base-url
4189 This function parses the text between @var{start} and @var{end} as
4190 HTML, and returns a list representing the HTML @dfn{parse tree}.  It
4191 attempts to handle ``real world'' HTML by robustly coping with syntax
4192 mistakes.
4194 The optional argument @var{base-url}, if non-@code{nil}, should be a
4195 string specifying the base URL for relative URLs occurring in links.
4197 In the parse tree, each HTML node is represented by a list in which
4198 the first element is a symbol representing the node name, the second
4199 element is an alist of node attributes, and the remaining elements are
4200 the subnodes.
4202 The following example demonstrates this.  Given this (malformed) HTML
4203 document:
4205 @example
4206 <html><head></head><body width=101><div class=thing>Foo<div>Yes
4207 @end example
4209 @noindent
4210 A call to @code{libxml-parse-html-region} returns this:
4212 @example
4213 (html ()
4214   (head ())
4215   (body ((width . "101"))
4216    (div ((class . "thing"))
4217     "Foo"
4218     (div ()
4219       "Yes"))))
4220 @end example
4221 @end defun
4223 @cindex parsing xml
4224 @defun libxml-parse-xml-region start end &optional base-url
4225 This function is the same as @code{libxml-parse-html-region}, except
4226 that it parses the text as XML rather than HTML (so it is stricter
4227 about syntax).
4228 @end defun
4230 @node Atomic Changes
4231 @section Atomic Change Groups
4232 @cindex atomic changes
4234   In database terminology, an @dfn{atomic} change is an indivisible
4235 change---it can succeed entirely or it can fail entirely, but it
4236 cannot partly succeed.  A Lisp program can make a series of changes to
4237 one or several buffers as an @dfn{atomic change group}, meaning that
4238 either the entire series of changes will be installed in their buffers
4239 or, in case of an error, none of them will be.
4241   To do this for one buffer, the one already current, simply write a
4242 call to @code{atomic-change-group} around the code that makes the
4243 changes, like this:
4245 @example
4246 (atomic-change-group
4247   (insert foo)
4248   (delete-region x y))
4249 @end example
4251 @noindent
4252 If an error (or other nonlocal exit) occurs inside the body of
4253 @code{atomic-change-group}, it unmakes all the changes in that buffer
4254 that were during the execution of the body.  This kind of change group
4255 has no effect on any other buffers---any such changes remain.
4257   If you need something more sophisticated, such as to make changes in
4258 various buffers constitute one atomic group, you must directly call
4259 lower-level functions that @code{atomic-change-group} uses.
4261 @defun prepare-change-group &optional buffer
4262 This function sets up a change group for buffer @var{buffer}, which
4263 defaults to the current buffer.  It returns a ``handle'' that
4264 represents the change group.  You must use this handle to activate the
4265 change group and subsequently to finish it.
4266 @end defun
4268   To use the change group, you must @dfn{activate} it.  You must do
4269 this before making any changes in the text of @var{buffer}.
4271 @defun activate-change-group handle
4272 This function activates the change group that @var{handle} designates.
4273 @end defun
4275   After you activate the change group, any changes you make in that
4276 buffer become part of it.  Once you have made all the desired changes
4277 in the buffer, you must @dfn{finish} the change group.  There are two
4278 ways to do this: you can either accept (and finalize) all the changes,
4279 or cancel them all.
4281 @defun accept-change-group handle
4282 This function accepts all the changes in the change group specified by
4283 @var{handle}, making them final.
4284 @end defun
4286 @defun cancel-change-group handle
4287 This function cancels and undoes all the changes in the change group
4288 specified by @var{handle}.
4289 @end defun
4291   Your code should use @code{unwind-protect} to make sure the group is
4292 always finished.  The call to @code{activate-change-group} should be
4293 inside the @code{unwind-protect}, in case the user types @kbd{C-g}
4294 just after it runs.  (This is one reason why
4295 @code{prepare-change-group} and @code{activate-change-group} are
4296 separate functions, because normally you would call
4297 @code{prepare-change-group} before the start of that
4298 @code{unwind-protect}.)  Once you finish the group, don't use the
4299 handle again---in particular, don't try to finish the same group
4300 twice.
4302   To make a multibuffer change group, call @code{prepare-change-group}
4303 once for each buffer you want to cover, then use @code{nconc} to
4304 combine the returned values, like this:
4306 @example
4307 (nconc (prepare-change-group buffer-1)
4308        (prepare-change-group buffer-2))
4309 @end example
4311 You can then activate the multibuffer change group with a single call
4312 to @code{activate-change-group}, and finish it with a single call to
4313 @code{accept-change-group} or @code{cancel-change-group}.
4315   Nested use of several change groups for the same buffer works as you
4316 would expect.  Non-nested use of change groups for the same buffer
4317 will get Emacs confused, so don't let it happen; the first change
4318 group you start for any given buffer should be the last one finished.
4320 @node Change Hooks
4321 @section Change Hooks
4322 @cindex change hooks
4323 @cindex hooks for text changes
4325   These hook variables let you arrange to take notice of all changes in
4326 all buffers (or in a particular buffer, if you make them buffer-local).
4327 See also @ref{Special Properties}, for how to detect changes to specific
4328 parts of the text.
4330   The functions you use in these hooks should save and restore the match
4331 data if they do anything that uses regular expressions; otherwise, they
4332 will interfere in bizarre ways with the editing operations that call
4333 them.
4335 @defvar before-change-functions
4336 This variable holds a list of functions to call before any buffer
4337 modification.  Each function gets two arguments, the beginning and end
4338 of the region that is about to change, represented as integers.  The
4339 buffer that is about to change is always the current buffer.
4340 @end defvar
4342 @defvar after-change-functions
4343 This variable holds a list of functions to call after any buffer
4344 modification.  Each function receives three arguments: the beginning
4345 and end of the region just changed, and the length of the text that
4346 existed before the change.  All three arguments are integers.  The
4347 buffer has been changed is always the current buffer.
4349 The length of the old text is the difference between the buffer
4350 positions before and after that text as it was before the change.  As
4351 for the changed text, its length is simply the difference between the
4352 first two arguments.
4353 @end defvar
4355   Output of messages into the @file{*Messages*} buffer does not
4356 call these functions.
4358 @defmac combine-after-change-calls body@dots{}
4359 The macro executes @var{body} normally, but arranges to call the
4360 after-change functions just once for a series of several changes---if
4361 that seems safe.
4363 If a program makes several text changes in the same area of the buffer,
4364 using the macro @code{combine-after-change-calls} around that part of
4365 the program can make it run considerably faster when after-change hooks
4366 are in use.  When the after-change hooks are ultimately called, the
4367 arguments specify a portion of the buffer including all of the changes
4368 made within the @code{combine-after-change-calls} body.
4370 @strong{Warning:} You must not alter the values of
4371 @code{after-change-functions} within
4372 the body of a @code{combine-after-change-calls} form.
4374 @strong{Warning:} if the changes you combine occur in widely scattered
4375 parts of the buffer, this will still work, but it is not advisable,
4376 because it may lead to inefficient behavior for some change hook
4377 functions.
4378 @end defmac
4380 @defvar first-change-hook
4381 This variable is a normal hook that is run whenever a buffer is changed
4382 that was previously in the unmodified state.
4383 @end defvar
4385 @defvar inhibit-modification-hooks
4386 If this variable is non-@code{nil}, all of the change hooks are
4387 disabled; none of them run.  This affects all the hook variables
4388 described above in this section, as well as the hooks attached to
4389 certain special text properties (@pxref{Special Properties}) and overlay
4390 properties (@pxref{Overlay Properties}).
4392 Also, this variable is bound to non-@code{nil} while running those
4393 same hook variables, so that by default modifying the buffer from
4394 a modification hook does not cause other modification hooks to be run.
4395 If you do want modification hooks to be run in a particular piece of
4396 code that is itself run from a modification hook, then rebind locally
4397 @code{inhibit-modification-hooks} to @code{nil}.
4398 @end defvar