2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-2014 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
9 This chapter describes the functions that deal with the text in a
10 buffer. Most examine, insert, or delete text in the current buffer,
11 often operating at point or on text adjacent to point. Many are
12 interactive. All the functions that change the text provide for undoing
13 the changes (@pxref{Undo}).
15 Many text-related functions operate on a region of text defined by two
16 buffer positions passed in arguments named @var{start} and @var{end}.
17 These arguments should be either markers (@pxref{Markers}) or numeric
18 character positions (@pxref{Positions}). The order of these arguments
19 does not matter; it is all right for @var{start} to be the end of the
20 region and @var{end} the beginning. For example, @code{(delete-region 1
21 10)} and @code{(delete-region 10 1)} are equivalent. An
22 @code{args-out-of-range} error is signaled if either @var{start} or
23 @var{end} is outside the accessible portion of the buffer. In an
24 interactive call, point and the mark are used for these arguments.
26 @cindex buffer contents
27 Throughout this chapter, ``text'' refers to the characters in the
28 buffer, together with their properties (when relevant). Keep in mind
29 that point is always between two characters, and the cursor appears on
30 the character after point.
33 * Near Point:: Examining text in the vicinity of point.
34 * Buffer Contents:: Examining text in a general fashion.
35 * Comparing Text:: Comparing substrings of buffers.
36 * Insertion:: Adding new text to a buffer.
37 * Commands for Insertion:: User-level commands to insert text.
38 * Deletion:: Removing text from a buffer.
39 * User-Level Deletion:: User-level commands to delete text.
40 * The Kill Ring:: Where removed text sometimes is saved for later use.
41 * Undo:: Undoing changes to the text of a buffer.
42 * Maintaining Undo:: How to enable and disable undo information.
43 How to control how much information is kept.
44 * Filling:: Functions for explicit filling.
45 * Margins:: How to specify margins for filling commands.
46 * Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context.
47 * Auto Filling:: How auto-fill mode is implemented to break lines.
48 * Sorting:: Functions for sorting parts of the buffer.
49 * Columns:: Computing horizontal positions, and using them.
50 * Indentation:: Functions to insert or adjust indentation.
51 * Case Changes:: Case conversion of parts of the buffer.
52 * Text Properties:: Assigning Lisp property lists to text characters.
53 * Substitution:: Replacing a given character wherever it appears.
54 * Registers:: How registers are implemented. Accessing the text or
55 position stored in a register.
56 * Transposition:: Swapping two portions of a buffer.
57 * Decompression:: Dealing with compressed data.
58 * Base 64:: Conversion to or from base 64 encoding.
59 * Checksum/Hash:: Computing cryptographic hashes.
60 * Parsing HTML/XML:: Parsing HTML and XML.
61 * Atomic Changes:: Installing several buffer changes "atomically".
62 * Change Hooks:: Supplying functions to be run when text is changed.
66 @section Examining Text Near Point
67 @cindex text near point
69 Many functions are provided to look at the characters around point.
70 Several simple functions are described here. See also @code{looking-at}
71 in @ref{Regexp Search}.
73 In the following four functions, ``beginning'' or ``end'' of buffer
74 refers to the beginning or end of the accessible portion.
76 @defun char-after &optional position
77 This function returns the character in the current buffer at (i.e.,
78 immediately after) position @var{position}. If @var{position} is out of
79 range for this purpose, either before the beginning of the buffer, or at
80 or beyond the end, then the value is @code{nil}. The default for
81 @var{position} is point.
83 In the following example, assume that the first character in the
88 (string (char-after 1))
94 @defun char-before &optional position
95 This function returns the character in the current buffer immediately
96 before position @var{position}. If @var{position} is out of range for
97 this purpose, either at or before the beginning of the buffer, or beyond
98 the end, then the value is @code{nil}. The default for
99 @var{position} is point.
102 @defun following-char
103 This function returns the character following point in the current
104 buffer. This is similar to @code{(char-after (point))}. However, if
105 point is at the end of the buffer, then @code{following-char} returns 0.
107 Remember that point is always between characters, and the cursor
108 normally appears over the character following point. Therefore, the
109 character returned by @code{following-char} is the character the
112 In this example, point is between the @samp{a} and the @samp{c}.
116 ---------- Buffer: foo ----------
117 Gentlemen may cry ``Pea@point{}ce! Peace!,''
118 but there is no peace.
119 ---------- Buffer: foo ----------
123 (string (preceding-char))
125 (string (following-char))
131 @defun preceding-char
132 This function returns the character preceding point in the current
133 buffer. See above, under @code{following-char}, for an example. If
134 point is at the beginning of the buffer, @code{preceding-char} returns
139 This function returns @code{t} if point is at the beginning of the
140 buffer. If narrowing is in effect, this means the beginning of the
141 accessible portion of the text. See also @code{point-min} in
146 This function returns @code{t} if point is at the end of the buffer.
147 If narrowing is in effect, this means the end of accessible portion of
148 the text. See also @code{point-max} in @xref{Point}.
152 This function returns @code{t} if point is at the beginning of a line.
153 @xref{Text Lines}. The beginning of the buffer (or of its accessible
154 portion) always counts as the beginning of a line.
158 This function returns @code{t} if point is at the end of a line. The
159 end of the buffer (or of its accessible portion) is always considered
163 @node Buffer Contents
164 @section Examining Buffer Contents
165 @cindex buffer portion as string
167 This section describes functions that allow a Lisp program to
168 convert any portion of the text in the buffer into a string.
170 @defun buffer-substring start end
171 This function returns a string containing a copy of the text of the
172 region defined by positions @var{start} and @var{end} in the current
173 buffer. If the arguments are not positions in the accessible portion
174 of the buffer, @code{buffer-substring} signals an
175 @code{args-out-of-range} error.
177 Here's an example which assumes Font-Lock mode is not enabled:
181 ---------- Buffer: foo ----------
182 This is the contents of buffer foo
184 ---------- Buffer: foo ----------
188 (buffer-substring 1 10)
189 @result{} "This is t"
192 (buffer-substring (point-max) 10)
193 @result{} "he contents of buffer foo\n"
197 If the text being copied has any text properties, these are copied into
198 the string along with the characters they belong to. @xref{Text
199 Properties}. However, overlays (@pxref{Overlays}) in the buffer and
200 their properties are ignored, not copied.
202 For example, if Font-Lock mode is enabled, you might get results like
207 (buffer-substring 1 10)
208 @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t))
213 @defun buffer-substring-no-properties start end
214 This is like @code{buffer-substring}, except that it does not copy text
215 properties, just the characters themselves. @xref{Text Properties}.
219 This function returns the contents of the entire accessible portion of
220 the current buffer, as a string.
223 @defun filter-buffer-substring start end &optional delete
224 This function filters the buffer text between @var{start} and @var{end}
225 using a function specified by the variable
226 @code{filter-buffer-substring-function}, and returns the result.
228 The default filter function consults the obsolete wrapper hook
229 @code{filter-buffer-substring-functions}, and the obsolete variable
230 @code{buffer-substring-filters}. If both of these are @code{nil}, it
231 returns the unaltered text from the buffer, i.e., what
232 @code{buffer-substring} would return.
234 If @var{delete} is non-@code{nil}, the function deletes the text
235 between @var{start} and @var{end} after copying it, like
236 @code{delete-and-extract-region}.
238 Lisp code should use this function instead of @code{buffer-substring},
239 @code{buffer-substring-no-properties},
240 or @code{delete-and-extract-region} when copying into user-accessible
241 data structures such as the kill-ring, X clipboard, and registers.
242 Major and minor modes can modify @code{filter-buffer-substring-function}
243 to alter such text as it is copied out of the buffer.
246 @defvar filter-buffer-substring-function
247 The value of this variable is a function that @code{filter-buffer-substring}
248 will call to do the actual work. The function receives three
249 arguments, the same as those of @code{filter-buffer-substring},
250 which it should treat as per the documentation of that function. It
251 should return the filtered text (and optionally delete the source text).
254 @noindent The following two variables are obsoleted by
255 @code{filter-buffer-substring-function}, but are still supported for
256 backward compatibility.
258 @defvar filter-buffer-substring-functions
259 This obsolete variable is a wrapper hook, whose members should be functions
260 that accept four arguments: @var{fun}, @var{start}, @var{end}, and
261 @var{delete}. @var{fun} is a function that takes three arguments
262 (@var{start}, @var{end}, and @var{delete}), and returns a string. In
263 both cases, the @var{start}, @var{end}, and @var{delete} arguments are
264 the same as those of @code{filter-buffer-substring}.
266 The first hook function is passed a @var{fun} that is equivalent to
267 the default operation of @code{filter-buffer-substring}, i.e., it
268 returns the buffer-substring between @var{start} and @var{end}
269 (processed by any @code{buffer-substring-filters}) and optionally
270 deletes the original text from the buffer. In most cases, the hook
271 function will call @var{fun} once, and then do its own processing of
272 the result. The next hook function receives a @var{fun} equivalent to
273 this, and so on. The actual return value is the result of all the
274 hook functions acting in sequence.
277 @defvar buffer-substring-filters
278 The value of this obsolete variable should be a list of functions
279 that accept a single string argument and return another string.
280 The default @code{filter-buffer-substring} function passes the buffer
281 substring to the first function in this list, and the return value of
282 each function is passed to the next function. The return value of the
283 last function is passed to @code{filter-buffer-substring-functions}.
286 @defun current-word &optional strict really-word
287 This function returns the symbol (or word) at or near point, as a
288 string. The return value includes no text properties.
290 If the optional argument @var{really-word} is non-@code{nil}, it finds a
291 word; otherwise, it finds a symbol (which includes both word
292 characters and symbol constituent characters).
294 If the optional argument @var{strict} is non-@code{nil}, then point
295 must be in or next to the symbol or word---if no symbol or word is
296 there, the function returns @code{nil}. Otherwise, a nearby symbol or
297 word on the same line is acceptable.
300 @defun thing-at-point thing
301 Return the @var{thing} around or next to point, as a string.
303 The argument @var{thing} is a symbol which specifies a kind of syntactic
304 entity. Possibilities include @code{symbol}, @code{list}, @code{sexp},
305 @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
306 @code{whitespace}, @code{line}, @code{page}, and others.
309 ---------- Buffer: foo ----------
310 Gentlemen may cry ``Pea@point{}ce! Peace!,''
311 but there is no peace.
312 ---------- Buffer: foo ----------
314 (thing-at-point 'word)
316 (thing-at-point 'line)
317 @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
318 (thing-at-point 'whitespace)
324 @section Comparing Text
325 @cindex comparing buffer text
327 This function lets you compare portions of the text in a buffer, without
328 copying them into strings first.
330 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
331 This function lets you compare two substrings of the same buffer or two
332 different buffers. The first three arguments specify one substring,
333 giving a buffer (or a buffer name) and two positions within the
334 buffer. The last three arguments specify the other substring in the
335 same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or
336 both to stand for the current buffer.
338 The value is negative if the first substring is less, positive if the
339 first is greater, and zero if they are equal. The absolute value of
340 the result is one plus the index of the first differing characters
341 within the substrings.
343 This function ignores case when comparing characters
344 if @code{case-fold-search} is non-@code{nil}. It always ignores
347 Suppose you have the text @w{@samp{foobarbar haha!rara!}} in the
348 current buffer; then in this example the two substrings are @samp{rbar
349 } and @samp{rara!}. The value is 2 because the first substring is
350 greater at the second character.
353 (compare-buffer-substrings nil 6 11 nil 16 21)
359 @section Inserting Text
360 @cindex insertion of text
361 @cindex text insertion
363 @cindex insertion before point
364 @cindex before point, insertion
365 @dfn{Insertion} means adding new text to a buffer. The inserted text
366 goes at point---between the character before point and the character
367 after point. Some insertion functions leave point before the inserted
368 text, while other functions leave it after. We call the former
369 insertion @dfn{after point} and the latter insertion @dfn{before point}.
371 Insertion moves markers located at positions after the insertion
372 point, so that they stay with the surrounding text (@pxref{Markers}).
373 When a marker points at the place of insertion, insertion may or may
374 not relocate the marker, depending on the marker's insertion type
375 (@pxref{Marker Insertion Types}). Certain special functions such as
376 @code{insert-before-markers} relocate all such markers to point after
377 the inserted text, regardless of the markers' insertion type.
379 Insertion functions signal an error if the current buffer is
380 read-only (@pxref{Read Only Buffers}) or if they insert within
381 read-only text (@pxref{Special Properties}).
383 These functions copy text characters from strings and buffers along
384 with their properties. The inserted characters have exactly the same
385 properties as the characters they were copied from. By contrast,
386 characters specified as separate arguments, not part of a string or
387 buffer, inherit their text properties from the neighboring text.
389 The insertion functions convert text from unibyte to multibyte in
390 order to insert in a multibyte buffer, and vice versa---if the text
391 comes from a string or from a buffer. However, they do not convert
392 unibyte character codes 128 through 255 to multibyte characters, not
393 even if the current buffer is a multibyte buffer. @xref{Converting
396 @defun insert &rest args
397 This function inserts the strings and/or characters @var{args} into the
398 current buffer, at point, moving point forward. In other words, it
399 inserts the text before point. An error is signaled unless all
400 @var{args} are either strings or characters. The value is @code{nil}.
403 @defun insert-before-markers &rest args
404 This function inserts the strings and/or characters @var{args} into the
405 current buffer, at point, moving point forward. An error is signaled
406 unless all @var{args} are either strings or characters. The value is
409 This function is unlike the other insertion functions in that it
410 relocates markers initially pointing at the insertion point, to point
411 after the inserted text. If an overlay begins at the insertion point,
412 the inserted text falls outside the overlay; if a nonempty overlay
413 ends at the insertion point, the inserted text falls inside that
417 @deffn Command insert-char character &optional count inherit
418 This command inserts @var{count} instances of @var{character} into the
419 current buffer before point. The argument @var{count} must be an
420 integer, and @var{character} must be a character.
422 If called interactively, this command prompts for @var{character}
423 using its Unicode name or its code point. @xref{Inserting Text,,,
424 emacs, The GNU Emacs Manual}.
426 This function does not convert unibyte character codes 128 through 255
427 to multibyte characters, not even if the current buffer is a multibyte
428 buffer. @xref{Converting Representations}.
430 If @var{inherit} is non-@code{nil}, the inserted characters inherit
431 sticky text properties from the two characters before and after the
432 insertion point. @xref{Sticky Properties}.
435 @defun insert-buffer-substring from-buffer-or-name &optional start end
436 This function inserts a portion of buffer @var{from-buffer-or-name}
437 into the current buffer before point. The text inserted is the region
438 between @var{start} (inclusive) and @var{end} (exclusive). (These
439 arguments default to the beginning and end of the accessible portion
440 of that buffer.) This function returns @code{nil}.
442 In this example, the form is executed with buffer @samp{bar} as the
443 current buffer. We assume that buffer @samp{bar} is initially empty.
447 ---------- Buffer: foo ----------
448 We hold these truths to be self-evident, that all
449 ---------- Buffer: foo ----------
453 (insert-buffer-substring "foo" 1 20)
456 ---------- Buffer: bar ----------
457 We hold these truth@point{}
458 ---------- Buffer: bar ----------
463 @defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
464 This is like @code{insert-buffer-substring} except that it does not
465 copy any text properties.
468 @xref{Sticky Properties}, for other insertion functions that inherit
469 text properties from the nearby text in addition to inserting it.
470 Whitespace inserted by indentation functions also inherits text
473 @node Commands for Insertion
474 @section User-Level Insertion Commands
476 This section describes higher-level commands for inserting text,
477 commands intended primarily for the user but useful also in Lisp
480 @deffn Command insert-buffer from-buffer-or-name
481 This command inserts the entire accessible contents of
482 @var{from-buffer-or-name} (which must exist) into the current buffer
483 after point. It leaves the mark after the inserted text. The value
487 @deffn Command self-insert-command count
488 @cindex character insertion
489 @cindex self-insertion
490 This command inserts the last character typed; it does so @var{count}
491 times, before point, and returns @code{nil}. Most printing characters
492 are bound to this command. In routine use, @code{self-insert-command}
493 is the most frequently called function in Emacs, but programs rarely use
494 it except to install it on a keymap.
496 In an interactive call, @var{count} is the numeric prefix argument.
498 @c FIXME: This variable is obsolete since 23.1.
499 Self-insertion translates the input character through
500 @code{translation-table-for-input}. @xref{Translation of Characters}.
502 This command calls @code{auto-fill-function} whenever that is
503 non-@code{nil} and the character inserted is in the table
504 @code{auto-fill-chars} (@pxref{Auto Filling}).
506 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
507 This command performs abbrev expansion if Abbrev mode is enabled and
508 the inserted character does not have word-constituent
509 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also
510 responsible for calling @code{blink-paren-function} when the inserted
511 character has close parenthesis syntax (@pxref{Blinking}).
513 @vindex post-self-insert-hook
514 The final thing this command does is to run the hook
515 @code{post-self-insert-hook}. You could use this to automatically
516 reindent text as it is typed, for example.
518 Do not try substituting your own definition of
519 @code{self-insert-command} for the standard one. The editor command
520 loop handles this function specially.
523 @deffn Command newline &optional number-of-newlines
524 This command inserts newlines into the current buffer before point.
525 If @var{number-of-newlines} is supplied, that many newline characters
528 @cindex newline and Auto Fill mode
529 This function calls @code{auto-fill-function} if the current column
530 number is greater than the value of @code{fill-column} and
531 @var{number-of-newlines} is @code{nil}. Typically what
532 @code{auto-fill-function} does is insert a newline; thus, the overall
533 result in this case is to insert two newlines at different places: one
534 at point, and another earlier in the line. @code{newline} does not
535 auto-fill if @var{number-of-newlines} is non-@code{nil}.
537 This command indents to the left margin if that is not zero.
540 The value returned is @code{nil}. In an interactive call, @var{count}
541 is the numeric prefix argument.
544 @defvar overwrite-mode
545 This variable controls whether overwrite mode is in effect. The value
546 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
547 or @code{nil}. @code{overwrite-mode-textual} specifies textual
548 overwrite mode (treats newlines and tabs specially), and
549 @code{overwrite-mode-binary} specifies binary overwrite mode (treats
550 newlines and tabs like any other characters).
554 @section Deleting Text
555 @cindex text deletion
557 @cindex deleting text vs killing
558 Deletion means removing part of the text in a buffer, without saving
559 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
560 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
561 Some deletion functions do save text in the kill ring in some special
564 All of the deletion functions operate on the current buffer.
566 @deffn Command erase-buffer
567 This function deletes the entire text of the current buffer
568 (@emph{not} just the accessible portion), leaving it
569 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
570 error; if some of the text in it is read-only, it signals a
571 @code{text-read-only} error. Otherwise, it deletes the text without
572 asking for any confirmation. It returns @code{nil}.
574 Normally, deleting a large amount of text from a buffer inhibits further
575 auto-saving of that buffer ``because it has shrunk''. However,
576 @code{erase-buffer} does not do this, the idea being that the future
577 text is not really related to the former text, and its size should not
578 be compared with that of the former text.
581 @deffn Command delete-region start end
582 This command deletes the text between positions @var{start} and
583 @var{end} in the current buffer, and returns @code{nil}. If point was
584 inside the deleted region, its value afterward is @var{start}.
585 Otherwise, point relocates with the surrounding text, as markers do.
588 @defun delete-and-extract-region start end
589 This function deletes the text between positions @var{start} and
590 @var{end} in the current buffer, and returns a string containing the
593 If point was inside the deleted region, its value afterward is
594 @var{start}. Otherwise, point relocates with the surrounding text, as
598 @deffn Command delete-char count &optional killp
599 This command deletes @var{count} characters directly after point, or
600 before point if @var{count} is negative. If @var{killp} is
601 non-@code{nil}, then it saves the deleted characters in the kill ring.
603 In an interactive call, @var{count} is the numeric prefix argument, and
604 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
605 argument is supplied, the text is saved in the kill ring. If no prefix
606 argument is supplied, then one character is deleted, but not saved in
609 The value returned is always @code{nil}.
612 @deffn Command delete-backward-char count &optional killp
613 @cindex deleting previous char
614 This command deletes @var{count} characters directly before point, or
615 after point if @var{count} is negative. If @var{killp} is
616 non-@code{nil}, then it saves the deleted characters in the kill ring.
618 In an interactive call, @var{count} is the numeric prefix argument, and
619 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
620 argument is supplied, the text is saved in the kill ring. If no prefix
621 argument is supplied, then one character is deleted, but not saved in
624 The value returned is always @code{nil}.
627 @deffn Command backward-delete-char-untabify count &optional killp
629 This command deletes @var{count} characters backward, changing tabs
630 into spaces. When the next character to be deleted is a tab, it is
631 first replaced with the proper number of spaces to preserve alignment
632 and then one of those spaces is deleted instead of the tab. If
633 @var{killp} is non-@code{nil}, then the command saves the deleted
634 characters in the kill ring.
636 Conversion of tabs to spaces happens only if @var{count} is positive.
637 If it is negative, exactly @minus{}@var{count} characters after point
640 In an interactive call, @var{count} is the numeric prefix argument, and
641 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
642 argument is supplied, the text is saved in the kill ring. If no prefix
643 argument is supplied, then one character is deleted, but not saved in
646 The value returned is always @code{nil}.
649 @defopt backward-delete-char-untabify-method
650 This option specifies how @code{backward-delete-char-untabify} should
651 deal with whitespace. Possible values include @code{untabify}, the
652 default, meaning convert a tab to many spaces and delete one;
653 @code{hungry}, meaning delete all tabs and spaces before point with
654 one command; @code{all} meaning delete all tabs, spaces and newlines
655 before point, and @code{nil}, meaning do nothing special for
656 whitespace characters.
659 @node User-Level Deletion
660 @section User-Level Deletion Commands
662 This section describes higher-level commands for deleting text,
663 commands intended primarily for the user but useful also in Lisp
666 @deffn Command delete-horizontal-space &optional backward-only
667 @cindex deleting whitespace
668 This function deletes all spaces and tabs around point. It returns
671 If @var{backward-only} is non-@code{nil}, the function deletes
672 spaces and tabs before point, but not after point.
674 In the following examples, we call @code{delete-horizontal-space} four
675 times, once on each line, with point between the second and third
676 characters on the line each time.
680 ---------- Buffer: foo ----------
685 ---------- Buffer: foo ----------
689 (delete-horizontal-space) ; @r{Four times.}
692 ---------- Buffer: foo ----------
697 ---------- Buffer: foo ----------
702 @deffn Command delete-indentation &optional join-following-p
703 This function joins the line point is on to the previous line, deleting
704 any whitespace at the join and in some cases replacing it with one
705 space. If @var{join-following-p} is non-@code{nil},
706 @code{delete-indentation} joins this line to the following line
707 instead. The function returns @code{nil}.
709 If there is a fill prefix, and the second of the lines being joined
710 starts with the prefix, then @code{delete-indentation} deletes the
711 fill prefix before joining the lines. @xref{Margins}.
713 In the example below, point is located on the line starting
714 @samp{events}, and it makes no difference if there are trailing spaces
715 in the preceding line.
719 ---------- Buffer: foo ----------
720 When in the course of human
721 @point{} events, it becomes necessary
722 ---------- Buffer: foo ----------
729 ---------- Buffer: foo ----------
730 When in the course of human@point{} events, it becomes necessary
731 ---------- Buffer: foo ----------
735 After the lines are joined, the function @code{fixup-whitespace} is
736 responsible for deciding whether to leave a space at the junction.
739 @deffn Command fixup-whitespace
740 This function replaces all the horizontal whitespace surrounding point
741 with either one space or no space, according to the context. It
744 At the beginning or end of a line, the appropriate amount of space is
745 none. Before a character with close parenthesis syntax, or after a
746 character with open parenthesis or expression-prefix syntax, no space is
747 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
750 In the example below, @code{fixup-whitespace} is called the first time
751 with point before the word @samp{spaces} in the first line. For the
752 second invocation, point is directly after the @samp{(}.
756 ---------- Buffer: foo ----------
757 This has too many @point{}spaces
758 This has too many spaces at the start of (@point{} this list)
759 ---------- Buffer: foo ----------
770 ---------- Buffer: foo ----------
771 This has too many spaces
772 This has too many spaces at the start of (this list)
773 ---------- Buffer: foo ----------
778 @deffn Command just-one-space &optional n
779 @comment !!SourceFile simple.el
780 This command replaces any spaces and tabs around point with a single
781 space, or @var{n} spaces if @var{n} is specified. It returns
785 @c There is also cycle-spacing, but I cannot see it being useful in
786 @c Lisp programs, so it is not mentioned here.
788 @deffn Command delete-blank-lines
789 This function deletes blank lines surrounding point. If point is on a
790 blank line with one or more blank lines before or after it, then all but
791 one of them are deleted. If point is on an isolated blank line, then it
792 is deleted. If point is on a nonblank line, the command deletes all
793 blank lines immediately following it.
795 A blank line is defined as a line containing only tabs and spaces.
796 @c and the Newline character?
798 @code{delete-blank-lines} returns @code{nil}.
801 @deffn Command delete-trailing-whitespace start end
802 Delete trailing whitespace in the region defined by @var{start} and
805 This command deletes whitespace characters after the last
806 non-whitespace character in each line in the region.
808 If this command acts on the entire buffer (i.e. if called
809 interactively with the mark inactive, or called from Lisp with
810 @var{end} @code{nil}), it also deletes all trailing lines at the end of the
811 buffer if the variable @code{delete-trailing-lines} is non-@code{nil}.
815 @section The Kill Ring
818 @dfn{Kill functions} delete text like the deletion functions, but save
819 it so that the user can reinsert it by @dfn{yanking}. Most of these
820 functions have @samp{kill-} in their name. By contrast, the functions
821 whose names start with @samp{delete-} normally do not save text for
822 yanking (though they can still be undone); these are ``deletion''
825 Most of the kill commands are primarily for interactive use, and are
826 not described here. What we do describe are the functions provided for
827 use in writing such commands. You can use these functions to write
828 commands for killing text. When you need to delete text for internal
829 purposes within a Lisp function, you should normally use deletion
830 functions, so as not to disturb the kill ring contents.
833 Killed text is saved for later yanking in the @dfn{kill ring}. This
834 is a list that holds a number of recent kills, not just the last text
835 kill. We call this a ``ring'' because yanking treats it as having
836 elements in a cyclic order. The list is kept in the variable
837 @code{kill-ring}, and can be operated on with the usual functions for
838 lists; there are also specialized functions, described in this section,
839 that treat it as a ring.
841 Some people think this use of the word ``kill'' is unfortunate, since
842 it refers to operations that specifically @emph{do not} destroy the
843 entities ``killed''. This is in sharp contrast to ordinary life, in
844 which death is permanent and ``killed'' entities do not come back to
845 life. Therefore, other metaphors have been proposed. For example, the
846 term ``cut ring'' makes sense to people who, in pre-computer days, used
847 scissors and paste to cut up and rearrange manuscripts. However, it
848 would be difficult to change the terminology now.
851 * Kill Ring Concepts:: What text looks like in the kill ring.
852 * Kill Functions:: Functions that kill text.
853 * Yanking:: How yanking is done.
854 * Yank Commands:: Commands that access the kill ring.
855 * Low-Level Kill Ring:: Functions and variables for kill ring access.
856 * Internals of Kill Ring:: Variables that hold kill ring data.
859 @node Kill Ring Concepts
860 @subsection Kill Ring Concepts
862 The kill ring records killed text as strings in a list, most recent
863 first. A short kill ring, for example, might look like this:
866 ("some text" "a different piece of text" "even older text")
870 When the list reaches @code{kill-ring-max} entries in length, adding a
871 new entry automatically deletes the last entry.
873 When kill commands are interwoven with other commands, each kill
874 command makes a new entry in the kill ring. Multiple kill commands in
875 succession build up a single kill ring entry, which would be yanked as a
876 unit; the second and subsequent consecutive kill commands add text to
877 the entry made by the first one.
879 For yanking, one entry in the kill ring is designated the ``front'' of
880 the ring. Some yank commands ``rotate'' the ring by designating a
881 different element as the ``front''. But this virtual rotation doesn't
882 change the list itself---the most recent entry always comes first in the
886 @subsection Functions for Killing
888 @code{kill-region} is the usual subroutine for killing text. Any
889 command that calls this function is a ``kill command'' (and should
890 probably have @samp{kill} in its name). @code{kill-region} puts the
891 newly killed text in a new element at the beginning of the kill ring or
892 adds it to the most recent element. It determines automatically (using
893 @code{last-command}) whether the previous command was a kill command,
894 and if so appends the killed text to the most recent entry.
896 @deffn Command kill-region start end
897 This function kills the text in the region defined by @var{start} and
898 @var{end}. The text is deleted but saved in the kill ring, along with
899 its text properties. The value is always @code{nil}.
901 In an interactive call, @var{start} and @var{end} are point and
904 If the buffer or text is read-only, @code{kill-region} modifies the kill
905 ring just the same, then signals an error without modifying the buffer.
906 This is convenient because it lets the user use a series of kill
907 commands to copy text from a read-only buffer into the kill ring.
910 @defopt kill-read-only-ok
911 If this option is non-@code{nil}, @code{kill-region} does not signal an
912 error if the buffer or text is read-only. Instead, it simply returns,
913 updating the kill ring but not changing the buffer.
916 @deffn Command copy-region-as-kill start end
917 This command saves the region defined by @var{start} and @var{end} on
918 the kill ring (including text properties), but does not delete the text
919 from the buffer. It returns @code{nil}.
921 The command does not set @code{this-command} to @code{kill-region}, so a
922 subsequent kill command does not append to the same kill ring entry.
924 @c FIXME Why is it better? Why isn't copy-region-as-kill obsolete then?
925 @c Why is it used in many places in Emacs?
926 In Lisp programs, it is better to use @code{kill-new} or
927 @code{kill-append} instead of this command. @xref{Low-Level Kill Ring}.
933 Yanking means inserting text from the kill ring, but it does not
934 insert the text blindly. The @code{yank} command, and related
935 commands, use @code{insert-for-yank} to perform special processing on
936 the text before it is inserted.
938 @defun insert-for-yank string
939 This function works like @code{insert}, except that it processes the
940 text in @var{string} according to the @code{yank-handler} text
941 property, as well as the variables @code{yank-handled-properties} and
942 @code{yank-excluded-properties} (see below), before inserting the
943 result into the current buffer.
946 @defun insert-buffer-substring-as-yank buf &optional start end
947 This function resembles @code{insert-buffer-substring}, except that it
948 processes the text according to @code{yank-handled-properties} and
949 @code{yank-excluded-properties}. (It does not handle the
950 @code{yank-handler} property, which does not normally occur in buffer
954 @c FIXME: Add an index for yank-handler.
955 If you put a @code{yank-handler} text property on all or part of a
956 string, that alters how @code{insert-for-yank} inserts the string. If
957 different parts of the string have different @code{yank-handler}
958 values (comparison being done with @code{eq}), each substring is
959 handled separately. The property value must be a list of one to four
960 elements, with the following format (where elements after the first
964 (@var{function} @var{param} @var{noexclude} @var{undo})
967 Here is what the elements do:
971 When @var{function} is non-@code{nil}, it is called instead of
972 @code{insert} to insert the string, with one argument---the string to
976 If @var{param} is present and non-@code{nil}, it replaces @var{string}
977 (or the substring of @var{string} being processed) as the object
978 passed to @var{function} (or @code{insert}). For example, if
979 @var{function} is @code{yank-rectangle}, @var{param} should be a list
980 of strings to insert as a rectangle.
983 If @var{noexclude} is present and non-@code{nil}, that disables the
984 normal action of @code{yank-handled-properties} and
985 @code{yank-excluded-properties} on the inserted string.
988 If @var{undo} is present and non-@code{nil}, it is a function that will be
989 called by @code{yank-pop} to undo the insertion of the current object.
990 It is called with two arguments, the start and end of the current
991 region. @var{function} can set @code{yank-undo-function} to override
992 the @var{undo} value.
995 @cindex yanking and text properties
996 @defopt yank-handled-properties
997 This variable specifies special text property handling conditions for
998 yanked text. It takes effect after the text has been inserted (either
999 normally, or via the @code{yank-handler} property), and prior to
1000 @code{yank-excluded-properties} taking effect.
1002 The value should be an alist of elements @code{(@var{prop}
1003 . @var{fun})}. Each alist element is handled in order. The inserted
1004 text is scanned for stretches of text having text properties @code{eq}
1005 to @var{prop}; for each such stretch, @var{fun} is called with three
1006 arguments: the value of the property, and the start and end positions
1010 @defopt yank-excluded-properties
1011 The value of this variable is the list of properties to remove from
1012 inserted text. Its default value contains properties that might lead
1013 to annoying results, such as causing the text to respond to the mouse
1014 or specifying key bindings. It takes effect after
1015 @code{yank-handled-properties}.
1020 @subsection Functions for Yanking
1022 This section describes higher-level commands for yanking, which are
1023 intended primarily for the user but useful also in Lisp programs.
1024 Both @code{yank} and @code{yank-pop} honor the
1025 @code{yank-excluded-properties} variable and @code{yank-handler} text
1026 property (@pxref{Yanking}).
1028 @deffn Command yank &optional arg
1029 @cindex inserting killed text
1030 This command inserts before point the text at the front of the kill
1031 ring. It sets the mark at the beginning of that text, using
1032 @code{push-mark} (@pxref{The Mark}), and puts point at the end.
1034 If @var{arg} is a non-@code{nil} list (which occurs interactively when
1035 the user types @kbd{C-u} with no digits), then @code{yank} inserts the
1036 text as described above, but puts point before the yanked text and
1037 sets the mark after it.
1039 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th
1040 most recently killed text---the @var{arg}th element of the kill ring
1041 list, counted cyclically from the front, which is considered the
1042 first element for this purpose.
1044 @code{yank} does not alter the contents of the kill ring, unless it
1045 used text provided by another program, in which case it pushes that text
1046 onto the kill ring. However if @var{arg} is an integer different from
1047 one, it rotates the kill ring to place the yanked string at the front.
1049 @code{yank} returns @code{nil}.
1052 @deffn Command yank-pop &optional arg
1053 This command replaces the just-yanked entry from the kill ring with a
1054 different entry from the kill ring.
1056 This is allowed only immediately after a @code{yank} or another
1057 @code{yank-pop}. At such a time, the region contains text that was just
1058 inserted by yanking. @code{yank-pop} deletes that text and inserts in
1059 its place a different piece of killed text. It does not add the deleted
1060 text to the kill ring, since it is already in the kill ring somewhere.
1061 It does however rotate the kill ring to place the newly yanked string at
1064 If @var{arg} is @code{nil}, then the replacement text is the previous
1065 element of the kill ring. If @var{arg} is numeric, the replacement is
1066 the @var{arg}th previous kill. If @var{arg} is negative, a more recent
1067 kill is the replacement.
1069 The sequence of kills in the kill ring wraps around, so that after the
1070 oldest one comes the newest one, and before the newest one goes the
1073 The return value is always @code{nil}.
1076 @defvar yank-undo-function
1077 If this variable is non-@code{nil}, the function @code{yank-pop} uses
1078 its value instead of @code{delete-region} to delete the text
1079 inserted by the previous @code{yank} or
1080 @code{yank-pop} command. The value must be a function of two
1081 arguments, the start and end of the current region.
1083 The function @code{insert-for-yank} automatically sets this variable
1084 according to the @var{undo} element of the @code{yank-handler}
1085 text property, if there is one.
1088 @node Low-Level Kill Ring
1089 @subsection Low-Level Kill Ring
1091 These functions and variables provide access to the kill ring at a
1092 lower level, but are still convenient for use in Lisp programs,
1093 because they take care of interaction with window system selections
1094 (@pxref{Window System Selections}).
1096 @defun current-kill n &optional do-not-move
1097 The function @code{current-kill} rotates the yanking pointer, which
1098 designates the ``front'' of the kill ring, by @var{n} places (from newer
1099 kills to older ones), and returns the text at that place in the ring.
1101 If the optional second argument @var{do-not-move} is non-@code{nil},
1102 then @code{current-kill} doesn't alter the yanking pointer; it just
1103 returns the @var{n}th kill, counting from the current yanking pointer.
1105 If @var{n} is zero, indicating a request for the latest kill,
1106 @code{current-kill} calls the value of
1107 @code{interprogram-paste-function} (documented below) before
1108 consulting the kill ring. If that value is a function and calling it
1109 returns a string or a list of several string, @code{current-kill}
1110 pushes the strings onto the kill ring and returns the first string.
1111 It also sets the yanking pointer to point to the kill-ring entry of
1112 the first string returned by @code{interprogram-paste-function},
1113 regardless of the value of @var{do-not-move}. Otherwise,
1114 @code{current-kill} does not treat a zero value for @var{n} specially:
1115 it returns the entry pointed at by the yanking pointer and does not
1116 move the yanking pointer.
1119 @defun kill-new string &optional replace
1120 This function pushes the text @var{string} onto the kill ring and
1121 makes the yanking pointer point to it. It discards the oldest entry
1122 if appropriate. It also invokes the value of
1123 @code{interprogram-cut-function} (see below).
1125 If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the
1126 first element of the kill ring with @var{string}, rather than pushing
1127 @var{string} onto the kill ring.
1130 @defun kill-append string before-p
1131 This function appends the text @var{string} to the first entry in the
1132 kill ring and makes the yanking pointer point to the combined entry.
1133 Normally @var{string} goes at the end of the entry, but if
1134 @var{before-p} is non-@code{nil}, it goes at the beginning. This
1135 function also invokes the value of @code{interprogram-cut-function}
1139 @defvar interprogram-paste-function
1140 This variable provides a way of transferring killed text from other
1141 programs, when you are using a window system. Its value should be
1142 @code{nil} or a function of no arguments.
1144 If the value is a function, @code{current-kill} calls it to get the
1145 ``most recent kill''. If the function returns a non-@code{nil} value,
1146 then that value is used as the ``most recent kill''. If it returns
1147 @code{nil}, then the front of the kill ring is used.
1149 To facilitate support for window systems that support multiple
1150 selections, this function may also return a list of strings. In that
1151 case, the first string is used as the ``most recent kill'', and all
1152 the other strings are pushed onto the kill ring, for easy access by
1155 The normal use of this function is to get the window system's
1156 clipboard as the most recent kill, even if the selection belongs to
1157 another application. @xref{Window System Selections}. However, if
1158 the clipboard contents come from the current Emacs session, this
1159 function should return @code{nil}.
1162 @defvar interprogram-cut-function
1163 This variable provides a way of communicating killed text to other
1164 programs, when you are using a window system. Its value should be
1165 @code{nil} or a function of one required argument.
1167 If the value is a function, @code{kill-new} and @code{kill-append} call
1168 it with the new first element of the kill ring as the argument.
1170 The normal use of this function is to put newly killed text in the
1171 window system's clipboard. @xref{Window System Selections}.
1174 @node Internals of Kill Ring
1175 @subsection Internals of the Kill Ring
1177 The variable @code{kill-ring} holds the kill ring contents, in the
1178 form of a list of strings. The most recent kill is always at the front
1181 The @code{kill-ring-yank-pointer} variable points to a link in the
1182 kill ring list, whose @sc{car} is the text to yank next. We say it
1183 identifies the ``front'' of the ring. Moving
1184 @code{kill-ring-yank-pointer} to a different link is called
1185 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
1186 the functions that move the yank pointer wrap around from the end of the
1187 list to the beginning, or vice-versa. Rotation of the kill ring is
1188 virtual; it does not change the value of @code{kill-ring}.
1190 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
1191 variables whose values are normally lists. The word ``pointer'' in the
1192 name of the @code{kill-ring-yank-pointer} indicates that the variable's
1193 purpose is to identify one element of the list for use by the next yank
1196 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
1197 of the links in the kill ring list. The element it identifies is the
1198 @sc{car} of that link. Kill commands, which change the kill ring, also
1199 set this variable to the value of @code{kill-ring}. The effect is to
1200 rotate the ring so that the newly killed text is at the front.
1202 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
1203 pointing to the second entry in the kill ring @code{("some text" "a
1204 different piece of text" "yet older text")}.
1208 kill-ring ---- kill-ring-yank-pointer
1211 | --- --- --- --- --- ---
1212 --> | | |------> | | |--> | | |--> nil
1213 --- --- --- --- --- ---
1216 | | -->"yet older text"
1218 | --> "a different piece of text"
1225 This state of affairs might occur after @kbd{C-y} (@code{yank})
1226 immediately followed by @kbd{M-y} (@code{yank-pop}).
1229 This variable holds the list of killed text sequences, most recently
1233 @defvar kill-ring-yank-pointer
1234 This variable's value indicates which element of the kill ring is at the
1235 ``front'' of the ring for yanking. More precisely, the value is a tail
1236 of the value of @code{kill-ring}, and its @sc{car} is the kill string
1237 that @kbd{C-y} should yank.
1240 @defopt kill-ring-max
1241 The value of this variable is the maximum length to which the kill
1242 ring can grow, before elements are thrown away at the end. The default
1243 value for @code{kill-ring-max} is 60.
1250 Most buffers have an @dfn{undo list}, which records all changes made
1251 to the buffer's text so that they can be undone. (The buffers that
1252 don't have one are usually special-purpose buffers for which Emacs
1253 assumes that undoing is not useful. In particular, any buffer whose
1254 name begins with a space has its undo recording off by default;
1255 see @ref{Buffer Names}.) All the primitives that modify the
1256 text in the buffer automatically add elements to the front of the undo
1257 list, which is in the variable @code{buffer-undo-list}.
1259 @defvar buffer-undo-list
1260 This buffer-local variable's value is the undo list of the current
1261 buffer. A value of @code{t} disables the recording of undo information.
1264 Here are the kinds of elements an undo list can have:
1267 @item @var{position}
1268 This kind of element records a previous value of point; undoing this
1269 element moves point to @var{position}. Ordinary cursor motion does not
1270 make any sort of undo record, but deletion operations use these entries
1271 to record where point was before the command.
1273 @item (@var{beg} . @var{end})
1274 This kind of element indicates how to delete text that was inserted.
1275 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
1278 @item (@var{text} . @var{position})
1279 This kind of element indicates how to reinsert text that was deleted.
1280 The deleted text itself is the string @var{text}. The place to
1281 reinsert it is @code{(abs @var{position})}. If @var{position} is
1282 positive, point was at the beginning of the deleted text, otherwise it
1283 was at the end. Zero or more (@var{marker} . @var{adjustment})
1284 elements follow immediately after this element.
1286 @item (t . @var{time-flag})
1287 This kind of element indicates that an unmodified buffer became
1288 modified. A @var{time-flag} of the form
1289 @code{(@var{sec-high} @var{sec-low} @var{microsec}
1290 @var{picosec})} represents the visited file's modification time as of
1291 when it was previously visited or saved, using the same format as
1292 @code{current-time}; see @ref{Time of Day}.
1293 A @var{time-flag} of 0 means the buffer does not correspond to any file;
1294 @minus{}1 means the visited file previously did not exist.
1295 @code{primitive-undo} uses these
1296 values to determine whether to mark the buffer as unmodified once again;
1297 it does so only if the file's status matches that of @var{time-flag}.
1299 @item (nil @var{property} @var{value} @var{beg} . @var{end})
1300 This kind of element records a change in a text property.
1301 Here's how you might undo the change:
1304 (put-text-property @var{beg} @var{end} @var{property} @var{value})
1307 @item (@var{marker} . @var{adjustment})
1308 This kind of element records the fact that the marker @var{marker} was
1309 relocated due to deletion of surrounding text, and that it moved
1310 @var{adjustment} character positions. If the marker's location is
1311 consistent with the (@var{text} . @var{position}) element preceding it
1312 in the undo list, then undoing this element moves @var{marker}
1313 @minus{} @var{adjustment} characters.
1315 @item (apply @var{funname} . @var{args})
1316 This is an extensible undo item, which is undone by calling
1317 @var{funname} with arguments @var{args}.
1319 @item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
1320 This is an extensible undo item, which records a change limited to the
1321 range @var{beg} to @var{end}, which increased the size of the buffer
1322 by @var{delta} characters. It is undone by calling @var{funname} with
1323 arguments @var{args}.
1325 This kind of element enables undo limited to a region to determine
1326 whether the element pertains to that region.
1329 This element is a boundary. The elements between two boundaries are
1330 called a @dfn{change group}; normally, each change group corresponds to
1331 one keyboard command, and undo commands normally undo an entire group as
1335 @defun undo-boundary
1336 This function places a boundary element in the undo list. The undo
1337 command stops at such a boundary, and successive undo commands undo
1338 to earlier and earlier boundaries. This function returns @code{nil}.
1340 The editor command loop automatically calls @code{undo-boundary} just
1341 before executing each key sequence, so that each undo normally undoes
1342 the effects of one command. As an exception, the command
1343 @code{self-insert-command}, which produces self-inserting input
1344 characters (@pxref{Commands for Insertion}), may remove the boundary
1345 inserted by the command loop: a boundary is accepted for the first
1346 such character, the next 19 consecutive self-inserting input
1347 characters do not have boundaries, and then the 20th does; and so on
1348 as long as the self-inserting characters continue. Hence, sequences
1349 of consecutive character insertions can be undone as a group.
1351 All buffer modifications add a boundary whenever the previous undoable
1352 change was made in some other buffer. This is to ensure that
1353 each command makes a boundary in each buffer where it makes changes.
1355 Calling this function explicitly is useful for splitting the effects of
1356 a command into more than one unit. For example, @code{query-replace}
1357 calls @code{undo-boundary} after each replacement, so that the user can
1358 undo individual replacements one by one.
1361 @defvar undo-in-progress
1362 This variable is normally @code{nil}, but the undo commands bind it to
1363 @code{t}. This is so that various kinds of change hooks can tell when
1364 they're being called for the sake of undoing.
1367 @defun primitive-undo count list
1368 This is the basic function for undoing elements of an undo list.
1369 It undoes the first @var{count} elements of @var{list}, returning
1370 the rest of @var{list}.
1372 @code{primitive-undo} adds elements to the buffer's undo list when it
1373 changes the buffer. Undo commands avoid confusion by saving the undo
1374 list value at the beginning of a sequence of undo operations. Then the
1375 undo operations use and update the saved value. The new elements added
1376 by undoing are not part of this saved value, so they don't interfere with
1379 This function does not bind @code{undo-in-progress}.
1382 @node Maintaining Undo
1383 @section Maintaining Undo Lists
1385 This section describes how to enable and disable undo information for
1386 a given buffer. It also explains how the undo list is truncated
1387 automatically so it doesn't get too big.
1389 Recording of undo information in a newly created buffer is normally
1390 enabled to start with; but if the buffer name starts with a space, the
1391 undo recording is initially disabled. You can explicitly enable or
1392 disable undo recording with the following two functions, or by setting
1393 @code{buffer-undo-list} yourself.
1395 @deffn Command buffer-enable-undo &optional buffer-or-name
1396 This command enables recording undo information for buffer
1397 @var{buffer-or-name}, so that subsequent changes can be undone. If no
1398 argument is supplied, then the current buffer is used. This function
1399 does nothing if undo recording is already enabled in the buffer. It
1402 In an interactive call, @var{buffer-or-name} is the current buffer.
1403 You cannot specify any other buffer.
1406 @deffn Command buffer-disable-undo &optional buffer-or-name
1407 @cindex disabling undo
1408 This function discards the undo list of @var{buffer-or-name}, and disables
1409 further recording of undo information. As a result, it is no longer
1410 possible to undo either previous changes or any subsequent changes. If
1411 the undo list of @var{buffer-or-name} is already disabled, this function
1414 In an interactive call, BUFFER-OR-NAME is the current buffer. You
1415 cannot specify any other buffer. This function returns @code{nil}.
1418 As editing continues, undo lists get longer and longer. To prevent
1419 them from using up all available memory space, garbage collection trims
1420 them back to size limits you can set. (For this purpose, the ``size''
1421 of an undo list measures the cons cells that make up the list, plus the
1422 strings of deleted text.) Three variables control the range of acceptable
1423 sizes: @code{undo-limit}, @code{undo-strong-limit} and
1424 @code{undo-outer-limit}. In these variables, size is counted as the
1425 number of bytes occupied, which includes both saved text and other
1429 This is the soft limit for the acceptable size of an undo list. The
1430 change group at which this size is exceeded is the last one kept.
1433 @defopt undo-strong-limit
1434 This is the upper limit for the acceptable size of an undo list. The
1435 change group at which this size is exceeded is discarded itself (along
1436 with all older change groups). There is one exception: the very latest
1437 change group is only discarded if it exceeds @code{undo-outer-limit}.
1440 @defopt undo-outer-limit
1441 If at garbage collection time the undo info for the current command
1442 exceeds this limit, Emacs discards the info and displays a warning.
1443 This is a last ditch limit to prevent memory overflow.
1446 @defopt undo-ask-before-discard
1447 If this variable is non-@code{nil}, when the undo info exceeds
1448 @code{undo-outer-limit}, Emacs asks in the echo area whether to
1449 discard the info. The default value is @code{nil}, which means to
1450 discard it automatically.
1452 This option is mainly intended for debugging. Garbage collection is
1453 inhibited while the question is asked, which means that Emacs might
1454 leak memory if the user waits too long before answering the question.
1459 @cindex filling text
1461 @dfn{Filling} means adjusting the lengths of lines (by moving the line
1462 breaks) so that they are nearly (but no greater than) a specified
1463 maximum width. Additionally, lines can be @dfn{justified}, which means
1464 inserting spaces to make the left and/or right margins line up
1465 precisely. The width is controlled by the variable @code{fill-column}.
1466 For ease of reading, lines should be no longer than 70 or so columns.
1468 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1469 automatically as you insert it, but changes to existing text may leave
1470 it improperly filled. Then you must fill the text explicitly.
1472 Most of the commands in this section return values that are not
1473 meaningful. All the functions that do filling take note of the current
1474 left margin, current right margin, and current justification style
1475 (@pxref{Margins}). If the current justification style is
1476 @code{none}, the filling functions don't actually do anything.
1478 Several of the filling functions have an argument @var{justify}.
1479 If it is non-@code{nil}, that requests some kind of justification. It
1480 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
1481 request a specific style of justification. If it is @code{t}, that
1482 means to use the current justification style for this part of the text
1483 (see @code{current-justification}, below). Any other value is treated
1486 When you call the filling functions interactively, using a prefix
1487 argument implies the value @code{full} for @var{justify}.
1489 @deffn Command fill-paragraph &optional justify region
1490 This command fills the paragraph at or after point. If
1491 @var{justify} is non-@code{nil}, each line is justified as well.
1492 It uses the ordinary paragraph motion commands to find paragraph
1493 boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
1495 When @var{region} is non-@code{nil}, then if Transient Mark mode is
1496 enabled and the mark is active, this command calls @code{fill-region}
1497 to fill all the paragraphs in the region, instead of filling only the
1498 current paragraph. When this command is called interactively,
1499 @var{region} is @code{t}.
1502 @deffn Command fill-region start end &optional justify nosqueeze to-eop
1503 This command fills each of the paragraphs in the region from @var{start}
1504 to @var{end}. It justifies as well if @var{justify} is
1507 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1508 other than line breaks untouched. If @var{to-eop} is non-@code{nil},
1509 that means to keep filling to the end of the paragraph---or the next hard
1510 newline, if @code{use-hard-newlines} is enabled (see below).
1512 The variable @code{paragraph-separate} controls how to distinguish
1513 paragraphs. @xref{Standard Regexps}.
1516 @deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
1517 This command fills each paragraph in the region according to its
1518 individual fill prefix. Thus, if the lines of a paragraph were indented
1519 with spaces, the filled paragraph will remain indented in the same
1522 The first two arguments, @var{start} and @var{end}, are the beginning
1523 and end of the region to be filled. The third and fourth arguments,
1524 @var{justify} and @var{citation-regexp}, are optional. If
1525 @var{justify} is non-@code{nil}, the paragraphs are justified as
1526 well as filled. If @var{citation-regexp} is non-@code{nil}, it means the
1527 function is operating on a mail message and therefore should not fill
1528 the header lines. If @var{citation-regexp} is a string, it is used as
1529 a regular expression; if it matches the beginning of a line, that line
1530 is treated as a citation marker.
1532 @c FIXME: "That mode" is confusing. It isn't a major/minor mode.
1533 Ordinarily, @code{fill-individual-paragraphs} regards each change in
1534 indentation as starting a new paragraph. If
1535 @code{fill-individual-varying-indent} is non-@code{nil}, then only
1536 separator lines separate paragraphs. That mode can handle indented
1537 paragraphs with additional indentation on the first line.
1540 @defopt fill-individual-varying-indent
1541 This variable alters the action of @code{fill-individual-paragraphs} as
1545 @deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
1546 This command considers a region of text as a single paragraph and fills
1547 it. If the region was made up of many paragraphs, the blank lines
1548 between paragraphs are removed. This function justifies as well as
1549 filling when @var{justify} is non-@code{nil}.
1551 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1552 other than line breaks untouched. If @var{squeeze-after} is
1553 non-@code{nil}, it specifies a position in the region, and means don't
1554 canonicalize spaces before that position.
1556 In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
1557 choose a fill prefix by default. @xref{Adaptive Fill}.
1560 @deffn Command justify-current-line &optional how eop nosqueeze
1561 This command inserts spaces between the words of the current line so
1562 that the line ends exactly at @code{fill-column}. It returns
1565 The argument @var{how}, if non-@code{nil} specifies explicitly the style
1566 of justification. It can be @code{left}, @code{right}, @code{full},
1567 @code{center}, or @code{none}. If it is @code{t}, that means to do
1568 follow specified justification style (see @code{current-justification},
1569 below). @code{nil} means to do full justification.
1571 If @var{eop} is non-@code{nil}, that means do only left-justification
1572 if @code{current-justification} specifies full justification. This is
1573 used for the last line of a paragraph; even if the paragraph as a
1574 whole is fully justified, the last line should not be.
1576 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1580 @defopt default-justification
1581 This variable's value specifies the style of justification to use for
1582 text that doesn't specify a style with a text property. The possible
1583 values are @code{left}, @code{right}, @code{full}, @code{center}, or
1584 @code{none}. The default value is @code{left}.
1587 @defun current-justification
1588 This function returns the proper justification style to use for filling
1589 the text around point.
1591 This returns the value of the @code{justification} text property at
1592 point, or the variable @var{default-justification} if there is no such
1593 text property. However, it returns @code{nil} rather than @code{none}
1594 to mean ``don't justify''.
1597 @defopt sentence-end-double-space
1598 @anchor{Definition of sentence-end-double-space}
1599 If this variable is non-@code{nil}, a period followed by just one space
1600 does not count as the end of a sentence, and the filling functions
1601 avoid breaking the line at such a place.
1604 @defopt sentence-end-without-period
1605 If this variable is non-@code{nil}, a sentence can end without a
1606 period. This is used for languages like Thai, where sentences end
1607 with a double space but without a period.
1610 @defopt sentence-end-without-space
1611 If this variable is non-@code{nil}, it should be a string of
1612 characters that can end a sentence without following spaces.
1615 @defvar fill-paragraph-function
1616 This variable provides a way to override the filling of paragraphs.
1617 If its value is non-@code{nil}, @code{fill-paragraph} calls this
1618 function to do the work. If the function returns a non-@code{nil}
1619 value, @code{fill-paragraph} assumes the job is done, and immediately
1622 The usual use of this feature is to fill comments in programming
1623 language modes. If the function needs to fill a paragraph in the usual
1624 way, it can do so as follows:
1627 (let ((fill-paragraph-function nil))
1628 (fill-paragraph arg))
1632 @defvar fill-forward-paragraph-function
1633 This variable provides a way to override how the filling functions,
1634 such as @code{fill-region} and @code{fill-paragraph}, move forward to
1635 the next paragraph. Its value should be a function, which is called
1636 with a single argument @var{n}, the number of paragraphs to move, and
1637 should return the difference between @var{n} and the number of
1638 paragraphs actually moved. The default value of this variable is
1639 @code{forward-paragraph}. @xref{Paragraphs,,, emacs, The GNU Emacs
1643 @defvar use-hard-newlines
1644 If this variable is non-@code{nil}, the filling functions do not delete
1645 newlines that have the @code{hard} text property. These ``hard
1646 newlines'' act as paragraph separators. @xref{Hard and Soft
1647 Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
1651 @section Margins for Filling
1652 @cindex margins, filling
1655 This buffer-local variable, if non-@code{nil}, specifies a string of
1656 text that appears at the beginning of normal text lines and should be
1657 disregarded when filling them. Any line that fails to start with the
1658 fill prefix is considered the start of a paragraph; so is any line
1659 that starts with the fill prefix followed by additional whitespace.
1660 Lines that start with the fill prefix but no additional whitespace are
1661 ordinary text lines that can be filled together. The resulting filled
1662 lines also start with the fill prefix.
1664 The fill prefix follows the left margin whitespace, if any.
1668 This buffer-local variable specifies the maximum width of filled lines.
1669 Its value should be an integer, which is a number of columns. All the
1670 filling, justification, and centering commands are affected by this
1671 variable, including Auto Fill mode (@pxref{Auto Filling}).
1673 As a practical matter, if you are writing text for other people to
1674 read, you should set @code{fill-column} to no more than 70. Otherwise
1675 the line will be too long for people to read comfortably, and this can
1676 make the text seem clumsy.
1678 The default value for @code{fill-column} is 70.
1681 @deffn Command set-left-margin from to margin
1682 This sets the @code{left-margin} property on the text from @var{from} to
1683 @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
1684 command also refills the region to fit the new margin.
1687 @deffn Command set-right-margin from to margin
1688 This sets the @code{right-margin} property on the text from @var{from}
1689 to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
1690 this command also refills the region to fit the new margin.
1693 @defun current-left-margin
1694 This function returns the proper left margin value to use for filling
1695 the text around point. The value is the sum of the @code{left-margin}
1696 property of the character at the start of the current line (or zero if
1697 none), and the value of the variable @code{left-margin}.
1700 @defun current-fill-column
1701 This function returns the proper fill column value to use for filling
1702 the text around point. The value is the value of the @code{fill-column}
1703 variable, minus the value of the @code{right-margin} property of the
1704 character after point.
1707 @deffn Command move-to-left-margin &optional n force
1708 This function moves point to the left margin of the current line. The
1709 column moved to is determined by calling the function
1710 @code{current-left-margin}. If the argument @var{n} is non-@code{nil},
1711 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
1713 If @var{force} is non-@code{nil}, that says to fix the line's
1714 indentation if that doesn't match the left margin value.
1717 @defun delete-to-left-margin &optional from to
1718 This function removes left margin indentation from the text between
1719 @var{from} and @var{to}. The amount of indentation to delete is
1720 determined by calling @code{current-left-margin}. In no case does this
1721 function delete non-whitespace. If @var{from} and @var{to} are omitted,
1722 they default to the whole buffer.
1725 @defun indent-to-left-margin
1726 This function adjusts the indentation at the beginning of the current
1727 line to the value specified by the variable @code{left-margin}. (That
1728 may involve either inserting or deleting whitespace.) This function
1729 is value of @code{indent-line-function} in Paragraph-Indent Text mode.
1733 This variable specifies the base left margin column. In Fundamental
1734 mode, @kbd{RET} indents to this column. This variable automatically
1735 becomes buffer-local when set in any fashion.
1738 @defopt fill-nobreak-predicate
1739 This variable gives major modes a way to specify not to break a line
1740 at certain places. Its value should be a list of functions. Whenever
1741 filling considers breaking the line at a certain place in the buffer,
1742 it calls each of these functions with no arguments and with point
1743 located at that place. If any of the functions returns
1744 non-@code{nil}, then the line won't be broken there.
1748 @section Adaptive Fill Mode
1749 @c @cindex Adaptive Fill mode "adaptive-fill-mode" is adjacent.
1751 When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill
1752 prefix automatically from the text in each paragraph being filled
1753 rather than using a predetermined value. During filling, this fill
1754 prefix gets inserted at the start of the second and subsequent lines
1755 of the paragraph as described in @ref{Filling}, and in @ref{Auto
1758 @defopt adaptive-fill-mode
1759 Adaptive Fill mode is enabled when this variable is non-@code{nil}.
1760 It is @code{t} by default.
1763 @defun fill-context-prefix from to
1764 This function implements the heart of Adaptive Fill mode; it chooses a
1765 fill prefix based on the text between @var{from} and @var{to},
1766 typically the start and end of a paragraph. It does this by looking
1767 at the first two lines of the paragraph, based on the variables
1769 @c The optional argument first-line-regexp is not documented
1770 @c because it exists for internal purposes and might be eliminated
1773 Usually, this function returns the fill prefix, a string. However,
1774 before doing this, the function makes a final check (not specially
1775 mentioned in the following) that a line starting with this prefix
1776 wouldn't look like the start of a paragraph. Should this happen, the
1777 function signals the anomaly by returning @code{nil} instead.
1779 In detail, @code{fill-context-prefix} does this:
1783 It takes a candidate for the fill prefix from the first line---it
1784 tries first the function in @code{adaptive-fill-function} (if any),
1785 then the regular expression @code{adaptive-fill-regexp} (see below).
1786 The first non-@code{nil} result of these, or the empty string if
1787 they're both @code{nil}, becomes the first line's candidate.
1789 If the paragraph has as yet only one line, the function tests the
1790 validity of the prefix candidate just found. The function then
1791 returns the candidate if it's valid, or a string of spaces otherwise.
1792 (see the description of @code{adaptive-fill-first-line-regexp} below).
1794 When the paragraph already has two lines, the function next looks for
1795 a prefix candidate on the second line, in just the same way it did for
1796 the first line. If it doesn't find one, it returns @code{nil}.
1798 The function now compares the two candidate prefixes heuristically: if
1799 the non-whitespace characters in the line 2 candidate occur in the
1800 same order in the line 1 candidate, the function returns the line 2
1801 candidate. Otherwise, it returns the largest initial substring which
1802 is common to both candidates (which might be the empty string).
1806 @defopt adaptive-fill-regexp
1807 Adaptive Fill mode matches this regular expression against the text
1808 starting after the left margin whitespace (if any) on a line; the
1809 characters it matches are that line's candidate for the fill prefix.
1811 The default value matches whitespace with certain punctuation
1812 characters intermingled.
1815 @defopt adaptive-fill-first-line-regexp
1816 Used only in one-line paragraphs, this regular expression acts as an
1817 additional check of the validity of the one available candidate fill
1818 prefix: the candidate must match this regular expression, or match
1819 @code{comment-start-skip}. If it doesn't, @code{fill-context-prefix}
1820 replaces the candidate with a string of spaces ``of the same width''
1823 The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which
1824 matches only a string of whitespace. The effect of this default is to
1825 force the fill prefixes found in one-line paragraphs always to be pure
1829 @defopt adaptive-fill-function
1830 You can specify more complex ways of choosing a fill prefix
1831 automatically by setting this variable to a function. The function is
1832 called with point after the left margin (if any) of a line, and it
1833 must preserve point. It should return either ``that line's'' fill
1834 prefix or @code{nil}, meaning it has failed to determine a prefix.
1838 @section Auto Filling
1839 @cindex filling, automatic
1840 @cindex Auto Fill mode
1842 @c FIXME: I don't think any of the variables below is a/an normal/abnormal hook.
1843 Auto Fill mode is a minor mode that fills lines automatically as text
1844 is inserted. This section describes the hook used by Auto Fill mode.
1845 For a description of functions that you can call explicitly to fill and
1846 justify existing text, see @ref{Filling}.
1848 Auto Fill mode also enables the functions that change the margins and
1849 justification style to refill portions of the text. @xref{Margins}.
1851 @defvar auto-fill-function
1852 The value of this buffer-local variable should be a function (of no
1853 arguments) to be called after self-inserting a character from the table
1854 @code{auto-fill-chars}. It may be @code{nil}, in which case nothing
1855 special is done in that case.
1857 The value of @code{auto-fill-function} is @code{do-auto-fill} when
1858 Auto-Fill mode is enabled. That is a function whose sole purpose is to
1859 implement the usual strategy for breaking a line.
1862 @defvar normal-auto-fill-function
1863 This variable specifies the function to use for
1864 @code{auto-fill-function}, if and when Auto Fill is turned on. Major
1865 modes can set buffer-local values for this variable to alter how Auto
1869 @defvar auto-fill-chars
1870 A char table of characters which invoke @code{auto-fill-function} when
1871 self-inserted---space and newline in most language environments. They
1872 have an entry @code{t} in the table.
1876 @section Sorting Text
1877 @cindex sorting text
1879 The sorting functions described in this section all rearrange text in
1880 a buffer. This is in contrast to the function @code{sort}, which
1881 rearranges the order of the elements of a list (@pxref{Rearrangement}).
1882 The values returned by these functions are not meaningful.
1884 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate
1885 This function is the general text-sorting routine that subdivides a
1886 buffer into records and then sorts them. Most of the commands in this
1887 section use this function.
1889 To understand how @code{sort-subr} works, consider the whole accessible
1890 portion of the buffer as being divided into disjoint pieces called
1891 @dfn{sort records}. The records may or may not be contiguous, but they
1892 must not overlap. A portion of each sort record (perhaps all of it) is
1893 designated as the sort key. Sorting rearranges the records in order by
1896 Usually, the records are rearranged in order of ascending sort key.
1897 If the first argument to the @code{sort-subr} function, @var{reverse},
1898 is non-@code{nil}, the sort records are rearranged in order of
1899 descending sort key.
1901 The next four arguments to @code{sort-subr} are functions that are
1902 called to move point across a sort record. They are called many times
1903 from within @code{sort-subr}.
1907 @var{nextrecfun} is called with point at the end of a record. This
1908 function moves point to the start of the next record. The first record
1909 is assumed to start at the position of point when @code{sort-subr} is
1910 called. Therefore, you should usually move point to the beginning of
1911 the buffer before calling @code{sort-subr}.
1913 This function can indicate there are no more sort records by leaving
1914 point at the end of the buffer.
1917 @var{endrecfun} is called with point within a record. It moves point to
1918 the end of the record.
1921 @var{startkeyfun} is called to move point from the start of a record to
1922 the start of the sort key. This argument is optional; if it is omitted,
1923 the whole record is the sort key. If supplied, the function should
1924 either return a non-@code{nil} value to be used as the sort key, or
1925 return @code{nil} to indicate that the sort key is in the buffer
1926 starting at point. In the latter case, @var{endkeyfun} is called to
1927 find the end of the sort key.
1930 @var{endkeyfun} is called to move point from the start of the sort key
1931 to the end of the sort key. This argument is optional. If
1932 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
1933 @code{nil}), then the sort key extends to the end of the record. There
1934 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1935 non-@code{nil} value.
1938 The argument @var{predicate} is the function to use to compare keys.
1939 If keys are numbers, it defaults to @code{<}; otherwise it defaults to
1942 As an example of @code{sort-subr}, here is the complete function
1943 definition for @code{sort-lines}:
1947 ;; @r{Note that the first two lines of doc string}
1948 ;; @r{are effectively one line when viewed by a user.}
1949 (defun sort-lines (reverse beg end)
1950 "Sort lines in region alphabetically;\
1951 argument means descending order.
1952 Called from a program, there are three arguments:
1955 REVERSE (non-nil means reverse order),\
1956 BEG and END (region to sort).
1957 The variable `sort-fold-case' determines\
1958 whether alphabetic case affects
1962 (interactive "P\nr")
1965 (narrow-to-region beg end)
1966 (goto-char (point-min))
1967 (let ((inhibit-field-text-motion t))
1968 (sort-subr reverse 'forward-line 'end-of-line)))))
1972 Here @code{forward-line} moves point to the start of the next record,
1973 and @code{end-of-line} moves point to the end of record. We do not pass
1974 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
1975 record is used as the sort key.
1977 The @code{sort-paragraphs} function is very much the same, except that
1978 its @code{sort-subr} call looks like this:
1985 (while (and (not (eobp))
1986 (looking-at paragraph-separate))
1992 Markers pointing into any sort records are left with no useful
1993 position after @code{sort-subr} returns.
1996 @defopt sort-fold-case
1997 If this variable is non-@code{nil}, @code{sort-subr} and the other
1998 buffer sorting functions ignore case when comparing strings.
2001 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
2002 This command sorts the region between @var{start} and @var{end}
2003 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
2004 If @var{reverse} is a negative integer, then sorting is in reverse
2007 Alphabetical sorting means that two sort keys are compared by
2008 comparing the first characters of each, the second characters of each,
2009 and so on. If a mismatch is found, it means that the sort keys are
2010 unequal; the sort key whose character is less at the point of first
2011 mismatch is the lesser sort key. The individual characters are compared
2012 according to their numerical character codes in the Emacs character set.
2014 The value of the @var{record-regexp} argument specifies how to divide
2015 the buffer into sort records. At the end of each record, a search is
2016 done for this regular expression, and the text that matches it is taken
2017 as the next record. For example, the regular expression @samp{^.+$},
2018 which matches lines with at least one character besides a newline, would
2019 make each such line into a sort record. @xref{Regular Expressions}, for
2020 a description of the syntax and meaning of regular expressions.
2022 The value of the @var{key-regexp} argument specifies what part of each
2023 record is the sort key. The @var{key-regexp} could match the whole
2024 record, or only a part. In the latter case, the rest of the record has
2025 no effect on the sorted order of records, but it is carried along when
2026 the record moves to its new position.
2028 The @var{key-regexp} argument can refer to the text matched by a
2029 subexpression of @var{record-regexp}, or it can be a regular expression
2032 If @var{key-regexp} is:
2035 @item @samp{\@var{digit}}
2036 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
2037 grouping in @var{record-regexp} is the sort key.
2040 then the whole record is the sort key.
2042 @item a regular expression
2043 then @code{sort-regexp-fields} searches for a match for the regular
2044 expression within the record. If such a match is found, it is the sort
2045 key. If there is no match for @var{key-regexp} within a record then
2046 that record is ignored, which means its position in the buffer is not
2047 changed. (The other records may move around it.)
2050 For example, if you plan to sort all the lines in the region by the
2051 first word on each line starting with the letter @samp{f}, you should
2052 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
2053 @samp{\<f\w*\>}. The resulting expression looks like this:
2057 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
2063 If you call @code{sort-regexp-fields} interactively, it prompts for
2064 @var{record-regexp} and @var{key-regexp} in the minibuffer.
2067 @deffn Command sort-lines reverse start end
2068 This command alphabetically sorts lines in the region between
2069 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2070 is in reverse order.
2073 @deffn Command sort-paragraphs reverse start end
2074 This command alphabetically sorts paragraphs in the region between
2075 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2076 is in reverse order.
2079 @deffn Command sort-pages reverse start end
2080 This command alphabetically sorts pages in the region between
2081 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2082 is in reverse order.
2085 @deffn Command sort-fields field start end
2086 This command sorts lines in the region between @var{start} and
2087 @var{end}, comparing them alphabetically by the @var{field}th field
2088 of each line. Fields are separated by whitespace and numbered starting
2089 from 1. If @var{field} is negative, sorting is by the
2090 @w{@minus{}@var{field}th} field from the end of the line. This command
2091 is useful for sorting tables.
2094 @deffn Command sort-numeric-fields field start end
2095 This command sorts lines in the region between @var{start} and
2096 @var{end}, comparing them numerically by the @var{field}th field of
2097 each line. Fields are separated by whitespace and numbered starting
2098 from 1. The specified field must contain a number in each line of the
2099 region. Numbers starting with 0 are treated as octal, and numbers
2100 starting with @samp{0x} are treated as hexadecimal.
2102 If @var{field} is negative, sorting is by the
2103 @w{@minus{}@var{field}th} field from the end of the line. This
2104 command is useful for sorting tables.
2107 @defopt sort-numeric-base
2108 This variable specifies the default radix for
2109 @code{sort-numeric-fields} to parse numbers.
2112 @deffn Command sort-columns reverse &optional beg end
2113 This command sorts the lines in the region between @var{beg} and
2114 @var{end}, comparing them alphabetically by a certain range of
2115 columns. The column positions of @var{beg} and @var{end} bound the
2116 range of columns to sort on.
2118 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
2120 One unusual thing about this command is that the entire line
2121 containing position @var{beg}, and the entire line containing position
2122 @var{end}, are included in the region sorted.
2124 Note that @code{sort-columns} rejects text that contains tabs, because
2125 tabs could be split across the specified columns. Use @kbd{M-x
2126 untabify} to convert tabs to spaces before sorting.
2128 When possible, this command actually works by calling the @code{sort}
2133 @section Counting Columns
2135 @cindex counting columns
2136 @cindex horizontal position
2138 The column functions convert between a character position (counting
2139 characters from the beginning of the buffer) and a column position
2140 (counting screen characters from the beginning of a line).
2142 These functions count each character according to the number of
2143 columns it occupies on the screen. This means control characters count
2144 as occupying 2 or 4 columns, depending upon the value of
2145 @code{ctl-arrow}, and tabs count as occupying a number of columns that
2146 depends on the value of @code{tab-width} and on the column where the tab
2147 begins. @xref{Usual Display}.
2149 Column number computations ignore the width of the window and the
2150 amount of horizontal scrolling. Consequently, a column value can be
2151 arbitrarily high. The first (or leftmost) column is numbered 0. They
2152 also ignore overlays and text properties, aside from invisibility.
2154 @defun current-column
2155 This function returns the horizontal position of point, measured in
2156 columns, counting from 0 at the left margin. The column position is the
2157 sum of the widths of all the displayed representations of the characters
2158 between the start of the current line and point.
2160 For an example of using @code{current-column}, see the description of
2161 @code{count-lines} in @ref{Text Lines}.
2164 @deffn Command move-to-column column &optional force
2165 This function moves point to @var{column} in the current line. The
2166 calculation of @var{column} takes into account the widths of the
2167 displayed representations of the characters between the start of the
2170 When called interactively, @var{column} is the value of prefix numeric
2171 argument. If @var{column} is not an integer, an error is signaled.
2173 @c This behavior used to be documented until 2013/08.
2175 If column @var{column} is beyond the end of the line, point moves to
2176 the end of the line. If @var{column} is negative, point moves to the
2177 beginning of the line.
2180 If it is impossible to move to column @var{column} because that is in
2181 the middle of a multicolumn character such as a tab, point moves to the
2182 end of that character. However, if @var{force} is non-@code{nil}, and
2183 @var{column} is in the middle of a tab, then @code{move-to-column}
2184 converts the tab into spaces so that it can move precisely to column
2185 @var{column}. Other multicolumn characters can cause anomalies despite
2186 @var{force}, since there is no way to split them.
2188 The argument @var{force} also has an effect if the line isn't long
2189 enough to reach column @var{column}; if it is @code{t}, that means to
2190 add whitespace at the end of the line to reach that column.
2192 The return value is the column number actually moved to.
2196 @section Indentation
2199 The indentation functions are used to examine, move to, and change
2200 whitespace that is at the beginning of a line. Some of the functions
2201 can also change whitespace elsewhere on a line. Columns and indentation
2202 count from zero at the left margin.
2205 * Primitive Indent:: Functions used to count and insert indentation.
2206 * Mode-Specific Indent:: Customize indentation for different modes.
2207 * Region Indent:: Indent all the lines in a region.
2208 * Relative Indent:: Indent the current line based on previous lines.
2209 * Indent Tabs:: Adjustable, typewriter-like tab stops.
2210 * Motion by Indent:: Move to first non-blank character.
2213 @node Primitive Indent
2214 @subsection Indentation Primitives
2216 This section describes the primitive functions used to count and
2217 insert indentation. The functions in the following sections use these
2218 primitives. @xref{Size of Displayed Text}, for related functions.
2220 @defun current-indentation
2221 @comment !!Type Primitive Function
2222 @comment !!SourceFile indent.c
2223 This function returns the indentation of the current line, which is
2224 the horizontal position of the first nonblank character. If the
2225 contents are entirely blank, then this is the horizontal position of the
2229 @deffn Command indent-to column &optional minimum
2230 @comment !!Type Primitive Function
2231 @comment !!SourceFile indent.c
2232 This function indents from point with tabs and spaces until @var{column}
2233 is reached. If @var{minimum} is specified and non-@code{nil}, then at
2234 least that many spaces are inserted even if this requires going beyond
2235 @var{column}. Otherwise the function does nothing if point is already
2236 beyond @var{column}. The value is the column at which the inserted
2239 The inserted whitespace characters inherit text properties from the
2240 surrounding text (usually, from the preceding text only). @xref{Sticky
2244 @defopt indent-tabs-mode
2245 @comment !!SourceFile indent.c
2246 If this variable is non-@code{nil}, indentation functions can insert
2247 tabs as well as spaces. Otherwise, they insert only spaces. Setting
2248 this variable automatically makes it buffer-local in the current buffer.
2251 @node Mode-Specific Indent
2252 @subsection Indentation Controlled by Major Mode
2254 An important function of each major mode is to customize the @key{TAB}
2255 key to indent properly for the language being edited. This section
2256 describes the mechanism of the @key{TAB} key and how to control it.
2257 The functions in this section return unpredictable values.
2259 @deffn Command indent-for-tab-command &optional rigid
2260 This is the command bound to @key{TAB} in most editing modes. Its
2261 usual action is to indent the current line, but it can alternatively
2262 insert a tab character or indent a region.
2264 Here is what it does:
2268 First, it checks whether Transient Mark mode is enabled and the region
2269 is active. If so, it called @code{indent-region} to indent all the
2270 text in the region (@pxref{Region Indent}).
2273 Otherwise, if the indentation function in @code{indent-line-function}
2274 is @code{indent-to-left-margin} (a trivial command that inserts a tab
2275 character), or if the variable @code{tab-always-indent} specifies that
2276 a tab character ought to be inserted (see below), then it inserts a
2280 Otherwise, it indents the current line; this is done by calling the
2281 function in @code{indent-line-function}. If the line is already
2282 indented, and the value of @code{tab-always-indent} is @code{complete}
2283 (see below), it tries completing the text at point.
2286 If @var{rigid} is non-@code{nil} (interactively, with a prefix
2287 argument), then after this command indents a line or inserts a tab, it
2288 also rigidly indents the entire balanced expression which starts at
2289 the beginning of the current line, in order to reflect the new
2290 indentation. This argument is ignored if the command indents the
2294 @defvar indent-line-function
2295 This variable's value is the function to be used by
2296 @code{indent-for-tab-command}, and various other indentation commands,
2297 to indent the current line. It is usually assigned by the major mode;
2298 for instance, Lisp mode sets it to @code{lisp-indent-line}, C mode
2299 sets it to @code{c-indent-line}, and so on. The default value is
2300 @code{indent-relative}. @xref{Auto-Indentation}.
2303 @deffn Command indent-according-to-mode
2304 This command calls the function in @code{indent-line-function} to
2305 indent the current line in a way appropriate for the current major mode.
2308 @deffn Command newline-and-indent
2309 This function inserts a newline, then indents the new line (the one
2310 following the newline just inserted) according to the major mode. It
2311 does indentation by calling @code{indent-according-to-mode}.
2314 @deffn Command reindent-then-newline-and-indent
2315 This command reindents the current line, inserts a newline at point,
2316 and then indents the new line (the one following the newline just
2317 inserted). It does indentation on both lines by calling
2318 @code{indent-according-to-mode}.
2321 @defopt tab-always-indent
2322 This variable can be used to customize the behavior of the @key{TAB}
2323 (@code{indent-for-tab-command}) command. If the value is @code{t}
2324 (the default), the command normally just indents the current line. If
2325 the value is @code{nil}, the command indents the current line only if
2326 point is at the left margin or in the line's indentation; otherwise,
2327 it inserts a tab character. If the value is @code{complete}, the
2328 command first tries to indent the current line, and if the line was
2329 already indented, it calls @code{completion-at-point} to complete the
2330 text at point (@pxref{Completion in Buffers}).
2334 @subsection Indenting an Entire Region
2336 This section describes commands that indent all the lines in the
2337 region. They return unpredictable values.
2339 @deffn Command indent-region start end &optional to-column
2340 This command indents each nonblank line starting between @var{start}
2341 (inclusive) and @var{end} (exclusive). If @var{to-column} is
2342 @code{nil}, @code{indent-region} indents each nonblank line by calling
2343 the current mode's indentation function, the value of
2344 @code{indent-line-function}.
2346 If @var{to-column} is non-@code{nil}, it should be an integer
2347 specifying the number of columns of indentation; then this function
2348 gives each line exactly that much indentation, by either adding or
2349 deleting whitespace.
2351 If there is a fill prefix, @code{indent-region} indents each line
2352 by making it start with the fill prefix.
2355 @defvar indent-region-function
2356 The value of this variable is a function that can be used by
2357 @code{indent-region} as a short cut. It should take two arguments, the
2358 start and end of the region. You should design the function so
2359 that it will produce the same results as indenting the lines of the
2360 region one by one, but presumably faster.
2362 If the value is @code{nil}, there is no short cut, and
2363 @code{indent-region} actually works line by line.
2365 A short-cut function is useful in modes such as C mode and Lisp mode,
2366 where the @code{indent-line-function} must scan from the beginning of
2367 the function definition: applying it to each line would be quadratic in
2368 time. The short cut can update the scan information as it moves through
2369 the lines indenting them; this takes linear time. In a mode where
2370 indenting a line individually is fast, there is no need for a short cut.
2372 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
2373 a different meaning and does not use this variable.
2376 @deffn Command indent-rigidly start end count
2377 This function indents all lines starting between @var{start}
2378 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
2379 This ``preserves the shape'' of the affected region, moving it as a
2382 This is useful not only for indenting regions of unindented text, but
2383 also for indenting regions of formatted code. For example, if
2384 @var{count} is 3, this command adds 3 columns of indentation to every
2385 line that begins in the specified region.
2387 If called interactively with no prefix argument, this command invokes
2388 a transient mode for adjusting indentation rigidly. @xref{Indentation
2389 Commands,,, emacs, The GNU Emacs Manual}.
2392 @deffn Command indent-code-rigidly start end columns &optional nochange-regexp
2393 This is like @code{indent-rigidly}, except that it doesn't alter lines
2394 that start within strings or comments.
2396 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
2397 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
2400 @node Relative Indent
2401 @subsection Indentation Relative to Previous Lines
2403 This section describes two commands that indent the current line
2404 based on the contents of previous lines.
2406 @deffn Command indent-relative &optional unindented-ok
2407 This command inserts whitespace at point, extending to the same
2408 column as the next @dfn{indent point} of the previous nonblank line. An
2409 indent point is a non-whitespace character following whitespace. The
2410 next indent point is the first one at a column greater than the current
2411 column of point. For example, if point is underneath and to the left of
2412 the first non-blank character of a line of text, it moves to that column
2413 by inserting whitespace.
2415 If the previous nonblank line has no next indent point (i.e., none at a
2416 great enough column position), @code{indent-relative} either does
2417 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
2418 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right
2419 of the last column of a short line of text, this command ordinarily
2420 moves point to the next tab stop by inserting whitespace.
2422 The return value of @code{indent-relative} is unpredictable.
2424 In the following example, point is at the beginning of the second
2429 This line is indented twelve spaces.
2430 @point{}The quick brown fox jumped.
2435 Evaluation of the expression @code{(indent-relative nil)} produces the
2440 This line is indented twelve spaces.
2441 @point{}The quick brown fox jumped.
2445 In this next example, point is between the @samp{m} and @samp{p} of
2450 This line is indented twelve spaces.
2451 The quick brown fox jum@point{}ped.
2456 Evaluation of the expression @code{(indent-relative nil)} produces the
2461 This line is indented twelve spaces.
2462 The quick brown fox jum @point{}ped.
2467 @deffn Command indent-relative-maybe
2468 @comment !!SourceFile indent.el
2469 This command indents the current line like the previous nonblank line,
2470 by calling @code{indent-relative} with @code{t} as the
2471 @var{unindented-ok} argument. The return value is unpredictable.
2473 If the previous nonblank line has no indent points beyond the current
2474 column, this command does nothing.
2478 @subsection Adjustable ``Tab Stops''
2479 @cindex tabs stops for indentation
2481 This section explains the mechanism for user-specified ``tab stops''
2482 and the mechanisms that use and set them. The name ``tab stops'' is
2483 used because the feature is similar to that of the tab stops on a
2484 typewriter. The feature works by inserting an appropriate number of
2485 spaces and tab characters to reach the next tab stop column; it does not
2486 affect the display of tab characters in the buffer (@pxref{Usual
2487 Display}). Note that the @key{TAB} character as input uses this tab
2488 stop feature only in a few major modes, such as Text mode.
2489 @xref{Tab Stops,,, emacs, The GNU Emacs Manual}.
2491 @deffn Command tab-to-tab-stop
2492 This command inserts spaces or tabs before point, up to the next tab
2493 stop column defined by @code{tab-stop-list}.
2496 @defopt tab-stop-list
2497 This variable defines the tab stop columns used by @code{tab-to-tab-stop}.
2498 It should be either @code{nil}, or a list of increasing integers,
2499 which need not be evenly spaced. The list is implicitly
2500 extended to infinity through repetition of the interval between the
2501 last and penultimate elements (or @code{tab-width} if the list has
2502 fewer than two elements). A value of @code{nil} means a tab stop
2503 every @code{tab-width} columns.
2505 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops interactively.
2508 @node Motion by Indent
2509 @subsection Indentation-Based Motion Commands
2511 These commands, primarily for interactive use, act based on the
2512 indentation in the text.
2514 @deffn Command back-to-indentation
2515 @comment !!SourceFile simple.el
2516 This command moves point to the first non-whitespace character in the
2517 current line (which is the line in which point is located). It returns
2521 @deffn Command backward-to-indentation &optional arg
2522 @comment !!SourceFile simple.el
2523 This command moves point backward @var{arg} lines and then to the
2524 first nonblank character on that line. It returns @code{nil}.
2525 If @var{arg} is omitted or @code{nil}, it defaults to 1.
2528 @deffn Command forward-to-indentation &optional arg
2529 @comment !!SourceFile simple.el
2530 This command moves point forward @var{arg} lines and then to the first
2531 nonblank character on that line. It returns @code{nil}.
2532 If @var{arg} is omitted or @code{nil}, it defaults to 1.
2536 @section Case Changes
2537 @cindex case conversion in buffers
2539 The case change commands described here work on text in the current
2540 buffer. @xref{Case Conversion}, for case conversion functions that work
2541 on strings and characters. @xref{Case Tables}, for how to customize
2542 which characters are upper or lower case and how to convert them.
2544 @deffn Command capitalize-region start end
2545 This function capitalizes all words in the region defined by
2546 @var{start} and @var{end}. To capitalize means to convert each word's
2547 first character to upper case and convert the rest of each word to lower
2548 case. The function returns @code{nil}.
2550 If one end of the region is in the middle of a word, the part of the
2551 word within the region is treated as an entire word.
2553 When @code{capitalize-region} is called interactively, @var{start} and
2554 @var{end} are point and the mark, with the smallest first.
2558 ---------- Buffer: foo ----------
2559 This is the contents of the 5th foo.
2560 ---------- Buffer: foo ----------
2564 (capitalize-region 1 37)
2567 ---------- Buffer: foo ----------
2568 This Is The Contents Of The 5th Foo.
2569 ---------- Buffer: foo ----------
2574 @deffn Command downcase-region start end
2575 This function converts all of the letters in the region defined by
2576 @var{start} and @var{end} to lower case. The function returns
2579 When @code{downcase-region} is called interactively, @var{start} and
2580 @var{end} are point and the mark, with the smallest first.
2583 @deffn Command upcase-region start end
2584 This function converts all of the letters in the region defined by
2585 @var{start} and @var{end} to upper case. The function returns
2588 When @code{upcase-region} is called interactively, @var{start} and
2589 @var{end} are point and the mark, with the smallest first.
2592 @deffn Command capitalize-word count
2593 This function capitalizes @var{count} words after point, moving point
2594 over as it does. To capitalize means to convert each word's first
2595 character to upper case and convert the rest of each word to lower case.
2596 If @var{count} is negative, the function capitalizes the
2597 @minus{}@var{count} previous words but does not move point. The value
2600 If point is in the middle of a word, the part of the word before point
2601 is ignored when moving forward. The rest is treated as an entire word.
2603 When @code{capitalize-word} is called interactively, @var{count} is
2604 set to the numeric prefix argument.
2607 @deffn Command downcase-word count
2608 This function converts the @var{count} words after point to all lower
2609 case, moving point over as it does. If @var{count} is negative, it
2610 converts the @minus{}@var{count} previous words but does not move point.
2611 The value is @code{nil}.
2613 When @code{downcase-word} is called interactively, @var{count} is set
2614 to the numeric prefix argument.
2617 @deffn Command upcase-word count
2618 This function converts the @var{count} words after point to all upper
2619 case, moving point over as it does. If @var{count} is negative, it
2620 converts the @minus{}@var{count} previous words but does not move point.
2621 The value is @code{nil}.
2623 When @code{upcase-word} is called interactively, @var{count} is set to
2624 the numeric prefix argument.
2627 @node Text Properties
2628 @section Text Properties
2629 @cindex text properties
2630 @cindex attributes of text
2631 @cindex properties of text
2633 Each character position in a buffer or a string can have a @dfn{text
2634 property list}, much like the property list of a symbol (@pxref{Property
2635 Lists}). The properties belong to a particular character at a
2636 particular place, such as, the letter @samp{T} at the beginning of this
2637 sentence or the first @samp{o} in @samp{foo}---if the same character
2638 occurs in two different places, the two occurrences in general have
2639 different properties.
2641 Each property has a name and a value. Both of these can be any Lisp
2642 object, but the name is normally a symbol. Typically each property
2643 name symbol is used for a particular purpose; for instance, the text
2644 property @code{face} specifies the faces for displaying the character
2645 (@pxref{Special Properties}). The usual way to access the property
2646 list is to specify a name and ask what value corresponds to it.
2648 If a character has a @code{category} property, we call it the
2649 @dfn{property category} of the character. It should be a symbol. The
2650 properties of the symbol serve as defaults for the properties of the
2653 Copying text between strings and buffers preserves the properties
2654 along with the characters; this includes such diverse functions as
2655 @code{substring}, @code{insert}, and @code{buffer-substring}.
2658 * Examining Properties:: Looking at the properties of one character.
2659 * Changing Properties:: Setting the properties of a range of text.
2660 * Property Search:: Searching for where a property changes value.
2661 * Special Properties:: Particular properties with special meanings.
2662 * Format Properties:: Properties for representing formatting of text.
2663 * Sticky Properties:: How inserted text gets properties from
2665 * Lazy Properties:: Computing text properties in a lazy fashion
2666 only when text is examined.
2667 * Clickable Text:: Using text properties to make regions of text
2668 do something when you click on them.
2669 * Fields:: The @code{field} property defines
2670 fields within the buffer.
2671 * Not Intervals:: Why text properties do not use
2672 Lisp-visible text intervals.
2675 @node Examining Properties
2676 @subsection Examining Text Properties
2677 @cindex examining text properties
2678 @cindex text properties, examining
2680 The simplest way to examine text properties is to ask for the value of
2681 a particular property of a particular character. For that, use
2682 @code{get-text-property}. Use @code{text-properties-at} to get the
2683 entire property list of a character. @xref{Property Search}, for
2684 functions to examine the properties of a number of characters at once.
2686 These functions handle both strings and buffers. Keep in mind that
2687 positions in a string start from 0, whereas positions in a buffer start
2690 @defun get-text-property pos prop &optional object
2691 This function returns the value of the @var{prop} property of the
2692 character after position @var{pos} in @var{object} (a buffer or
2693 string). The argument @var{object} is optional and defaults to the
2696 If there is no @var{prop} property strictly speaking, but the character
2697 has a property category that is a symbol, then @code{get-text-property} returns
2698 the @var{prop} property of that symbol.
2701 @defun get-char-property position prop &optional object
2702 This function is like @code{get-text-property}, except that it checks
2703 overlays first and then text properties. @xref{Overlays}.
2705 The argument @var{object} may be a string, a buffer, or a window. If
2706 it is a window, then the buffer displayed in that window is used for
2707 text properties and overlays, but only the overlays active for that
2708 window are considered. If @var{object} is a buffer, then overlays in
2709 that buffer are considered first, in order of decreasing priority,
2710 followed by the text properties. If @var{object} is a string, only
2711 text properties are considered, since strings never have overlays.
2714 @defun get-pos-property position prop &optional object
2715 This function is like @code{get-char-property}, except that it pays
2716 attention to properties' stickiness and overlays' advancement settings
2717 instead of the property of the character at (i.e. right after)
2721 @defun get-char-property-and-overlay position prop &optional object
2722 This is like @code{get-char-property}, but gives extra information
2723 about the overlay that the property value comes from.
2725 Its value is a cons cell whose @sc{car} is the property value, the
2726 same value @code{get-char-property} would return with the same
2727 arguments. Its @sc{cdr} is the overlay in which the property was
2728 found, or @code{nil}, if it was found as a text property or not found
2731 If @var{position} is at the end of @var{object}, both the @sc{car} and
2732 the @sc{cdr} of the value are @code{nil}.
2735 @defvar char-property-alias-alist
2736 This variable holds an alist which maps property names to a list of
2737 alternative property names. If a character does not specify a direct
2738 value for a property, the alternative property names are consulted in
2739 order; the first non-@code{nil} value is used. This variable takes
2740 precedence over @code{default-text-properties}, and @code{category}
2741 properties take precedence over this variable.
2744 @defun text-properties-at position &optional object
2745 This function returns the entire property list of the character at
2746 @var{position} in the string or buffer @var{object}. If @var{object} is
2747 @code{nil}, it defaults to the current buffer.
2750 @defvar default-text-properties
2751 This variable holds a property list giving default values for text
2752 properties. Whenever a character does not specify a value for a
2753 property, neither directly, through a category symbol, or through
2754 @code{char-property-alias-alist}, the value stored in this list is
2755 used instead. Here is an example:
2758 (setq default-text-properties '(foo 69)
2759 char-property-alias-alist nil)
2760 ;; @r{Make sure character 1 has no properties of its own.}
2761 (set-text-properties 1 2 nil)
2762 ;; @r{What we get, when we ask, is the default value.}
2763 (get-text-property 1 'foo)
2768 @node Changing Properties
2769 @subsection Changing Text Properties
2770 @cindex changing text properties
2771 @cindex text properties, changing
2773 The primitives for changing properties apply to a specified range of
2774 text in a buffer or string. The function @code{set-text-properties}
2775 (see end of section) sets the entire property list of the text in that
2776 range; more often, it is useful to add, change, or delete just certain
2777 properties specified by name.
2779 Since text properties are considered part of the contents of the
2780 buffer (or string), and can affect how a buffer looks on the screen,
2781 any change in buffer text properties marks the buffer as modified.
2782 Buffer text property changes are undoable also (@pxref{Undo}).
2783 Positions in a string start from 0, whereas positions in a buffer
2786 @defun put-text-property start end prop value &optional object
2787 This function sets the @var{prop} property to @var{value} for the text
2788 between @var{start} and @var{end} in the string or buffer @var{object}.
2789 If @var{object} is @code{nil}, it defaults to the current buffer.
2792 @defun add-text-properties start end props &optional object
2793 This function adds or overrides text properties for the text between
2794 @var{start} and @var{end} in the string or buffer @var{object}. If
2795 @var{object} is @code{nil}, it defaults to the current buffer.
2797 The argument @var{props} specifies which properties to add. It should
2798 have the form of a property list (@pxref{Property Lists}): a list whose
2799 elements include the property names followed alternately by the
2800 corresponding values.
2802 The return value is @code{t} if the function actually changed some
2803 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2804 its values agree with those in the text).
2806 For example, here is how to set the @code{comment} and @code{face}
2807 properties of a range of text:
2810 (add-text-properties @var{start} @var{end}
2811 '(comment t face highlight))
2815 @defun remove-text-properties start end props &optional object
2816 This function deletes specified text properties from the text between
2817 @var{start} and @var{end} in the string or buffer @var{object}. If
2818 @var{object} is @code{nil}, it defaults to the current buffer.
2820 The argument @var{props} specifies which properties to delete. It
2821 should have the form of a property list (@pxref{Property Lists}): a list
2822 whose elements are property names alternating with corresponding values.
2823 But only the names matter---the values that accompany them are ignored.
2824 For example, here's how to remove the @code{face} property.
2827 (remove-text-properties @var{start} @var{end} '(face nil))
2830 The return value is @code{t} if the function actually changed some
2831 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2832 if no character in the specified text had any of those properties).
2834 To remove all text properties from certain text, use
2835 @code{set-text-properties} and specify @code{nil} for the new property
2839 @defun remove-list-of-text-properties start end list-of-properties &optional object
2840 Like @code{remove-text-properties} except that
2841 @var{list-of-properties} is a list of property names only, not an
2842 alternating list of property names and values.
2845 @defun set-text-properties start end props &optional object
2846 This function completely replaces the text property list for the text
2847 between @var{start} and @var{end} in the string or buffer @var{object}.
2848 If @var{object} is @code{nil}, it defaults to the current buffer.
2850 The argument @var{props} is the new property list. It should be a list
2851 whose elements are property names alternating with corresponding values.
2853 After @code{set-text-properties} returns, all the characters in the
2854 specified range have identical properties.
2856 If @var{props} is @code{nil}, the effect is to get rid of all properties
2857 from the specified range of text. Here's an example:
2860 (set-text-properties @var{start} @var{end} nil)
2863 Do not rely on the return value of this function.
2866 @defun add-face-text-property start end face &optional appendp object
2867 This function acts on the text between @var{start} and @var{end},
2868 adding the face @var{face} to the @code{face} text property.
2869 @var{face} should be a valid value for the @code{face} property
2870 (@pxref{Special Properties}), such as a face name or an anonymous face
2873 If any text in the region already has a non-@code{nil} @code{face} property,
2874 those face(s) are retained. This function sets the @code{face}
2875 property to a list of faces, with @var{face} as the first element (by
2876 default) and the pre-existing faces as the remaining elements. If the
2877 optional argument @var{append} is non-@code{nil}, @var{face} is
2878 appended to the end of the list instead. Note that in a face list,
2879 the first occurring value for each attribute takes precedence.
2881 For example, the following code would assign a italicized green face
2882 to the text between @var{start} and @var{end}:
2885 (add-face-text-property @var{start} @var{end} 'italic)
2886 (add-face-text-property @var{start} @var{end} '(:foreground "red"))
2887 (add-face-text-property @var{start} @var{end} '(:foreground "green"))
2890 The optional argument @var{object}, if non-@code{nil}, specifies a
2891 buffer or string to act on, rather than the current buffer. If
2892 @var{object} is a string, then @var{start} and @var{end} are
2893 zero-based indices into the string.
2896 The easiest way to make a string with text properties is with
2899 @defun propertize string &rest properties
2900 This function returns a copy of @var{string} with the text properties
2901 @var{properties} added. These properties apply to all the characters
2902 in the string that is returned. Here is an example that constructs a
2903 string with a @code{face} property and a @code{mouse-face} property:
2906 (propertize "foo" 'face 'italic
2907 'mouse-face 'bold-italic)
2908 @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
2911 To put different properties on various parts of a string, you can
2912 construct each part with @code{propertize} and then combine them with
2917 (propertize "foo" 'face 'italic
2918 'mouse-face 'bold-italic)
2920 (propertize "bar" 'face 'italic
2921 'mouse-face 'bold-italic))
2922 @result{} #("foo and bar"
2923 0 3 (face italic mouse-face bold-italic)
2925 8 11 (face italic mouse-face bold-italic))
2929 @xref{Buffer Contents}, for the function
2930 @code{buffer-substring-no-properties}, which copies text from the
2931 buffer but does not copy its properties.
2933 @node Property Search
2934 @subsection Text Property Search Functions
2935 @cindex searching text properties
2936 @cindex text properties, searching
2938 In typical use of text properties, most of the time several or many
2939 consecutive characters have the same value for a property. Rather than
2940 writing your programs to examine characters one by one, it is much
2941 faster to process chunks of text that have the same property value.
2943 Here are functions you can use to do this. They use @code{eq} for
2944 comparing property values. In all cases, @var{object} defaults to the
2947 For good performance, it's very important to use the @var{limit}
2948 argument to these functions, especially the ones that search for a
2949 single property---otherwise, they may spend a long time scanning to the
2950 end of the buffer, if the property you are interested in does not change.
2952 These functions do not move point; instead, they return a position (or
2953 @code{nil}). Remember that a position is always between two characters;
2954 the position returned by these functions is between two characters with
2955 different properties.
2957 @defun next-property-change pos &optional object limit
2958 The function scans the text forward from position @var{pos} in the
2959 string or buffer @var{object} until it finds a change in some text
2960 property, then returns the position of the change. In other words, it
2961 returns the position of the first character beyond @var{pos} whose
2962 properties are not identical to those of the character just after
2965 If @var{limit} is non-@code{nil}, then the scan ends at position
2966 @var{limit}. If there is no property change before that point, this
2967 function returns @var{limit}.
2969 The value is @code{nil} if the properties remain unchanged all the way
2970 to the end of @var{object} and @var{limit} is @code{nil}. If the value
2971 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
2972 The value equals @var{pos} only when @var{limit} equals @var{pos}.
2974 Here is an example of how to scan the buffer by chunks of text within
2975 which all properties are constant:
2979 (let ((plist (text-properties-at (point)))
2981 (or (next-property-change (point) (current-buffer))
2983 @r{Process text from point to @var{next-change}@dots{}}
2984 (goto-char next-change)))
2988 @defun previous-property-change pos &optional object limit
2989 This is like @code{next-property-change}, but scans back from @var{pos}
2990 instead of forward. If the value is non-@code{nil}, it is a position
2991 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
2995 @defun next-single-property-change pos prop &optional object limit
2996 The function scans text for a change in the @var{prop} property, then
2997 returns the position of the change. The scan goes forward from
2998 position @var{pos} in the string or buffer @var{object}. In other
2999 words, this function returns the position of the first character
3000 beyond @var{pos} whose @var{prop} property differs from that of the
3001 character just after @var{pos}.
3003 If @var{limit} is non-@code{nil}, then the scan ends at position
3004 @var{limit}. If there is no property change before that point,
3005 @code{next-single-property-change} returns @var{limit}.
3007 The value is @code{nil} if the property remains unchanged all the way to
3008 the end of @var{object} and @var{limit} is @code{nil}. If the value is
3009 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
3010 equals @var{pos} only if @var{limit} equals @var{pos}.
3013 @defun previous-single-property-change pos prop &optional object limit
3014 This is like @code{next-single-property-change}, but scans back from
3015 @var{pos} instead of forward. If the value is non-@code{nil}, it is a
3016 position less than or equal to @var{pos}; it equals @var{pos} only if
3017 @var{limit} equals @var{pos}.
3020 @defun next-char-property-change pos &optional limit
3021 This is like @code{next-property-change} except that it considers
3022 overlay properties as well as text properties, and if no change is
3023 found before the end of the buffer, it returns the maximum buffer
3024 position rather than @code{nil} (in this sense, it resembles the
3025 corresponding overlay function @code{next-overlay-change}, rather than
3026 @code{next-property-change}). There is no @var{object} operand
3027 because this function operates only on the current buffer. It returns
3028 the next address at which either kind of property changes.
3031 @defun previous-char-property-change pos &optional limit
3032 This is like @code{next-char-property-change}, but scans back from
3033 @var{pos} instead of forward, and returns the minimum buffer
3034 position if no change is found.
3037 @defun next-single-char-property-change pos prop &optional object limit
3038 This is like @code{next-single-property-change} except that it
3039 considers overlay properties as well as text properties, and if no
3040 change is found before the end of the @var{object}, it returns the
3041 maximum valid position in @var{object} rather than @code{nil}. Unlike
3042 @code{next-char-property-change}, this function @emph{does} have an
3043 @var{object} operand; if @var{object} is not a buffer, only
3044 text-properties are considered.
3047 @defun previous-single-char-property-change pos prop &optional object limit
3048 This is like @code{next-single-char-property-change}, but scans back
3049 from @var{pos} instead of forward, and returns the minimum valid
3050 position in @var{object} if no change is found.
3053 @defun text-property-any start end prop value &optional object
3054 This function returns non-@code{nil} if at least one character between
3055 @var{start} and @var{end} has a property @var{prop} whose value is
3056 @var{value}. More precisely, it returns the position of the first such
3057 character. Otherwise, it returns @code{nil}.
3059 The optional fifth argument, @var{object}, specifies the string or
3060 buffer to scan. Positions are relative to @var{object}. The default
3061 for @var{object} is the current buffer.
3064 @defun text-property-not-all start end prop value &optional object
3065 This function returns non-@code{nil} if at least one character between
3066 @var{start} and @var{end} does not have a property @var{prop} with value
3067 @var{value}. More precisely, it returns the position of the first such
3068 character. Otherwise, it returns @code{nil}.
3070 The optional fifth argument, @var{object}, specifies the string or
3071 buffer to scan. Positions are relative to @var{object}. The default
3072 for @var{object} is the current buffer.
3075 @node Special Properties
3076 @subsection Properties with Special Meanings
3078 Here is a table of text property names that have special built-in
3079 meanings. The following sections list a few additional special property
3080 names that control filling and property inheritance. All other names
3081 have no standard meaning, and you can use them as you like.
3083 Note: the properties @code{composition}, @code{display},
3084 @code{invisible} and @code{intangible} can also cause point to move to
3085 an acceptable place, after each Emacs command. @xref{Adjusting
3089 @cindex property category of text character
3090 @c FIXME: Isn't @kindex for keyboard commands?
3091 @kindex category @r{(text property)}
3093 If a character has a @code{category} property, we call it the
3094 @dfn{property category} of the character. It should be a symbol. The
3095 properties of this symbol serve as defaults for the properties of the
3099 @cindex face codes of text
3100 @kindex face @r{(text property)}
3101 The @code{face} property controls the appearance of the character
3102 (@pxref{Faces}). The value of the property can be the following:
3106 A face name (a symbol or string).
3109 An anonymous face: a property list of the form @code{(@var{keyword}
3110 @var{value} @dots{})}, where each @var{keyword} is a face attribute
3111 name and @var{value} is a value for that attribute.
3114 A list of faces. Each list element should be either a face name or an
3115 anonymous face. This specifies a face which is an aggregate of the
3116 attributes of each of the listed faces. Faces occurring earlier in
3117 the list have higher priority.
3120 A cons cell of the form @code{(foreground-color . @var{color-name})}
3121 or @code{(background-color . @var{color-name})}. This specifies the
3122 foreground or background color, similar to @code{(:foreground
3123 @var{color-name})} or @code{(:background @var{color-name})}. This
3124 form is supported for backward compatibility only, and should be
3128 Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
3129 dynamically updating the @code{face} property of characters based on
3132 The @code{add-face-text-property} function provides a convenient way
3133 to set this text property. @xref{Changing Properties}.
3135 @item font-lock-face
3136 @kindex font-lock-face @r{(text property)}
3137 This property specifies a value for the @code{face} property that Font
3138 Lock mode should apply to the underlying text. It is one of the
3139 fontification methods used by Font Lock mode, and is useful for
3140 special modes that implement their own highlighting.
3141 @xref{Precalculated Fontification}. When Font Lock mode is disabled,
3142 @code{font-lock-face} has no effect.
3145 @kindex mouse-face @r{(text property)}
3146 This property is used instead of @code{face} when the mouse is on or
3147 near the character. For this purpose, ``near'' means that all text
3148 between the character and where the mouse is have the same
3149 @code{mouse-face} property value.
3151 Emacs ignores all face attributes from the @code{mouse-face} property
3152 that alter the text size (e.g., @code{:height}, @code{:weight}, and
3153 @code{:slant}). Those attributes are always the same as for the
3157 @kindex fontified @r{(text property)}
3158 This property says whether the text is ready for display. If
3159 @code{nil}, Emacs's redisplay routine calls the functions in
3160 @code{fontification-functions} (@pxref{Auto Faces}) to prepare this
3161 part of the buffer before it is displayed. It is used internally by
3162 the ``just in time'' font locking code.
3165 This property activates various features that change the
3166 way text is displayed. For example, it can make text appear taller
3167 or shorter, higher or lower, wider or narrow, or replaced with an image.
3168 @xref{Display Property}.
3171 @kindex help-echo @r{(text property)}
3173 @anchor{Text help-echo}
3174 If text has a string as its @code{help-echo} property, then when you
3175 move the mouse onto that text, Emacs displays that string in the echo
3176 area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
3179 If the value of the @code{help-echo} property is a function, that
3180 function is called with three arguments, @var{window}, @var{object} and
3181 @var{pos} and should return a help string or @code{nil} for
3182 none. The first argument, @var{window} is the window in which
3183 the help was found. The second, @var{object}, is the buffer, overlay or
3184 string which had the @code{help-echo} property. The @var{pos}
3185 argument is as follows:
3189 If @var{object} is a buffer, @var{pos} is the position in the buffer.
3191 If @var{object} is an overlay, that overlay has a @code{help-echo}
3192 property, and @var{pos} is the position in the overlay's buffer.
3194 If @var{object} is a string (an overlay string or a string displayed
3195 with the @code{display} property), @var{pos} is the position in that
3199 If the value of the @code{help-echo} property is neither a function nor
3200 a string, it is evaluated to obtain a help string.
3202 You can alter the way help text is displayed by setting the variable
3203 @code{show-help-function} (@pxref{Help display}).
3205 This feature is used in the mode line and for other active text.
3208 @cindex keymap of character
3209 @kindex keymap @r{(text property)}
3210 The @code{keymap} property specifies an additional keymap for
3211 commands. When this keymap applies, it is used for key lookup before
3212 the minor mode keymaps and before the buffer's local map.
3213 @xref{Active Keymaps}. If the property value is a symbol, the
3214 symbol's function definition is used as the keymap.
3216 The property's value for the character before point applies if it is
3217 non-@code{nil} and rear-sticky, and the property's value for the
3218 character after point applies if it is non-@code{nil} and
3219 front-sticky. (For mouse clicks, the position of the click is used
3220 instead of the position of point.)
3223 @kindex local-map @r{(text property)}
3224 This property works like @code{keymap} except that it specifies a
3225 keymap to use @emph{instead of} the buffer's local map. For most
3226 purposes (perhaps all purposes), it is better to use the @code{keymap}
3230 The @code{syntax-table} property overrides what the syntax table says
3231 about this particular character. @xref{Syntax Properties}.
3234 @cindex read-only character
3235 @kindex read-only @r{(text property)}
3236 If a character has the property @code{read-only}, then modifying that
3237 character is not allowed. Any command that would do so gets an error,
3238 @code{text-read-only}. If the property value is a string, that string
3239 is used as the error message.
3241 Insertion next to a read-only character is an error if inserting
3242 ordinary text there would inherit the @code{read-only} property due to
3243 stickiness. Thus, you can control permission to insert next to
3244 read-only text by controlling the stickiness. @xref{Sticky Properties}.
3246 Since changing properties counts as modifying the buffer, it is not
3247 possible to remove a @code{read-only} property unless you know the
3248 special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
3249 and then remove the property. @xref{Read Only Buffers}.
3252 @kindex invisible @r{(text property)}
3253 A non-@code{nil} @code{invisible} property can make a character invisible
3254 on the screen. @xref{Invisible Text}, for details.
3257 @kindex intangible @r{(text property)}
3258 If a group of consecutive characters have equal and non-@code{nil}
3259 @code{intangible} properties, then you cannot place point between them.
3260 If you try to move point forward into the group, point actually moves to
3261 the end of the group. If you try to move point backward into the group,
3262 point actually moves to the start of the group.
3264 If consecutive characters have unequal non-@code{nil}
3265 @code{intangible} properties, they belong to separate groups; each
3266 group is separately treated as described above.
3268 When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
3269 the @code{intangible} property is ignored.
3271 Beware: this property operates at a very low level, and affects a lot of code
3272 in unexpected ways. So use it with extreme caution. A common misuse is to put
3273 an intangible property on invisible text, which is actually unnecessary since
3274 the command loop will move point outside of the invisible text at the end of
3275 each command anyway. @xref{Adjusting Point}.
3278 @kindex field @r{(text property)}
3279 Consecutive characters with the same @code{field} property constitute a
3280 @dfn{field}. Some motion functions including @code{forward-word} and
3281 @code{beginning-of-line} stop moving at a field boundary.
3285 @kindex cursor @r{(text property)}
3286 Normally, the cursor is displayed at the beginning or the end of any
3287 overlay and text property strings present at the current buffer
3288 position. You can place the cursor on any desired character of these
3289 strings by giving that character a non-@code{nil} @code{cursor} text
3290 property. In addition, if the value of the @code{cursor} property is
3291 an integer, it specifies the number of buffer's character
3292 positions, starting with the position where the overlay or the
3293 @code{display} property begins, for which the cursor should be
3294 displayed on that character. Specifically, if the value of the
3295 @code{cursor} property of a character is the number @var{n}, the
3296 cursor will be displayed on this character for any buffer position in
3297 the range @code{[@var{ovpos}..@var{ovpos}+@var{n})}, where @var{ovpos}
3298 is the overlay's starting position given by @code{overlay-start}
3299 (@pxref{Managing Overlays}), or the position where the @code{display}
3300 text property begins in the buffer.
3302 In other words, the string character with the @code{cursor} property
3303 of any non-@code{nil} value is the character where to display the
3304 cursor. The value of the property says for which buffer positions to
3305 display the cursor there. If the value is an integer @var{n},
3306 the cursor is displayed there when point is anywhere between the
3307 beginning of the overlay or @code{display} property and @var{n}
3308 positions after that. If the value is anything else and
3309 non-@code{nil}, the cursor is displayed there only when point is at
3310 the beginning of the @code{display} property or at
3311 @code{overlay-start}.
3313 @cindex cursor position for @code{display} properties and overlays
3314 When the buffer has many overlay strings (e.g., @pxref{Overlay
3315 Properties, before-string}) or @code{display} properties that are
3316 strings, it is a good idea to use the @code{cursor} property on these
3317 strings to cue the Emacs display about the places where to put the
3318 cursor while traversing these strings. This directly communicates to
3319 the display engine where the Lisp program wants to put the cursor, or
3320 where the user would expect the cursor.
3323 @kindex pointer @r{(text property)}
3324 This specifies a specific pointer shape when the mouse pointer is over
3325 this text or image. @xref{Pointer Shape}, for possible pointer
3329 @kindex line-spacing @r{(text property)}
3330 A newline can have a @code{line-spacing} text or overlay property that
3331 controls the height of the display line ending with that newline. The
3332 property value overrides the default frame line spacing and the buffer
3333 local @code{line-spacing} variable. @xref{Line Height}.
3336 @kindex line-height @r{(text property)}
3337 A newline can have a @code{line-height} text or overlay property that
3338 controls the total height of the display line ending in that newline.
3342 If text has a @code{wrap-prefix} property, the prefix it defines will
3343 be added at display time to the beginning of every continuation line
3344 due to text wrapping (so if lines are truncated, the wrap-prefix is
3345 never used). It may be a string or an image (@pxref{Other Display
3346 Specs}), or a stretch of whitespace such as specified by the
3347 @code{:width} or @code{:align-to} display properties (@pxref{Specified
3350 A wrap-prefix may also be specified for an entire buffer using the
3351 @code{wrap-prefix} buffer-local variable (however, a
3352 @code{wrap-prefix} text-property takes precedence over the value of
3353 the @code{wrap-prefix} variable). @xref{Truncation}.
3356 If text has a @code{line-prefix} property, the prefix it defines will
3357 be added at display time to the beginning of every non-continuation
3358 line. It may be a string or an image (@pxref{Other Display
3359 Specs}), or a stretch of whitespace such as specified by the
3360 @code{:width} or @code{:align-to} display properties (@pxref{Specified
3363 A line-prefix may also be specified for an entire buffer using the
3364 @code{line-prefix} buffer-local variable (however, a
3365 @code{line-prefix} text-property takes precedence over the value of
3366 the @code{line-prefix} variable). @xref{Truncation}.
3368 @item modification-hooks
3369 @cindex change hooks for a character
3370 @cindex hooks for changing a character
3371 @kindex modification-hooks @r{(text property)}
3372 If a character has the property @code{modification-hooks}, then its
3373 value should be a list of functions; modifying that character calls
3374 all of those functions before the actual modification. Each function
3375 receives two arguments: the beginning and end of the part of the
3376 buffer being modified. Note that if a particular modification hook
3377 function appears on several characters being modified by a single
3378 primitive, you can't predict how many times the function will
3380 Furthermore, insertion will not modify any existing character, so this
3381 hook will only be run when removing some characters, replacing them
3382 with others, or changing their text-properties.
3384 If these functions modify the buffer, they should bind
3385 @code{inhibit-modification-hooks} to @code{t} around doing so, to
3386 avoid confusing the internal mechanism that calls these hooks.
3388 Overlays also support the @code{modification-hooks} property, but the
3389 details are somewhat different (@pxref{Overlay Properties}).
3391 @item insert-in-front-hooks
3392 @itemx insert-behind-hooks
3393 @kindex insert-in-front-hooks @r{(text property)}
3394 @kindex insert-behind-hooks @r{(text property)}
3395 The operation of inserting text in a buffer also calls the functions
3396 listed in the @code{insert-in-front-hooks} property of the following
3397 character and in the @code{insert-behind-hooks} property of the
3398 preceding character. These functions receive two arguments, the
3399 beginning and end of the inserted text. The functions are called
3400 @emph{after} the actual insertion takes place.
3402 See also @ref{Change Hooks}, for other hooks that are called
3403 when you change text in a buffer.
3407 @cindex hooks for motion of point
3408 @kindex point-entered @r{(text property)}
3409 @kindex point-left @r{(text property)}
3410 The special properties @code{point-entered} and @code{point-left}
3411 record hook functions that report motion of point. Each time point
3412 moves, Emacs compares these two property values:
3416 the @code{point-left} property of the character after the old location,
3419 the @code{point-entered} property of the character after the new
3424 If these two values differ, each of them is called (if not @code{nil})
3425 with two arguments: the old value of point, and the new one.
3427 The same comparison is made for the characters before the old and new
3428 locations. The result may be to execute two @code{point-left} functions
3429 (which may be the same function) and/or two @code{point-entered}
3430 functions (which may be the same function). In any case, all the
3431 @code{point-left} functions are called first, followed by all the
3432 @code{point-entered} functions.
3434 It is possible to use @code{char-after} to examine characters at various
3435 buffer positions without moving point to those positions. Only an
3436 actual change in the value of point runs these hook functions.
3438 The variable @code{inhibit-point-motion-hooks} can inhibit running the
3439 @code{point-left} and @code{point-entered} hooks, see @ref{Inhibit
3440 point motion hooks}.
3443 @kindex composition @r{(text property)}
3444 This text property is used to display a sequence of characters as a
3445 single glyph composed from components. But the value of the property
3446 itself is completely internal to Emacs and should not be manipulated
3447 directly by, for instance, @code{put-text-property}.
3451 @defvar inhibit-point-motion-hooks
3452 @anchor{Inhibit point motion hooks} When this variable is
3453 non-@code{nil}, @code{point-left} and @code{point-entered} hooks are
3454 not run, and the @code{intangible} property has no effect. Do not set
3455 this variable globally; bind it with @code{let}.
3458 @defvar show-help-function
3459 @anchor{Help display} If this variable is non-@code{nil}, it specifies a
3460 function called to display help strings. These may be @code{help-echo}
3461 properties, menu help strings (@pxref{Simple Menu Items},
3462 @pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
3463 Bar}). The specified function is called with one argument, the help
3464 string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs
3465 Manual}) provides an example.
3468 @node Format Properties
3469 @subsection Formatted Text Properties
3471 These text properties affect the behavior of the fill commands. They
3472 are used for representing formatted text. @xref{Filling}, and
3477 If a newline character has this property, it is a ``hard'' newline.
3478 The fill commands do not alter hard newlines and do not move words
3479 across them. However, this property takes effect only if the
3480 @code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft
3481 Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
3484 This property specifies an extra right margin for filling this part of the
3488 This property specifies an extra left margin for filling this part of the
3492 This property specifies the style of justification for filling this part
3496 @node Sticky Properties
3497 @subsection Stickiness of Text Properties
3498 @cindex sticky text properties
3499 @cindex inheritance, text property
3501 Self-inserting characters normally take on the same properties as the
3502 preceding character. This is called @dfn{inheritance} of properties.
3504 A Lisp program can do insertion with inheritance or without,
3505 depending on the choice of insertion primitive. The ordinary text
3506 insertion functions, such as @code{insert}, do not inherit any
3507 properties. They insert text with precisely the properties of the
3508 string being inserted, and no others. This is correct for programs
3509 that copy text from one context to another---for example, into or out
3510 of the kill ring. To insert with inheritance, use the special
3511 primitives described in this section. Self-inserting characters
3512 inherit properties because they work using these primitives.
3514 When you do insertion with inheritance, @emph{which} properties are
3515 inherited, and from where, depends on which properties are @dfn{sticky}.
3516 Insertion after a character inherits those of its properties that are
3517 @dfn{rear-sticky}. Insertion before a character inherits those of its
3518 properties that are @dfn{front-sticky}. When both sides offer different
3519 sticky values for the same property, the previous character's value
3522 By default, a text property is rear-sticky but not front-sticky; thus,
3523 the default is to inherit all the properties of the preceding character,
3524 and nothing from the following character.
3526 You can control the stickiness of various text properties with two
3527 specific text properties, @code{front-sticky} and @code{rear-nonsticky},
3528 and with the variable @code{text-property-default-nonsticky}. You can
3529 use the variable to specify a different default for a given property.
3530 You can use those two text properties to make any specific properties
3531 sticky or nonsticky in any particular part of the text.
3533 If a character's @code{front-sticky} property is @code{t}, then all
3534 its properties are front-sticky. If the @code{front-sticky} property is
3535 a list, then the sticky properties of the character are those whose
3536 names are in the list. For example, if a character has a
3537 @code{front-sticky} property whose value is @code{(face read-only)},
3538 then insertion before the character can inherit its @code{face} property
3539 and its @code{read-only} property, but no others.
3541 The @code{rear-nonsticky} property works the opposite way. Most
3542 properties are rear-sticky by default, so the @code{rear-nonsticky}
3543 property says which properties are @emph{not} rear-sticky. If a
3544 character's @code{rear-nonsticky} property is @code{t}, then none of its
3545 properties are rear-sticky. If the @code{rear-nonsticky} property is a
3546 list, properties are rear-sticky @emph{unless} their names are in the
3549 @defvar text-property-default-nonsticky
3550 This variable holds an alist which defines the default rear-stickiness
3551 of various text properties. Each element has the form
3552 @code{(@var{property} . @var{nonstickiness})}, and it defines the
3553 stickiness of a particular text property, @var{property}.
3555 If @var{nonstickiness} is non-@code{nil}, this means that the property
3556 @var{property} is rear-nonsticky by default. Since all properties are
3557 front-nonsticky by default, this makes @var{property} nonsticky in both
3558 directions by default.
3560 The text properties @code{front-sticky} and @code{rear-nonsticky}, when
3561 used, take precedence over the default @var{nonstickiness} specified in
3562 @code{text-property-default-nonsticky}.
3565 Here are the functions that insert text with inheritance of properties:
3567 @defun insert-and-inherit &rest strings
3568 Insert the strings @var{strings}, just like the function @code{insert},
3569 but inherit any sticky properties from the adjoining text.
3572 @defun insert-before-markers-and-inherit &rest strings
3573 Insert the strings @var{strings}, just like the function
3574 @code{insert-before-markers}, but inherit any sticky properties from the
3578 @xref{Insertion}, for the ordinary insertion functions which do not
3581 @node Lazy Properties
3582 @subsection Lazy Computation of Text Properties
3584 Instead of computing text properties for all the text in the buffer,
3585 you can arrange to compute the text properties for parts of the text
3586 when and if something depends on them.
3588 The primitive that extracts text from the buffer along with its
3589 properties is @code{buffer-substring}. Before examining the properties,
3590 this function runs the abnormal hook @code{buffer-access-fontify-functions}.
3592 @defvar buffer-access-fontify-functions
3593 This variable holds a list of functions for computing text properties.
3594 Before @code{buffer-substring} copies the text and text properties for a
3595 portion of the buffer, it calls all the functions in this list. Each of
3596 the functions receives two arguments that specify the range of the
3597 buffer being accessed. (The buffer itself is always the current
3601 The function @code{buffer-substring-no-properties} does not call these
3602 functions, since it ignores text properties anyway.
3604 In order to prevent the hook functions from being called more than
3605 once for the same part of the buffer, you can use the variable
3606 @code{buffer-access-fontified-property}.
3608 @defvar buffer-access-fontified-property
3609 If this variable's value is non-@code{nil}, it is a symbol which is used
3610 as a text property name. A non-@code{nil} value for that text property
3611 means, ``the other text properties for this character have already been
3614 If all the characters in the range specified for @code{buffer-substring}
3615 have a non-@code{nil} value for this property, @code{buffer-substring}
3616 does not call the @code{buffer-access-fontify-functions} functions. It
3617 assumes these characters already have the right text properties, and
3618 just copies the properties they already have.
3620 The normal way to use this feature is that the
3621 @code{buffer-access-fontify-functions} functions add this property, as
3622 well as others, to the characters they operate on. That way, they avoid
3623 being called over and over for the same text.
3626 @node Clickable Text
3627 @subsection Defining Clickable Text
3628 @cindex clickable text
3629 @cindex follow links
3632 @dfn{Clickable text} is text that can be clicked, with either the
3633 mouse or via a keyboard command, to produce some result. Many major
3634 modes use clickable text to implement textual hyper-links, or
3635 @dfn{links} for short.
3637 The easiest way to insert and manipulate links is to use the
3638 @code{button} package. @xref{Buttons}. In this section, we will
3639 explain how to manually set up clickable text in a buffer, using text
3640 properties. For simplicity, we will refer to the clickable text as a
3643 Implementing a link involves three separate steps: (1) indicating
3644 clickability when the mouse moves over the link; (2) making @key{RET}
3645 or @kbd{Mouse-2} on that link do something; and (3) setting up a
3646 @code{follow-link} condition so that the link obeys
3647 @code{mouse-1-click-follows-link}.
3649 To indicate clickability, add the @code{mouse-face} text property to
3650 the text of the link; then Emacs will highlight the link when the
3651 mouse moves over it. In addition, you should define a tooltip or echo
3652 area message, using the @code{help-echo} text property. @xref{Special
3653 Properties}. For instance, here is how Dired indicates that file
3654 names are clickable:
3657 (if (dired-move-to-filename)
3658 (add-text-properties
3661 (dired-move-to-end-of-filename)
3663 '(mouse-face highlight
3664 help-echo "mouse-2: visit this file in other window")))
3667 To make the link clickable, bind @key{RET} and @kbd{Mouse-2} to
3668 commands that perform the desired action. Each command should check
3669 to see whether it was called on a link, and act accordingly. For
3670 instance, Dired's major mode keymap binds @kbd{Mouse-2} to the
3674 (defun dired-mouse-find-file-other-window (event)
3675 "In Dired, visit the file or directory name you click on."
3677 (let ((window (posn-window (event-end event)))
3678 (pos (posn-point (event-end event)))
3680 (if (not (windowp window))
3681 (error "No file chosen"))
3682 (with-current-buffer (window-buffer window)
3684 (setq file (dired-get-file-for-visit)))
3685 (if (file-directory-p file)
3686 (or (and (cdr dired-subdir-alist)
3687 (dired-goto-subdir file))
3689 (select-window window)
3690 (dired-other-window file)))
3691 (select-window window)
3692 (find-file-other-window (file-name-sans-versions file t)))))
3696 This command uses the functions @code{posn-window} and
3697 @code{posn-point} to determine where the click occurred, and
3698 @code{dired-get-file-for-visit} to determine which file to visit.
3700 Instead of binding the mouse command in a major mode keymap, you can
3701 bind it within the link text, using the @code{keymap} text property
3702 (@pxref{Special Properties}). For instance:
3705 (let ((map (make-sparse-keymap)))
3706 (define-key map [mouse-2] 'operate-this-button)
3707 (put-text-property link-start link-end 'keymap map))
3711 With this method, you can easily define different commands for
3712 different links. Furthermore, the global definition of @key{RET} and
3713 @kbd{Mouse-2} remain available for the rest of the text in the buffer.
3715 @vindex mouse-1-click-follows-link
3716 The basic Emacs command for clicking on links is @kbd{Mouse-2}.
3717 However, for compatibility with other graphical applications, Emacs
3718 also recognizes @kbd{Mouse-1} clicks on links, provided the user
3719 clicks on the link quickly without moving the mouse. This behavior is
3720 controlled by the user option @code{mouse-1-click-follows-link}.
3721 @xref{Mouse References,,, emacs, The GNU Emacs Manual}.
3723 To set up the link so that it obeys
3724 @code{mouse-1-click-follows-link}, you must either (1) apply a
3725 @code{follow-link} text or overlay property to the link text, or (2)
3726 bind the @code{follow-link} event to a keymap (which can be a major
3727 mode keymap or a local keymap specified via the @code{keymap} text
3728 property). The value of the @code{follow-link} property, or the
3729 binding for the @code{follow-link} event, acts as a ``condition'' for
3730 the link action. This condition tells Emacs two things: the
3731 circumstances under which a @kbd{Mouse-1} click should be regarded as
3732 occurring ``inside'' the link, and how to compute an ``action code''
3733 that says what to translate the @kbd{Mouse-1} click into. The link
3734 action condition can be one of the following:
3737 @item @code{mouse-face}
3738 If the condition is the symbol @code{mouse-face}, a position is inside
3739 a link if there is a non-@code{nil} @code{mouse-face} property at that
3740 position. The action code is always @code{t}.
3742 For example, here is how Info mode handles @key{Mouse-1}:
3745 (define-key Info-mode-map [follow-link] 'mouse-face)
3749 If the condition is a function, @var{func}, then a position @var{pos}
3750 is inside a link if @code{(@var{func} @var{pos})} evaluates to
3751 non-@code{nil}. The value returned by @var{func} serves as the action
3754 For example, here is how pcvs enables @kbd{Mouse-1} to follow links on
3758 (define-key map [follow-link]
3760 (eq (get-char-property pos 'face) 'cvs-filename-face)))
3764 If the condition value is anything else, then the position is inside a
3765 link and the condition itself is the action code. Clearly, you should
3766 specify this kind of condition only when applying the condition via a
3767 text or property overlay on the link text (so that it does not apply
3768 to the entire buffer).
3772 The action code tells @kbd{Mouse-1} how to follow the link:
3775 @item a string or vector
3776 If the action code is a string or vector, the @kbd{Mouse-1} event is
3777 translated into the first element of the string or vector; i.e., the
3778 action of the @kbd{Mouse-1} click is the local or global binding of
3779 that character or symbol. Thus, if the action code is @code{"foo"},
3780 @kbd{Mouse-1} translates into @kbd{f}. If it is @code{[foo]},
3781 @kbd{Mouse-1} translates into @key{foo}.
3784 For any other non-@code{nil} action code, the @kbd{Mouse-1} event is
3785 translated into a @kbd{Mouse-2} event at the same position.
3788 To define @kbd{Mouse-1} to activate a button defined with
3789 @code{define-button-type}, give the button a @code{follow-link}
3790 property. The property value should be a link action condition, as
3791 described above. @xref{Buttons}. For example, here is how Help mode
3792 handles @kbd{Mouse-1}:
3795 (define-button-type 'help-xref
3797 'action #'help-button-action)
3800 To define @kbd{Mouse-1} on a widget defined with
3801 @code{define-widget}, give the widget a @code{:follow-link} property.
3802 The property value should be a link action condition, as described
3803 above. For example, here is how the @code{link} widget specifies that
3804 a @key{Mouse-1} click shall be translated to @key{RET}:
3807 (define-widget 'link 'item
3809 :button-prefix 'widget-link-prefix
3810 :button-suffix 'widget-link-suffix
3812 :help-echo "Follow the link."
3816 @defun mouse-on-link-p pos
3817 This function returns non-@code{nil} if position @var{pos} in the
3818 current buffer is on a link. @var{pos} can also be a mouse event
3819 location, as returned by @code{event-start} (@pxref{Accessing Mouse}).
3823 @subsection Defining and Using Fields
3826 A field is a range of consecutive characters in the buffer that are
3827 identified by having the same value (comparing with @code{eq}) of the
3828 @code{field} property (either a text-property or an overlay property).
3829 This section describes special functions that are available for
3830 operating on fields.
3832 You specify a field with a buffer position, @var{pos}. We think of
3833 each field as containing a range of buffer positions, so the position
3834 you specify stands for the field containing that position.
3836 When the characters before and after @var{pos} are part of the same
3837 field, there is no doubt which field contains @var{pos}: the one those
3838 characters both belong to. When @var{pos} is at a boundary between
3839 fields, which field it belongs to depends on the stickiness of the
3840 @code{field} properties of the two surrounding characters (@pxref{Sticky
3841 Properties}). The field whose property would be inherited by text
3842 inserted at @var{pos} is the field that contains @var{pos}.
3844 There is an anomalous case where newly inserted text at @var{pos}
3845 would not inherit the @code{field} property from either side. This
3846 happens if the previous character's @code{field} property is not
3847 rear-sticky, and the following character's @code{field} property is not
3848 front-sticky. In this case, @var{pos} belongs to neither the preceding
3849 field nor the following field; the field functions treat it as belonging
3850 to an empty field whose beginning and end are both at @var{pos}.
3852 In all of these functions, if @var{pos} is omitted or @code{nil}, the
3853 value of point is used by default. If narrowing is in effect, then
3854 @var{pos} should fall within the accessible portion. @xref{Narrowing}.
3856 @defun field-beginning &optional pos escape-from-edge limit
3857 This function returns the beginning of the field specified by @var{pos}.
3859 If @var{pos} is at the beginning of its field, and
3860 @var{escape-from-edge} is non-@code{nil}, then the return value is
3861 always the beginning of the preceding field that @emph{ends} at @var{pos},
3862 regardless of the stickiness of the @code{field} properties around
3865 If @var{limit} is non-@code{nil}, it is a buffer position; if the
3866 beginning of the field is before @var{limit}, then @var{limit} will be
3870 @defun field-end &optional pos escape-from-edge limit
3871 This function returns the end of the field specified by @var{pos}.
3873 If @var{pos} is at the end of its field, and @var{escape-from-edge} is
3874 non-@code{nil}, then the return value is always the end of the following
3875 field that @emph{begins} at @var{pos}, regardless of the stickiness of
3876 the @code{field} properties around @var{pos}.
3878 If @var{limit} is non-@code{nil}, it is a buffer position; if the end
3879 of the field is after @var{limit}, then @var{limit} will be returned
3883 @defun field-string &optional pos
3884 This function returns the contents of the field specified by @var{pos},
3888 @defun field-string-no-properties &optional pos
3889 This function returns the contents of the field specified by @var{pos},
3890 as a string, discarding text properties.
3893 @defun delete-field &optional pos
3894 This function deletes the text of the field specified by @var{pos}.
3897 @defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
3898 This function ``constrains'' @var{new-pos} to the field that
3899 @var{old-pos} belongs to---in other words, it returns the position
3900 closest to @var{new-pos} that is in the same field as @var{old-pos}.
3902 If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
3903 the value of point instead, and moves point to the resulting position
3904 in addition to returning that position.
3906 If @var{old-pos} is at the boundary of two fields, then the acceptable
3907 final positions depend on the argument @var{escape-from-edge}. If
3908 @var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in
3909 the field whose @code{field} property equals what new characters
3910 inserted at @var{old-pos} would inherit. (This depends on the
3911 stickiness of the @code{field} property for the characters before and
3912 after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
3913 @var{new-pos} can be anywhere in the two adjacent fields.
3914 Additionally, if two fields are separated by another field with the
3915 special value @code{boundary}, then any point within this special
3916 field is also considered to be ``on the boundary''.
3918 Commands like @kbd{C-a} with no argument, that normally move backward
3919 to a specific kind of location and stay there once there, probably
3920 should specify @code{nil} for @var{escape-from-edge}. Other motion
3921 commands that check fields should probably pass @code{t}.
3923 If the optional argument @var{only-in-line} is non-@code{nil}, and
3924 constraining @var{new-pos} in the usual way would move it to a different
3925 line, @var{new-pos} is returned unconstrained. This used in commands
3926 that move by line, such as @code{next-line} and
3927 @code{beginning-of-line}, so that they respect field boundaries only in
3928 the case where they can still move to the right line.
3930 If the optional argument @var{inhibit-capture-property} is
3931 non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that
3932 name, then any field boundaries are ignored.
3934 You can cause @code{constrain-to-field} to ignore all field boundaries
3935 (and so never constrain anything) by binding the variable
3936 @code{inhibit-field-text-motion} to a non-@code{nil} value.
3940 @subsection Why Text Properties are not Intervals
3943 Some editors that support adding attributes to text in the buffer do
3944 so by letting the user specify ``intervals'' within the text, and adding
3945 the properties to the intervals. Those editors permit the user or the
3946 programmer to determine where individual intervals start and end. We
3947 deliberately provided a different sort of interface in Emacs Lisp to
3948 avoid certain paradoxical behavior associated with text modification.
3950 If the actual subdivision into intervals is meaningful, that means you
3951 can distinguish between a buffer that is just one interval with a
3952 certain property, and a buffer containing the same text subdivided into
3953 two intervals, both of which have that property.
3955 Suppose you take the buffer with just one interval and kill part of
3956 the text. The text remaining in the buffer is one interval, and the
3957 copy in the kill ring (and the undo list) becomes a separate interval.
3958 Then if you yank back the killed text, you get two intervals with the
3959 same properties. Thus, editing does not preserve the distinction
3960 between one interval and two.
3962 Suppose we ``fix'' this problem by coalescing the two intervals when
3963 the text is inserted. That works fine if the buffer originally was a
3964 single interval. But suppose instead that we have two adjacent
3965 intervals with the same properties, and we kill the text of one interval
3966 and yank it back. The same interval-coalescence feature that rescues
3967 the other case causes trouble in this one: after yanking, we have just
3968 one interval. Once again, editing does not preserve the distinction
3969 between one interval and two.
3971 Insertion of text at the border between intervals also raises
3972 questions that have no satisfactory answer.
3974 However, it is easy to arrange for editing to behave consistently
3975 for questions of the form, ``What are the properties of text at this
3976 buffer or string position?'' So we have decided these are the only
3977 questions that make sense; we have not implemented asking questions
3978 about where intervals start or end.
3980 In practice, you can usually use the text property search functions in
3981 place of explicit interval boundaries. You can think of them as finding
3982 the boundaries of intervals, assuming that intervals are always
3983 coalesced whenever possible. @xref{Property Search}.
3985 Emacs also provides explicit intervals as a presentation feature; see
3989 @section Substituting for a Character Code
3990 @cindex replace characters in region
3991 @cindex substitute characters
3993 The following functions replace characters within a specified region
3994 based on their character codes.
3996 @defun subst-char-in-region start end old-char new-char &optional noundo
3997 @cindex replace characters
3998 This function replaces all occurrences of the character @var{old-char}
3999 with the character @var{new-char} in the region of the current buffer
4000 defined by @var{start} and @var{end}.
4002 @cindex undo avoidance
4003 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
4004 not record the change for undo and does not mark the buffer as modified.
4005 This was useful for controlling the old selective display feature
4006 (@pxref{Selective Display}).
4008 @code{subst-char-in-region} does not move point and returns
4013 ---------- Buffer: foo ----------
4014 This is the contents of the buffer before.
4015 ---------- Buffer: foo ----------
4019 (subst-char-in-region 1 20 ?i ?X)
4022 ---------- Buffer: foo ----------
4023 ThXs Xs the contents of the buffer before.
4024 ---------- Buffer: foo ----------
4029 @deffn Command translate-region start end table
4030 This function applies a translation table to the characters in the
4031 buffer between positions @var{start} and @var{end}.
4033 The translation table @var{table} is a string or a char-table;
4034 @code{(aref @var{table} @var{ochar})} gives the translated character
4035 corresponding to @var{ochar}. If @var{table} is a string, any
4036 characters with codes larger than the length of @var{table} are not
4037 altered by the translation.
4039 The return value of @code{translate-region} is the number of
4040 characters that were actually changed by the translation. This does
4041 not count characters that were mapped into themselves in the
4049 A register is a sort of variable used in Emacs editing that can hold a
4050 variety of different kinds of values. Each register is named by a
4051 single character. All @acronym{ASCII} characters and their meta variants
4052 (but with the exception of @kbd{C-g}) can be used to name registers.
4053 Thus, there are 255 possible registers. A register is designated in
4054 Emacs Lisp by the character that is its name.
4056 @defvar register-alist
4057 This variable is an alist of elements of the form @code{(@var{name} .
4058 @var{contents})}. Normally, there is one element for each Emacs
4059 register that has been used.
4061 The object @var{name} is a character (an integer) identifying the
4065 The @var{contents} of a register can have several possible types:
4069 A number stands for itself. If @code{insert-register} finds a number
4070 in the register, it converts the number to decimal.
4073 A marker represents a buffer position to jump to.
4076 A string is text saved in the register.
4079 A rectangle is represented by a list of strings.
4081 @item @code{(@var{window-configuration} @var{position})}
4082 This represents a window configuration to restore in one frame, and a
4083 position to jump to in the current buffer.
4085 @c FIXME: Mention frameset here.
4086 @item @code{(@var{frame-configuration} @var{position})}
4087 This represents a frame configuration to restore, and a position
4088 to jump to in the current buffer.
4090 @item (file @var{filename})
4091 This represents a file to visit; jumping to this value visits file
4094 @item (file-query @var{filename} @var{position})
4095 This represents a file to visit and a position in it; jumping to this
4096 value visits file @var{filename} and goes to buffer position
4097 @var{position}. Restoring this type of position asks the user for
4101 The functions in this section return unpredictable values unless
4104 @defun get-register reg
4105 This function returns the contents of the register
4106 @var{reg}, or @code{nil} if it has no contents.
4109 @defun set-register reg value
4110 This function sets the contents of register @var{reg} to @var{value}.
4111 A register can be set to any value, but the other register functions
4112 expect only certain data types. The return value is @var{value}.
4115 @deffn Command view-register reg
4116 This command displays what is contained in register @var{reg}.
4119 @deffn Command insert-register reg &optional beforep
4120 This command inserts contents of register @var{reg} into the current
4123 Normally, this command puts point before the inserted text, and the
4124 mark after it. However, if the optional second argument @var{beforep}
4125 is non-@code{nil}, it puts the mark before and point after.
4126 You can pass a non-@code{nil} second argument @var{beforep} to this
4127 function interactively by supplying any prefix argument.
4129 If the register contains a rectangle, then the rectangle is inserted
4130 with its upper left corner at point. This means that text is inserted
4131 in the current line and underneath it on successive lines.
4133 If the register contains something other than saved text (a string) or
4134 a rectangle (a list), currently useless things happen. This may be
4135 changed in the future.
4138 @defun register-read-with-preview prompt
4139 @cindex register preview
4140 This function reads and returns a register name, prompting with
4141 @var{prompt} and possibly showing a preview of the existing registers
4142 and their contents. The preview is shown in a temporary window, after
4143 the delay specified by the user option @code{register-preview-delay},
4144 if its value and @code{register-alist} are both non-@code{nil}. The
4145 preview is also shown if the user requests help (e.g., by typing the
4146 help character). We recommend that all interactive commands which
4147 read register names use this function.
4151 @section Transposition of Text
4153 This function can be used to transpose stretches of text:
4155 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
4156 This function exchanges two nonoverlapping portions of the buffer.
4157 Arguments @var{start1} and @var{end1} specify the bounds of one portion
4158 and arguments @var{start2} and @var{end2} specify the bounds of the
4161 Normally, @code{transpose-regions} relocates markers with the transposed
4162 text; a marker previously positioned within one of the two transposed
4163 portions moves along with that portion, thus remaining between the same
4164 two characters in their new position. However, if @var{leave-markers}
4165 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
4166 all markers unrelocated.
4170 @section Dealing With Compressed Data
4172 When @code{auto-compression-mode} is enabled, Emacs automatically
4173 uncompresses compressed files when you visit them, and automatically
4174 recompresses them if you alter and save them. @xref{Compressed
4175 Files,,, emacs, The GNU Emacs Manual}.
4177 The above feature works by calling an external executable (e.g.,
4178 @command{gzip}). Emacs can also be compiled with support for built-in
4179 decompression using the zlib library, which is faster than calling an
4182 @defun zlib-available-p
4183 This function returns non-@code{nil} if built-in zlib decompression is
4187 @defun zlib-decompress-region start end
4188 This function decompresses the region between @var{start} and
4189 @var{end}, using built-in zlib decompression. The region should
4190 contain data that were compressed with gzip or zlib. On success, the
4191 function replaces the contents of the region with the decompressed
4192 data. On failure, the function leaves the region unchanged and
4193 returns @code{nil}. This function can be called only in unibyte
4199 @section Base 64 Encoding
4200 @cindex base 64 encoding
4202 Base 64 code is used in email to encode a sequence of 8-bit bytes as
4203 a longer sequence of @acronym{ASCII} graphic characters. It is defined in
4204 Internet RFC@footnote{
4205 An RFC, an acronym for @dfn{Request for Comments}, is a numbered
4206 Internet informational document describing a standard. RFCs are
4207 usually written by technical experts acting on their own initiative,
4208 and are traditionally written in a pragmatic, experience-driven
4210 }2045. This section describes the functions for
4211 converting to and from this code.
4213 @deffn Command base64-encode-region beg end &optional no-line-break
4214 This function converts the region from @var{beg} to @var{end} into base
4215 64 code. It returns the length of the encoded text. An error is
4216 signaled if a character in the region is multibyte, i.e., in a
4217 multibyte buffer the region must contain only characters from the
4218 charsets @code{ascii}, @code{eight-bit-control} and
4219 @code{eight-bit-graphic}.
4221 Normally, this function inserts newline characters into the encoded
4222 text, to avoid overlong lines. However, if the optional argument
4223 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
4224 the output is just one long line.
4227 @defun base64-encode-string string &optional no-line-break
4228 This function converts the string @var{string} into base 64 code. It
4229 returns a string containing the encoded text. As for
4230 @code{base64-encode-region}, an error is signaled if a character in the
4231 string is multibyte.
4233 Normally, this function inserts newline characters into the encoded
4234 text, to avoid overlong lines. However, if the optional argument
4235 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
4236 the result string is just one long line.
4239 @deffn Command base64-decode-region beg end
4240 This function converts the region from @var{beg} to @var{end} from base
4241 64 code into the corresponding decoded text. It returns the length of
4244 The decoding functions ignore newline characters in the encoded text.
4247 @defun base64-decode-string string
4248 This function converts the string @var{string} from base 64 code into
4249 the corresponding decoded text. It returns a unibyte string containing the
4252 The decoding functions ignore newline characters in the encoded text.
4256 @section Checksum/Hash
4257 @cindex MD5 checksum
4259 @cindex hash, cryptographic
4260 @cindex cryptographic hash
4262 Emacs has built-in support for computing @dfn{cryptographic hashes}.
4263 A cryptographic hash, or @dfn{checksum}, is a digital ``fingerprint''
4264 of a piece of data (e.g., a block of text) which can be used to check
4265 that you have an unaltered copy of that data.
4267 @cindex message digest
4268 Emacs supports several common cryptographic hash algorithms: MD5,
4269 SHA-1, SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512. MD5 is the
4270 oldest of these algorithms, and is commonly used in @dfn{message
4271 digests} to check the integrity of messages transmitted over a
4272 network. MD5 is not ``collision resistant'' (i.e., it is possible to
4273 deliberately design different pieces of data which have the same MD5
4274 hash), so you should not used it for anything security-related. A
4275 similar theoretical weakness also exists in SHA-1. Therefore, for
4276 security-related applications you should use the other hash types,
4279 @defun secure-hash algorithm object &optional start end binary
4280 This function returns a hash for @var{object}. The argument
4281 @var{algorithm} is a symbol stating which hash to compute: one of
4282 @code{md5}, @code{sha1}, @code{sha224}, @code{sha256}, @code{sha384}
4283 or @code{sha512}. The argument @var{object} should be a buffer or a
4286 The optional arguments @var{start} and @var{end} are character
4287 positions specifying the portion of @var{object} to compute the
4288 message digest for. If they are @code{nil} or omitted, the hash is
4289 computed for the whole of @var{object}.
4291 If the argument @var{binary} is omitted or @code{nil}, the function
4292 returns the @dfn{text form} of the hash, as an ordinary Lisp string.
4293 If @var{binary} is non-@code{nil}, it returns the hash in @dfn{binary
4294 form}, as a sequence of bytes stored in a unibyte string.
4296 This function does not compute the hash directly from the internal
4297 representation of @var{object}'s text (@pxref{Text Representations}).
4298 Instead, it encodes the text using a coding system (@pxref{Coding
4299 Systems}), and computes the hash from that encoded text. If
4300 @var{object} is a buffer, the coding system used is the one which
4301 would be chosen by default for writing the text into a file. If
4302 @var{object} is a string, the user's preferred coding system is used
4303 (@pxref{Recognize Coding,,, emacs, GNU Emacs Manual}).
4306 @defun md5 object &optional start end coding-system noerror
4307 This function returns an MD5 hash. It is semi-obsolete, since for
4308 most purposes it is equivalent to calling @code{secure-hash} with
4309 @code{md5} as the @var{algorithm} argument. The @var{object},
4310 @var{start} and @var{end} arguments have the same meanings as in
4313 If @var{coding-system} is non-@code{nil}, it specifies a coding system
4314 to use to encode the text; if omitted or @code{nil}, the default
4315 coding system is used, like in @code{secure-hash}.
4317 Normally, @code{md5} signals an error if the text can't be encoded
4318 using the specified or chosen coding system. However, if
4319 @var{noerror} is non-@code{nil}, it silently uses @code{raw-text}
4323 @node Parsing HTML/XML
4324 @section Parsing HTML and XML
4325 @cindex parsing html
4327 When Emacs is compiled with libxml2 support, the following functions
4328 are available to parse HTML or XML text into Lisp object trees.
4330 @defun libxml-parse-html-region start end &optional base-url
4331 This function parses the text between @var{start} and @var{end} as
4332 HTML, and returns a list representing the HTML @dfn{parse tree}. It
4333 attempts to handle ``real world'' HTML by robustly coping with syntax
4336 The optional argument @var{base-url}, if non-@code{nil}, should be a
4337 string specifying the base URL for relative URLs occurring in links.
4339 In the parse tree, each HTML node is represented by a list in which
4340 the first element is a symbol representing the node name, the second
4341 element is an alist of node attributes, and the remaining elements are
4344 The following example demonstrates this. Given this (malformed) HTML
4348 <html><head></head><body width=101><div class=thing>Foo<div>Yes
4352 A call to @code{libxml-parse-html-region} returns this:
4357 (body ((width . "101"))
4358 (div ((class . "thing"))
4365 @cindex rendering html
4366 @defun shr-insert-document dom
4367 This function renders the parsed HTML in @var{dom} into the current
4368 buffer. The argument @var{dom} should be a list as generated by
4369 @code{libxml-parse-html-region}. This function is, e.g., used by
4370 @ref{Top, EWW,, eww, The Emacs Web Wowser Manual}.
4374 @defun libxml-parse-xml-region start end &optional base-url
4375 This function is the same as @code{libxml-parse-html-region}, except
4376 that it parses the text as XML rather than HTML (so it is stricter
4380 @node Atomic Changes
4381 @section Atomic Change Groups
4382 @cindex atomic changes
4384 In database terminology, an @dfn{atomic} change is an indivisible
4385 change---it can succeed entirely or it can fail entirely, but it
4386 cannot partly succeed. A Lisp program can make a series of changes to
4387 one or several buffers as an @dfn{atomic change group}, meaning that
4388 either the entire series of changes will be installed in their buffers
4389 or, in case of an error, none of them will be.
4391 To do this for one buffer, the one already current, simply write a
4392 call to @code{atomic-change-group} around the code that makes the
4396 (atomic-change-group
4398 (delete-region x y))
4402 If an error (or other nonlocal exit) occurs inside the body of
4403 @code{atomic-change-group}, it unmakes all the changes in that buffer
4404 that were during the execution of the body. This kind of change group
4405 has no effect on any other buffers---any such changes remain.
4407 If you need something more sophisticated, such as to make changes in
4408 various buffers constitute one atomic group, you must directly call
4409 lower-level functions that @code{atomic-change-group} uses.
4411 @defun prepare-change-group &optional buffer
4412 This function sets up a change group for buffer @var{buffer}, which
4413 defaults to the current buffer. It returns a ``handle'' that
4414 represents the change group. You must use this handle to activate the
4415 change group and subsequently to finish it.
4418 To use the change group, you must @dfn{activate} it. You must do
4419 this before making any changes in the text of @var{buffer}.
4421 @defun activate-change-group handle
4422 This function activates the change group that @var{handle} designates.
4425 After you activate the change group, any changes you make in that
4426 buffer become part of it. Once you have made all the desired changes
4427 in the buffer, you must @dfn{finish} the change group. There are two
4428 ways to do this: you can either accept (and finalize) all the changes,
4431 @defun accept-change-group handle
4432 This function accepts all the changes in the change group specified by
4433 @var{handle}, making them final.
4436 @defun cancel-change-group handle
4437 This function cancels and undoes all the changes in the change group
4438 specified by @var{handle}.
4441 Your code should use @code{unwind-protect} to make sure the group is
4442 always finished. The call to @code{activate-change-group} should be
4443 inside the @code{unwind-protect}, in case the user types @kbd{C-g}
4444 just after it runs. (This is one reason why
4445 @code{prepare-change-group} and @code{activate-change-group} are
4446 separate functions, because normally you would call
4447 @code{prepare-change-group} before the start of that
4448 @code{unwind-protect}.) Once you finish the group, don't use the
4449 handle again---in particular, don't try to finish the same group
4452 To make a multibuffer change group, call @code{prepare-change-group}
4453 once for each buffer you want to cover, then use @code{nconc} to
4454 combine the returned values, like this:
4457 (nconc (prepare-change-group buffer-1)
4458 (prepare-change-group buffer-2))
4461 You can then activate the multibuffer change group with a single call
4462 to @code{activate-change-group}, and finish it with a single call to
4463 @code{accept-change-group} or @code{cancel-change-group}.
4465 Nested use of several change groups for the same buffer works as you
4466 would expect. Non-nested use of change groups for the same buffer
4467 will get Emacs confused, so don't let it happen; the first change
4468 group you start for any given buffer should be the last one finished.
4471 @section Change Hooks
4472 @cindex change hooks
4473 @cindex hooks for text changes
4475 These hook variables let you arrange to take notice of all changes in
4476 all buffers (or in a particular buffer, if you make them buffer-local).
4477 See also @ref{Special Properties}, for how to detect changes to specific
4480 The functions you use in these hooks should save and restore the match
4481 data if they do anything that uses regular expressions; otherwise, they
4482 will interfere in bizarre ways with the editing operations that call
4485 @defvar before-change-functions
4486 This variable holds a list of functions to call before any buffer
4487 modification. Each function gets two arguments, the beginning and end
4488 of the region that is about to change, represented as integers. The
4489 buffer that is about to change is always the current buffer.
4492 @defvar after-change-functions
4493 This variable holds a list of functions to call after any buffer
4494 modification. Each function receives three arguments: the beginning
4495 and end of the region just changed, and the length of the text that
4496 existed before the change. All three arguments are integers. The
4497 buffer that has been changed is always the current buffer.
4499 The length of the old text is the difference between the buffer
4500 positions before and after that text as it was before the change. As
4501 for the changed text, its length is simply the difference between the
4502 first two arguments.
4505 Output of messages into the @file{*Messages*} buffer does not
4506 call these functions.
4508 @defmac combine-after-change-calls body@dots{}
4509 The macro executes @var{body} normally, but arranges to call the
4510 after-change functions just once for a series of several changes---if
4513 If a program makes several text changes in the same area of the buffer,
4514 using the macro @code{combine-after-change-calls} around that part of
4515 the program can make it run considerably faster when after-change hooks
4516 are in use. When the after-change hooks are ultimately called, the
4517 arguments specify a portion of the buffer including all of the changes
4518 made within the @code{combine-after-change-calls} body.
4520 @strong{Warning:} You must not alter the values of
4521 @code{after-change-functions} within
4522 the body of a @code{combine-after-change-calls} form.
4524 @strong{Warning:} if the changes you combine occur in widely scattered
4525 parts of the buffer, this will still work, but it is not advisable,
4526 because it may lead to inefficient behavior for some change hook
4530 @defvar first-change-hook
4531 This variable is a normal hook that is run whenever a buffer is changed
4532 that was previously in the unmodified state.
4535 @defvar inhibit-modification-hooks
4536 If this variable is non-@code{nil}, all of the change hooks are
4537 disabled; none of them run. This affects all the hook variables
4538 described above in this section, as well as the hooks attached to
4539 certain special text properties (@pxref{Special Properties}) and overlay
4540 properties (@pxref{Overlay Properties}).
4542 Also, this variable is bound to non-@code{nil} while running those
4543 same hook variables, so that by default modifying the buffer from
4544 a modification hook does not cause other modification hooks to be run.
4545 If you do want modification hooks to be run in a particular piece of
4546 code that is itself run from a modification hook, then rebind locally
4547 @code{inhibit-modification-hooks} to @code{nil}.