2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../../info/text
6 @node Text, Non-ASCII Characters, Markers, Top
10 This chapter describes the functions that deal with the text in a
11 buffer. Most examine, insert, or delete text in the current buffer,
12 often operating at point or on text adjacent to point. Many are
13 interactive. All the functions that change the text provide for undoing
14 the changes (@pxref{Undo}).
16 Many text-related functions operate on a region of text defined by two
17 buffer positions passed in arguments named @var{start} and @var{end}.
18 These arguments should be either markers (@pxref{Markers}) or numeric
19 character positions (@pxref{Positions}). The order of these arguments
20 does not matter; it is all right for @var{start} to be the end of the
21 region and @var{end} the beginning. For example, @code{(delete-region 1
22 10)} and @code{(delete-region 10 1)} are equivalent. An
23 @code{args-out-of-range} error is signaled if either @var{start} or
24 @var{end} is outside the accessible portion of the buffer. In an
25 interactive call, point and the mark are used for these arguments.
27 @cindex buffer contents
28 Throughout this chapter, ``text'' refers to the characters in the
29 buffer, together with their properties (when relevant). Keep in mind
30 that point is always between two characters, and the cursor appears on
31 the character after point.
34 * Near Point:: Examining text in the vicinity of point.
35 * Buffer Contents:: Examining text in a general fashion.
36 * Comparing Text:: Comparing substrings of buffers.
37 * Insertion:: Adding new text to a buffer.
38 * Commands for Insertion:: User-level commands to insert text.
39 * Deletion:: Removing text from a buffer.
40 * User-Level Deletion:: User-level commands to delete text.
41 * The Kill Ring:: Where removed text sometimes is saved for later use.
42 * Undo:: Undoing changes to the text of a buffer.
43 * Maintaining Undo:: How to enable and disable undo information.
44 How to control how much information is kept.
45 * Filling:: Functions for explicit filling.
46 * Margins:: How to specify margins for filling commands.
47 * Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context.
48 * Auto Filling:: How auto-fill mode is implemented to break lines.
49 * Sorting:: Functions for sorting parts of the buffer.
50 * Columns:: Computing horizontal positions, and using them.
51 * Indentation:: Functions to insert or adjust indentation.
52 * Case Changes:: Case conversion of parts of the buffer.
53 * Text Properties:: Assigning Lisp property lists to text characters.
54 * Substitution:: Replacing a given character wherever it appears.
55 * Transposition:: Swapping two portions of a buffer.
56 * Registers:: How registers are implemented. Accessing the text or
57 position stored in a register.
58 * Base 64:: Conversion to or from base 64 encoding.
59 * Checksum/Hash:: Computing "message digests"/"checksums"/"hashes".
60 * Parsing HTML:: 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
166 This section describes functions that allow a Lisp program to
167 convert any portion of the text in the buffer into a string.
169 @defun buffer-substring start end
170 This function returns a string containing a copy of the text of the
171 region defined by positions @var{start} and @var{end} in the current
172 buffer. If the arguments are not positions in the accessible portion of
173 the buffer, @code{buffer-substring} signals an @code{args-out-of-range}
176 It is not necessary for @var{start} to be less than @var{end}; the
177 arguments can be given in either order. But most often the smaller
178 argument is written first.
180 Here's an example which assumes Font-Lock mode is not enabled:
184 ---------- Buffer: foo ----------
185 This is the contents of buffer foo
187 ---------- Buffer: foo ----------
191 (buffer-substring 1 10)
192 @result{} "This is t"
195 (buffer-substring (point-max) 10)
196 @result{} "he contents of buffer foo\n"
200 If the text being copied has any text properties, these are copied into
201 the string along with the characters they belong to. @xref{Text
202 Properties}. However, overlays (@pxref{Overlays}) in the buffer and
203 their properties are ignored, not copied.
205 For example, if Font-Lock mode is enabled, you might get results like
210 (buffer-substring 1 10)
211 @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t))
216 @defun buffer-substring-no-properties start end
217 This is like @code{buffer-substring}, except that it does not copy text
218 properties, just the characters themselves. @xref{Text Properties}.
221 @defun filter-buffer-substring start end &optional delete
222 This function passes the buffer text between @var{start} and @var{end}
223 through the filter functions specified by the wrapper hook
224 @code{filter-buffer-substring-functions}, and returns the final
225 result of applying all filters. The obsolete variable
226 @code{buffer-substring-filters} is also consulted. If both of these
227 variables are @code{nil}, the value is the unaltered text from the
228 buffer, as @code{buffer-substring} would return.
230 If @var{delete} is non-@code{nil}, this function deletes the text
231 between @var{start} and @var{end} after copying it, like
232 @code{delete-and-extract-region}.
234 Lisp code should use this function instead of @code{buffer-substring},
235 @code{buffer-substring-no-properties},
236 or @code{delete-and-extract-region} when copying into user-accessible
237 data structures such as the kill-ring, X clipboard, and registers.
238 Major and minor modes can add functions to
239 @code{filter-buffer-substring-functions} to alter such text as it is
240 copied out of the buffer.
243 @defvar filter-buffer-substring-functions
244 This variable is a wrapper hook (@pxref{Running Hooks}), whose members
245 should be functions that accept four arguments: @var{fun},
246 @var{start}, @var{end}, and @var{delete}. @var{fun} is a function
247 that takes three arguments (@var{start}, @var{end}, and @var{delete}),
248 and returns a string. In both cases, the @var{start}, @var{end}, and
249 @var{delete} arguments are the same as those of
250 @code{filter-buffer-substring}.
252 The first hook function is passed a @var{fun} that is equivalent to
253 the default operation of @code{filter-buffer-substring}, i.e. it
254 returns the buffer-substring between @var{start} and @var{end}
255 (processed by any @code{buffer-substring-filters}) and optionally
256 deletes the original text from the buffer. In most cases, the hook
257 function will call @var{fun} once, and then do its own processing of
258 the result. The next hook function receives a @var{fun} equivalent to
259 this, and so on. The actual return value is the result of all the
260 hook functions acting in sequence.
264 This function returns the contents of the entire accessible portion of
265 the current buffer as a string. It is equivalent to
268 (buffer-substring (point-min) (point-max))
273 ---------- Buffer: foo ----------
274 This is the contents of buffer foo
276 ---------- Buffer: foo ----------
279 @result{} "This is the contents of buffer foo\n"
284 @defun current-word &optional strict really-word
285 This function returns the symbol (or word) at or near point, as a string.
286 The return value includes no text properties.
288 If the optional argument @var{really-word} is non-@code{nil}, it finds a
289 word; otherwise, it finds a symbol (which includes both word
290 characters and symbol constituent characters).
292 If the optional argument @var{strict} is non-@code{nil}, then point
293 must be in or next to the symbol or word---if no symbol or word is
294 there, the function returns @code{nil}. Otherwise, a nearby symbol or
295 word on the same line is acceptable.
298 @defun thing-at-point thing
299 Return the @var{thing} around or next to point, as a string.
301 The argument @var{thing} is a symbol which specifies a kind of syntactic
302 entity. Possibilities include @code{symbol}, @code{list}, @code{sexp},
303 @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
304 @code{whitespace}, @code{line}, @code{page}, and others.
307 ---------- Buffer: foo ----------
308 Gentlemen may cry ``Pea@point{}ce! Peace!,''
309 but there is no peace.
310 ---------- Buffer: foo ----------
312 (thing-at-point 'word)
314 (thing-at-point 'line)
315 @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
316 (thing-at-point 'whitespace)
322 @section Comparing Text
323 @cindex comparing buffer text
325 This function lets you compare portions of the text in a buffer, without
326 copying them into strings first.
328 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
329 This function lets you compare two substrings of the same buffer or two
330 different buffers. The first three arguments specify one substring,
331 giving a buffer (or a buffer name) and two positions within the
332 buffer. The last three arguments specify the other substring in the
333 same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or
334 both to stand for the current buffer.
336 The value is negative if the first substring is less, positive if the
337 first is greater, and zero if they are equal. The absolute value of
338 the result is one plus the index of the first differing characters
339 within the substrings.
341 This function ignores case when comparing characters
342 if @code{case-fold-search} is non-@code{nil}. It always ignores
345 Suppose the current buffer contains the text @samp{foobarbar
346 haha!rara!}; then in this example the two substrings are @samp{rbar }
347 and @samp{rara!}. The value is 2 because the first substring is greater
348 at the second character.
351 (compare-buffer-substrings nil 6 11 nil 16 21)
357 @section Inserting Text
358 @cindex insertion of text
359 @cindex text insertion
361 @cindex insertion before point
362 @cindex before point, insertion
363 @dfn{Insertion} means adding new text to a buffer. The inserted text
364 goes at point---between the character before point and the character
365 after point. Some insertion functions leave point before the inserted
366 text, while other functions leave it after. We call the former
367 insertion @dfn{after point} and the latter insertion @dfn{before point}.
369 Insertion moves markers located at positions after the insertion
370 point, so that they stay with the surrounding text (@pxref{Markers}).
371 When a marker points at the place of insertion, insertion may or may
372 not relocate the marker, depending on the marker's insertion type
373 (@pxref{Marker Insertion Types}). Certain special functions such as
374 @code{insert-before-markers} relocate all such markers to point after
375 the inserted text, regardless of the markers' insertion type.
377 Insertion functions signal an error if the current buffer is
378 read-only or if they insert within read-only text.
380 These functions copy text characters from strings and buffers along
381 with their properties. The inserted characters have exactly the same
382 properties as the characters they were copied from. By contrast,
383 characters specified as separate arguments, not part of a string or
384 buffer, inherit their text properties from the neighboring text.
386 The insertion functions convert text from unibyte to multibyte in
387 order to insert in a multibyte buffer, and vice versa---if the text
388 comes from a string or from a buffer. However, they do not convert
389 unibyte character codes 128 through 255 to multibyte characters, not
390 even if the current buffer is a multibyte buffer. @xref{Converting
393 @defun insert &rest args
394 This function inserts the strings and/or characters @var{args} into the
395 current buffer, at point, moving point forward. In other words, it
396 inserts the text before point. An error is signaled unless all
397 @var{args} are either strings or characters. The value is @code{nil}.
400 @defun insert-before-markers &rest args
401 This function inserts the strings and/or characters @var{args} into the
402 current buffer, at point, moving point forward. An error is signaled
403 unless all @var{args} are either strings or characters. The value is
406 This function is unlike the other insertion functions in that it
407 relocates markers initially pointing at the insertion point, to point
408 after the inserted text. If an overlay begins at the insertion point,
409 the inserted text falls outside the overlay; if a nonempty overlay
410 ends at the insertion point, the inserted text falls inside that
414 @defun insert-char character count &optional inherit
415 This function inserts @var{count} instances of @var{character} into the
416 current buffer before point. The argument @var{count} should be an
417 integer, and @var{character} must be a character. The value is @code{nil}.
419 This function does not convert unibyte character codes 128 through 255
420 to multibyte characters, not even if the current buffer is a multibyte
421 buffer. @xref{Converting Representations}.
423 If @var{inherit} is non-@code{nil}, then the inserted characters inherit
424 sticky text properties from the two characters before and after the
425 insertion point. @xref{Sticky Properties}.
428 @defun insert-buffer-substring from-buffer-or-name &optional start end
429 This function inserts a portion of buffer @var{from-buffer-or-name}
430 (which must already exist) into the current buffer before point. The
431 text inserted is the region between @var{start} and @var{end}. (These
432 arguments default to the beginning and end of the accessible portion of
433 that buffer.) This function returns @code{nil}.
435 In this example, the form is executed with buffer @samp{bar} as the
436 current buffer. We assume that buffer @samp{bar} is initially empty.
440 ---------- Buffer: foo ----------
441 We hold these truths to be self-evident, that all
442 ---------- Buffer: foo ----------
446 (insert-buffer-substring "foo" 1 20)
449 ---------- Buffer: bar ----------
450 We hold these truth@point{}
451 ---------- Buffer: bar ----------
456 @defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
457 This is like @code{insert-buffer-substring} except that it does not
458 copy any text properties.
461 @xref{Sticky Properties}, for other insertion functions that inherit
462 text properties from the nearby text in addition to inserting it.
463 Whitespace inserted by indentation functions also inherits text
466 @node Commands for Insertion
467 @section User-Level Insertion Commands
469 This section describes higher-level commands for inserting text,
470 commands intended primarily for the user but useful also in Lisp
473 @deffn Command insert-buffer from-buffer-or-name
474 This command inserts the entire accessible contents of
475 @var{from-buffer-or-name} (which must exist) into the current buffer
476 after point. It leaves the mark after the inserted text. The value
480 @deffn Command self-insert-command count
481 @cindex character insertion
482 @cindex self-insertion
483 This command inserts the last character typed; it does so @var{count}
484 times, before point, and returns @code{nil}. Most printing characters
485 are bound to this command. In routine use, @code{self-insert-command}
486 is the most frequently called function in Emacs, but programs rarely use
487 it except to install it on a keymap.
489 In an interactive call, @var{count} is the numeric prefix argument.
491 Self-insertion translates the input character through
492 @code{translation-table-for-input}. @xref{Translation of Characters}.
494 This command calls @code{auto-fill-function} whenever that is
495 non-@code{nil} and the character inserted is in the table
496 @code{auto-fill-chars} (@pxref{Auto Filling}).
498 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
499 This command performs abbrev expansion if Abbrev mode is enabled and
500 the inserted character does not have word-constituent
501 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also
502 responsible for calling @code{blink-paren-function} when the inserted
503 character has close parenthesis syntax (@pxref{Blinking}).
505 @vindex post-self-insert-hook
506 The final thing this command does is to run the hook
507 @code{post-self-insert-hook}. You could use this to automatically
508 reindent text as it is typed, for example.
510 Do not try substituting your own definition of
511 @code{self-insert-command} for the standard one. The editor command
512 loop handles this function specially.
515 @deffn Command newline &optional number-of-newlines
516 This command inserts newlines into the current buffer before point.
517 If @var{number-of-newlines} is supplied, that many newline characters
520 @cindex newline and Auto Fill mode
521 This function calls @code{auto-fill-function} if the current column
522 number is greater than the value of @code{fill-column} and
523 @var{number-of-newlines} is @code{nil}. Typically what
524 @code{auto-fill-function} does is insert a newline; thus, the overall
525 result in this case is to insert two newlines at different places: one
526 at point, and another earlier in the line. @code{newline} does not
527 auto-fill if @var{number-of-newlines} is non-@code{nil}.
529 This command indents to the left margin if that is not zero.
532 The value returned is @code{nil}. In an interactive call, @var{count}
533 is the numeric prefix argument.
536 @defvar overwrite-mode
537 This variable controls whether overwrite mode is in effect. The value
538 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
539 or @code{nil}. @code{overwrite-mode-textual} specifies textual
540 overwrite mode (treats newlines and tabs specially), and
541 @code{overwrite-mode-binary} specifies binary overwrite mode (treats
542 newlines and tabs like any other characters).
546 @section Deleting Text
547 @cindex text deletion
549 @cindex deleting text vs killing
550 Deletion means removing part of the text in a buffer, without saving
551 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
552 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
553 Some deletion functions do save text in the kill ring in some special
556 All of the deletion functions operate on the current buffer.
558 @deffn Command erase-buffer
559 This function deletes the entire text of the current buffer
560 (@emph{not} just the accessible portion), leaving it
561 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
562 error; if some of the text in it is read-only, it signals a
563 @code{text-read-only} error. Otherwise, it deletes the text without
564 asking for any confirmation. It returns @code{nil}.
566 Normally, deleting a large amount of text from a buffer inhibits further
567 auto-saving of that buffer ``because it has shrunk.'' However,
568 @code{erase-buffer} does not do this, the idea being that the future
569 text is not really related to the former text, and its size should not
570 be compared with that of the former text.
573 @deffn Command delete-region start end
574 This command deletes the text between positions @var{start} and
575 @var{end} in the current buffer, and returns @code{nil}. If point was
576 inside the deleted region, its value afterward is @var{start}.
577 Otherwise, point relocates with the surrounding text, as markers do.
580 @defun delete-and-extract-region start end
581 This function deletes the text between positions @var{start} and
582 @var{end} in the current buffer, and returns a string containing the
585 If point was inside the deleted region, its value afterward is
586 @var{start}. Otherwise, point relocates with the surrounding text, as
590 @deffn Command delete-char count &optional killp
591 This command deletes @var{count} characters directly after point, or
592 before point if @var{count} is negative. If @var{killp} is
593 non-@code{nil}, then it saves the deleted characters in the kill ring.
595 In an interactive call, @var{count} is the numeric prefix argument, and
596 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
597 argument is supplied, the text is saved in the kill ring. If no prefix
598 argument is supplied, then one character is deleted, but not saved in
601 The value returned is always @code{nil}.
604 @deffn Command delete-backward-char count &optional killp
605 @cindex deleting previous char
606 This command deletes @var{count} characters directly before point, or
607 after point if @var{count} is negative. If @var{killp} is
608 non-@code{nil}, then it saves the deleted characters in the kill ring.
610 In an interactive call, @var{count} is the numeric prefix argument, and
611 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
612 argument is supplied, the text is saved in the kill ring. If no prefix
613 argument is supplied, then one character is deleted, but not saved in
616 The value returned is always @code{nil}.
619 @deffn Command backward-delete-char-untabify count &optional killp
621 This command deletes @var{count} characters backward, changing tabs
622 into spaces. When the next character to be deleted is a tab, it is
623 first replaced with the proper number of spaces to preserve alignment
624 and then one of those spaces is deleted instead of the tab. If
625 @var{killp} is non-@code{nil}, then the command saves the deleted
626 characters in the kill ring.
628 Conversion of tabs to spaces happens only if @var{count} is positive.
629 If it is negative, exactly @minus{}@var{count} characters after point
632 In an interactive call, @var{count} is the numeric prefix argument, and
633 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
634 argument is supplied, the text is saved in the kill ring. If no prefix
635 argument is supplied, then one character is deleted, but not saved in
638 The value returned is always @code{nil}.
641 @defopt backward-delete-char-untabify-method
642 This option specifies how @code{backward-delete-char-untabify} should
643 deal with whitespace. Possible values include @code{untabify}, the
644 default, meaning convert a tab to many spaces and delete one;
645 @code{hungry}, meaning delete all tabs and spaces before point with
646 one command; @code{all} meaning delete all tabs, spaces and newlines
647 before point, and @code{nil}, meaning do nothing special for
648 whitespace characters.
651 @node User-Level Deletion
652 @section User-Level Deletion Commands
654 This section describes higher-level commands for deleting text,
655 commands intended primarily for the user but useful also in Lisp
658 @deffn Command delete-horizontal-space &optional backward-only
659 @cindex deleting whitespace
660 This function deletes all spaces and tabs around point. It returns
663 If @var{backward-only} is non-@code{nil}, the function deletes
664 spaces and tabs before point, but not after point.
666 In the following examples, we call @code{delete-horizontal-space} four
667 times, once on each line, with point between the second and third
668 characters on the line each time.
672 ---------- Buffer: foo ----------
677 ---------- Buffer: foo ----------
681 (delete-horizontal-space) ; @r{Four times.}
684 ---------- Buffer: foo ----------
689 ---------- Buffer: foo ----------
694 @deffn Command delete-indentation &optional join-following-p
695 This function joins the line point is on to the previous line, deleting
696 any whitespace at the join and in some cases replacing it with one
697 space. If @var{join-following-p} is non-@code{nil},
698 @code{delete-indentation} joins this line to the following line
699 instead. The function returns @code{nil}.
701 If there is a fill prefix, and the second of the lines being joined
702 starts with the prefix, then @code{delete-indentation} deletes the
703 fill prefix before joining the lines. @xref{Margins}.
705 In the example below, point is located on the line starting
706 @samp{events}, and it makes no difference if there are trailing spaces
707 in the preceding line.
711 ---------- Buffer: foo ----------
712 When in the course of human
713 @point{} events, it becomes necessary
714 ---------- Buffer: foo ----------
721 ---------- Buffer: foo ----------
722 When in the course of human@point{} events, it becomes necessary
723 ---------- Buffer: foo ----------
727 After the lines are joined, the function @code{fixup-whitespace} is
728 responsible for deciding whether to leave a space at the junction.
731 @deffn Command fixup-whitespace
732 This function replaces all the horizontal whitespace surrounding point
733 with either one space or no space, according to the context. It
736 At the beginning or end of a line, the appropriate amount of space is
737 none. Before a character with close parenthesis syntax, or after a
738 character with open parenthesis or expression-prefix syntax, no space is
739 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
742 In the example below, @code{fixup-whitespace} is called the first time
743 with point before the word @samp{spaces} in the first line. For the
744 second invocation, point is directly after the @samp{(}.
748 ---------- Buffer: foo ----------
749 This has too many @point{}spaces
750 This has too many spaces at the start of (@point{} this list)
751 ---------- Buffer: foo ----------
762 ---------- Buffer: foo ----------
763 This has too many spaces
764 This has too many spaces at the start of (this list)
765 ---------- Buffer: foo ----------
770 @deffn Command just-one-space &optional n
771 @comment !!SourceFile simple.el
772 This command replaces any spaces and tabs around point with a single
773 space, or @var{n} spaces if @var{n} is specified. It returns
777 @deffn Command delete-blank-lines
778 This function deletes blank lines surrounding point. If point is on a
779 blank line with one or more blank lines before or after it, then all but
780 one of them are deleted. If point is on an isolated blank line, then it
781 is deleted. If point is on a nonblank line, the command deletes all
782 blank lines immediately following it.
784 A blank line is defined as a line containing only tabs and spaces.
786 @code{delete-blank-lines} returns @code{nil}.
790 @section The Kill Ring
793 @dfn{Kill functions} delete text like the deletion functions, but save
794 it so that the user can reinsert it by @dfn{yanking}. Most of these
795 functions have @samp{kill-} in their name. By contrast, the functions
796 whose names start with @samp{delete-} normally do not save text for
797 yanking (though they can still be undone); these are ``deletion''
800 Most of the kill commands are primarily for interactive use, and are
801 not described here. What we do describe are the functions provided for
802 use in writing such commands. You can use these functions to write
803 commands for killing text. When you need to delete text for internal
804 purposes within a Lisp function, you should normally use deletion
805 functions, so as not to disturb the kill ring contents.
808 Killed text is saved for later yanking in the @dfn{kill ring}. This
809 is a list that holds a number of recent kills, not just the last text
810 kill. We call this a ``ring'' because yanking treats it as having
811 elements in a cyclic order. The list is kept in the variable
812 @code{kill-ring}, and can be operated on with the usual functions for
813 lists; there are also specialized functions, described in this section,
814 that treat it as a ring.
816 Some people think this use of the word ``kill'' is unfortunate, since
817 it refers to operations that specifically @emph{do not} destroy the
818 entities ``killed.'' This is in sharp contrast to ordinary life, in
819 which death is permanent and ``killed'' entities do not come back to
820 life. Therefore, other metaphors have been proposed. For example, the
821 term ``cut ring'' makes sense to people who, in pre-computer days, used
822 scissors and paste to cut up and rearrange manuscripts. However, it
823 would be difficult to change the terminology now.
826 * Kill Ring Concepts:: What text looks like in the kill ring.
827 * Kill Functions:: Functions that kill text.
828 * Yanking:: How yanking is done.
829 * Yank Commands:: Commands that access the kill ring.
830 * Low-Level Kill Ring:: Functions and variables for kill ring access.
831 * Internals of Kill Ring:: Variables that hold kill ring data.
834 @node Kill Ring Concepts
835 @comment node-name, next, previous, up
836 @subsection Kill Ring Concepts
838 The kill ring records killed text as strings in a list, most recent
839 first. A short kill ring, for example, might look like this:
842 ("some text" "a different piece of text" "even older text")
846 When the list reaches @code{kill-ring-max} entries in length, adding a
847 new entry automatically deletes the last entry.
849 When kill commands are interwoven with other commands, each kill
850 command makes a new entry in the kill ring. Multiple kill commands in
851 succession build up a single kill ring entry, which would be yanked as a
852 unit; the second and subsequent consecutive kill commands add text to
853 the entry made by the first one.
855 For yanking, one entry in the kill ring is designated the ``front'' of
856 the ring. Some yank commands ``rotate'' the ring by designating a
857 different element as the ``front.'' But this virtual rotation doesn't
858 change the list itself---the most recent entry always comes first in the
862 @comment node-name, next, previous, up
863 @subsection Functions for Killing
865 @code{kill-region} is the usual subroutine for killing text. Any
866 command that calls this function is a ``kill command'' (and should
867 probably have @samp{kill} in its name). @code{kill-region} puts the
868 newly killed text in a new element at the beginning of the kill ring or
869 adds it to the most recent element. It determines automatically (using
870 @code{last-command}) whether the previous command was a kill command,
871 and if so appends the killed text to the most recent entry.
873 @deffn Command kill-region start end
874 This function kills the text in the region defined by @var{start} and
875 @var{end}. The text is deleted but saved in the kill ring, along with
876 its text properties. The value is always @code{nil}.
878 In an interactive call, @var{start} and @var{end} are point and
881 If the buffer or text is read-only, @code{kill-region} modifies the kill
882 ring just the same, then signals an error without modifying the buffer.
883 This is convenient because it lets the user use a series of kill
884 commands to copy text from a read-only buffer into the kill ring.
887 @defopt kill-read-only-ok
888 If this option is non-@code{nil}, @code{kill-region} does not signal an
889 error if the buffer or text is read-only. Instead, it simply returns,
890 updating the kill ring but not changing the buffer.
893 @deffn Command copy-region-as-kill start end
894 This command saves the region defined by @var{start} and @var{end} on
895 the kill ring (including text properties), but does not delete the text
896 from the buffer. It returns @code{nil}.
898 The command does not set @code{this-command} to @code{kill-region}, so a
899 subsequent kill command does not append to the same kill ring entry.
901 @c FIXME Why is it better? Why isn't copy-region-as-kill obsolete then?
902 @c Why is it used in many places in Emacs?
903 In Lisp programs, it is better to use @code{kill-new} or
904 @code{kill-append} instead of this command. @xref{Low-Level Kill Ring}.
910 Yanking means inserting text from the kill ring, but it does
911 not insert the text blindly. Yank commands and some other commands
912 use @code{insert-for-yank} to perform special processing on the
913 text that they copy into the buffer.
915 @defun insert-for-yank string
916 This function normally works like @code{insert} except that it doesn't
917 insert the text properties (@pxref{Text Properties}) in the list
918 variable @code{yank-excluded-properties}. However, if any part of
919 @var{string} has a non-@code{nil} @code{yank-handler} text property,
920 that property can do various special processing on that part of the
924 @defun insert-buffer-substring-as-yank buf &optional start end
925 This function resembles @code{insert-buffer-substring} except that it
926 doesn't insert the text properties in the
927 @code{yank-excluded-properties} list.
930 You can put a @code{yank-handler} text property on all or part of
931 the text to control how it will be inserted if it is yanked. The
932 @code{insert-for-yank} function looks for that property. The property
933 value must be a list of one to four elements, with the following
934 format (where elements after the first may be omitted):
937 (@var{function} @var{param} @var{noexclude} @var{undo})
940 Here is what the elements do:
944 When @var{function} is present and non-@code{nil}, it is called instead of
945 @code{insert} to insert the string. @var{function} takes one
946 argument---the string to insert.
949 If @var{param} is present and non-@code{nil}, it replaces @var{string}
950 (or the part of @var{string} being processed) as the object passed to
951 @var{function} (or @code{insert}); for example, if @var{function} is
952 @code{yank-rectangle}, @var{param} should be a list of strings to
953 insert as a rectangle.
956 If @var{noexclude} is present and non-@code{nil}, the normal removal of the
957 yank-excluded-properties is not performed; instead @var{function} is
958 responsible for removing those properties. This may be necessary
959 if @var{function} adjusts point before or after inserting the object.
962 If @var{undo} is present and non-@code{nil}, it is a function that will be
963 called by @code{yank-pop} to undo the insertion of the current object.
964 It is called with two arguments, the start and end of the current
965 region. @var{function} can set @code{yank-undo-function} to override
966 the @var{undo} value.
969 @cindex yanking and text properties
970 @defopt yank-excluded-properties
971 Yanking discards certain text properties from the yanked text, as
972 described above. The value of this variable is the list of properties
973 to discard. Its default value contains properties that might lead to
974 annoying results, such as causing the text to respond to the mouse or
975 specifying key bindings.
979 @comment node-name, next, previous, up
980 @subsection Functions for Yanking
982 This section describes higher-level commands for yanking, which are
983 intended primarily for the user but useful also in Lisp programs.
984 Both @code{yank} and @code{yank-pop} honor the
985 @code{yank-excluded-properties} variable and @code{yank-handler} text
986 property (@pxref{Yanking}).
988 @deffn Command yank &optional arg
989 @cindex inserting killed text
990 This command inserts before point the text at the front of the kill
991 ring. It sets the mark at the beginning of that text, using
992 @code{push-mark} (@pxref{The Mark}), and puts point at the end.
994 If @var{arg} is a non-@code{nil} list (which occurs interactively when
995 the user types @kbd{C-u} with no digits), then @code{yank} inserts the
996 text as described above, but puts point before the yanked text and
997 sets the mark after it.
999 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th
1000 most recently killed text---the @var{arg}th element of the kill ring
1001 list, counted cyclically from the front, which is considered the
1002 first element for this purpose.
1004 @code{yank} does not alter the contents of the kill ring, unless it
1005 used text provided by another program, in which case it pushes that text
1006 onto the kill ring. However if @var{arg} is an integer different from
1007 one, it rotates the kill ring to place the yanked string at the front.
1009 @code{yank} returns @code{nil}.
1012 @deffn Command yank-pop &optional arg
1013 This command replaces the just-yanked entry from the kill ring with a
1014 different entry from the kill ring.
1016 This is allowed only immediately after a @code{yank} or another
1017 @code{yank-pop}. At such a time, the region contains text that was just
1018 inserted by yanking. @code{yank-pop} deletes that text and inserts in
1019 its place a different piece of killed text. It does not add the deleted
1020 text to the kill ring, since it is already in the kill ring somewhere.
1021 It does however rotate the kill ring to place the newly yanked string at
1024 If @var{arg} is @code{nil}, then the replacement text is the previous
1025 element of the kill ring. If @var{arg} is numeric, the replacement is
1026 the @var{arg}th previous kill. If @var{arg} is negative, a more recent
1027 kill is the replacement.
1029 The sequence of kills in the kill ring wraps around, so that after the
1030 oldest one comes the newest one, and before the newest one goes the
1033 The return value is always @code{nil}.
1036 @defvar yank-undo-function
1037 If this variable is non-@code{nil}, the function @code{yank-pop} uses
1038 its value instead of @code{delete-region} to delete the text
1039 inserted by the previous @code{yank} or
1040 @code{yank-pop} command. The value must be a function of two
1041 arguments, the start and end of the current region.
1043 The function @code{insert-for-yank} automatically sets this variable
1044 according to the @var{undo} element of the @code{yank-handler}
1045 text property, if there is one.
1048 @node Low-Level Kill Ring
1049 @subsection Low-Level Kill Ring
1051 These functions and variables provide access to the kill ring at a
1052 lower level, but are still convenient for use in Lisp programs,
1053 because they take care of interaction with window system selections
1054 (@pxref{Window System Selections}).
1056 @defun current-kill n &optional do-not-move
1057 The function @code{current-kill} rotates the yanking pointer, which
1058 designates the ``front'' of the kill ring, by @var{n} places (from newer
1059 kills to older ones), and returns the text at that place in the ring.
1061 If the optional second argument @var{do-not-move} is non-@code{nil},
1062 then @code{current-kill} doesn't alter the yanking pointer; it just
1063 returns the @var{n}th kill, counting from the current yanking pointer.
1065 If @var{n} is zero, indicating a request for the latest kill,
1066 @code{current-kill} calls the value of
1067 @code{interprogram-paste-function} (documented below) before
1068 consulting the kill ring. If that value is a function and calling it
1069 returns a string or a list of several string, @code{current-kill}
1070 pushes the strings onto the kill ring and returns the first string.
1071 It also sets the yanking pointer to point to the kill-ring entry of
1072 the first string returned by @code{interprogram-paste-function},
1073 regardless of the value of @var{do-not-move}. Otherwise,
1074 @code{current-kill} does not treat a zero value for @var{n} specially:
1075 it returns the entry pointed at by the yanking pointer and does not
1076 move the yanking pointer.
1079 @defun kill-new string &optional replace
1080 This function pushes the text @var{string} onto the kill ring and
1081 makes the yanking pointer point to it. It discards the oldest entry
1082 if appropriate. It also invokes the value of
1083 @code{interprogram-cut-function} (see below).
1085 If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the
1086 first element of the kill ring with @var{string}, rather than pushing
1087 @var{string} onto the kill ring.
1090 @defun kill-append string before-p
1091 This function appends the text @var{string} to the first entry in the
1092 kill ring and makes the yanking pointer point to the combined entry.
1093 Normally @var{string} goes at the end of the entry, but if
1094 @var{before-p} is non-@code{nil}, it goes at the beginning. This
1095 function also invokes the value of @code{interprogram-cut-function}
1099 @defvar interprogram-paste-function
1100 This variable provides a way of transferring killed text from other
1101 programs, when you are using a window system. Its value should be
1102 @code{nil} or a function of no arguments.
1104 If the value is a function, @code{current-kill} calls it to get the
1105 ``most recent kill.'' If the function returns a non-@code{nil} value,
1106 then that value is used as the ``most recent kill.'' If it returns
1107 @code{nil}, then the front of the kill ring is used.
1109 To facilitate support for window systems that support multiple
1110 selections, this function may also return a list of strings. In that
1111 case, the first string is used as the ``most recent kill'', and all
1112 the other strings are pushed onto the kill ring, for easy access by
1115 The normal use of this function is to get the window system's primary
1116 selection as the most recent kill, even if the selection belongs to
1117 another application. @xref{Window System Selections}. However, if
1118 the selection was provided by the current Emacs session, this function
1119 should return @code{nil}. (If it is hard to tell whether Emacs or
1120 some other program provided the selection, it should be good enough to
1121 use @code{string=} to compare it with the last text Emacs provided.)
1124 @defvar interprogram-cut-function
1125 This variable provides a way of communicating killed text to other
1126 programs, when you are using a window system. Its value should be
1127 @code{nil} or a function of one required argument.
1129 If the value is a function, @code{kill-new} and @code{kill-append} call
1130 it with the new first element of the kill ring as the argument.
1132 The normal use of this function is to set the window system's primary
1133 selection from the newly killed text.
1134 @xref{Window System Selections}.
1137 @node Internals of Kill Ring
1138 @comment node-name, next, previous, up
1139 @subsection Internals of the Kill Ring
1141 The variable @code{kill-ring} holds the kill ring contents, in the
1142 form of a list of strings. The most recent kill is always at the front
1145 The @code{kill-ring-yank-pointer} variable points to a link in the
1146 kill ring list, whose @sc{car} is the text to yank next. We say it
1147 identifies the ``front'' of the ring. Moving
1148 @code{kill-ring-yank-pointer} to a different link is called
1149 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
1150 the functions that move the yank pointer wrap around from the end of the
1151 list to the beginning, or vice-versa. Rotation of the kill ring is
1152 virtual; it does not change the value of @code{kill-ring}.
1154 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
1155 variables whose values are normally lists. The word ``pointer'' in the
1156 name of the @code{kill-ring-yank-pointer} indicates that the variable's
1157 purpose is to identify one element of the list for use by the next yank
1160 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
1161 of the links in the kill ring list. The element it identifies is the
1162 @sc{car} of that link. Kill commands, which change the kill ring, also
1163 set this variable to the value of @code{kill-ring}. The effect is to
1164 rotate the ring so that the newly killed text is at the front.
1166 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
1167 pointing to the second entry in the kill ring @code{("some text" "a
1168 different piece of text" "yet older text")}.
1172 kill-ring ---- kill-ring-yank-pointer
1175 | --- --- --- --- --- ---
1176 --> | | |------> | | |--> | | |--> nil
1177 --- --- --- --- --- ---
1180 | | -->"yet older text"
1182 | --> "a different piece of text"
1189 This state of affairs might occur after @kbd{C-y} (@code{yank})
1190 immediately followed by @kbd{M-y} (@code{yank-pop}).
1193 This variable holds the list of killed text sequences, most recently
1197 @defvar kill-ring-yank-pointer
1198 This variable's value indicates which element of the kill ring is at the
1199 ``front'' of the ring for yanking. More precisely, the value is a tail
1200 of the value of @code{kill-ring}, and its @sc{car} is the kill string
1201 that @kbd{C-y} should yank.
1204 @defopt kill-ring-max
1205 The value of this variable is the maximum length to which the kill
1206 ring can grow, before elements are thrown away at the end. The default
1207 value for @code{kill-ring-max} is 60.
1211 @comment node-name, next, previous, up
1215 Most buffers have an @dfn{undo list}, which records all changes made
1216 to the buffer's text so that they can be undone. (The buffers that
1217 don't have one are usually special-purpose buffers for which Emacs
1218 assumes that undoing is not useful. In particular, any buffer whose
1219 name begins with a space has its undo recording off by default;
1220 see @ref{Buffer Names}.) All the primitives that modify the
1221 text in the buffer automatically add elements to the front of the undo
1222 list, which is in the variable @code{buffer-undo-list}.
1224 @defvar buffer-undo-list
1225 This buffer-local variable's value is the undo list of the current
1226 buffer. A value of @code{t} disables the recording of undo information.
1229 Here are the kinds of elements an undo list can have:
1232 @item @var{position}
1233 This kind of element records a previous value of point; undoing this
1234 element moves point to @var{position}. Ordinary cursor motion does not
1235 make any sort of undo record, but deletion operations use these entries
1236 to record where point was before the command.
1238 @item (@var{beg} . @var{end})
1239 This kind of element indicates how to delete text that was inserted.
1240 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
1243 @item (@var{text} . @var{position})
1244 This kind of element indicates how to reinsert text that was deleted.
1245 The deleted text itself is the string @var{text}. The place to
1246 reinsert it is @code{(abs @var{position})}. If @var{position} is
1247 positive, point was at the beginning of the deleted text, otherwise it
1250 @item (t @var{high} . @var{low})
1251 This kind of element indicates that an unmodified buffer became
1252 modified. The elements @var{high} and @var{low} are two integers, each
1253 recording 16 bits of the visited file's modification time as of when it
1254 was previously visited or saved. @code{primitive-undo} uses those
1255 values to determine whether to mark the buffer as unmodified once again;
1256 it does so only if the file's modification time matches those numbers.
1258 @item (nil @var{property} @var{value} @var{beg} . @var{end})
1259 This kind of element records a change in a text property.
1260 Here's how you might undo the change:
1263 (put-text-property @var{beg} @var{end} @var{property} @var{value})
1266 @item (@var{marker} . @var{adjustment})
1267 This kind of element records the fact that the marker @var{marker} was
1268 relocated due to deletion of surrounding text, and that it moved
1269 @var{adjustment} character positions. Undoing this element moves
1270 @var{marker} @minus{} @var{adjustment} characters.
1272 @item (apply @var{funname} . @var{args})
1273 This is an extensible undo item, which is undone by calling
1274 @var{funname} with arguments @var{args}.
1276 @item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
1277 This is an extensible undo item, which records a change limited to the
1278 range @var{beg} to @var{end}, which increased the size of the buffer
1279 by @var{delta}. It is undone by calling @var{funname} with arguments
1282 This kind of element enables undo limited to a region to determine
1283 whether the element pertains to that region.
1286 This element is a boundary. The elements between two boundaries are
1287 called a @dfn{change group}; normally, each change group corresponds to
1288 one keyboard command, and undo commands normally undo an entire group as
1292 @defun undo-boundary
1293 This function places a boundary element in the undo list. The undo
1294 command stops at such a boundary, and successive undo commands undo
1295 to earlier and earlier boundaries. This function returns @code{nil}.
1297 The editor command loop automatically calls @code{undo-boundary} just
1298 before executing each key sequence, so that each undo normally undoes
1299 the effects of one command. As an exception, the command
1300 @code{self-insert-command}, which produces self-inserting input
1301 characters (@pxref{Commands for Insertion}), may remove the boundary
1302 inserted by the command loop: a boundary is accepted for the first
1303 such character, the next 19 consecutive self-inserting input
1304 characters do not have boundaries, and then the 20th does; and so on
1305 as long as the self-inserting characters continue. Hence, sequences
1306 of consecutive character insertions can be undone as a group.
1308 All buffer modifications add a boundary whenever the previous undoable
1309 change was made in some other buffer. This is to ensure that
1310 each command makes a boundary in each buffer where it makes changes.
1312 Calling this function explicitly is useful for splitting the effects of
1313 a command into more than one unit. For example, @code{query-replace}
1314 calls @code{undo-boundary} after each replacement, so that the user can
1315 undo individual replacements one by one.
1318 @defvar undo-in-progress
1319 This variable is normally @code{nil}, but the undo commands bind it to
1320 @code{t}. This is so that various kinds of change hooks can tell when
1321 they're being called for the sake of undoing.
1324 @defun primitive-undo count list
1325 This is the basic function for undoing elements of an undo list.
1326 It undoes the first @var{count} elements of @var{list}, returning
1327 the rest of @var{list}.
1329 @code{primitive-undo} adds elements to the buffer's undo list when it
1330 changes the buffer. Undo commands avoid confusion by saving the undo
1331 list value at the beginning of a sequence of undo operations. Then the
1332 undo operations use and update the saved value. The new elements added
1333 by undoing are not part of this saved value, so they don't interfere with
1336 This function does not bind @code{undo-in-progress}.
1339 @node Maintaining Undo
1340 @section Maintaining Undo Lists
1342 This section describes how to enable and disable undo information for
1343 a given buffer. It also explains how the undo list is truncated
1344 automatically so it doesn't get too big.
1346 Recording of undo information in a newly created buffer is normally
1347 enabled to start with; but if the buffer name starts with a space, the
1348 undo recording is initially disabled. You can explicitly enable or
1349 disable undo recording with the following two functions, or by setting
1350 @code{buffer-undo-list} yourself.
1352 @deffn Command buffer-enable-undo &optional buffer-or-name
1353 This command enables recording undo information for buffer
1354 @var{buffer-or-name}, so that subsequent changes can be undone. If no
1355 argument is supplied, then the current buffer is used. This function
1356 does nothing if undo recording is already enabled in the buffer. It
1359 In an interactive call, @var{buffer-or-name} is the current buffer.
1360 You cannot specify any other buffer.
1363 @deffn Command buffer-disable-undo &optional buffer-or-name
1364 @cindex disabling undo
1365 This function discards the undo list of @var{buffer-or-name}, and disables
1366 further recording of undo information. As a result, it is no longer
1367 possible to undo either previous changes or any subsequent changes. If
1368 the undo list of @var{buffer-or-name} is already disabled, this function
1371 This function returns @code{nil}.
1374 As editing continues, undo lists get longer and longer. To prevent
1375 them from using up all available memory space, garbage collection trims
1376 them back to size limits you can set. (For this purpose, the ``size''
1377 of an undo list measures the cons cells that make up the list, plus the
1378 strings of deleted text.) Three variables control the range of acceptable
1379 sizes: @code{undo-limit}, @code{undo-strong-limit} and
1380 @code{undo-outer-limit}. In these variables, size is counted as the
1381 number of bytes occupied, which includes both saved text and other
1385 This is the soft limit for the acceptable size of an undo list. The
1386 change group at which this size is exceeded is the last one kept.
1389 @defopt undo-strong-limit
1390 This is the upper limit for the acceptable size of an undo list. The
1391 change group at which this size is exceeded is discarded itself (along
1392 with all older change groups). There is one exception: the very latest
1393 change group is only discarded if it exceeds @code{undo-outer-limit}.
1396 @defopt undo-outer-limit
1397 If at garbage collection time the undo info for the current command
1398 exceeds this limit, Emacs discards the info and displays a warning.
1399 This is a last ditch limit to prevent memory overflow.
1402 @defopt undo-ask-before-discard
1403 If this variable is non-@code{nil}, when the undo info exceeds
1404 @code{undo-outer-limit}, Emacs asks in the echo area whether to
1405 discard the info. The default value is @code{nil}, which means to
1406 discard it automatically.
1408 This option is mainly intended for debugging. Garbage collection is
1409 inhibited while the question is asked, which means that Emacs might
1410 leak memory if the user waits too long before answering the question.
1414 @comment node-name, next, previous, up
1416 @cindex filling text
1418 @dfn{Filling} means adjusting the lengths of lines (by moving the line
1419 breaks) so that they are nearly (but no greater than) a specified
1420 maximum width. Additionally, lines can be @dfn{justified}, which means
1421 inserting spaces to make the left and/or right margins line up
1422 precisely. The width is controlled by the variable @code{fill-column}.
1423 For ease of reading, lines should be no longer than 70 or so columns.
1425 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1426 automatically as you insert it, but changes to existing text may leave
1427 it improperly filled. Then you must fill the text explicitly.
1429 Most of the commands in this section return values that are not
1430 meaningful. All the functions that do filling take note of the current
1431 left margin, current right margin, and current justification style
1432 (@pxref{Margins}). If the current justification style is
1433 @code{none}, the filling functions don't actually do anything.
1435 Several of the filling functions have an argument @var{justify}.
1436 If it is non-@code{nil}, that requests some kind of justification. It
1437 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
1438 request a specific style of justification. If it is @code{t}, that
1439 means to use the current justification style for this part of the text
1440 (see @code{current-justification}, below). Any other value is treated
1443 When you call the filling functions interactively, using a prefix
1444 argument implies the value @code{full} for @var{justify}.
1446 @deffn Command fill-paragraph &optional justify region
1447 This command fills the paragraph at or after point. If
1448 @var{justify} is non-@code{nil}, each line is justified as well.
1449 It uses the ordinary paragraph motion commands to find paragraph
1450 boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
1452 When @var{region} is non-@code{nil}, then if Transient Mark mode is
1453 enabled and the mark is active, this command calls @code{fill-region}
1454 to fill all the paragraphs in the region, instead of filling only the
1455 current paragraph. When this command is called interactively,
1456 @var{region} is @code{t}.
1459 @deffn Command fill-region start end &optional justify nosqueeze to-eop
1460 This command fills each of the paragraphs in the region from @var{start}
1461 to @var{end}. It justifies as well if @var{justify} is
1464 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1465 other than line breaks untouched. If @var{to-eop} is non-@code{nil},
1466 that means to keep filling to the end of the paragraph---or the next hard
1467 newline, if @code{use-hard-newlines} is enabled (see below).
1469 The variable @code{paragraph-separate} controls how to distinguish
1470 paragraphs. @xref{Standard Regexps}.
1473 @deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
1474 This command fills each paragraph in the region according to its
1475 individual fill prefix. Thus, if the lines of a paragraph were indented
1476 with spaces, the filled paragraph will remain indented in the same
1479 The first two arguments, @var{start} and @var{end}, are the beginning
1480 and end of the region to be filled. The third and fourth arguments,
1481 @var{justify} and @var{citation-regexp}, are optional. If
1482 @var{justify} is non-@code{nil}, the paragraphs are justified as
1483 well as filled. If @var{citation-regexp} is non-@code{nil}, it means the
1484 function is operating on a mail message and therefore should not fill
1485 the header lines. If @var{citation-regexp} is a string, it is used as
1486 a regular expression; if it matches the beginning of a line, that line
1487 is treated as a citation marker.
1489 Ordinarily, @code{fill-individual-paragraphs} regards each change in
1490 indentation as starting a new paragraph. If
1491 @code{fill-individual-varying-indent} is non-@code{nil}, then only
1492 separator lines separate paragraphs. That mode can handle indented
1493 paragraphs with additional indentation on the first line.
1496 @defopt fill-individual-varying-indent
1497 This variable alters the action of @code{fill-individual-paragraphs} as
1501 @deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
1502 This command considers a region of text as a single paragraph and fills
1503 it. If the region was made up of many paragraphs, the blank lines
1504 between paragraphs are removed. This function justifies as well as
1505 filling when @var{justify} is non-@code{nil}.
1507 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1508 other than line breaks untouched. If @var{squeeze-after} is
1509 non-@code{nil}, it specifies a position in the region, and means don't
1510 canonicalize spaces before that position.
1512 In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
1513 choose a fill prefix by default. @xref{Adaptive Fill}.
1516 @deffn Command justify-current-line &optional how eop nosqueeze
1517 This command inserts spaces between the words of the current line so
1518 that the line ends exactly at @code{fill-column}. It returns
1521 The argument @var{how}, if non-@code{nil} specifies explicitly the style
1522 of justification. It can be @code{left}, @code{right}, @code{full},
1523 @code{center}, or @code{none}. If it is @code{t}, that means to do
1524 follow specified justification style (see @code{current-justification},
1525 below). @code{nil} means to do full justification.
1527 If @var{eop} is non-@code{nil}, that means do only left-justification
1528 if @code{current-justification} specifies full justification. This is
1529 used for the last line of a paragraph; even if the paragraph as a
1530 whole is fully justified, the last line should not be.
1532 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1536 @defopt default-justification
1537 This variable's value specifies the style of justification to use for
1538 text that doesn't specify a style with a text property. The possible
1539 values are @code{left}, @code{right}, @code{full}, @code{center}, or
1540 @code{none}. The default value is @code{left}.
1543 @defun current-justification
1544 This function returns the proper justification style to use for filling
1545 the text around point.
1547 This returns the value of the @code{justification} text property at
1548 point, or the variable @var{default-justification} if there is no such
1549 text property. However, it returns @code{nil} rather than @code{none}
1550 to mean ``don't justify''.
1553 @defopt sentence-end-double-space
1554 @anchor{Definition of sentence-end-double-space}
1555 If this variable is non-@code{nil}, a period followed by just one space
1556 does not count as the end of a sentence, and the filling functions
1557 avoid breaking the line at such a place.
1560 @defopt sentence-end-without-period
1561 If this variable is non-@code{nil}, a sentence can end without a
1562 period. This is used for languages like Thai, where sentences end
1563 with a double space but without a period.
1566 @defopt sentence-end-without-space
1567 If this variable is non-@code{nil}, it should be a string of
1568 characters that can end a sentence without following spaces.
1571 @defvar fill-paragraph-function
1572 This variable provides a way to override the filling of paragraphs.
1573 If its value is non-@code{nil}, @code{fill-paragraph} calls this
1574 function to do the work. If the function returns a non-@code{nil}
1575 value, @code{fill-paragraph} assumes the job is done, and immediately
1578 The usual use of this feature is to fill comments in programming
1579 language modes. If the function needs to fill a paragraph in the usual
1580 way, it can do so as follows:
1583 (let ((fill-paragraph-function nil))
1584 (fill-paragraph arg))
1588 @defvar fill-forward-paragraph-function
1589 This variable provides a way to override how the filling functions,
1590 such as @code{fill-region} and @code{fill-paragraph}, move forward to
1591 the next paragraph. Its value should be a function, which is called
1592 with a single argument @var{n}, the number of paragraphs to move, and
1593 should return the difference between @var{n} and the number of
1594 paragraphs actually moved. The default value of this variable is
1595 @code{forward-paragraph}. @xref{Paragraphs,,, emacs, The GNU Emacs
1599 @defvar use-hard-newlines
1600 If this variable is non-@code{nil}, the filling functions do not delete
1601 newlines that have the @code{hard} text property. These ``hard
1602 newlines'' act as paragraph separators.
1606 @section Margins for Filling
1609 This buffer-local variable, if non-@code{nil}, specifies a string of
1610 text that appears at the beginning of normal text lines and should be
1611 disregarded when filling them. Any line that fails to start with the
1612 fill prefix is considered the start of a paragraph; so is any line
1613 that starts with the fill prefix followed by additional whitespace.
1614 Lines that start with the fill prefix but no additional whitespace are
1615 ordinary text lines that can be filled together. The resulting filled
1616 lines also start with the fill prefix.
1618 The fill prefix follows the left margin whitespace, if any.
1622 This buffer-local variable specifies the maximum width of filled lines.
1623 Its value should be an integer, which is a number of columns. All the
1624 filling, justification, and centering commands are affected by this
1625 variable, including Auto Fill mode (@pxref{Auto Filling}).
1627 As a practical matter, if you are writing text for other people to
1628 read, you should set @code{fill-column} to no more than 70. Otherwise
1629 the line will be too long for people to read comfortably, and this can
1630 make the text seem clumsy.
1632 The default value for @code{fill-column} is 70.
1635 @deffn Command set-left-margin from to margin
1636 This sets the @code{left-margin} property on the text from @var{from} to
1637 @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
1638 command also refills the region to fit the new margin.
1641 @deffn Command set-right-margin from to margin
1642 This sets the @code{right-margin} property on the text from @var{from}
1643 to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
1644 this command also refills the region to fit the new margin.
1647 @defun current-left-margin
1648 This function returns the proper left margin value to use for filling
1649 the text around point. The value is the sum of the @code{left-margin}
1650 property of the character at the start of the current line (or zero if
1651 none), and the value of the variable @code{left-margin}.
1654 @defun current-fill-column
1655 This function returns the proper fill column value to use for filling
1656 the text around point. The value is the value of the @code{fill-column}
1657 variable, minus the value of the @code{right-margin} property of the
1658 character after point.
1661 @deffn Command move-to-left-margin &optional n force
1662 This function moves point to the left margin of the current line. The
1663 column moved to is determined by calling the function
1664 @code{current-left-margin}. If the argument @var{n} is non-@code{nil},
1665 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
1667 If @var{force} is non-@code{nil}, that says to fix the line's
1668 indentation if that doesn't match the left margin value.
1671 @defun delete-to-left-margin &optional from to
1672 This function removes left margin indentation from the text between
1673 @var{from} and @var{to}. The amount of indentation to delete is
1674 determined by calling @code{current-left-margin}. In no case does this
1675 function delete non-whitespace. If @var{from} and @var{to} are omitted,
1676 they default to the whole buffer.
1679 @defun indent-to-left-margin
1680 This function adjusts the indentation at the beginning of the current
1681 line to the value specified by the variable @code{left-margin}. (That
1682 may involve either inserting or deleting whitespace.) This function
1683 is value of @code{indent-line-function} in Paragraph-Indent Text mode.
1687 This variable specifies the base left margin column. In Fundamental
1688 mode, @kbd{C-j} indents to this column. This variable automatically
1689 becomes buffer-local when set in any fashion.
1692 @defopt fill-nobreak-predicate
1693 This variable gives major modes a way to specify not to break a line
1694 at certain places. Its value should be a list of functions. Whenever
1695 filling considers breaking the line at a certain place in the buffer,
1696 it calls each of these functions with no arguments and with point
1697 located at that place. If any of the functions returns
1698 non-@code{nil}, then the line won't be broken there.
1702 @section Adaptive Fill Mode
1703 @c @cindex Adaptive Fill mode "adaptive-fill-mode" is adjacent.
1705 When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill
1706 prefix automatically from the text in each paragraph being filled
1707 rather than using a predetermined value. During filling, this fill
1708 prefix gets inserted at the start of the second and subsequent lines
1709 of the paragraph as described in @ref{Filling}, and in @ref{Auto
1712 @defopt adaptive-fill-mode
1713 Adaptive Fill mode is enabled when this variable is non-@code{nil}.
1714 It is @code{t} by default.
1717 @defun fill-context-prefix from to
1718 This function implements the heart of Adaptive Fill mode; it chooses a
1719 fill prefix based on the text between @var{from} and @var{to},
1720 typically the start and end of a paragraph. It does this by looking
1721 at the first two lines of the paragraph, based on the variables
1723 @c The optional argument first-line-regexp is not documented
1724 @c because it exists for internal purposes and might be eliminated
1727 Usually, this function returns the fill prefix, a string. However,
1728 before doing this, the function makes a final check (not specially
1729 mentioned in the following) that a line starting with this prefix
1730 wouldn't look like the start of a paragraph. Should this happen, the
1731 function signals the anomaly by returning @code{nil} instead.
1733 In detail, @code{fill-context-prefix} does this:
1737 It takes a candidate for the fill prefix from the first line---it
1738 tries first the function in @code{adaptive-fill-function} (if any),
1739 then the regular expression @code{adaptive-fill-regexp} (see below).
1740 The first non-@code{nil} result of these, or the empty string if
1741 they're both @code{nil}, becomes the first line's candidate.
1743 If the paragraph has as yet only one line, the function tests the
1744 validity of the prefix candidate just found. The function then
1745 returns the candidate if it's valid, or a string of spaces otherwise.
1746 (see the description of @code{adaptive-fill-first-line-regexp} below).
1748 When the paragraph already has two lines, the function next looks for
1749 a prefix candidate on the second line, in just the same way it did for
1750 the first line. If it doesn't find one, it returns @code{nil}.
1752 The function now compares the two candidate prefixes heuristically: if
1753 the non-whitespace characters in the line 2 candidate occur in the
1754 same order in the line 1 candidate, the function returns the line 2
1755 candidate. Otherwise, it returns the largest initial substring which
1756 is common to both candidates (which might be the empty string).
1760 @defopt adaptive-fill-regexp
1761 Adaptive Fill mode matches this regular expression against the text
1762 starting after the left margin whitespace (if any) on a line; the
1763 characters it matches are that line's candidate for the fill prefix.
1765 The default value matches whitespace with certain punctuation
1766 characters intermingled.
1769 @defopt adaptive-fill-first-line-regexp
1770 Used only in one-line paragraphs, this regular expression acts as an
1771 additional check of the validity of the one available candidate fill
1772 prefix: the candidate must match this regular expression, or match
1773 @code{comment-start-skip}. If it doesn't, @code{fill-context-prefix}
1774 replaces the candidate with a string of spaces ``of the same width''
1777 The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which
1778 matches only a string of whitespace. The effect of this default is to
1779 force the fill prefixes found in one-line paragraphs always to be pure
1783 @defopt adaptive-fill-function
1784 You can specify more complex ways of choosing a fill prefix
1785 automatically by setting this variable to a function. The function is
1786 called with point after the left margin (if any) of a line, and it
1787 must preserve point. It should return either ``that line's'' fill
1788 prefix or @code{nil}, meaning it has failed to determine a prefix.
1792 @comment node-name, next, previous, up
1793 @section Auto Filling
1794 @cindex filling, automatic
1795 @cindex Auto Fill mode
1797 Auto Fill mode is a minor mode that fills lines automatically as text
1798 is inserted. This section describes the hook used by Auto Fill mode.
1799 For a description of functions that you can call explicitly to fill and
1800 justify existing text, see @ref{Filling}.
1802 Auto Fill mode also enables the functions that change the margins and
1803 justification style to refill portions of the text. @xref{Margins}.
1805 @defvar auto-fill-function
1806 The value of this buffer-local variable should be a function (of no
1807 arguments) to be called after self-inserting a character from the table
1808 @code{auto-fill-chars}. It may be @code{nil}, in which case nothing
1809 special is done in that case.
1811 The value of @code{auto-fill-function} is @code{do-auto-fill} when
1812 Auto-Fill mode is enabled. That is a function whose sole purpose is to
1813 implement the usual strategy for breaking a line.
1816 In older Emacs versions, this variable was named @code{auto-fill-hook},
1817 but since it is not called with the standard convention for hooks, it
1818 was renamed to @code{auto-fill-function} in version 19.
1822 @defvar normal-auto-fill-function
1823 This variable specifies the function to use for
1824 @code{auto-fill-function}, if and when Auto Fill is turned on. Major
1825 modes can set buffer-local values for this variable to alter how Auto
1829 @defvar auto-fill-chars
1830 A char table of characters which invoke @code{auto-fill-function} when
1831 self-inserted---space and newline in most language environments. They
1832 have an entry @code{t} in the table.
1836 @section Sorting Text
1837 @cindex sorting text
1839 The sorting functions described in this section all rearrange text in
1840 a buffer. This is in contrast to the function @code{sort}, which
1841 rearranges the order of the elements of a list (@pxref{Rearrangement}).
1842 The values returned by these functions are not meaningful.
1844 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate
1845 This function is the general text-sorting routine that subdivides a
1846 buffer into records and then sorts them. Most of the commands in this
1847 section use this function.
1849 To understand how @code{sort-subr} works, consider the whole accessible
1850 portion of the buffer as being divided into disjoint pieces called
1851 @dfn{sort records}. The records may or may not be contiguous, but they
1852 must not overlap. A portion of each sort record (perhaps all of it) is
1853 designated as the sort key. Sorting rearranges the records in order by
1856 Usually, the records are rearranged in order of ascending sort key.
1857 If the first argument to the @code{sort-subr} function, @var{reverse},
1858 is non-@code{nil}, the sort records are rearranged in order of
1859 descending sort key.
1861 The next four arguments to @code{sort-subr} are functions that are
1862 called to move point across a sort record. They are called many times
1863 from within @code{sort-subr}.
1867 @var{nextrecfun} is called with point at the end of a record. This
1868 function moves point to the start of the next record. The first record
1869 is assumed to start at the position of point when @code{sort-subr} is
1870 called. Therefore, you should usually move point to the beginning of
1871 the buffer before calling @code{sort-subr}.
1873 This function can indicate there are no more sort records by leaving
1874 point at the end of the buffer.
1877 @var{endrecfun} is called with point within a record. It moves point to
1878 the end of the record.
1881 @var{startkeyfun} is called to move point from the start of a record to
1882 the start of the sort key. This argument is optional; if it is omitted,
1883 the whole record is the sort key. If supplied, the function should
1884 either return a non-@code{nil} value to be used as the sort key, or
1885 return @code{nil} to indicate that the sort key is in the buffer
1886 starting at point. In the latter case, @var{endkeyfun} is called to
1887 find the end of the sort key.
1890 @var{endkeyfun} is called to move point from the start of the sort key
1891 to the end of the sort key. This argument is optional. If
1892 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
1893 @code{nil}), then the sort key extends to the end of the record. There
1894 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1895 non-@code{nil} value.
1898 The argument @var{predicate} is the function to use to compare keys.
1899 If keys are numbers, it defaults to @code{<}; otherwise it defaults to
1902 As an example of @code{sort-subr}, here is the complete function
1903 definition for @code{sort-lines}:
1907 ;; @r{Note that the first two lines of doc string}
1908 ;; @r{are effectively one line when viewed by a user.}
1909 (defun sort-lines (reverse beg end)
1910 "Sort lines in region alphabetically;\
1911 argument means descending order.
1912 Called from a program, there are three arguments:
1915 REVERSE (non-nil means reverse order),\
1916 BEG and END (region to sort).
1917 The variable `sort-fold-case' determines\
1918 whether alphabetic case affects
1922 (interactive "P\nr")
1925 (narrow-to-region beg end)
1926 (goto-char (point-min))
1927 (let ((inhibit-field-text-motion t))
1928 (sort-subr reverse 'forward-line 'end-of-line)))))
1932 Here @code{forward-line} moves point to the start of the next record,
1933 and @code{end-of-line} moves point to the end of record. We do not pass
1934 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
1935 record is used as the sort key.
1937 The @code{sort-paragraphs} function is very much the same, except that
1938 its @code{sort-subr} call looks like this:
1945 (while (and (not (eobp))
1946 (looking-at paragraph-separate))
1952 Markers pointing into any sort records are left with no useful
1953 position after @code{sort-subr} returns.
1956 @defopt sort-fold-case
1957 If this variable is non-@code{nil}, @code{sort-subr} and the other
1958 buffer sorting functions ignore case when comparing strings.
1961 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
1962 This command sorts the region between @var{start} and @var{end}
1963 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
1964 If @var{reverse} is a negative integer, then sorting is in reverse
1967 Alphabetical sorting means that two sort keys are compared by
1968 comparing the first characters of each, the second characters of each,
1969 and so on. If a mismatch is found, it means that the sort keys are
1970 unequal; the sort key whose character is less at the point of first
1971 mismatch is the lesser sort key. The individual characters are compared
1972 according to their numerical character codes in the Emacs character set.
1974 The value of the @var{record-regexp} argument specifies how to divide
1975 the buffer into sort records. At the end of each record, a search is
1976 done for this regular expression, and the text that matches it is taken
1977 as the next record. For example, the regular expression @samp{^.+$},
1978 which matches lines with at least one character besides a newline, would
1979 make each such line into a sort record. @xref{Regular Expressions}, for
1980 a description of the syntax and meaning of regular expressions.
1982 The value of the @var{key-regexp} argument specifies what part of each
1983 record is the sort key. The @var{key-regexp} could match the whole
1984 record, or only a part. In the latter case, the rest of the record has
1985 no effect on the sorted order of records, but it is carried along when
1986 the record moves to its new position.
1988 The @var{key-regexp} argument can refer to the text matched by a
1989 subexpression of @var{record-regexp}, or it can be a regular expression
1992 If @var{key-regexp} is:
1995 @item @samp{\@var{digit}}
1996 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
1997 grouping in @var{record-regexp} is the sort key.
2000 then the whole record is the sort key.
2002 @item a regular expression
2003 then @code{sort-regexp-fields} searches for a match for the regular
2004 expression within the record. If such a match is found, it is the sort
2005 key. If there is no match for @var{key-regexp} within a record then
2006 that record is ignored, which means its position in the buffer is not
2007 changed. (The other records may move around it.)
2010 For example, if you plan to sort all the lines in the region by the
2011 first word on each line starting with the letter @samp{f}, you should
2012 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
2013 @samp{\<f\w*\>}. The resulting expression looks like this:
2017 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
2023 If you call @code{sort-regexp-fields} interactively, it prompts for
2024 @var{record-regexp} and @var{key-regexp} in the minibuffer.
2027 @deffn Command sort-lines reverse start end
2028 This command alphabetically sorts lines in the region between
2029 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2030 is in reverse order.
2033 @deffn Command sort-paragraphs reverse start end
2034 This command alphabetically sorts paragraphs in the region between
2035 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2036 is in reverse order.
2039 @deffn Command sort-pages reverse start end
2040 This command alphabetically sorts pages in the region between
2041 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2042 is in reverse order.
2045 @deffn Command sort-fields field start end
2046 This command sorts lines in the region between @var{start} and
2047 @var{end}, comparing them alphabetically by the @var{field}th field
2048 of each line. Fields are separated by whitespace and numbered starting
2049 from 1. If @var{field} is negative, sorting is by the
2050 @w{@minus{}@var{field}th} field from the end of the line. This command
2051 is useful for sorting tables.
2054 @deffn Command sort-numeric-fields field start end
2055 This command sorts lines in the region between @var{start} and
2056 @var{end}, comparing them numerically by the @var{field}th field of
2057 each line. Fields are separated by whitespace and numbered starting
2058 from 1. The specified field must contain a number in each line of the
2059 region. Numbers starting with 0 are treated as octal, and numbers
2060 starting with @samp{0x} are treated as hexadecimal.
2062 If @var{field} is negative, sorting is by the
2063 @w{@minus{}@var{field}th} field from the end of the line. This
2064 command is useful for sorting tables.
2067 @defopt sort-numeric-base
2068 This variable specifies the default radix for
2069 @code{sort-numeric-fields} to parse numbers.
2072 @deffn Command sort-columns reverse &optional beg end
2073 This command sorts the lines in the region between @var{beg} and
2074 @var{end}, comparing them alphabetically by a certain range of
2075 columns. The column positions of @var{beg} and @var{end} bound the
2076 range of columns to sort on.
2078 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
2080 One unusual thing about this command is that the entire line
2081 containing position @var{beg}, and the entire line containing position
2082 @var{end}, are included in the region sorted.
2084 Note that @code{sort-columns} rejects text that contains tabs, because
2085 tabs could be split across the specified columns. Use @kbd{M-x
2086 untabify} to convert tabs to spaces before sorting.
2088 When possible, this command actually works by calling the @code{sort}
2093 @comment node-name, next, previous, up
2094 @section Counting Columns
2096 @cindex counting columns
2097 @cindex horizontal position
2099 The column functions convert between a character position (counting
2100 characters from the beginning of the buffer) and a column position
2101 (counting screen characters from the beginning of a line).
2103 These functions count each character according to the number of
2104 columns it occupies on the screen. This means control characters count
2105 as occupying 2 or 4 columns, depending upon the value of
2106 @code{ctl-arrow}, and tabs count as occupying a number of columns that
2107 depends on the value of @code{tab-width} and on the column where the tab
2108 begins. @xref{Usual Display}.
2110 Column number computations ignore the width of the window and the
2111 amount of horizontal scrolling. Consequently, a column value can be
2112 arbitrarily high. The first (or leftmost) column is numbered 0. They
2113 also ignore overlays and text properties, aside from invisibility.
2115 @defun current-column
2116 This function returns the horizontal position of point, measured in
2117 columns, counting from 0 at the left margin. The column position is the
2118 sum of the widths of all the displayed representations of the characters
2119 between the start of the current line and point.
2121 For an example of using @code{current-column}, see the description of
2122 @code{count-lines} in @ref{Text Lines}.
2125 @deffn Command move-to-column column &optional force
2126 This function moves point to @var{column} in the current line. The
2127 calculation of @var{column} takes into account the widths of the
2128 displayed representations of the characters between the start of the
2131 When called interactively, @var{column} is the value of prefix numeric
2132 argument. If @var{column} is not an integer, an error is signaled.
2134 If column @var{column} is beyond the end of the line, point moves to
2135 the end of the line. If @var{column} is negative, point moves to the
2136 beginning of the line.
2138 If it is impossible to move to column @var{column} because that is in
2139 the middle of a multicolumn character such as a tab, point moves to the
2140 end of that character. However, if @var{force} is non-@code{nil}, and
2141 @var{column} is in the middle of a tab, then @code{move-to-column}
2142 converts the tab into spaces so that it can move precisely to column
2143 @var{column}. Other multicolumn characters can cause anomalies despite
2144 @var{force}, since there is no way to split them.
2146 The argument @var{force} also has an effect if the line isn't long
2147 enough to reach column @var{column}; if it is @code{t}, that means to
2148 add whitespace at the end of the line to reach that column.
2150 The return value is the column number actually moved to.
2154 @section Indentation
2157 The indentation functions are used to examine, move to, and change
2158 whitespace that is at the beginning of a line. Some of the functions
2159 can also change whitespace elsewhere on a line. Columns and indentation
2160 count from zero at the left margin.
2163 * Primitive Indent:: Functions used to count and insert indentation.
2164 * Mode-Specific Indent:: Customize indentation for different modes.
2165 * Region Indent:: Indent all the lines in a region.
2166 * Relative Indent:: Indent the current line based on previous lines.
2167 * Indent Tabs:: Adjustable, typewriter-like tab stops.
2168 * Motion by Indent:: Move to first non-blank character.
2171 @node Primitive Indent
2172 @subsection Indentation Primitives
2174 This section describes the primitive functions used to count and
2175 insert indentation. The functions in the following sections use these
2176 primitives. @xref{Width}, for related functions.
2178 @defun current-indentation
2179 @comment !!Type Primitive Function
2180 @comment !!SourceFile indent.c
2181 This function returns the indentation of the current line, which is
2182 the horizontal position of the first nonblank character. If the
2183 contents are entirely blank, then this is the horizontal position of the
2187 @deffn Command indent-to column &optional minimum
2188 @comment !!Type Primitive Function
2189 @comment !!SourceFile indent.c
2190 This function indents from point with tabs and spaces until @var{column}
2191 is reached. If @var{minimum} is specified and non-@code{nil}, then at
2192 least that many spaces are inserted even if this requires going beyond
2193 @var{column}. Otherwise the function does nothing if point is already
2194 beyond @var{column}. The value is the column at which the inserted
2197 The inserted whitespace characters inherit text properties from the
2198 surrounding text (usually, from the preceding text only). @xref{Sticky
2202 @defopt indent-tabs-mode
2203 @comment !!SourceFile indent.c
2204 If this variable is non-@code{nil}, indentation functions can insert
2205 tabs as well as spaces. Otherwise, they insert only spaces. Setting
2206 this variable automatically makes it buffer-local in the current buffer.
2209 @node Mode-Specific Indent
2210 @subsection Indentation Controlled by Major Mode
2212 An important function of each major mode is to customize the @key{TAB}
2213 key to indent properly for the language being edited. This section
2214 describes the mechanism of the @key{TAB} key and how to control it.
2215 The functions in this section return unpredictable values.
2217 @defvar indent-line-function
2218 This variable's value is the function to be used by @key{TAB} (and
2219 various commands) to indent the current line. The command
2220 @code{indent-according-to-mode} does little more than call this function.
2222 In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C
2223 mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
2224 The default value is @code{indent-relative}. @xref{Auto-Indentation}.
2227 @deffn Command indent-according-to-mode
2228 This command calls the function in @code{indent-line-function} to
2229 indent the current line in a way appropriate for the current major mode.
2232 @deffn Command indent-for-tab-command &optional rigid
2233 This command calls the function in @code{indent-line-function} to
2234 indent the current line; however, if that function is
2235 @code{indent-to-left-margin}, @code{insert-tab} is called instead.
2236 (That is a trivial command that inserts a tab character.) If
2237 @var{rigid} is non-@code{nil}, this function also rigidly indents the
2238 entire balanced expression that starts at the beginning of the current
2239 line, to reflect change in indentation of the current line.
2242 @deffn Command newline-and-indent
2243 This function inserts a newline, then indents the new line (the one
2244 following the newline just inserted) according to the major mode.
2246 It does indentation by calling the current @code{indent-line-function}.
2247 In programming language modes, this is the same thing @key{TAB} does,
2248 but in some text modes, where @key{TAB} inserts a tab,
2249 @code{newline-and-indent} indents to the column specified by
2253 @deffn Command reindent-then-newline-and-indent
2254 @comment !!SourceFile simple.el
2255 This command reindents the current line, inserts a newline at point,
2256 and then indents the new line (the one following the newline just
2259 This command does indentation on both lines according to the current
2260 major mode, by calling the current value of @code{indent-line-function}.
2261 In programming language modes, this is the same thing @key{TAB} does,
2262 but in some text modes, where @key{TAB} inserts a tab,
2263 @code{reindent-then-newline-and-indent} indents to the column specified
2264 by @code{left-margin}.
2268 @subsection Indenting an Entire Region
2270 This section describes commands that indent all the lines in the
2271 region. They return unpredictable values.
2273 @deffn Command indent-region start end &optional to-column
2274 This command indents each nonblank line starting between @var{start}
2275 (inclusive) and @var{end} (exclusive). If @var{to-column} is
2276 @code{nil}, @code{indent-region} indents each nonblank line by calling
2277 the current mode's indentation function, the value of
2278 @code{indent-line-function}.
2280 If @var{to-column} is non-@code{nil}, it should be an integer
2281 specifying the number of columns of indentation; then this function
2282 gives each line exactly that much indentation, by either adding or
2283 deleting whitespace.
2285 If there is a fill prefix, @code{indent-region} indents each line
2286 by making it start with the fill prefix.
2289 @defvar indent-region-function
2290 The value of this variable is a function that can be used by
2291 @code{indent-region} as a short cut. It should take two arguments, the
2292 start and end of the region. You should design the function so
2293 that it will produce the same results as indenting the lines of the
2294 region one by one, but presumably faster.
2296 If the value is @code{nil}, there is no short cut, and
2297 @code{indent-region} actually works line by line.
2299 A short-cut function is useful in modes such as C mode and Lisp mode,
2300 where the @code{indent-line-function} must scan from the beginning of
2301 the function definition: applying it to each line would be quadratic in
2302 time. The short cut can update the scan information as it moves through
2303 the lines indenting them; this takes linear time. In a mode where
2304 indenting a line individually is fast, there is no need for a short cut.
2306 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
2307 a different meaning and does not use this variable.
2310 @deffn Command indent-rigidly start end count
2311 This command indents all lines starting between @var{start}
2312 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
2313 This ``preserves the shape'' of the affected region, moving it as a
2314 rigid unit. Consequently, this command is useful not only for indenting
2315 regions of unindented text, but also for indenting regions of formatted
2318 For example, if @var{count} is 3, this command adds 3 columns of
2319 indentation to each of the lines beginning in the region specified.
2321 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
2322 @code{indent-rigidly} to indent the text copied from the message being
2326 @deffn Command indent-code-rigidly start end columns &optional nochange-regexp
2327 This is like @code{indent-rigidly}, except that it doesn't alter lines
2328 that start within strings or comments.
2330 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
2331 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
2334 @node Relative Indent
2335 @subsection Indentation Relative to Previous Lines
2337 This section describes two commands that indent the current line
2338 based on the contents of previous lines.
2340 @deffn Command indent-relative &optional unindented-ok
2341 This command inserts whitespace at point, extending to the same
2342 column as the next @dfn{indent point} of the previous nonblank line. An
2343 indent point is a non-whitespace character following whitespace. The
2344 next indent point is the first one at a column greater than the current
2345 column of point. For example, if point is underneath and to the left of
2346 the first non-blank character of a line of text, it moves to that column
2347 by inserting whitespace.
2349 If the previous nonblank line has no next indent point (i.e., none at a
2350 great enough column position), @code{indent-relative} either does
2351 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
2352 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right
2353 of the last column of a short line of text, this command ordinarily
2354 moves point to the next tab stop by inserting whitespace.
2356 The return value of @code{indent-relative} is unpredictable.
2358 In the following example, point is at the beginning of the second
2363 This line is indented twelve spaces.
2364 @point{}The quick brown fox jumped.
2369 Evaluation of the expression @code{(indent-relative nil)} produces the
2374 This line is indented twelve spaces.
2375 @point{}The quick brown fox jumped.
2379 In this next example, point is between the @samp{m} and @samp{p} of
2384 This line is indented twelve spaces.
2385 The quick brown fox jum@point{}ped.
2390 Evaluation of the expression @code{(indent-relative nil)} produces the
2395 This line is indented twelve spaces.
2396 The quick brown fox jum @point{}ped.
2401 @deffn Command indent-relative-maybe
2402 @comment !!SourceFile indent.el
2403 This command indents the current line like the previous nonblank line,
2404 by calling @code{indent-relative} with @code{t} as the
2405 @var{unindented-ok} argument. The return value is unpredictable.
2407 If the previous nonblank line has no indent points beyond the current
2408 column, this command does nothing.
2412 @comment node-name, next, previous, up
2413 @subsection Adjustable ``Tab Stops''
2414 @cindex tabs stops for indentation
2416 This section explains the mechanism for user-specified ``tab stops''
2417 and the mechanisms that use and set them. The name ``tab stops'' is
2418 used because the feature is similar to that of the tab stops on a
2419 typewriter. The feature works by inserting an appropriate number of
2420 spaces and tab characters to reach the next tab stop column; it does not
2421 affect the display of tab characters in the buffer (@pxref{Usual
2422 Display}). Note that the @key{TAB} character as input uses this tab
2423 stop feature only in a few major modes, such as Text mode.
2424 @xref{Tab Stops,,, emacs, The GNU Emacs Manual}.
2426 @deffn Command tab-to-tab-stop
2427 This command inserts spaces or tabs before point, up to the next tab
2428 stop column defined by @code{tab-stop-list}. It searches the list for
2429 an element greater than the current column number, and uses that element
2430 as the column to indent to. It does nothing if no such element is
2434 @defopt tab-stop-list
2435 This variable is the list of tab stop columns used by
2436 @code{tab-to-tab-stops}. The elements should be integers in increasing
2437 order. The tab stop columns need not be evenly spaced.
2439 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
2443 @node Motion by Indent
2444 @subsection Indentation-Based Motion Commands
2446 These commands, primarily for interactive use, act based on the
2447 indentation in the text.
2449 @deffn Command back-to-indentation
2450 @comment !!SourceFile simple.el
2451 This command moves point to the first non-whitespace character in the
2452 current line (which is the line in which point is located). It returns
2456 @deffn Command backward-to-indentation &optional arg
2457 @comment !!SourceFile simple.el
2458 This command moves point backward @var{arg} lines and then to the
2459 first nonblank character on that line. It returns @code{nil}.
2460 If @var{arg} is omitted or @code{nil}, it defaults to 1.
2463 @deffn Command forward-to-indentation &optional arg
2464 @comment !!SourceFile simple.el
2465 This command moves point forward @var{arg} lines and then to the first
2466 nonblank character on that line. It returns @code{nil}.
2467 If @var{arg} is omitted or @code{nil}, it defaults to 1.
2471 @comment node-name, next, previous, up
2472 @section Case Changes
2473 @cindex case conversion in buffers
2475 The case change commands described here work on text in the current
2476 buffer. @xref{Case Conversion}, for case conversion functions that work
2477 on strings and characters. @xref{Case Tables}, for how to customize
2478 which characters are upper or lower case and how to convert them.
2480 @deffn Command capitalize-region start end
2481 This function capitalizes all words in the region defined by
2482 @var{start} and @var{end}. To capitalize means to convert each word's
2483 first character to upper case and convert the rest of each word to lower
2484 case. The function returns @code{nil}.
2486 If one end of the region is in the middle of a word, the part of the
2487 word within the region is treated as an entire word.
2489 When @code{capitalize-region} is called interactively, @var{start} and
2490 @var{end} are point and the mark, with the smallest first.
2494 ---------- Buffer: foo ----------
2495 This is the contents of the 5th foo.
2496 ---------- Buffer: foo ----------
2500 (capitalize-region 1 44)
2503 ---------- Buffer: foo ----------
2504 This Is The Contents Of The 5th Foo.
2505 ---------- Buffer: foo ----------
2510 @deffn Command downcase-region start end
2511 This function converts all of the letters in the region defined by
2512 @var{start} and @var{end} to lower case. The function returns
2515 When @code{downcase-region} is called interactively, @var{start} and
2516 @var{end} are point and the mark, with the smallest first.
2519 @deffn Command upcase-region start end
2520 This function converts all of the letters in the region defined by
2521 @var{start} and @var{end} to upper case. The function returns
2524 When @code{upcase-region} is called interactively, @var{start} and
2525 @var{end} are point and the mark, with the smallest first.
2528 @deffn Command capitalize-word count
2529 This function capitalizes @var{count} words after point, moving point
2530 over as it does. To capitalize means to convert each word's first
2531 character to upper case and convert the rest of each word to lower case.
2532 If @var{count} is negative, the function capitalizes the
2533 @minus{}@var{count} previous words but does not move point. The value
2536 If point is in the middle of a word, the part of the word before point
2537 is ignored when moving forward. The rest is treated as an entire word.
2539 When @code{capitalize-word} is called interactively, @var{count} is
2540 set to the numeric prefix argument.
2543 @deffn Command downcase-word count
2544 This function converts the @var{count} words after point to all lower
2545 case, moving point over as it does. If @var{count} is negative, it
2546 converts the @minus{}@var{count} previous words but does not move point.
2547 The value is @code{nil}.
2549 When @code{downcase-word} is called interactively, @var{count} is set
2550 to the numeric prefix argument.
2553 @deffn Command upcase-word count
2554 This function converts the @var{count} words after point to all upper
2555 case, moving point over as it does. If @var{count} is negative, it
2556 converts the @minus{}@var{count} previous words but does not move point.
2557 The value is @code{nil}.
2559 When @code{upcase-word} is called interactively, @var{count} is set to
2560 the numeric prefix argument.
2563 @node Text Properties
2564 @section Text Properties
2565 @cindex text properties
2566 @cindex attributes of text
2567 @cindex properties of text
2569 Each character position in a buffer or a string can have a @dfn{text
2570 property list}, much like the property list of a symbol (@pxref{Property
2571 Lists}). The properties belong to a particular character at a
2572 particular place, such as, the letter @samp{T} at the beginning of this
2573 sentence or the first @samp{o} in @samp{foo}---if the same character
2574 occurs in two different places, the two occurrences in general have
2575 different properties.
2577 Each property has a name and a value. Both of these can be any Lisp
2578 object, but the name is normally a symbol. Typically each property
2579 name symbol is used for a particular purpose; for instance, the text
2580 property @code{face} specifies the faces for displaying the character
2581 (@pxref{Special Properties}). The usual way to access the property
2582 list is to specify a name and ask what value corresponds to it.
2584 If a character has a @code{category} property, we call it the
2585 @dfn{property category} of the character. It should be a symbol. The
2586 properties of the symbol serve as defaults for the properties of the
2589 Copying text between strings and buffers preserves the properties
2590 along with the characters; this includes such diverse functions as
2591 @code{substring}, @code{insert}, and @code{buffer-substring}.
2594 * Examining Properties:: Looking at the properties of one character.
2595 * Changing Properties:: Setting the properties of a range of text.
2596 * Property Search:: Searching for where a property changes value.
2597 * Special Properties:: Particular properties with special meanings.
2598 * Format Properties:: Properties for representing formatting of text.
2599 * Sticky Properties:: How inserted text gets properties from
2601 * Lazy Properties:: Computing text properties in a lazy fashion
2602 only when text is examined.
2603 * Clickable Text:: Using text properties to make regions of text
2604 do something when you click on them.
2605 * Fields:: The @code{field} property defines
2606 fields within the buffer.
2607 * Not Intervals:: Why text properties do not use
2608 Lisp-visible text intervals.
2611 @node Examining Properties
2612 @subsection Examining Text Properties
2614 The simplest way to examine text properties is to ask for the value of
2615 a particular property of a particular character. For that, use
2616 @code{get-text-property}. Use @code{text-properties-at} to get the
2617 entire property list of a character. @xref{Property Search}, for
2618 functions to examine the properties of a number of characters at once.
2620 These functions handle both strings and buffers. Keep in mind that
2621 positions in a string start from 0, whereas positions in a buffer start
2624 @defun get-text-property pos prop &optional object
2625 This function returns the value of the @var{prop} property of the
2626 character after position @var{pos} in @var{object} (a buffer or
2627 string). The argument @var{object} is optional and defaults to the
2630 If there is no @var{prop} property strictly speaking, but the character
2631 has a property category that is a symbol, then @code{get-text-property} returns
2632 the @var{prop} property of that symbol.
2635 @defun get-char-property position prop &optional object
2636 This function is like @code{get-text-property}, except that it checks
2637 overlays first and then text properties. @xref{Overlays}.
2639 The argument @var{object} may be a string, a buffer, or a window. If
2640 it is a window, then the buffer displayed in that window is used for
2641 text properties and overlays, but only the overlays active for that
2642 window are considered. If @var{object} is a buffer, then overlays in
2643 that buffer are considered first, in order of decreasing priority,
2644 followed by the text properties. If @var{object} is a string, only
2645 text properties are considered, since strings never have overlays.
2648 @defun get-char-property-and-overlay position prop &optional object
2649 This is like @code{get-char-property}, but gives extra information
2650 about the overlay that the property value comes from.
2652 Its value is a cons cell whose @sc{car} is the property value, the
2653 same value @code{get-char-property} would return with the same
2654 arguments. Its @sc{cdr} is the overlay in which the property was
2655 found, or @code{nil}, if it was found as a text property or not found
2658 If @var{position} is at the end of @var{object}, both the @sc{car} and
2659 the @sc{cdr} of the value are @code{nil}.
2662 @defvar char-property-alias-alist
2663 This variable holds an alist which maps property names to a list of
2664 alternative property names. If a character does not specify a direct
2665 value for a property, the alternative property names are consulted in
2666 order; the first non-@code{nil} value is used. This variable takes
2667 precedence over @code{default-text-properties}, and @code{category}
2668 properties take precedence over this variable.
2671 @defun text-properties-at position &optional object
2672 This function returns the entire property list of the character at
2673 @var{position} in the string or buffer @var{object}. If @var{object} is
2674 @code{nil}, it defaults to the current buffer.
2677 @defvar default-text-properties
2678 This variable holds a property list giving default values for text
2679 properties. Whenever a character does not specify a value for a
2680 property, neither directly, through a category symbol, or through
2681 @code{char-property-alias-alist}, the value stored in this list is
2682 used instead. Here is an example:
2685 (setq default-text-properties '(foo 69)
2686 char-property-alias-alist nil)
2687 ;; @r{Make sure character 1 has no properties of its own.}
2688 (set-text-properties 1 2 nil)
2689 ;; @r{What we get, when we ask, is the default value.}
2690 (get-text-property 1 'foo)
2695 @node Changing Properties
2696 @subsection Changing Text Properties
2698 The primitives for changing properties apply to a specified range of
2699 text in a buffer or string. The function @code{set-text-properties}
2700 (see end of section) sets the entire property list of the text in that
2701 range; more often, it is useful to add, change, or delete just certain
2702 properties specified by name.
2704 Since text properties are considered part of the contents of the
2705 buffer (or string), and can affect how a buffer looks on the screen,
2706 any change in buffer text properties marks the buffer as modified.
2707 Buffer text property changes are undoable also (@pxref{Undo}).
2708 Positions in a string start from 0, whereas positions in a buffer
2711 @defun put-text-property start end prop value &optional object
2712 This function sets the @var{prop} property to @var{value} for the text
2713 between @var{start} and @var{end} in the string or buffer @var{object}.
2714 If @var{object} is @code{nil}, it defaults to the current buffer.
2717 @defun add-text-properties start end props &optional object
2718 This function adds or overrides text properties for the text between
2719 @var{start} and @var{end} in the string or buffer @var{object}. If
2720 @var{object} is @code{nil}, it defaults to the current buffer.
2722 The argument @var{props} specifies which properties to add. It should
2723 have the form of a property list (@pxref{Property Lists}): a list whose
2724 elements include the property names followed alternately by the
2725 corresponding values.
2727 The return value is @code{t} if the function actually changed some
2728 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2729 its values agree with those in the text).
2731 For example, here is how to set the @code{comment} and @code{face}
2732 properties of a range of text:
2735 (add-text-properties @var{start} @var{end}
2736 '(comment t face highlight))
2740 @defun remove-text-properties start end props &optional object
2741 This function deletes specified text properties from the text between
2742 @var{start} and @var{end} in the string or buffer @var{object}. If
2743 @var{object} is @code{nil}, it defaults to the current buffer.
2745 The argument @var{props} specifies which properties to delete. It
2746 should have the form of a property list (@pxref{Property Lists}): a list
2747 whose elements are property names alternating with corresponding values.
2748 But only the names matter---the values that accompany them are ignored.
2749 For example, here's how to remove the @code{face} property.
2752 (remove-text-properties @var{start} @var{end} '(face nil))
2755 The return value is @code{t} if the function actually changed some
2756 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2757 if no character in the specified text had any of those properties).
2759 To remove all text properties from certain text, use
2760 @code{set-text-properties} and specify @code{nil} for the new property
2764 @defun remove-list-of-text-properties start end list-of-properties &optional object
2765 Like @code{remove-text-properties} except that
2766 @var{list-of-properties} is a list of property names only, not an
2767 alternating list of property names and values.
2770 @defun set-text-properties start end props &optional object
2771 This function completely replaces the text property list for the text
2772 between @var{start} and @var{end} in the string or buffer @var{object}.
2773 If @var{object} is @code{nil}, it defaults to the current buffer.
2775 The argument @var{props} is the new property list. It should be a list
2776 whose elements are property names alternating with corresponding values.
2778 After @code{set-text-properties} returns, all the characters in the
2779 specified range have identical properties.
2781 If @var{props} is @code{nil}, the effect is to get rid of all properties
2782 from the specified range of text. Here's an example:
2785 (set-text-properties @var{start} @var{end} nil)
2788 Do not rely on the return value of this function.
2791 The easiest way to make a string with text properties
2792 is with @code{propertize}:
2794 @defun propertize string &rest properties
2795 This function returns a copy of @var{string} which has the text
2796 properties @var{properties}. These properties apply to all the
2797 characters in the string that is returned. Here is an example that
2798 constructs a string with a @code{face} property and a @code{mouse-face}
2802 (propertize "foo" 'face 'italic
2803 'mouse-face 'bold-italic)
2804 @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
2807 To put different properties on various parts of a string, you can
2808 construct each part with @code{propertize} and then combine them with
2813 (propertize "foo" 'face 'italic
2814 'mouse-face 'bold-italic)
2816 (propertize "bar" 'face 'italic
2817 'mouse-face 'bold-italic))
2818 @result{} #("foo and bar"
2819 0 3 (face italic mouse-face bold-italic)
2821 8 11 (face italic mouse-face bold-italic))
2825 @xref{Buffer Contents}, for the function
2826 @code{buffer-substring-no-properties}, which copies text from the
2827 buffer but does not copy its properties.
2829 @node Property Search
2830 @subsection Text Property Search Functions
2832 In typical use of text properties, most of the time several or many
2833 consecutive characters have the same value for a property. Rather than
2834 writing your programs to examine characters one by one, it is much
2835 faster to process chunks of text that have the same property value.
2837 Here are functions you can use to do this. They use @code{eq} for
2838 comparing property values. In all cases, @var{object} defaults to the
2841 For high performance, it's very important to use the @var{limit}
2842 argument to these functions, especially the ones that search for a
2843 single property---otherwise, they may spend a long time scanning to the
2844 end of the buffer, if the property you are interested in does not change.
2846 These functions do not move point; instead, they return a position (or
2847 @code{nil}). Remember that a position is always between two characters;
2848 the position returned by these functions is between two characters with
2849 different properties.
2851 @defun next-property-change pos &optional object limit
2852 The function scans the text forward from position @var{pos} in the
2853 string or buffer @var{object} till it finds a change in some text
2854 property, then returns the position of the change. In other words, it
2855 returns the position of the first character beyond @var{pos} whose
2856 properties are not identical to those of the character just after
2859 If @var{limit} is non-@code{nil}, then the scan ends at position
2860 @var{limit}. If there is no property change before that point,
2861 @code{next-property-change} returns @var{limit}.
2863 The value is @code{nil} if the properties remain unchanged all the way
2864 to the end of @var{object} and @var{limit} is @code{nil}. If the value
2865 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
2866 The value equals @var{pos} only when @var{limit} equals @var{pos}.
2868 Here is an example of how to scan the buffer by chunks of text within
2869 which all properties are constant:
2873 (let ((plist (text-properties-at (point)))
2875 (or (next-property-change (point) (current-buffer))
2877 @r{Process text from point to @var{next-change}@dots{}}
2878 (goto-char next-change)))
2882 @defun previous-property-change pos &optional object limit
2883 This is like @code{next-property-change}, but scans back from @var{pos}
2884 instead of forward. If the value is non-@code{nil}, it is a position
2885 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
2889 @defun next-single-property-change pos prop &optional object limit
2890 The function scans text for a change in the @var{prop} property, then
2891 returns the position of the change. The scan goes forward from
2892 position @var{pos} in the string or buffer @var{object}. In other
2893 words, this function returns the position of the first character
2894 beyond @var{pos} whose @var{prop} property differs from that of the
2895 character just after @var{pos}.
2897 If @var{limit} is non-@code{nil}, then the scan ends at position
2898 @var{limit}. If there is no property change before that point,
2899 @code{next-single-property-change} returns @var{limit}.
2901 The value is @code{nil} if the property remains unchanged all the way to
2902 the end of @var{object} and @var{limit} is @code{nil}. If the value is
2903 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
2904 equals @var{pos} only if @var{limit} equals @var{pos}.
2907 @defun previous-single-property-change pos prop &optional object limit
2908 This is like @code{next-single-property-change}, but scans back from
2909 @var{pos} instead of forward. If the value is non-@code{nil}, it is a
2910 position less than or equal to @var{pos}; it equals @var{pos} only if
2911 @var{limit} equals @var{pos}.
2914 @defun next-char-property-change pos &optional limit
2915 This is like @code{next-property-change} except that it considers
2916 overlay properties as well as text properties, and if no change is
2917 found before the end of the buffer, it returns the maximum buffer
2918 position rather than @code{nil} (in this sense, it resembles the
2919 corresponding overlay function @code{next-overlay-change}, rather than
2920 @code{next-property-change}). There is no @var{object} operand
2921 because this function operates only on the current buffer. It returns
2922 the next address at which either kind of property changes.
2925 @defun previous-char-property-change pos &optional limit
2926 This is like @code{next-char-property-change}, but scans back from
2927 @var{pos} instead of forward, and returns the minimum buffer
2928 position if no change is found.
2931 @defun next-single-char-property-change pos prop &optional object limit
2932 This is like @code{next-single-property-change} except that it
2933 considers overlay properties as well as text properties, and if no
2934 change is found before the end of the @var{object}, it returns the
2935 maximum valid position in @var{object} rather than @code{nil}. Unlike
2936 @code{next-char-property-change}, this function @emph{does} have an
2937 @var{object} operand; if @var{object} is not a buffer, only
2938 text-properties are considered.
2941 @defun previous-single-char-property-change pos prop &optional object limit
2942 This is like @code{next-single-char-property-change}, but scans back
2943 from @var{pos} instead of forward, and returns the minimum valid
2944 position in @var{object} if no change is found.
2947 @defun text-property-any start end prop value &optional object
2948 This function returns non-@code{nil} if at least one character between
2949 @var{start} and @var{end} has a property @var{prop} whose value is
2950 @var{value}. More precisely, it returns the position of the first such
2951 character. Otherwise, it returns @code{nil}.
2953 The optional fifth argument, @var{object}, specifies the string or
2954 buffer to scan. Positions are relative to @var{object}. The default
2955 for @var{object} is the current buffer.
2958 @defun text-property-not-all start end prop value &optional object
2959 This function returns non-@code{nil} if at least one character between
2960 @var{start} and @var{end} does not have a property @var{prop} with value
2961 @var{value}. More precisely, it returns the position of the first such
2962 character. Otherwise, it returns @code{nil}.
2964 The optional fifth argument, @var{object}, specifies the string or
2965 buffer to scan. Positions are relative to @var{object}. The default
2966 for @var{object} is the current buffer.
2969 @node Special Properties
2970 @subsection Properties with Special Meanings
2972 Here is a table of text property names that have special built-in
2973 meanings. The following sections list a few additional special property
2974 names that control filling and property inheritance. All other names
2975 have no standard meaning, and you can use them as you like.
2977 Note: the properties @code{composition}, @code{display},
2978 @code{invisible} and @code{intangible} can also cause point to move to
2979 an acceptable place, after each Emacs command. @xref{Adjusting
2983 @cindex property category of text character
2984 @kindex category @r{(text property)}
2986 If a character has a @code{category} property, we call it the
2987 @dfn{property category} of the character. It should be a symbol. The
2988 properties of this symbol serve as defaults for the properties of the
2992 @cindex face codes of text
2993 @kindex face @r{(text property)}
2994 You can use the property @code{face} to control the font and color of
2995 text. @xref{Faces}, for more information.
2997 @code{face} can be the following:
3001 A face name (a symbol or string).
3004 A property list of face attributes. This has the
3005 form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
3006 face attribute name and @var{value} is a meaningful value for that
3007 attribute. With this feature, you do not need to create a face each
3008 time you want to specify a particular attribute for certain text.
3009 @xref{Face Attributes}.
3012 @code{face} can also be a list, where each element uses one of the
3015 Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
3016 dynamically updating the @code{face} property of characters based on
3019 @item font-lock-face
3020 @kindex font-lock-face @r{(text property)}
3021 This property specifies a value for the @code{face} property that Font
3022 Lock mode should apply to the underlying text. It is one of the
3023 fontification methods used by Font Lock mode, and is useful for
3024 special modes that implement their own highlighting.
3025 @xref{Precalculated Fontification}. When Font Lock mode is disabled,
3026 @code{font-lock-face} has no effect.
3029 @kindex mouse-face @r{(text property)}
3030 This property is used instead of @code{face} when the mouse is on or
3031 near the character. For this purpose, ``near'' means that all text
3032 between the character and where the mouse is have the same
3033 @code{mouse-face} property value.
3035 Emacs ignores all face attributes from the @code{mouse-face} property
3036 that alter the text size (e.g. @code{:height}, @code{:weight}, and
3037 @code{:slant}). Those attributes are always the same as for the
3041 @kindex fontified @r{(text property)}
3042 This property says whether the text is ready for display. If
3043 @code{nil}, Emacs's redisplay routine calls the functions in
3044 @code{fontification-functions} (@pxref{Auto Faces}) to prepare this
3045 part of the buffer before it is displayed. It is used internally by
3046 the ``just in time'' font locking code.
3049 This property activates various features that change the
3050 way text is displayed. For example, it can make text appear taller
3051 or shorter, higher or lower, wider or narrow, or replaced with an image.
3052 @xref{Display Property}.
3055 @kindex help-echo @r{(text property)}
3057 @anchor{Text help-echo}
3058 If text has a string as its @code{help-echo} property, then when you
3059 move the mouse onto that text, Emacs displays that string in the echo
3060 area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
3063 If the value of the @code{help-echo} property is a function, that
3064 function is called with three arguments, @var{window}, @var{object} and
3065 @var{pos} and should return a help string or @code{nil} for
3066 none. The first argument, @var{window} is the window in which
3067 the help was found. The second, @var{object}, is the buffer, overlay or
3068 string which had the @code{help-echo} property. The @var{pos}
3069 argument is as follows:
3073 If @var{object} is a buffer, @var{pos} is the position in the buffer.
3075 If @var{object} is an overlay, that overlay has a @code{help-echo}
3076 property, and @var{pos} is the position in the overlay's buffer.
3078 If @var{object} is a string (an overlay string or a string displayed
3079 with the @code{display} property), @var{pos} is the position in that
3083 If the value of the @code{help-echo} property is neither a function nor
3084 a string, it is evaluated to obtain a help string.
3086 You can alter the way help text is displayed by setting the variable
3087 @code{show-help-function} (@pxref{Help display}).
3089 This feature is used in the mode line and for other active text.
3092 @cindex keymap of character
3093 @kindex keymap @r{(text property)}
3094 The @code{keymap} property specifies an additional keymap for
3095 commands. When this keymap applies, it is used for key lookup before
3096 the minor mode keymaps and before the buffer's local map.
3097 @xref{Active Keymaps}. If the property value is a symbol, the
3098 symbol's function definition is used as the keymap.
3100 The property's value for the character before point applies if it is
3101 non-@code{nil} and rear-sticky, and the property's value for the
3102 character after point applies if it is non-@code{nil} and
3103 front-sticky. (For mouse clicks, the position of the click is used
3104 instead of the position of point.)
3107 @kindex local-map @r{(text property)}
3108 This property works like @code{keymap} except that it specifies a
3109 keymap to use @emph{instead of} the buffer's local map. For most
3110 purposes (perhaps all purposes), it is better to use the @code{keymap}
3114 The @code{syntax-table} property overrides what the syntax table says
3115 about this particular character. @xref{Syntax Properties}.
3118 @cindex read-only character
3119 @kindex read-only @r{(text property)}
3120 If a character has the property @code{read-only}, then modifying that
3121 character is not allowed. Any command that would do so gets an error,
3122 @code{text-read-only}. If the property value is a string, that string
3123 is used as the error message.
3125 Insertion next to a read-only character is an error if inserting
3126 ordinary text there would inherit the @code{read-only} property due to
3127 stickiness. Thus, you can control permission to insert next to
3128 read-only text by controlling the stickiness. @xref{Sticky Properties}.
3130 Since changing properties counts as modifying the buffer, it is not
3131 possible to remove a @code{read-only} property unless you know the
3132 special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
3133 and then remove the property. @xref{Read Only Buffers}.
3136 @kindex invisible @r{(text property)}
3137 A non-@code{nil} @code{invisible} property can make a character invisible
3138 on the screen. @xref{Invisible Text}, for details.
3141 @kindex intangible @r{(text property)}
3142 If a group of consecutive characters have equal and non-@code{nil}
3143 @code{intangible} properties, then you cannot place point between them.
3144 If you try to move point forward into the group, point actually moves to
3145 the end of the group. If you try to move point backward into the group,
3146 point actually moves to the start of the group.
3148 If consecutive characters have unequal non-@code{nil}
3149 @code{intangible} properties, they belong to separate groups; each
3150 group is separately treated as described above.
3152 When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
3153 the @code{intangible} property is ignored.
3155 Beware: this property operates at a very low level, and affects a lot of code
3156 in unexpected ways. So use it with extreme caution. A common misuse is to put
3157 an intangible property on invisible text, which is actually unnecessary since
3158 the command loop will move point outside of the invisible text at the end of
3159 each command anyway. @xref{Adjusting Point}.
3162 @kindex field @r{(text property)}
3163 Consecutive characters with the same @code{field} property constitute a
3164 @dfn{field}. Some motion functions including @code{forward-word} and
3165 @code{beginning-of-line} stop moving at a field boundary.
3169 @kindex cursor @r{(text property)}
3170 Normally, the cursor is displayed at the end of any overlay and text
3171 property strings present at the current buffer position. You can
3172 place the cursor on any desired character of these strings by giving
3173 that character a non-@code{nil} @code{cursor} text property. In
3174 addition, if the value of the @code{cursor} property of an overlay
3175 string is an integer number, it specifies the number of buffer's
3176 character positions associated with the overlay string; this way,
3177 Emacs will display the cursor on the character with that property
3178 regardless of whether the current buffer position is actually covered
3179 by the overlay. Specifically, if the value of the @code{cursor}
3180 property of a character is the number @var{n}, the cursor will be
3181 displayed on this character for any buffer position in the range
3182 @code{[@var{ovpos}..@var{ovpos}+@var{n}]}, where @var{ovpos} is the
3183 starting buffer position covered by the overlay (@pxref{Managing
3187 @kindex pointer @r{(text property)}
3188 This specifies a specific pointer shape when the mouse pointer is over
3189 this text or image. @xref{Pointer Shape}, for possible pointer
3193 @kindex line-spacing @r{(text property)}
3194 A newline can have a @code{line-spacing} text or overlay property that
3195 controls the height of the display line ending with that newline. The
3196 property value overrides the default frame line spacing and the buffer
3197 local @code{line-spacing} variable. @xref{Line Height}.
3200 @kindex line-height @r{(text property)}
3201 A newline can have a @code{line-height} text or overlay property that
3202 controls the total height of the display line ending in that newline.
3206 If text has a @code{wrap-prefix} property, the prefix it defines will
3207 be added at display time to the beginning of every continuation line
3208 due to text wrapping (so if lines are truncated, the wrap-prefix is
3209 never used). It may be a string or an image (@pxref{Other Display
3210 Specs}), or a stretch of whitespace such as specified by the
3211 @code{:width} or @code{:align-to} display properties (@pxref{Specified
3214 A wrap-prefix may also be specified for an entire buffer using the
3215 @code{wrap-prefix} buffer-local variable (however, a
3216 @code{wrap-prefix} text-property takes precedence over the value of
3217 the @code{wrap-prefix} variable). @xref{Truncation}.
3220 If text has a @code{line-prefix} property, the prefix it defines will
3221 be added at display time to the beginning of every non-continuation
3222 line. It may be a string or an image (@pxref{Other Display
3223 Specs}), or a stretch of whitespace such as specified by the
3224 @code{:width} or @code{:align-to} display properties (@pxref{Specified
3227 A line-prefix may also be specified for an entire buffer using the
3228 @code{line-prefix} buffer-local variable (however, a
3229 @code{line-prefix} text-property takes precedence over the value of
3230 the @code{line-prefix} variable). @xref{Truncation}.
3232 @item modification-hooks
3233 @cindex change hooks for a character
3234 @cindex hooks for changing a character
3235 @kindex modification-hooks @r{(text property)}
3236 If a character has the property @code{modification-hooks}, then its
3237 value should be a list of functions; modifying that character calls
3238 all of those functions before the actual modification. Each function
3239 receives two arguments: the beginning and end of the part of the
3240 buffer being modified. Note that if a particular modification hook
3241 function appears on several characters being modified by a single
3242 primitive, you can't predict how many times the function will
3244 Furthermore, insertion will not modify any existing character, so this
3245 hook will only be run when removing some characters, replacing them
3246 with others, or changing their text-properties.
3248 If these functions modify the buffer, they should bind
3249 @code{inhibit-modification-hooks} to @code{t} around doing so, to
3250 avoid confusing the internal mechanism that calls these hooks.
3252 Overlays also support the @code{modification-hooks} property, but the
3253 details are somewhat different (@pxref{Overlay Properties}).
3255 @item insert-in-front-hooks
3256 @itemx insert-behind-hooks
3257 @kindex insert-in-front-hooks @r{(text property)}
3258 @kindex insert-behind-hooks @r{(text property)}
3259 The operation of inserting text in a buffer also calls the functions
3260 listed in the @code{insert-in-front-hooks} property of the following
3261 character and in the @code{insert-behind-hooks} property of the
3262 preceding character. These functions receive two arguments, the
3263 beginning and end of the inserted text. The functions are called
3264 @emph{after} the actual insertion takes place.
3266 See also @ref{Change Hooks}, for other hooks that are called
3267 when you change text in a buffer.
3271 @cindex hooks for motion of point
3272 @kindex point-entered @r{(text property)}
3273 @kindex point-left @r{(text property)}
3274 The special properties @code{point-entered} and @code{point-left}
3275 record hook functions that report motion of point. Each time point
3276 moves, Emacs compares these two property values:
3280 the @code{point-left} property of the character after the old location,
3283 the @code{point-entered} property of the character after the new
3288 If these two values differ, each of them is called (if not @code{nil})
3289 with two arguments: the old value of point, and the new one.
3291 The same comparison is made for the characters before the old and new
3292 locations. The result may be to execute two @code{point-left} functions
3293 (which may be the same function) and/or two @code{point-entered}
3294 functions (which may be the same function). In any case, all the
3295 @code{point-left} functions are called first, followed by all the
3296 @code{point-entered} functions.
3298 It is possible to use @code{char-after} to examine characters at various
3299 buffer positions without moving point to those positions. Only an
3300 actual change in the value of point runs these hook functions.
3302 The variable @code{inhibit-point-motion-hooks} can inhibit running the
3303 @code{point-left} and @code{point-entered} hooks, see @ref{Inhibit
3304 point motion hooks}.
3307 @kindex composition @r{(text property)}
3308 This text property is used to display a sequence of characters as a
3309 single glyph composed from components. But the value of the property
3310 itself is completely internal to Emacs and should not be manipulated
3311 directly by, for instance, @code{put-text-property}.
3315 @defvar inhibit-point-motion-hooks
3316 @anchor{Inhibit point motion hooks} When this variable is
3317 non-@code{nil}, @code{point-left} and @code{point-entered} hooks are
3318 not run, and the @code{intangible} property has no effect. Do not set
3319 this variable globally; bind it with @code{let}.
3322 @defvar show-help-function
3323 @anchor{Help display} If this variable is non-@code{nil}, it specifies a
3324 function called to display help strings. These may be @code{help-echo}
3325 properties, menu help strings (@pxref{Simple Menu Items},
3326 @pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
3327 Bar}). The specified function is called with one argument, the help
3328 string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs
3329 Manual}) provides an example.
3332 @node Format Properties
3333 @subsection Formatted Text Properties
3335 These text properties affect the behavior of the fill commands. They
3336 are used for representing formatted text. @xref{Filling}, and
3341 If a newline character has this property, it is a ``hard'' newline.
3342 The fill commands do not alter hard newlines and do not move words
3343 across them. However, this property takes effect only if the
3344 @code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft
3345 Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
3348 This property specifies an extra right margin for filling this part of the
3352 This property specifies an extra left margin for filling this part of the
3356 This property specifies the style of justification for filling this part
3360 @node Sticky Properties
3361 @subsection Stickiness of Text Properties
3362 @cindex sticky text properties
3363 @cindex inheritance of text properties
3365 Self-inserting characters normally take on the same properties as the
3366 preceding character. This is called @dfn{inheritance} of properties.
3368 In a Lisp program, you can do insertion with inheritance or without,
3369 depending on your choice of insertion primitive. The ordinary text
3370 insertion functions such as @code{insert} do not inherit any properties.
3371 They insert text with precisely the properties of the string being
3372 inserted, and no others. This is correct for programs that copy text
3373 from one context to another---for example, into or out of the kill ring.
3374 To insert with inheritance, use the special primitives described in this
3375 section. Self-inserting characters inherit properties because they work
3376 using these primitives.
3378 When you do insertion with inheritance, @emph{which} properties are
3379 inherited, and from where, depends on which properties are @dfn{sticky}.
3380 Insertion after a character inherits those of its properties that are
3381 @dfn{rear-sticky}. Insertion before a character inherits those of its
3382 properties that are @dfn{front-sticky}. When both sides offer different
3383 sticky values for the same property, the previous character's value
3386 By default, a text property is rear-sticky but not front-sticky; thus,
3387 the default is to inherit all the properties of the preceding character,
3388 and nothing from the following character.
3390 You can control the stickiness of various text properties with two
3391 specific text properties, @code{front-sticky} and @code{rear-nonsticky},
3392 and with the variable @code{text-property-default-nonsticky}. You can
3393 use the variable to specify a different default for a given property.
3394 You can use those two text properties to make any specific properties
3395 sticky or nonsticky in any particular part of the text.
3397 If a character's @code{front-sticky} property is @code{t}, then all
3398 its properties are front-sticky. If the @code{front-sticky} property is
3399 a list, then the sticky properties of the character are those whose
3400 names are in the list. For example, if a character has a
3401 @code{front-sticky} property whose value is @code{(face read-only)},
3402 then insertion before the character can inherit its @code{face} property
3403 and its @code{read-only} property, but no others.
3405 The @code{rear-nonsticky} property works the opposite way. Most
3406 properties are rear-sticky by default, so the @code{rear-nonsticky}
3407 property says which properties are @emph{not} rear-sticky. If a
3408 character's @code{rear-nonsticky} property is @code{t}, then none of its
3409 properties are rear-sticky. If the @code{rear-nonsticky} property is a
3410 list, properties are rear-sticky @emph{unless} their names are in the
3413 @defvar text-property-default-nonsticky
3414 This variable holds an alist which defines the default rear-stickiness
3415 of various text properties. Each element has the form
3416 @code{(@var{property} . @var{nonstickiness})}, and it defines the
3417 stickiness of a particular text property, @var{property}.
3419 If @var{nonstickiness} is non-@code{nil}, this means that the property
3420 @var{property} is rear-nonsticky by default. Since all properties are
3421 front-nonsticky by default, this makes @var{property} nonsticky in both
3422 directions by default.
3424 The text properties @code{front-sticky} and @code{rear-nonsticky}, when
3425 used, take precedence over the default @var{nonstickiness} specified in
3426 @code{text-property-default-nonsticky}.
3429 Here are the functions that insert text with inheritance of properties:
3431 @defun insert-and-inherit &rest strings
3432 Insert the strings @var{strings}, just like the function @code{insert},
3433 but inherit any sticky properties from the adjoining text.
3436 @defun insert-before-markers-and-inherit &rest strings
3437 Insert the strings @var{strings}, just like the function
3438 @code{insert-before-markers}, but inherit any sticky properties from the
3442 @xref{Insertion}, for the ordinary insertion functions which do not
3445 @node Lazy Properties
3446 @subsection Lazy Computation of Text Properties
3448 Instead of computing text properties for all the text in the buffer,
3449 you can arrange to compute the text properties for parts of the text
3450 when and if something depends on them.
3452 The primitive that extracts text from the buffer along with its
3453 properties is @code{buffer-substring}. Before examining the properties,
3454 this function runs the abnormal hook @code{buffer-access-fontify-functions}.
3456 @defvar buffer-access-fontify-functions
3457 This variable holds a list of functions for computing text properties.
3458 Before @code{buffer-substring} copies the text and text properties for a
3459 portion of the buffer, it calls all the functions in this list. Each of
3460 the functions receives two arguments that specify the range of the
3461 buffer being accessed. (The buffer itself is always the current
3465 The function @code{buffer-substring-no-properties} does not call these
3466 functions, since it ignores text properties anyway.
3468 In order to prevent the hook functions from being called more than
3469 once for the same part of the buffer, you can use the variable
3470 @code{buffer-access-fontified-property}.
3472 @defvar buffer-access-fontified-property
3473 If this variable's value is non-@code{nil}, it is a symbol which is used
3474 as a text property name. A non-@code{nil} value for that text property
3475 means, ``the other text properties for this character have already been
3478 If all the characters in the range specified for @code{buffer-substring}
3479 have a non-@code{nil} value for this property, @code{buffer-substring}
3480 does not call the @code{buffer-access-fontify-functions} functions. It
3481 assumes these characters already have the right text properties, and
3482 just copies the properties they already have.
3484 The normal way to use this feature is that the
3485 @code{buffer-access-fontify-functions} functions add this property, as
3486 well as others, to the characters they operate on. That way, they avoid
3487 being called over and over for the same text.
3490 @node Clickable Text
3491 @subsection Defining Clickable Text
3492 @cindex clickable text
3493 @cindex follow links
3496 @dfn{Clickable text} is text that can be clicked, with either the
3497 mouse or via a keyboard command, to produce some result. Many major
3498 modes use clickable text to implement textual hyper-links, or
3499 @dfn{links} for short.
3501 The easiest way to insert and manipulate links is to use the
3502 @code{button} package. @xref{Buttons}. In this section, we will
3503 explain how to manually set up clickable text in a buffer, using text
3504 properties. For simplicity, we will refer to the clickable text as a
3507 Implementing a link involves three separate steps: (1) indicating
3508 clickability when the mouse moves over the link; (2) making @kbd{RET}
3509 or @kbd{Mouse-2} on that link do something; and (3) setting up a
3510 @code{follow-link} condition so that the link obeys
3511 @code{mouse-1-click-follows-link}.
3513 To indicate clickability, add the @code{mouse-face} text property to
3514 the text of the link; then Emacs will highlight the link when the
3515 mouse moves over it. In addition, you should define a tooltip or echo
3516 area message, using the @code{help-echo} text property. @xref{Special
3517 Properties}. For instance, here is how Dired indicates that file
3518 names are clickable:
3521 (if (dired-move-to-filename)
3522 (add-text-properties
3525 (dired-move-to-end-of-filename)
3527 '(mouse-face highlight
3528 help-echo "mouse-2: visit this file in other window")))
3531 To make the link clickable, bind @key{RET} and @kbd{Mouse-2} to
3532 commands that perform the desired action. Each command should check
3533 to see whether it was called on a link, and act accordingly. For
3534 instance, Dired's major mode keymap binds @kbd{Mouse-2} to the
3538 (defun dired-mouse-find-file-other-window (event)
3539 "In Dired, visit the file or directory name you click on."
3541 (let ((window (posn-window (event-end event)))
3542 (pos (posn-point (event-end event)))
3544 (if (not (windowp window))
3545 (error "No file chosen"))
3546 (with-current-buffer (window-buffer window)
3548 (setq file (dired-get-file-for-visit)))
3549 (if (file-directory-p file)
3550 (or (and (cdr dired-subdir-alist)
3551 (dired-goto-subdir file))
3553 (select-window window)
3554 (dired-other-window file)))
3555 (select-window window)
3556 (find-file-other-window (file-name-sans-versions file t)))))
3560 This command uses the functions @code{posn-window} and
3561 @code{posn-point} to determine where the click occurred, and
3562 @code{dired-get-file-for-visit} to determine which file to visit.
3564 Instead of binding the mouse command in a major mode keymap, you can
3565 bind it within the link text, using the @code{keymap} text property
3566 (@pxref{Special Properties}). For instance:
3569 (let ((map (make-sparse-keymap)))
3570 (define-key map [mouse-2] 'operate-this-button)
3571 (put-text-property link-start link-end 'keymap map))
3575 With this method, you can easily define different commands for
3576 different links. Furthermore, the global definition of @key{RET} and
3577 @kbd{Mouse-2} remain available for the rest of the text in the buffer.
3579 @vindex mouse-1-click-follows-link
3580 The basic Emacs command for clicking on links is @kbd{Mouse-2}.
3581 However, for compatibility with other graphical applications, Emacs
3582 also recognizes @kbd{Mouse-1} clicks on links, provided the user
3583 clicks on the link quickly without moving the mouse. This behavior is
3584 controlled by the user option @code{mouse-1-click-follows-link}.
3585 @xref{Mouse References,,, emacs, The GNU Emacs Manual}.
3587 To set up the link so that it obeys
3588 @code{mouse-1-click-follows-link}, you must either (1) apply a
3589 @code{follow-link} text or overlay property to the link text, or (2)
3590 bind the @code{follow-link} event to a keymap (which can be a major
3591 mode keymap or a local keymap specified via the @code{keymap} text
3592 property). The value of the @code{follow-link} property, or the
3593 binding for the @code{follow-link} event, acts as a ``condition'' for
3594 the link action. This condition tells Emacs two things: the
3595 circumstances under which a @kbd{Mouse-1} click should be regarded as
3596 occurring ``inside'' the link, and how to compute an ``action code''
3597 that says what to translate the @kbd{Mouse-1} click into. The link
3598 action condition can be one of the following:
3601 @item @code{mouse-face}
3602 If the condition is the symbol @code{mouse-face}, a position is inside
3603 a link if there is a non-@code{nil} @code{mouse-face} property at that
3604 position. The action code is always @code{t}.
3606 For example, here is how Info mode handles @key{Mouse-1}:
3609 (define-key Info-mode-map [follow-link] 'mouse-face)
3613 If the condition is a function, @var{func}, then a position @var{pos}
3614 is inside a link if @code{(@var{func} @var{pos})} evaluates to
3615 non-@code{nil}. The value returned by @var{func} serves as the action
3618 For example, here is how pcvs enables @kbd{Mouse-1} to follow links on
3622 (define-key map [follow-link]
3624 (eq (get-char-property pos 'face) 'cvs-filename-face)))
3628 If the condition value is anything else, then the position is inside a
3629 link and the condition itself is the action code. Clearly, you should
3630 specify this kind of condition only when applying the condition via a
3631 text or property overlay on the link text (so that it does not apply
3632 to the entire buffer).
3636 The action code tells @kbd{Mouse-1} how to follow the link:
3639 @item a string or vector
3640 If the action code is a string or vector, the @kbd{Mouse-1} event is
3641 translated into the first element of the string or vector; i.e., the
3642 action of the @kbd{Mouse-1} click is the local or global binding of
3643 that character or symbol. Thus, if the action code is @code{"foo"},
3644 @kbd{Mouse-1} translates into @kbd{f}. If it is @code{[foo]},
3645 @kbd{Mouse-1} translates into @key{foo}.
3648 For any other non-@code{nil} action code, the @kbd{Mouse-1} event is
3649 translated into a @kbd{Mouse-2} event at the same position.
3652 To define @kbd{Mouse-1} to activate a button defined with
3653 @code{define-button-type}, give the button a @code{follow-link}
3654 property. The property value should be a link action condition, as
3655 described above. @xref{Buttons}. For example, here is how Help mode
3656 handles @kbd{Mouse-1}:
3659 (define-button-type 'help-xref
3661 'action #'help-button-action)
3664 To define @kbd{Mouse-1} on a widget defined with
3665 @code{define-widget}, give the widget a @code{:follow-link} property.
3666 The property value should be a link action condition, as described
3667 above. For example, here is how the @code{link} widget specifies that
3668 a @key{Mouse-1} click shall be translated to @key{RET}:
3671 (define-widget 'link 'item
3673 :button-prefix 'widget-link-prefix
3674 :button-suffix 'widget-link-suffix
3676 :help-echo "Follow the link."
3680 @defun mouse-on-link-p pos
3681 This function returns non-@code{nil} if position @var{pos} in the
3682 current buffer is on a link. @var{pos} can also be a mouse event
3683 location, as returned by @code{event-start} (@pxref{Accessing Mouse}).
3687 @subsection Defining and Using Fields
3690 A field is a range of consecutive characters in the buffer that are
3691 identified by having the same value (comparing with @code{eq}) of the
3692 @code{field} property (either a text-property or an overlay property).
3693 This section describes special functions that are available for
3694 operating on fields.
3696 You specify a field with a buffer position, @var{pos}. We think of
3697 each field as containing a range of buffer positions, so the position
3698 you specify stands for the field containing that position.
3700 When the characters before and after @var{pos} are part of the same
3701 field, there is no doubt which field contains @var{pos}: the one those
3702 characters both belong to. When @var{pos} is at a boundary between
3703 fields, which field it belongs to depends on the stickiness of the
3704 @code{field} properties of the two surrounding characters (@pxref{Sticky
3705 Properties}). The field whose property would be inherited by text
3706 inserted at @var{pos} is the field that contains @var{pos}.
3708 There is an anomalous case where newly inserted text at @var{pos}
3709 would not inherit the @code{field} property from either side. This
3710 happens if the previous character's @code{field} property is not
3711 rear-sticky, and the following character's @code{field} property is not
3712 front-sticky. In this case, @var{pos} belongs to neither the preceding
3713 field nor the following field; the field functions treat it as belonging
3714 to an empty field whose beginning and end are both at @var{pos}.
3716 In all of these functions, if @var{pos} is omitted or @code{nil}, the
3717 value of point is used by default. If narrowing is in effect, then
3718 @var{pos} should fall within the accessible portion. @xref{Narrowing}.
3720 @defun field-beginning &optional pos escape-from-edge limit
3721 This function returns the beginning of the field specified by @var{pos}.
3723 If @var{pos} is at the beginning of its field, and
3724 @var{escape-from-edge} is non-@code{nil}, then the return value is
3725 always the beginning of the preceding field that @emph{ends} at @var{pos},
3726 regardless of the stickiness of the @code{field} properties around
3729 If @var{limit} is non-@code{nil}, it is a buffer position; if the
3730 beginning of the field is before @var{limit}, then @var{limit} will be
3734 @defun field-end &optional pos escape-from-edge limit
3735 This function returns the end of the field specified by @var{pos}.
3737 If @var{pos} is at the end of its field, and @var{escape-from-edge} is
3738 non-@code{nil}, then the return value is always the end of the following
3739 field that @emph{begins} at @var{pos}, regardless of the stickiness of
3740 the @code{field} properties around @var{pos}.
3742 If @var{limit} is non-@code{nil}, it is a buffer position; if the end
3743 of the field is after @var{limit}, then @var{limit} will be returned
3747 @defun field-string &optional pos
3748 This function returns the contents of the field specified by @var{pos},
3752 @defun field-string-no-properties &optional pos
3753 This function returns the contents of the field specified by @var{pos},
3754 as a string, discarding text properties.
3757 @defun delete-field &optional pos
3758 This function deletes the text of the field specified by @var{pos}.
3761 @defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
3762 This function ``constrains'' @var{new-pos} to the field that
3763 @var{old-pos} belongs to---in other words, it returns the position
3764 closest to @var{new-pos} that is in the same field as @var{old-pos}.
3766 If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
3767 the value of point instead, and moves point to the resulting position
3768 as well as returning it.
3770 If @var{old-pos} is at the boundary of two fields, then the acceptable
3771 final positions depend on the argument @var{escape-from-edge}. If
3772 @var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in
3773 the field whose @code{field} property equals what new characters
3774 inserted at @var{old-pos} would inherit. (This depends on the
3775 stickiness of the @code{field} property for the characters before and
3776 after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
3777 @var{new-pos} can be anywhere in the two adjacent fields.
3778 Additionally, if two fields are separated by another field with the
3779 special value @code{boundary}, then any point within this special
3780 field is also considered to be ``on the boundary.''
3782 Commands like @kbd{C-a} with no argument, that normally move backward
3783 to a specific kind of location and stay there once there, probably
3784 should specify @code{nil} for @var{escape-from-edge}. Other motion
3785 commands that check fields should probably pass @code{t}.
3787 If the optional argument @var{only-in-line} is non-@code{nil}, and
3788 constraining @var{new-pos} in the usual way would move it to a different
3789 line, @var{new-pos} is returned unconstrained. This used in commands
3790 that move by line, such as @code{next-line} and
3791 @code{beginning-of-line}, so that they respect field boundaries only in
3792 the case where they can still move to the right line.
3794 If the optional argument @var{inhibit-capture-property} is
3795 non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that
3796 name, then any field boundaries are ignored.
3798 You can cause @code{constrain-to-field} to ignore all field boundaries
3799 (and so never constrain anything) by binding the variable
3800 @code{inhibit-field-text-motion} to a non-@code{nil} value.
3804 @subsection Why Text Properties are not Intervals
3807 Some editors that support adding attributes to text in the buffer do
3808 so by letting the user specify ``intervals'' within the text, and adding
3809 the properties to the intervals. Those editors permit the user or the
3810 programmer to determine where individual intervals start and end. We
3811 deliberately provided a different sort of interface in Emacs Lisp to
3812 avoid certain paradoxical behavior associated with text modification.
3814 If the actual subdivision into intervals is meaningful, that means you
3815 can distinguish between a buffer that is just one interval with a
3816 certain property, and a buffer containing the same text subdivided into
3817 two intervals, both of which have that property.
3819 Suppose you take the buffer with just one interval and kill part of
3820 the text. The text remaining in the buffer is one interval, and the
3821 copy in the kill ring (and the undo list) becomes a separate interval.
3822 Then if you yank back the killed text, you get two intervals with the
3823 same properties. Thus, editing does not preserve the distinction
3824 between one interval and two.
3826 Suppose we ``fix'' this problem by coalescing the two intervals when
3827 the text is inserted. That works fine if the buffer originally was a
3828 single interval. But suppose instead that we have two adjacent
3829 intervals with the same properties, and we kill the text of one interval
3830 and yank it back. The same interval-coalescence feature that rescues
3831 the other case causes trouble in this one: after yanking, we have just
3832 one interval. One again, editing does not preserve the distinction
3833 between one interval and two.
3835 Insertion of text at the border between intervals also raises
3836 questions that have no satisfactory answer.
3838 However, it is easy to arrange for editing to behave consistently for
3839 questions of the form, ``What are the properties of this character?''
3840 So we have decided these are the only questions that make sense; we have
3841 not implemented asking questions about where intervals start or end.
3843 In practice, you can usually use the text property search functions in
3844 place of explicit interval boundaries. You can think of them as finding
3845 the boundaries of intervals, assuming that intervals are always
3846 coalesced whenever possible. @xref{Property Search}.
3848 Emacs also provides explicit intervals as a presentation feature; see
3852 @section Substituting for a Character Code
3854 The following functions replace characters within a specified region
3855 based on their character codes.
3857 @defun subst-char-in-region start end old-char new-char &optional noundo
3858 @cindex replace characters
3859 This function replaces all occurrences of the character @var{old-char}
3860 with the character @var{new-char} in the region of the current buffer
3861 defined by @var{start} and @var{end}.
3863 @cindex undo avoidance
3864 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
3865 not record the change for undo and does not mark the buffer as modified.
3866 This was useful for controlling the old selective display feature
3867 (@pxref{Selective Display}).
3869 @code{subst-char-in-region} does not move point and returns
3874 ---------- Buffer: foo ----------
3875 This is the contents of the buffer before.
3876 ---------- Buffer: foo ----------
3880 (subst-char-in-region 1 20 ?i ?X)
3883 ---------- Buffer: foo ----------
3884 ThXs Xs the contents of the buffer before.
3885 ---------- Buffer: foo ----------
3890 @deffn Command translate-region start end table
3891 This function applies a translation table to the characters in the
3892 buffer between positions @var{start} and @var{end}.
3894 The translation table @var{table} is a string or a char-table;
3895 @code{(aref @var{table} @var{ochar})} gives the translated character
3896 corresponding to @var{ochar}. If @var{table} is a string, any
3897 characters with codes larger than the length of @var{table} are not
3898 altered by the translation.
3900 The return value of @code{translate-region} is the number of
3901 characters that were actually changed by the translation. This does
3902 not count characters that were mapped into themselves in the
3910 A register is a sort of variable used in Emacs editing that can hold a
3911 variety of different kinds of values. Each register is named by a
3912 single character. All @acronym{ASCII} characters and their meta variants
3913 (but with the exception of @kbd{C-g}) can be used to name registers.
3914 Thus, there are 255 possible registers. A register is designated in
3915 Emacs Lisp by the character that is its name.
3917 @defvar register-alist
3918 This variable is an alist of elements of the form @code{(@var{name} .
3919 @var{contents})}. Normally, there is one element for each Emacs
3920 register that has been used.
3922 The object @var{name} is a character (an integer) identifying the
3926 The @var{contents} of a register can have several possible types:
3930 A number stands for itself. If @code{insert-register} finds a number
3931 in the register, it converts the number to decimal.
3934 A marker represents a buffer position to jump to.
3937 A string is text saved in the register.
3940 A rectangle is represented by a list of strings.
3942 @item @code{(@var{window-configuration} @var{position})}
3943 This represents a window configuration to restore in one frame, and a
3944 position to jump to in the current buffer.
3946 @item @code{(@var{frame-configuration} @var{position})}
3947 This represents a frame configuration to restore, and a position
3948 to jump to in the current buffer.
3950 @item (file @var{filename})
3951 This represents a file to visit; jumping to this value visits file
3954 @item (file-query @var{filename} @var{position})
3955 This represents a file to visit and a position in it; jumping to this
3956 value visits file @var{filename} and goes to buffer position
3957 @var{position}. Restoring this type of position asks the user for
3961 The functions in this section return unpredictable values unless
3964 @defun get-register reg
3965 This function returns the contents of the register
3966 @var{reg}, or @code{nil} if it has no contents.
3969 @defun set-register reg value
3970 This function sets the contents of register @var{reg} to @var{value}.
3971 A register can be set to any value, but the other register functions
3972 expect only certain data types. The return value is @var{value}.
3975 @deffn Command view-register reg
3976 This command displays what is contained in register @var{reg}.
3979 @deffn Command insert-register reg &optional beforep
3980 This command inserts contents of register @var{reg} into the current
3983 Normally, this command puts point before the inserted text, and the
3984 mark after it. However, if the optional second argument @var{beforep}
3985 is non-@code{nil}, it puts the mark before and point after.
3986 You can pass a non-@code{nil} second argument @var{beforep} to this
3987 function interactively by supplying any prefix argument.
3989 If the register contains a rectangle, then the rectangle is inserted
3990 with its upper left corner at point. This means that text is inserted
3991 in the current line and underneath it on successive lines.
3993 If the register contains something other than saved text (a string) or
3994 a rectangle (a list), currently useless things happen. This may be
3995 changed in the future.
3999 @section Transposition of Text
4001 This function can be used to transpose stretches of text:
4003 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
4004 This function exchanges two nonoverlapping portions of the buffer.
4005 Arguments @var{start1} and @var{end1} specify the bounds of one portion
4006 and arguments @var{start2} and @var{end2} specify the bounds of the
4009 Normally, @code{transpose-regions} relocates markers with the transposed
4010 text; a marker previously positioned within one of the two transposed
4011 portions moves along with that portion, thus remaining between the same
4012 two characters in their new position. However, if @var{leave-markers}
4013 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
4014 all markers unrelocated.
4018 @section Base 64 Encoding
4019 @cindex base 64 encoding
4021 Base 64 code is used in email to encode a sequence of 8-bit bytes as
4022 a longer sequence of @acronym{ASCII} graphic characters. It is defined in
4023 Internet RFC@footnote{
4024 An RFC, an acronym for @dfn{Request for Comments}, is a numbered
4025 Internet informational document describing a standard. RFCs are
4026 usually written by technical experts acting on their own initiative,
4027 and are traditionally written in a pragmatic, experience-driven
4029 }2045. This section describes the functions for
4030 converting to and from this code.
4032 @deffn Command base64-encode-region beg end &optional no-line-break
4033 This function converts the region from @var{beg} to @var{end} into base
4034 64 code. It returns the length of the encoded text. An error is
4035 signaled if a character in the region is multibyte, i.e.@: in a
4036 multibyte buffer the region must contain only characters from the
4037 charsets @code{ascii}, @code{eight-bit-control} and
4038 @code{eight-bit-graphic}.
4040 Normally, this function inserts newline characters into the encoded
4041 text, to avoid overlong lines. However, if the optional argument
4042 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
4043 the output is just one long line.
4046 @deffn Command base64-encode-string string &optional no-line-break
4047 This function converts the string @var{string} into base 64 code. It
4048 returns a string containing the encoded text. As for
4049 @code{base64-encode-region}, an error is signaled if a character in the
4050 string is multibyte.
4052 Normally, this function inserts newline characters into the encoded
4053 text, to avoid overlong lines. However, if the optional argument
4054 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
4055 the result string is just one long line.
4058 @defun base64-decode-region beg end
4059 This function converts the region from @var{beg} to @var{end} from base
4060 64 code into the corresponding decoded text. It returns the length of
4063 The decoding functions ignore newline characters in the encoded text.
4066 @defun base64-decode-string string
4067 This function converts the string @var{string} from base 64 code into
4068 the corresponding decoded text. It returns a unibyte string containing the
4071 The decoding functions ignore newline characters in the encoded text.
4075 @section Checksum/Hash
4076 @cindex MD5 checksum
4077 @cindex hashing, secure
4079 @cindex message digest computation
4081 MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit
4082 ``fingerprints'' of a document or program. They are used to verify
4083 that you have an exact and unaltered copy of the data. The algorithm
4084 to calculate the MD5 message digest is defined in Internet
4086 For an explanation of what is an RFC, see the footnote in @ref{Base
4088 }1321. This section describes the Emacs facilities for computing
4089 message digests and other forms of ``secure hash''.
4091 @defun md5 object &optional start end coding-system noerror
4092 This function returns the MD5 message digest of @var{object}, which
4093 should be a buffer or a string.
4095 The two optional arguments @var{start} and @var{end} are character
4096 positions specifying the portion of @var{object} to compute the
4097 message digest for. If they are @code{nil} or omitted, the digest is
4098 computed for the whole of @var{object}.
4100 The function @code{md5} does not compute the message digest directly
4101 from the internal Emacs representation of the text (@pxref{Text
4102 Representations}). Instead, it encodes the text using a coding
4103 system, and computes the message digest from the encoded text. The
4104 optional fourth argument @var{coding-system} specifies which coding
4105 system to use for encoding the text. It should be the same coding
4106 system that you used to read the text, or that you used or will use
4107 when saving or sending the text. @xref{Coding Systems}, for more
4108 information about coding systems.
4110 If @var{coding-system} is @code{nil} or omitted, the default depends
4111 on @var{object}. If @var{object} is a buffer, the default for
4112 @var{coding-system} is whatever coding system would be chosen by
4113 default for writing this text into a file. If @var{object} is a
4114 string, the user's most preferred coding system (@pxref{Recognize
4115 Coding, prefer-coding-system, the description of
4116 @code{prefer-coding-system}, emacs, GNU Emacs Manual}) is used.
4118 Normally, @code{md5} signals an error if the text can't be encoded
4119 using the specified or chosen coding system. However, if
4120 @var{noerror} is non-@code{nil}, it silently uses @code{raw-text}
4124 @defun secure-hash algorithm object &optional start end binary
4125 This function provides a general interface to a variety of secure
4126 hashing algorithms. As well as the MD5 algorithm, it supports SHA-1,
4127 SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512. The argument
4128 @var{algorithm} is a symbol stating which hash to compute. The
4129 arguments @var{object}, @var{start}, and @var{end} are as for the
4130 @code{md5} function. If the optional argument @var{binary} is
4131 non-@code{nil}, returns a string in binary form.
4135 @section Parsing HTML
4136 @cindex parsing html
4138 @defun libxml-parse-html-region start end &optional base-url
4139 This function provides HTML parsing via the @code{libxml2} library.
4140 It parses ``real world'' HTML and tries to return a sensible parse tree
4143 In addition to @var{start} and @var{end} (specifying the start and end
4144 of the region to act on), it takes an optional parameter,
4145 @var{base-url}, which is used to expand relative URLs in the document,
4148 Here's an example demonstrating the structure of the parsed data you
4149 get out. Given this HTML document:
4152 <html><hEad></head><body width=101><div class=thing>Foo<div>Yes
4155 You get this parse tree:
4166 (text . "Yes\n")))))
4169 It's a simple tree structure, where the @code{car} for each node is
4170 the name of the node, and the @code{cdr} is the value, or the list of
4173 Attributes are coded the same way as child nodes, but with @samp{:} as
4174 the first character.
4178 @defun libxml-parse-xml-region start end &optional base-url
4180 This is much the same as @code{libxml-parse-html-region} above, but
4181 operates on XML instead of HTML, and is correspondingly stricter about
4185 @node Atomic Changes
4186 @section Atomic Change Groups
4187 @cindex atomic changes
4189 In database terminology, an @dfn{atomic} change is an indivisible
4190 change---it can succeed entirely or it can fail entirely, but it
4191 cannot partly succeed. A Lisp program can make a series of changes to
4192 one or several buffers as an @dfn{atomic change group}, meaning that
4193 either the entire series of changes will be installed in their buffers
4194 or, in case of an error, none of them will be.
4196 To do this for one buffer, the one already current, simply write a
4197 call to @code{atomic-change-group} around the code that makes the
4201 (atomic-change-group
4203 (delete-region x y))
4207 If an error (or other nonlocal exit) occurs inside the body of
4208 @code{atomic-change-group}, it unmakes all the changes in that buffer
4209 that were during the execution of the body. This kind of change group
4210 has no effect on any other buffers---any such changes remain.
4212 If you need something more sophisticated, such as to make changes in
4213 various buffers constitute one atomic group, you must directly call
4214 lower-level functions that @code{atomic-change-group} uses.
4216 @defun prepare-change-group &optional buffer
4217 This function sets up a change group for buffer @var{buffer}, which
4218 defaults to the current buffer. It returns a ``handle'' that
4219 represents the change group. You must use this handle to activate the
4220 change group and subsequently to finish it.
4223 To use the change group, you must @dfn{activate} it. You must do
4224 this before making any changes in the text of @var{buffer}.
4226 @defun activate-change-group handle
4227 This function activates the change group that @var{handle} designates.
4230 After you activate the change group, any changes you make in that
4231 buffer become part of it. Once you have made all the desired changes
4232 in the buffer, you must @dfn{finish} the change group. There are two
4233 ways to do this: you can either accept (and finalize) all the changes,
4236 @defun accept-change-group handle
4237 This function accepts all the changes in the change group specified by
4238 @var{handle}, making them final.
4241 @defun cancel-change-group handle
4242 This function cancels and undoes all the changes in the change group
4243 specified by @var{handle}.
4246 Your code should use @code{unwind-protect} to make sure the group is
4247 always finished. The call to @code{activate-change-group} should be
4248 inside the @code{unwind-protect}, in case the user types @kbd{C-g}
4249 just after it runs. (This is one reason why
4250 @code{prepare-change-group} and @code{activate-change-group} are
4251 separate functions, because normally you would call
4252 @code{prepare-change-group} before the start of that
4253 @code{unwind-protect}.) Once you finish the group, don't use the
4254 handle again---in particular, don't try to finish the same group
4257 To make a multibuffer change group, call @code{prepare-change-group}
4258 once for each buffer you want to cover, then use @code{nconc} to
4259 combine the returned values, like this:
4262 (nconc (prepare-change-group buffer-1)
4263 (prepare-change-group buffer-2))
4266 You can then activate the multibuffer change group with a single call
4267 to @code{activate-change-group}, and finish it with a single call to
4268 @code{accept-change-group} or @code{cancel-change-group}.
4270 Nested use of several change groups for the same buffer works as you
4271 would expect. Non-nested use of change groups for the same buffer
4272 will get Emacs confused, so don't let it happen; the first change
4273 group you start for any given buffer should be the last one finished.
4276 @section Change Hooks
4277 @cindex change hooks
4278 @cindex hooks for text changes
4280 These hook variables let you arrange to take notice of all changes in
4281 all buffers (or in a particular buffer, if you make them buffer-local).
4282 See also @ref{Special Properties}, for how to detect changes to specific
4285 The functions you use in these hooks should save and restore the match
4286 data if they do anything that uses regular expressions; otherwise, they
4287 will interfere in bizarre ways with the editing operations that call
4290 @defvar before-change-functions
4291 This variable holds a list of functions to call before any buffer
4292 modification. Each function gets two arguments, the beginning and end
4293 of the region that is about to change, represented as integers. The
4294 buffer that is about to change is always the current buffer.
4297 @defvar after-change-functions
4298 This variable holds a list of functions to call after any buffer
4299 modification. Each function receives three arguments: the beginning and
4300 end of the region just changed, and the length of the text that existed
4301 before the change. All three arguments are integers. The buffer that's
4302 about to change is always the current buffer.
4304 The length of the old text is the difference between the buffer positions
4305 before and after that text as it was before the change. As for the
4306 changed text, its length is simply the difference between the first two
4310 Output of messages into the @samp{*Messages*} buffer does not
4311 call these functions.
4313 @defmac combine-after-change-calls body@dots{}
4314 The macro executes @var{body} normally, but arranges to call the
4315 after-change functions just once for a series of several changes---if
4318 If a program makes several text changes in the same area of the buffer,
4319 using the macro @code{combine-after-change-calls} around that part of
4320 the program can make it run considerably faster when after-change hooks
4321 are in use. When the after-change hooks are ultimately called, the
4322 arguments specify a portion of the buffer including all of the changes
4323 made within the @code{combine-after-change-calls} body.
4325 @strong{Warning:} You must not alter the values of
4326 @code{after-change-functions} within
4327 the body of a @code{combine-after-change-calls} form.
4329 @strong{Warning:} if the changes you combine occur in widely scattered
4330 parts of the buffer, this will still work, but it is not advisable,
4331 because it may lead to inefficient behavior for some change hook
4335 @defvar first-change-hook
4336 This variable is a normal hook that is run whenever a buffer is changed
4337 that was previously in the unmodified state.
4340 @defvar inhibit-modification-hooks
4341 If this variable is non-@code{nil}, all of the change hooks are
4342 disabled; none of them run. This affects all the hook variables
4343 described above in this section, as well as the hooks attached to
4344 certain special text properties (@pxref{Special Properties}) and overlay
4345 properties (@pxref{Overlay Properties}).
4347 Also, this variable is bound to non-@code{nil} while running those
4348 same hook variables, so that by default modifying the buffer from
4349 a modification hook does not cause other modification hooks to be run.
4350 If you do want modification hooks to be run in a particular piece of
4351 code that is itself run from a modification hook, then rebind locally
4352 @code{inhibit-modification-hooks} to @code{nil}.