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
225 @defun thing-at-point thing
226 Return the @var{thing} around or next to point, as a string.
228 The argument @var{thing} is a symbol which specifies a kind of syntactic
229 entity. Possibilities include @code{symbol}, @code{list}, @code{sexp},
230 @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
231 @code{whitespace}, @code{line}, @code{page}, and others.
234 ---------- Buffer: foo ----------
235 Gentlemen may cry ``Pea@point{}ce! Peace!,''
236 but there is no peace.
237 ---------- Buffer: foo ----------
239 (thing-at-point 'word)
241 (thing-at-point 'line)
242 @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
243 (thing-at-point 'whitespace)
249 @section Comparing Text
250 @cindex comparing buffer text
252 This function lets you compare portions of the text in a buffer, without
253 copying them into strings first.
255 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
256 This function lets you compare two substrings of the same buffer or two
257 different buffers. The first three arguments specify one substring,
258 giving a buffer and two positions within the buffer. The last three
259 arguments specify the other substring in the same way. You can use
260 @code{nil} for @var{buffer1}, @var{buffer2}, or both to stand for the
263 The value is negative if the first substring is less, positive if the
264 first is greater, and zero if they are equal. The absolute value of
265 the result is one plus the index of the first differing characters
266 within the substrings.
268 This function ignores case when comparing characters
269 if @code{case-fold-search} is non-@code{nil}. It always ignores
272 Suppose the current buffer contains the text @samp{foobarbar
273 haha!rara!}; then in this example the two substrings are @samp{rbar }
274 and @samp{rara!}. The value is 2 because the first substring is greater
275 at the second character.
278 (compare-buffer-substring nil 6 11 nil 16 21)
284 @section Inserting Text
285 @cindex insertion of text
286 @cindex text insertion
288 @cindex insertion before point
289 @cindex before point, insertion
290 @dfn{Insertion} means adding new text to a buffer. The inserted text
291 goes at point---between the character before point and the character
292 after point. Some insertion functions leave point before the inserted
293 text, while other functions leave it after. We call the former
294 insertion @dfn{after point} and the latter insertion @dfn{before point}.
296 Insertion relocates markers that point at positions after the
297 insertion point, so that they stay with the surrounding text
298 (@pxref{Markers}). When a marker points at the place of insertion,
299 insertion may or may not relocate the marker, depending on the marker's
300 insertion type (@pxref{Marker Insertion Types}). Certain special
301 functions such as @code{insert-before-markers} relocate all such markers
302 to point after the inserted text, regardless of the markers' insertion
305 Insertion functions signal an error if the current buffer is
308 These functions copy text characters from strings and buffers along
309 with their properties. The inserted characters have exactly the same
310 properties as the characters they were copied from. By contrast,
311 characters specified as separate arguments, not part of a string or
312 buffer, inherit their text properties from the neighboring text.
314 The insertion functions convert text from unibyte to multibyte in
315 order to insert in a multibyte buffer, and vice versa---if the text
316 comes from a string or from a buffer. However, they do not convert
317 unibyte character codes 128 through 255 to multibyte characters, not
318 even if the current buffer is a multibyte buffer. @xref{Converting
321 @defun insert &rest args
322 This function inserts the strings and/or characters @var{args} into the
323 current buffer, at point, moving point forward. In other words, it
324 inserts the text before point. An error is signaled unless all
325 @var{args} are either strings or characters. The value is @code{nil}.
328 @defun insert-before-markers &rest args
329 This function inserts the strings and/or characters @var{args} into the
330 current buffer, at point, moving point forward. An error is signaled
331 unless all @var{args} are either strings or characters. The value is
334 This function is unlike the other insertion functions in that it
335 relocates markers initially pointing at the insertion point, to point
336 after the inserted text. If an overlay begins the insertion point, the
337 inserted text falls outside the overlay; if a nonempty overlay ends at
338 the insertion point, the inserted text falls inside that overlay.
341 @defun insert-char character &optional count inherit
342 This function inserts @var{count} instances of @var{character} into the
343 current buffer before point. The argument @var{count} should be a
344 number (@code{nil} means 1), and @var{character} must be a character.
345 The value is @code{nil}.
347 This function does not convert unibyte character codes 128 through 255
348 to multibyte characters, not even if the current buffer is a multibyte
349 buffer. @xref{Converting Representations}.
351 If @var{inherit} is non-@code{nil}, then the inserted characters inherit
352 sticky text properties from the two characters before and after the
353 insertion point. @xref{Sticky Properties}.
356 @defun insert-buffer-substring from-buffer-or-name &optional start end
357 This function inserts a portion of buffer @var{from-buffer-or-name}
358 (which must already exist) into the current buffer before point. The
359 text inserted is the region from @var{start} and @var{end}. (These
360 arguments default to the beginning and end of the accessible portion of
361 that buffer.) This function returns @code{nil}.
363 In this example, the form is executed with buffer @samp{bar} as the
364 current buffer. We assume that buffer @samp{bar} is initially empty.
368 ---------- Buffer: foo ----------
369 We hold these truths to be self-evident, that all
370 ---------- Buffer: foo ----------
374 (insert-buffer-substring "foo" 1 20)
377 ---------- Buffer: bar ----------
378 We hold these truth@point{}
379 ---------- Buffer: bar ----------
384 @xref{Sticky Properties}, for other insertion functions that inherit
385 text properties from the nearby text in addition to inserting it.
386 Whitespace inserted by indentation functions also inherits text
389 @node Commands for Insertion
390 @section User-Level Insertion Commands
392 This section describes higher-level commands for inserting text,
393 commands intended primarily for the user but useful also in Lisp
396 @deffn Command insert-buffer from-buffer-or-name
397 This command inserts the entire contents of @var{from-buffer-or-name}
398 (which must exist) into the current buffer after point. It leaves
399 the mark after the inserted text. The value is @code{nil}.
402 @deffn Command self-insert-command count
403 @cindex character insertion
404 @cindex self-insertion
405 This command inserts the last character typed; it does so @var{count}
406 times, before point, and returns @code{nil}. Most printing characters
407 are bound to this command. In routine use, @code{self-insert-command}
408 is the most frequently called function in Emacs, but programs rarely use
409 it except to install it on a keymap.
411 In an interactive call, @var{count} is the numeric prefix argument.
413 This command calls @code{auto-fill-function} whenever that is
414 non-@code{nil} and the character inserted is a space or a newline
415 (@pxref{Auto Filling}).
417 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
418 This command performs abbrev expansion if Abbrev mode is enabled and
419 the inserted character does not have word-constituent
420 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
422 This is also responsible for calling @code{blink-paren-function} when
423 the inserted character has close parenthesis syntax (@pxref{Blinking}).
426 @deffn Command newline &optional number-of-newlines
427 This command inserts newlines into the current buffer before point.
428 If @var{number-of-newlines} is supplied, that many newline characters
431 @cindex newline and Auto Fill mode
432 This function calls @code{auto-fill-function} if the current column
433 number is greater than the value of @code{fill-column} and
434 @var{number-of-newlines} is @code{nil}. Typically what
435 @code{auto-fill-function} does is insert a newline; thus, the overall
436 result in this case is to insert two newlines at different places: one
437 at point, and another earlier in the line. @code{newline} does not
438 auto-fill if @var{number-of-newlines} is non-@code{nil}.
440 This command indents to the left margin if that is not zero.
443 The value returned is @code{nil}. In an interactive call, @var{count}
444 is the numeric prefix argument.
447 @deffn Command split-line
448 This command splits the current line, moving the portion of the line
449 after point down vertically so that it is on the next line directly
450 below where it was before. Whitespace is inserted as needed at the
451 beginning of the lower line, using the @code{indent-to} function.
452 @code{split-line} returns the position of point.
454 Programs hardly ever use this function.
457 @defvar overwrite-mode
458 This variable controls whether overwrite mode is in effect. The value
459 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
460 or @code{nil}. @code{overwrite-mode-textual} specifies textual
461 overwrite mode (treats newlines and tabs specially), and
462 @code{overwrite-mode-binary} specifies binary overwrite mode (treats
463 newlines and tabs like any other characters).
467 @section Deleting Text
469 @cindex deletion vs killing
470 Deletion means removing part of the text in a buffer, without saving
471 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
472 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
473 Some deletion functions do save text in the kill ring in some special
476 All of the deletion functions operate on the current buffer, and all
477 return a value of @code{nil}.
479 @deffn Command erase-buffer
480 This function deletes the entire text of the current buffer, leaving it
481 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
482 error. Otherwise, it deletes the text without asking for any
483 confirmation. It returns @code{nil}.
485 Normally, deleting a large amount of text from a buffer inhibits further
486 auto-saving of that buffer ``because it has shrunk''. However,
487 @code{erase-buffer} does not do this, the idea being that the future
488 text is not really related to the former text, and its size should not
489 be compared with that of the former text.
492 @deffn Command delete-region start end
493 This command deletes the text in the current buffer in the region
494 defined by @var{start} and @var{end}. The value is @code{nil}. If
495 point was inside the deleted region, its value afterward is @var{start}.
496 Otherwise, point relocates with the surrounding text, as markers do.
499 @deffn Command delete-char count &optional killp
500 This command deletes @var{count} characters directly after point, or
501 before point if @var{count} is negative. If @var{killp} is
502 non-@code{nil}, then it saves the deleted characters in the kill ring.
504 In an interactive call, @var{count} is the numeric prefix argument, and
505 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
506 argument is supplied, the text is saved in the kill ring. If no prefix
507 argument is supplied, then one character is deleted, but not saved in
510 The value returned is always @code{nil}.
513 @deffn Command delete-backward-char count &optional killp
514 @cindex delete previous char
515 This command deletes @var{count} characters directly before point, or
516 after point if @var{count} is negative. If @var{killp} is
517 non-@code{nil}, then it saves the deleted characters in the kill ring.
519 In an interactive call, @var{count} is the numeric prefix argument, and
520 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
521 argument is supplied, the text is saved in the kill ring. If no prefix
522 argument is supplied, then one character is deleted, but not saved in
525 The value returned is always @code{nil}.
528 @deffn Command backward-delete-char-untabify count &optional killp
530 This command deletes @var{count} characters backward, changing tabs
531 into spaces. When the next character to be deleted is a tab, it is
532 first replaced with the proper number of spaces to preserve alignment
533 and then one of those spaces is deleted instead of the tab. If
534 @var{killp} is non-@code{nil}, then the command saves the deleted
535 characters in the kill ring.
537 Conversion of tabs to spaces happens only if @var{count} is positive.
538 If it is negative, exactly @minus{}@var{count} characters after point
541 In an interactive call, @var{count} is the numeric prefix argument, and
542 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
543 argument is supplied, the text is saved in the kill ring. If no prefix
544 argument is supplied, then one character is deleted, but not saved in
547 The value returned is always @code{nil}.
550 @defopt backward-delete-char-untabify-method
551 @tindex backward-delete-char-untabify-method
552 This option specifies how @code{backward-delete-char-untabify} should
553 deal with whitespace. Possible values include @code{untabify}, the
554 default, meaning convert a tab to many spaces and delete one;
555 @code{hungry}, meaning delete all the whitespace characters before point
556 with one command, and @code{nil}, meaning do nothing special for
557 whitespace characters.
560 @node User-Level Deletion
561 @section User-Level Deletion Commands
563 This section describes higher-level commands for deleting text,
564 commands intended primarily for the user but useful also in Lisp
567 @deffn Command delete-horizontal-space
568 @cindex deleting whitespace
569 This function deletes all spaces and tabs around point. It returns
572 In the following examples, we call @code{delete-horizontal-space} four
573 times, once on each line, with point between the second and third
574 characters on the line each time.
578 ---------- Buffer: foo ----------
583 ---------- Buffer: foo ----------
587 (delete-horizontal-space) ; @r{Four times.}
590 ---------- Buffer: foo ----------
595 ---------- Buffer: foo ----------
600 @deffn Command delete-indentation &optional join-following-p
601 This function joins the line point is on to the previous line, deleting
602 any whitespace at the join and in some cases replacing it with one
603 space. If @var{join-following-p} is non-@code{nil},
604 @code{delete-indentation} joins this line to the following line
605 instead. The function returns @code{nil}.
607 If there is a fill prefix, and the second of the lines being joined
608 starts with the prefix, then @code{delete-indentation} deletes the
609 fill prefix before joining the lines. @xref{Margins}.
611 In the example below, point is located on the line starting
612 @samp{events}, and it makes no difference if there are trailing spaces
613 in the preceding line.
617 ---------- Buffer: foo ----------
618 When in the course of human
619 @point{} events, it becomes necessary
620 ---------- Buffer: foo ----------
627 ---------- Buffer: foo ----------
628 When in the course of human@point{} events, it becomes necessary
629 ---------- Buffer: foo ----------
633 After the lines are joined, the function @code{fixup-whitespace} is
634 responsible for deciding whether to leave a space at the junction.
637 @defun fixup-whitespace
638 This function replaces all the whitespace surrounding point with either
639 one space or no space, according to the context. It returns @code{nil}.
641 At the beginning or end of a line, the appropriate amount of space is
642 none. Before a character with close parenthesis syntax, or after a
643 character with open parenthesis or expression-prefix syntax, no space is
644 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
647 In the example below, @code{fixup-whitespace} is called the first time
648 with point before the word @samp{spaces} in the first line. For the
649 second invocation, point is directly after the @samp{(}.
653 ---------- Buffer: foo ----------
654 This has too many @point{}spaces
655 This has too many spaces at the start of (@point{} this list)
656 ---------- Buffer: foo ----------
667 ---------- Buffer: foo ----------
668 This has too many spaces
669 This has too many spaces at the start of (this list)
670 ---------- Buffer: foo ----------
675 @deffn Command just-one-space
676 @comment !!SourceFile simple.el
677 This command replaces any spaces and tabs around point with a single
678 space. It returns @code{nil}.
681 @deffn Command delete-blank-lines
682 This function deletes blank lines surrounding point. If point is on a
683 blank line with one or more blank lines before or after it, then all but
684 one of them are deleted. If point is on an isolated blank line, then it
685 is deleted. If point is on a nonblank line, the command deletes all
686 blank lines following it.
688 A blank line is defined as a line containing only tabs and spaces.
690 @code{delete-blank-lines} returns @code{nil}.
694 @section The Kill Ring
697 @dfn{Kill functions} delete text like the deletion functions, but save
698 it so that the user can reinsert it by @dfn{yanking}. Most of these
699 functions have @samp{kill-} in their name. By contrast, the functions
700 whose names start with @samp{delete-} normally do not save text for
701 yanking (though they can still be undone); these are ``deletion''
704 Most of the kill commands are primarily for interactive use, and are
705 not described here. What we do describe are the functions provided for
706 use in writing such commands. You can use these functions to write
707 commands for killing text. When you need to delete text for internal
708 purposes within a Lisp function, you should normally use deletion
709 functions, so as not to disturb the kill ring contents.
712 Killed text is saved for later yanking in the @dfn{kill ring}. This
713 is a list that holds a number of recent kills, not just the last text
714 kill. We call this a ``ring'' because yanking treats it as having
715 elements in a cyclic order. The list is kept in the variable
716 @code{kill-ring}, and can be operated on with the usual functions for
717 lists; there are also specialized functions, described in this section,
718 that treat it as a ring.
720 Some people think this use of the word ``kill'' is unfortunate, since
721 it refers to operations that specifically @emph{do not} destroy the
722 entities ``killed''. This is in sharp contrast to ordinary life, in
723 which death is permanent and ``killed'' entities do not come back to
724 life. Therefore, other metaphors have been proposed. For example, the
725 term ``cut ring'' makes sense to people who, in pre-computer days, used
726 scissors and paste to cut up and rearrange manuscripts. However, it
727 would be difficult to change the terminology now.
730 * Kill Ring Concepts:: What text looks like in the kill ring.
731 * Kill Functions:: Functions that kill text.
732 * Yank Commands:: Commands that access the kill ring.
733 * Low-Level Kill Ring:: Functions and variables for kill ring access.
734 * Internals of Kill Ring:: Variables that hold kill-ring data.
737 @node Kill Ring Concepts
738 @comment node-name, next, previous, up
739 @subsection Kill Ring Concepts
741 The kill ring records killed text as strings in a list, most recent
742 first. A short kill ring, for example, might look like this:
745 ("some text" "a different piece of text" "even older text")
749 When the list reaches @code{kill-ring-max} entries in length, adding a
750 new entry automatically deletes the last entry.
752 When kill commands are interwoven with other commands, each kill
753 command makes a new entry in the kill ring. Multiple kill commands in
754 succession build up a single kill-ring entry, which would be yanked as a
755 unit; the second and subsequent consecutive kill commands add text to
756 the entry made by the first one.
758 For yanking, one entry in the kill ring is designated the ``front'' of
759 the ring. Some yank commands ``rotate'' the ring by designating a
760 different element as the ``front.'' But this virtual rotation doesn't
761 change the list itself---the most recent entry always comes first in the
765 @comment node-name, next, previous, up
766 @subsection Functions for Killing
768 @code{kill-region} is the usual subroutine for killing text. Any
769 command that calls this function is a ``kill command'' (and should
770 probably have @samp{kill} in its name). @code{kill-region} puts the
771 newly killed text in a new element at the beginning of the kill ring or
772 adds it to the most recent element. It determines automatically (using
773 @code{last-command}) whether the previous command was a kill command,
774 and if so appends the killed text to the most recent entry.
776 @deffn Command kill-region start end
777 This function kills the text in the region defined by @var{start} and
778 @var{end}. The text is deleted but saved in the kill ring, along with
779 its text properties. The value is always @code{nil}.
781 In an interactive call, @var{start} and @var{end} are point and
785 If the buffer is read-only, @code{kill-region} modifies the kill ring
786 just the same, then signals an error without modifying the buffer. This
787 is convenient because it lets the user use all the kill commands to copy
788 text into the kill ring from a read-only buffer.
791 @defopt kill-read-only-ok
792 If this option is non-@code{nil}, @code{kill-region} does not get an
793 error if the buffer is read-only. Instead, it simply returns, updating
794 the kill ring but not changing the buffer.
797 @deffn Command copy-region-as-kill start end
798 This command saves the region defined by @var{start} and @var{end} on
799 the kill ring (including text properties), but does not delete the text
800 from the buffer. It returns @code{nil}. It also indicates the extent
801 of the text copied by moving the cursor momentarily, or by displaying a
802 message in the echo area.
804 The command does not set @code{this-command} to @code{kill-region}, so a
805 subsequent kill command does not append to the same kill ring entry.
807 Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
808 support Emacs 18. For newer Emacs versions, it is better to use
809 @code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill
814 @comment node-name, next, previous, up
815 @subsection Functions for Yanking
817 @dfn{Yanking} means reinserting an entry of previously killed text
818 from the kill ring. The text properties are copied too.
820 @deffn Command yank &optional arg
821 @cindex inserting killed text
822 This command inserts before point the text in the first entry in the
823 kill ring. It positions the mark at the beginning of that text, and
826 If @var{arg} is a list (which occurs interactively when the user
827 types @kbd{C-u} with no digits), then @code{yank} inserts the text as
828 described above, but puts point before the yanked text and puts the mark
831 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most
832 recently killed text---the @var{arg}th element of the kill ring list.
834 @code{yank} does not alter the contents of the kill ring or rotate it.
835 It returns @code{nil}.
838 @deffn Command yank-pop arg
839 This command replaces the just-yanked entry from the kill ring with a
840 different entry from the kill ring.
842 This is allowed only immediately after a @code{yank} or another
843 @code{yank-pop}. At such a time, the region contains text that was just
844 inserted by yanking. @code{yank-pop} deletes that text and inserts in
845 its place a different piece of killed text. It does not add the deleted
846 text to the kill ring, since it is already in the kill ring somewhere.
848 If @var{arg} is @code{nil}, then the replacement text is the previous
849 element of the kill ring. If @var{arg} is numeric, the replacement is
850 the @var{arg}th previous kill. If @var{arg} is negative, a more recent
851 kill is the replacement.
853 The sequence of kills in the kill ring wraps around, so that after the
854 oldest one comes the newest one, and before the newest one goes the
857 The return value is always @code{nil}.
860 @node Low-Level Kill Ring
861 @subsection Low-Level Kill Ring
863 These functions and variables provide access to the kill ring at a
864 lower level, but still convenient for use in Lisp programs, because they
865 take care of interaction with window system selections
866 (@pxref{Window System Selections}).
868 @defun current-kill n &optional do-not-move
869 The function @code{current-kill} rotates the yanking pointer, which
870 designates the ``front'' of the kill ring, by @var{n} places (from newer
871 kills to older ones), and returns the text at that place in the ring.
873 If the optional second argument @var{do-not-move} is non-@code{nil},
874 then @code{current-kill} doesn't alter the yanking pointer; it just
875 returns the @var{n}th kill, counting from the current yanking pointer.
877 If @var{n} is zero, indicating a request for the latest kill,
878 @code{current-kill} calls the value of
879 @code{interprogram-paste-function} (documented below) before consulting
883 @defun kill-new string
884 This function puts the text @var{string} into the kill ring as a new
885 entry at the front of the ring. It discards the oldest entry if
886 appropriate. It also invokes the value of
887 @code{interprogram-cut-function} (see below).
890 @defun kill-append string before-p
891 This function appends the text @var{string} to the first entry in the
892 kill ring. Normally @var{string} goes at the end of the entry, but if
893 @var{before-p} is non-@code{nil}, it goes at the beginning. This
894 function also invokes the value of @code{interprogram-cut-function} (see
898 @defvar interprogram-paste-function
899 This variable provides a way of transferring killed text from other
900 programs, when you are using a window system. Its value should be
901 @code{nil} or a function of no arguments.
903 If the value is a function, @code{current-kill} calls it to get the
904 ``most recent kill''. If the function returns a non-@code{nil} value,
905 then that value is used as the ``most recent kill''. If it returns
906 @code{nil}, then the first element of @code{kill-ring} is used.
908 The normal use of this hook is to get the window system's primary
909 selection as the most recent kill, even if the selection belongs to
910 another application. @xref{Window System Selections}.
913 @defvar interprogram-cut-function
914 This variable provides a way of communicating killed text to other
915 programs, when you are using a window system. Its value should be
916 @code{nil} or a function of one argument.
918 If the value is a function, @code{kill-new} and @code{kill-append} call
919 it with the new first element of the kill ring as an argument.
921 The normal use of this hook is to set the window system's primary
922 selection from the newly killed text. @xref{Window System Selections}.
925 @node Internals of Kill Ring
926 @comment node-name, next, previous, up
927 @subsection Internals of the Kill Ring
929 The variable @code{kill-ring} holds the kill ring contents, in the
930 form of a list of strings. The most recent kill is always at the front
933 The @code{kill-ring-yank-pointer} variable points to a link in the
934 kill ring list, whose @sc{car} is the text to yank next. We say it
935 identifies the ``front'' of the ring. Moving
936 @code{kill-ring-yank-pointer} to a different link is called
937 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
938 the functions that move the yank pointer wrap around from the end of the
939 list to the beginning, or vice-versa. Rotation of the kill ring is
940 virtual; it does not change the value of @code{kill-ring}.
942 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
943 variables whose values are normally lists. The word ``pointer'' in the
944 name of the @code{kill-ring-yank-pointer} indicates that the variable's
945 purpose is to identify one element of the list for use by the next yank
948 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
949 of the links in the kill ring list. The element it identifies is the
950 @sc{car} of that link. Kill commands, which change the kill ring, also
951 set this variable to the value of @code{kill-ring}. The effect is to
952 rotate the ring so that the newly killed text is at the front.
954 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
955 pointing to the second entry in the kill ring @code{("some text" "a
956 different piece of text" "yet older text")}.
960 kill-ring ---- kill-ring-yank-pointer
963 | --- --- --- --- --- ---
964 --> | | |------> | | |--> | | |--> nil
965 --- --- --- --- --- ---
968 | | -->"yet older text"
970 | --> "a different piece of text"
977 This state of affairs might occur after @kbd{C-y} (@code{yank})
978 immediately followed by @kbd{M-y} (@code{yank-pop}).
981 This variable holds the list of killed text sequences, most recently
985 @defvar kill-ring-yank-pointer
986 This variable's value indicates which element of the kill ring is at the
987 ``front'' of the ring for yanking. More precisely, the value is a tail
988 of the value of @code{kill-ring}, and its @sc{car} is the kill string
989 that @kbd{C-y} should yank.
992 @defopt kill-ring-max
993 The value of this variable is the maximum length to which the kill
994 ring can grow, before elements are thrown away at the end. The default
995 value for @code{kill-ring-max} is 30.
999 @comment node-name, next, previous, up
1003 Most buffers have an @dfn{undo list}, which records all changes made
1004 to the buffer's text so that they can be undone. (The buffers that
1005 don't have one are usually special-purpose buffers for which Emacs
1006 assumes that undoing is not useful.) All the primitives that modify the
1007 text in the buffer automatically add elements to the front of the undo
1008 list, which is in the variable @code{buffer-undo-list}.
1010 @defvar buffer-undo-list
1011 This variable's value is the undo list of the current buffer.
1012 A value of @code{t} disables the recording of undo information.
1015 Here are the kinds of elements an undo list can have:
1018 @item @var{position}
1019 This kind of element records a previous value of point; undoing this
1020 element moves point to @var{position}. Ordinary cursor motion does not
1021 make any sort of undo record, but deletion operations use these entries
1022 to record where point was before the command.
1024 @item (@var{beg} . @var{end})
1025 This kind of element indicates how to delete text that was inserted.
1026 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
1029 @item (@var{text} . @var{position})
1030 This kind of element indicates how to reinsert text that was deleted.
1031 The deleted text itself is the string @var{text}. The place to
1032 reinsert it is @code{(abs @var{position})}.
1034 @item (t @var{high} . @var{low})
1035 This kind of element indicates that an unmodified buffer became
1036 modified. The elements @var{high} and @var{low} are two integers, each
1037 recording 16 bits of the visited file's modification time as of when it
1038 was previously visited or saved. @code{primitive-undo} uses those
1039 values to determine whether to mark the buffer as unmodified once again;
1040 it does so only if the file's modification time matches those numbers.
1042 @item (nil @var{property} @var{value} @var{beg} . @var{end})
1043 This kind of element records a change in a text property.
1044 Here's how you might undo the change:
1047 (put-text-property @var{beg} @var{end} @var{property} @var{value})
1050 @item (@var{marker} . @var{adjustment})
1051 This kind of element records the fact that the marker @var{marker} was
1052 relocated due to deletion of surrounding text, and that it moved
1053 @var{adjustment} character positions. Undoing this element moves
1054 @var{marker} @minus{} @var{adjustment} characters.
1057 This element is a boundary. The elements between two boundaries are
1058 called a @dfn{change group}; normally, each change group corresponds to
1059 one keyboard command, and undo commands normally undo an entire group as
1063 @defun undo-boundary
1064 This function places a boundary element in the undo list. The undo
1065 command stops at such a boundary, and successive undo commands undo
1066 to earlier and earlier boundaries. This function returns @code{nil}.
1068 The editor command loop automatically creates an undo boundary before
1069 each key sequence is executed. Thus, each undo normally undoes the
1070 effects of one command. Self-inserting input characters are an
1071 exception. The command loop makes a boundary for the first such
1072 character; the next 19 consecutive self-inserting input characters do
1073 not make boundaries, and then the 20th does, and so on as long as
1074 self-inserting characters continue.
1076 All buffer modifications add a boundary whenever the previous undoable
1077 change was made in some other buffer. This is to ensure that
1078 each command makes a boundary in each buffer where it makes changes.
1080 Calling this function explicitly is useful for splitting the effects of
1081 a command into more than one unit. For example, @code{query-replace}
1082 calls @code{undo-boundary} after each replacement, so that the user can
1083 undo individual replacements one by one.
1086 @defun primitive-undo count list
1087 This is the basic function for undoing elements of an undo list.
1088 It undoes the first @var{count} elements of @var{list}, returning
1089 the rest of @var{list}. You could write this function in Lisp,
1090 but it is convenient to have it in C.
1092 @code{primitive-undo} adds elements to the buffer's undo list when it
1093 changes the buffer. Undo commands avoid confusion by saving the undo
1094 list value at the beginning of a sequence of undo operations. Then the
1095 undo operations use and update the saved value. The new elements added
1096 by undoing are not part of this saved value, so they don't interfere with
1100 @node Maintaining Undo
1101 @section Maintaining Undo Lists
1103 This section describes how to enable and disable undo information for
1104 a given buffer. It also explains how the undo list is truncated
1105 automatically so it doesn't get too big.
1107 Recording of undo information in a newly created buffer is normally
1108 enabled to start with; but if the buffer name starts with a space, the
1109 undo recording is initially disabled. You can explicitly enable or
1110 disable undo recording with the following two functions, or by setting
1111 @code{buffer-undo-list} yourself.
1113 @deffn Command buffer-enable-undo &optional buffer-or-name
1114 This command enables recording undo information for buffer
1115 @var{buffer-or-name}, so that subsequent changes can be undone. If no
1116 argument is supplied, then the current buffer is used. This function
1117 does nothing if undo recording is already enabled in the buffer. It
1120 In an interactive call, @var{buffer-or-name} is the current buffer.
1121 You cannot specify any other buffer.
1124 @deffn Command buffer-disable-undo &optional buffer
1125 @deffnx Command buffer-flush-undo &optional buffer
1126 @cindex disable undo
1127 This function discards the undo list of @var{buffer}, and disables
1128 further recording of undo information. As a result, it is no longer
1129 possible to undo either previous changes or any subsequent changes. If
1130 the undo list of @var{buffer} is already disabled, this function
1133 This function returns @code{nil}.
1135 The name @code{buffer-flush-undo} is not considered obsolete, but the
1136 preferred name is @code{buffer-disable-undo}.
1139 As editing continues, undo lists get longer and longer. To prevent
1140 them from using up all available memory space, garbage collection trims
1141 them back to size limits you can set. (For this purpose, the ``size''
1142 of an undo list measures the cons cells that make up the list, plus the
1143 strings of deleted text.) Two variables control the range of acceptable
1144 sizes: @code{undo-limit} and @code{undo-strong-limit}.
1147 This is the soft limit for the acceptable size of an undo list. The
1148 change group at which this size is exceeded is the last one kept.
1151 @defvar undo-strong-limit
1152 This is the upper limit for the acceptable size of an undo list. The
1153 change group at which this size is exceeded is discarded itself (along
1154 with all older change groups). There is one exception: the very latest
1155 change group is never discarded no matter how big it is.
1159 @comment node-name, next, previous, up
1161 @cindex filling, explicit
1163 @dfn{Filling} means adjusting the lengths of lines (by moving the line
1164 breaks) so that they are nearly (but no greater than) a specified
1165 maximum width. Additionally, lines can be @dfn{justified}, which means
1166 inserting spaces to make the left and/or right margins line up
1167 precisely. The width is controlled by the variable @code{fill-column}.
1168 For ease of reading, lines should be no longer than 70 or so columns.
1170 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1171 automatically as you insert it, but changes to existing text may leave
1172 it improperly filled. Then you must fill the text explicitly.
1174 Most of the commands in this section return values that are not
1175 meaningful. All the functions that do filling take note of the current
1176 left margin, current right margin, and current justification style
1177 (@pxref{Margins}). If the current justification style is
1178 @code{none}, the filling functions don't actually do anything.
1180 Several of the filling functions have an argument @var{justify}.
1181 If it is non-@code{nil}, that requests some kind of justification. It
1182 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
1183 request a specific style of justification. If it is @code{t}, that
1184 means to use the current justification style for this part of the text
1185 (see @code{current-justification}, below). Any other value is treated
1188 When you call the filling functions interactively, using a prefix
1189 argument implies the value @code{full} for @var{justify}.
1191 @deffn Command fill-paragraph justify
1192 @cindex filling a paragraph
1193 This command fills the paragraph at or after point. If
1194 @var{justify} is non-@code{nil}, each line is justified as well.
1195 It uses the ordinary paragraph motion commands to find paragraph
1196 boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}.
1199 @deffn Command fill-region start end &optional justify nosqueeze
1200 This command fills each of the paragraphs in the region from @var{start}
1201 to @var{end}. It justifies as well if @var{justify} is
1204 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1205 other than line breaks untouched. If @var{to-eop} is non-@code{nil},
1206 that means to keep filling to the end of the paragraph---or the next hard
1207 newline, if @code{use-hard-newlines} is enabled (see below).
1209 The variable @code{paragraph-separate} controls how to distinguish
1210 paragraphs. @xref{Standard Regexps}.
1213 @deffn Command fill-individual-paragraphs start end &optional justify mail-flag
1214 This command fills each paragraph in the region according to its
1215 individual fill prefix. Thus, if the lines of a paragraph were indented
1216 with spaces, the filled paragraph will remain indented in the same
1219 The first two arguments, @var{start} and @var{end}, are the beginning
1220 and end of the region to be filled. The third and fourth arguments,
1221 @var{justify} and @var{mail-flag}, are optional. If
1222 @var{justify} is non-@code{nil}, the paragraphs are justified as
1223 well as filled. If @var{mail-flag} is non-@code{nil}, it means the
1224 function is operating on a mail message and therefore should not fill
1227 Ordinarily, @code{fill-individual-paragraphs} regards each change in
1228 indentation as starting a new paragraph. If
1229 @code{fill-individual-varying-indent} is non-@code{nil}, then only
1230 separator lines separate paragraphs. That mode can handle indented
1231 paragraphs with additional indentation on the first line.
1234 @defopt fill-individual-varying-indent
1235 This variable alters the action of @code{fill-individual-paragraphs} as
1239 @deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
1240 This command considers a region of text as a single paragraph and fills
1241 it. If the region was made up of many paragraphs, the blank lines
1242 between paragraphs are removed. This function justifies as well as
1243 filling when @var{justify} is non-@code{nil}.
1245 In an interactive call, any prefix argument requests justification.
1247 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1248 other than line breaks untouched. If @var{squeeze-after} is
1249 non-@code{nil}, it specifies a position in the region, and means don't
1250 canonicalize spaces before that position.
1252 In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
1253 choose a fill prefix by default. @xref{Adaptive Fill}.
1256 @deffn Command justify-current-line how eop nosqueeze
1257 This command inserts spaces between the words of the current line so
1258 that the line ends exactly at @code{fill-column}. It returns
1261 The argument @var{how}, if non-@code{nil} specifies explicitly the style
1262 of justification. It can be @code{left}, @code{right}, @code{full},
1263 @code{center}, or @code{none}. If it is @code{t}, that means to do
1264 follow specified justification style (see @code{current-justification},
1265 below). @code{nil} means to do full justification.
1267 If @var{eop} is non-@code{nil}, that means do left-justification if
1268 @code{current-justification} specifies full justification. This is used
1269 for the last line of a paragraph; even if the paragraph as a whole is
1270 fully justified, the last line should not be.
1272 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1276 @defopt default-justification
1277 This variable's value specifies the style of justification to use for
1278 text that doesn't specify a style with a text property. The possible
1279 values are @code{left}, @code{right}, @code{full}, @code{center}, or
1280 @code{none}. The default value is @code{left}.
1283 @defun current-justification
1284 This function returns the proper justification style to use for filling
1285 the text around point.
1288 @defopt sentence-end-double-space
1289 If this variable is non-@code{nil}, a period followed by just one space
1290 does not count as the end of a sentence, and the filling functions
1291 avoid breaking the line at such a place.
1294 @defvar fill-paragraph-function
1295 This variable provides a way for major modes to override the filling of
1296 paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
1297 this function to do the work. If the function returns a non-@code{nil}
1298 value, @code{fill-paragraph} assumes the job is done, and immediately
1301 The usual use of this feature is to fill comments in programming
1302 language modes. If the function needs to fill a paragraph in the usual
1303 way, it can do so as follows:
1306 (let ((fill-paragraph-function nil))
1307 (fill-paragraph arg))
1311 @defvar use-hard-newlines
1312 If this variable is non-@code{nil}, the filling functions do not delete
1313 newlines that have the @code{hard} text property. These ``hard
1314 newlines'' act as paragraph separators.
1318 @section Margins for Filling
1321 This buffer-local variable specifies a string of text that appears at
1323 of normal text lines and should be disregarded when filling them. Any
1324 line that fails to start with the fill prefix is considered the start of
1325 a paragraph; so is any line that starts with the fill prefix followed by
1326 additional whitespace. Lines that start with the fill prefix but no
1327 additional whitespace are ordinary text lines that can be filled
1328 together. The resulting filled lines also start with the fill prefix.
1330 The fill prefix follows the left margin whitespace, if any.
1334 This buffer-local variable specifies the maximum width of filled lines.
1335 Its value should be an integer, which is a number of columns. All the
1336 filling, justification, and centering commands are affected by this
1337 variable, including Auto Fill mode (@pxref{Auto Filling}).
1339 As a practical matter, if you are writing text for other people to
1340 read, you should set @code{fill-column} to no more than 70. Otherwise
1341 the line will be too long for people to read comfortably, and this can
1342 make the text seem clumsy.
1345 @defvar default-fill-column
1346 The value of this variable is the default value for @code{fill-column} in
1347 buffers that do not override it. This is the same as
1348 @code{(default-value 'fill-column)}.
1350 The default value for @code{default-fill-column} is 70.
1353 @deffn Command set-left-margin from to margin
1354 This sets the @code{left-margin} property on the text from @var{from} to
1355 @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
1356 command also refills the region to fit the new margin.
1359 @deffn Command set-right-margin from to margin
1360 This sets the @code{right-margin} property on the text from @var{from}
1361 to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
1362 this command also refills the region to fit the new margin.
1365 @defun current-left-margin
1366 This function returns the proper left margin value to use for filling
1367 the text around point. The value is the sum of the @code{left-margin}
1368 property of the character at the start of the current line (or zero if
1369 none), and the value of the variable @code{left-margin}.
1372 @defun current-fill-column
1373 This function returns the proper fill column value to use for filling
1374 the text around point. The value is the value of the @code{fill-column}
1375 variable, minus the value of the @code{right-margin} property of the
1376 character after point.
1379 @deffn Command move-to-left-margin &optional n force
1380 This function moves point to the left margin of the current line. The
1381 column moved to is determined by calling the function
1382 @code{current-left-margin}. If the argument @var{n} is non-@code{nil},
1383 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
1385 If @var{force} is non-@code{nil}, that says to fix the line's
1386 indentation if that doesn't match the left margin value.
1389 @defun delete-to-left-margin from to
1390 This function removes left margin indentation from the text
1391 between @var{from} and @var{to}. The amount of indentation
1392 to delete is determined by calling @code{current-left-margin}.
1393 In no case does this function delete non-whitespace.
1396 @defun indent-to-left-margin
1397 This is the default @code{indent-line-function}, used in Fundamental
1398 mode, Text mode, etc. Its effect is to adjust the indentation at the
1399 beginning of the current line to the value specified by the variable
1400 @code{left-margin}. This may involve either inserting or deleting
1405 This variable specifies the base left margin column. In Fundamental
1406 mode, @kbd{C-j} indents to this column. This variable automatically
1407 becomes buffer-local when set in any fashion.
1410 @defvar fill-nobreak-predicate
1411 @tindex fill-nobreak-predicate
1412 This variable gives major modes a way to specify not to break a line at
1413 certain places. Its value should be a function. This function is
1414 called during filling, with no arguments and with point located at the
1415 place where a break is being considered. If the function returns
1416 non-@code{nil}, then the line won't be broken there.
1420 @section Adaptive Fill Mode
1421 @cindex Adaptive Fill mode
1423 Adaptive Fill mode chooses a fill prefix automatically from the text
1424 in each paragraph being filled.
1426 @defopt adaptive-fill-mode
1427 Adaptive Fill mode is enabled when this variable is non-@code{nil}.
1428 It is @code{t} by default.
1431 @defun fill-context-prefix from to
1432 This function implements the heart of Adaptive Fill mode; it chooses a
1433 fill prefix based on the text between @var{from} and @var{to}. It does
1434 this by looking at the first two lines of the paragraph, based on the
1435 variables described below.
1438 @defopt adaptive-fill-regexp
1439 This variable holds a regular expression to control Adaptive Fill mode.
1440 Adaptive Fill mode matches this regular expression against the text
1441 starting after the left margin whitespace (if any) on a line; the
1442 characters it matches are that line's candidate for the fill prefix.
1445 @defopt adaptive-fill-first-line-regexp
1446 In a one-line paragraph, if the candidate fill prefix matches this
1447 regular expression, or if it matches @code{comment-start-skip}, then it
1448 is used---otherwise, spaces amounting to the same width are used
1451 However, the fill prefix is never taken from a one-line paragraph
1452 if it would act as a paragraph starter on subsequent lines.
1455 @defopt adaptive-fill-function
1456 You can specify more complex ways of choosing a fill prefix
1457 automatically by setting this variable to a function. The function is
1458 called when @code{adaptive-fill-regexp} does not match, with point after
1459 the left margin of a line, and it should return the appropriate fill
1460 prefix based on that line. If it returns @code{nil}, that means it sees
1461 no fill prefix in that line.
1465 @comment node-name, next, previous, up
1466 @section Auto Filling
1467 @cindex filling, automatic
1468 @cindex Auto Fill mode
1470 Auto Fill mode is a minor mode that fills lines automatically as text
1471 is inserted. This section describes the hook used by Auto Fill mode.
1472 For a description of functions that you can call explicitly to fill and
1473 justify existing text, see @ref{Filling}.
1475 Auto Fill mode also enables the functions that change the margins and
1476 justification style to refill portions of the text. @xref{Margins}.
1478 @defvar auto-fill-function
1479 The value of this variable should be a function (of no arguments) to be
1480 called after self-inserting a space or a newline. It may be @code{nil},
1481 in which case nothing special is done in that case.
1483 The value of @code{auto-fill-function} is @code{do-auto-fill} when
1484 Auto-Fill mode is enabled. That is a function whose sole purpose is to
1485 implement the usual strategy for breaking a line.
1488 In older Emacs versions, this variable was named @code{auto-fill-hook},
1489 but since it is not called with the standard convention for hooks, it
1490 was renamed to @code{auto-fill-function} in version 19.
1494 @defvar normal-auto-fill-function
1495 This variable specifies the function to use for
1496 @code{auto-fill-function}, if and when Auto Fill is turned on. Major
1497 modes can set buffer-local values for this variable to alter how Auto
1502 @section Sorting Text
1503 @cindex sorting text
1505 The sorting functions described in this section all rearrange text in
1506 a buffer. This is in contrast to the function @code{sort}, which
1507 rearranges the order of the elements of a list (@pxref{Rearrangement}).
1508 The values returned by these functions are not meaningful.
1510 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
1511 This function is the general text-sorting routine that subdivides a
1512 buffer into records and then sorts them. Most of the commands in this
1513 section use this function.
1515 To understand how @code{sort-subr} works, consider the whole accessible
1516 portion of the buffer as being divided into disjoint pieces called
1517 @dfn{sort records}. The records may or may not be contiguous, but they
1518 must not overlap. A portion of each sort record (perhaps all of it) is
1519 designated as the sort key. Sorting rearranges the records in order by
1522 Usually, the records are rearranged in order of ascending sort key.
1523 If the first argument to the @code{sort-subr} function, @var{reverse},
1524 is non-@code{nil}, the sort records are rearranged in order of
1525 descending sort key.
1527 The next four arguments to @code{sort-subr} are functions that are
1528 called to move point across a sort record. They are called many times
1529 from within @code{sort-subr}.
1533 @var{nextrecfun} is called with point at the end of a record. This
1534 function moves point to the start of the next record. The first record
1535 is assumed to start at the position of point when @code{sort-subr} is
1536 called. Therefore, you should usually move point to the beginning of
1537 the buffer before calling @code{sort-subr}.
1539 This function can indicate there are no more sort records by leaving
1540 point at the end of the buffer.
1543 @var{endrecfun} is called with point within a record. It moves point to
1544 the end of the record.
1547 @var{startkeyfun} is called to move point from the start of a record to
1548 the start of the sort key. This argument is optional; if it is omitted,
1549 the whole record is the sort key. If supplied, the function should
1550 either return a non-@code{nil} value to be used as the sort key, or
1551 return @code{nil} to indicate that the sort key is in the buffer
1552 starting at point. In the latter case, @var{endkeyfun} is called to
1553 find the end of the sort key.
1556 @var{endkeyfun} is called to move point from the start of the sort key
1557 to the end of the sort key. This argument is optional. If
1558 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
1559 @code{nil}), then the sort key extends to the end of the record. There
1560 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1561 non-@code{nil} value.
1564 As an example of @code{sort-subr}, here is the complete function
1565 definition for @code{sort-lines}:
1569 ;; @r{Note that the first two lines of doc string}
1570 ;; @r{are effectively one line when viewed by a user.}
1571 (defun sort-lines (reverse beg end)
1572 "Sort lines in region alphabetically;\
1573 argument means descending order.
1574 Called from a program, there are three arguments:
1577 REVERSE (non-nil means reverse order),\
1578 BEG and END (region to sort).
1579 The variable `sort-fold-case' determines\
1580 whether alphabetic case affects
1584 (interactive "P\nr")
1587 (narrow-to-region beg end)
1588 (goto-char (point-min))
1589 (sort-subr reverse 'forward-line 'end-of-line))))
1593 Here @code{forward-line} moves point to the start of the next record,
1594 and @code{end-of-line} moves point to the end of record. We do not pass
1595 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
1596 record is used as the sort key.
1598 The @code{sort-paragraphs} function is very much the same, except that
1599 its @code{sort-subr} call looks like this:
1606 (while (and (not (eobp))
1607 (looking-at paragraph-separate))
1613 Markers pointing into any sort records are left with no useful
1614 position after @code{sort-subr} returns.
1617 @defopt sort-fold-case
1618 If this variable is non-@code{nil}, @code{sort-subr} and the other
1619 buffer sorting functions ignore case when comparing strings.
1622 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
1623 This command sorts the region between @var{start} and @var{end}
1624 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
1625 If @var{reverse} is a negative integer, then sorting is in reverse
1628 Alphabetical sorting means that two sort keys are compared by
1629 comparing the first characters of each, the second characters of each,
1630 and so on. If a mismatch is found, it means that the sort keys are
1631 unequal; the sort key whose character is less at the point of first
1632 mismatch is the lesser sort key. The individual characters are compared
1633 according to their numerical character codes in the Emacs character set.
1635 The value of the @var{record-regexp} argument specifies how to divide
1636 the buffer into sort records. At the end of each record, a search is
1637 done for this regular expression, and the text that matches it is taken
1638 as the next record. For example, the regular expression @samp{^.+$},
1639 which matches lines with at least one character besides a newline, would
1640 make each such line into a sort record. @xref{Regular Expressions}, for
1641 a description of the syntax and meaning of regular expressions.
1643 The value of the @var{key-regexp} argument specifies what part of each
1644 record is the sort key. The @var{key-regexp} could match the whole
1645 record, or only a part. In the latter case, the rest of the record has
1646 no effect on the sorted order of records, but it is carried along when
1647 the record moves to its new position.
1649 The @var{key-regexp} argument can refer to the text matched by a
1650 subexpression of @var{record-regexp}, or it can be a regular expression
1653 If @var{key-regexp} is:
1656 @item @samp{\@var{digit}}
1657 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
1658 grouping in @var{record-regexp} is the sort key.
1661 then the whole record is the sort key.
1663 @item a regular expression
1664 then @code{sort-regexp-fields} searches for a match for the regular
1665 expression within the record. If such a match is found, it is the sort
1666 key. If there is no match for @var{key-regexp} within a record then
1667 that record is ignored, which means its position in the buffer is not
1668 changed. (The other records may move around it.)
1671 For example, if you plan to sort all the lines in the region by the
1672 first word on each line starting with the letter @samp{f}, you should
1673 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
1674 @samp{\<f\w*\>}. The resulting expression looks like this:
1678 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
1684 If you call @code{sort-regexp-fields} interactively, it prompts for
1685 @var{record-regexp} and @var{key-regexp} in the minibuffer.
1688 @deffn Command sort-lines reverse start end
1689 This command alphabetically sorts lines in the region between
1690 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1691 is in reverse order.
1694 @deffn Command sort-paragraphs reverse start end
1695 This command alphabetically sorts paragraphs in the region between
1696 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1697 is in reverse order.
1700 @deffn Command sort-pages reverse start end
1701 This command alphabetically sorts pages in the region between
1702 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1703 is in reverse order.
1706 @deffn Command sort-fields field start end
1707 This command sorts lines in the region between @var{start} and
1708 @var{end}, comparing them alphabetically by the @var{field}th field
1709 of each line. Fields are separated by whitespace and numbered starting
1710 from 1. If @var{field} is negative, sorting is by the
1711 @w{@minus{}@var{field}th} field from the end of the line. This command
1712 is useful for sorting tables.
1715 @deffn Command sort-numeric-fields field start end
1716 This command sorts lines in the region between @var{start} and
1717 @var{end}, comparing them numerically by the @var{field}th field of each
1718 line. The specified field must contain a number in each line of the
1719 region. Fields are separated by whitespace and numbered starting from
1720 1. If @var{field} is negative, sorting is by the
1721 @w{@minus{}@var{field}th} field from the end of the line. This command
1722 is useful for sorting tables.
1725 @deffn Command sort-columns reverse &optional beg end
1726 This command sorts the lines in the region between @var{beg} and
1727 @var{end}, comparing them alphabetically by a certain range of columns.
1728 The column positions of @var{beg} and @var{end} bound the range of
1731 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
1733 One unusual thing about this command is that the entire line
1734 containing position @var{beg}, and the entire line containing position
1735 @var{end}, are included in the region sorted.
1737 Note that @code{sort-columns} uses the @code{sort} utility program,
1738 and so cannot work properly on text containing tab characters. Use
1739 @kbd{M-x untabify} to convert tabs to spaces before sorting.
1743 @comment node-name, next, previous, up
1744 @section Counting Columns
1746 @cindex counting columns
1747 @cindex horizontal position
1749 The column functions convert between a character position (counting
1750 characters from the beginning of the buffer) and a column position
1751 (counting screen characters from the beginning of a line).
1753 These functions count each character according to the number of
1754 columns it occupies on the screen. This means control characters count
1755 as occupying 2 or 4 columns, depending upon the value of
1756 @code{ctl-arrow}, and tabs count as occupying a number of columns that
1757 depends on the value of @code{tab-width} and on the column where the tab
1758 begins. @xref{Usual Display}.
1760 Column number computations ignore the width of the window and the
1761 amount of horizontal scrolling. Consequently, a column value can be
1762 arbitrarily high. The first (or leftmost) column is numbered 0.
1764 @defun current-column
1765 This function returns the horizontal position of point, measured in
1766 columns, counting from 0 at the left margin. The column position is the
1767 sum of the widths of all the displayed representations of the characters
1768 between the start of the current line and point.
1770 For an example of using @code{current-column}, see the description of
1771 @code{count-lines} in @ref{Text Lines}.
1774 @defun move-to-column column &optional force
1775 This function moves point to @var{column} in the current line. The
1776 calculation of @var{column} takes into account the widths of the
1777 displayed representations of the characters between the start of the
1780 If column @var{column} is beyond the end of the line, point moves to the
1781 end of the line. If @var{column} is negative, point moves to the
1782 beginning of the line.
1784 If it is impossible to move to column @var{column} because that is in
1785 the middle of a multicolumn character such as a tab, point moves to the
1786 end of that character. However, if @var{force} is non-@code{nil}, and
1787 @var{column} is in the middle of a tab, then @code{move-to-column}
1788 converts the tab into spaces so that it can move precisely to column
1789 @var{column}. Other multicolumn characters can cause anomalies despite
1790 @var{force}, since there is no way to split them.
1792 The argument @var{force} also has an effect if the line isn't long
1793 enough to reach column @var{column}; in that case, it says to add
1794 whitespace at the end of the line to reach that column.
1796 If @var{column} is not an integer, an error is signaled.
1798 The return value is the column number actually moved to.
1802 @section Indentation
1805 The indentation functions are used to examine, move to, and change
1806 whitespace that is at the beginning of a line. Some of the functions
1807 can also change whitespace elsewhere on a line. Columns and indentation
1808 count from zero at the left margin.
1811 * Primitive Indent:: Functions used to count and insert indentation.
1812 * Mode-Specific Indent:: Customize indentation for different modes.
1813 * Region Indent:: Indent all the lines in a region.
1814 * Relative Indent:: Indent the current line based on previous lines.
1815 * Indent Tabs:: Adjustable, typewriter-like tab stops.
1816 * Motion by Indent:: Move to first non-blank character.
1819 @node Primitive Indent
1820 @subsection Indentation Primitives
1822 This section describes the primitive functions used to count and
1823 insert indentation. The functions in the following sections use these
1824 primitives. @xref{Width}, for related functions.
1826 @defun current-indentation
1827 @comment !!Type Primitive Function
1828 @comment !!SourceFile indent.c
1829 This function returns the indentation of the current line, which is
1830 the horizontal position of the first nonblank character. If the
1831 contents are entirely blank, then this is the horizontal position of the
1835 @deffn Command indent-to column &optional minimum
1836 @comment !!Type Primitive Function
1837 @comment !!SourceFile indent.c
1838 This function indents from point with tabs and spaces until @var{column}
1839 is reached. If @var{minimum} is specified and non-@code{nil}, then at
1840 least that many spaces are inserted even if this requires going beyond
1841 @var{column}. Otherwise the function does nothing if point is already
1842 beyond @var{column}. The value is the column at which the inserted
1845 The inserted whitespace characters inherit text properties from the
1846 surrounding text (usually, from the preceding text only). @xref{Sticky
1850 @defopt indent-tabs-mode
1851 @comment !!SourceFile indent.c
1852 If this variable is non-@code{nil}, indentation functions can insert
1853 tabs as well as spaces. Otherwise, they insert only spaces. Setting
1854 this variable automatically makes it buffer-local in the current buffer.
1857 @node Mode-Specific Indent
1858 @subsection Indentation Controlled by Major Mode
1860 An important function of each major mode is to customize the @key{TAB}
1861 key to indent properly for the language being edited. This section
1862 describes the mechanism of the @key{TAB} key and how to control it.
1863 The functions in this section return unpredictable values.
1865 @defvar indent-line-function
1866 This variable's value is the function to be used by @key{TAB} (and
1867 various commands) to indent the current line. The command
1868 @code{indent-according-to-mode} does no more than call this function.
1870 In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C
1871 mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
1872 In Fundamental mode, Text mode, and many other modes with no standard
1873 for indentation, the value is @code{indent-to-left-margin} (which is the
1877 @deffn Command indent-according-to-mode
1878 This command calls the function in @code{indent-line-function} to
1879 indent the current line in a way appropriate for the current major mode.
1882 @deffn Command indent-for-tab-command
1883 This command calls the function in @code{indent-line-function} to indent
1884 the current line; however, if that function is
1885 @code{indent-to-left-margin}, @code{insert-tab} is called instead. (That
1886 is a trivial command that inserts a tab character.)
1889 @deffn Command newline-and-indent
1890 @comment !!SourceFile simple.el
1891 This function inserts a newline, then indents the new line (the one
1892 following the newline just inserted) according to the major mode.
1894 It does indentation by calling the current @code{indent-line-function}.
1895 In programming language modes, this is the same thing @key{TAB} does,
1896 but in some text modes, where @key{TAB} inserts a tab,
1897 @code{newline-and-indent} indents to the column specified by
1901 @deffn Command reindent-then-newline-and-indent
1902 @comment !!SourceFile simple.el
1903 This command reindents the current line, inserts a newline at point,
1904 and then indents the new line (the one following the newline just
1907 This command does indentation on both lines according to the current
1908 major mode, by calling the current value of @code{indent-line-function}.
1909 In programming language modes, this is the same thing @key{TAB} does,
1910 but in some text modes, where @key{TAB} inserts a tab,
1911 @code{reindent-then-newline-and-indent} indents to the column specified
1912 by @code{left-margin}.
1916 @subsection Indenting an Entire Region
1918 This section describes commands that indent all the lines in the
1919 region. They return unpredictable values.
1921 @deffn Command indent-region start end to-column
1922 This command indents each nonblank line starting between @var{start}
1923 (inclusive) and @var{end} (exclusive). If @var{to-column} is
1924 @code{nil}, @code{indent-region} indents each nonblank line by calling
1925 the current mode's indentation function, the value of
1926 @code{indent-line-function}.
1928 If @var{to-column} is non-@code{nil}, it should be an integer
1929 specifying the number of columns of indentation; then this function
1930 gives each line exactly that much indentation, by either adding or
1931 deleting whitespace.
1933 If there is a fill prefix, @code{indent-region} indents each line
1934 by making it start with the fill prefix.
1937 @defvar indent-region-function
1938 The value of this variable is a function that can be used by
1939 @code{indent-region} as a short cut. It should take two arguments, the
1940 start and end of the region. You should design the function so
1941 that it will produce the same results as indenting the lines of the
1942 region one by one, but presumably faster.
1944 If the value is @code{nil}, there is no short cut, and
1945 @code{indent-region} actually works line by line.
1947 A short-cut function is useful in modes such as C mode and Lisp mode,
1948 where the @code{indent-line-function} must scan from the beginning of
1949 the function definition: applying it to each line would be quadratic in
1950 time. The short cut can update the scan information as it moves through
1951 the lines indenting them; this takes linear time. In a mode where
1952 indenting a line individually is fast, there is no need for a short cut.
1954 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
1955 a different meaning and does not use this variable.
1958 @deffn Command indent-rigidly start end count
1959 @comment !!SourceFile indent.el
1960 This command indents all lines starting between @var{start}
1961 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
1962 This ``preserves the shape'' of the affected region, moving it as a
1963 rigid unit. Consequently, this command is useful not only for indenting
1964 regions of unindented text, but also for indenting regions of formatted
1967 For example, if @var{count} is 3, this command adds 3 columns of
1968 indentation to each of the lines beginning in the region specified.
1970 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
1971 @code{indent-rigidly} to indent the text copied from the message being
1975 @defun indent-code-rigidly start end columns &optional nochange-regexp
1976 This is like @code{indent-rigidly}, except that it doesn't alter lines
1977 that start within strings or comments.
1979 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
1980 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
1983 @node Relative Indent
1984 @subsection Indentation Relative to Previous Lines
1986 This section describes two commands that indent the current line
1987 based on the contents of previous lines.
1989 @deffn Command indent-relative &optional unindented-ok
1990 This command inserts whitespace at point, extending to the same
1991 column as the next @dfn{indent point} of the previous nonblank line. An
1992 indent point is a non-whitespace character following whitespace. The
1993 next indent point is the first one at a column greater than the current
1994 column of point. For example, if point is underneath and to the left of
1995 the first non-blank character of a line of text, it moves to that column
1996 by inserting whitespace.
1998 If the previous nonblank line has no next indent point (i.e., none at a
1999 great enough column position), @code{indent-relative} either does
2000 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
2001 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right
2002 of the last column of a short line of text, this command ordinarily
2003 moves point to the next tab stop by inserting whitespace.
2005 The return value of @code{indent-relative} is unpredictable.
2007 In the following example, point is at the beginning of the second
2012 This line is indented twelve spaces.
2013 @point{}The quick brown fox jumped.
2018 Evaluation of the expression @code{(indent-relative nil)} produces the
2023 This line is indented twelve spaces.
2024 @point{}The quick brown fox jumped.
2028 In this next example, point is between the @samp{m} and @samp{p} of
2033 This line is indented twelve spaces.
2034 The quick brown fox jum@point{}ped.
2039 Evaluation of the expression @code{(indent-relative nil)} produces the
2044 This line is indented twelve spaces.
2045 The quick brown fox jum @point{}ped.
2050 @deffn Command indent-relative-maybe
2051 @comment !!SourceFile indent.el
2052 This command indents the current line like the previous nonblank line,
2053 by calling @code{indent-relative} with @code{t} as the
2054 @var{unindented-ok} argument. The return value is unpredictable.
2056 If the previous nonblank line has no indent points beyond the current
2057 column, this command does nothing.
2061 @comment node-name, next, previous, up
2062 @subsection Adjustable ``Tab Stops''
2063 @cindex tabs stops for indentation
2065 This section explains the mechanism for user-specified ``tab stops''
2066 and the mechanisms that use and set them. The name ``tab stops'' is
2067 used because the feature is similar to that of the tab stops on a
2068 typewriter. The feature works by inserting an appropriate number of
2069 spaces and tab characters to reach the next tab stop column; it does not
2070 affect the display of tab characters in the buffer (@pxref{Usual
2071 Display}). Note that the @key{TAB} character as input uses this tab
2072 stop feature only in a few major modes, such as Text mode.
2074 @deffn Command tab-to-tab-stop
2075 This command inserts spaces or tabs before point, up to the next tab
2076 stop column defined by @code{tab-stop-list}. It searches the list for
2077 an element greater than the current column number, and uses that element
2078 as the column to indent to. It does nothing if no such element is
2082 @defopt tab-stop-list
2083 This variable is the list of tab stop columns used by
2084 @code{tab-to-tab-stops}. The elements should be integers in increasing
2085 order. The tab stop columns need not be evenly spaced.
2087 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
2091 @node Motion by Indent
2092 @subsection Indentation-Based Motion Commands
2094 These commands, primarily for interactive use, act based on the
2095 indentation in the text.
2097 @deffn Command back-to-indentation
2098 @comment !!SourceFile simple.el
2099 This command moves point to the first non-whitespace character in the
2100 current line (which is the line in which point is located). It returns
2104 @deffn Command backward-to-indentation arg
2105 @comment !!SourceFile simple.el
2106 This command moves point backward @var{arg} lines and then to the
2107 first nonblank character on that line. It returns @code{nil}.
2110 @deffn Command forward-to-indentation arg
2111 @comment !!SourceFile simple.el
2112 This command moves point forward @var{arg} lines and then to the first
2113 nonblank character on that line. It returns @code{nil}.
2117 @comment node-name, next, previous, up
2118 @section Case Changes
2119 @cindex case conversion in buffers
2121 The case change commands described here work on text in the current
2122 buffer. @xref{Case Conversion}, for case conversion functions that work
2123 on strings and characters. @xref{Case Tables}, for how to customize
2124 which characters are upper or lower case and how to convert them.
2126 @deffn Command capitalize-region start end
2127 This function capitalizes all words in the region defined by
2128 @var{start} and @var{end}. To capitalize means to convert each word's
2129 first character to upper case and convert the rest of each word to lower
2130 case. The function returns @code{nil}.
2132 If one end of the region is in the middle of a word, the part of the
2133 word within the region is treated as an entire word.
2135 When @code{capitalize-region} is called interactively, @var{start} and
2136 @var{end} are point and the mark, with the smallest first.
2140 ---------- Buffer: foo ----------
2141 This is the contents of the 5th foo.
2142 ---------- Buffer: foo ----------
2146 (capitalize-region 1 44)
2149 ---------- Buffer: foo ----------
2150 This Is The Contents Of The 5th Foo.
2151 ---------- Buffer: foo ----------
2156 @deffn Command downcase-region start end
2157 This function converts all of the letters in the region defined by
2158 @var{start} and @var{end} to lower case. The function returns
2161 When @code{downcase-region} is called interactively, @var{start} and
2162 @var{end} are point and the mark, with the smallest first.
2165 @deffn Command upcase-region start end
2166 This function converts all of the letters in the region defined by
2167 @var{start} and @var{end} to upper case. The function returns
2170 When @code{upcase-region} is called interactively, @var{start} and
2171 @var{end} are point and the mark, with the smallest first.
2174 @deffn Command capitalize-word count
2175 This function capitalizes @var{count} words after point, moving point
2176 over as it does. To capitalize means to convert each word's first
2177 character to upper case and convert the rest of each word to lower case.
2178 If @var{count} is negative, the function capitalizes the
2179 @minus{}@var{count} previous words but does not move point. The value
2182 If point is in the middle of a word, the part of the word before point
2183 is ignored when moving forward. The rest is treated as an entire word.
2185 When @code{capitalize-word} is called interactively, @var{count} is
2186 set to the numeric prefix argument.
2189 @deffn Command downcase-word count
2190 This function converts the @var{count} words after point to all lower
2191 case, moving point over as it does. If @var{count} is negative, it
2192 converts the @minus{}@var{count} previous words but does not move point.
2193 The value is @code{nil}.
2195 When @code{downcase-word} is called interactively, @var{count} is set
2196 to the numeric prefix argument.
2199 @deffn Command upcase-word count
2200 This function converts the @var{count} words after point to all upper
2201 case, moving point over as it does. If @var{count} is negative, it
2202 converts the @minus{}@var{count} previous words but does not move point.
2203 The value is @code{nil}.
2205 When @code{upcase-word} is called interactively, @var{count} is set to
2206 the numeric prefix argument.
2209 @node Text Properties
2210 @section Text Properties
2211 @cindex text properties
2212 @cindex attributes of text
2213 @cindex properties of text
2215 Each character position in a buffer or a string can have a @dfn{text
2216 property list}, much like the property list of a symbol (@pxref{Property
2217 Lists}). The properties belong to a particular character at a
2218 particular place, such as, the letter @samp{T} at the beginning of this
2219 sentence or the first @samp{o} in @samp{foo}---if the same character
2220 occurs in two different places, the two occurrences generally have
2221 different properties.
2223 Each property has a name and a value. Both of these can be any Lisp
2224 object, but the name is normally a symbol. The usual way to access the
2225 property list is to specify a name and ask what value corresponds to it.
2227 If a character has a @code{category} property, we call it the
2228 @dfn{category} of the character. It should be a symbol. The properties
2229 of the symbol serve as defaults for the properties of the character.
2231 Copying text between strings and buffers preserves the properties
2232 along with the characters; this includes such diverse functions as
2233 @code{substring}, @code{insert}, and @code{buffer-substring}.
2236 * Examining Properties:: Looking at the properties of one character.
2237 * Changing Properties:: Setting the properties of a range of text.
2238 * Property Search:: Searching for where a property changes value.
2239 * Special Properties:: Particular properties with special meanings.
2240 * Format Properties:: Properties for representing formatting of text.
2241 * Sticky Properties:: How inserted text gets properties from
2243 * Saving Properties:: Saving text properties in files, and reading
2245 * Lazy Properties:: Computing text properties in a lazy fashion
2246 only when text is examined.
2247 * Clickable Text:: Using text properties to make regions of text
2248 do something when you click on them.
2249 * Not Intervals:: Why text properties do not use
2250 Lisp-visible text intervals.
2253 @node Examining Properties
2254 @subsection Examining Text Properties
2256 The simplest way to examine text properties is to ask for the value of
2257 a particular property of a particular character. For that, use
2258 @code{get-text-property}. Use @code{text-properties-at} to get the
2259 entire property list of a character. @xref{Property Search}, for
2260 functions to examine the properties of a number of characters at once.
2262 These functions handle both strings and buffers. Keep in mind that
2263 positions in a string start from 0, whereas positions in a buffer start
2266 @defun get-text-property pos prop &optional object
2267 This function returns the value of the @var{prop} property of the
2268 character after position @var{pos} in @var{object} (a buffer or
2269 string). The argument @var{object} is optional and defaults to the
2272 If there is no @var{prop} property strictly speaking, but the character
2273 has a category that is a symbol, then @code{get-text-property} returns
2274 the @var{prop} property of that symbol.
2277 @defun get-char-property pos prop &optional object
2278 This function is like @code{get-text-property}, except that it checks
2279 overlays first and then text properties. @xref{Overlays}.
2281 The argument @var{object} may be a string, a buffer, or a window. If it
2282 is a window, then the buffer displayed in that window is used for text
2283 properties and overlays, but only the overlays active for that window
2284 are considered. If @var{object} is a buffer, then all overlays in that
2285 buffer are considered, as well as text properties. If @var{object} is a
2286 string, only text properties are considered, since strings never have
2290 @defun text-properties-at position &optional object
2291 This function returns the entire property list of the character at
2292 @var{position} in the string or buffer @var{object}. If @var{object} is
2293 @code{nil}, it defaults to the current buffer.
2296 @defvar default-text-properties
2297 This variable holds a property list giving default values for text
2298 properties. Whenever a character does not specify a value for a
2299 property, neither directly nor through a category symbol, the value
2300 stored in this list is used instead. Here is an example:
2303 (setq default-text-properties '(foo 69))
2304 ;; @r{Make sure character 1 has no properties of its own.}
2305 (set-text-properties 1 2 nil)
2306 ;; @r{What we get, when we ask, is the default value.}
2307 (get-text-property 1 'foo)
2312 @node Changing Properties
2313 @subsection Changing Text Properties
2315 The primitives for changing properties apply to a specified range of
2316 text in a buffer or string. The function @code{set-text-properties}
2317 (see end of section) sets the entire property list of the text in that
2318 range; more often, it is useful to add, change, or delete just certain
2319 properties specified by name.
2321 Since text properties are considered part of the contents of the
2322 buffer (or string), and can affect how a buffer looks on the screen, any
2323 change in buffer text properties mark the buffer as modified. Buffer
2324 text property changes are undoable also (@pxref{Undo}).
2326 @defun put-text-property start end prop value &optional object
2327 This function sets the @var{prop} property to @var{value} for the text
2328 between @var{start} and @var{end} in the string or buffer @var{object}.
2329 If @var{object} is @code{nil}, it defaults to the current buffer.
2332 @defun add-text-properties start end props &optional object
2333 This function adds or overrides text properties for the text between
2334 @var{start} and @var{end} in the string or buffer @var{object}. If
2335 @var{object} is @code{nil}, it defaults to the current buffer.
2337 The argument @var{props} specifies which properties to add. It should
2338 have the form of a property list (@pxref{Property Lists}): a list whose
2339 elements include the property names followed alternately by the
2340 corresponding values.
2342 The return value is @code{t} if the function actually changed some
2343 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2344 its values agree with those in the text).
2346 For example, here is how to set the @code{comment} and @code{face}
2347 properties of a range of text:
2350 (add-text-properties @var{start} @var{end}
2351 '(comment t face highlight))
2355 @defun remove-text-properties start end props &optional object
2356 This function deletes specified text properties from the text between
2357 @var{start} and @var{end} in the string or buffer @var{object}. If
2358 @var{object} is @code{nil}, it defaults to the current buffer.
2360 The argument @var{props} specifies which properties to delete. It
2361 should have the form of a property list (@pxref{Property Lists}): a list
2362 whose elements are property names alternating with corresponding values.
2363 But only the names matter---the values that accompany them are ignored.
2364 For example, here's how to remove the @code{face} property.
2367 (remove-text-properties @var{start} @var{end} '(face nil))
2370 The return value is @code{t} if the function actually changed some
2371 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2372 if no character in the specified text had any of those properties).
2374 To remove all text properties from certain text, use
2375 @code{set-text-properties} and specify @code{nil} for the new property
2379 @defun set-text-properties start end props &optional object
2380 This function completely replaces the text property list for the text
2381 between @var{start} and @var{end} in the string or buffer @var{object}.
2382 If @var{object} is @code{nil}, it defaults to the current buffer.
2384 The argument @var{props} is the new property list. It should be a list
2385 whose elements are property names alternating with corresponding values.
2387 After @code{set-text-properties} returns, all the characters in the
2388 specified range have identical properties.
2390 If @var{props} is @code{nil}, the effect is to get rid of all properties
2391 from the specified range of text. Here's an example:
2394 (set-text-properties @var{start} @var{end} nil)
2398 See also the function @code{buffer-substring-no-properties}
2399 (@pxref{Buffer Contents}) which copies text from the buffer
2400 but does not copy its properties.
2402 @node Property Search
2403 @subsection Text Property Search Functions
2405 In typical use of text properties, most of the time several or many
2406 consecutive characters have the same value for a property. Rather than
2407 writing your programs to examine characters one by one, it is much
2408 faster to process chunks of text that have the same property value.
2410 Here are functions you can use to do this. They use @code{eq} for
2411 comparing property values. In all cases, @var{object} defaults to the
2414 For high performance, it's very important to use the @var{limit}
2415 argument to these functions, especially the ones that search for a
2416 single property---otherwise, they may spend a long time scanning to the
2417 end of the buffer, if the property you are interested in does not change.
2419 These functions do not move point; instead, they return a position (or
2420 @code{nil}). Remember that a position is always between two characters;
2421 the position returned by these functions is between two characters with
2422 different properties.
2424 @defun next-property-change pos &optional object limit
2425 The function scans the text forward from position @var{pos} in the
2426 string or buffer @var{object} till it finds a change in some text
2427 property, then returns the position of the change. In other words, it
2428 returns the position of the first character beyond @var{pos} whose
2429 properties are not identical to those of the character just after
2432 If @var{limit} is non-@code{nil}, then the scan ends at position
2433 @var{limit}. If there is no property change before that point,
2434 @code{next-property-change} returns @var{limit}.
2436 The value is @code{nil} if the properties remain unchanged all the way
2437 to the end of @var{object} and @var{limit} is @code{nil}. If the value
2438 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
2439 The value equals @var{pos} only when @var{limit} equals @var{pos}.
2441 Here is an example of how to scan the buffer by chunks of text within
2442 which all properties are constant:
2446 (let ((plist (text-properties-at (point)))
2448 (or (next-property-change (point) (current-buffer))
2450 @r{Process text from point to @var{next-change}@dots{}}
2451 (goto-char next-change)))
2455 @defun next-single-property-change pos prop &optional object limit
2456 The function scans the text forward from position @var{pos} in the
2457 string or buffer @var{object} till it finds a change in the @var{prop}
2458 property, then returns the position of the change. In other words, it
2459 returns the position of the first character beyond @var{pos} whose
2460 @var{prop} property differs from that of the character just after
2463 If @var{limit} is non-@code{nil}, then the scan ends at position
2464 @var{limit}. If there is no property change before that point,
2465 @code{next-single-property-change} returns @var{limit}.
2467 The value is @code{nil} if the property remains unchanged all the way to
2468 the end of @var{object} and @var{limit} is @code{nil}. If the value is
2469 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
2470 equals @var{pos} only if @var{limit} equals @var{pos}.
2473 @defun previous-property-change pos &optional object limit
2474 This is like @code{next-property-change}, but scans back from @var{pos}
2475 instead of forward. If the value is non-@code{nil}, it is a position
2476 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
2480 @defun previous-single-property-change pos prop &optional object limit
2481 This is like @code{next-single-property-change}, but scans back from
2482 @var{pos} instead of forward. If the value is non-@code{nil}, it is a
2483 position less than or equal to @var{pos}; it equals @var{pos} only if
2484 @var{limit} equals @var{pos}.
2487 @defun next-char-property-change position &optional limit
2488 @tindex next-char-property-change
2489 This is like @code{next-property-change} except that it considers
2490 overlay properties as well as text properties. There is no @var{object}
2491 operand because this function operates only on the current buffer. It
2492 returns the next address at which either kind of property changes.
2495 @defun previous-char-property-change position &optional limit
2496 @tindex previous-char-property-change
2497 This is like @code{next-char-property-change}, but scans back from
2498 @var{position} instead of forward.
2501 @defun text-property-any start end prop value &optional object
2502 This function returns non-@code{nil} if at least one character between
2503 @var{start} and @var{end} has a property @var{prop} whose value is
2504 @var{value}. More precisely, it returns the position of the first such
2505 character. Otherwise, it returns @code{nil}.
2507 The optional fifth argument, @var{object}, specifies the string or
2508 buffer to scan. Positions are relative to @var{object}. The default
2509 for @var{object} is the current buffer.
2512 @defun text-property-not-all start end prop value &optional object
2513 This function returns non-@code{nil} if at least one character between
2514 @var{start} and @var{end} does not have a property @var{prop} with value
2515 @var{value}. More precisely, it returns the position of the first such
2516 character. Otherwise, it returns @code{nil}.
2518 The optional fifth argument, @var{object}, specifies the string or
2519 buffer to scan. Positions are relative to @var{object}. The default
2520 for @var{object} is the current buffer.
2523 @node Special Properties
2524 @subsection Properties with Special Meanings
2526 Here is a table of text property names that have special built-in
2527 meanings. The following sections list a few additional special property
2528 names that control filling and property inheritance. All other names
2529 have no standard meaning, and you can use them as you like.
2532 @cindex category of text character
2533 @kindex category @r{(text property)}
2535 If a character has a @code{category} property, we call it the
2536 @dfn{category} of the character. It should be a symbol. The properties
2537 of the symbol serve as defaults for the properties of the character.
2540 @cindex face codes of text
2541 @kindex face @r{(text property)}
2542 You can use the property @code{face} to control the font and color of
2543 text. Its value is a face name or a list of face names. @xref{Faces},
2544 for more information.
2546 If the property value is a list, elements may also have the form
2547 @code{(foreground-color . @var{color-name})} or @code{(background-color
2548 . @var{color-name})}. These elements specify just the foreground color
2549 or just the background color; therefore, there is no need to create a
2550 face for each color that you want to use.
2552 @xref{Font Lock Mode}, for information on how to update @code{face}
2553 properties automatically based on the contents of the text.
2556 @kindex mouse-face @r{(text property)}
2557 The property @code{mouse-face} is used instead of @code{face} when the
2558 mouse is on or near the character. For this purpose, ``near'' means
2559 that all text between the character and where the mouse is have the same
2560 @code{mouse-face} property value.
2563 @cindex keymap of character
2564 @kindex local-map @r{(text property)}
2565 You can specify a different keymap for some of the text in a buffer by
2566 means of the @code{local-map} property. The property's value for the
2567 character after point, if non-@code{nil}, is used for key lookup instead
2568 of the buffer's local map. If the property value is a symbol, the
2569 symbol's function definition is used as the keymap. @xref{Active
2573 The @code{syntax-table} property overrides what the syntax table says
2574 about this particular character. @xref{Syntax Properties}.
2577 @cindex read-only character
2578 @kindex read-only @r{(text property)}
2579 If a character has the property @code{read-only}, then modifying that
2580 character is not allowed. Any command that would do so gets an error.
2582 Insertion next to a read-only character is an error if inserting
2583 ordinary text there would inherit the @code{read-only} property due to
2584 stickiness. Thus, you can control permission to insert next to
2585 read-only text by controlling the stickiness. @xref{Sticky Properties}.
2587 Since changing properties counts as modifying the buffer, it is not
2588 possible to remove a @code{read-only} property unless you know the
2589 special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
2590 and then remove the property. @xref{Read Only Buffers}.
2593 @kindex invisible @r{(text property)}
2594 A non-@code{nil} @code{invisible} property can make a character invisible
2595 on the screen. @xref{Invisible Text}, for details.
2598 @kindex intangible @r{(text property)}
2599 If a group of consecutive characters have equal and non-@code{nil}
2600 @code{intangible} properties, then you cannot place point between them.
2601 If you try to move point forward into the group, point actually moves to
2602 the end of the group. If you try to move point backward into the group,
2603 point actually moves to the start of the group.
2605 When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
2606 the @code{intangible} property is ignored.
2608 @item modification-hooks
2609 @cindex change hooks for a character
2610 @cindex hooks for changing a character
2611 @kindex modification-hooks @r{(text property)}
2612 If a character has the property @code{modification-hooks}, then its
2613 value should be a list of functions; modifying that character calls all
2614 of those functions. Each function receives two arguments: the beginning
2615 and end of the part of the buffer being modified. Note that if a
2616 particular modification hook function appears on several characters
2617 being modified by a single primitive, you can't predict how many times
2618 the function will be called.
2620 @item insert-in-front-hooks
2621 @itemx insert-behind-hooks
2622 @kindex insert-in-front-hooks @r{(text property)}
2623 @kindex insert-behind-hooks @r{(text property)}
2624 The operation of inserting text in a buffer also calls the functions
2625 listed in the @code{insert-in-front-hooks} property of the following
2626 character and in the @code{insert-behind-hooks} property of the
2627 preceding character. These functions receive two arguments, the
2628 beginning and end of the inserted text. The functions are called
2629 @emph{after} the actual insertion takes place.
2631 See also @ref{Change Hooks}, for other hooks that are called
2632 when you change text in a buffer.
2636 @cindex hooks for motion of point
2637 @kindex point-entered @r{(text property)}
2638 @kindex point-left @r{(text property)}
2639 The special properties @code{point-entered} and @code{point-left}
2640 record hook functions that report motion of point. Each time point
2641 moves, Emacs compares these two property values:
2645 the @code{point-left} property of the character after the old location,
2648 the @code{point-entered} property of the character after the new
2653 If these two values differ, each of them is called (if not @code{nil})
2654 with two arguments: the old value of point, and the new one.
2656 The same comparison is made for the characters before the old and new
2657 locations. The result may be to execute two @code{point-left} functions
2658 (which may be the same function) and/or two @code{point-entered}
2659 functions (which may be the same function). In any case, all the
2660 @code{point-left} functions are called first, followed by all the
2661 @code{point-entered} functions.
2663 It is possible using @code{char-after} to examine characters at various
2664 positions without moving point to those positions. Only an actual
2665 change in the value of point runs these hook functions.
2668 @defvar inhibit-point-motion-hooks
2669 When this variable is non-@code{nil}, @code{point-left} and
2670 @code{point-entered} hooks are not run, and the @code{intangible}
2671 property has no effect. Do not set this variable globally; bind it with
2675 @node Format Properties
2676 @subsection Formatted Text Properties
2678 These text properties affect the behavior of the fill commands. They
2679 are used for representing formatted text. @xref{Filling}, and
2684 If a newline character has this property, it is a ``hard'' newline.
2685 The fill commands do not alter hard newlines and do not move words
2686 across them. However, this property takes effect only if the variable
2687 @code{use-hard-newlines} is non-@code{nil}.
2690 This property specifies an extra right margin for filling this part of the
2694 This property specifies an extra left margin for filling this part of the
2698 This property specifies the style of justification for filling this part
2702 @node Sticky Properties
2703 @subsection Stickiness of Text Properties
2704 @cindex sticky text properties
2705 @cindex inheritance of text properties
2707 Self-inserting characters normally take on the same properties as the
2708 preceding character. This is called @dfn{inheritance} of properties.
2710 In a Lisp program, you can do insertion with inheritance or without,
2711 depending on your choice of insertion primitive. The ordinary text
2712 insertion functions such as @code{insert} do not inherit any properties.
2713 They insert text with precisely the properties of the string being
2714 inserted, and no others. This is correct for programs that copy text
2715 from one context to another---for example, into or out of the kill ring.
2716 To insert with inheritance, use the special primitives described in this
2717 section. Self-inserting characters inherit properties because they work
2718 using these primitives.
2720 When you do insertion with inheritance, @emph{which} properties are
2721 inherited depends on two specific properties: @code{front-sticky} and
2722 @code{rear-nonsticky}.
2724 Insertion after a character inherits those of its properties that are
2725 @dfn{rear-sticky}. Insertion before a character inherits those of its
2726 properties that are @dfn{front-sticky}. By default, a text property is
2727 rear-sticky but not front-sticky. Thus, the default is to inherit all
2728 the properties of the preceding character, and nothing from the
2729 following character. You can request different behavior by specifying
2730 the stickiness of certain properties.
2732 If a character's @code{front-sticky} property is @code{t}, then all
2733 its properties are front-sticky. If the @code{front-sticky} property is
2734 a list, then the sticky properties of the character are those whose
2735 names are in the list. For example, if a character has a
2736 @code{front-sticky} property whose value is @code{(face read-only)},
2737 then insertion before the character can inherit its @code{face} property
2738 and its @code{read-only} property, but no others.
2740 The @code{rear-nonsticky} works the opposite way. Every property is
2741 rear-sticky by default, so the @code{rear-nonsticky} property says which
2742 properties are @emph{not} rear-sticky. If a character's
2743 @code{rear-nonsticky} property is @code{t}, then none of its properties
2744 are rear-sticky. If the @code{rear-nonsticky} property is a list,
2745 properties are rear-sticky @emph{unless} their names are in the list.
2747 When you insert text with inheritance, it inherits all the rear-sticky
2748 properties of the preceding character, and all the front-sticky
2749 properties of the following character. The previous character's
2750 properties take precedence when both sides offer different sticky values
2751 for the same property.
2753 Here are the functions that insert text with inheritance of properties:
2755 @defun insert-and-inherit &rest strings
2756 Insert the strings @var{strings}, just like the function @code{insert},
2757 but inherit any sticky properties from the adjoining text.
2760 @defun insert-before-markers-and-inherit &rest strings
2761 Insert the strings @var{strings}, just like the function
2762 @code{insert-before-markers}, but inherit any sticky properties from the
2766 @xref{Insertion}, for the ordinary insertion functions which do not
2769 @node Saving Properties
2770 @subsection Saving Text Properties in Files
2771 @cindex text properties in files
2772 @cindex saving text properties
2774 You can save text properties in files (along with the text itself),
2775 and restore the same text properties when visiting or inserting the
2776 files, using these two hooks:
2778 @defvar write-region-annotate-functions
2779 This variable's value is a list of functions for @code{write-region} to
2780 run to encode text properties in some fashion as annotations to the text
2781 being written in the file. @xref{Writing to Files}.
2783 Each function in the list is called with two arguments: the start and
2784 end of the region to be written. These functions should not alter the
2785 contents of the buffer. Instead, they should return lists indicating
2786 annotations to write in the file in addition to the text in the
2789 Each function should return a list of elements of the form
2790 @code{(@var{position} . @var{string})}, where @var{position} is an
2791 integer specifying the relative position within the text to be written,
2792 and @var{string} is the annotation to add there.
2794 Each list returned by one of these functions must be already sorted in
2795 increasing order by @var{position}. If there is more than one function,
2796 @code{write-region} merges the lists destructively into one sorted list.
2798 When @code{write-region} actually writes the text from the buffer to the
2799 file, it intermixes the specified annotations at the corresponding
2800 positions. All this takes place without modifying the buffer.
2803 @defvar after-insert-file-functions
2804 This variable holds a list of functions for @code{insert-file-contents}
2805 to call after inserting a file's contents. These functions should scan
2806 the inserted text for annotations, and convert them to the text
2807 properties they stand for.
2809 Each function receives one argument, the length of the inserted text;
2810 point indicates the start of that text. The function should scan that
2811 text for annotations, delete them, and create the text properties that
2812 the annotations specify. The function should return the updated length
2813 of the inserted text, as it stands after those changes. The value
2814 returned by one function becomes the argument to the next function.
2816 These functions should always return with point at the beginning of
2819 The intended use of @code{after-insert-file-functions} is for converting
2820 some sort of textual annotations into actual text properties. But other
2821 uses may be possible.
2824 We invite users to write Lisp programs to store and retrieve text
2825 properties in files, using these hooks, and thus to experiment with
2826 various data formats and find good ones. Eventually we hope users
2827 will produce good, general extensions we can install in Emacs.
2829 We suggest not trying to handle arbitrary Lisp objects as text property
2830 names or values---because a program that general is probably difficult
2831 to write, and slow. Instead, choose a set of possible data types that
2832 are reasonably flexible, and not too hard to encode.
2834 @xref{Format Conversion}, for a related feature.
2836 @c ??? In next edition, merge this info Format Conversion.
2838 @node Lazy Properties
2839 @subsection Lazy Computation of Text Properties
2841 Instead of computing text properties for all the text in the buffer,
2842 you can arrange to compute the text properties for parts of the text
2843 when and if something depends on them.
2845 The primitive that extracts text from the buffer along with its
2846 properties is @code{buffer-substring}. Before examining the properties,
2847 this function runs the abnormal hook @code{buffer-access-fontify-functions}.
2849 @defvar buffer-access-fontify-functions
2850 This variable holds a list of functions for computing text properties.
2851 Before @code{buffer-substring} copies the text and text properties for a
2852 portion of the buffer, it calls all the functions in this list. Each of
2853 the functions receives two arguments that specify the range of the
2854 buffer being accessed. (The buffer itself is always the current
2858 The function @code{buffer-substring-no-properties} does not call these
2859 functions, since it ignores text properties anyway.
2861 In order to prevent the hook functions from being called more than
2862 once for the same part of the buffer, you can use the variable
2863 @code{buffer-access-fontified-property}.
2865 @defvar buffer-access-fontified-property
2866 If this value's variable is non-@code{nil}, it is a symbol which is used
2867 as a text property name. A non-@code{nil} value for that text property
2868 means, ``the other text properties for this character have already been
2871 If all the characters in the range specified for @code{buffer-substring}
2872 have a non-@code{nil} value for this property, @code{buffer-substring}
2873 does not call the @code{buffer-access-fontify-functions} functions. It
2874 assumes these characters already have the right text properties, and
2875 just copies the properties they already have.
2877 The normal way to use this feature is that the
2878 @code{buffer-access-fontify-functions} functions add this property, as
2879 well as others, to the characters they operate on. That way, they avoid
2880 being called over and over for the same text.
2883 @node Clickable Text
2884 @subsection Defining Clickable Text
2885 @cindex clickable text
2887 There are two ways to set up @dfn{clickable text} in a buffer.
2888 There are typically two parts of this: to make the text highlight
2889 when the mouse is over it, and to make a mouse button do something
2890 when you click it on that part of the text.
2892 Highlighting is done with the @code{mouse-face} text property.
2893 Here is an example of how Dired does it:
2897 (if (dired-move-to-filename)
2898 (put-text-property (point)
2900 (dired-move-to-end-of-filename)
2902 'mouse-face 'highlight))
2907 The first two arguments to @code{put-text-property} specify the
2908 beginning and end of the text.
2910 The usual way to make the mouse do something when you click it
2911 on this text is to define @code{mouse-2} in the major mode's
2912 keymap. The job of checking whether the click was on clickable text
2913 is done by the command definition. Here is how Dired does it:
2916 (defun dired-mouse-find-file-other-window (event)
2917 "In dired, visit the file or directory name you click on."
2921 (set-buffer (window-buffer (posn-window (event-end event))))
2923 (goto-char (posn-point (event-end event)))
2924 (setq file (dired-get-filename))))
2925 (select-window (posn-window (event-end event)))
2926 (find-file-other-window (file-name-sans-versions file t))))
2930 The reason for the outer @code{save-excursion} construct is to avoid
2931 changing the current buffer; the reason for the inner one is to avoid
2932 permanently altering point in the buffer you click on. In this case,
2933 Dired uses the function @code{dired-get-filename} to determine which
2934 file to visit, based on the position found in the event.
2936 Instead of defining a mouse command for the major mode, you can define
2937 a key binding for the clickable text itself, using the @code{local-map}
2941 (let ((map (make-sparse-keymap)))
2942 (define-key-binding map [mouse-2] 'operate-this-button)
2943 (put-text-property (point)
2945 (dired-move-to-end-of-filename)
2951 This method makes it possible to define different commands for various
2952 clickable pieces of text. Also, the major mode definition (or the
2953 global definition) remains available for the rest of the text in the
2957 @subsection Why Text Properties are not Intervals
2960 Some editors that support adding attributes to text in the buffer do
2961 so by letting the user specify ``intervals'' within the text, and adding
2962 the properties to the intervals. Those editors permit the user or the
2963 programmer to determine where individual intervals start and end. We
2964 deliberately provided a different sort of interface in Emacs Lisp to
2965 avoid certain paradoxical behavior associated with text modification.
2967 If the actual subdivision into intervals is meaningful, that means you
2968 can distinguish between a buffer that is just one interval with a
2969 certain property, and a buffer containing the same text subdivided into
2970 two intervals, both of which have that property.
2972 Suppose you take the buffer with just one interval and kill part of
2973 the text. The text remaining in the buffer is one interval, and the
2974 copy in the kill ring (and the undo list) becomes a separate interval.
2975 Then if you yank back the killed text, you get two intervals with the
2976 same properties. Thus, editing does not preserve the distinction
2977 between one interval and two.
2979 Suppose we ``fix'' this problem by coalescing the two intervals when
2980 the text is inserted. That works fine if the buffer originally was a
2981 single interval. But suppose instead that we have two adjacent
2982 intervals with the same properties, and we kill the text of one interval
2983 and yank it back. The same interval-coalescence feature that rescues
2984 the other case causes trouble in this one: after yanking, we have just
2985 one interval. One again, editing does not preserve the distinction
2986 between one interval and two.
2988 Insertion of text at the border between intervals also raises
2989 questions that have no satisfactory answer.
2991 However, it is easy to arrange for editing to behave consistently for
2992 questions of the form, ``What are the properties of this character?''
2993 So we have decided these are the only questions that make sense; we have
2994 not implemented asking questions about where intervals start or end.
2996 In practice, you can usually use the text property search functions in
2997 place of explicit interval boundaries. You can think of them as finding
2998 the boundaries of intervals, assuming that intervals are always
2999 coalesced whenever possible. @xref{Property Search}.
3001 Emacs also provides explicit intervals as a presentation feature; see
3005 @section Substituting for a Character Code
3007 The following functions replace characters within a specified region
3008 based on their character codes.
3010 @defun subst-char-in-region start end old-char new-char &optional noundo
3011 @cindex replace characters
3012 This function replaces all occurrences of the character @var{old-char}
3013 with the character @var{new-char} in the region of the current buffer
3014 defined by @var{start} and @var{end}.
3016 @cindex Outline mode
3017 @cindex undo avoidance
3018 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
3019 not record the change for undo and does not mark the buffer as modified.
3020 This feature is used for controlling selective display (@pxref{Selective
3023 @code{subst-char-in-region} does not move point and returns
3028 ---------- Buffer: foo ----------
3029 This is the contents of the buffer before.
3030 ---------- Buffer: foo ----------
3034 (subst-char-in-region 1 20 ?i ?X)
3037 ---------- Buffer: foo ----------
3038 ThXs Xs the contents of the buffer before.
3039 ---------- Buffer: foo ----------
3044 @defun translate-region start end table
3045 This function applies a translation table to the characters in the
3046 buffer between positions @var{start} and @var{end}.
3048 The translation table @var{table} is a string; @code{(aref @var{table}
3049 @var{ochar})} gives the translated character corresponding to
3050 @var{ochar}. If the length of @var{table} is less than 256, any
3051 characters with codes larger than the length of @var{table} are not
3052 altered by the translation.
3054 The return value of @code{translate-region} is the number of
3055 characters that were actually changed by the translation. This does
3056 not count characters that were mapped into themselves in the
3064 A register is a sort of variable used in Emacs editing that can hold a
3065 variety of different kinds of values. Each register is named by a
3066 single character. All ASCII characters and their meta variants (but
3067 with the exception of @kbd{C-g}) can be used to name registers. Thus,
3068 there are 255 possible registers. A register is designated in Emacs
3069 Lisp by the character that is its name.
3071 @defvar register-alist
3072 This variable is an alist of elements of the form @code{(@var{name} .
3073 @var{contents})}. Normally, there is one element for each Emacs
3074 register that has been used.
3076 The object @var{name} is a character (an integer) identifying the
3080 The @var{contents} of a register can have several possible types:
3084 A number stands for itself. If @code{insert-register} finds a number
3085 in the register, it converts the number to decimal.
3088 A marker represents a buffer position to jump to.
3091 A string is text saved in the register.
3094 A rectangle is represented by a list of strings.
3096 @item @code{(@var{window-configuration} @var{position})}
3097 This represents a window configuration to restore in one frame, and a
3098 position to jump to in the current buffer.
3100 @item @code{(@var{frame-configuration} @var{position})}
3101 This represents a frame configuration to restore, and a position
3102 to jump to in the current buffer.
3104 @item (file @var{filename})
3105 This represents a file to visit; jumping to this value visits file
3108 @item (file-query @var{filename} @var{position})
3109 This represents a file to visit and a position in it; jumping to this
3110 value visits file @var{filename} and goes to buffer position
3111 @var{position}. Restoring this type of position asks the user for
3115 The functions in this section return unpredictable values unless
3118 @defun get-register reg
3119 This function returns the contents of the register
3120 @var{reg}, or @code{nil} if it has no contents.
3123 @defun set-register reg value
3124 This function sets the contents of register @var{reg} to @var{value}.
3125 A register can be set to any value, but the other register functions
3126 expect only certain data types. The return value is @var{value}.
3129 @deffn Command view-register reg
3130 This command displays what is contained in register @var{reg}.
3134 @deffn Command point-to-register reg
3135 This command stores both the current location of point and the current
3136 buffer in register @var{reg} as a marker.
3139 @deffn Command jump-to-register reg
3140 @deffnx Command register-to-point reg
3141 @comment !!SourceFile register.el
3142 This command restores the status recorded in register @var{reg}.
3144 If @var{reg} contains a marker, it moves point to the position stored in
3145 the marker. Since both the buffer and the location within the buffer
3146 are stored by the @code{point-to-register} function, this command can
3147 switch you to another buffer.
3149 If @var{reg} contains a window configuration or a frame configuration.
3150 @code{jump-to-register} restores that configuration.
3154 @deffn Command insert-register reg &optional beforep
3155 This command inserts contents of register @var{reg} into the current
3158 Normally, this command puts point before the inserted text, and the
3159 mark after it. However, if the optional second argument @var{beforep}
3160 is non-@code{nil}, it puts the mark before and point after.
3161 You can pass a non-@code{nil} second argument @var{beforep} to this
3162 function interactively by supplying any prefix argument.
3164 If the register contains a rectangle, then the rectangle is inserted
3165 with its upper left corner at point. This means that text is inserted
3166 in the current line and underneath it on successive lines.
3168 If the register contains something other than saved text (a string) or
3169 a rectangle (a list), currently useless things happen. This may be
3170 changed in the future.
3174 @deffn Command copy-to-register reg start end &optional delete-flag
3175 This command copies the region from @var{start} to @var{end} into
3176 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
3177 the region from the buffer after copying it into the register.
3180 @deffn Command prepend-to-register reg start end &optional delete-flag
3181 This command prepends the region from @var{start} to @var{end} into
3182 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
3183 the region from the buffer after copying it to the register.
3186 @deffn Command append-to-register reg start end &optional delete-flag
3187 This command appends the region from @var{start} to @var{end} to the
3188 text already in register @var{reg}. If @var{delete-flag} is
3189 non-@code{nil}, it deletes the region from the buffer after copying it
3193 @deffn Command copy-rectangle-to-register reg start end &optional delete-flag
3194 This command copies a rectangular region from @var{start} to @var{end}
3195 into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it
3196 deletes the region from the buffer after copying it to the register.
3199 @deffn Command window-configuration-to-register reg
3200 This function stores the window configuration of the selected frame in
3204 @deffn Command frame-configuration-to-register reg
3205 This function stores the current frame configuration in register
3211 @section Transposition of Text
3213 This subroutine is used by the transposition commands.
3215 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
3216 This function exchanges two nonoverlapping portions of the buffer.
3217 Arguments @var{start1} and @var{end1} specify the bounds of one portion
3218 and arguments @var{start2} and @var{end2} specify the bounds of the
3221 Normally, @code{transpose-regions} relocates markers with the transposed
3222 text; a marker previously positioned within one of the two transposed
3223 portions moves along with that portion, thus remaining between the same
3224 two characters in their new position. However, if @var{leave-markers}
3225 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
3226 all markers unrelocated.
3230 @section Base 64 Encoding
3231 @cindex base 64 encoding
3233 Base 64 code is used in email to encode a sequence of 8-bit bytes as a
3234 longer sequence of @sc{ASCII} graphic characters. This section
3235 describes the functions for converting to and from this code.
3237 @defun base64-encode-region beg end &optional no-line-break
3238 @tindex base64-encode-region
3239 This function converts the region from @var{beg} to @var{end}
3240 into base 64 code. It returns the length of the encoded text.
3242 Normally, this function inserts newline characters into the encoded
3243 text, to avoid overlong lines. However, if the optional argument
3244 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
3245 the output is just one long line.
3248 @defun base64-encode-string string &optional no-line-break
3249 @tindex base64-encode-string
3250 This function converts the string @var{string} into base 64 code. It
3251 returns a string containing the encoded text.
3253 Normally, this function inserts newline characters into the encoded
3254 text, to avoid overlong lines. However, if the optional argument
3255 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
3256 the result string is just one long line.
3259 @defun base64-decode-region beg end
3260 @tindex base64-decode-region
3261 This function converts the region from @var{beg} to @var{end} from base
3262 64 code into the corresponding decoded text. It returns the length of
3265 The decoding functions ignore newline characters in the encoded text.
3268 @defun base64-decode-string string
3269 @tindex base64-decode-string
3270 This function converts the string @var{string} from base 64 code into
3271 the corresponding decoded text. It returns a string containing the
3274 The decoding functions ignore newline characters in the encoded text.
3278 @section Change Hooks
3279 @cindex change hooks
3280 @cindex hooks for text changes
3282 These hook variables let you arrange to take notice of all changes in
3283 all buffers (or in a particular buffer, if you make them buffer-local).
3284 See also @ref{Special Properties}, for how to detect changes to specific
3287 The functions you use in these hooks should save and restore the match
3288 data if they do anything that uses regular expressions; otherwise, they
3289 will interfere in bizarre ways with the editing operations that call
3292 @defvar before-change-functions
3293 This variable holds a list of functions to call before any buffer
3294 modification. Each function gets two arguments, the beginning and end
3295 of the region that is about to change, represented as integers. The
3296 buffer that is about to change is always the current buffer.
3299 @defvar after-change-functions
3300 This variable holds a list of functions to call after any buffer
3301 modification. Each function receives three arguments: the beginning and
3302 end of the region just changed, and the length of the text that existed
3303 before the change. All three arguments are integers. The buffer that's
3304 about to change is always the current buffer.
3306 The length of the old text is the difference between the buffer positions
3307 before and after that text as it was before the change. As for the
3308 changed text, its length is simply the difference between the first two
3312 @defmac combine-after-change-calls body...
3313 @tindex combine-after-change-calls
3314 The macro executes @var{body} normally, but arranges to call the
3315 after-change functions just once for a series of several changes---if
3318 If a program makes several text changes in the same area of the buffer,
3319 using the macro @code{combine-after-change-calls} around that part of
3320 the program can make it run considerably faster when after-change hooks
3321 are in use. When the after-change hooks are ultimately called, the
3322 arguments specify a portion of the buffer including all of the changes
3323 made within the @code{combine-after-change-calls} body.
3325 @strong{Warning:} You must not alter the values of
3326 @code{after-change-functions} and @code{after-change-function} within
3327 the body of a @code{combine-after-change-calls} form.
3329 @strong{Note:} If the changes you combine occur in widely scattered
3330 parts of the buffer, this will still work, but it is not advisable,
3331 because it may lead to inefficient behavior for some change hook
3335 @defvar before-change-function
3336 This obsolete variable holds one function to call before any buffer
3337 modification (or @code{nil} for no function). It is called just like
3338 the functions in @code{before-change-functions}.
3341 @defvar after-change-function
3342 This obsolete variable holds one function to call after any buffer modification
3343 (or @code{nil} for no function). It is called just like the functions in
3344 @code{after-change-functions}.
3347 The four variables above are temporarily bound to @code{nil} during the
3348 time that any of these functions is running. This means that if one of
3349 these functions changes the buffer, that change won't run these
3350 functions. If you do want a hook function to make changes that run
3351 these functions, make it bind these variables back to their usual
3354 One inconvenient result of this protective feature is that you cannot
3355 have a function in @code{after-change-functions} or
3356 @code{before-change-functions} which changes the value of that variable.
3357 But that's not a real limitation. If you want those functions to change
3358 the list of functions to run, simply add one fixed function to the hook,
3359 and code that function to look in another variable for other functions
3360 to call. Here is an example:
3363 (setq my-own-after-change-functions nil)
3364 (defun indirect-after-change-function (beg end len)
3365 (let ((list my-own-after-change-functions))
3367 (funcall (car list) beg end len)
3368 (setq list (cdr list)))))
3371 (add-hooks 'after-change-functions
3372 'indirect-after-change-function)
3376 @defvar first-change-hook
3377 This variable is a normal hook that is run whenever a buffer is changed
3378 that was previously in the unmodified state.