2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @node Text, Non-ASCII Characters, Markers, Top
9 This chapter describes the functions that deal with the text in a
10 buffer. Most examine, insert, or delete text in the current buffer,
11 often operating at point or on text adjacent to point. Many are
12 interactive. All the functions that change the text provide for undoing
13 the changes (@pxref{Undo}).
15 Many text-related functions operate on a region of text defined by two
16 buffer positions passed in arguments named @var{start} and @var{end}.
17 These arguments should be either markers (@pxref{Markers}) or numeric
18 character positions (@pxref{Positions}). The order of these arguments
19 does not matter; it is all right for @var{start} to be the end of the
20 region and @var{end} the beginning. For example, @code{(delete-region 1
21 10)} and @code{(delete-region 10 1)} are equivalent. An
22 @code{args-out-of-range} error is signaled if either @var{start} or
23 @var{end} is outside the accessible portion of the buffer. In an
24 interactive call, point and the mark are used for these arguments.
26 @cindex buffer contents
27 Throughout this chapter, ``text'' refers to the characters in the
28 buffer, together with their properties (when relevant). Keep in mind
29 that point is always between two characters, and the cursor appears on
30 the character after point.
33 * Near Point:: Examining text in the vicinity of point.
34 * Buffer Contents:: Examining text in a general fashion.
35 * Comparing Text:: Comparing substrings of buffers.
36 * Insertion:: Adding new text to a buffer.
37 * Commands for Insertion:: User-level commands to insert text.
38 * Deletion:: Removing text from a buffer.
39 * User-Level Deletion:: User-level commands to delete text.
40 * The Kill Ring:: Where removed text sometimes is saved for later use.
41 * Undo:: Undoing changes to the text of a buffer.
42 * Maintaining Undo:: How to enable and disable undo information.
43 How to control how much information is kept.
44 * Filling:: Functions for explicit filling.
45 * Margins:: How to specify margins for filling commands.
46 * Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context.
47 * Auto Filling:: How auto-fill mode is implemented to break lines.
48 * Sorting:: Functions for sorting parts of the buffer.
49 * Columns:: Computing horizontal positions, and using them.
50 * Indentation:: Functions to insert or adjust indentation.
51 * Case Changes:: Case conversion of parts of the buffer.
52 * Text Properties:: Assigning Lisp property lists to text characters.
53 * Substitution:: Replacing a given character wherever it appears.
54 * Transposition:: Swapping two portions of a buffer.
55 * Registers:: How registers are implemented. Accessing the text or
56 position stored in a register.
57 * Base 64:: Conversion to or from base 64 encoding.
58 * Checksum/Hash:: Computing cryptographic hashes.
59 * Parsing HTML/XML:: Parsing HTML and XML.
60 * Atomic Changes:: Installing several buffer changes "atomically".
61 * Change Hooks:: Supplying functions to be run when text is changed.
65 @section Examining Text Near Point
66 @cindex text near point
68 Many functions are provided to look at the characters around point.
69 Several simple functions are described here. See also @code{looking-at}
70 in @ref{Regexp Search}.
72 In the following four functions, ``beginning'' or ``end'' of buffer
73 refers to the beginning or end of the accessible portion.
75 @defun char-after &optional position
76 This function returns the character in the current buffer at (i.e.,
77 immediately after) position @var{position}. If @var{position} is out of
78 range for this purpose, either before the beginning of the buffer, or at
79 or beyond the end, then the value is @code{nil}. The default for
80 @var{position} is point.
82 In the following example, assume that the first character in the
87 (string (char-after 1))
93 @defun char-before &optional position
94 This function returns the character in the current buffer immediately
95 before position @var{position}. If @var{position} is out of range for
96 this purpose, either at or before the beginning of the buffer, or beyond
97 the end, then the value is @code{nil}. The default for
98 @var{position} is point.
101 @defun following-char
102 This function returns the character following point in the current
103 buffer. This is similar to @code{(char-after (point))}. However, if
104 point is at the end of the buffer, then @code{following-char} returns 0.
106 Remember that point is always between characters, and the cursor
107 normally appears over the character following point. Therefore, the
108 character returned by @code{following-char} is the character the
111 In this example, point is between the @samp{a} and the @samp{c}.
115 ---------- Buffer: foo ----------
116 Gentlemen may cry ``Pea@point{}ce! Peace!,''
117 but there is no peace.
118 ---------- Buffer: foo ----------
122 (string (preceding-char))
124 (string (following-char))
130 @defun preceding-char
131 This function returns the character preceding point in the current
132 buffer. See above, under @code{following-char}, for an example. If
133 point is at the beginning of the buffer, @code{preceding-char} returns
138 This function returns @code{t} if point is at the beginning of the
139 buffer. If narrowing is in effect, this means the beginning of the
140 accessible portion of the text. See also @code{point-min} in
145 This function returns @code{t} if point is at the end of the buffer.
146 If narrowing is in effect, this means the end of accessible portion of
147 the text. See also @code{point-max} in @xref{Point}.
151 This function returns @code{t} if point is at the beginning of a line.
152 @xref{Text Lines}. The beginning of the buffer (or of its accessible
153 portion) always counts as the beginning of a line.
157 This function returns @code{t} if point is at the end of a line. The
158 end of the buffer (or of its accessible portion) is always considered
162 @node Buffer Contents
163 @section Examining Buffer Contents
165 This section describes functions that allow a Lisp program to
166 convert any portion of the text in the buffer into a string.
168 @defun buffer-substring start end
169 This function returns a string containing a copy of the text of the
170 region defined by positions @var{start} and @var{end} in the current
171 buffer. If the arguments are not positions in the accessible portion
172 of the buffer, @code{buffer-substring} signals an
173 @code{args-out-of-range} error.
175 Here's an example which assumes Font-Lock mode is not enabled:
179 ---------- Buffer: foo ----------
180 This is the contents of buffer foo
182 ---------- Buffer: foo ----------
186 (buffer-substring 1 10)
187 @result{} "This is t"
190 (buffer-substring (point-max) 10)
191 @result{} "he contents of buffer foo\n"
195 If the text being copied has any text properties, these are copied into
196 the string along with the characters they belong to. @xref{Text
197 Properties}. However, overlays (@pxref{Overlays}) in the buffer and
198 their properties are ignored, not copied.
200 For example, if Font-Lock mode is enabled, you might get results like
205 (buffer-substring 1 10)
206 @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t))
211 @defun buffer-substring-no-properties start end
212 This is like @code{buffer-substring}, except that it does not copy text
213 properties, just the characters themselves. @xref{Text Properties}.
217 This function returns the contents of the entire accessible portion of
218 the current buffer as a string. It is equivalent to
219 @w{@code{(buffer-substring (point-min) (point-max))}}.
222 @defun filter-buffer-substring start end &optional delete
223 This function passes the buffer text between @var{start} and @var{end}
224 through the filter functions specified by the wrapper hook
225 @code{filter-buffer-substring-functions}, and returns the result. The
226 obsolete variable @code{buffer-substring-filters} is also consulted.
227 If both of these variables are @code{nil}, the value is the unaltered
228 text from the buffer, i.e.@: what @code{buffer-substring} would
231 If @var{delete} is non-@code{nil}, this function deletes the text
232 between @var{start} and @var{end} after copying it, like
233 @code{delete-and-extract-region}.
235 Lisp code should use this function instead of @code{buffer-substring},
236 @code{buffer-substring-no-properties},
237 or @code{delete-and-extract-region} when copying into user-accessible
238 data structures such as the kill-ring, X clipboard, and registers.
239 Major and minor modes can add functions to
240 @code{filter-buffer-substring-functions} to alter such text as it is
241 copied out of the buffer.
244 @defvar filter-buffer-substring-functions
245 This variable is a wrapper hook (@pxref{Running Hooks}), whose members
246 should be functions that accept four arguments: @var{fun},
247 @var{start}, @var{end}, and @var{delete}. @var{fun} is a function
248 that takes three arguments (@var{start}, @var{end}, and @var{delete}),
249 and returns a string. In both cases, the @var{start}, @var{end}, and
250 @var{delete} arguments are the same as those of
251 @code{filter-buffer-substring}.
253 The first hook function is passed a @var{fun} that is equivalent to
254 the default operation of @code{filter-buffer-substring}, i.e. it
255 returns the buffer-substring between @var{start} and @var{end}
256 (processed by any @code{buffer-substring-filters}) and optionally
257 deletes the original text from the buffer. In most cases, the hook
258 function will call @var{fun} once, and then do its own processing of
259 the result. The next hook function receives a @var{fun} equivalent to
260 this, and so on. The actual return value is the result of all the
261 hook functions acting in sequence.
264 @defvar buffer-substring-filters
265 This variable is obsoleted by
266 @code{filter-buffer-substring-functions}, but is still supported for
267 backward compatibility. Its value should should be a list of
268 functions which accept a single string argument and return another
269 string. @code{filter-buffer-substring} passes the buffer substring to
270 the first function in this list, and the return value of each function
271 is passed to the next function. The return value of the last function
272 is passed to @code{filter-buffer-substring-functions}.
275 @defun current-word &optional strict really-word
276 This function returns the symbol (or word) at or near point, as a
277 string. The return value includes no text properties.
279 If the optional argument @var{really-word} is non-@code{nil}, it finds a
280 word; otherwise, it finds a symbol (which includes both word
281 characters and symbol constituent characters).
283 If the optional argument @var{strict} is non-@code{nil}, then point
284 must be in or next to the symbol or word---if no symbol or word is
285 there, the function returns @code{nil}. Otherwise, a nearby symbol or
286 word on the same line is acceptable.
289 @defun thing-at-point thing
290 Return the @var{thing} around or next to point, as a string.
292 The argument @var{thing} is a symbol which specifies a kind of syntactic
293 entity. Possibilities include @code{symbol}, @code{list}, @code{sexp},
294 @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
295 @code{whitespace}, @code{line}, @code{page}, and others.
298 ---------- Buffer: foo ----------
299 Gentlemen may cry ``Pea@point{}ce! Peace!,''
300 but there is no peace.
301 ---------- Buffer: foo ----------
303 (thing-at-point 'word)
305 (thing-at-point 'line)
306 @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
307 (thing-at-point 'whitespace)
313 @section Comparing Text
314 @cindex comparing buffer text
316 This function lets you compare portions of the text in a buffer, without
317 copying them into strings first.
319 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
320 This function lets you compare two substrings of the same buffer or two
321 different buffers. The first three arguments specify one substring,
322 giving a buffer (or a buffer name) and two positions within the
323 buffer. The last three arguments specify the other substring in the
324 same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or
325 both to stand for the current buffer.
327 The value is negative if the first substring is less, positive if the
328 first is greater, and zero if they are equal. The absolute value of
329 the result is one plus the index of the first differing characters
330 within the substrings.
332 This function ignores case when comparing characters
333 if @code{case-fold-search} is non-@code{nil}. It always ignores
336 Suppose the current buffer contains the text @samp{foobarbar
337 haha!rara!}; then in this example the two substrings are @samp{rbar }
338 and @samp{rara!}. The value is 2 because the first substring is greater
339 at the second character.
342 (compare-buffer-substrings nil 6 11 nil 16 21)
348 @section Inserting Text
349 @cindex insertion of text
350 @cindex text insertion
352 @cindex insertion before point
353 @cindex before point, insertion
354 @dfn{Insertion} means adding new text to a buffer. The inserted text
355 goes at point---between the character before point and the character
356 after point. Some insertion functions leave point before the inserted
357 text, while other functions leave it after. We call the former
358 insertion @dfn{after point} and the latter insertion @dfn{before point}.
360 Insertion moves markers located at positions after the insertion
361 point, so that they stay with the surrounding text (@pxref{Markers}).
362 When a marker points at the place of insertion, insertion may or may
363 not relocate the marker, depending on the marker's insertion type
364 (@pxref{Marker Insertion Types}). Certain special functions such as
365 @code{insert-before-markers} relocate all such markers to point after
366 the inserted text, regardless of the markers' insertion type.
368 Insertion functions signal an error if the current buffer is
369 read-only or if they insert within read-only text.
371 These functions copy text characters from strings and buffers along
372 with their properties. The inserted characters have exactly the same
373 properties as the characters they were copied from. By contrast,
374 characters specified as separate arguments, not part of a string or
375 buffer, inherit their text properties from the neighboring text.
377 The insertion functions convert text from unibyte to multibyte in
378 order to insert in a multibyte buffer, and vice versa---if the text
379 comes from a string or from a buffer. However, they do not convert
380 unibyte character codes 128 through 255 to multibyte characters, not
381 even if the current buffer is a multibyte buffer. @xref{Converting
384 @defun insert &rest args
385 This function inserts the strings and/or characters @var{args} into the
386 current buffer, at point, moving point forward. In other words, it
387 inserts the text before point. An error is signaled unless all
388 @var{args} are either strings or characters. The value is @code{nil}.
391 @defun insert-before-markers &rest args
392 This function inserts the strings and/or characters @var{args} into the
393 current buffer, at point, moving point forward. An error is signaled
394 unless all @var{args} are either strings or characters. The value is
397 This function is unlike the other insertion functions in that it
398 relocates markers initially pointing at the insertion point, to point
399 after the inserted text. If an overlay begins at the insertion point,
400 the inserted text falls outside the overlay; if a nonempty overlay
401 ends at the insertion point, the inserted text falls inside that
405 @defun insert-char character count &optional inherit
406 This function inserts @var{count} instances of @var{character} into the
407 current buffer before point. The argument @var{count} should be an
408 integer, and @var{character} must be a character. The value is @code{nil}.
410 This function does not convert unibyte character codes 128 through 255
411 to multibyte characters, not even if the current buffer is a multibyte
412 buffer. @xref{Converting Representations}.
414 If @var{inherit} is non-@code{nil}, then the inserted characters inherit
415 sticky text properties from the two characters before and after the
416 insertion point. @xref{Sticky Properties}.
419 @defun insert-buffer-substring from-buffer-or-name &optional start end
420 This function inserts a portion of buffer @var{from-buffer-or-name}
421 (which must already exist) into the current buffer before point. The
422 text inserted is the region between @var{start} and @var{end}. (These
423 arguments default to the beginning and end of the accessible portion of
424 that buffer.) This function returns @code{nil}.
426 In this example, the form is executed with buffer @samp{bar} as the
427 current buffer. We assume that buffer @samp{bar} is initially empty.
431 ---------- Buffer: foo ----------
432 We hold these truths to be self-evident, that all
433 ---------- Buffer: foo ----------
437 (insert-buffer-substring "foo" 1 20)
440 ---------- Buffer: bar ----------
441 We hold these truth@point{}
442 ---------- Buffer: bar ----------
447 @defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
448 This is like @code{insert-buffer-substring} except that it does not
449 copy any text properties.
452 @xref{Sticky Properties}, for other insertion functions that inherit
453 text properties from the nearby text in addition to inserting it.
454 Whitespace inserted by indentation functions also inherits text
457 @node Commands for Insertion
458 @section User-Level Insertion Commands
460 This section describes higher-level commands for inserting text,
461 commands intended primarily for the user but useful also in Lisp
464 @deffn Command insert-buffer from-buffer-or-name
465 This command inserts the entire accessible contents of
466 @var{from-buffer-or-name} (which must exist) into the current buffer
467 after point. It leaves the mark after the inserted text. The value
471 @deffn Command self-insert-command count
472 @cindex character insertion
473 @cindex self-insertion
474 This command inserts the last character typed; it does so @var{count}
475 times, before point, and returns @code{nil}. Most printing characters
476 are bound to this command. In routine use, @code{self-insert-command}
477 is the most frequently called function in Emacs, but programs rarely use
478 it except to install it on a keymap.
480 In an interactive call, @var{count} is the numeric prefix argument.
482 Self-insertion translates the input character through
483 @code{translation-table-for-input}. @xref{Translation of Characters}.
485 This command calls @code{auto-fill-function} whenever that is
486 non-@code{nil} and the character inserted is in the table
487 @code{auto-fill-chars} (@pxref{Auto Filling}).
489 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
490 This command performs abbrev expansion if Abbrev mode is enabled and
491 the inserted character does not have word-constituent
492 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also
493 responsible for calling @code{blink-paren-function} when the inserted
494 character has close parenthesis syntax (@pxref{Blinking}).
496 @vindex post-self-insert-hook
497 The final thing this command does is to run the hook
498 @code{post-self-insert-hook}. You could use this to automatically
499 reindent text as it is typed, for example.
501 Do not try substituting your own definition of
502 @code{self-insert-command} for the standard one. The editor command
503 loop handles this function specially.
506 @deffn Command newline &optional number-of-newlines
507 This command inserts newlines into the current buffer before point.
508 If @var{number-of-newlines} is supplied, that many newline characters
511 @cindex newline and Auto Fill mode
512 This function calls @code{auto-fill-function} if the current column
513 number is greater than the value of @code{fill-column} and
514 @var{number-of-newlines} is @code{nil}. Typically what
515 @code{auto-fill-function} does is insert a newline; thus, the overall
516 result in this case is to insert two newlines at different places: one
517 at point, and another earlier in the line. @code{newline} does not
518 auto-fill if @var{number-of-newlines} is non-@code{nil}.
520 This command indents to the left margin if that is not zero.
523 The value returned is @code{nil}. In an interactive call, @var{count}
524 is the numeric prefix argument.
527 @defvar overwrite-mode
528 This variable controls whether overwrite mode is in effect. The value
529 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
530 or @code{nil}. @code{overwrite-mode-textual} specifies textual
531 overwrite mode (treats newlines and tabs specially), and
532 @code{overwrite-mode-binary} specifies binary overwrite mode (treats
533 newlines and tabs like any other characters).
537 @section Deleting Text
538 @cindex text deletion
540 @cindex deleting text vs killing
541 Deletion means removing part of the text in a buffer, without saving
542 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
543 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
544 Some deletion functions do save text in the kill ring in some special
547 All of the deletion functions operate on the current buffer.
549 @deffn Command erase-buffer
550 This function deletes the entire text of the current buffer
551 (@emph{not} just the accessible portion), leaving it
552 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
553 error; if some of the text in it is read-only, it signals a
554 @code{text-read-only} error. Otherwise, it deletes the text without
555 asking for any confirmation. It returns @code{nil}.
557 Normally, deleting a large amount of text from a buffer inhibits further
558 auto-saving of that buffer ``because it has shrunk''. However,
559 @code{erase-buffer} does not do this, the idea being that the future
560 text is not really related to the former text, and its size should not
561 be compared with that of the former text.
564 @deffn Command delete-region start end
565 This command deletes the text between positions @var{start} and
566 @var{end} in the current buffer, and returns @code{nil}. If point was
567 inside the deleted region, its value afterward is @var{start}.
568 Otherwise, point relocates with the surrounding text, as markers do.
571 @defun delete-and-extract-region start end
572 This function deletes the text between positions @var{start} and
573 @var{end} in the current buffer, and returns a string containing the
576 If point was inside the deleted region, its value afterward is
577 @var{start}. Otherwise, point relocates with the surrounding text, as
581 @deffn Command delete-char count &optional killp
582 This command deletes @var{count} characters directly after point, or
583 before point if @var{count} is negative. If @var{killp} is
584 non-@code{nil}, then it saves the deleted characters in the kill ring.
586 In an interactive call, @var{count} is the numeric prefix argument, and
587 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
588 argument is supplied, the text is saved in the kill ring. If no prefix
589 argument is supplied, then one character is deleted, but not saved in
592 The value returned is always @code{nil}.
595 @deffn Command delete-backward-char count &optional killp
596 @cindex deleting previous char
597 This command deletes @var{count} characters directly before point, or
598 after point if @var{count} is negative. If @var{killp} is
599 non-@code{nil}, then it saves the deleted characters in the kill ring.
601 In an interactive call, @var{count} is the numeric prefix argument, and
602 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
603 argument is supplied, the text is saved in the kill ring. If no prefix
604 argument is supplied, then one character is deleted, but not saved in
607 The value returned is always @code{nil}.
610 @deffn Command backward-delete-char-untabify count &optional killp
612 This command deletes @var{count} characters backward, changing tabs
613 into spaces. When the next character to be deleted is a tab, it is
614 first replaced with the proper number of spaces to preserve alignment
615 and then one of those spaces is deleted instead of the tab. If
616 @var{killp} is non-@code{nil}, then the command saves the deleted
617 characters in the kill ring.
619 Conversion of tabs to spaces happens only if @var{count} is positive.
620 If it is negative, exactly @minus{}@var{count} characters after point
623 In an interactive call, @var{count} is the numeric prefix argument, and
624 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
625 argument is supplied, the text is saved in the kill ring. If no prefix
626 argument is supplied, then one character is deleted, but not saved in
629 The value returned is always @code{nil}.
632 @defopt backward-delete-char-untabify-method
633 This option specifies how @code{backward-delete-char-untabify} should
634 deal with whitespace. Possible values include @code{untabify}, the
635 default, meaning convert a tab to many spaces and delete one;
636 @code{hungry}, meaning delete all tabs and spaces before point with
637 one command; @code{all} meaning delete all tabs, spaces and newlines
638 before point, and @code{nil}, meaning do nothing special for
639 whitespace characters.
642 @node User-Level Deletion
643 @section User-Level Deletion Commands
645 This section describes higher-level commands for deleting text,
646 commands intended primarily for the user but useful also in Lisp
649 @deffn Command delete-horizontal-space &optional backward-only
650 @cindex deleting whitespace
651 This function deletes all spaces and tabs around point. It returns
654 If @var{backward-only} is non-@code{nil}, the function deletes
655 spaces and tabs before point, but not after point.
657 In the following examples, we call @code{delete-horizontal-space} four
658 times, once on each line, with point between the second and third
659 characters on the line each time.
663 ---------- Buffer: foo ----------
668 ---------- Buffer: foo ----------
672 (delete-horizontal-space) ; @r{Four times.}
675 ---------- Buffer: foo ----------
680 ---------- Buffer: foo ----------
685 @deffn Command delete-indentation &optional join-following-p
686 This function joins the line point is on to the previous line, deleting
687 any whitespace at the join and in some cases replacing it with one
688 space. If @var{join-following-p} is non-@code{nil},
689 @code{delete-indentation} joins this line to the following line
690 instead. The function returns @code{nil}.
692 If there is a fill prefix, and the second of the lines being joined
693 starts with the prefix, then @code{delete-indentation} deletes the
694 fill prefix before joining the lines. @xref{Margins}.
696 In the example below, point is located on the line starting
697 @samp{events}, and it makes no difference if there are trailing spaces
698 in the preceding line.
702 ---------- Buffer: foo ----------
703 When in the course of human
704 @point{} events, it becomes necessary
705 ---------- Buffer: foo ----------
712 ---------- Buffer: foo ----------
713 When in the course of human@point{} events, it becomes necessary
714 ---------- Buffer: foo ----------
718 After the lines are joined, the function @code{fixup-whitespace} is
719 responsible for deciding whether to leave a space at the junction.
722 @deffn Command fixup-whitespace
723 This function replaces all the horizontal whitespace surrounding point
724 with either one space or no space, according to the context. It
727 At the beginning or end of a line, the appropriate amount of space is
728 none. Before a character with close parenthesis syntax, or after a
729 character with open parenthesis or expression-prefix syntax, no space is
730 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
733 In the example below, @code{fixup-whitespace} is called the first time
734 with point before the word @samp{spaces} in the first line. For the
735 second invocation, point is directly after the @samp{(}.
739 ---------- Buffer: foo ----------
740 This has too many @point{}spaces
741 This has too many spaces at the start of (@point{} this list)
742 ---------- Buffer: foo ----------
753 ---------- Buffer: foo ----------
754 This has too many spaces
755 This has too many spaces at the start of (this list)
756 ---------- Buffer: foo ----------
761 @deffn Command just-one-space &optional n
762 @comment !!SourceFile simple.el
763 This command replaces any spaces and tabs around point with a single
764 space, or @var{n} spaces if @var{n} is specified. It returns
768 @deffn Command delete-blank-lines
769 This function deletes blank lines surrounding point. If point is on a
770 blank line with one or more blank lines before or after it, then all but
771 one of them are deleted. If point is on an isolated blank line, then it
772 is deleted. If point is on a nonblank line, the command deletes all
773 blank lines immediately following it.
775 A blank line is defined as a line containing only tabs and spaces.
777 @code{delete-blank-lines} returns @code{nil}.
781 @section The Kill Ring
784 @dfn{Kill functions} delete text like the deletion functions, but save
785 it so that the user can reinsert it by @dfn{yanking}. Most of these
786 functions have @samp{kill-} in their name. By contrast, the functions
787 whose names start with @samp{delete-} normally do not save text for
788 yanking (though they can still be undone); these are ``deletion''
791 Most of the kill commands are primarily for interactive use, and are
792 not described here. What we do describe are the functions provided for
793 use in writing such commands. You can use these functions to write
794 commands for killing text. When you need to delete text for internal
795 purposes within a Lisp function, you should normally use deletion
796 functions, so as not to disturb the kill ring contents.
799 Killed text is saved for later yanking in the @dfn{kill ring}. This
800 is a list that holds a number of recent kills, not just the last text
801 kill. We call this a ``ring'' because yanking treats it as having
802 elements in a cyclic order. The list is kept in the variable
803 @code{kill-ring}, and can be operated on with the usual functions for
804 lists; there are also specialized functions, described in this section,
805 that treat it as a ring.
807 Some people think this use of the word ``kill'' is unfortunate, since
808 it refers to operations that specifically @emph{do not} destroy the
809 entities ``killed''. This is in sharp contrast to ordinary life, in
810 which death is permanent and ``killed'' entities do not come back to
811 life. Therefore, other metaphors have been proposed. For example, the
812 term ``cut ring'' makes sense to people who, in pre-computer days, used
813 scissors and paste to cut up and rearrange manuscripts. However, it
814 would be difficult to change the terminology now.
817 * Kill Ring Concepts:: What text looks like in the kill ring.
818 * Kill Functions:: Functions that kill text.
819 * Yanking:: How yanking is done.
820 * Yank Commands:: Commands that access the kill ring.
821 * Low-Level Kill Ring:: Functions and variables for kill ring access.
822 * Internals of Kill Ring:: Variables that hold kill ring data.
825 @node Kill Ring Concepts
826 @comment node-name, next, previous, up
827 @subsection Kill Ring Concepts
829 The kill ring records killed text as strings in a list, most recent
830 first. A short kill ring, for example, might look like this:
833 ("some text" "a different piece of text" "even older text")
837 When the list reaches @code{kill-ring-max} entries in length, adding a
838 new entry automatically deletes the last entry.
840 When kill commands are interwoven with other commands, each kill
841 command makes a new entry in the kill ring. Multiple kill commands in
842 succession build up a single kill ring entry, which would be yanked as a
843 unit; the second and subsequent consecutive kill commands add text to
844 the entry made by the first one.
846 For yanking, one entry in the kill ring is designated the ``front'' of
847 the ring. Some yank commands ``rotate'' the ring by designating a
848 different element as the ``front''. But this virtual rotation doesn't
849 change the list itself---the most recent entry always comes first in the
853 @comment node-name, next, previous, up
854 @subsection Functions for Killing
856 @code{kill-region} is the usual subroutine for killing text. Any
857 command that calls this function is a ``kill command'' (and should
858 probably have @samp{kill} in its name). @code{kill-region} puts the
859 newly killed text in a new element at the beginning of the kill ring or
860 adds it to the most recent element. It determines automatically (using
861 @code{last-command}) whether the previous command was a kill command,
862 and if so appends the killed text to the most recent entry.
864 @deffn Command kill-region start end
865 This function kills the text in the region defined by @var{start} and
866 @var{end}. The text is deleted but saved in the kill ring, along with
867 its text properties. The value is always @code{nil}.
869 In an interactive call, @var{start} and @var{end} are point and
872 If the buffer or text is read-only, @code{kill-region} modifies the kill
873 ring just the same, then signals an error without modifying the buffer.
874 This is convenient because it lets the user use a series of kill
875 commands to copy text from a read-only buffer into the kill ring.
878 @defopt kill-read-only-ok
879 If this option is non-@code{nil}, @code{kill-region} does not signal an
880 error if the buffer or text is read-only. Instead, it simply returns,
881 updating the kill ring but not changing the buffer.
884 @deffn Command copy-region-as-kill start end
885 This command saves the region defined by @var{start} and @var{end} on
886 the kill ring (including text properties), but does not delete the text
887 from the buffer. It returns @code{nil}.
889 The command does not set @code{this-command} to @code{kill-region}, so a
890 subsequent kill command does not append to the same kill ring entry.
892 @c FIXME Why is it better? Why isn't copy-region-as-kill obsolete then?
893 @c Why is it used in many places in Emacs?
894 In Lisp programs, it is better to use @code{kill-new} or
895 @code{kill-append} instead of this command. @xref{Low-Level Kill Ring}.
901 Yanking means inserting text from the kill ring, but it does
902 not insert the text blindly. Yank commands and some other commands
903 use @code{insert-for-yank} to perform special processing on the
904 text that they copy into the buffer.
906 @defun insert-for-yank string
907 This function normally works like @code{insert} except that it doesn't
908 insert the text properties (@pxref{Text Properties}) in the list
909 variable @code{yank-excluded-properties}. However, if any part of
910 @var{string} has a non-@code{nil} @code{yank-handler} text property,
911 that property can do various special processing on that part of the
915 @defun insert-buffer-substring-as-yank buf &optional start end
916 This function resembles @code{insert-buffer-substring} except that it
917 doesn't insert the text properties in the
918 @code{yank-excluded-properties} list.
921 You can put a @code{yank-handler} text property on all or part of
922 the text to control how it will be inserted if it is yanked. The
923 @code{insert-for-yank} function looks for that property. The property
924 value must be a list of one to four elements, with the following
925 format (where elements after the first may be omitted):
928 (@var{function} @var{param} @var{noexclude} @var{undo})
931 Here is what the elements do:
935 When @var{function} is present and non-@code{nil}, it is called instead of
936 @code{insert} to insert the string. @var{function} takes one
937 argument---the string to insert.
940 If @var{param} is present and non-@code{nil}, it replaces @var{string}
941 (or the part of @var{string} being processed) as the object passed to
942 @var{function} (or @code{insert}); for example, if @var{function} is
943 @code{yank-rectangle}, @var{param} should be a list of strings to
944 insert as a rectangle.
947 If @var{noexclude} is present and non-@code{nil}, the normal removal of the
948 yank-excluded-properties is not performed; instead @var{function} is
949 responsible for removing those properties. This may be necessary
950 if @var{function} adjusts point before or after inserting the object.
953 If @var{undo} is present and non-@code{nil}, it is a function that will be
954 called by @code{yank-pop} to undo the insertion of the current object.
955 It is called with two arguments, the start and end of the current
956 region. @var{function} can set @code{yank-undo-function} to override
957 the @var{undo} value.
960 @cindex yanking and text properties
961 @defopt yank-excluded-properties
962 Yanking discards certain text properties from the yanked text, as
963 described above. The value of this variable is the list of properties
964 to discard. Its default value contains properties that might lead to
965 annoying results, such as causing the text to respond to the mouse or
966 specifying key bindings.
970 @comment node-name, next, previous, up
971 @subsection Functions for Yanking
973 This section describes higher-level commands for yanking, which are
974 intended primarily for the user but useful also in Lisp programs.
975 Both @code{yank} and @code{yank-pop} honor the
976 @code{yank-excluded-properties} variable and @code{yank-handler} text
977 property (@pxref{Yanking}).
979 @deffn Command yank &optional arg
980 @cindex inserting killed text
981 This command inserts before point the text at the front of the kill
982 ring. It sets the mark at the beginning of that text, using
983 @code{push-mark} (@pxref{The Mark}), and puts point at the end.
985 If @var{arg} is a non-@code{nil} list (which occurs interactively when
986 the user types @kbd{C-u} with no digits), then @code{yank} inserts the
987 text as described above, but puts point before the yanked text and
988 sets the mark after it.
990 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th
991 most recently killed text---the @var{arg}th element of the kill ring
992 list, counted cyclically from the front, which is considered the
993 first element for this purpose.
995 @code{yank} does not alter the contents of the kill ring, unless it
996 used text provided by another program, in which case it pushes that text
997 onto the kill ring. However if @var{arg} is an integer different from
998 one, it rotates the kill ring to place the yanked string at the front.
1000 @code{yank} returns @code{nil}.
1003 @deffn Command yank-pop &optional arg
1004 This command replaces the just-yanked entry from the kill ring with a
1005 different entry from the kill ring.
1007 This is allowed only immediately after a @code{yank} or another
1008 @code{yank-pop}. At such a time, the region contains text that was just
1009 inserted by yanking. @code{yank-pop} deletes that text and inserts in
1010 its place a different piece of killed text. It does not add the deleted
1011 text to the kill ring, since it is already in the kill ring somewhere.
1012 It does however rotate the kill ring to place the newly yanked string at
1015 If @var{arg} is @code{nil}, then the replacement text is the previous
1016 element of the kill ring. If @var{arg} is numeric, the replacement is
1017 the @var{arg}th previous kill. If @var{arg} is negative, a more recent
1018 kill is the replacement.
1020 The sequence of kills in the kill ring wraps around, so that after the
1021 oldest one comes the newest one, and before the newest one goes the
1024 The return value is always @code{nil}.
1027 @defvar yank-undo-function
1028 If this variable is non-@code{nil}, the function @code{yank-pop} uses
1029 its value instead of @code{delete-region} to delete the text
1030 inserted by the previous @code{yank} or
1031 @code{yank-pop} command. The value must be a function of two
1032 arguments, the start and end of the current region.
1034 The function @code{insert-for-yank} automatically sets this variable
1035 according to the @var{undo} element of the @code{yank-handler}
1036 text property, if there is one.
1039 @node Low-Level Kill Ring
1040 @subsection Low-Level Kill Ring
1042 These functions and variables provide access to the kill ring at a
1043 lower level, but are still convenient for use in Lisp programs,
1044 because they take care of interaction with window system selections
1045 (@pxref{Window System Selections}).
1047 @defun current-kill n &optional do-not-move
1048 The function @code{current-kill} rotates the yanking pointer, which
1049 designates the ``front'' of the kill ring, by @var{n} places (from newer
1050 kills to older ones), and returns the text at that place in the ring.
1052 If the optional second argument @var{do-not-move} is non-@code{nil},
1053 then @code{current-kill} doesn't alter the yanking pointer; it just
1054 returns the @var{n}th kill, counting from the current yanking pointer.
1056 If @var{n} is zero, indicating a request for the latest kill,
1057 @code{current-kill} calls the value of
1058 @code{interprogram-paste-function} (documented below) before
1059 consulting the kill ring. If that value is a function and calling it
1060 returns a string or a list of several string, @code{current-kill}
1061 pushes the strings onto the kill ring and returns the first string.
1062 It also sets the yanking pointer to point to the kill-ring entry of
1063 the first string returned by @code{interprogram-paste-function},
1064 regardless of the value of @var{do-not-move}. Otherwise,
1065 @code{current-kill} does not treat a zero value for @var{n} specially:
1066 it returns the entry pointed at by the yanking pointer and does not
1067 move the yanking pointer.
1070 @defun kill-new string &optional replace
1071 This function pushes the text @var{string} onto the kill ring and
1072 makes the yanking pointer point to it. It discards the oldest entry
1073 if appropriate. It also invokes the value of
1074 @code{interprogram-cut-function} (see below).
1076 If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the
1077 first element of the kill ring with @var{string}, rather than pushing
1078 @var{string} onto the kill ring.
1081 @defun kill-append string before-p
1082 This function appends the text @var{string} to the first entry in the
1083 kill ring and makes the yanking pointer point to the combined entry.
1084 Normally @var{string} goes at the end of the entry, but if
1085 @var{before-p} is non-@code{nil}, it goes at the beginning. This
1086 function also invokes the value of @code{interprogram-cut-function}
1090 @defvar interprogram-paste-function
1091 This variable provides a way of transferring killed text from other
1092 programs, when you are using a window system. Its value should be
1093 @code{nil} or a function of no arguments.
1095 If the value is a function, @code{current-kill} calls it to get the
1096 ``most recent kill''. If the function returns a non-@code{nil} value,
1097 then that value is used as the ``most recent kill''. If it returns
1098 @code{nil}, then the front of the kill ring is used.
1100 To facilitate support for window systems that support multiple
1101 selections, this function may also return a list of strings. In that
1102 case, the first string is used as the ``most recent kill'', and all
1103 the other strings are pushed onto the kill ring, for easy access by
1106 The normal use of this function is to get the window system's
1107 clipboard as the most recent kill, even if the selection belongs to
1108 another application. @xref{Window System Selections}. However, if
1109 the clipboard contents come from the current Emacs session, this
1110 function should return @code{nil}.
1113 @defvar interprogram-cut-function
1114 This variable provides a way of communicating killed text to other
1115 programs, when you are using a window system. Its value should be
1116 @code{nil} or a function of one required argument.
1118 If the value is a function, @code{kill-new} and @code{kill-append} call
1119 it with the new first element of the kill ring as the argument.
1121 The normal use of this function is to put newly killed text in the
1122 window system's clipboard. @xref{Window System Selections}.
1125 @node Internals of Kill Ring
1126 @comment node-name, next, previous, up
1127 @subsection Internals of the Kill Ring
1129 The variable @code{kill-ring} holds the kill ring contents, in the
1130 form of a list of strings. The most recent kill is always at the front
1133 The @code{kill-ring-yank-pointer} variable points to a link in the
1134 kill ring list, whose @sc{car} is the text to yank next. We say it
1135 identifies the ``front'' of the ring. Moving
1136 @code{kill-ring-yank-pointer} to a different link is called
1137 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
1138 the functions that move the yank pointer wrap around from the end of the
1139 list to the beginning, or vice-versa. Rotation of the kill ring is
1140 virtual; it does not change the value of @code{kill-ring}.
1142 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
1143 variables whose values are normally lists. The word ``pointer'' in the
1144 name of the @code{kill-ring-yank-pointer} indicates that the variable's
1145 purpose is to identify one element of the list for use by the next yank
1148 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
1149 of the links in the kill ring list. The element it identifies is the
1150 @sc{car} of that link. Kill commands, which change the kill ring, also
1151 set this variable to the value of @code{kill-ring}. The effect is to
1152 rotate the ring so that the newly killed text is at the front.
1154 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
1155 pointing to the second entry in the kill ring @code{("some text" "a
1156 different piece of text" "yet older text")}.
1160 kill-ring ---- kill-ring-yank-pointer
1163 | --- --- --- --- --- ---
1164 --> | | |------> | | |--> | | |--> nil
1165 --- --- --- --- --- ---
1168 | | -->"yet older text"
1170 | --> "a different piece of text"
1177 This state of affairs might occur after @kbd{C-y} (@code{yank})
1178 immediately followed by @kbd{M-y} (@code{yank-pop}).
1181 This variable holds the list of killed text sequences, most recently
1185 @defvar kill-ring-yank-pointer
1186 This variable's value indicates which element of the kill ring is at the
1187 ``front'' of the ring for yanking. More precisely, the value is a tail
1188 of the value of @code{kill-ring}, and its @sc{car} is the kill string
1189 that @kbd{C-y} should yank.
1192 @defopt kill-ring-max
1193 The value of this variable is the maximum length to which the kill
1194 ring can grow, before elements are thrown away at the end. The default
1195 value for @code{kill-ring-max} is 60.
1199 @comment node-name, next, previous, up
1203 Most buffers have an @dfn{undo list}, which records all changes made
1204 to the buffer's text so that they can be undone. (The buffers that
1205 don't have one are usually special-purpose buffers for which Emacs
1206 assumes that undoing is not useful. In particular, any buffer whose
1207 name begins with a space has its undo recording off by default;
1208 see @ref{Buffer Names}.) All the primitives that modify the
1209 text in the buffer automatically add elements to the front of the undo
1210 list, which is in the variable @code{buffer-undo-list}.
1212 @defvar buffer-undo-list
1213 This buffer-local variable's value is the undo list of the current
1214 buffer. A value of @code{t} disables the recording of undo information.
1217 Here are the kinds of elements an undo list can have:
1220 @item @var{position}
1221 This kind of element records a previous value of point; undoing this
1222 element moves point to @var{position}. Ordinary cursor motion does not
1223 make any sort of undo record, but deletion operations use these entries
1224 to record where point was before the command.
1226 @item (@var{beg} . @var{end})
1227 This kind of element indicates how to delete text that was inserted.
1228 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
1231 @item (@var{text} . @var{position})
1232 This kind of element indicates how to reinsert text that was deleted.
1233 The deleted text itself is the string @var{text}. The place to
1234 reinsert it is @code{(abs @var{position})}. If @var{position} is
1235 positive, point was at the beginning of the deleted text, otherwise it
1238 @item (t @var{high} . @var{low})
1239 This kind of element indicates that an unmodified buffer became
1240 modified. The elements @var{high} and @var{low} are two integers, each
1241 recording 16 bits of the visited file's modification time as of when it
1242 was previously visited or saved. @code{primitive-undo} uses those
1243 values to determine whether to mark the buffer as unmodified once again;
1244 it does so only if the file's modification time matches those numbers.
1246 @item (nil @var{property} @var{value} @var{beg} . @var{end})
1247 This kind of element records a change in a text property.
1248 Here's how you might undo the change:
1251 (put-text-property @var{beg} @var{end} @var{property} @var{value})
1254 @item (@var{marker} . @var{adjustment})
1255 This kind of element records the fact that the marker @var{marker} was
1256 relocated due to deletion of surrounding text, and that it moved
1257 @var{adjustment} character positions. Undoing this element moves
1258 @var{marker} @minus{} @var{adjustment} characters.
1260 @item (apply @var{funname} . @var{args})
1261 This is an extensible undo item, which is undone by calling
1262 @var{funname} with arguments @var{args}.
1264 @item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
1265 This is an extensible undo item, which records a change limited to the
1266 range @var{beg} to @var{end}, which increased the size of the buffer
1267 by @var{delta}. It is undone by calling @var{funname} with arguments
1270 This kind of element enables undo limited to a region to determine
1271 whether the element pertains to that region.
1274 This element is a boundary. The elements between two boundaries are
1275 called a @dfn{change group}; normally, each change group corresponds to
1276 one keyboard command, and undo commands normally undo an entire group as
1280 @defun undo-boundary
1281 This function places a boundary element in the undo list. The undo
1282 command stops at such a boundary, and successive undo commands undo
1283 to earlier and earlier boundaries. This function returns @code{nil}.
1285 The editor command loop automatically calls @code{undo-boundary} just
1286 before executing each key sequence, so that each undo normally undoes
1287 the effects of one command. As an exception, the command
1288 @code{self-insert-command}, which produces self-inserting input
1289 characters (@pxref{Commands for Insertion}), may remove the boundary
1290 inserted by the command loop: a boundary is accepted for the first
1291 such character, the next 19 consecutive self-inserting input
1292 characters do not have boundaries, and then the 20th does; and so on
1293 as long as the self-inserting characters continue. Hence, sequences
1294 of consecutive character insertions can be undone as a group.
1296 All buffer modifications add a boundary whenever the previous undoable
1297 change was made in some other buffer. This is to ensure that
1298 each command makes a boundary in each buffer where it makes changes.
1300 Calling this function explicitly is useful for splitting the effects of
1301 a command into more than one unit. For example, @code{query-replace}
1302 calls @code{undo-boundary} after each replacement, so that the user can
1303 undo individual replacements one by one.
1306 @defvar undo-in-progress
1307 This variable is normally @code{nil}, but the undo commands bind it to
1308 @code{t}. This is so that various kinds of change hooks can tell when
1309 they're being called for the sake of undoing.
1312 @defun primitive-undo count list
1313 This is the basic function for undoing elements of an undo list.
1314 It undoes the first @var{count} elements of @var{list}, returning
1315 the rest of @var{list}.
1317 @code{primitive-undo} adds elements to the buffer's undo list when it
1318 changes the buffer. Undo commands avoid confusion by saving the undo
1319 list value at the beginning of a sequence of undo operations. Then the
1320 undo operations use and update the saved value. The new elements added
1321 by undoing are not part of this saved value, so they don't interfere with
1324 This function does not bind @code{undo-in-progress}.
1327 @node Maintaining Undo
1328 @section Maintaining Undo Lists
1330 This section describes how to enable and disable undo information for
1331 a given buffer. It also explains how the undo list is truncated
1332 automatically so it doesn't get too big.
1334 Recording of undo information in a newly created buffer is normally
1335 enabled to start with; but if the buffer name starts with a space, the
1336 undo recording is initially disabled. You can explicitly enable or
1337 disable undo recording with the following two functions, or by setting
1338 @code{buffer-undo-list} yourself.
1340 @deffn Command buffer-enable-undo &optional buffer-or-name
1341 This command enables recording undo information for buffer
1342 @var{buffer-or-name}, so that subsequent changes can be undone. If no
1343 argument is supplied, then the current buffer is used. This function
1344 does nothing if undo recording is already enabled in the buffer. It
1347 In an interactive call, @var{buffer-or-name} is the current buffer.
1348 You cannot specify any other buffer.
1351 @deffn Command buffer-disable-undo &optional buffer-or-name
1352 @cindex disabling undo
1353 This function discards the undo list of @var{buffer-or-name}, and disables
1354 further recording of undo information. As a result, it is no longer
1355 possible to undo either previous changes or any subsequent changes. If
1356 the undo list of @var{buffer-or-name} is already disabled, this function
1359 This function returns @code{nil}.
1362 As editing continues, undo lists get longer and longer. To prevent
1363 them from using up all available memory space, garbage collection trims
1364 them back to size limits you can set. (For this purpose, the ``size''
1365 of an undo list measures the cons cells that make up the list, plus the
1366 strings of deleted text.) Three variables control the range of acceptable
1367 sizes: @code{undo-limit}, @code{undo-strong-limit} and
1368 @code{undo-outer-limit}. In these variables, size is counted as the
1369 number of bytes occupied, which includes both saved text and other
1373 This is the soft limit for the acceptable size of an undo list. The
1374 change group at which this size is exceeded is the last one kept.
1377 @defopt undo-strong-limit
1378 This is the upper limit for the acceptable size of an undo list. The
1379 change group at which this size is exceeded is discarded itself (along
1380 with all older change groups). There is one exception: the very latest
1381 change group is only discarded if it exceeds @code{undo-outer-limit}.
1384 @defopt undo-outer-limit
1385 If at garbage collection time the undo info for the current command
1386 exceeds this limit, Emacs discards the info and displays a warning.
1387 This is a last ditch limit to prevent memory overflow.
1390 @defopt undo-ask-before-discard
1391 If this variable is non-@code{nil}, when the undo info exceeds
1392 @code{undo-outer-limit}, Emacs asks in the echo area whether to
1393 discard the info. The default value is @code{nil}, which means to
1394 discard it automatically.
1396 This option is mainly intended for debugging. Garbage collection is
1397 inhibited while the question is asked, which means that Emacs might
1398 leak memory if the user waits too long before answering the question.
1402 @comment node-name, next, previous, up
1404 @cindex filling text
1406 @dfn{Filling} means adjusting the lengths of lines (by moving the line
1407 breaks) so that they are nearly (but no greater than) a specified
1408 maximum width. Additionally, lines can be @dfn{justified}, which means
1409 inserting spaces to make the left and/or right margins line up
1410 precisely. The width is controlled by the variable @code{fill-column}.
1411 For ease of reading, lines should be no longer than 70 or so columns.
1413 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1414 automatically as you insert it, but changes to existing text may leave
1415 it improperly filled. Then you must fill the text explicitly.
1417 Most of the commands in this section return values that are not
1418 meaningful. All the functions that do filling take note of the current
1419 left margin, current right margin, and current justification style
1420 (@pxref{Margins}). If the current justification style is
1421 @code{none}, the filling functions don't actually do anything.
1423 Several of the filling functions have an argument @var{justify}.
1424 If it is non-@code{nil}, that requests some kind of justification. It
1425 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
1426 request a specific style of justification. If it is @code{t}, that
1427 means to use the current justification style for this part of the text
1428 (see @code{current-justification}, below). Any other value is treated
1431 When you call the filling functions interactively, using a prefix
1432 argument implies the value @code{full} for @var{justify}.
1434 @deffn Command fill-paragraph &optional justify region
1435 This command fills the paragraph at or after point. If
1436 @var{justify} is non-@code{nil}, each line is justified as well.
1437 It uses the ordinary paragraph motion commands to find paragraph
1438 boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
1440 When @var{region} is non-@code{nil}, then if Transient Mark mode is
1441 enabled and the mark is active, this command calls @code{fill-region}
1442 to fill all the paragraphs in the region, instead of filling only the
1443 current paragraph. When this command is called interactively,
1444 @var{region} is @code{t}.
1447 @deffn Command fill-region start end &optional justify nosqueeze to-eop
1448 This command fills each of the paragraphs in the region from @var{start}
1449 to @var{end}. It justifies as well if @var{justify} is
1452 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1453 other than line breaks untouched. If @var{to-eop} is non-@code{nil},
1454 that means to keep filling to the end of the paragraph---or the next hard
1455 newline, if @code{use-hard-newlines} is enabled (see below).
1457 The variable @code{paragraph-separate} controls how to distinguish
1458 paragraphs. @xref{Standard Regexps}.
1461 @deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
1462 This command fills each paragraph in the region according to its
1463 individual fill prefix. Thus, if the lines of a paragraph were indented
1464 with spaces, the filled paragraph will remain indented in the same
1467 The first two arguments, @var{start} and @var{end}, are the beginning
1468 and end of the region to be filled. The third and fourth arguments,
1469 @var{justify} and @var{citation-regexp}, are optional. If
1470 @var{justify} is non-@code{nil}, the paragraphs are justified as
1471 well as filled. If @var{citation-regexp} is non-@code{nil}, it means the
1472 function is operating on a mail message and therefore should not fill
1473 the header lines. If @var{citation-regexp} is a string, it is used as
1474 a regular expression; if it matches the beginning of a line, that line
1475 is treated as a citation marker.
1477 Ordinarily, @code{fill-individual-paragraphs} regards each change in
1478 indentation as starting a new paragraph. If
1479 @code{fill-individual-varying-indent} is non-@code{nil}, then only
1480 separator lines separate paragraphs. That mode can handle indented
1481 paragraphs with additional indentation on the first line.
1484 @defopt fill-individual-varying-indent
1485 This variable alters the action of @code{fill-individual-paragraphs} as
1489 @deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
1490 This command considers a region of text as a single paragraph and fills
1491 it. If the region was made up of many paragraphs, the blank lines
1492 between paragraphs are removed. This function justifies as well as
1493 filling when @var{justify} is non-@code{nil}.
1495 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1496 other than line breaks untouched. If @var{squeeze-after} is
1497 non-@code{nil}, it specifies a position in the region, and means don't
1498 canonicalize spaces before that position.
1500 In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
1501 choose a fill prefix by default. @xref{Adaptive Fill}.
1504 @deffn Command justify-current-line &optional how eop nosqueeze
1505 This command inserts spaces between the words of the current line so
1506 that the line ends exactly at @code{fill-column}. It returns
1509 The argument @var{how}, if non-@code{nil} specifies explicitly the style
1510 of justification. It can be @code{left}, @code{right}, @code{full},
1511 @code{center}, or @code{none}. If it is @code{t}, that means to do
1512 follow specified justification style (see @code{current-justification},
1513 below). @code{nil} means to do full justification.
1515 If @var{eop} is non-@code{nil}, that means do only left-justification
1516 if @code{current-justification} specifies full justification. This is
1517 used for the last line of a paragraph; even if the paragraph as a
1518 whole is fully justified, the last line should not be.
1520 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1524 @defopt default-justification
1525 This variable's value specifies the style of justification to use for
1526 text that doesn't specify a style with a text property. The possible
1527 values are @code{left}, @code{right}, @code{full}, @code{center}, or
1528 @code{none}. The default value is @code{left}.
1531 @defun current-justification
1532 This function returns the proper justification style to use for filling
1533 the text around point.
1535 This returns the value of the @code{justification} text property at
1536 point, or the variable @var{default-justification} if there is no such
1537 text property. However, it returns @code{nil} rather than @code{none}
1538 to mean ``don't justify''.
1541 @defopt sentence-end-double-space
1542 @anchor{Definition of sentence-end-double-space}
1543 If this variable is non-@code{nil}, a period followed by just one space
1544 does not count as the end of a sentence, and the filling functions
1545 avoid breaking the line at such a place.
1548 @defopt sentence-end-without-period
1549 If this variable is non-@code{nil}, a sentence can end without a
1550 period. This is used for languages like Thai, where sentences end
1551 with a double space but without a period.
1554 @defopt sentence-end-without-space
1555 If this variable is non-@code{nil}, it should be a string of
1556 characters that can end a sentence without following spaces.
1559 @defvar fill-paragraph-function
1560 This variable provides a way to override the filling of paragraphs.
1561 If its value is non-@code{nil}, @code{fill-paragraph} calls this
1562 function to do the work. If the function returns a non-@code{nil}
1563 value, @code{fill-paragraph} assumes the job is done, and immediately
1566 The usual use of this feature is to fill comments in programming
1567 language modes. If the function needs to fill a paragraph in the usual
1568 way, it can do so as follows:
1571 (let ((fill-paragraph-function nil))
1572 (fill-paragraph arg))
1576 @defvar fill-forward-paragraph-function
1577 This variable provides a way to override how the filling functions,
1578 such as @code{fill-region} and @code{fill-paragraph}, move forward to
1579 the next paragraph. Its value should be a function, which is called
1580 with a single argument @var{n}, the number of paragraphs to move, and
1581 should return the difference between @var{n} and the number of
1582 paragraphs actually moved. The default value of this variable is
1583 @code{forward-paragraph}. @xref{Paragraphs,,, emacs, The GNU Emacs
1587 @defvar use-hard-newlines
1588 If this variable is non-@code{nil}, the filling functions do not delete
1589 newlines that have the @code{hard} text property. These ``hard
1590 newlines'' act as paragraph separators.
1594 @section Margins for Filling
1597 This buffer-local variable, if non-@code{nil}, specifies a string of
1598 text that appears at the beginning of normal text lines and should be
1599 disregarded when filling them. Any line that fails to start with the
1600 fill prefix is considered the start of a paragraph; so is any line
1601 that starts with the fill prefix followed by additional whitespace.
1602 Lines that start with the fill prefix but no additional whitespace are
1603 ordinary text lines that can be filled together. The resulting filled
1604 lines also start with the fill prefix.
1606 The fill prefix follows the left margin whitespace, if any.
1610 This buffer-local variable specifies the maximum width of filled lines.
1611 Its value should be an integer, which is a number of columns. All the
1612 filling, justification, and centering commands are affected by this
1613 variable, including Auto Fill mode (@pxref{Auto Filling}).
1615 As a practical matter, if you are writing text for other people to
1616 read, you should set @code{fill-column} to no more than 70. Otherwise
1617 the line will be too long for people to read comfortably, and this can
1618 make the text seem clumsy.
1620 The default value for @code{fill-column} is 70.
1623 @deffn Command set-left-margin from to margin
1624 This sets the @code{left-margin} property on the text from @var{from} to
1625 @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
1626 command also refills the region to fit the new margin.
1629 @deffn Command set-right-margin from to margin
1630 This sets the @code{right-margin} property on the text from @var{from}
1631 to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
1632 this command also refills the region to fit the new margin.
1635 @defun current-left-margin
1636 This function returns the proper left margin value to use for filling
1637 the text around point. The value is the sum of the @code{left-margin}
1638 property of the character at the start of the current line (or zero if
1639 none), and the value of the variable @code{left-margin}.
1642 @defun current-fill-column
1643 This function returns the proper fill column value to use for filling
1644 the text around point. The value is the value of the @code{fill-column}
1645 variable, minus the value of the @code{right-margin} property of the
1646 character after point.
1649 @deffn Command move-to-left-margin &optional n force
1650 This function moves point to the left margin of the current line. The
1651 column moved to is determined by calling the function
1652 @code{current-left-margin}. If the argument @var{n} is non-@code{nil},
1653 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
1655 If @var{force} is non-@code{nil}, that says to fix the line's
1656 indentation if that doesn't match the left margin value.
1659 @defun delete-to-left-margin &optional from to
1660 This function removes left margin indentation from the text between
1661 @var{from} and @var{to}. The amount of indentation to delete is
1662 determined by calling @code{current-left-margin}. In no case does this
1663 function delete non-whitespace. If @var{from} and @var{to} are omitted,
1664 they default to the whole buffer.
1667 @defun indent-to-left-margin
1668 This function adjusts the indentation at the beginning of the current
1669 line to the value specified by the variable @code{left-margin}. (That
1670 may involve either inserting or deleting whitespace.) This function
1671 is value of @code{indent-line-function} in Paragraph-Indent Text mode.
1675 This variable specifies the base left margin column. In Fundamental
1676 mode, @kbd{C-j} indents to this column. This variable automatically
1677 becomes buffer-local when set in any fashion.
1680 @defopt fill-nobreak-predicate
1681 This variable gives major modes a way to specify not to break a line
1682 at certain places. Its value should be a list of functions. Whenever
1683 filling considers breaking the line at a certain place in the buffer,
1684 it calls each of these functions with no arguments and with point
1685 located at that place. If any of the functions returns
1686 non-@code{nil}, then the line won't be broken there.
1690 @section Adaptive Fill Mode
1691 @c @cindex Adaptive Fill mode "adaptive-fill-mode" is adjacent.
1693 When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill
1694 prefix automatically from the text in each paragraph being filled
1695 rather than using a predetermined value. During filling, this fill
1696 prefix gets inserted at the start of the second and subsequent lines
1697 of the paragraph as described in @ref{Filling}, and in @ref{Auto
1700 @defopt adaptive-fill-mode
1701 Adaptive Fill mode is enabled when this variable is non-@code{nil}.
1702 It is @code{t} by default.
1705 @defun fill-context-prefix from to
1706 This function implements the heart of Adaptive Fill mode; it chooses a
1707 fill prefix based on the text between @var{from} and @var{to},
1708 typically the start and end of a paragraph. It does this by looking
1709 at the first two lines of the paragraph, based on the variables
1711 @c The optional argument first-line-regexp is not documented
1712 @c because it exists for internal purposes and might be eliminated
1715 Usually, this function returns the fill prefix, a string. However,
1716 before doing this, the function makes a final check (not specially
1717 mentioned in the following) that a line starting with this prefix
1718 wouldn't look like the start of a paragraph. Should this happen, the
1719 function signals the anomaly by returning @code{nil} instead.
1721 In detail, @code{fill-context-prefix} does this:
1725 It takes a candidate for the fill prefix from the first line---it
1726 tries first the function in @code{adaptive-fill-function} (if any),
1727 then the regular expression @code{adaptive-fill-regexp} (see below).
1728 The first non-@code{nil} result of these, or the empty string if
1729 they're both @code{nil}, becomes the first line's candidate.
1731 If the paragraph has as yet only one line, the function tests the
1732 validity of the prefix candidate just found. The function then
1733 returns the candidate if it's valid, or a string of spaces otherwise.
1734 (see the description of @code{adaptive-fill-first-line-regexp} below).
1736 When the paragraph already has two lines, the function next looks for
1737 a prefix candidate on the second line, in just the same way it did for
1738 the first line. If it doesn't find one, it returns @code{nil}.
1740 The function now compares the two candidate prefixes heuristically: if
1741 the non-whitespace characters in the line 2 candidate occur in the
1742 same order in the line 1 candidate, the function returns the line 2
1743 candidate. Otherwise, it returns the largest initial substring which
1744 is common to both candidates (which might be the empty string).
1748 @defopt adaptive-fill-regexp
1749 Adaptive Fill mode matches this regular expression against the text
1750 starting after the left margin whitespace (if any) on a line; the
1751 characters it matches are that line's candidate for the fill prefix.
1753 The default value matches whitespace with certain punctuation
1754 characters intermingled.
1757 @defopt adaptive-fill-first-line-regexp
1758 Used only in one-line paragraphs, this regular expression acts as an
1759 additional check of the validity of the one available candidate fill
1760 prefix: the candidate must match this regular expression, or match
1761 @code{comment-start-skip}. If it doesn't, @code{fill-context-prefix}
1762 replaces the candidate with a string of spaces ``of the same width''
1765 The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which
1766 matches only a string of whitespace. The effect of this default is to
1767 force the fill prefixes found in one-line paragraphs always to be pure
1771 @defopt adaptive-fill-function
1772 You can specify more complex ways of choosing a fill prefix
1773 automatically by setting this variable to a function. The function is
1774 called with point after the left margin (if any) of a line, and it
1775 must preserve point. It should return either ``that line's'' fill
1776 prefix or @code{nil}, meaning it has failed to determine a prefix.
1780 @comment node-name, next, previous, up
1781 @section Auto Filling
1782 @cindex filling, automatic
1783 @cindex Auto Fill mode
1785 Auto Fill mode is a minor mode that fills lines automatically as text
1786 is inserted. This section describes the hook used by Auto Fill mode.
1787 For a description of functions that you can call explicitly to fill and
1788 justify existing text, see @ref{Filling}.
1790 Auto Fill mode also enables the functions that change the margins and
1791 justification style to refill portions of the text. @xref{Margins}.
1793 @defvar auto-fill-function
1794 The value of this buffer-local variable should be a function (of no
1795 arguments) to be called after self-inserting a character from the table
1796 @code{auto-fill-chars}. It may be @code{nil}, in which case nothing
1797 special is done in that case.
1799 The value of @code{auto-fill-function} is @code{do-auto-fill} when
1800 Auto-Fill mode is enabled. That is a function whose sole purpose is to
1801 implement the usual strategy for breaking a line.
1804 @defvar normal-auto-fill-function
1805 This variable specifies the function to use for
1806 @code{auto-fill-function}, if and when Auto Fill is turned on. Major
1807 modes can set buffer-local values for this variable to alter how Auto
1811 @defvar auto-fill-chars
1812 A char table of characters which invoke @code{auto-fill-function} when
1813 self-inserted---space and newline in most language environments. They
1814 have an entry @code{t} in the table.
1818 @section Sorting Text
1819 @cindex sorting text
1821 The sorting functions described in this section all rearrange text in
1822 a buffer. This is in contrast to the function @code{sort}, which
1823 rearranges the order of the elements of a list (@pxref{Rearrangement}).
1824 The values returned by these functions are not meaningful.
1826 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate
1827 This function is the general text-sorting routine that subdivides a
1828 buffer into records and then sorts them. Most of the commands in this
1829 section use this function.
1831 To understand how @code{sort-subr} works, consider the whole accessible
1832 portion of the buffer as being divided into disjoint pieces called
1833 @dfn{sort records}. The records may or may not be contiguous, but they
1834 must not overlap. A portion of each sort record (perhaps all of it) is
1835 designated as the sort key. Sorting rearranges the records in order by
1838 Usually, the records are rearranged in order of ascending sort key.
1839 If the first argument to the @code{sort-subr} function, @var{reverse},
1840 is non-@code{nil}, the sort records are rearranged in order of
1841 descending sort key.
1843 The next four arguments to @code{sort-subr} are functions that are
1844 called to move point across a sort record. They are called many times
1845 from within @code{sort-subr}.
1849 @var{nextrecfun} is called with point at the end of a record. This
1850 function moves point to the start of the next record. The first record
1851 is assumed to start at the position of point when @code{sort-subr} is
1852 called. Therefore, you should usually move point to the beginning of
1853 the buffer before calling @code{sort-subr}.
1855 This function can indicate there are no more sort records by leaving
1856 point at the end of the buffer.
1859 @var{endrecfun} is called with point within a record. It moves point to
1860 the end of the record.
1863 @var{startkeyfun} is called to move point from the start of a record to
1864 the start of the sort key. This argument is optional; if it is omitted,
1865 the whole record is the sort key. If supplied, the function should
1866 either return a non-@code{nil} value to be used as the sort key, or
1867 return @code{nil} to indicate that the sort key is in the buffer
1868 starting at point. In the latter case, @var{endkeyfun} is called to
1869 find the end of the sort key.
1872 @var{endkeyfun} is called to move point from the start of the sort key
1873 to the end of the sort key. This argument is optional. If
1874 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
1875 @code{nil}), then the sort key extends to the end of the record. There
1876 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1877 non-@code{nil} value.
1880 The argument @var{predicate} is the function to use to compare keys.
1881 If keys are numbers, it defaults to @code{<}; otherwise it defaults to
1884 As an example of @code{sort-subr}, here is the complete function
1885 definition for @code{sort-lines}:
1889 ;; @r{Note that the first two lines of doc string}
1890 ;; @r{are effectively one line when viewed by a user.}
1891 (defun sort-lines (reverse beg end)
1892 "Sort lines in region alphabetically;\
1893 argument means descending order.
1894 Called from a program, there are three arguments:
1897 REVERSE (non-nil means reverse order),\
1898 BEG and END (region to sort).
1899 The variable `sort-fold-case' determines\
1900 whether alphabetic case affects
1904 (interactive "P\nr")
1907 (narrow-to-region beg end)
1908 (goto-char (point-min))
1909 (let ((inhibit-field-text-motion t))
1910 (sort-subr reverse 'forward-line 'end-of-line)))))
1914 Here @code{forward-line} moves point to the start of the next record,
1915 and @code{end-of-line} moves point to the end of record. We do not pass
1916 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
1917 record is used as the sort key.
1919 The @code{sort-paragraphs} function is very much the same, except that
1920 its @code{sort-subr} call looks like this:
1927 (while (and (not (eobp))
1928 (looking-at paragraph-separate))
1934 Markers pointing into any sort records are left with no useful
1935 position after @code{sort-subr} returns.
1938 @defopt sort-fold-case
1939 If this variable is non-@code{nil}, @code{sort-subr} and the other
1940 buffer sorting functions ignore case when comparing strings.
1943 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
1944 This command sorts the region between @var{start} and @var{end}
1945 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
1946 If @var{reverse} is a negative integer, then sorting is in reverse
1949 Alphabetical sorting means that two sort keys are compared by
1950 comparing the first characters of each, the second characters of each,
1951 and so on. If a mismatch is found, it means that the sort keys are
1952 unequal; the sort key whose character is less at the point of first
1953 mismatch is the lesser sort key. The individual characters are compared
1954 according to their numerical character codes in the Emacs character set.
1956 The value of the @var{record-regexp} argument specifies how to divide
1957 the buffer into sort records. At the end of each record, a search is
1958 done for this regular expression, and the text that matches it is taken
1959 as the next record. For example, the regular expression @samp{^.+$},
1960 which matches lines with at least one character besides a newline, would
1961 make each such line into a sort record. @xref{Regular Expressions}, for
1962 a description of the syntax and meaning of regular expressions.
1964 The value of the @var{key-regexp} argument specifies what part of each
1965 record is the sort key. The @var{key-regexp} could match the whole
1966 record, or only a part. In the latter case, the rest of the record has
1967 no effect on the sorted order of records, but it is carried along when
1968 the record moves to its new position.
1970 The @var{key-regexp} argument can refer to the text matched by a
1971 subexpression of @var{record-regexp}, or it can be a regular expression
1974 If @var{key-regexp} is:
1977 @item @samp{\@var{digit}}
1978 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
1979 grouping in @var{record-regexp} is the sort key.
1982 then the whole record is the sort key.
1984 @item a regular expression
1985 then @code{sort-regexp-fields} searches for a match for the regular
1986 expression within the record. If such a match is found, it is the sort
1987 key. If there is no match for @var{key-regexp} within a record then
1988 that record is ignored, which means its position in the buffer is not
1989 changed. (The other records may move around it.)
1992 For example, if you plan to sort all the lines in the region by the
1993 first word on each line starting with the letter @samp{f}, you should
1994 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
1995 @samp{\<f\w*\>}. The resulting expression looks like this:
1999 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
2005 If you call @code{sort-regexp-fields} interactively, it prompts for
2006 @var{record-regexp} and @var{key-regexp} in the minibuffer.
2009 @deffn Command sort-lines reverse start end
2010 This command alphabetically sorts lines in the region between
2011 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2012 is in reverse order.
2015 @deffn Command sort-paragraphs reverse start end
2016 This command alphabetically sorts paragraphs in the region between
2017 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2018 is in reverse order.
2021 @deffn Command sort-pages reverse start end
2022 This command alphabetically sorts pages in the region between
2023 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2024 is in reverse order.
2027 @deffn Command sort-fields field start end
2028 This command sorts lines in the region between @var{start} and
2029 @var{end}, comparing them alphabetically by the @var{field}th field
2030 of each line. Fields are separated by whitespace and numbered starting
2031 from 1. If @var{field} is negative, sorting is by the
2032 @w{@minus{}@var{field}th} field from the end of the line. This command
2033 is useful for sorting tables.
2036 @deffn Command sort-numeric-fields field start end
2037 This command sorts lines in the region between @var{start} and
2038 @var{end}, comparing them numerically by the @var{field}th field of
2039 each line. Fields are separated by whitespace and numbered starting
2040 from 1. The specified field must contain a number in each line of the
2041 region. Numbers starting with 0 are treated as octal, and numbers
2042 starting with @samp{0x} are treated as hexadecimal.
2044 If @var{field} is negative, sorting is by the
2045 @w{@minus{}@var{field}th} field from the end of the line. This
2046 command is useful for sorting tables.
2049 @defopt sort-numeric-base
2050 This variable specifies the default radix for
2051 @code{sort-numeric-fields} to parse numbers.
2054 @deffn Command sort-columns reverse &optional beg end
2055 This command sorts the lines in the region between @var{beg} and
2056 @var{end}, comparing them alphabetically by a certain range of
2057 columns. The column positions of @var{beg} and @var{end} bound the
2058 range of columns to sort on.
2060 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
2062 One unusual thing about this command is that the entire line
2063 containing position @var{beg}, and the entire line containing position
2064 @var{end}, are included in the region sorted.
2066 Note that @code{sort-columns} rejects text that contains tabs, because
2067 tabs could be split across the specified columns. Use @kbd{M-x
2068 untabify} to convert tabs to spaces before sorting.
2070 When possible, this command actually works by calling the @code{sort}
2075 @comment node-name, next, previous, up
2076 @section Counting Columns
2078 @cindex counting columns
2079 @cindex horizontal position
2081 The column functions convert between a character position (counting
2082 characters from the beginning of the buffer) and a column position
2083 (counting screen characters from the beginning of a line).
2085 These functions count each character according to the number of
2086 columns it occupies on the screen. This means control characters count
2087 as occupying 2 or 4 columns, depending upon the value of
2088 @code{ctl-arrow}, and tabs count as occupying a number of columns that
2089 depends on the value of @code{tab-width} and on the column where the tab
2090 begins. @xref{Usual Display}.
2092 Column number computations ignore the width of the window and the
2093 amount of horizontal scrolling. Consequently, a column value can be
2094 arbitrarily high. The first (or leftmost) column is numbered 0. They
2095 also ignore overlays and text properties, aside from invisibility.
2097 @defun current-column
2098 This function returns the horizontal position of point, measured in
2099 columns, counting from 0 at the left margin. The column position is the
2100 sum of the widths of all the displayed representations of the characters
2101 between the start of the current line and point.
2103 For an example of using @code{current-column}, see the description of
2104 @code{count-lines} in @ref{Text Lines}.
2107 @deffn Command move-to-column column &optional force
2108 This function moves point to @var{column} in the current line. The
2109 calculation of @var{column} takes into account the widths of the
2110 displayed representations of the characters between the start of the
2113 When called interactively, @var{column} is the value of prefix numeric
2114 argument. If @var{column} is not an integer, an error is signaled.
2116 If column @var{column} is beyond the end of the line, point moves to
2117 the end of the line. If @var{column} is negative, point moves to the
2118 beginning of the line.
2120 If it is impossible to move to column @var{column} because that is in
2121 the middle of a multicolumn character such as a tab, point moves to the
2122 end of that character. However, if @var{force} is non-@code{nil}, and
2123 @var{column} is in the middle of a tab, then @code{move-to-column}
2124 converts the tab into spaces so that it can move precisely to column
2125 @var{column}. Other multicolumn characters can cause anomalies despite
2126 @var{force}, since there is no way to split them.
2128 The argument @var{force} also has an effect if the line isn't long
2129 enough to reach column @var{column}; if it is @code{t}, that means to
2130 add whitespace at the end of the line to reach that column.
2132 The return value is the column number actually moved to.
2136 @section Indentation
2139 The indentation functions are used to examine, move to, and change
2140 whitespace that is at the beginning of a line. Some of the functions
2141 can also change whitespace elsewhere on a line. Columns and indentation
2142 count from zero at the left margin.
2145 * Primitive Indent:: Functions used to count and insert indentation.
2146 * Mode-Specific Indent:: Customize indentation for different modes.
2147 * Region Indent:: Indent all the lines in a region.
2148 * Relative Indent:: Indent the current line based on previous lines.
2149 * Indent Tabs:: Adjustable, typewriter-like tab stops.
2150 * Motion by Indent:: Move to first non-blank character.
2153 @node Primitive Indent
2154 @subsection Indentation Primitives
2156 This section describes the primitive functions used to count and
2157 insert indentation. The functions in the following sections use these
2158 primitives. @xref{Width}, for related functions.
2160 @defun current-indentation
2161 @comment !!Type Primitive Function
2162 @comment !!SourceFile indent.c
2163 This function returns the indentation of the current line, which is
2164 the horizontal position of the first nonblank character. If the
2165 contents are entirely blank, then this is the horizontal position of the
2169 @deffn Command indent-to column &optional minimum
2170 @comment !!Type Primitive Function
2171 @comment !!SourceFile indent.c
2172 This function indents from point with tabs and spaces until @var{column}
2173 is reached. If @var{minimum} is specified and non-@code{nil}, then at
2174 least that many spaces are inserted even if this requires going beyond
2175 @var{column}. Otherwise the function does nothing if point is already
2176 beyond @var{column}. The value is the column at which the inserted
2179 The inserted whitespace characters inherit text properties from the
2180 surrounding text (usually, from the preceding text only). @xref{Sticky
2184 @defopt indent-tabs-mode
2185 @comment !!SourceFile indent.c
2186 If this variable is non-@code{nil}, indentation functions can insert
2187 tabs as well as spaces. Otherwise, they insert only spaces. Setting
2188 this variable automatically makes it buffer-local in the current buffer.
2191 @node Mode-Specific Indent
2192 @subsection Indentation Controlled by Major Mode
2194 An important function of each major mode is to customize the @key{TAB}
2195 key to indent properly for the language being edited. This section
2196 describes the mechanism of the @key{TAB} key and how to control it.
2197 The functions in this section return unpredictable values.
2199 @deffn Command indent-for-tab-command &optional rigid
2200 This is the command bound to @key{TAB} in most editing modes. Its
2201 usual action is to indent the current line, but it can alternatively
2202 insert a tab character or indent a region.
2204 Here is what it does:
2208 First, it checks whether Transient Mark mode is enabled and the region
2209 is active. If so, it called @code{indent-region} to indent all the
2210 text in the region (@pxref{Region Indent}).
2213 Otherwise, if the indentation function in @code{indent-line-function}
2214 is @code{indent-to-left-margin} (a trivial command that inserts a tab
2215 character), or if the variable @code{tab-always-indent} specifies that
2216 a tab character ought to be inserted (see below), then it inserts a
2220 Otherwise, it indents the current line; this is done by calling the
2221 function in @code{indent-line-function}. If the line is already
2222 indented, and the value of @code{tab-always-indent} is @code{complete}
2223 (see below), it tries completing the text at point.
2226 If @var{rigid} is non-@code{nil} (interactively, with a prefix
2227 argument), then after this command indents a line or inserts a tab, it
2228 also rigidly indents the entire balanced expression which starts at
2229 the beginning of the current line, in order to reflect the new
2230 indentation. This argument is ignored if the command indents the
2234 @defvar indent-line-function
2235 This variable's value is the function to be used by
2236 @code{indent-for-tab-command}, and various other indentation commands,
2237 to indent the current line. It is usually assigned by the major mode;
2238 for instance, Lisp mode sets it to @code{lisp-indent-line}, C mode
2239 sets it to @code{c-indent-line}, and so on. The default value is
2240 @code{indent-relative}. @xref{Auto-Indentation}.
2243 @deffn Command indent-according-to-mode
2244 This command calls the function in @code{indent-line-function} to
2245 indent the current line in a way appropriate for the current major mode.
2248 @deffn Command newline-and-indent
2249 This function inserts a newline, then indents the new line (the one
2250 following the newline just inserted) according to the major mode. It
2251 does indentation by calling @code{indent-according-to-mode}.
2254 @deffn Command reindent-then-newline-and-indent
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
2257 inserted). It does indentation on both lines by calling
2258 @code{indent-according-to-mode}.
2261 @defopt tab-always-indent
2262 This variable can be used to customize the behavior of the @key{TAB}
2263 (@code{indent-for-tab-command}) command. If the value is @code{t}
2264 (the default), the command normally just indents the current line. If
2265 the value is @code{nil}, the command indents the current line only if
2266 point is at the left margin or in the line's indentation; otherwise,
2267 it inserts a tab character. If the value is @code{complete}, the
2268 command first tries to indent the current line, and if the line was
2269 already indented, it calls @code{completion-at-point} to complete the
2270 text at point (@pxref{Completion in Buffers}).
2274 @subsection Indenting an Entire Region
2276 This section describes commands that indent all the lines in the
2277 region. They return unpredictable values.
2279 @deffn Command indent-region start end &optional to-column
2280 This command indents each nonblank line starting between @var{start}
2281 (inclusive) and @var{end} (exclusive). If @var{to-column} is
2282 @code{nil}, @code{indent-region} indents each nonblank line by calling
2283 the current mode's indentation function, the value of
2284 @code{indent-line-function}.
2286 If @var{to-column} is non-@code{nil}, it should be an integer
2287 specifying the number of columns of indentation; then this function
2288 gives each line exactly that much indentation, by either adding or
2289 deleting whitespace.
2291 If there is a fill prefix, @code{indent-region} indents each line
2292 by making it start with the fill prefix.
2295 @defvar indent-region-function
2296 The value of this variable is a function that can be used by
2297 @code{indent-region} as a short cut. It should take two arguments, the
2298 start and end of the region. You should design the function so
2299 that it will produce the same results as indenting the lines of the
2300 region one by one, but presumably faster.
2302 If the value is @code{nil}, there is no short cut, and
2303 @code{indent-region} actually works line by line.
2305 A short-cut function is useful in modes such as C mode and Lisp mode,
2306 where the @code{indent-line-function} must scan from the beginning of
2307 the function definition: applying it to each line would be quadratic in
2308 time. The short cut can update the scan information as it moves through
2309 the lines indenting them; this takes linear time. In a mode where
2310 indenting a line individually is fast, there is no need for a short cut.
2312 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
2313 a different meaning and does not use this variable.
2316 @deffn Command indent-rigidly start end count
2317 This command indents all lines starting between @var{start}
2318 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
2319 This ``preserves the shape'' of the affected region, moving it as a
2320 rigid unit. Consequently, this command is useful not only for indenting
2321 regions of unindented text, but also for indenting regions of formatted
2324 For example, if @var{count} is 3, this command adds 3 columns of
2325 indentation to each of the lines beginning in the region specified.
2327 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
2328 @code{indent-rigidly} to indent the text copied from the message being
2332 @deffn Command indent-code-rigidly start end columns &optional nochange-regexp
2333 This is like @code{indent-rigidly}, except that it doesn't alter lines
2334 that start within strings or comments.
2336 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
2337 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
2340 @node Relative Indent
2341 @subsection Indentation Relative to Previous Lines
2343 This section describes two commands that indent the current line
2344 based on the contents of previous lines.
2346 @deffn Command indent-relative &optional unindented-ok
2347 This command inserts whitespace at point, extending to the same
2348 column as the next @dfn{indent point} of the previous nonblank line. An
2349 indent point is a non-whitespace character following whitespace. The
2350 next indent point is the first one at a column greater than the current
2351 column of point. For example, if point is underneath and to the left of
2352 the first non-blank character of a line of text, it moves to that column
2353 by inserting whitespace.
2355 If the previous nonblank line has no next indent point (i.e., none at a
2356 great enough column position), @code{indent-relative} either does
2357 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
2358 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right
2359 of the last column of a short line of text, this command ordinarily
2360 moves point to the next tab stop by inserting whitespace.
2362 The return value of @code{indent-relative} is unpredictable.
2364 In the following example, point is at the beginning of the second
2369 This line is indented twelve spaces.
2370 @point{}The quick brown fox jumped.
2375 Evaluation of the expression @code{(indent-relative nil)} produces the
2380 This line is indented twelve spaces.
2381 @point{}The quick brown fox jumped.
2385 In this next example, point is between the @samp{m} and @samp{p} of
2390 This line is indented twelve spaces.
2391 The quick brown fox jum@point{}ped.
2396 Evaluation of the expression @code{(indent-relative nil)} produces the
2401 This line is indented twelve spaces.
2402 The quick brown fox jum @point{}ped.
2407 @deffn Command indent-relative-maybe
2408 @comment !!SourceFile indent.el
2409 This command indents the current line like the previous nonblank line,
2410 by calling @code{indent-relative} with @code{t} as the
2411 @var{unindented-ok} argument. The return value is unpredictable.
2413 If the previous nonblank line has no indent points beyond the current
2414 column, this command does nothing.
2418 @comment node-name, next, previous, up
2419 @subsection Adjustable ``Tab Stops''
2420 @cindex tabs stops for indentation
2422 This section explains the mechanism for user-specified ``tab stops''
2423 and the mechanisms that use and set them. The name ``tab stops'' is
2424 used because the feature is similar to that of the tab stops on a
2425 typewriter. The feature works by inserting an appropriate number of
2426 spaces and tab characters to reach the next tab stop column; it does not
2427 affect the display of tab characters in the buffer (@pxref{Usual
2428 Display}). Note that the @key{TAB} character as input uses this tab
2429 stop feature only in a few major modes, such as Text mode.
2430 @xref{Tab Stops,,, emacs, The GNU Emacs Manual}.
2432 @deffn Command tab-to-tab-stop
2433 This command inserts spaces or tabs before point, up to the next tab
2434 stop column defined by @code{tab-stop-list}. It searches the list for
2435 an element greater than the current column number, and uses that element
2436 as the column to indent to. It does nothing if no such element is
2440 @defopt tab-stop-list
2441 This variable is the list of tab stop columns used by
2442 @code{tab-to-tab-stops}. The elements should be integers in increasing
2443 order. The tab stop columns need not be evenly spaced.
2445 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
2449 @node Motion by Indent
2450 @subsection Indentation-Based Motion Commands
2452 These commands, primarily for interactive use, act based on the
2453 indentation in the text.
2455 @deffn Command back-to-indentation
2456 @comment !!SourceFile simple.el
2457 This command moves point to the first non-whitespace character in the
2458 current line (which is the line in which point is located). It returns
2462 @deffn Command backward-to-indentation &optional arg
2463 @comment !!SourceFile simple.el
2464 This command moves point backward @var{arg} lines and then to the
2465 first nonblank character on that line. It returns @code{nil}.
2466 If @var{arg} is omitted or @code{nil}, it defaults to 1.
2469 @deffn Command forward-to-indentation &optional arg
2470 @comment !!SourceFile simple.el
2471 This command moves point forward @var{arg} lines and then to the first
2472 nonblank character on that line. It returns @code{nil}.
2473 If @var{arg} is omitted or @code{nil}, it defaults to 1.
2477 @comment node-name, next, previous, up
2478 @section Case Changes
2479 @cindex case conversion in buffers
2481 The case change commands described here work on text in the current
2482 buffer. @xref{Case Conversion}, for case conversion functions that work
2483 on strings and characters. @xref{Case Tables}, for how to customize
2484 which characters are upper or lower case and how to convert them.
2486 @deffn Command capitalize-region start end
2487 This function capitalizes all words in the region defined by
2488 @var{start} and @var{end}. To capitalize means to convert each word's
2489 first character to upper case and convert the rest of each word to lower
2490 case. The function returns @code{nil}.
2492 If one end of the region is in the middle of a word, the part of the
2493 word within the region is treated as an entire word.
2495 When @code{capitalize-region} is called interactively, @var{start} and
2496 @var{end} are point and the mark, with the smallest first.
2500 ---------- Buffer: foo ----------
2501 This is the contents of the 5th foo.
2502 ---------- Buffer: foo ----------
2506 (capitalize-region 1 44)
2509 ---------- Buffer: foo ----------
2510 This Is The Contents Of The 5th Foo.
2511 ---------- Buffer: foo ----------
2516 @deffn Command downcase-region start end
2517 This function converts all of the letters in the region defined by
2518 @var{start} and @var{end} to lower case. The function returns
2521 When @code{downcase-region} is called interactively, @var{start} and
2522 @var{end} are point and the mark, with the smallest first.
2525 @deffn Command upcase-region start end
2526 This function converts all of the letters in the region defined by
2527 @var{start} and @var{end} to upper case. The function returns
2530 When @code{upcase-region} is called interactively, @var{start} and
2531 @var{end} are point and the mark, with the smallest first.
2534 @deffn Command capitalize-word count
2535 This function capitalizes @var{count} words after point, moving point
2536 over as it does. To capitalize means to convert each word's first
2537 character to upper case and convert the rest of each word to lower case.
2538 If @var{count} is negative, the function capitalizes the
2539 @minus{}@var{count} previous words but does not move point. The value
2542 If point is in the middle of a word, the part of the word before point
2543 is ignored when moving forward. The rest is treated as an entire word.
2545 When @code{capitalize-word} is called interactively, @var{count} is
2546 set to the numeric prefix argument.
2549 @deffn Command downcase-word count
2550 This function converts the @var{count} words after point to all lower
2551 case, moving point over as it does. If @var{count} is negative, it
2552 converts the @minus{}@var{count} previous words but does not move point.
2553 The value is @code{nil}.
2555 When @code{downcase-word} is called interactively, @var{count} is set
2556 to the numeric prefix argument.
2559 @deffn Command upcase-word count
2560 This function converts the @var{count} words after point to all upper
2561 case, moving point over as it does. If @var{count} is negative, it
2562 converts the @minus{}@var{count} previous words but does not move point.
2563 The value is @code{nil}.
2565 When @code{upcase-word} is called interactively, @var{count} is set to
2566 the numeric prefix argument.
2569 @node Text Properties
2570 @section Text Properties
2571 @cindex text properties
2572 @cindex attributes of text
2573 @cindex properties of text
2575 Each character position in a buffer or a string can have a @dfn{text
2576 property list}, much like the property list of a symbol (@pxref{Property
2577 Lists}). The properties belong to a particular character at a
2578 particular place, such as, the letter @samp{T} at the beginning of this
2579 sentence or the first @samp{o} in @samp{foo}---if the same character
2580 occurs in two different places, the two occurrences in general have
2581 different properties.
2583 Each property has a name and a value. Both of these can be any Lisp
2584 object, but the name is normally a symbol. Typically each property
2585 name symbol is used for a particular purpose; for instance, the text
2586 property @code{face} specifies the faces for displaying the character
2587 (@pxref{Special Properties}). The usual way to access the property
2588 list is to specify a name and ask what value corresponds to it.
2590 If a character has a @code{category} property, we call it the
2591 @dfn{property category} of the character. It should be a symbol. The
2592 properties of the symbol serve as defaults for the properties of the
2595 Copying text between strings and buffers preserves the properties
2596 along with the characters; this includes such diverse functions as
2597 @code{substring}, @code{insert}, and @code{buffer-substring}.
2600 * Examining Properties:: Looking at the properties of one character.
2601 * Changing Properties:: Setting the properties of a range of text.
2602 * Property Search:: Searching for where a property changes value.
2603 * Special Properties:: Particular properties with special meanings.
2604 * Format Properties:: Properties for representing formatting of text.
2605 * Sticky Properties:: How inserted text gets properties from
2607 * Lazy Properties:: Computing text properties in a lazy fashion
2608 only when text is examined.
2609 * Clickable Text:: Using text properties to make regions of text
2610 do something when you click on them.
2611 * Fields:: The @code{field} property defines
2612 fields within the buffer.
2613 * Not Intervals:: Why text properties do not use
2614 Lisp-visible text intervals.
2617 @node Examining Properties
2618 @subsection Examining Text Properties
2620 The simplest way to examine text properties is to ask for the value of
2621 a particular property of a particular character. For that, use
2622 @code{get-text-property}. Use @code{text-properties-at} to get the
2623 entire property list of a character. @xref{Property Search}, for
2624 functions to examine the properties of a number of characters at once.
2626 These functions handle both strings and buffers. Keep in mind that
2627 positions in a string start from 0, whereas positions in a buffer start
2630 @defun get-text-property pos prop &optional object
2631 This function returns the value of the @var{prop} property of the
2632 character after position @var{pos} in @var{object} (a buffer or
2633 string). The argument @var{object} is optional and defaults to the
2636 If there is no @var{prop} property strictly speaking, but the character
2637 has a property category that is a symbol, then @code{get-text-property} returns
2638 the @var{prop} property of that symbol.
2641 @defun get-char-property position prop &optional object
2642 This function is like @code{get-text-property}, except that it checks
2643 overlays first and then text properties. @xref{Overlays}.
2645 The argument @var{object} may be a string, a buffer, or a window. If
2646 it is a window, then the buffer displayed in that window is used for
2647 text properties and overlays, but only the overlays active for that
2648 window are considered. If @var{object} is a buffer, then overlays in
2649 that buffer are considered first, in order of decreasing priority,
2650 followed by the text properties. If @var{object} is a string, only
2651 text properties are considered, since strings never have overlays.
2654 @defun get-char-property-and-overlay position prop &optional object
2655 This is like @code{get-char-property}, but gives extra information
2656 about the overlay that the property value comes from.
2658 Its value is a cons cell whose @sc{car} is the property value, the
2659 same value @code{get-char-property} would return with the same
2660 arguments. Its @sc{cdr} is the overlay in which the property was
2661 found, or @code{nil}, if it was found as a text property or not found
2664 If @var{position} is at the end of @var{object}, both the @sc{car} and
2665 the @sc{cdr} of the value are @code{nil}.
2668 @defvar char-property-alias-alist
2669 This variable holds an alist which maps property names to a list of
2670 alternative property names. If a character does not specify a direct
2671 value for a property, the alternative property names are consulted in
2672 order; the first non-@code{nil} value is used. This variable takes
2673 precedence over @code{default-text-properties}, and @code{category}
2674 properties take precedence over this variable.
2677 @defun text-properties-at position &optional object
2678 This function returns the entire property list of the character at
2679 @var{position} in the string or buffer @var{object}. If @var{object} is
2680 @code{nil}, it defaults to the current buffer.
2683 @defvar default-text-properties
2684 This variable holds a property list giving default values for text
2685 properties. Whenever a character does not specify a value for a
2686 property, neither directly, through a category symbol, or through
2687 @code{char-property-alias-alist}, the value stored in this list is
2688 used instead. Here is an example:
2691 (setq default-text-properties '(foo 69)
2692 char-property-alias-alist nil)
2693 ;; @r{Make sure character 1 has no properties of its own.}
2694 (set-text-properties 1 2 nil)
2695 ;; @r{What we get, when we ask, is the default value.}
2696 (get-text-property 1 'foo)
2701 @node Changing Properties
2702 @subsection Changing Text Properties
2704 The primitives for changing properties apply to a specified range of
2705 text in a buffer or string. The function @code{set-text-properties}
2706 (see end of section) sets the entire property list of the text in that
2707 range; more often, it is useful to add, change, or delete just certain
2708 properties specified by name.
2710 Since text properties are considered part of the contents of the
2711 buffer (or string), and can affect how a buffer looks on the screen,
2712 any change in buffer text properties marks the buffer as modified.
2713 Buffer text property changes are undoable also (@pxref{Undo}).
2714 Positions in a string start from 0, whereas positions in a buffer
2717 @defun put-text-property start end prop value &optional object
2718 This function sets the @var{prop} property to @var{value} for the text
2719 between @var{start} and @var{end} in the string or buffer @var{object}.
2720 If @var{object} is @code{nil}, it defaults to the current buffer.
2723 @defun add-text-properties start end props &optional object
2724 This function adds or overrides text properties for the text between
2725 @var{start} and @var{end} in the string or buffer @var{object}. If
2726 @var{object} is @code{nil}, it defaults to the current buffer.
2728 The argument @var{props} specifies which properties to add. It should
2729 have the form of a property list (@pxref{Property Lists}): a list whose
2730 elements include the property names followed alternately by the
2731 corresponding values.
2733 The return value is @code{t} if the function actually changed some
2734 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2735 its values agree with those in the text).
2737 For example, here is how to set the @code{comment} and @code{face}
2738 properties of a range of text:
2741 (add-text-properties @var{start} @var{end}
2742 '(comment t face highlight))
2746 @defun remove-text-properties start end props &optional object
2747 This function deletes specified text properties from the text between
2748 @var{start} and @var{end} in the string or buffer @var{object}. If
2749 @var{object} is @code{nil}, it defaults to the current buffer.
2751 The argument @var{props} specifies which properties to delete. It
2752 should have the form of a property list (@pxref{Property Lists}): a list
2753 whose elements are property names alternating with corresponding values.
2754 But only the names matter---the values that accompany them are ignored.
2755 For example, here's how to remove the @code{face} property.
2758 (remove-text-properties @var{start} @var{end} '(face nil))
2761 The return value is @code{t} if the function actually changed some
2762 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2763 if no character in the specified text had any of those properties).
2765 To remove all text properties from certain text, use
2766 @code{set-text-properties} and specify @code{nil} for the new property
2770 @defun remove-list-of-text-properties start end list-of-properties &optional object
2771 Like @code{remove-text-properties} except that
2772 @var{list-of-properties} is a list of property names only, not an
2773 alternating list of property names and values.
2776 @defun set-text-properties start end props &optional object
2777 This function completely replaces the text property list for the text
2778 between @var{start} and @var{end} in the string or buffer @var{object}.
2779 If @var{object} is @code{nil}, it defaults to the current buffer.
2781 The argument @var{props} is the new property list. It should be a list
2782 whose elements are property names alternating with corresponding values.
2784 After @code{set-text-properties} returns, all the characters in the
2785 specified range have identical properties.
2787 If @var{props} is @code{nil}, the effect is to get rid of all properties
2788 from the specified range of text. Here's an example:
2791 (set-text-properties @var{start} @var{end} nil)
2794 Do not rely on the return value of this function.
2797 The easiest way to make a string with text properties
2798 is with @code{propertize}:
2800 @defun propertize string &rest properties
2801 This function returns a copy of @var{string} which has the text
2802 properties @var{properties}. These properties apply to all the
2803 characters in the string that is returned. Here is an example that
2804 constructs a string with a @code{face} property and a @code{mouse-face}
2808 (propertize "foo" 'face 'italic
2809 'mouse-face 'bold-italic)
2810 @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
2813 To put different properties on various parts of a string, you can
2814 construct each part with @code{propertize} and then combine them with
2819 (propertize "foo" 'face 'italic
2820 'mouse-face 'bold-italic)
2822 (propertize "bar" 'face 'italic
2823 'mouse-face 'bold-italic))
2824 @result{} #("foo and bar"
2825 0 3 (face italic mouse-face bold-italic)
2827 8 11 (face italic mouse-face bold-italic))
2831 @xref{Buffer Contents}, for the function
2832 @code{buffer-substring-no-properties}, which copies text from the
2833 buffer but does not copy its properties.
2835 @node Property Search
2836 @subsection Text Property Search Functions
2838 In typical use of text properties, most of the time several or many
2839 consecutive characters have the same value for a property. Rather than
2840 writing your programs to examine characters one by one, it is much
2841 faster to process chunks of text that have the same property value.
2843 Here are functions you can use to do this. They use @code{eq} for
2844 comparing property values. In all cases, @var{object} defaults to the
2847 For good performance, it's very important to use the @var{limit}
2848 argument to these functions, especially the ones that search for a
2849 single property---otherwise, they may spend a long time scanning to the
2850 end of the buffer, if the property you are interested in does not change.
2852 These functions do not move point; instead, they return a position (or
2853 @code{nil}). Remember that a position is always between two characters;
2854 the position returned by these functions is between two characters with
2855 different properties.
2857 @defun next-property-change pos &optional object limit
2858 The function scans the text forward from position @var{pos} in the
2859 string or buffer @var{object} until it finds a change in some text
2860 property, then returns the position of the change. In other words, it
2861 returns the position of the first character beyond @var{pos} whose
2862 properties are not identical to those of the character just after
2865 If @var{limit} is non-@code{nil}, then the scan ends at position
2866 @var{limit}. If there is no property change before that point, this
2867 function returns @var{limit}.
2869 The value is @code{nil} if the properties remain unchanged all the way
2870 to the end of @var{object} and @var{limit} is @code{nil}. If the value
2871 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
2872 The value equals @var{pos} only when @var{limit} equals @var{pos}.
2874 Here is an example of how to scan the buffer by chunks of text within
2875 which all properties are constant:
2879 (let ((plist (text-properties-at (point)))
2881 (or (next-property-change (point) (current-buffer))
2883 @r{Process text from point to @var{next-change}@dots{}}
2884 (goto-char next-change)))
2888 @defun previous-property-change pos &optional object limit
2889 This is like @code{next-property-change}, but scans back from @var{pos}
2890 instead of forward. If the value is non-@code{nil}, it is a position
2891 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
2895 @defun next-single-property-change pos prop &optional object limit
2896 The function scans text for a change in the @var{prop} property, then
2897 returns the position of the change. The scan goes forward from
2898 position @var{pos} in the string or buffer @var{object}. In other
2899 words, this function returns the position of the first character
2900 beyond @var{pos} whose @var{prop} property differs from that of the
2901 character just after @var{pos}.
2903 If @var{limit} is non-@code{nil}, then the scan ends at position
2904 @var{limit}. If there is no property change before that point,
2905 @code{next-single-property-change} returns @var{limit}.
2907 The value is @code{nil} if the property remains unchanged all the way to
2908 the end of @var{object} and @var{limit} is @code{nil}. If the value is
2909 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
2910 equals @var{pos} only if @var{limit} equals @var{pos}.
2913 @defun previous-single-property-change pos prop &optional object limit
2914 This is like @code{next-single-property-change}, but scans back from
2915 @var{pos} instead of forward. If the value is non-@code{nil}, it is a
2916 position less than or equal to @var{pos}; it equals @var{pos} only if
2917 @var{limit} equals @var{pos}.
2920 @defun next-char-property-change pos &optional limit
2921 This is like @code{next-property-change} except that it considers
2922 overlay properties as well as text properties, and if no change is
2923 found before the end of the buffer, it returns the maximum buffer
2924 position rather than @code{nil} (in this sense, it resembles the
2925 corresponding overlay function @code{next-overlay-change}, rather than
2926 @code{next-property-change}). There is no @var{object} operand
2927 because this function operates only on the current buffer. It returns
2928 the next address at which either kind of property changes.
2931 @defun previous-char-property-change pos &optional limit
2932 This is like @code{next-char-property-change}, but scans back from
2933 @var{pos} instead of forward, and returns the minimum buffer
2934 position if no change is found.
2937 @defun next-single-char-property-change pos prop &optional object limit
2938 This is like @code{next-single-property-change} except that it
2939 considers overlay properties as well as text properties, and if no
2940 change is found before the end of the @var{object}, it returns the
2941 maximum valid position in @var{object} rather than @code{nil}. Unlike
2942 @code{next-char-property-change}, this function @emph{does} have an
2943 @var{object} operand; if @var{object} is not a buffer, only
2944 text-properties are considered.
2947 @defun previous-single-char-property-change pos prop &optional object limit
2948 This is like @code{next-single-char-property-change}, but scans back
2949 from @var{pos} instead of forward, and returns the minimum valid
2950 position in @var{object} if no change is found.
2953 @defun text-property-any start end prop value &optional object
2954 This function returns non-@code{nil} if at least one character between
2955 @var{start} and @var{end} has a property @var{prop} whose value is
2956 @var{value}. More precisely, it returns the position of the first such
2957 character. Otherwise, it returns @code{nil}.
2959 The optional fifth argument, @var{object}, specifies the string or
2960 buffer to scan. Positions are relative to @var{object}. The default
2961 for @var{object} is the current buffer.
2964 @defun text-property-not-all start end prop value &optional object
2965 This function returns non-@code{nil} if at least one character between
2966 @var{start} and @var{end} does not have a property @var{prop} with value
2967 @var{value}. More precisely, it returns the position of the first such
2968 character. Otherwise, it returns @code{nil}.
2970 The optional fifth argument, @var{object}, specifies the string or
2971 buffer to scan. Positions are relative to @var{object}. The default
2972 for @var{object} is the current buffer.
2975 @node Special Properties
2976 @subsection Properties with Special Meanings
2978 Here is a table of text property names that have special built-in
2979 meanings. The following sections list a few additional special property
2980 names that control filling and property inheritance. All other names
2981 have no standard meaning, and you can use them as you like.
2983 Note: the properties @code{composition}, @code{display},
2984 @code{invisible} and @code{intangible} can also cause point to move to
2985 an acceptable place, after each Emacs command. @xref{Adjusting
2989 @cindex property category of text character
2990 @kindex category @r{(text property)}
2992 If a character has a @code{category} property, we call it the
2993 @dfn{property category} of the character. It should be a symbol. The
2994 properties of this symbol serve as defaults for the properties of the
2998 @cindex face codes of text
2999 @kindex face @r{(text property)}
3000 The @code{face} property controls the appearance of the character,
3001 such as its font and color. @xref{Faces}. The value of the property
3002 can be the following:
3006 A face name (a symbol or string).
3009 A property list of face attributes. This has the
3010 form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
3011 face attribute name and @var{value} is a meaningful value for that
3012 attribute. With this feature, you do not need to create a face each
3013 time you want to specify a particular attribute for certain text.
3014 @xref{Face Attributes}.
3017 A list, where each element uses one of the two forms listed above.
3020 Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
3021 dynamically updating the @code{face} property of characters based on
3024 @item font-lock-face
3025 @kindex font-lock-face @r{(text property)}
3026 This property specifies a value for the @code{face} property that Font
3027 Lock mode should apply to the underlying text. It is one of the
3028 fontification methods used by Font Lock mode, and is useful for
3029 special modes that implement their own highlighting.
3030 @xref{Precalculated Fontification}. When Font Lock mode is disabled,
3031 @code{font-lock-face} has no effect.
3034 @kindex mouse-face @r{(text property)}
3035 This property is used instead of @code{face} when the mouse is on or
3036 near the character. For this purpose, ``near'' means that all text
3037 between the character and where the mouse is have the same
3038 @code{mouse-face} property value.
3040 Emacs ignores all face attributes from the @code{mouse-face} property
3041 that alter the text size (e.g. @code{:height}, @code{:weight}, and
3042 @code{:slant}). Those attributes are always the same as for the
3046 @kindex fontified @r{(text property)}
3047 This property says whether the text is ready for display. If
3048 @code{nil}, Emacs's redisplay routine calls the functions in
3049 @code{fontification-functions} (@pxref{Auto Faces}) to prepare this
3050 part of the buffer before it is displayed. It is used internally by
3051 the ``just in time'' font locking code.
3054 This property activates various features that change the
3055 way text is displayed. For example, it can make text appear taller
3056 or shorter, higher or lower, wider or narrow, or replaced with an image.
3057 @xref{Display Property}.
3060 @kindex help-echo @r{(text property)}
3062 @anchor{Text help-echo}
3063 If text has a string as its @code{help-echo} property, then when you
3064 move the mouse onto that text, Emacs displays that string in the echo
3065 area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
3068 If the value of the @code{help-echo} property is a function, that
3069 function is called with three arguments, @var{window}, @var{object} and
3070 @var{pos} and should return a help string or @code{nil} for
3071 none. The first argument, @var{window} is the window in which
3072 the help was found. The second, @var{object}, is the buffer, overlay or
3073 string which had the @code{help-echo} property. The @var{pos}
3074 argument is as follows:
3078 If @var{object} is a buffer, @var{pos} is the position in the buffer.
3080 If @var{object} is an overlay, that overlay has a @code{help-echo}
3081 property, and @var{pos} is the position in the overlay's buffer.
3083 If @var{object} is a string (an overlay string or a string displayed
3084 with the @code{display} property), @var{pos} is the position in that
3088 If the value of the @code{help-echo} property is neither a function nor
3089 a string, it is evaluated to obtain a help string.
3091 You can alter the way help text is displayed by setting the variable
3092 @code{show-help-function} (@pxref{Help display}).
3094 This feature is used in the mode line and for other active text.
3097 @cindex keymap of character
3098 @kindex keymap @r{(text property)}
3099 The @code{keymap} property specifies an additional keymap for
3100 commands. When this keymap applies, it is used for key lookup before
3101 the minor mode keymaps and before the buffer's local map.
3102 @xref{Active Keymaps}. If the property value is a symbol, the
3103 symbol's function definition is used as the keymap.
3105 The property's value for the character before point applies if it is
3106 non-@code{nil} and rear-sticky, and the property's value for the
3107 character after point applies if it is non-@code{nil} and
3108 front-sticky. (For mouse clicks, the position of the click is used
3109 instead of the position of point.)
3112 @kindex local-map @r{(text property)}
3113 This property works like @code{keymap} except that it specifies a
3114 keymap to use @emph{instead of} the buffer's local map. For most
3115 purposes (perhaps all purposes), it is better to use the @code{keymap}
3119 The @code{syntax-table} property overrides what the syntax table says
3120 about this particular character. @xref{Syntax Properties}.
3123 @cindex read-only character
3124 @kindex read-only @r{(text property)}
3125 If a character has the property @code{read-only}, then modifying that
3126 character is not allowed. Any command that would do so gets an error,
3127 @code{text-read-only}. If the property value is a string, that string
3128 is used as the error message.
3130 Insertion next to a read-only character is an error if inserting
3131 ordinary text there would inherit the @code{read-only} property due to
3132 stickiness. Thus, you can control permission to insert next to
3133 read-only text by controlling the stickiness. @xref{Sticky Properties}.
3135 Since changing properties counts as modifying the buffer, it is not
3136 possible to remove a @code{read-only} property unless you know the
3137 special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
3138 and then remove the property. @xref{Read Only Buffers}.
3141 @kindex invisible @r{(text property)}
3142 A non-@code{nil} @code{invisible} property can make a character invisible
3143 on the screen. @xref{Invisible Text}, for details.
3146 @kindex intangible @r{(text property)}
3147 If a group of consecutive characters have equal and non-@code{nil}
3148 @code{intangible} properties, then you cannot place point between them.
3149 If you try to move point forward into the group, point actually moves to
3150 the end of the group. If you try to move point backward into the group,
3151 point actually moves to the start of the group.
3153 If consecutive characters have unequal non-@code{nil}
3154 @code{intangible} properties, they belong to separate groups; each
3155 group is separately treated as described above.
3157 When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
3158 the @code{intangible} property is ignored.
3160 Beware: this property operates at a very low level, and affects a lot of code
3161 in unexpected ways. So use it with extreme caution. A common misuse is to put
3162 an intangible property on invisible text, which is actually unnecessary since
3163 the command loop will move point outside of the invisible text at the end of
3164 each command anyway. @xref{Adjusting Point}.
3167 @kindex field @r{(text property)}
3168 Consecutive characters with the same @code{field} property constitute a
3169 @dfn{field}. Some motion functions including @code{forward-word} and
3170 @code{beginning-of-line} stop moving at a field boundary.
3174 @kindex cursor @r{(text property)}
3175 Normally, the cursor is displayed at the beginning or the end of any
3176 overlay and text property strings present at the current buffer
3177 position. You can place the cursor on any desired character of these
3178 strings by giving that character a non-@code{nil} @code{cursor} text
3179 property. In addition, if the value of the @code{cursor} property is
3180 an integer number, it specifies the number of buffer's character
3181 positions, starting with the position where the overlay or the
3182 @code{display} property begins, for which the cursor should be
3183 displayed on that character. Specifically, if the value of the
3184 @code{cursor} property of a character is the number @var{n}, the
3185 cursor will be displayed on this character for any buffer position in
3186 the range @code{[@var{ovpos}..@var{ovpos}+@var{n})}, where @var{ovpos}
3187 is the overlay's starting position given by @code{overlay-start}
3188 (@pxref{Managing Overlays}), or the position where the @code{display}
3189 text property begins in the buffer.
3191 In other words, the string character with the @code{cursor} property
3192 of any non-@code{nil} value is the character where to display the
3193 cursor. The value of the property says for which buffer positions to
3194 display the cursor there. If the value is an integer number @var{n},
3195 the cursor is displayed there when point is anywhere between the
3196 beginning of the overlay or @code{display} property and @var{n}
3197 positions after that. If the value is anything else and
3198 non-@code{nil}, the cursor is displayed there only when point is at
3199 the beginning of the @code{display} property or at
3200 @code{overlay-start}.
3202 @cindex cursor position for @code{display} properties and overlays
3203 When the buffer has many overlay strings (e.g., @pxref{Overlay
3204 Properties, before-string}) or @code{display} properties that are
3205 strings, it is a good idea to use the @code{cursor} property on these
3206 strings to cue the Emacs display about the places where to put the
3207 cursor while traversing these strings. This directly communicates to
3208 the display engine where the Lisp program wants to put the cursor, or
3209 where the user would expect the cursor.
3212 @kindex pointer @r{(text property)}
3213 This specifies a specific pointer shape when the mouse pointer is over
3214 this text or image. @xref{Pointer Shape}, for possible pointer
3218 @kindex line-spacing @r{(text property)}
3219 A newline can have a @code{line-spacing} text or overlay property that
3220 controls the height of the display line ending with that newline. The
3221 property value overrides the default frame line spacing and the buffer
3222 local @code{line-spacing} variable. @xref{Line Height}.
3225 @kindex line-height @r{(text property)}
3226 A newline can have a @code{line-height} text or overlay property that
3227 controls the total height of the display line ending in that newline.
3231 If text has a @code{wrap-prefix} property, the prefix it defines will
3232 be added at display time to the beginning of every continuation line
3233 due to text wrapping (so if lines are truncated, the wrap-prefix is
3234 never used). It may be a string or an image (@pxref{Other Display
3235 Specs}), or a stretch of whitespace such as specified by the
3236 @code{:width} or @code{:align-to} display properties (@pxref{Specified
3239 A wrap-prefix may also be specified for an entire buffer using the
3240 @code{wrap-prefix} buffer-local variable (however, a
3241 @code{wrap-prefix} text-property takes precedence over the value of
3242 the @code{wrap-prefix} variable). @xref{Truncation}.
3245 If text has a @code{line-prefix} property, the prefix it defines will
3246 be added at display time to the beginning of every non-continuation
3247 line. It may be a string or an image (@pxref{Other Display
3248 Specs}), or a stretch of whitespace such as specified by the
3249 @code{:width} or @code{:align-to} display properties (@pxref{Specified
3252 A line-prefix may also be specified for an entire buffer using the
3253 @code{line-prefix} buffer-local variable (however, a
3254 @code{line-prefix} text-property takes precedence over the value of
3255 the @code{line-prefix} variable). @xref{Truncation}.
3257 @item modification-hooks
3258 @cindex change hooks for a character
3259 @cindex hooks for changing a character
3260 @kindex modification-hooks @r{(text property)}
3261 If a character has the property @code{modification-hooks}, then its
3262 value should be a list of functions; modifying that character calls
3263 all of those functions before the actual modification. Each function
3264 receives two arguments: the beginning and end of the part of the
3265 buffer being modified. Note that if a particular modification hook
3266 function appears on several characters being modified by a single
3267 primitive, you can't predict how many times the function will
3269 Furthermore, insertion will not modify any existing character, so this
3270 hook will only be run when removing some characters, replacing them
3271 with others, or changing their text-properties.
3273 If these functions modify the buffer, they should bind
3274 @code{inhibit-modification-hooks} to @code{t} around doing so, to
3275 avoid confusing the internal mechanism that calls these hooks.
3277 Overlays also support the @code{modification-hooks} property, but the
3278 details are somewhat different (@pxref{Overlay Properties}).
3280 @item insert-in-front-hooks
3281 @itemx insert-behind-hooks
3282 @kindex insert-in-front-hooks @r{(text property)}
3283 @kindex insert-behind-hooks @r{(text property)}
3284 The operation of inserting text in a buffer also calls the functions
3285 listed in the @code{insert-in-front-hooks} property of the following
3286 character and in the @code{insert-behind-hooks} property of the
3287 preceding character. These functions receive two arguments, the
3288 beginning and end of the inserted text. The functions are called
3289 @emph{after} the actual insertion takes place.
3291 See also @ref{Change Hooks}, for other hooks that are called
3292 when you change text in a buffer.
3296 @cindex hooks for motion of point
3297 @kindex point-entered @r{(text property)}
3298 @kindex point-left @r{(text property)}
3299 The special properties @code{point-entered} and @code{point-left}
3300 record hook functions that report motion of point. Each time point
3301 moves, Emacs compares these two property values:
3305 the @code{point-left} property of the character after the old location,
3308 the @code{point-entered} property of the character after the new
3313 If these two values differ, each of them is called (if not @code{nil})
3314 with two arguments: the old value of point, and the new one.
3316 The same comparison is made for the characters before the old and new
3317 locations. The result may be to execute two @code{point-left} functions
3318 (which may be the same function) and/or two @code{point-entered}
3319 functions (which may be the same function). In any case, all the
3320 @code{point-left} functions are called first, followed by all the
3321 @code{point-entered} functions.
3323 It is possible to use @code{char-after} to examine characters at various
3324 buffer positions without moving point to those positions. Only an
3325 actual change in the value of point runs these hook functions.
3327 The variable @code{inhibit-point-motion-hooks} can inhibit running the
3328 @code{point-left} and @code{point-entered} hooks, see @ref{Inhibit
3329 point motion hooks}.
3332 @kindex composition @r{(text property)}
3333 This text property is used to display a sequence of characters as a
3334 single glyph composed from components. But the value of the property
3335 itself is completely internal to Emacs and should not be manipulated
3336 directly by, for instance, @code{put-text-property}.
3340 @defvar inhibit-point-motion-hooks
3341 @anchor{Inhibit point motion hooks} When this variable is
3342 non-@code{nil}, @code{point-left} and @code{point-entered} hooks are
3343 not run, and the @code{intangible} property has no effect. Do not set
3344 this variable globally; bind it with @code{let}.
3347 @defvar show-help-function
3348 @anchor{Help display} If this variable is non-@code{nil}, it specifies a
3349 function called to display help strings. These may be @code{help-echo}
3350 properties, menu help strings (@pxref{Simple Menu Items},
3351 @pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
3352 Bar}). The specified function is called with one argument, the help
3353 string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs
3354 Manual}) provides an example.
3357 @node Format Properties
3358 @subsection Formatted Text Properties
3360 These text properties affect the behavior of the fill commands. They
3361 are used for representing formatted text. @xref{Filling}, and
3366 If a newline character has this property, it is a ``hard'' newline.
3367 The fill commands do not alter hard newlines and do not move words
3368 across them. However, this property takes effect only if the
3369 @code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft
3370 Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
3373 This property specifies an extra right margin for filling this part of the
3377 This property specifies an extra left margin for filling this part of the
3381 This property specifies the style of justification for filling this part
3385 @node Sticky Properties
3386 @subsection Stickiness of Text Properties
3387 @cindex sticky text properties
3388 @cindex inheritance of text properties
3390 Self-inserting characters normally take on the same properties as the
3391 preceding character. This is called @dfn{inheritance} of properties.
3393 A Lisp program can do insertion with inheritance or without,
3394 depending on the choice of insertion primitive. The ordinary text
3395 insertion functions, such as @code{insert}, do not inherit any
3396 properties. They insert text with precisely the properties of the
3397 string being inserted, and no others. This is correct for programs
3398 that copy text from one context to another---for example, into or out
3399 of the kill ring. To insert with inheritance, use the special
3400 primitives described in this section. Self-inserting characters
3401 inherit properties because they work using these primitives.
3403 When you do insertion with inheritance, @emph{which} properties are
3404 inherited, and from where, depends on which properties are @dfn{sticky}.
3405 Insertion after a character inherits those of its properties that are
3406 @dfn{rear-sticky}. Insertion before a character inherits those of its
3407 properties that are @dfn{front-sticky}. When both sides offer different
3408 sticky values for the same property, the previous character's value
3411 By default, a text property is rear-sticky but not front-sticky; thus,
3412 the default is to inherit all the properties of the preceding character,
3413 and nothing from the following character.
3415 You can control the stickiness of various text properties with two
3416 specific text properties, @code{front-sticky} and @code{rear-nonsticky},
3417 and with the variable @code{text-property-default-nonsticky}. You can
3418 use the variable to specify a different default for a given property.
3419 You can use those two text properties to make any specific properties
3420 sticky or nonsticky in any particular part of the text.
3422 If a character's @code{front-sticky} property is @code{t}, then all
3423 its properties are front-sticky. If the @code{front-sticky} property is
3424 a list, then the sticky properties of the character are those whose
3425 names are in the list. For example, if a character has a
3426 @code{front-sticky} property whose value is @code{(face read-only)},
3427 then insertion before the character can inherit its @code{face} property
3428 and its @code{read-only} property, but no others.
3430 The @code{rear-nonsticky} property works the opposite way. Most
3431 properties are rear-sticky by default, so the @code{rear-nonsticky}
3432 property says which properties are @emph{not} rear-sticky. If a
3433 character's @code{rear-nonsticky} property is @code{t}, then none of its
3434 properties are rear-sticky. If the @code{rear-nonsticky} property is a
3435 list, properties are rear-sticky @emph{unless} their names are in the
3438 @defvar text-property-default-nonsticky
3439 This variable holds an alist which defines the default rear-stickiness
3440 of various text properties. Each element has the form
3441 @code{(@var{property} . @var{nonstickiness})}, and it defines the
3442 stickiness of a particular text property, @var{property}.
3444 If @var{nonstickiness} is non-@code{nil}, this means that the property
3445 @var{property} is rear-nonsticky by default. Since all properties are
3446 front-nonsticky by default, this makes @var{property} nonsticky in both
3447 directions by default.
3449 The text properties @code{front-sticky} and @code{rear-nonsticky}, when
3450 used, take precedence over the default @var{nonstickiness} specified in
3451 @code{text-property-default-nonsticky}.
3454 Here are the functions that insert text with inheritance of properties:
3456 @defun insert-and-inherit &rest strings
3457 Insert the strings @var{strings}, just like the function @code{insert},
3458 but inherit any sticky properties from the adjoining text.
3461 @defun insert-before-markers-and-inherit &rest strings
3462 Insert the strings @var{strings}, just like the function
3463 @code{insert-before-markers}, but inherit any sticky properties from the
3467 @xref{Insertion}, for the ordinary insertion functions which do not
3470 @node Lazy Properties
3471 @subsection Lazy Computation of Text Properties
3473 Instead of computing text properties for all the text in the buffer,
3474 you can arrange to compute the text properties for parts of the text
3475 when and if something depends on them.
3477 The primitive that extracts text from the buffer along with its
3478 properties is @code{buffer-substring}. Before examining the properties,
3479 this function runs the abnormal hook @code{buffer-access-fontify-functions}.
3481 @defvar buffer-access-fontify-functions
3482 This variable holds a list of functions for computing text properties.
3483 Before @code{buffer-substring} copies the text and text properties for a
3484 portion of the buffer, it calls all the functions in this list. Each of
3485 the functions receives two arguments that specify the range of the
3486 buffer being accessed. (The buffer itself is always the current
3490 The function @code{buffer-substring-no-properties} does not call these
3491 functions, since it ignores text properties anyway.
3493 In order to prevent the hook functions from being called more than
3494 once for the same part of the buffer, you can use the variable
3495 @code{buffer-access-fontified-property}.
3497 @defvar buffer-access-fontified-property
3498 If this variable's value is non-@code{nil}, it is a symbol which is used
3499 as a text property name. A non-@code{nil} value for that text property
3500 means, ``the other text properties for this character have already been
3503 If all the characters in the range specified for @code{buffer-substring}
3504 have a non-@code{nil} value for this property, @code{buffer-substring}
3505 does not call the @code{buffer-access-fontify-functions} functions. It
3506 assumes these characters already have the right text properties, and
3507 just copies the properties they already have.
3509 The normal way to use this feature is that the
3510 @code{buffer-access-fontify-functions} functions add this property, as
3511 well as others, to the characters they operate on. That way, they avoid
3512 being called over and over for the same text.
3515 @node Clickable Text
3516 @subsection Defining Clickable Text
3517 @cindex clickable text
3518 @cindex follow links
3521 @dfn{Clickable text} is text that can be clicked, with either the
3522 mouse or via a keyboard command, to produce some result. Many major
3523 modes use clickable text to implement textual hyper-links, or
3524 @dfn{links} for short.
3526 The easiest way to insert and manipulate links is to use the
3527 @code{button} package. @xref{Buttons}. In this section, we will
3528 explain how to manually set up clickable text in a buffer, using text
3529 properties. For simplicity, we will refer to the clickable text as a
3532 Implementing a link involves three separate steps: (1) indicating
3533 clickability when the mouse moves over the link; (2) making @key{RET}
3534 or @kbd{Mouse-2} on that link do something; and (3) setting up a
3535 @code{follow-link} condition so that the link obeys
3536 @code{mouse-1-click-follows-link}.
3538 To indicate clickability, add the @code{mouse-face} text property to
3539 the text of the link; then Emacs will highlight the link when the
3540 mouse moves over it. In addition, you should define a tooltip or echo
3541 area message, using the @code{help-echo} text property. @xref{Special
3542 Properties}. For instance, here is how Dired indicates that file
3543 names are clickable:
3546 (if (dired-move-to-filename)
3547 (add-text-properties
3550 (dired-move-to-end-of-filename)
3552 '(mouse-face highlight
3553 help-echo "mouse-2: visit this file in other window")))
3556 To make the link clickable, bind @key{RET} and @kbd{Mouse-2} to
3557 commands that perform the desired action. Each command should check
3558 to see whether it was called on a link, and act accordingly. For
3559 instance, Dired's major mode keymap binds @kbd{Mouse-2} to the
3563 (defun dired-mouse-find-file-other-window (event)
3564 "In Dired, visit the file or directory name you click on."
3566 (let ((window (posn-window (event-end event)))
3567 (pos (posn-point (event-end event)))
3569 (if (not (windowp window))
3570 (error "No file chosen"))
3571 (with-current-buffer (window-buffer window)
3573 (setq file (dired-get-file-for-visit)))
3574 (if (file-directory-p file)
3575 (or (and (cdr dired-subdir-alist)
3576 (dired-goto-subdir file))
3578 (select-window window)
3579 (dired-other-window file)))
3580 (select-window window)
3581 (find-file-other-window (file-name-sans-versions file t)))))
3585 This command uses the functions @code{posn-window} and
3586 @code{posn-point} to determine where the click occurred, and
3587 @code{dired-get-file-for-visit} to determine which file to visit.
3589 Instead of binding the mouse command in a major mode keymap, you can
3590 bind it within the link text, using the @code{keymap} text property
3591 (@pxref{Special Properties}). For instance:
3594 (let ((map (make-sparse-keymap)))
3595 (define-key map [mouse-2] 'operate-this-button)
3596 (put-text-property link-start link-end 'keymap map))
3600 With this method, you can easily define different commands for
3601 different links. Furthermore, the global definition of @key{RET} and
3602 @kbd{Mouse-2} remain available for the rest of the text in the buffer.
3604 @vindex mouse-1-click-follows-link
3605 The basic Emacs command for clicking on links is @kbd{Mouse-2}.
3606 However, for compatibility with other graphical applications, Emacs
3607 also recognizes @kbd{Mouse-1} clicks on links, provided the user
3608 clicks on the link quickly without moving the mouse. This behavior is
3609 controlled by the user option @code{mouse-1-click-follows-link}.
3610 @xref{Mouse References,,, emacs, The GNU Emacs Manual}.
3612 To set up the link so that it obeys
3613 @code{mouse-1-click-follows-link}, you must either (1) apply a
3614 @code{follow-link} text or overlay property to the link text, or (2)
3615 bind the @code{follow-link} event to a keymap (which can be a major
3616 mode keymap or a local keymap specified via the @code{keymap} text
3617 property). The value of the @code{follow-link} property, or the
3618 binding for the @code{follow-link} event, acts as a ``condition'' for
3619 the link action. This condition tells Emacs two things: the
3620 circumstances under which a @kbd{Mouse-1} click should be regarded as
3621 occurring ``inside'' the link, and how to compute an ``action code''
3622 that says what to translate the @kbd{Mouse-1} click into. The link
3623 action condition can be one of the following:
3626 @item @code{mouse-face}
3627 If the condition is the symbol @code{mouse-face}, a position is inside
3628 a link if there is a non-@code{nil} @code{mouse-face} property at that
3629 position. The action code is always @code{t}.
3631 For example, here is how Info mode handles @key{Mouse-1}:
3634 (define-key Info-mode-map [follow-link] 'mouse-face)
3638 If the condition is a function, @var{func}, then a position @var{pos}
3639 is inside a link if @code{(@var{func} @var{pos})} evaluates to
3640 non-@code{nil}. The value returned by @var{func} serves as the action
3643 For example, here is how pcvs enables @kbd{Mouse-1} to follow links on
3647 (define-key map [follow-link]
3649 (eq (get-char-property pos 'face) 'cvs-filename-face)))
3653 If the condition value is anything else, then the position is inside a
3654 link and the condition itself is the action code. Clearly, you should
3655 specify this kind of condition only when applying the condition via a
3656 text or property overlay on the link text (so that it does not apply
3657 to the entire buffer).
3661 The action code tells @kbd{Mouse-1} how to follow the link:
3664 @item a string or vector
3665 If the action code is a string or vector, the @kbd{Mouse-1} event is
3666 translated into the first element of the string or vector; i.e., the
3667 action of the @kbd{Mouse-1} click is the local or global binding of
3668 that character or symbol. Thus, if the action code is @code{"foo"},
3669 @kbd{Mouse-1} translates into @kbd{f}. If it is @code{[foo]},
3670 @kbd{Mouse-1} translates into @key{foo}.
3673 For any other non-@code{nil} action code, the @kbd{Mouse-1} event is
3674 translated into a @kbd{Mouse-2} event at the same position.
3677 To define @kbd{Mouse-1} to activate a button defined with
3678 @code{define-button-type}, give the button a @code{follow-link}
3679 property. The property value should be a link action condition, as
3680 described above. @xref{Buttons}. For example, here is how Help mode
3681 handles @kbd{Mouse-1}:
3684 (define-button-type 'help-xref
3686 'action #'help-button-action)
3689 To define @kbd{Mouse-1} on a widget defined with
3690 @code{define-widget}, give the widget a @code{:follow-link} property.
3691 The property value should be a link action condition, as described
3692 above. For example, here is how the @code{link} widget specifies that
3693 a @key{Mouse-1} click shall be translated to @key{RET}:
3696 (define-widget 'link 'item
3698 :button-prefix 'widget-link-prefix
3699 :button-suffix 'widget-link-suffix
3701 :help-echo "Follow the link."
3705 @defun mouse-on-link-p pos
3706 This function returns non-@code{nil} if position @var{pos} in the
3707 current buffer is on a link. @var{pos} can also be a mouse event
3708 location, as returned by @code{event-start} (@pxref{Accessing Mouse}).
3712 @subsection Defining and Using Fields
3715 A field is a range of consecutive characters in the buffer that are
3716 identified by having the same value (comparing with @code{eq}) of the
3717 @code{field} property (either a text-property or an overlay property).
3718 This section describes special functions that are available for
3719 operating on fields.
3721 You specify a field with a buffer position, @var{pos}. We think of
3722 each field as containing a range of buffer positions, so the position
3723 you specify stands for the field containing that position.
3725 When the characters before and after @var{pos} are part of the same
3726 field, there is no doubt which field contains @var{pos}: the one those
3727 characters both belong to. When @var{pos} is at a boundary between
3728 fields, which field it belongs to depends on the stickiness of the
3729 @code{field} properties of the two surrounding characters (@pxref{Sticky
3730 Properties}). The field whose property would be inherited by text
3731 inserted at @var{pos} is the field that contains @var{pos}.
3733 There is an anomalous case where newly inserted text at @var{pos}
3734 would not inherit the @code{field} property from either side. This
3735 happens if the previous character's @code{field} property is not
3736 rear-sticky, and the following character's @code{field} property is not
3737 front-sticky. In this case, @var{pos} belongs to neither the preceding
3738 field nor the following field; the field functions treat it as belonging
3739 to an empty field whose beginning and end are both at @var{pos}.
3741 In all of these functions, if @var{pos} is omitted or @code{nil}, the
3742 value of point is used by default. If narrowing is in effect, then
3743 @var{pos} should fall within the accessible portion. @xref{Narrowing}.
3745 @defun field-beginning &optional pos escape-from-edge limit
3746 This function returns the beginning of the field specified by @var{pos}.
3748 If @var{pos} is at the beginning of its field, and
3749 @var{escape-from-edge} is non-@code{nil}, then the return value is
3750 always the beginning of the preceding field that @emph{ends} at @var{pos},
3751 regardless of the stickiness of the @code{field} properties around
3754 If @var{limit} is non-@code{nil}, it is a buffer position; if the
3755 beginning of the field is before @var{limit}, then @var{limit} will be
3759 @defun field-end &optional pos escape-from-edge limit
3760 This function returns the end of the field specified by @var{pos}.
3762 If @var{pos} is at the end of its field, and @var{escape-from-edge} is
3763 non-@code{nil}, then the return value is always the end of the following
3764 field that @emph{begins} at @var{pos}, regardless of the stickiness of
3765 the @code{field} properties around @var{pos}.
3767 If @var{limit} is non-@code{nil}, it is a buffer position; if the end
3768 of the field is after @var{limit}, then @var{limit} will be returned
3772 @defun field-string &optional pos
3773 This function returns the contents of the field specified by @var{pos},
3777 @defun field-string-no-properties &optional pos
3778 This function returns the contents of the field specified by @var{pos},
3779 as a string, discarding text properties.
3782 @defun delete-field &optional pos
3783 This function deletes the text of the field specified by @var{pos}.
3786 @defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
3787 This function ``constrains'' @var{new-pos} to the field that
3788 @var{old-pos} belongs to---in other words, it returns the position
3789 closest to @var{new-pos} that is in the same field as @var{old-pos}.
3791 If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
3792 the value of point instead, and moves point to the resulting position
3793 in addition to returning that position.
3795 If @var{old-pos} is at the boundary of two fields, then the acceptable
3796 final positions depend on the argument @var{escape-from-edge}. If
3797 @var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in
3798 the field whose @code{field} property equals what new characters
3799 inserted at @var{old-pos} would inherit. (This depends on the
3800 stickiness of the @code{field} property for the characters before and
3801 after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
3802 @var{new-pos} can be anywhere in the two adjacent fields.
3803 Additionally, if two fields are separated by another field with the
3804 special value @code{boundary}, then any point within this special
3805 field is also considered to be ``on the boundary''.
3807 Commands like @kbd{C-a} with no argument, that normally move backward
3808 to a specific kind of location and stay there once there, probably
3809 should specify @code{nil} for @var{escape-from-edge}. Other motion
3810 commands that check fields should probably pass @code{t}.
3812 If the optional argument @var{only-in-line} is non-@code{nil}, and
3813 constraining @var{new-pos} in the usual way would move it to a different
3814 line, @var{new-pos} is returned unconstrained. This used in commands
3815 that move by line, such as @code{next-line} and
3816 @code{beginning-of-line}, so that they respect field boundaries only in
3817 the case where they can still move to the right line.
3819 If the optional argument @var{inhibit-capture-property} is
3820 non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that
3821 name, then any field boundaries are ignored.
3823 You can cause @code{constrain-to-field} to ignore all field boundaries
3824 (and so never constrain anything) by binding the variable
3825 @code{inhibit-field-text-motion} to a non-@code{nil} value.
3829 @subsection Why Text Properties are not Intervals
3832 Some editors that support adding attributes to text in the buffer do
3833 so by letting the user specify ``intervals'' within the text, and adding
3834 the properties to the intervals. Those editors permit the user or the
3835 programmer to determine where individual intervals start and end. We
3836 deliberately provided a different sort of interface in Emacs Lisp to
3837 avoid certain paradoxical behavior associated with text modification.
3839 If the actual subdivision into intervals is meaningful, that means you
3840 can distinguish between a buffer that is just one interval with a
3841 certain property, and a buffer containing the same text subdivided into
3842 two intervals, both of which have that property.
3844 Suppose you take the buffer with just one interval and kill part of
3845 the text. The text remaining in the buffer is one interval, and the
3846 copy in the kill ring (and the undo list) becomes a separate interval.
3847 Then if you yank back the killed text, you get two intervals with the
3848 same properties. Thus, editing does not preserve the distinction
3849 between one interval and two.
3851 Suppose we ``fix'' this problem by coalescing the two intervals when
3852 the text is inserted. That works fine if the buffer originally was a
3853 single interval. But suppose instead that we have two adjacent
3854 intervals with the same properties, and we kill the text of one interval
3855 and yank it back. The same interval-coalescence feature that rescues
3856 the other case causes trouble in this one: after yanking, we have just
3857 one interval. One again, editing does not preserve the distinction
3858 between one interval and two.
3860 Insertion of text at the border between intervals also raises
3861 questions that have no satisfactory answer.
3863 However, it is easy to arrange for editing to behave consistently for
3864 questions of the form, ``What are the properties of this character?''
3865 So we have decided these are the only questions that make sense; we have
3866 not implemented asking questions about where intervals start or end.
3868 In practice, you can usually use the text property search functions in
3869 place of explicit interval boundaries. You can think of them as finding
3870 the boundaries of intervals, assuming that intervals are always
3871 coalesced whenever possible. @xref{Property Search}.
3873 Emacs also provides explicit intervals as a presentation feature; see
3877 @section Substituting for a Character Code
3879 The following functions replace characters within a specified region
3880 based on their character codes.
3882 @defun subst-char-in-region start end old-char new-char &optional noundo
3883 @cindex replace characters
3884 This function replaces all occurrences of the character @var{old-char}
3885 with the character @var{new-char} in the region of the current buffer
3886 defined by @var{start} and @var{end}.
3888 @cindex undo avoidance
3889 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
3890 not record the change for undo and does not mark the buffer as modified.
3891 This was useful for controlling the old selective display feature
3892 (@pxref{Selective Display}).
3894 @code{subst-char-in-region} does not move point and returns
3899 ---------- Buffer: foo ----------
3900 This is the contents of the buffer before.
3901 ---------- Buffer: foo ----------
3905 (subst-char-in-region 1 20 ?i ?X)
3908 ---------- Buffer: foo ----------
3909 ThXs Xs the contents of the buffer before.
3910 ---------- Buffer: foo ----------
3915 @deffn Command translate-region start end table
3916 This function applies a translation table to the characters in the
3917 buffer between positions @var{start} and @var{end}.
3919 The translation table @var{table} is a string or a char-table;
3920 @code{(aref @var{table} @var{ochar})} gives the translated character
3921 corresponding to @var{ochar}. If @var{table} is a string, any
3922 characters with codes larger than the length of @var{table} are not
3923 altered by the translation.
3925 The return value of @code{translate-region} is the number of
3926 characters that were actually changed by the translation. This does
3927 not count characters that were mapped into themselves in the
3935 A register is a sort of variable used in Emacs editing that can hold a
3936 variety of different kinds of values. Each register is named by a
3937 single character. All @acronym{ASCII} characters and their meta variants
3938 (but with the exception of @kbd{C-g}) can be used to name registers.
3939 Thus, there are 255 possible registers. A register is designated in
3940 Emacs Lisp by the character that is its name.
3942 @defvar register-alist
3943 This variable is an alist of elements of the form @code{(@var{name} .
3944 @var{contents})}. Normally, there is one element for each Emacs
3945 register that has been used.
3947 The object @var{name} is a character (an integer) identifying the
3951 The @var{contents} of a register can have several possible types:
3955 A number stands for itself. If @code{insert-register} finds a number
3956 in the register, it converts the number to decimal.
3959 A marker represents a buffer position to jump to.
3962 A string is text saved in the register.
3965 A rectangle is represented by a list of strings.
3967 @item @code{(@var{window-configuration} @var{position})}
3968 This represents a window configuration to restore in one frame, and a
3969 position to jump to in the current buffer.
3971 @item @code{(@var{frame-configuration} @var{position})}
3972 This represents a frame configuration to restore, and a position
3973 to jump to in the current buffer.
3975 @item (file @var{filename})
3976 This represents a file to visit; jumping to this value visits file
3979 @item (file-query @var{filename} @var{position})
3980 This represents a file to visit and a position in it; jumping to this
3981 value visits file @var{filename} and goes to buffer position
3982 @var{position}. Restoring this type of position asks the user for
3986 The functions in this section return unpredictable values unless
3989 @defun get-register reg
3990 This function returns the contents of the register
3991 @var{reg}, or @code{nil} if it has no contents.
3994 @defun set-register reg value
3995 This function sets the contents of register @var{reg} to @var{value}.
3996 A register can be set to any value, but the other register functions
3997 expect only certain data types. The return value is @var{value}.
4000 @deffn Command view-register reg
4001 This command displays what is contained in register @var{reg}.
4004 @deffn Command insert-register reg &optional beforep
4005 This command inserts contents of register @var{reg} into the current
4008 Normally, this command puts point before the inserted text, and the
4009 mark after it. However, if the optional second argument @var{beforep}
4010 is non-@code{nil}, it puts the mark before and point after.
4011 You can pass a non-@code{nil} second argument @var{beforep} to this
4012 function interactively by supplying any prefix argument.
4014 If the register contains a rectangle, then the rectangle is inserted
4015 with its upper left corner at point. This means that text is inserted
4016 in the current line and underneath it on successive lines.
4018 If the register contains something other than saved text (a string) or
4019 a rectangle (a list), currently useless things happen. This may be
4020 changed in the future.
4024 @section Transposition of Text
4026 This function can be used to transpose stretches of text:
4028 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
4029 This function exchanges two nonoverlapping portions of the buffer.
4030 Arguments @var{start1} and @var{end1} specify the bounds of one portion
4031 and arguments @var{start2} and @var{end2} specify the bounds of the
4034 Normally, @code{transpose-regions} relocates markers with the transposed
4035 text; a marker previously positioned within one of the two transposed
4036 portions moves along with that portion, thus remaining between the same
4037 two characters in their new position. However, if @var{leave-markers}
4038 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
4039 all markers unrelocated.
4043 @section Base 64 Encoding
4044 @cindex base 64 encoding
4046 Base 64 code is used in email to encode a sequence of 8-bit bytes as
4047 a longer sequence of @acronym{ASCII} graphic characters. It is defined in
4048 Internet RFC@footnote{
4049 An RFC, an acronym for @dfn{Request for Comments}, is a numbered
4050 Internet informational document describing a standard. RFCs are
4051 usually written by technical experts acting on their own initiative,
4052 and are traditionally written in a pragmatic, experience-driven
4054 }2045. This section describes the functions for
4055 converting to and from this code.
4057 @deffn Command base64-encode-region beg end &optional no-line-break
4058 This function converts the region from @var{beg} to @var{end} into base
4059 64 code. It returns the length of the encoded text. An error is
4060 signaled if a character in the region is multibyte, i.e.@: in a
4061 multibyte buffer the region must contain only characters from the
4062 charsets @code{ascii}, @code{eight-bit-control} and
4063 @code{eight-bit-graphic}.
4065 Normally, this function inserts newline characters into the encoded
4066 text, to avoid overlong lines. However, if the optional argument
4067 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
4068 the output is just one long line.
4071 @defun base64-encode-string string &optional no-line-break
4072 This function converts the string @var{string} into base 64 code. It
4073 returns a string containing the encoded text. As for
4074 @code{base64-encode-region}, an error is signaled if a character in the
4075 string is multibyte.
4077 Normally, this function inserts newline characters into the encoded
4078 text, to avoid overlong lines. However, if the optional argument
4079 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
4080 the result string is just one long line.
4083 @deffn Command base64-decode-region beg end
4084 This function converts the region from @var{beg} to @var{end} from base
4085 64 code into the corresponding decoded text. It returns the length of
4088 The decoding functions ignore newline characters in the encoded text.
4091 @defun base64-decode-string string
4092 This function converts the string @var{string} from base 64 code into
4093 the corresponding decoded text. It returns a unibyte string containing the
4096 The decoding functions ignore newline characters in the encoded text.
4100 @section Checksum/Hash
4101 @cindex MD5 checksum
4103 @cindex hash, cryptographic
4104 @cindex cryptographic hash
4106 Emacs has built-in support for computing @dfn{cryptographic hashes}.
4107 A cryptographic hash, or @dfn{checksum}, is a digital ``fingerprint''
4108 of a piece of data (e.g.@: a block of text) which can be used to check
4109 that you have an unaltered copy of that data.
4111 @cindex message digest
4112 Emacs supports several common cryptographic hash algorithms: MD5,
4113 SHA-1, SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512. MD5 is the
4114 oldest of these algorithms, and is commonly used in @dfn{message
4115 digests} to check the integrity of messages transmitted over a
4116 network. MD5 is not ``collision resistant'' (i.e.@: it is possible to
4117 deliberately design different pieces of data which have the same MD5
4118 hash), so you should not used it for anything security-related. A
4119 similar theoretical weakness also exists in SHA-1. Therefore, for
4120 security-related applications you should use the other hash types,
4123 @defun secure-hash algorithm object &optional start end binary
4124 This function returns a hash for @var{object}. The argument
4125 @var{algorithm} is a symbol stating which hash to compute: one of
4126 @code{md5}, @code{sha1}, @code{sha224}, @code{sha256}, @code{sha384}
4127 or @code{sha512}. The argument @var{object} should be a buffer or a
4130 The optional arguments @var{start} and @var{end} are character
4131 positions specifying the portion of @var{object} to compute the
4132 message digest for. If they are @code{nil} or omitted, the hash is
4133 computed for the whole of @var{object}.
4135 If the argument @var{binary} is omitted or @code{nil}, the function
4136 returns the @dfn{text form} of the hash, as an ordinary Lisp string.
4137 If @var{binary} is non-@code{nil}, it returns the hash in @dfn{binary
4138 form}, as a sequence of bytes stored in a unibyte string.
4140 This function does not compute the hash directly from the internal
4141 representation of @var{object}'s text (@pxref{Text Representations}).
4142 Instead, it encodes the text using a coding system (@pxref{Coding
4143 Systems}), and computes the hash from that encoded text. If
4144 @var{object} is a buffer, the coding system used is the one which
4145 would be chosen by default for writing the text into a file. If
4146 @var{object} is a string, the user's preferred coding system is used
4147 (@pxref{Recognize Coding,,, emacs, GNU Emacs Manual}).
4150 @defun md5 object &optional start end coding-system noerror
4151 This function returns an MD5 hash. It is semi-obsolete, since for
4152 most purposes it is equivalent to calling @code{secure-hash} with
4153 @code{md5} as the @var{algorithm} argument. The @var{object},
4154 @var{start} and @var{end} arguments have the same meanings as in
4157 If @var{coding-system} is non-@code{nil}, it specifies a coding system
4158 to use to encode the text; if omitted or @code{nil}, the default
4159 coding system is used, like in @code{secure-hash}.
4161 Normally, @code{md5} signals an error if the text can't be encoded
4162 using the specified or chosen coding system. However, if
4163 @var{noerror} is non-@code{nil}, it silently uses @code{raw-text}
4167 @node Parsing HTML/XML
4168 @section Parsing HTML and XML
4169 @cindex parsing html
4171 When Emacs is compiled with libxml2 support, the following functions
4172 are available to parse HTML or XML text into Lisp object trees.
4174 @defun libxml-parse-html-region start end &optional base-url
4175 This function parses the text between @var{start} and @var{end} as
4176 HTML, and returns a list representing the HTML @dfn{parse tree}. It
4177 attempts to handle ``real world'' HTML by robustly coping with syntax
4180 The optional argument @var{base-url}, if non-@code{nil}, should be a
4181 string specifying the base URL for relative URLs occurring in links.
4183 In the parse tree, each HTML node is represented by a list in which
4184 the first element is a symbol representing the node name, the second
4185 element is an alist of node attributes, and the remaining elements are
4188 The following example demonstrates this. Given this (malformed) HTML
4192 <html><head></head><body width=101><div class=thing>Foo<div>Yes
4196 A call to @code{libxml-parse-html-region} returns this:
4201 (body ((width . "101"))
4202 (div ((class . "thing"))
4210 @defun libxml-parse-xml-region start end &optional base-url
4211 This function is the same as @code{libxml-parse-html-region}, except
4212 that it parses the text as XML rather than HTML (so it is stricter
4216 @node Atomic Changes
4217 @section Atomic Change Groups
4218 @cindex atomic changes
4220 In database terminology, an @dfn{atomic} change is an indivisible
4221 change---it can succeed entirely or it can fail entirely, but it
4222 cannot partly succeed. A Lisp program can make a series of changes to
4223 one or several buffers as an @dfn{atomic change group}, meaning that
4224 either the entire series of changes will be installed in their buffers
4225 or, in case of an error, none of them will be.
4227 To do this for one buffer, the one already current, simply write a
4228 call to @code{atomic-change-group} around the code that makes the
4232 (atomic-change-group
4234 (delete-region x y))
4238 If an error (or other nonlocal exit) occurs inside the body of
4239 @code{atomic-change-group}, it unmakes all the changes in that buffer
4240 that were during the execution of the body. This kind of change group
4241 has no effect on any other buffers---any such changes remain.
4243 If you need something more sophisticated, such as to make changes in
4244 various buffers constitute one atomic group, you must directly call
4245 lower-level functions that @code{atomic-change-group} uses.
4247 @defun prepare-change-group &optional buffer
4248 This function sets up a change group for buffer @var{buffer}, which
4249 defaults to the current buffer. It returns a ``handle'' that
4250 represents the change group. You must use this handle to activate the
4251 change group and subsequently to finish it.
4254 To use the change group, you must @dfn{activate} it. You must do
4255 this before making any changes in the text of @var{buffer}.
4257 @defun activate-change-group handle
4258 This function activates the change group that @var{handle} designates.
4261 After you activate the change group, any changes you make in that
4262 buffer become part of it. Once you have made all the desired changes
4263 in the buffer, you must @dfn{finish} the change group. There are two
4264 ways to do this: you can either accept (and finalize) all the changes,
4267 @defun accept-change-group handle
4268 This function accepts all the changes in the change group specified by
4269 @var{handle}, making them final.
4272 @defun cancel-change-group handle
4273 This function cancels and undoes all the changes in the change group
4274 specified by @var{handle}.
4277 Your code should use @code{unwind-protect} to make sure the group is
4278 always finished. The call to @code{activate-change-group} should be
4279 inside the @code{unwind-protect}, in case the user types @kbd{C-g}
4280 just after it runs. (This is one reason why
4281 @code{prepare-change-group} and @code{activate-change-group} are
4282 separate functions, because normally you would call
4283 @code{prepare-change-group} before the start of that
4284 @code{unwind-protect}.) Once you finish the group, don't use the
4285 handle again---in particular, don't try to finish the same group
4288 To make a multibuffer change group, call @code{prepare-change-group}
4289 once for each buffer you want to cover, then use @code{nconc} to
4290 combine the returned values, like this:
4293 (nconc (prepare-change-group buffer-1)
4294 (prepare-change-group buffer-2))
4297 You can then activate the multibuffer change group with a single call
4298 to @code{activate-change-group}, and finish it with a single call to
4299 @code{accept-change-group} or @code{cancel-change-group}.
4301 Nested use of several change groups for the same buffer works as you
4302 would expect. Non-nested use of change groups for the same buffer
4303 will get Emacs confused, so don't let it happen; the first change
4304 group you start for any given buffer should be the last one finished.
4307 @section Change Hooks
4308 @cindex change hooks
4309 @cindex hooks for text changes
4311 These hook variables let you arrange to take notice of all changes in
4312 all buffers (or in a particular buffer, if you make them buffer-local).
4313 See also @ref{Special Properties}, for how to detect changes to specific
4316 The functions you use in these hooks should save and restore the match
4317 data if they do anything that uses regular expressions; otherwise, they
4318 will interfere in bizarre ways with the editing operations that call
4321 @defvar before-change-functions
4322 This variable holds a list of functions to call before any buffer
4323 modification. Each function gets two arguments, the beginning and end
4324 of the region that is about to change, represented as integers. The
4325 buffer that is about to change is always the current buffer.
4328 @defvar after-change-functions
4329 This variable holds a list of functions to call after any buffer
4330 modification. Each function receives three arguments: the beginning
4331 and end of the region just changed, and the length of the text that
4332 existed before the change. All three arguments are integers. The
4333 buffer has been changed is always the current buffer.
4335 The length of the old text is the difference between the buffer
4336 positions before and after that text as it was before the change. As
4337 for the changed text, its length is simply the difference between the
4338 first two arguments.
4341 Output of messages into the @file{*Messages*} buffer does not
4342 call these functions.
4344 @defmac combine-after-change-calls body@dots{}
4345 The macro executes @var{body} normally, but arranges to call the
4346 after-change functions just once for a series of several changes---if
4349 If a program makes several text changes in the same area of the buffer,
4350 using the macro @code{combine-after-change-calls} around that part of
4351 the program can make it run considerably faster when after-change hooks
4352 are in use. When the after-change hooks are ultimately called, the
4353 arguments specify a portion of the buffer including all of the changes
4354 made within the @code{combine-after-change-calls} body.
4356 @strong{Warning:} You must not alter the values of
4357 @code{after-change-functions} within
4358 the body of a @code{combine-after-change-calls} form.
4360 @strong{Warning:} if the changes you combine occur in widely scattered
4361 parts of the buffer, this will still work, but it is not advisable,
4362 because it may lead to inefficient behavior for some change hook
4366 @defvar first-change-hook
4367 This variable is a normal hook that is run whenever a buffer is changed
4368 that was previously in the unmodified state.
4371 @defvar inhibit-modification-hooks
4372 If this variable is non-@code{nil}, all of the change hooks are
4373 disabled; none of them run. This affects all the hook variables
4374 described above in this section, as well as the hooks attached to
4375 certain special text properties (@pxref{Special Properties}) and overlay
4376 properties (@pxref{Overlay Properties}).
4378 Also, this variable is bound to non-@code{nil} while running those
4379 same hook variables, so that by default modifying the buffer from
4380 a modification hook does not cause other modification hooks to be run.
4381 If you do want modification hooks to be run in a particular piece of
4382 code that is itself run from a modification hook, then rebind locally
4383 @code{inhibit-modification-hooks} to @code{nil}.