2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/text
6 @node Text, Non-ASCII Characters, Markers, Top
10 This chapter describes the functions that deal with the text in a
11 buffer. Most examine, insert, or delete text in the current buffer,
12 often operating at point or on text adjacent to point. Many are
13 interactive. All the functions that change the text provide for undoing
14 the changes (@pxref{Undo}).
16 Many text-related functions operate on a region of text defined by two
17 buffer positions passed in arguments named @var{start} and @var{end}.
18 These arguments should be either markers (@pxref{Markers}) or numeric
19 character positions (@pxref{Positions}). The order of these arguments
20 does not matter; it is all right for @var{start} to be the end of the
21 region and @var{end} the beginning. For example, @code{(delete-region 1
22 10)} and @code{(delete-region 10 1)} are equivalent. An
23 @code{args-out-of-range} error is signaled if either @var{start} or
24 @var{end} is outside the accessible portion of the buffer. In an
25 interactive call, point and the mark are used for these arguments.
27 @cindex buffer contents
28 Throughout this chapter, ``text'' refers to the characters in the
29 buffer, together with their properties (when relevant). Keep in mind
30 that point is always between two characters, and the cursor appears on
31 the character after point.
34 * Near Point:: Examining text in the vicinity of point.
35 * Buffer Contents:: Examining text in a general fashion.
36 * Comparing Text:: Comparing substrings of buffers.
37 * Insertion:: Adding new text to a buffer.
38 * Commands for Insertion:: User-level commands to insert text.
39 * Deletion:: Removing text from a buffer.
40 * User-Level Deletion:: User-level commands to delete text.
41 * The Kill Ring:: Where removed text sometimes is saved for later use.
42 * Undo:: Undoing changes to the text of a buffer.
43 * Maintaining Undo:: How to enable and disable undo information.
44 How to control how much information is kept.
45 * Filling:: Functions for explicit filling.
46 * Margins:: How to specify margins for filling commands.
47 * Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context.
48 * Auto Filling:: How auto-fill mode is implemented to break lines.
49 * Sorting:: Functions for sorting parts of the buffer.
50 * Columns:: Computing horizontal positions, and using them.
51 * Indentation:: Functions to insert or adjust indentation.
52 * Case Changes:: Case conversion of parts of the buffer.
53 * Text Properties:: Assigning Lisp property lists to text characters.
54 * Substitution:: Replacing a given character wherever it appears.
55 * Transposition:: Swapping two portions of a buffer.
56 * Registers:: How registers are implemented. Accessing the text or
57 position stored in a register.
58 * Base 64:: Conversion to or from base 64 encoding.
59 * Change Hooks:: Supplying functions to be run when text is changed.
63 @section Examining Text Near Point
65 Many functions are provided to look at the characters around point.
66 Several simple functions are described here. See also @code{looking-at}
67 in @ref{Regexp Search}.
69 @defun char-after &optional position
70 This function returns the character in the current buffer at (i.e.,
71 immediately after) position @var{position}. If @var{position} is out of
72 range for this purpose, either before the beginning of the buffer, or at
73 or beyond the end, then the value is @code{nil}. The default for
74 @var{position} is point.
76 In the following example, assume that the first character in the
81 (char-to-string (char-after 1))
87 @defun char-before &optional position
88 This function returns the character in the current buffer immediately
89 before position @var{position}. If @var{position} is out of range for
90 this purpose, either before the beginning of the buffer, or at or beyond
91 the end, then the value is @code{nil}. The default for
92 @var{position} is point.
96 This function returns the character following point in the current
97 buffer. This is similar to @code{(char-after (point))}. However, if
98 point is at the end of the buffer, then @code{following-char} returns 0.
100 Remember that point is always between characters, and the terminal
101 cursor normally appears over the character following point. Therefore,
102 the character returned by @code{following-char} is the character the
105 In this example, point is between the @samp{a} and the @samp{c}.
109 ---------- Buffer: foo ----------
110 Gentlemen may cry ``Pea@point{}ce! Peace!,''
111 but there is no peace.
112 ---------- Buffer: foo ----------
116 (char-to-string (preceding-char))
118 (char-to-string (following-char))
124 @defun preceding-char
125 This function returns the character preceding point in the current
126 buffer. See above, under @code{following-char}, for an example. If
127 point is at the beginning of the buffer, @code{preceding-char} returns
132 This function returns @code{t} if point is at the beginning of the
133 buffer. If narrowing is in effect, this means the beginning of the
134 accessible portion of the text. See also @code{point-min} in
139 This function returns @code{t} if point is at the end of the buffer.
140 If narrowing is in effect, this means the end of accessible portion of
141 the text. See also @code{point-max} in @xref{Point}.
145 This function returns @code{t} if point is at the beginning of a line.
146 @xref{Text Lines}. The beginning of the buffer (or of its accessible
147 portion) always counts as the beginning of a line.
151 This function returns @code{t} if point is at the end of a line. The
152 end of the buffer (or of its accessible portion) is always considered
156 @node Buffer Contents
157 @section Examining Buffer Contents
159 This section describes two functions that allow a Lisp program to
160 convert any portion of the text in the buffer into a string.
162 @defun buffer-substring start end
163 This function returns a string containing a copy of the text of the
164 region defined by positions @var{start} and @var{end} in the current
165 buffer. If the arguments are not positions in the accessible portion of
166 the buffer, @code{buffer-substring} signals an @code{args-out-of-range}
169 It is not necessary for @var{start} to be less than @var{end}; the
170 arguments can be given in either order. But most often the smaller
171 argument is written first.
173 If the text being copied has any text properties, these are copied into
174 the string along with the characters they belong to. @xref{Text
175 Properties}. However, overlays (@pxref{Overlays}) in the buffer and
176 their properties are ignored, not copied.
180 ---------- Buffer: foo ----------
181 This is the contents of buffer foo
183 ---------- Buffer: foo ----------
187 (buffer-substring 1 10)
188 @result{} "This is t"
191 (buffer-substring (point-max) 10)
192 @result{} "he contents of buffer foo
198 @defun buffer-substring-no-properties start end
199 This is like @code{buffer-substring}, except that it does not copy text
200 properties, just the characters themselves. @xref{Text Properties}.
204 This function returns the contents of the entire accessible portion of
205 the current buffer as a string. It is equivalent to
208 (buffer-substring (point-min) (point-max))
213 ---------- Buffer: foo ----------
214 This is the contents of buffer foo
216 ---------- Buffer: foo ----------
219 @result{} "This is the contents of buffer foo
224 When this function is used in the minibuffer, the value does not include
228 @defun thing-at-point thing
229 Return the @var{thing} around or next to point, as a string.
231 The argument @var{thing} is a symbol which specifies a kind of syntactic
232 entity. Possibilities include @code{symbol}, @code{list}, @code{sexp},
233 @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
234 @code{whitespace}, @code{line}, @code{page}, and others.
237 ---------- Buffer: foo ----------
238 Gentlemen may cry ``Pea@point{}ce! Peace!,''
239 but there is no peace.
240 ---------- Buffer: foo ----------
242 (thing-at-point 'word)
244 (thing-at-point 'line)
245 @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
246 (thing-at-point 'whitespace)
252 @section Comparing Text
253 @cindex comparing buffer text
255 This function lets you compare portions of the text in a buffer, without
256 copying them into strings first.
258 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
259 This function lets you compare two substrings of the same buffer or two
260 different buffers. The first three arguments specify one substring,
261 giving a buffer and two positions within the buffer. The last three
262 arguments specify the other substring in the same way. You can use
263 @code{nil} for @var{buffer1}, @var{buffer2}, or both to stand for the
266 The value is negative if the first substring is less, positive if the
267 first is greater, and zero if they are equal. The absolute value of
268 the result is one plus the index of the first differing characters
269 within the substrings.
271 This function ignores case when comparing characters
272 if @code{case-fold-search} is non-@code{nil}. It always ignores
275 Suppose the current buffer contains the text @samp{foobarbar
276 haha!rara!}; then in this example the two substrings are @samp{rbar }
277 and @samp{rara!}. The value is 2 because the first substring is greater
278 at the second character.
281 (compare-buffer-substrings nil 6 11 nil 16 21)
287 @section Inserting Text
288 @cindex insertion of text
289 @cindex text insertion
291 @cindex insertion before point
292 @cindex before point, insertion
293 @dfn{Insertion} means adding new text to a buffer. The inserted text
294 goes at point---between the character before point and the character
295 after point. Some insertion functions leave point before the inserted
296 text, while other functions leave it after. We call the former
297 insertion @dfn{after point} and the latter insertion @dfn{before point}.
299 Insertion relocates markers that point at positions after the
300 insertion point, so that they stay with the surrounding text
301 (@pxref{Markers}). When a marker points at the place of insertion,
302 insertion may or may not relocate the marker, depending on the marker's
303 insertion type (@pxref{Marker Insertion Types}). Certain special
304 functions such as @code{insert-before-markers} relocate all such markers
305 to point after the inserted text, regardless of the markers' insertion
308 Insertion functions signal an error if the current buffer is
311 These functions copy text characters from strings and buffers along
312 with their properties. The inserted characters have exactly the same
313 properties as the characters they were copied from. By contrast,
314 characters specified as separate arguments, not part of a string or
315 buffer, inherit their text properties from the neighboring text.
317 The insertion functions convert text from unibyte to multibyte in
318 order to insert in a multibyte buffer, and vice versa---if the text
319 comes from a string or from a buffer. However, they do not convert
320 unibyte character codes 128 through 255 to multibyte characters, not
321 even if the current buffer is a multibyte buffer. @xref{Converting
324 @defun insert &rest args
325 This function inserts the strings and/or characters @var{args} into the
326 current buffer, at point, moving point forward. In other words, it
327 inserts the text before point. An error is signaled unless all
328 @var{args} are either strings or characters. The value is @code{nil}.
331 @defun insert-before-markers &rest args
332 This function inserts the strings and/or characters @var{args} into the
333 current buffer, at point, moving point forward. An error is signaled
334 unless all @var{args} are either strings or characters. The value is
337 This function is unlike the other insertion functions in that it
338 relocates markers initially pointing at the insertion point, to point
339 after the inserted text. If an overlay begins the insertion point, the
340 inserted text falls outside the overlay; if a nonempty overlay ends at
341 the insertion point, the inserted text falls inside that overlay.
344 @defun insert-char character &optional count inherit
345 This function inserts @var{count} instances of @var{character} into the
346 current buffer before point. The argument @var{count} should be a
347 number (@code{nil} means 1), and @var{character} must be a character.
348 The value is @code{nil}.
350 This function does not convert unibyte character codes 128 through 255
351 to multibyte characters, not even if the current buffer is a multibyte
352 buffer. @xref{Converting Representations}.
354 If @var{inherit} is non-@code{nil}, then the inserted characters inherit
355 sticky text properties from the two characters before and after the
356 insertion point. @xref{Sticky Properties}.
359 @defun insert-buffer-substring from-buffer-or-name &optional start end
360 This function inserts a portion of buffer @var{from-buffer-or-name}
361 (which must already exist) into the current buffer before point. The
362 text inserted is the region from @var{start} and @var{end}. (These
363 arguments default to the beginning and end of the accessible portion of
364 that buffer.) This function returns @code{nil}.
366 In this example, the form is executed with buffer @samp{bar} as the
367 current buffer. We assume that buffer @samp{bar} is initially empty.
371 ---------- Buffer: foo ----------
372 We hold these truths to be self-evident, that all
373 ---------- Buffer: foo ----------
377 (insert-buffer-substring "foo" 1 20)
380 ---------- Buffer: bar ----------
381 We hold these truth@point{}
382 ---------- Buffer: bar ----------
387 @xref{Sticky Properties}, for other insertion functions that inherit
388 text properties from the nearby text in addition to inserting it.
389 Whitespace inserted by indentation functions also inherits text
392 @node Commands for Insertion
393 @section User-Level Insertion Commands
395 This section describes higher-level commands for inserting text,
396 commands intended primarily for the user but useful also in Lisp
399 @deffn Command insert-buffer from-buffer-or-name
400 This command inserts the entire contents of @var{from-buffer-or-name}
401 (which must exist) into the current buffer after point. It leaves
402 the mark after the inserted text. The value is @code{nil}.
405 @deffn Command self-insert-command count
406 @cindex character insertion
407 @cindex self-insertion
408 This command inserts the last character typed; it does so @var{count}
409 times, before point, and returns @code{nil}. Most printing characters
410 are bound to this command. In routine use, @code{self-insert-command}
411 is the most frequently called function in Emacs, but programs rarely use
412 it except to install it on a keymap.
414 In an interactive call, @var{count} is the numeric prefix argument.
416 This command calls @code{auto-fill-function} whenever that is
417 non-@code{nil} and the character inserted is a space or a newline
418 (@pxref{Auto Filling}).
420 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
421 This command performs abbrev expansion if Abbrev mode is enabled and
422 the inserted character does not have word-constituent
423 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
425 This is also responsible for calling @code{blink-paren-function} when
426 the inserted character has close parenthesis syntax (@pxref{Blinking}).
428 Do not try substituting your own definition of
429 @code{self-insert-command} for the standard one. The editor command
430 loop handles this function specially.
433 @deffn Command newline &optional number-of-newlines
434 This command inserts newlines into the current buffer before point.
435 If @var{number-of-newlines} is supplied, that many newline characters
438 @cindex newline and Auto Fill mode
439 This function calls @code{auto-fill-function} if the current column
440 number is greater than the value of @code{fill-column} and
441 @var{number-of-newlines} is @code{nil}. Typically what
442 @code{auto-fill-function} does is insert a newline; thus, the overall
443 result in this case is to insert two newlines at different places: one
444 at point, and another earlier in the line. @code{newline} does not
445 auto-fill if @var{number-of-newlines} is non-@code{nil}.
447 This command indents to the left margin if that is not zero.
450 The value returned is @code{nil}. In an interactive call, @var{count}
451 is the numeric prefix argument.
454 @deffn Command split-line
455 This command splits the current line, moving the portion of the line
456 after point down vertically so that it is on the next line directly
457 below where it was before. Whitespace is inserted as needed at the
458 beginning of the lower line, using the @code{indent-to} function.
459 @code{split-line} returns the position of point.
461 Programs hardly ever use this function.
464 @defvar overwrite-mode
465 This variable controls whether overwrite mode is in effect. The value
466 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
467 or @code{nil}. @code{overwrite-mode-textual} specifies textual
468 overwrite mode (treats newlines and tabs specially), and
469 @code{overwrite-mode-binary} specifies binary overwrite mode (treats
470 newlines and tabs like any other characters).
474 @section Deleting Text
476 @cindex deletion vs killing
477 Deletion means removing part of the text in a buffer, without saving
478 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
479 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
480 Some deletion functions do save text in the kill ring in some special
483 All of the deletion functions operate on the current buffer, and all
484 return a value of @code{nil}.
486 @deffn Command erase-buffer
487 This function deletes the entire text of the current buffer, leaving it
488 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
489 error. Otherwise, it deletes the text without asking for any
490 confirmation. It returns @code{nil}.
492 In the minibuffer, @code{erase-buffer} does not delete the prompt.
494 Normally, deleting a large amount of text from a buffer inhibits further
495 auto-saving of that buffer ``because it has shrunk''. However,
496 @code{erase-buffer} does not do this, the idea being that the future
497 text is not really related to the former text, and its size should not
498 be compared with that of the former text.
501 @deffn Command delete-region start end
502 This command deletes the text in the current buffer in the region
503 defined by @var{start} and @var{end}. The value is @code{nil}. If
504 point was inside the deleted region, its value afterward is @var{start}.
505 Otherwise, point relocates with the surrounding text, as markers do.
508 @deffn Command delete-char count &optional killp
509 This command deletes @var{count} characters directly after point, or
510 before point if @var{count} is negative. If @var{killp} is
511 non-@code{nil}, then it saves the deleted characters in the kill ring.
513 In an interactive call, @var{count} is the numeric prefix argument, and
514 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
515 argument is supplied, the text is saved in the kill ring. If no prefix
516 argument is supplied, then one character is deleted, but not saved in
519 The value returned is always @code{nil}.
522 @deffn Command delete-backward-char count &optional killp
523 @cindex delete previous char
524 This command deletes @var{count} characters directly before point, or
525 after point if @var{count} is negative. If @var{killp} is
526 non-@code{nil}, then it saves the deleted characters in the kill ring.
528 In an interactive call, @var{count} is the numeric prefix argument, and
529 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
530 argument is supplied, the text is saved in the kill ring. If no prefix
531 argument is supplied, then one character is deleted, but not saved in
534 The value returned is always @code{nil}.
537 @deffn Command backward-delete-char-untabify count &optional killp
539 This command deletes @var{count} characters backward, changing tabs
540 into spaces. When the next character to be deleted is a tab, it is
541 first replaced with the proper number of spaces to preserve alignment
542 and then one of those spaces is deleted instead of the tab. If
543 @var{killp} is non-@code{nil}, then the command saves the deleted
544 characters in the kill ring.
546 Conversion of tabs to spaces happens only if @var{count} is positive.
547 If it is negative, exactly @minus{}@var{count} characters after point
550 In an interactive call, @var{count} is the numeric prefix argument, and
551 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
552 argument is supplied, the text is saved in the kill ring. If no prefix
553 argument is supplied, then one character is deleted, but not saved in
556 The value returned is always @code{nil}.
559 @defopt backward-delete-char-untabify-method
560 @tindex backward-delete-char-untabify-method
561 This option specifies how @code{backward-delete-char-untabify} should
562 deal with whitespace. Possible values include @code{untabify}, the
563 default, meaning convert a tab to many spaces and delete one;
564 @code{hungry}, meaning delete all the whitespace characters before point
565 with one command, and @code{nil}, meaning do nothing special for
566 whitespace characters.
569 @node User-Level Deletion
570 @section User-Level Deletion Commands
572 This section describes higher-level commands for deleting text,
573 commands intended primarily for the user but useful also in Lisp
576 @deffn Command delete-horizontal-space
577 @cindex deleting whitespace
578 This function deletes all spaces and tabs around point. It returns
581 In the following examples, we call @code{delete-horizontal-space} four
582 times, once on each line, with point between the second and third
583 characters on the line each time.
587 ---------- Buffer: foo ----------
592 ---------- Buffer: foo ----------
596 (delete-horizontal-space) ; @r{Four times.}
599 ---------- Buffer: foo ----------
604 ---------- Buffer: foo ----------
609 @deffn Command delete-indentation &optional join-following-p
610 This function joins the line point is on to the previous line, deleting
611 any whitespace at the join and in some cases replacing it with one
612 space. If @var{join-following-p} is non-@code{nil},
613 @code{delete-indentation} joins this line to the following line
614 instead. The function returns @code{nil}.
616 If there is a fill prefix, and the second of the lines being joined
617 starts with the prefix, then @code{delete-indentation} deletes the
618 fill prefix before joining the lines. @xref{Margins}.
620 In the example below, point is located on the line starting
621 @samp{events}, and it makes no difference if there are trailing spaces
622 in the preceding line.
626 ---------- Buffer: foo ----------
627 When in the course of human
628 @point{} events, it becomes necessary
629 ---------- Buffer: foo ----------
636 ---------- Buffer: foo ----------
637 When in the course of human@point{} events, it becomes necessary
638 ---------- Buffer: foo ----------
642 After the lines are joined, the function @code{fixup-whitespace} is
643 responsible for deciding whether to leave a space at the junction.
646 @defun fixup-whitespace
647 This function replaces all the whitespace surrounding point with either
648 one space or no space, according to the context. It returns @code{nil}.
650 At the beginning or end of a line, the appropriate amount of space is
651 none. Before a character with close parenthesis syntax, or after a
652 character with open parenthesis or expression-prefix syntax, no space is
653 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
656 In the example below, @code{fixup-whitespace} is called the first time
657 with point before the word @samp{spaces} in the first line. For the
658 second invocation, point is directly after the @samp{(}.
662 ---------- Buffer: foo ----------
663 This has too many @point{}spaces
664 This has too many spaces at the start of (@point{} this list)
665 ---------- Buffer: foo ----------
676 ---------- Buffer: foo ----------
677 This has too many spaces
678 This has too many spaces at the start of (this list)
679 ---------- Buffer: foo ----------
684 @deffn Command just-one-space
685 @comment !!SourceFile simple.el
686 This command replaces any spaces and tabs around point with a single
687 space. It returns @code{nil}.
690 @deffn Command delete-blank-lines
691 This function deletes blank lines surrounding point. If point is on a
692 blank line with one or more blank lines before or after it, then all but
693 one of them are deleted. If point is on an isolated blank line, then it
694 is deleted. If point is on a nonblank line, the command deletes all
695 blank lines following it.
697 A blank line is defined as a line containing only tabs and spaces.
699 @code{delete-blank-lines} returns @code{nil}.
703 @section The Kill Ring
706 @dfn{Kill functions} delete text like the deletion functions, but save
707 it so that the user can reinsert it by @dfn{yanking}. Most of these
708 functions have @samp{kill-} in their name. By contrast, the functions
709 whose names start with @samp{delete-} normally do not save text for
710 yanking (though they can still be undone); these are ``deletion''
713 Most of the kill commands are primarily for interactive use, and are
714 not described here. What we do describe are the functions provided for
715 use in writing such commands. You can use these functions to write
716 commands for killing text. When you need to delete text for internal
717 purposes within a Lisp function, you should normally use deletion
718 functions, so as not to disturb the kill ring contents.
721 Killed text is saved for later yanking in the @dfn{kill ring}. This
722 is a list that holds a number of recent kills, not just the last text
723 kill. We call this a ``ring'' because yanking treats it as having
724 elements in a cyclic order. The list is kept in the variable
725 @code{kill-ring}, and can be operated on with the usual functions for
726 lists; there are also specialized functions, described in this section,
727 that treat it as a ring.
729 Some people think this use of the word ``kill'' is unfortunate, since
730 it refers to operations that specifically @emph{do not} destroy the
731 entities ``killed''. This is in sharp contrast to ordinary life, in
732 which death is permanent and ``killed'' entities do not come back to
733 life. Therefore, other metaphors have been proposed. For example, the
734 term ``cut ring'' makes sense to people who, in pre-computer days, used
735 scissors and paste to cut up and rearrange manuscripts. However, it
736 would be difficult to change the terminology now.
739 * Kill Ring Concepts:: What text looks like in the kill ring.
740 * Kill Functions:: Functions that kill text.
741 * Yank Commands:: Commands that access the kill ring.
742 * Low-Level Kill Ring:: Functions and variables for kill ring access.
743 * Internals of Kill Ring:: Variables that hold kill-ring data.
746 @node Kill Ring Concepts
747 @comment node-name, next, previous, up
748 @subsection Kill Ring Concepts
750 The kill ring records killed text as strings in a list, most recent
751 first. A short kill ring, for example, might look like this:
754 ("some text" "a different piece of text" "even older text")
758 When the list reaches @code{kill-ring-max} entries in length, adding a
759 new entry automatically deletes the last entry.
761 When kill commands are interwoven with other commands, each kill
762 command makes a new entry in the kill ring. Multiple kill commands in
763 succession build up a single kill-ring entry, which would be yanked as a
764 unit; the second and subsequent consecutive kill commands add text to
765 the entry made by the first one.
767 For yanking, one entry in the kill ring is designated the ``front'' of
768 the ring. Some yank commands ``rotate'' the ring by designating a
769 different element as the ``front.'' But this virtual rotation doesn't
770 change the list itself---the most recent entry always comes first in the
774 @comment node-name, next, previous, up
775 @subsection Functions for Killing
777 @code{kill-region} is the usual subroutine for killing text. Any
778 command that calls this function is a ``kill command'' (and should
779 probably have @samp{kill} in its name). @code{kill-region} puts the
780 newly killed text in a new element at the beginning of the kill ring or
781 adds it to the most recent element. It determines automatically (using
782 @code{last-command}) whether the previous command was a kill command,
783 and if so appends the killed text to the most recent entry.
785 @deffn Command kill-region start end
786 This function kills the text in the region defined by @var{start} and
787 @var{end}. The text is deleted but saved in the kill ring, along with
788 its text properties. The value is always @code{nil}.
790 In an interactive call, @var{start} and @var{end} are point and
794 If the buffer is read-only, @code{kill-region} modifies the kill ring
795 just the same, then signals an error without modifying the buffer. This
796 is convenient because it lets the user use all the kill commands to copy
797 text into the kill ring from a read-only buffer.
800 @defopt kill-read-only-ok
801 If this option is non-@code{nil}, @code{kill-region} does not get an
802 error if the buffer is read-only. Instead, it simply returns, updating
803 the kill ring but not changing the buffer.
806 @deffn Command copy-region-as-kill start end
807 This command saves the region defined by @var{start} and @var{end} on
808 the kill ring (including text properties), but does not delete the text
809 from the buffer. It returns @code{nil}. It also indicates the extent
810 of the text copied by moving the cursor momentarily, or by displaying a
811 message in the echo area.
813 The command does not set @code{this-command} to @code{kill-region}, so a
814 subsequent kill command does not append to the same kill ring entry.
816 Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
817 support Emacs 18. For newer Emacs versions, it is better to use
818 @code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill
823 @comment node-name, next, previous, up
824 @subsection Functions for Yanking
826 @dfn{Yanking} means reinserting an entry of previously killed text
827 from the kill ring. The text properties are copied too.
829 @deffn Command yank &optional arg
830 @cindex inserting killed text
831 This command inserts before point the text in the first entry in the
832 kill ring. It positions the mark at the beginning of that text, and
835 If @var{arg} is a list (which occurs interactively when the user
836 types @kbd{C-u} with no digits), then @code{yank} inserts the text as
837 described above, but puts point before the yanked text and puts the mark
840 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most
841 recently killed text---the @var{arg}th element of the kill ring list.
843 @code{yank} does not alter the contents of the kill ring or rotate it.
844 It returns @code{nil}.
847 @deffn Command yank-pop arg
848 This command replaces the just-yanked entry from the kill ring with a
849 different entry from the kill ring.
851 This is allowed only immediately after a @code{yank} or another
852 @code{yank-pop}. At such a time, the region contains text that was just
853 inserted by yanking. @code{yank-pop} deletes that text and inserts in
854 its place a different piece of killed text. It does not add the deleted
855 text to the kill ring, since it is already in the kill ring somewhere.
857 If @var{arg} is @code{nil}, then the replacement text is the previous
858 element of the kill ring. If @var{arg} is numeric, the replacement is
859 the @var{arg}th previous kill. If @var{arg} is negative, a more recent
860 kill is the replacement.
862 The sequence of kills in the kill ring wraps around, so that after the
863 oldest one comes the newest one, and before the newest one goes the
866 The return value is always @code{nil}.
869 @node Low-Level Kill Ring
870 @subsection Low-Level Kill Ring
872 These functions and variables provide access to the kill ring at a
873 lower level, but still convenient for use in Lisp programs, because they
874 take care of interaction with window system selections
875 (@pxref{Window System Selections}).
877 @defun current-kill n &optional do-not-move
878 The function @code{current-kill} rotates the yanking pointer, which
879 designates the ``front'' of the kill ring, by @var{n} places (from newer
880 kills to older ones), and returns the text at that place in the ring.
882 If the optional second argument @var{do-not-move} is non-@code{nil},
883 then @code{current-kill} doesn't alter the yanking pointer; it just
884 returns the @var{n}th kill, counting from the current yanking pointer.
886 If @var{n} is zero, indicating a request for the latest kill,
887 @code{current-kill} calls the value of
888 @code{interprogram-paste-function} (documented below) before consulting
892 @defun kill-new string
893 This function puts the text @var{string} into the kill ring as a new
894 entry at the front of the ring. It discards the oldest entry if
895 appropriate. It also invokes the value of
896 @code{interprogram-cut-function} (see below).
899 @defun kill-append string before-p
900 This function appends the text @var{string} to the first entry in the
901 kill ring. Normally @var{string} goes at the end of the entry, but if
902 @var{before-p} is non-@code{nil}, it goes at the beginning. This
903 function also invokes the value of @code{interprogram-cut-function} (see
907 @defvar interprogram-paste-function
908 This variable provides a way of transferring killed text from other
909 programs, when you are using a window system. Its value should be
910 @code{nil} or a function of no arguments.
912 If the value is a function, @code{current-kill} calls it to get the
913 ``most recent kill''. If the function returns a non-@code{nil} value,
914 then that value is used as the ``most recent kill''. If it returns
915 @code{nil}, then the first element of @code{kill-ring} is used.
917 The normal use of this hook is to get the window system's primary
918 selection as the most recent kill, even if the selection belongs to
919 another application. @xref{Window System Selections}.
922 @defvar interprogram-cut-function
923 This variable provides a way of communicating killed text to other
924 programs, when you are using a window system. Its value should be
925 @code{nil} or a function of one argument.
927 If the value is a function, @code{kill-new} and @code{kill-append} call
928 it with the new first element of the kill ring as an argument.
930 The normal use of this hook is to set the window system's primary
931 selection from the newly killed text. @xref{Window System Selections}.
934 @node Internals of Kill Ring
935 @comment node-name, next, previous, up
936 @subsection Internals of the Kill Ring
938 The variable @code{kill-ring} holds the kill ring contents, in the
939 form of a list of strings. The most recent kill is always at the front
942 The @code{kill-ring-yank-pointer} variable points to a link in the
943 kill ring list, whose @sc{car} is the text to yank next. We say it
944 identifies the ``front'' of the ring. Moving
945 @code{kill-ring-yank-pointer} to a different link is called
946 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
947 the functions that move the yank pointer wrap around from the end of the
948 list to the beginning, or vice-versa. Rotation of the kill ring is
949 virtual; it does not change the value of @code{kill-ring}.
951 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
952 variables whose values are normally lists. The word ``pointer'' in the
953 name of the @code{kill-ring-yank-pointer} indicates that the variable's
954 purpose is to identify one element of the list for use by the next yank
957 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
958 of the links in the kill ring list. The element it identifies is the
959 @sc{car} of that link. Kill commands, which change the kill ring, also
960 set this variable to the value of @code{kill-ring}. The effect is to
961 rotate the ring so that the newly killed text is at the front.
963 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
964 pointing to the second entry in the kill ring @code{("some text" "a
965 different piece of text" "yet older text")}.
969 kill-ring ---- kill-ring-yank-pointer
972 | --- --- --- --- --- ---
973 --> | | |------> | | |--> | | |--> nil
974 --- --- --- --- --- ---
977 | | -->"yet older text"
979 | --> "a different piece of text"
986 This state of affairs might occur after @kbd{C-y} (@code{yank})
987 immediately followed by @kbd{M-y} (@code{yank-pop}).
990 This variable holds the list of killed text sequences, most recently
994 @defvar kill-ring-yank-pointer
995 This variable's value indicates which element of the kill ring is at the
996 ``front'' of the ring for yanking. More precisely, the value is a tail
997 of the value of @code{kill-ring}, and its @sc{car} is the kill string
998 that @kbd{C-y} should yank.
1001 @defopt kill-ring-max
1002 The value of this variable is the maximum length to which the kill
1003 ring can grow, before elements are thrown away at the end. The default
1004 value for @code{kill-ring-max} is 30.
1008 @comment node-name, next, previous, up
1012 Most buffers have an @dfn{undo list}, which records all changes made
1013 to the buffer's text so that they can be undone. (The buffers that
1014 don't have one are usually special-purpose buffers for which Emacs
1015 assumes that undoing is not useful.) All the primitives that modify the
1016 text in the buffer automatically add elements to the front of the undo
1017 list, which is in the variable @code{buffer-undo-list}.
1019 @defvar buffer-undo-list
1020 This variable's value is the undo list of the current buffer.
1021 A value of @code{t} disables the recording of undo information.
1024 Here are the kinds of elements an undo list can have:
1027 @item @var{position}
1028 This kind of element records a previous value of point; undoing this
1029 element moves point to @var{position}. Ordinary cursor motion does not
1030 make any sort of undo record, but deletion operations use these entries
1031 to record where point was before the command.
1033 @item (@var{beg} . @var{end})
1034 This kind of element indicates how to delete text that was inserted.
1035 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
1038 @item (@var{text} . @var{position})
1039 This kind of element indicates how to reinsert text that was deleted.
1040 The deleted text itself is the string @var{text}. The place to
1041 reinsert it is @code{(abs @var{position})}.
1043 @item (t @var{high} . @var{low})
1044 This kind of element indicates that an unmodified buffer became
1045 modified. The elements @var{high} and @var{low} are two integers, each
1046 recording 16 bits of the visited file's modification time as of when it
1047 was previously visited or saved. @code{primitive-undo} uses those
1048 values to determine whether to mark the buffer as unmodified once again;
1049 it does so only if the file's modification time matches those numbers.
1051 @item (nil @var{property} @var{value} @var{beg} . @var{end})
1052 This kind of element records a change in a text property.
1053 Here's how you might undo the change:
1056 (put-text-property @var{beg} @var{end} @var{property} @var{value})
1059 @item (@var{marker} . @var{adjustment})
1060 This kind of element records the fact that the marker @var{marker} was
1061 relocated due to deletion of surrounding text, and that it moved
1062 @var{adjustment} character positions. Undoing this element moves
1063 @var{marker} @minus{} @var{adjustment} characters.
1066 This element is a boundary. The elements between two boundaries are
1067 called a @dfn{change group}; normally, each change group corresponds to
1068 one keyboard command, and undo commands normally undo an entire group as
1072 @defun undo-boundary
1073 This function places a boundary element in the undo list. The undo
1074 command stops at such a boundary, and successive undo commands undo
1075 to earlier and earlier boundaries. This function returns @code{nil}.
1077 The editor command loop automatically creates an undo boundary before
1078 each key sequence is executed. Thus, each undo normally undoes the
1079 effects of one command. Self-inserting input characters are an
1080 exception. The command loop makes a boundary for the first such
1081 character; the next 19 consecutive self-inserting input characters do
1082 not make boundaries, and then the 20th does, and so on as long as
1083 self-inserting characters continue.
1085 All buffer modifications add a boundary whenever the previous undoable
1086 change was made in some other buffer. This is to ensure that
1087 each command makes a boundary in each buffer where it makes changes.
1089 Calling this function explicitly is useful for splitting the effects of
1090 a command into more than one unit. For example, @code{query-replace}
1091 calls @code{undo-boundary} after each replacement, so that the user can
1092 undo individual replacements one by one.
1095 @defun primitive-undo count list
1096 This is the basic function for undoing elements of an undo list.
1097 It undoes the first @var{count} elements of @var{list}, returning
1098 the rest of @var{list}. You could write this function in Lisp,
1099 but it is convenient to have it in C.
1101 @code{primitive-undo} adds elements to the buffer's undo list when it
1102 changes the buffer. Undo commands avoid confusion by saving the undo
1103 list value at the beginning of a sequence of undo operations. Then the
1104 undo operations use and update the saved value. The new elements added
1105 by undoing are not part of this saved value, so they don't interfere with
1109 @node Maintaining Undo
1110 @section Maintaining Undo Lists
1112 This section describes how to enable and disable undo information for
1113 a given buffer. It also explains how the undo list is truncated
1114 automatically so it doesn't get too big.
1116 Recording of undo information in a newly created buffer is normally
1117 enabled to start with; but if the buffer name starts with a space, the
1118 undo recording is initially disabled. You can explicitly enable or
1119 disable undo recording with the following two functions, or by setting
1120 @code{buffer-undo-list} yourself.
1122 @deffn Command buffer-enable-undo &optional buffer-or-name
1123 This command enables recording undo information for buffer
1124 @var{buffer-or-name}, so that subsequent changes can be undone. If no
1125 argument is supplied, then the current buffer is used. This function
1126 does nothing if undo recording is already enabled in the buffer. It
1129 In an interactive call, @var{buffer-or-name} is the current buffer.
1130 You cannot specify any other buffer.
1133 @deffn Command buffer-disable-undo &optional buffer
1134 @deffnx Command buffer-flush-undo &optional buffer
1135 @cindex disable undo
1136 This function discards the undo list of @var{buffer}, and disables
1137 further recording of undo information. As a result, it is no longer
1138 possible to undo either previous changes or any subsequent changes. If
1139 the undo list of @var{buffer} is already disabled, this function
1142 This function returns @code{nil}.
1144 The name @code{buffer-flush-undo} is not considered obsolete, but the
1145 preferred name is @code{buffer-disable-undo}.
1148 As editing continues, undo lists get longer and longer. To prevent
1149 them from using up all available memory space, garbage collection trims
1150 them back to size limits you can set. (For this purpose, the ``size''
1151 of an undo list measures the cons cells that make up the list, plus the
1152 strings of deleted text.) Two variables control the range of acceptable
1153 sizes: @code{undo-limit} and @code{undo-strong-limit}.
1156 This is the soft limit for the acceptable size of an undo list. The
1157 change group at which this size is exceeded is the last one kept.
1160 @defvar undo-strong-limit
1161 This is the upper limit for the acceptable size of an undo list. The
1162 change group at which this size is exceeded is discarded itself (along
1163 with all older change groups). There is one exception: the very latest
1164 change group is never discarded no matter how big it is.
1168 @comment node-name, next, previous, up
1170 @cindex filling, explicit
1172 @dfn{Filling} means adjusting the lengths of lines (by moving the line
1173 breaks) so that they are nearly (but no greater than) a specified
1174 maximum width. Additionally, lines can be @dfn{justified}, which means
1175 inserting spaces to make the left and/or right margins line up
1176 precisely. The width is controlled by the variable @code{fill-column}.
1177 For ease of reading, lines should be no longer than 70 or so columns.
1179 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1180 automatically as you insert it, but changes to existing text may leave
1181 it improperly filled. Then you must fill the text explicitly.
1183 Most of the commands in this section return values that are not
1184 meaningful. All the functions that do filling take note of the current
1185 left margin, current right margin, and current justification style
1186 (@pxref{Margins}). If the current justification style is
1187 @code{none}, the filling functions don't actually do anything.
1189 Several of the filling functions have an argument @var{justify}.
1190 If it is non-@code{nil}, that requests some kind of justification. It
1191 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
1192 request a specific style of justification. If it is @code{t}, that
1193 means to use the current justification style for this part of the text
1194 (see @code{current-justification}, below). Any other value is treated
1197 When you call the filling functions interactively, using a prefix
1198 argument implies the value @code{full} for @var{justify}.
1200 @deffn Command fill-paragraph justify
1201 @cindex filling a paragraph
1202 This command fills the paragraph at or after point. If
1203 @var{justify} is non-@code{nil}, each line is justified as well.
1204 It uses the ordinary paragraph motion commands to find paragraph
1205 boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}.
1208 @deffn Command fill-region start end &optional justify nosqueeze to-eop
1209 This command fills each of the paragraphs in the region from @var{start}
1210 to @var{end}. It justifies as well if @var{justify} is
1213 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1214 other than line breaks untouched. If @var{to-eop} is non-@code{nil},
1215 that means to keep filling to the end of the paragraph---or the next hard
1216 newline, if @code{use-hard-newlines} is enabled (see below).
1218 The variable @code{paragraph-separate} controls how to distinguish
1219 paragraphs. @xref{Standard Regexps}.
1222 @deffn Command fill-individual-paragraphs start end &optional justify mail-flag
1223 This command fills each paragraph in the region according to its
1224 individual fill prefix. Thus, if the lines of a paragraph were indented
1225 with spaces, the filled paragraph will remain indented in the same
1228 The first two arguments, @var{start} and @var{end}, are the beginning
1229 and end of the region to be filled. The third and fourth arguments,
1230 @var{justify} and @var{mail-flag}, are optional. If
1231 @var{justify} is non-@code{nil}, the paragraphs are justified as
1232 well as filled. If @var{mail-flag} is non-@code{nil}, it means the
1233 function is operating on a mail message and therefore should not fill
1236 Ordinarily, @code{fill-individual-paragraphs} regards each change in
1237 indentation as starting a new paragraph. If
1238 @code{fill-individual-varying-indent} is non-@code{nil}, then only
1239 separator lines separate paragraphs. That mode can handle indented
1240 paragraphs with additional indentation on the first line.
1243 @defopt fill-individual-varying-indent
1244 This variable alters the action of @code{fill-individual-paragraphs} as
1248 @deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
1249 This command considers a region of text as a single paragraph and fills
1250 it. If the region was made up of many paragraphs, the blank lines
1251 between paragraphs are removed. This function justifies as well as
1252 filling when @var{justify} is non-@code{nil}.
1254 In an interactive call, any prefix argument requests justification.
1256 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1257 other than line breaks untouched. If @var{squeeze-after} is
1258 non-@code{nil}, it specifies a position in the region, and means don't
1259 canonicalize spaces before that position.
1261 In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
1262 choose a fill prefix by default. @xref{Adaptive Fill}.
1265 @deffn Command justify-current-line how eop nosqueeze
1266 This command inserts spaces between the words of the current line so
1267 that the line ends exactly at @code{fill-column}. It returns
1270 The argument @var{how}, if non-@code{nil} specifies explicitly the style
1271 of justification. It can be @code{left}, @code{right}, @code{full},
1272 @code{center}, or @code{none}. If it is @code{t}, that means to do
1273 follow specified justification style (see @code{current-justification},
1274 below). @code{nil} means to do full justification.
1276 If @var{eop} is non-@code{nil}, that means do left-justification if
1277 @code{current-justification} specifies full justification. This is used
1278 for the last line of a paragraph; even if the paragraph as a whole is
1279 fully justified, the last line should not be.
1281 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1285 @defopt default-justification
1286 This variable's value specifies the style of justification to use for
1287 text that doesn't specify a style with a text property. The possible
1288 values are @code{left}, @code{right}, @code{full}, @code{center}, or
1289 @code{none}. The default value is @code{left}.
1292 @defun current-justification
1293 This function returns the proper justification style to use for filling
1294 the text around point.
1297 @defopt sentence-end-double-space
1298 If this variable is non-@code{nil}, a period followed by just one space
1299 does not count as the end of a sentence, and the filling functions
1300 avoid breaking the line at such a place.
1303 @defvar fill-paragraph-function
1304 This variable provides a way for major modes to override the filling of
1305 paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
1306 this function to do the work. If the function returns a non-@code{nil}
1307 value, @code{fill-paragraph} assumes the job is done, and immediately
1310 The usual use of this feature is to fill comments in programming
1311 language modes. If the function needs to fill a paragraph in the usual
1312 way, it can do so as follows:
1315 (let ((fill-paragraph-function nil))
1316 (fill-paragraph arg))
1320 @defvar use-hard-newlines
1321 If this variable is non-@code{nil}, the filling functions do not delete
1322 newlines that have the @code{hard} text property. These ``hard
1323 newlines'' act as paragraph separators.
1327 @section Margins for Filling
1330 This buffer-local variable specifies a string of text that appears at
1332 of normal text lines and should be disregarded when filling them. Any
1333 line that fails to start with the fill prefix is considered the start of
1334 a paragraph; so is any line that starts with the fill prefix followed by
1335 additional whitespace. Lines that start with the fill prefix but no
1336 additional whitespace are ordinary text lines that can be filled
1337 together. The resulting filled lines also start with the fill prefix.
1339 The fill prefix follows the left margin whitespace, if any.
1343 This buffer-local variable specifies the maximum width of filled lines.
1344 Its value should be an integer, which is a number of columns. All the
1345 filling, justification, and centering commands are affected by this
1346 variable, including Auto Fill mode (@pxref{Auto Filling}).
1348 As a practical matter, if you are writing text for other people to
1349 read, you should set @code{fill-column} to no more than 70. Otherwise
1350 the line will be too long for people to read comfortably, and this can
1351 make the text seem clumsy.
1354 @defvar default-fill-column
1355 The value of this variable is the default value for @code{fill-column} in
1356 buffers that do not override it. This is the same as
1357 @code{(default-value 'fill-column)}.
1359 The default value for @code{default-fill-column} is 70.
1362 @deffn Command set-left-margin from to margin
1363 This sets the @code{left-margin} property on the text from @var{from} to
1364 @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
1365 command also refills the region to fit the new margin.
1368 @deffn Command set-right-margin from to margin
1369 This sets the @code{right-margin} property on the text from @var{from}
1370 to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
1371 this command also refills the region to fit the new margin.
1374 @defun current-left-margin
1375 This function returns the proper left margin value to use for filling
1376 the text around point. The value is the sum of the @code{left-margin}
1377 property of the character at the start of the current line (or zero if
1378 none), and the value of the variable @code{left-margin}.
1381 @defun current-fill-column
1382 This function returns the proper fill column value to use for filling
1383 the text around point. The value is the value of the @code{fill-column}
1384 variable, minus the value of the @code{right-margin} property of the
1385 character after point.
1388 @deffn Command move-to-left-margin &optional n force
1389 This function moves point to the left margin of the current line. The
1390 column moved to is determined by calling the function
1391 @code{current-left-margin}. If the argument @var{n} is non-@code{nil},
1392 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
1394 If @var{force} is non-@code{nil}, that says to fix the line's
1395 indentation if that doesn't match the left margin value.
1398 @defun delete-to-left-margin from to
1399 This function removes left margin indentation from the text
1400 between @var{from} and @var{to}. The amount of indentation
1401 to delete is determined by calling @code{current-left-margin}.
1402 In no case does this function delete non-whitespace.
1405 @defun indent-to-left-margin
1406 This is the default @code{indent-line-function}, used in Fundamental
1407 mode, Text mode, etc. Its effect is to adjust the indentation at the
1408 beginning of the current line to the value specified by the variable
1409 @code{left-margin}. This may involve either inserting or deleting
1414 This variable specifies the base left margin column. In Fundamental
1415 mode, @kbd{C-j} indents to this column. This variable automatically
1416 becomes buffer-local when set in any fashion.
1419 @defvar fill-nobreak-predicate
1420 @tindex fill-nobreak-predicate
1421 This variable gives major modes a way to specify not to break a line at
1422 certain places. Its value should be a function. This function is
1423 called during filling, with no arguments and with point located at the
1424 place where a break is being considered. If the function returns
1425 non-@code{nil}, then the line won't be broken there.
1429 @section Adaptive Fill Mode
1430 @cindex Adaptive Fill mode
1432 Adaptive Fill mode chooses a fill prefix automatically from the text
1433 in each paragraph being filled.
1435 @defopt adaptive-fill-mode
1436 Adaptive Fill mode is enabled when this variable is non-@code{nil}.
1437 It is @code{t} by default.
1440 @defun fill-context-prefix from to
1441 This function implements the heart of Adaptive Fill mode; it chooses a
1442 fill prefix based on the text between @var{from} and @var{to}. It does
1443 this by looking at the first two lines of the paragraph, based on the
1444 variables described below.
1447 @defopt adaptive-fill-regexp
1448 This variable holds a regular expression to control Adaptive Fill mode.
1449 Adaptive Fill mode matches this regular expression against the text
1450 starting after the left margin whitespace (if any) on a line; the
1451 characters it matches are that line's candidate for the fill prefix.
1454 @defopt adaptive-fill-first-line-regexp
1455 In a one-line paragraph, if the candidate fill prefix matches this
1456 regular expression, or if it matches @code{comment-start-skip}, then it
1457 is used---otherwise, spaces amounting to the same width are used
1460 However, the fill prefix is never taken from a one-line paragraph
1461 if it would act as a paragraph starter on subsequent lines.
1464 @defopt adaptive-fill-function
1465 You can specify more complex ways of choosing a fill prefix
1466 automatically by setting this variable to a function. The function is
1467 called when @code{adaptive-fill-regexp} does not match, with point after
1468 the left margin of a line, and it should return the appropriate fill
1469 prefix based on that line. If it returns @code{nil}, that means it sees
1470 no fill prefix in that line.
1474 @comment node-name, next, previous, up
1475 @section Auto Filling
1476 @cindex filling, automatic
1477 @cindex Auto Fill mode
1479 Auto Fill mode is a minor mode that fills lines automatically as text
1480 is inserted. This section describes the hook used by Auto Fill mode.
1481 For a description of functions that you can call explicitly to fill and
1482 justify existing text, see @ref{Filling}.
1484 Auto Fill mode also enables the functions that change the margins and
1485 justification style to refill portions of the text. @xref{Margins}.
1487 @defvar auto-fill-function
1488 The value of this variable should be a function (of no arguments) to be
1489 called after self-inserting a space or a newline. It may be @code{nil},
1490 in which case nothing special is done in that case.
1492 The value of @code{auto-fill-function} is @code{do-auto-fill} when
1493 Auto-Fill mode is enabled. That is a function whose sole purpose is to
1494 implement the usual strategy for breaking a line.
1497 In older Emacs versions, this variable was named @code{auto-fill-hook},
1498 but since it is not called with the standard convention for hooks, it
1499 was renamed to @code{auto-fill-function} in version 19.
1503 @defvar normal-auto-fill-function
1504 This variable specifies the function to use for
1505 @code{auto-fill-function}, if and when Auto Fill is turned on. Major
1506 modes can set buffer-local values for this variable to alter how Auto
1511 @section Sorting Text
1512 @cindex sorting text
1514 The sorting functions described in this section all rearrange text in
1515 a buffer. This is in contrast to the function @code{sort}, which
1516 rearranges the order of the elements of a list (@pxref{Rearrangement}).
1517 The values returned by these functions are not meaningful.
1519 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
1520 This function is the general text-sorting routine that subdivides a
1521 buffer into records and then sorts them. Most of the commands in this
1522 section use this function.
1524 To understand how @code{sort-subr} works, consider the whole accessible
1525 portion of the buffer as being divided into disjoint pieces called
1526 @dfn{sort records}. The records may or may not be contiguous, but they
1527 must not overlap. A portion of each sort record (perhaps all of it) is
1528 designated as the sort key. Sorting rearranges the records in order by
1531 Usually, the records are rearranged in order of ascending sort key.
1532 If the first argument to the @code{sort-subr} function, @var{reverse},
1533 is non-@code{nil}, the sort records are rearranged in order of
1534 descending sort key.
1536 The next four arguments to @code{sort-subr} are functions that are
1537 called to move point across a sort record. They are called many times
1538 from within @code{sort-subr}.
1542 @var{nextrecfun} is called with point at the end of a record. This
1543 function moves point to the start of the next record. The first record
1544 is assumed to start at the position of point when @code{sort-subr} is
1545 called. Therefore, you should usually move point to the beginning of
1546 the buffer before calling @code{sort-subr}.
1548 This function can indicate there are no more sort records by leaving
1549 point at the end of the buffer.
1552 @var{endrecfun} is called with point within a record. It moves point to
1553 the end of the record.
1556 @var{startkeyfun} is called to move point from the start of a record to
1557 the start of the sort key. This argument is optional; if it is omitted,
1558 the whole record is the sort key. If supplied, the function should
1559 either return a non-@code{nil} value to be used as the sort key, or
1560 return @code{nil} to indicate that the sort key is in the buffer
1561 starting at point. In the latter case, @var{endkeyfun} is called to
1562 find the end of the sort key.
1565 @var{endkeyfun} is called to move point from the start of the sort key
1566 to the end of the sort key. This argument is optional. If
1567 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
1568 @code{nil}), then the sort key extends to the end of the record. There
1569 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1570 non-@code{nil} value.
1573 As an example of @code{sort-subr}, here is the complete function
1574 definition for @code{sort-lines}:
1578 ;; @r{Note that the first two lines of doc string}
1579 ;; @r{are effectively one line when viewed by a user.}
1580 (defun sort-lines (reverse beg end)
1581 "Sort lines in region alphabetically;\
1582 argument means descending order.
1583 Called from a program, there are three arguments:
1586 REVERSE (non-nil means reverse order),\
1587 BEG and END (region to sort).
1588 The variable `sort-fold-case' determines\
1589 whether alphabetic case affects
1593 (interactive "P\nr")
1596 (narrow-to-region beg end)
1597 (goto-char (point-min))
1598 (sort-subr reverse 'forward-line 'end-of-line))))
1602 Here @code{forward-line} moves point to the start of the next record,
1603 and @code{end-of-line} moves point to the end of record. We do not pass
1604 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
1605 record is used as the sort key.
1607 The @code{sort-paragraphs} function is very much the same, except that
1608 its @code{sort-subr} call looks like this:
1615 (while (and (not (eobp))
1616 (looking-at paragraph-separate))
1622 Markers pointing into any sort records are left with no useful
1623 position after @code{sort-subr} returns.
1626 @defopt sort-fold-case
1627 If this variable is non-@code{nil}, @code{sort-subr} and the other
1628 buffer sorting functions ignore case when comparing strings.
1631 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
1632 This command sorts the region between @var{start} and @var{end}
1633 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
1634 If @var{reverse} is a negative integer, then sorting is in reverse
1637 Alphabetical sorting means that two sort keys are compared by
1638 comparing the first characters of each, the second characters of each,
1639 and so on. If a mismatch is found, it means that the sort keys are
1640 unequal; the sort key whose character is less at the point of first
1641 mismatch is the lesser sort key. The individual characters are compared
1642 according to their numerical character codes in the Emacs character set.
1644 The value of the @var{record-regexp} argument specifies how to divide
1645 the buffer into sort records. At the end of each record, a search is
1646 done for this regular expression, and the text that matches it is taken
1647 as the next record. For example, the regular expression @samp{^.+$},
1648 which matches lines with at least one character besides a newline, would
1649 make each such line into a sort record. @xref{Regular Expressions}, for
1650 a description of the syntax and meaning of regular expressions.
1652 The value of the @var{key-regexp} argument specifies what part of each
1653 record is the sort key. The @var{key-regexp} could match the whole
1654 record, or only a part. In the latter case, the rest of the record has
1655 no effect on the sorted order of records, but it is carried along when
1656 the record moves to its new position.
1658 The @var{key-regexp} argument can refer to the text matched by a
1659 subexpression of @var{record-regexp}, or it can be a regular expression
1662 If @var{key-regexp} is:
1665 @item @samp{\@var{digit}}
1666 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
1667 grouping in @var{record-regexp} is the sort key.
1670 then the whole record is the sort key.
1672 @item a regular expression
1673 then @code{sort-regexp-fields} searches for a match for the regular
1674 expression within the record. If such a match is found, it is the sort
1675 key. If there is no match for @var{key-regexp} within a record then
1676 that record is ignored, which means its position in the buffer is not
1677 changed. (The other records may move around it.)
1680 For example, if you plan to sort all the lines in the region by the
1681 first word on each line starting with the letter @samp{f}, you should
1682 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
1683 @samp{\<f\w*\>}. The resulting expression looks like this:
1687 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
1693 If you call @code{sort-regexp-fields} interactively, it prompts for
1694 @var{record-regexp} and @var{key-regexp} in the minibuffer.
1697 @deffn Command sort-lines reverse start end
1698 This command alphabetically sorts lines in the region between
1699 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1700 is in reverse order.
1703 @deffn Command sort-paragraphs reverse start end
1704 This command alphabetically sorts paragraphs in the region between
1705 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1706 is in reverse order.
1709 @deffn Command sort-pages reverse start end
1710 This command alphabetically sorts pages in the region between
1711 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1712 is in reverse order.
1715 @deffn Command sort-fields field start end
1716 This command sorts lines in the region between @var{start} and
1717 @var{end}, comparing them alphabetically by the @var{field}th field
1718 of each line. Fields are separated by whitespace and numbered starting
1719 from 1. If @var{field} is negative, sorting is by the
1720 @w{@minus{}@var{field}th} field from the end of the line. This command
1721 is useful for sorting tables.
1724 @deffn Command sort-numeric-fields field start end
1725 This command sorts lines in the region between @var{start} and
1726 @var{end}, comparing them numerically by the @var{field}th field of each
1727 line. The specified field must contain a number in each line of the
1728 region. Fields are separated by whitespace and numbered starting from
1729 1. If @var{field} is negative, sorting is by the
1730 @w{@minus{}@var{field}th} field from the end of the line. This command
1731 is useful for sorting tables.
1734 @deffn Command sort-columns reverse &optional beg end
1735 This command sorts the lines in the region between @var{beg} and
1736 @var{end}, comparing them alphabetically by a certain range of columns.
1737 The column positions of @var{beg} and @var{end} bound the range of
1740 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
1742 One unusual thing about this command is that the entire line
1743 containing position @var{beg}, and the entire line containing position
1744 @var{end}, are included in the region sorted.
1746 Note that @code{sort-columns} uses the @code{sort} utility program,
1747 and so cannot work properly on text containing tab characters. Use
1748 @kbd{M-x untabify} to convert tabs to spaces before sorting.
1752 @comment node-name, next, previous, up
1753 @section Counting Columns
1755 @cindex counting columns
1756 @cindex horizontal position
1758 The column functions convert between a character position (counting
1759 characters from the beginning of the buffer) and a column position
1760 (counting screen characters from the beginning of a line).
1762 These functions count each character according to the number of
1763 columns it occupies on the screen. This means control characters count
1764 as occupying 2 or 4 columns, depending upon the value of
1765 @code{ctl-arrow}, and tabs count as occupying a number of columns that
1766 depends on the value of @code{tab-width} and on the column where the tab
1767 begins. @xref{Usual Display}.
1769 Column number computations ignore the width of the window and the
1770 amount of horizontal scrolling. Consequently, a column value can be
1771 arbitrarily high. The first (or leftmost) column is numbered 0.
1773 @defun current-column
1774 This function returns the horizontal position of point, measured in
1775 columns, counting from 0 at the left margin. The column position is the
1776 sum of the widths of all the displayed representations of the characters
1777 between the start of the current line and point.
1779 For an example of using @code{current-column}, see the description of
1780 @code{count-lines} in @ref{Text Lines}.
1783 @defun move-to-column column &optional force
1784 This function moves point to @var{column} in the current line. The
1785 calculation of @var{column} takes into account the widths of the
1786 displayed representations of the characters between the start of the
1789 If column @var{column} is beyond the end of the line, point moves to the
1790 end of the line. If @var{column} is negative, point moves to the
1791 beginning of the line.
1793 If it is impossible to move to column @var{column} because that is in
1794 the middle of a multicolumn character such as a tab, point moves to the
1795 end of that character. However, if @var{force} is non-@code{nil}, and
1796 @var{column} is in the middle of a tab, then @code{move-to-column}
1797 converts the tab into spaces so that it can move precisely to column
1798 @var{column}. Other multicolumn characters can cause anomalies despite
1799 @var{force}, since there is no way to split them.
1801 The argument @var{force} also has an effect if the line isn't long
1802 enough to reach column @var{column}; if it is @code{t}, that means to
1803 add whitespace at the end of the line to reach that column.
1805 If @var{column} is not an integer, an error is signaled.
1807 The return value is the column number actually moved to.
1811 @section Indentation
1814 The indentation functions are used to examine, move to, and change
1815 whitespace that is at the beginning of a line. Some of the functions
1816 can also change whitespace elsewhere on a line. Columns and indentation
1817 count from zero at the left margin.
1820 * Primitive Indent:: Functions used to count and insert indentation.
1821 * Mode-Specific Indent:: Customize indentation for different modes.
1822 * Region Indent:: Indent all the lines in a region.
1823 * Relative Indent:: Indent the current line based on previous lines.
1824 * Indent Tabs:: Adjustable, typewriter-like tab stops.
1825 * Motion by Indent:: Move to first non-blank character.
1828 @node Primitive Indent
1829 @subsection Indentation Primitives
1831 This section describes the primitive functions used to count and
1832 insert indentation. The functions in the following sections use these
1833 primitives. @xref{Width}, for related functions.
1835 @defun current-indentation
1836 @comment !!Type Primitive Function
1837 @comment !!SourceFile indent.c
1838 This function returns the indentation of the current line, which is
1839 the horizontal position of the first nonblank character. If the
1840 contents are entirely blank, then this is the horizontal position of the
1844 @deffn Command indent-to column &optional minimum
1845 @comment !!Type Primitive Function
1846 @comment !!SourceFile indent.c
1847 This function indents from point with tabs and spaces until @var{column}
1848 is reached. If @var{minimum} is specified and non-@code{nil}, then at
1849 least that many spaces are inserted even if this requires going beyond
1850 @var{column}. Otherwise the function does nothing if point is already
1851 beyond @var{column}. The value is the column at which the inserted
1854 The inserted whitespace characters inherit text properties from the
1855 surrounding text (usually, from the preceding text only). @xref{Sticky
1859 @defopt indent-tabs-mode
1860 @comment !!SourceFile indent.c
1861 If this variable is non-@code{nil}, indentation functions can insert
1862 tabs as well as spaces. Otherwise, they insert only spaces. Setting
1863 this variable automatically makes it buffer-local in the current buffer.
1866 @node Mode-Specific Indent
1867 @subsection Indentation Controlled by Major Mode
1869 An important function of each major mode is to customize the @key{TAB}
1870 key to indent properly for the language being edited. This section
1871 describes the mechanism of the @key{TAB} key and how to control it.
1872 The functions in this section return unpredictable values.
1874 @defvar indent-line-function
1875 This variable's value is the function to be used by @key{TAB} (and
1876 various commands) to indent the current line. The command
1877 @code{indent-according-to-mode} does no more than call this function.
1879 In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C
1880 mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
1881 In Fundamental mode, Text mode, and many other modes with no standard
1882 for indentation, the value is @code{indent-to-left-margin} (which is the
1886 @deffn Command indent-according-to-mode
1887 This command calls the function in @code{indent-line-function} to
1888 indent the current line in a way appropriate for the current major mode.
1891 @deffn Command indent-for-tab-command
1892 This command calls the function in @code{indent-line-function} to indent
1893 the current line; however, if that function is
1894 @code{indent-to-left-margin}, @code{insert-tab} is called instead. (That
1895 is a trivial command that inserts a tab character.)
1898 @deffn Command newline-and-indent
1899 @comment !!SourceFile simple.el
1900 This function inserts a newline, then indents the new line (the one
1901 following the newline just inserted) according to the major mode.
1903 It does indentation by calling the current @code{indent-line-function}.
1904 In programming language modes, this is the same thing @key{TAB} does,
1905 but in some text modes, where @key{TAB} inserts a tab,
1906 @code{newline-and-indent} indents to the column specified by
1910 @deffn Command reindent-then-newline-and-indent
1911 @comment !!SourceFile simple.el
1912 This command reindents the current line, inserts a newline at point,
1913 and then indents the new line (the one following the newline just
1916 This command does indentation on both lines according to the current
1917 major mode, by calling the current value of @code{indent-line-function}.
1918 In programming language modes, this is the same thing @key{TAB} does,
1919 but in some text modes, where @key{TAB} inserts a tab,
1920 @code{reindent-then-newline-and-indent} indents to the column specified
1921 by @code{left-margin}.
1925 @subsection Indenting an Entire Region
1927 This section describes commands that indent all the lines in the
1928 region. They return unpredictable values.
1930 @deffn Command indent-region start end to-column
1931 This command indents each nonblank line starting between @var{start}
1932 (inclusive) and @var{end} (exclusive). If @var{to-column} is
1933 @code{nil}, @code{indent-region} indents each nonblank line by calling
1934 the current mode's indentation function, the value of
1935 @code{indent-line-function}.
1937 If @var{to-column} is non-@code{nil}, it should be an integer
1938 specifying the number of columns of indentation; then this function
1939 gives each line exactly that much indentation, by either adding or
1940 deleting whitespace.
1942 If there is a fill prefix, @code{indent-region} indents each line
1943 by making it start with the fill prefix.
1946 @defvar indent-region-function
1947 The value of this variable is a function that can be used by
1948 @code{indent-region} as a short cut. It should take two arguments, the
1949 start and end of the region. You should design the function so
1950 that it will produce the same results as indenting the lines of the
1951 region one by one, but presumably faster.
1953 If the value is @code{nil}, there is no short cut, and
1954 @code{indent-region} actually works line by line.
1956 A short-cut function is useful in modes such as C mode and Lisp mode,
1957 where the @code{indent-line-function} must scan from the beginning of
1958 the function definition: applying it to each line would be quadratic in
1959 time. The short cut can update the scan information as it moves through
1960 the lines indenting them; this takes linear time. In a mode where
1961 indenting a line individually is fast, there is no need for a short cut.
1963 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
1964 a different meaning and does not use this variable.
1967 @deffn Command indent-rigidly start end count
1968 @comment !!SourceFile indent.el
1969 This command indents all lines starting between @var{start}
1970 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
1971 This ``preserves the shape'' of the affected region, moving it as a
1972 rigid unit. Consequently, this command is useful not only for indenting
1973 regions of unindented text, but also for indenting regions of formatted
1976 For example, if @var{count} is 3, this command adds 3 columns of
1977 indentation to each of the lines beginning in the region specified.
1979 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
1980 @code{indent-rigidly} to indent the text copied from the message being
1984 @defun indent-code-rigidly start end columns &optional nochange-regexp
1985 This is like @code{indent-rigidly}, except that it doesn't alter lines
1986 that start within strings or comments.
1988 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
1989 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
1992 @node Relative Indent
1993 @subsection Indentation Relative to Previous Lines
1995 This section describes two commands that indent the current line
1996 based on the contents of previous lines.
1998 @deffn Command indent-relative &optional unindented-ok
1999 This command inserts whitespace at point, extending to the same
2000 column as the next @dfn{indent point} of the previous nonblank line. An
2001 indent point is a non-whitespace character following whitespace. The
2002 next indent point is the first one at a column greater than the current
2003 column of point. For example, if point is underneath and to the left of
2004 the first non-blank character of a line of text, it moves to that column
2005 by inserting whitespace.
2007 If the previous nonblank line has no next indent point (i.e., none at a
2008 great enough column position), @code{indent-relative} either does
2009 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
2010 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right
2011 of the last column of a short line of text, this command ordinarily
2012 moves point to the next tab stop by inserting whitespace.
2014 The return value of @code{indent-relative} is unpredictable.
2016 In the following example, point is at the beginning of the second
2021 This line is indented twelve spaces.
2022 @point{}The quick brown fox jumped.
2027 Evaluation of the expression @code{(indent-relative nil)} produces the
2032 This line is indented twelve spaces.
2033 @point{}The quick brown fox jumped.
2037 In this next example, point is between the @samp{m} and @samp{p} of
2042 This line is indented twelve spaces.
2043 The quick brown fox jum@point{}ped.
2048 Evaluation of the expression @code{(indent-relative nil)} produces the
2053 This line is indented twelve spaces.
2054 The quick brown fox jum @point{}ped.
2059 @deffn Command indent-relative-maybe
2060 @comment !!SourceFile indent.el
2061 This command indents the current line like the previous nonblank line,
2062 by calling @code{indent-relative} with @code{t} as the
2063 @var{unindented-ok} argument. The return value is unpredictable.
2065 If the previous nonblank line has no indent points beyond the current
2066 column, this command does nothing.
2070 @comment node-name, next, previous, up
2071 @subsection Adjustable ``Tab Stops''
2072 @cindex tabs stops for indentation
2074 This section explains the mechanism for user-specified ``tab stops''
2075 and the mechanisms that use and set them. The name ``tab stops'' is
2076 used because the feature is similar to that of the tab stops on a
2077 typewriter. The feature works by inserting an appropriate number of
2078 spaces and tab characters to reach the next tab stop column; it does not
2079 affect the display of tab characters in the buffer (@pxref{Usual
2080 Display}). Note that the @key{TAB} character as input uses this tab
2081 stop feature only in a few major modes, such as Text mode.
2083 @deffn Command tab-to-tab-stop
2084 This command inserts spaces or tabs before point, up to the next tab
2085 stop column defined by @code{tab-stop-list}. It searches the list for
2086 an element greater than the current column number, and uses that element
2087 as the column to indent to. It does nothing if no such element is
2091 @defopt tab-stop-list
2092 This variable is the list of tab stop columns used by
2093 @code{tab-to-tab-stops}. The elements should be integers in increasing
2094 order. The tab stop columns need not be evenly spaced.
2096 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
2100 @node Motion by Indent
2101 @subsection Indentation-Based Motion Commands
2103 These commands, primarily for interactive use, act based on the
2104 indentation in the text.
2106 @deffn Command back-to-indentation
2107 @comment !!SourceFile simple.el
2108 This command moves point to the first non-whitespace character in the
2109 current line (which is the line in which point is located). It returns
2113 @deffn Command backward-to-indentation arg
2114 @comment !!SourceFile simple.el
2115 This command moves point backward @var{arg} lines and then to the
2116 first nonblank character on that line. It returns @code{nil}.
2119 @deffn Command forward-to-indentation arg
2120 @comment !!SourceFile simple.el
2121 This command moves point forward @var{arg} lines and then to the first
2122 nonblank character on that line. It returns @code{nil}.
2126 @comment node-name, next, previous, up
2127 @section Case Changes
2128 @cindex case conversion in buffers
2130 The case change commands described here work on text in the current
2131 buffer. @xref{Case Conversion}, for case conversion functions that work
2132 on strings and characters. @xref{Case Tables}, for how to customize
2133 which characters are upper or lower case and how to convert them.
2135 @deffn Command capitalize-region start end
2136 This function capitalizes all words in the region defined by
2137 @var{start} and @var{end}. To capitalize means to convert each word's
2138 first character to upper case and convert the rest of each word to lower
2139 case. The function returns @code{nil}.
2141 If one end of the region is in the middle of a word, the part of the
2142 word within the region is treated as an entire word.
2144 When @code{capitalize-region} is called interactively, @var{start} and
2145 @var{end} are point and the mark, with the smallest first.
2149 ---------- Buffer: foo ----------
2150 This is the contents of the 5th foo.
2151 ---------- Buffer: foo ----------
2155 (capitalize-region 1 44)
2158 ---------- Buffer: foo ----------
2159 This Is The Contents Of The 5th Foo.
2160 ---------- Buffer: foo ----------
2165 @deffn Command downcase-region start end
2166 This function converts all of the letters in the region defined by
2167 @var{start} and @var{end} to lower case. The function returns
2170 When @code{downcase-region} is called interactively, @var{start} and
2171 @var{end} are point and the mark, with the smallest first.
2174 @deffn Command upcase-region start end
2175 This function converts all of the letters in the region defined by
2176 @var{start} and @var{end} to upper case. The function returns
2179 When @code{upcase-region} is called interactively, @var{start} and
2180 @var{end} are point and the mark, with the smallest first.
2183 @deffn Command capitalize-word count
2184 This function capitalizes @var{count} words after point, moving point
2185 over as it does. To capitalize means to convert each word's first
2186 character to upper case and convert the rest of each word to lower case.
2187 If @var{count} is negative, the function capitalizes the
2188 @minus{}@var{count} previous words but does not move point. The value
2191 If point is in the middle of a word, the part of the word before point
2192 is ignored when moving forward. The rest is treated as an entire word.
2194 When @code{capitalize-word} is called interactively, @var{count} is
2195 set to the numeric prefix argument.
2198 @deffn Command downcase-word count
2199 This function converts the @var{count} words after point to all lower
2200 case, moving point over as it does. If @var{count} is negative, it
2201 converts the @minus{}@var{count} previous words but does not move point.
2202 The value is @code{nil}.
2204 When @code{downcase-word} is called interactively, @var{count} is set
2205 to the numeric prefix argument.
2208 @deffn Command upcase-word count
2209 This function converts the @var{count} words after point to all upper
2210 case, moving point over as it does. If @var{count} is negative, it
2211 converts the @minus{}@var{count} previous words but does not move point.
2212 The value is @code{nil}.
2214 When @code{upcase-word} is called interactively, @var{count} is set to
2215 the numeric prefix argument.
2218 @node Text Properties
2219 @section Text Properties
2220 @cindex text properties
2221 @cindex attributes of text
2222 @cindex properties of text
2224 Each character position in a buffer or a string can have a @dfn{text
2225 property list}, much like the property list of a symbol (@pxref{Property
2226 Lists}). The properties belong to a particular character at a
2227 particular place, such as, the letter @samp{T} at the beginning of this
2228 sentence or the first @samp{o} in @samp{foo}---if the same character
2229 occurs in two different places, the two occurrences generally have
2230 different properties.
2232 Each property has a name and a value. Both of these can be any Lisp
2233 object, but the name is normally a symbol. The usual way to access the
2234 property list is to specify a name and ask what value corresponds to it.
2236 If a character has a @code{category} property, we call it the
2237 @dfn{category} of the character. It should be a symbol. The properties
2238 of the symbol serve as defaults for the properties of the character.
2240 Copying text between strings and buffers preserves the properties
2241 along with the characters; this includes such diverse functions as
2242 @code{substring}, @code{insert}, and @code{buffer-substring}.
2245 * Examining Properties:: Looking at the properties of one character.
2246 * Changing Properties:: Setting the properties of a range of text.
2247 * Property Search:: Searching for where a property changes value.
2248 * Special Properties:: Particular properties with special meanings.
2249 * Format Properties:: Properties for representing formatting of text.
2250 * Sticky Properties:: How inserted text gets properties from
2252 * Saving Properties:: Saving text properties in files, and reading
2254 * Lazy Properties:: Computing text properties in a lazy fashion
2255 only when text is examined.
2256 * Clickable Text:: Using text properties to make regions of text
2257 do something when you click on them.
2258 * Not Intervals:: Why text properties do not use
2259 Lisp-visible text intervals.
2262 @node Examining Properties
2263 @subsection Examining Text Properties
2265 The simplest way to examine text properties is to ask for the value of
2266 a particular property of a particular character. For that, use
2267 @code{get-text-property}. Use @code{text-properties-at} to get the
2268 entire property list of a character. @xref{Property Search}, for
2269 functions to examine the properties of a number of characters at once.
2271 These functions handle both strings and buffers. Keep in mind that
2272 positions in a string start from 0, whereas positions in a buffer start
2275 @defun get-text-property pos prop &optional object
2276 This function returns the value of the @var{prop} property of the
2277 character after position @var{pos} in @var{object} (a buffer or
2278 string). The argument @var{object} is optional and defaults to the
2281 If there is no @var{prop} property strictly speaking, but the character
2282 has a category that is a symbol, then @code{get-text-property} returns
2283 the @var{prop} property of that symbol.
2286 @defun get-char-property pos prop &optional object
2287 This function is like @code{get-text-property}, except that it checks
2288 overlays first and then text properties. @xref{Overlays}.
2290 The argument @var{object} may be a string, a buffer, or a window. If it
2291 is a window, then the buffer displayed in that window is used for text
2292 properties and overlays, but only the overlays active for that window
2293 are considered. If @var{object} is a buffer, then all overlays in that
2294 buffer are considered, as well as text properties. If @var{object} is a
2295 string, only text properties are considered, since strings never have
2299 @defun text-properties-at position &optional object
2300 This function returns the entire property list of the character at
2301 @var{position} in the string or buffer @var{object}. If @var{object} is
2302 @code{nil}, it defaults to the current buffer.
2305 @defvar default-text-properties
2306 This variable holds a property list giving default values for text
2307 properties. Whenever a character does not specify a value for a
2308 property, neither directly nor through a category symbol, the value
2309 stored in this list is used instead. Here is an example:
2312 (setq default-text-properties '(foo 69))
2313 ;; @r{Make sure character 1 has no properties of its own.}
2314 (set-text-properties 1 2 nil)
2315 ;; @r{What we get, when we ask, is the default value.}
2316 (get-text-property 1 'foo)
2321 @node Changing Properties
2322 @subsection Changing Text Properties
2324 The primitives for changing properties apply to a specified range of
2325 text in a buffer or string. The function @code{set-text-properties}
2326 (see end of section) sets the entire property list of the text in that
2327 range; more often, it is useful to add, change, or delete just certain
2328 properties specified by name.
2330 Since text properties are considered part of the contents of the
2331 buffer (or string), and can affect how a buffer looks on the screen, any
2332 change in buffer text properties mark the buffer as modified. Buffer
2333 text property changes are undoable also (@pxref{Undo}).
2335 @defun put-text-property start end prop value &optional object
2336 This function sets the @var{prop} property to @var{value} for the text
2337 between @var{start} and @var{end} in the string or buffer @var{object}.
2338 If @var{object} is @code{nil}, it defaults to the current buffer.
2341 @defun add-text-properties start end props &optional object
2342 This function adds or overrides text properties for the text between
2343 @var{start} and @var{end} in the string or buffer @var{object}. If
2344 @var{object} is @code{nil}, it defaults to the current buffer.
2346 The argument @var{props} specifies which properties to add. It should
2347 have the form of a property list (@pxref{Property Lists}): a list whose
2348 elements include the property names followed alternately by the
2349 corresponding values.
2351 The return value is @code{t} if the function actually changed some
2352 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2353 its values agree with those in the text).
2355 For example, here is how to set the @code{comment} and @code{face}
2356 properties of a range of text:
2359 (add-text-properties @var{start} @var{end}
2360 '(comment t face highlight))
2364 @defun remove-text-properties start end props &optional object
2365 This function deletes specified text properties from the text between
2366 @var{start} and @var{end} in the string or buffer @var{object}. If
2367 @var{object} is @code{nil}, it defaults to the current buffer.
2369 The argument @var{props} specifies which properties to delete. It
2370 should have the form of a property list (@pxref{Property Lists}): a list
2371 whose elements are property names alternating with corresponding values.
2372 But only the names matter---the values that accompany them are ignored.
2373 For example, here's how to remove the @code{face} property.
2376 (remove-text-properties @var{start} @var{end} '(face nil))
2379 The return value is @code{t} if the function actually changed some
2380 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2381 if no character in the specified text had any of those properties).
2383 To remove all text properties from certain text, use
2384 @code{set-text-properties} and specify @code{nil} for the new property
2388 @defun set-text-properties start end props &optional object
2389 This function completely replaces the text property list for the text
2390 between @var{start} and @var{end} in the string or buffer @var{object}.
2391 If @var{object} is @code{nil}, it defaults to the current buffer.
2393 The argument @var{props} is the new property list. It should be a list
2394 whose elements are property names alternating with corresponding values.
2396 After @code{set-text-properties} returns, all the characters in the
2397 specified range have identical properties.
2399 If @var{props} is @code{nil}, the effect is to get rid of all properties
2400 from the specified range of text. Here's an example:
2403 (set-text-properties @var{start} @var{end} nil)
2407 The easiest way to make a string with text properties
2408 is with @code{propertize}:
2410 @defun propertize string &rest properties
2412 This function returns a copy of @var{string} which has the text
2413 properties @var{properties}. These properties apply to all the
2414 characters in the string that is returned. Here is an example that
2415 constructs a string with a @code{face} property and a @code{mouse-face}
2419 (propertize "foo" 'face 'italic
2420 'mouse-face 'bold-italic)
2421 @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
2424 To put different properties on various parts of a string, you can
2425 construct each part with @code{propertize} and then combine them with
2430 (propertize "foo" 'face 'italic
2431 'mouse-face 'bold-italic)
2433 (propertize "bar" 'face 'italic
2434 'mouse-face 'bold-italic))
2435 @result{} #("foo and bar"
2436 0 3 (face italic mouse-face bold-italic)
2438 8 11 (face italic mouse-face bold-italic))
2442 See also the function @code{buffer-substring-no-properties}
2443 (@pxref{Buffer Contents}) which copies text from the buffer
2444 but does not copy its properties.
2446 @node Property Search
2447 @subsection Text Property Search Functions
2449 In typical use of text properties, most of the time several or many
2450 consecutive characters have the same value for a property. Rather than
2451 writing your programs to examine characters one by one, it is much
2452 faster to process chunks of text that have the same property value.
2454 Here are functions you can use to do this. They use @code{eq} for
2455 comparing property values. In all cases, @var{object} defaults to the
2458 For high performance, it's very important to use the @var{limit}
2459 argument to these functions, especially the ones that search for a
2460 single property---otherwise, they may spend a long time scanning to the
2461 end of the buffer, if the property you are interested in does not change.
2463 These functions do not move point; instead, they return a position (or
2464 @code{nil}). Remember that a position is always between two characters;
2465 the position returned by these functions is between two characters with
2466 different properties.
2468 @defun next-property-change pos &optional object limit
2469 The function scans the text forward from position @var{pos} in the
2470 string or buffer @var{object} till it finds a change in some text
2471 property, then returns the position of the change. In other words, it
2472 returns the position of the first character beyond @var{pos} whose
2473 properties are not identical to those of the character just after
2476 If @var{limit} is non-@code{nil}, then the scan ends at position
2477 @var{limit}. If there is no property change before that point,
2478 @code{next-property-change} returns @var{limit}.
2480 The value is @code{nil} if the properties remain unchanged all the way
2481 to the end of @var{object} and @var{limit} is @code{nil}. If the value
2482 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
2483 The value equals @var{pos} only when @var{limit} equals @var{pos}.
2485 Here is an example of how to scan the buffer by chunks of text within
2486 which all properties are constant:
2490 (let ((plist (text-properties-at (point)))
2492 (or (next-property-change (point) (current-buffer))
2494 @r{Process text from point to @var{next-change}@dots{}}
2495 (goto-char next-change)))
2499 @defun next-single-property-change pos prop &optional object limit
2500 The function scans the text forward from position @var{pos} in the
2501 string or buffer @var{object} till it finds a change in the @var{prop}
2502 property, then returns the position of the change. In other words, it
2503 returns the position of the first character beyond @var{pos} whose
2504 @var{prop} property differs from that of the character just after
2507 If @var{limit} is non-@code{nil}, then the scan ends at position
2508 @var{limit}. If there is no property change before that point,
2509 @code{next-single-property-change} returns @var{limit}.
2511 The value is @code{nil} if the property remains unchanged all the way to
2512 the end of @var{object} and @var{limit} is @code{nil}. If the value is
2513 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
2514 equals @var{pos} only if @var{limit} equals @var{pos}.
2517 @defun previous-property-change pos &optional object limit
2518 This is like @code{next-property-change}, but scans back from @var{pos}
2519 instead of forward. If the value is non-@code{nil}, it is a position
2520 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
2524 @defun previous-single-property-change pos prop &optional object limit
2525 This is like @code{next-single-property-change}, but scans back from
2526 @var{pos} instead of forward. If the value is non-@code{nil}, it is a
2527 position less than or equal to @var{pos}; it equals @var{pos} only if
2528 @var{limit} equals @var{pos}.
2531 @defun next-char-property-change position &optional limit
2532 @tindex next-char-property-change
2533 This is like @code{next-property-change} except that it considers
2534 overlay properties as well as text properties. There is no @var{object}
2535 operand because this function operates only on the current buffer. It
2536 returns the next address at which either kind of property changes.
2539 @defun previous-char-property-change position &optional limit
2540 @tindex previous-char-property-change
2541 This is like @code{next-char-property-change}, but scans back from
2542 @var{position} instead of forward.
2545 @defun text-property-any start end prop value &optional object
2546 This function returns non-@code{nil} if at least one character between
2547 @var{start} and @var{end} has a property @var{prop} whose value is
2548 @var{value}. More precisely, it returns the position of the first such
2549 character. Otherwise, it returns @code{nil}.
2551 The optional fifth argument, @var{object}, specifies the string or
2552 buffer to scan. Positions are relative to @var{object}. The default
2553 for @var{object} is the current buffer.
2556 @defun text-property-not-all start end prop value &optional object
2557 This function returns non-@code{nil} if at least one character between
2558 @var{start} and @var{end} does not have a property @var{prop} with value
2559 @var{value}. More precisely, it returns the position of the first such
2560 character. Otherwise, it returns @code{nil}.
2562 The optional fifth argument, @var{object}, specifies the string or
2563 buffer to scan. Positions are relative to @var{object}. The default
2564 for @var{object} is the current buffer.
2567 @node Special Properties
2568 @subsection Properties with Special Meanings
2570 Here is a table of text property names that have special built-in
2571 meanings. The following sections list a few additional special property
2572 names that control filling and property inheritance. All other names
2573 have no standard meaning, and you can use them as you like.
2576 @cindex category of text character
2577 @kindex category @r{(text property)}
2579 If a character has a @code{category} property, we call it the
2580 @dfn{category} of the character. It should be a symbol. The properties
2581 of the symbol serve as defaults for the properties of the character.
2584 @cindex face codes of text
2585 @kindex face @r{(text property)}
2586 You can use the property @code{face} to control the font and color of
2587 text. @xref{Faces}, for more information.
2589 In the simplest case, the value is a face name. It can also be a list;
2590 then each element can be any of these possibilities;
2594 A face name (a symbol or string).
2597 Starting in Emacs 21, a property list of face attributes. This has the
2598 form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
2599 face attribute name and @var{value} is a meaningful value for that
2600 attribute. With this feature, you do not need to create a face each
2601 time you want to specify a particular attribute for certain text.
2602 @xref{Face Attributes}.
2605 A cons cell of the form @code{(foreground-color . @var{color-name})} or
2606 @code{(background-color . @var{color-name})}. These elements specify
2607 just the foreground color or just the background color.
2609 @code{(foreground-color . @var{color-name})} is equivalent to
2610 @code{(:foreground @var{color-name})}, and likewise for the background.
2613 @xref{Font Lock Mode}, for information on how to update @code{face}
2614 properties automatically based on the contents of the text.
2617 @kindex mouse-face @r{(text property)}
2618 The property @code{mouse-face} is used instead of @code{face} when the
2619 mouse is on or near the character. For this purpose, ``near'' means
2620 that all text between the character and where the mouse is have the same
2621 @code{mouse-face} property value.
2624 @kindex fontified @r{(text property)}
2625 This property, if non-@code{nil}, says that text in the buffer has
2626 had faces assigned automatically by a feature such as Font-Lock mode.
2630 @kindex display @r{(text property)}
2631 This property activates various features that change the
2632 way text is displayed. For example, it can make text appear taller
2633 or shorter, higher or lower, wider or narror, or replaced with an image.
2634 @xref{Display Property}.
2637 @kindex help-echo @r{(text property)}
2638 If text has a string as its @code{help-echo} property, then when you
2639 move the mouse onto that text, Emacs displays that string in the echo
2640 area, or in the tooltip window. This feature is used in the mode line.
2641 It is available starting in Emacs 21.
2644 @cindex keymap of character
2645 @kindex local-map @r{(text property)}
2646 You can specify a different keymap for some of the text in a buffer by
2647 means of the @code{local-map} property. The property's value for the
2648 character after point, if non-@code{nil}, is used for key lookup instead
2649 of the buffer's local map. If the property value is a symbol, the
2650 symbol's function definition is used as the keymap. @xref{Active
2654 The @code{syntax-table} property overrides what the syntax table says
2655 about this particular character. @xref{Syntax Properties}.
2658 @cindex read-only character
2659 @kindex read-only @r{(text property)}
2660 If a character has the property @code{read-only}, then modifying that
2661 character is not allowed. Any command that would do so gets an error.
2663 Insertion next to a read-only character is an error if inserting
2664 ordinary text there would inherit the @code{read-only} property due to
2665 stickiness. Thus, you can control permission to insert next to
2666 read-only text by controlling the stickiness. @xref{Sticky Properties}.
2668 Since changing properties counts as modifying the buffer, it is not
2669 possible to remove a @code{read-only} property unless you know the
2670 special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
2671 and then remove the property. @xref{Read Only Buffers}.
2674 @kindex invisible @r{(text property)}
2675 A non-@code{nil} @code{invisible} property can make a character invisible
2676 on the screen. @xref{Invisible Text}, for details.
2679 @kindex intangible @r{(text property)}
2680 If a group of consecutive characters have equal and non-@code{nil}
2681 @code{intangible} properties, then you cannot place point between them.
2682 If you try to move point forward into the group, point actually moves to
2683 the end of the group. If you try to move point backward into the group,
2684 point actually moves to the start of the group.
2686 When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
2687 the @code{intangible} property is ignored.
2689 @item modification-hooks
2690 @cindex change hooks for a character
2691 @cindex hooks for changing a character
2692 @kindex modification-hooks @r{(text property)}
2693 If a character has the property @code{modification-hooks}, then its
2694 value should be a list of functions; modifying that character calls all
2695 of those functions. Each function receives two arguments: the beginning
2696 and end of the part of the buffer being modified. Note that if a
2697 particular modification hook function appears on several characters
2698 being modified by a single primitive, you can't predict how many times
2699 the function will be called.
2701 @item insert-in-front-hooks
2702 @itemx insert-behind-hooks
2703 @kindex insert-in-front-hooks @r{(text property)}
2704 @kindex insert-behind-hooks @r{(text property)}
2705 The operation of inserting text in a buffer also calls the functions
2706 listed in the @code{insert-in-front-hooks} property of the following
2707 character and in the @code{insert-behind-hooks} property of the
2708 preceding character. These functions receive two arguments, the
2709 beginning and end of the inserted text. The functions are called
2710 @emph{after} the actual insertion takes place.
2712 See also @ref{Change Hooks}, for other hooks that are called
2713 when you change text in a buffer.
2717 @cindex hooks for motion of point
2718 @kindex point-entered @r{(text property)}
2719 @kindex point-left @r{(text property)}
2720 The special properties @code{point-entered} and @code{point-left}
2721 record hook functions that report motion of point. Each time point
2722 moves, Emacs compares these two property values:
2726 the @code{point-left} property of the character after the old location,
2729 the @code{point-entered} property of the character after the new
2734 If these two values differ, each of them is called (if not @code{nil})
2735 with two arguments: the old value of point, and the new one.
2737 The same comparison is made for the characters before the old and new
2738 locations. The result may be to execute two @code{point-left} functions
2739 (which may be the same function) and/or two @code{point-entered}
2740 functions (which may be the same function). In any case, all the
2741 @code{point-left} functions are called first, followed by all the
2742 @code{point-entered} functions.
2744 It is possible using @code{char-after} to examine characters at various
2745 positions without moving point to those positions. Only an actual
2746 change in the value of point runs these hook functions.
2749 @defvar inhibit-point-motion-hooks
2750 When this variable is non-@code{nil}, @code{point-left} and
2751 @code{point-entered} hooks are not run, and the @code{intangible}
2752 property has no effect. Do not set this variable globally; bind it with
2756 @node Format Properties
2757 @subsection Formatted Text Properties
2759 These text properties affect the behavior of the fill commands. They
2760 are used for representing formatted text. @xref{Filling}, and
2765 If a newline character has this property, it is a ``hard'' newline.
2766 The fill commands do not alter hard newlines and do not move words
2767 across them. However, this property takes effect only if the variable
2768 @code{use-hard-newlines} is non-@code{nil}.
2771 This property specifies an extra right margin for filling this part of the
2775 This property specifies an extra left margin for filling this part of the
2779 This property specifies the style of justification for filling this part
2783 @node Sticky Properties
2784 @subsection Stickiness of Text Properties
2785 @cindex sticky text properties
2786 @cindex inheritance of text properties
2788 Self-inserting characters normally take on the same properties as the
2789 preceding character. This is called @dfn{inheritance} of properties.
2791 In a Lisp program, you can do insertion with inheritance or without,
2792 depending on your choice of insertion primitive. The ordinary text
2793 insertion functions such as @code{insert} do not inherit any properties.
2794 They insert text with precisely the properties of the string being
2795 inserted, and no others. This is correct for programs that copy text
2796 from one context to another---for example, into or out of the kill ring.
2797 To insert with inheritance, use the special primitives described in this
2798 section. Self-inserting characters inherit properties because they work
2799 using these primitives.
2801 When you do insertion with inheritance, @emph{which} properties are
2802 inherited depends on two specific properties: @code{front-sticky} and
2803 @code{rear-nonsticky}.
2805 Insertion after a character inherits those of its properties that are
2806 @dfn{rear-sticky}. Insertion before a character inherits those of its
2807 properties that are @dfn{front-sticky}. By default, a text property is
2808 rear-sticky but not front-sticky. Thus, the default is to inherit all
2809 the properties of the preceding character, and nothing from the
2810 following character. You can request different behavior by specifying
2811 the stickiness of certain properties.
2813 If a character's @code{front-sticky} property is @code{t}, then all
2814 its properties are front-sticky. If the @code{front-sticky} property is
2815 a list, then the sticky properties of the character are those whose
2816 names are in the list. For example, if a character has a
2817 @code{front-sticky} property whose value is @code{(face read-only)},
2818 then insertion before the character can inherit its @code{face} property
2819 and its @code{read-only} property, but no others.
2821 The @code{rear-nonsticky} works the opposite way. Every property is
2822 rear-sticky by default, so the @code{rear-nonsticky} property says which
2823 properties are @emph{not} rear-sticky. If a character's
2824 @code{rear-nonsticky} property is @code{t}, then none of its properties
2825 are rear-sticky. If the @code{rear-nonsticky} property is a list,
2826 properties are rear-sticky @emph{unless} their names are in the list.
2828 When you insert text with inheritance, it inherits all the rear-sticky
2829 properties of the preceding character, and all the front-sticky
2830 properties of the following character. The previous character's
2831 properties take precedence when both sides offer different sticky values
2832 for the same property.
2834 Here are the functions that insert text with inheritance of properties:
2836 @defun insert-and-inherit &rest strings
2837 Insert the strings @var{strings}, just like the function @code{insert},
2838 but inherit any sticky properties from the adjoining text.
2841 @defun insert-before-markers-and-inherit &rest strings
2842 Insert the strings @var{strings}, just like the function
2843 @code{insert-before-markers}, but inherit any sticky properties from the
2847 @xref{Insertion}, for the ordinary insertion functions which do not
2850 @node Saving Properties
2851 @subsection Saving Text Properties in Files
2852 @cindex text properties in files
2853 @cindex saving text properties
2855 You can save text properties in files (along with the text itself),
2856 and restore the same text properties when visiting or inserting the
2857 files, using these two hooks:
2859 @defvar write-region-annotate-functions
2860 This variable's value is a list of functions for @code{write-region} to
2861 run to encode text properties in some fashion as annotations to the text
2862 being written in the file. @xref{Writing to Files}.
2864 Each function in the list is called with two arguments: the start and
2865 end of the region to be written. These functions should not alter the
2866 contents of the buffer. Instead, they should return lists indicating
2867 annotations to write in the file in addition to the text in the
2870 Each function should return a list of elements of the form
2871 @code{(@var{position} . @var{string})}, where @var{position} is an
2872 integer specifying the relative position within the text to be written,
2873 and @var{string} is the annotation to add there.
2875 Each list returned by one of these functions must be already sorted in
2876 increasing order by @var{position}. If there is more than one function,
2877 @code{write-region} merges the lists destructively into one sorted list.
2879 When @code{write-region} actually writes the text from the buffer to the
2880 file, it intermixes the specified annotations at the corresponding
2881 positions. All this takes place without modifying the buffer.
2884 @defvar after-insert-file-functions
2885 This variable holds a list of functions for @code{insert-file-contents}
2886 to call after inserting a file's contents. These functions should scan
2887 the inserted text for annotations, and convert them to the text
2888 properties they stand for.
2890 Each function receives one argument, the length of the inserted text;
2891 point indicates the start of that text. The function should scan that
2892 text for annotations, delete them, and create the text properties that
2893 the annotations specify. The function should return the updated length
2894 of the inserted text, as it stands after those changes. The value
2895 returned by one function becomes the argument to the next function.
2897 These functions should always return with point at the beginning of
2900 The intended use of @code{after-insert-file-functions} is for converting
2901 some sort of textual annotations into actual text properties. But other
2902 uses may be possible.
2905 We invite users to write Lisp programs to store and retrieve text
2906 properties in files, using these hooks, and thus to experiment with
2907 various data formats and find good ones. Eventually we hope users
2908 will produce good, general extensions we can install in Emacs.
2910 We suggest not trying to handle arbitrary Lisp objects as text property
2911 names or values---because a program that general is probably difficult
2912 to write, and slow. Instead, choose a set of possible data types that
2913 are reasonably flexible, and not too hard to encode.
2915 @xref{Format Conversion}, for a related feature.
2917 @c ??? In next edition, merge this info Format Conversion.
2919 @node Lazy Properties
2920 @subsection Lazy Computation of Text Properties
2922 Instead of computing text properties for all the text in the buffer,
2923 you can arrange to compute the text properties for parts of the text
2924 when and if something depends on them.
2926 The primitive that extracts text from the buffer along with its
2927 properties is @code{buffer-substring}. Before examining the properties,
2928 this function runs the abnormal hook @code{buffer-access-fontify-functions}.
2930 @defvar buffer-access-fontify-functions
2931 This variable holds a list of functions for computing text properties.
2932 Before @code{buffer-substring} copies the text and text properties for a
2933 portion of the buffer, it calls all the functions in this list. Each of
2934 the functions receives two arguments that specify the range of the
2935 buffer being accessed. (The buffer itself is always the current
2939 The function @code{buffer-substring-no-properties} does not call these
2940 functions, since it ignores text properties anyway.
2942 In order to prevent the hook functions from being called more than
2943 once for the same part of the buffer, you can use the variable
2944 @code{buffer-access-fontified-property}.
2946 @defvar buffer-access-fontified-property
2947 If this value's variable is non-@code{nil}, it is a symbol which is used
2948 as a text property name. A non-@code{nil} value for that text property
2949 means, ``the other text properties for this character have already been
2952 If all the characters in the range specified for @code{buffer-substring}
2953 have a non-@code{nil} value for this property, @code{buffer-substring}
2954 does not call the @code{buffer-access-fontify-functions} functions. It
2955 assumes these characters already have the right text properties, and
2956 just copies the properties they already have.
2958 The normal way to use this feature is that the
2959 @code{buffer-access-fontify-functions} functions add this property, as
2960 well as others, to the characters they operate on. That way, they avoid
2961 being called over and over for the same text.
2964 @node Clickable Text
2965 @subsection Defining Clickable Text
2966 @cindex clickable text
2968 There are two ways to set up @dfn{clickable text} in a buffer.
2969 There are typically two parts of this: to make the text highlight
2970 when the mouse is over it, and to make a mouse button do something
2971 when you click it on that part of the text.
2973 Highlighting is done with the @code{mouse-face} text property.
2974 Here is an example of how Dired does it:
2978 (if (dired-move-to-filename)
2979 (put-text-property (point)
2981 (dired-move-to-end-of-filename)
2983 'mouse-face 'highlight))
2988 The first two arguments to @code{put-text-property} specify the
2989 beginning and end of the text.
2991 The usual way to make the mouse do something when you click it
2992 on this text is to define @code{mouse-2} in the major mode's
2993 keymap. The job of checking whether the click was on clickable text
2994 is done by the command definition. Here is how Dired does it:
2997 (defun dired-mouse-find-file-other-window (event)
2998 "In dired, visit the file or directory name you click on."
3002 (set-buffer (window-buffer (posn-window (event-end event))))
3004 (goto-char (posn-point (event-end event)))
3005 (setq file (dired-get-filename))))
3006 (select-window (posn-window (event-end event)))
3007 (find-file-other-window (file-name-sans-versions file t))))
3011 The reason for the outer @code{save-excursion} construct is to avoid
3012 changing the current buffer; the reason for the inner one is to avoid
3013 permanently altering point in the buffer you click on. In this case,
3014 Dired uses the function @code{dired-get-filename} to determine which
3015 file to visit, based on the position found in the event.
3017 Instead of defining a mouse command for the major mode, you can define
3018 a key binding for the clickable text itself, using the @code{local-map}
3022 (let ((map (make-sparse-keymap)))
3023 (define-key-binding map [mouse-2] 'operate-this-button)
3024 (put-text-property (point)
3026 (dired-move-to-end-of-filename)
3032 This method makes it possible to define different commands for various
3033 clickable pieces of text. Also, the major mode definition (or the
3034 global definition) remains available for the rest of the text in the
3038 @subsection Why Text Properties are not Intervals
3041 Some editors that support adding attributes to text in the buffer do
3042 so by letting the user specify ``intervals'' within the text, and adding
3043 the properties to the intervals. Those editors permit the user or the
3044 programmer to determine where individual intervals start and end. We
3045 deliberately provided a different sort of interface in Emacs Lisp to
3046 avoid certain paradoxical behavior associated with text modification.
3048 If the actual subdivision into intervals is meaningful, that means you
3049 can distinguish between a buffer that is just one interval with a
3050 certain property, and a buffer containing the same text subdivided into
3051 two intervals, both of which have that property.
3053 Suppose you take the buffer with just one interval and kill part of
3054 the text. The text remaining in the buffer is one interval, and the
3055 copy in the kill ring (and the undo list) becomes a separate interval.
3056 Then if you yank back the killed text, you get two intervals with the
3057 same properties. Thus, editing does not preserve the distinction
3058 between one interval and two.
3060 Suppose we ``fix'' this problem by coalescing the two intervals when
3061 the text is inserted. That works fine if the buffer originally was a
3062 single interval. But suppose instead that we have two adjacent
3063 intervals with the same properties, and we kill the text of one interval
3064 and yank it back. The same interval-coalescence feature that rescues
3065 the other case causes trouble in this one: after yanking, we have just
3066 one interval. One again, editing does not preserve the distinction
3067 between one interval and two.
3069 Insertion of text at the border between intervals also raises
3070 questions that have no satisfactory answer.
3072 However, it is easy to arrange for editing to behave consistently for
3073 questions of the form, ``What are the properties of this character?''
3074 So we have decided these are the only questions that make sense; we have
3075 not implemented asking questions about where intervals start or end.
3077 In practice, you can usually use the text property search functions in
3078 place of explicit interval boundaries. You can think of them as finding
3079 the boundaries of intervals, assuming that intervals are always
3080 coalesced whenever possible. @xref{Property Search}.
3082 Emacs also provides explicit intervals as a presentation feature; see
3086 @section Substituting for a Character Code
3088 The following functions replace characters within a specified region
3089 based on their character codes.
3091 @defun subst-char-in-region start end old-char new-char &optional noundo
3092 @cindex replace characters
3093 This function replaces all occurrences of the character @var{old-char}
3094 with the character @var{new-char} in the region of the current buffer
3095 defined by @var{start} and @var{end}.
3097 @cindex Outline mode
3098 @cindex undo avoidance
3099 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
3100 not record the change for undo and does not mark the buffer as modified.
3101 This feature is used for controlling selective display (@pxref{Selective
3104 @code{subst-char-in-region} does not move point and returns
3109 ---------- Buffer: foo ----------
3110 This is the contents of the buffer before.
3111 ---------- Buffer: foo ----------
3115 (subst-char-in-region 1 20 ?i ?X)
3118 ---------- Buffer: foo ----------
3119 ThXs Xs the contents of the buffer before.
3120 ---------- Buffer: foo ----------
3125 @defun translate-region start end table
3126 This function applies a translation table to the characters in the
3127 buffer between positions @var{start} and @var{end}.
3129 The translation table @var{table} is a string; @code{(aref @var{table}
3130 @var{ochar})} gives the translated character corresponding to
3131 @var{ochar}. If the length of @var{table} is less than 256, any
3132 characters with codes larger than the length of @var{table} are not
3133 altered by the translation.
3135 The return value of @code{translate-region} is the number of
3136 characters that were actually changed by the translation. This does
3137 not count characters that were mapped into themselves in the
3145 A register is a sort of variable used in Emacs editing that can hold a
3146 variety of different kinds of values. Each register is named by a
3147 single character. All ASCII characters and their meta variants (but
3148 with the exception of @kbd{C-g}) can be used to name registers. Thus,
3149 there are 255 possible registers. A register is designated in Emacs
3150 Lisp by the character that is its name.
3152 @defvar register-alist
3153 This variable is an alist of elements of the form @code{(@var{name} .
3154 @var{contents})}. Normally, there is one element for each Emacs
3155 register that has been used.
3157 The object @var{name} is a character (an integer) identifying the
3161 The @var{contents} of a register can have several possible types:
3165 A number stands for itself. If @code{insert-register} finds a number
3166 in the register, it converts the number to decimal.
3169 A marker represents a buffer position to jump to.
3172 A string is text saved in the register.
3175 A rectangle is represented by a list of strings.
3177 @item @code{(@var{window-configuration} @var{position})}
3178 This represents a window configuration to restore in one frame, and a
3179 position to jump to in the current buffer.
3181 @item @code{(@var{frame-configuration} @var{position})}
3182 This represents a frame configuration to restore, and a position
3183 to jump to in the current buffer.
3185 @item (file @var{filename})
3186 This represents a file to visit; jumping to this value visits file
3189 @item (file-query @var{filename} @var{position})
3190 This represents a file to visit and a position in it; jumping to this
3191 value visits file @var{filename} and goes to buffer position
3192 @var{position}. Restoring this type of position asks the user for
3196 The functions in this section return unpredictable values unless
3199 @defun get-register reg
3200 This function returns the contents of the register
3201 @var{reg}, or @code{nil} if it has no contents.
3204 @defun set-register reg value
3205 This function sets the contents of register @var{reg} to @var{value}.
3206 A register can be set to any value, but the other register functions
3207 expect only certain data types. The return value is @var{value}.
3210 @deffn Command view-register reg
3211 This command displays what is contained in register @var{reg}.
3215 @deffn Command point-to-register reg
3216 This command stores both the current location of point and the current
3217 buffer in register @var{reg} as a marker.
3220 @deffn Command jump-to-register reg
3221 @deffnx Command register-to-point reg
3222 @comment !!SourceFile register.el
3223 This command restores the status recorded in register @var{reg}.
3225 If @var{reg} contains a marker, it moves point to the position stored in
3226 the marker. Since both the buffer and the location within the buffer
3227 are stored by the @code{point-to-register} function, this command can
3228 switch you to another buffer.
3230 If @var{reg} contains a window configuration or a frame configuration.
3231 @code{jump-to-register} restores that configuration.
3235 @deffn Command insert-register reg &optional beforep
3236 This command inserts contents of register @var{reg} into the current
3239 Normally, this command puts point before the inserted text, and the
3240 mark after it. However, if the optional second argument @var{beforep}
3241 is non-@code{nil}, it puts the mark before and point after.
3242 You can pass a non-@code{nil} second argument @var{beforep} to this
3243 function interactively by supplying any prefix argument.
3245 If the register contains a rectangle, then the rectangle is inserted
3246 with its upper left corner at point. This means that text is inserted
3247 in the current line and underneath it on successive lines.
3249 If the register contains something other than saved text (a string) or
3250 a rectangle (a list), currently useless things happen. This may be
3251 changed in the future.
3255 @deffn Command copy-to-register reg start end &optional delete-flag
3256 This command copies the region from @var{start} to @var{end} into
3257 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
3258 the region from the buffer after copying it into the register.
3261 @deffn Command prepend-to-register reg start end &optional delete-flag
3262 This command prepends the region from @var{start} to @var{end} into
3263 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
3264 the region from the buffer after copying it to the register.
3267 @deffn Command append-to-register reg start end &optional delete-flag
3268 This command appends the region from @var{start} to @var{end} to the
3269 text already in register @var{reg}. If @var{delete-flag} is
3270 non-@code{nil}, it deletes the region from the buffer after copying it
3274 @deffn Command copy-rectangle-to-register reg start end &optional delete-flag
3275 This command copies a rectangular region from @var{start} to @var{end}
3276 into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it
3277 deletes the region from the buffer after copying it to the register.
3280 @deffn Command window-configuration-to-register reg
3281 This function stores the window configuration of the selected frame in
3285 @deffn Command frame-configuration-to-register reg
3286 This function stores the current frame configuration in register
3292 @section Transposition of Text
3294 This subroutine is used by the transposition commands.
3296 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
3297 This function exchanges two nonoverlapping portions of the buffer.
3298 Arguments @var{start1} and @var{end1} specify the bounds of one portion
3299 and arguments @var{start2} and @var{end2} specify the bounds of the
3302 Normally, @code{transpose-regions} relocates markers with the transposed
3303 text; a marker previously positioned within one of the two transposed
3304 portions moves along with that portion, thus remaining between the same
3305 two characters in their new position. However, if @var{leave-markers}
3306 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
3307 all markers unrelocated.
3311 @section Base 64 Encoding
3312 @cindex base 64 encoding
3314 Base 64 code is used in email to encode a sequence of 8-bit bytes as a
3315 longer sequence of @sc{ascii} graphic characters. This section
3316 describes the functions for converting to and from this code.
3318 @defun base64-encode-region beg end &optional no-line-break
3319 @tindex base64-encode-region
3320 This function converts the region from @var{beg} to @var{end}
3321 into base 64 code. It returns the length of the encoded text.
3323 Normally, this function inserts newline characters into the encoded
3324 text, to avoid overlong lines. However, if the optional argument
3325 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
3326 the output is just one long line.
3329 @defun base64-encode-string string &optional no-line-break
3330 @tindex base64-encode-string
3331 This function converts the string @var{string} into base 64 code. It
3332 returns a string containing the encoded text.
3334 Normally, this function inserts newline characters into the encoded
3335 text, to avoid overlong lines. However, if the optional argument
3336 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
3337 the result string is just one long line.
3340 @defun base64-decode-region beg end
3341 @tindex base64-decode-region
3342 This function converts the region from @var{beg} to @var{end} from base
3343 64 code into the corresponding decoded text. It returns the length of
3346 The decoding functions ignore newline characters in the encoded text.
3349 @defun base64-decode-string string
3350 @tindex base64-decode-string
3351 This function converts the string @var{string} from base 64 code into
3352 the corresponding decoded text. It returns a string containing the
3355 The decoding functions ignore newline characters in the encoded text.
3359 @section Change Hooks
3360 @cindex change hooks
3361 @cindex hooks for text changes
3363 These hook variables let you arrange to take notice of all changes in
3364 all buffers (or in a particular buffer, if you make them buffer-local).
3365 See also @ref{Special Properties}, for how to detect changes to specific
3368 The functions you use in these hooks should save and restore the match
3369 data if they do anything that uses regular expressions; otherwise, they
3370 will interfere in bizarre ways with the editing operations that call
3373 @defvar before-change-functions
3374 This variable holds a list of functions to call before any buffer
3375 modification. Each function gets two arguments, the beginning and end
3376 of the region that is about to change, represented as integers. The
3377 buffer that is about to change is always the current buffer.
3380 @defvar after-change-functions
3381 This variable holds a list of functions to call after any buffer
3382 modification. Each function receives three arguments: the beginning and
3383 end of the region just changed, and the length of the text that existed
3384 before the change. All three arguments are integers. The buffer that's
3385 about to change is always the current buffer.
3387 The length of the old text is the difference between the buffer positions
3388 before and after that text as it was before the change. As for the
3389 changed text, its length is simply the difference between the first two
3393 @defmac combine-after-change-calls body...
3394 @tindex combine-after-change-calls
3395 The macro executes @var{body} normally, but arranges to call the
3396 after-change functions just once for a series of several changes---if
3399 If a program makes several text changes in the same area of the buffer,
3400 using the macro @code{combine-after-change-calls} around that part of
3401 the program can make it run considerably faster when after-change hooks
3402 are in use. When the after-change hooks are ultimately called, the
3403 arguments specify a portion of the buffer including all of the changes
3404 made within the @code{combine-after-change-calls} body.
3406 @strong{Warning:} You must not alter the values of
3407 @code{after-change-functions} and @code{after-change-function} within
3408 the body of a @code{combine-after-change-calls} form.
3410 @strong{Note:} If the changes you combine occur in widely scattered
3411 parts of the buffer, this will still work, but it is not advisable,
3412 because it may lead to inefficient behavior for some change hook
3416 @defvar before-change-function
3417 This obsolete variable holds one function to call before any buffer
3418 modification (or @code{nil} for no function). It is called just like
3419 the functions in @code{before-change-functions}.
3422 @defvar after-change-function
3423 This obsolete variable holds one function to call after any buffer modification
3424 (or @code{nil} for no function). It is called just like the functions in
3425 @code{after-change-functions}.
3428 The four variables above are temporarily bound to @code{nil} during the
3429 time that any of these functions is running. This means that if one of
3430 these functions changes the buffer, that change won't run these
3431 functions. If you do want a hook function to make changes that run
3432 these functions, make it bind these variables back to their usual
3435 One inconvenient result of this protective feature is that you cannot
3436 have a function in @code{after-change-functions} or
3437 @code{before-change-functions} which changes the value of that variable.
3438 But that's not a real limitation. If you want those functions to change
3439 the list of functions to run, simply add one fixed function to the hook,
3440 and code that function to look in another variable for other functions
3441 to call. Here is an example:
3444 (setq my-own-after-change-functions nil)
3445 (defun indirect-after-change-function (beg end len)
3446 (let ((list my-own-after-change-functions))
3448 (funcall (car list) beg end len)
3449 (setq list (cdr list)))))
3452 (add-hooks 'after-change-functions
3453 'indirect-after-change-function)
3457 @defvar first-change-hook
3458 This variable is a normal hook that is run whenever a buffer is changed
3459 that was previously in the unmodified state.
3462 @defvar inhibit-modification-hooks
3463 @tindex inhibit-modification-hooks
3464 If this variable is non-@code{nil}, all of the change hooks are
3465 disabled; none of them run. This affects all the hook variables
3466 described above in this section, as well as the hooks attached to
3467 certain special text properties (@pxref{Special Properties}) and overlay
3468 properties (@pxref{Overlay Properties}).
3470 This variable is available starting in Emacs 21.