2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/text.info
6 @node Text, Searching and Matching, 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 in the vicinity of point. Many are interactive. All the
13 functions that change the text provide for undoing the changes
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).
32 * Near Point:: Examining text in the vicinity of point.
33 * Buffer Contents:: Examining text in a general fashion.
34 * Comparing Text:: Comparing substrings of buffers.
35 * Insertion:: Adding new text to a buffer.
36 * Commands for Insertion:: User-level commands to insert text.
37 * Deletion:: Removing text from a buffer.
38 * User-Level Deletion:: User-level commands to delete text.
39 * The Kill Ring:: Where removed text sometimes is saved for later use.
40 * Undo:: Undoing changes to the text of a buffer.
41 * Maintaining Undo:: How to enable and disable undo information.
42 How to control how much information is kept.
43 * Filling:: Functions for explicit filling.
44 * Margins:: How to specify margins for filling commands.
45 * Auto Filling:: How auto-fill mode is implemented to break lines.
46 * Sorting:: Functions for sorting parts of the buffer.
47 * Columns:: Computing horizontal positions, and using them.
48 * Indentation:: Functions to insert or adjust indentation.
49 * Case Changes:: Case conversion of parts of the buffer.
50 * Text Properties:: Assigning Lisp property lists to text characters.
51 * Substitution:: Replacing a given character wherever it appears.
52 * Registers:: How registers are implemented. Accessing the text or
53 position stored in a register.
54 * Transposition:: Swapping two portions of a buffer.
55 * Change Hooks:: Supplying functions to be run when text is changed.
56 * Transformations:: MD5 and base64 support.
60 @section Examining Text Near Point
62 Many functions are provided to look at the characters around point.
63 Several simple functions are described here. See also @code{looking-at}
64 in @ref{Regexp Search}.
66 Many of these functions take an optional @var{buffer} argument.
67 In all such cases, the current buffer will be used if this argument
68 is omitted. (In FSF Emacs, and earlier versions of XEmacs, these
69 functions usually did not have these optional @var{buffer} arguments
70 and always operated on the current buffer.)
73 @defun char-after &optional position buffer
74 This function returns the character in the buffer at (i.e.,
75 immediately after) position @var{position}. If @var{position} is out of
76 range for this purpose, either before the beginning of the buffer, or at
77 or beyond the end, then the value is @code{nil}. The default for
78 @var{position} is point. If optional argument @var{buffer} is
79 @code{nil}, the current buffer is assumed.
81 In the following example, assume that the first character in the
86 (char-to-string (char-after 1))
92 @defun char-before &optional position buffer
93 This function returns the character in the current buffer immediately
94 before position @var{position}. If @var{position} is out of range for
95 this purpose, either at or before the beginning of the buffer, or beyond
96 the end, then the value is @code{nil}. The default for
97 @var{position} is point. If optional argument @var{buffer} is
98 @code{nil}, the current buffer is assumed.
101 @defun following-char &optional buffer
102 This function returns the character following point in the buffer.
103 This is similar to @code{(char-after (point))}. However, if point is at
104 the end of the buffer, then the result of @code{following-char} is 0.
105 If optional argument @var{buffer} is @code{nil}, the current buffer is
108 Remember that point is always between characters, and the terminal
109 cursor normally appears over the character following point. Therefore,
110 the character returned by @code{following-char} is the character the
113 In this example, point is between the @samp{a} and the @samp{c}.
117 ---------- Buffer: foo ----------
118 Gentlemen may cry ``Pea@point{}ce! Peace!,''
119 but there is no peace.
120 ---------- Buffer: foo ----------
124 (char-to-string (preceding-char))
126 (char-to-string (following-char))
132 @defun preceding-char &optional buffer
133 This function returns the character preceding point in the buffer.
134 See above, under @code{following-char}, for an example. If
135 point is at the beginning of the buffer, @code{preceding-char} returns
136 0. If optional argument @var{buffer} is @code{nil}, the current buffer
140 @defun bobp &optional buffer
141 This function returns @code{t} if point is at the beginning of the
142 buffer. If narrowing is in effect, this means the beginning of the
143 accessible portion of the text. If optional argument @var{buffer} is
144 @code{nil}, the current buffer is assumed. See also @code{point-min} in
148 @defun eobp &optional buffer
149 This function returns @code{t} if point is at the end of the buffer.
150 If narrowing is in effect, this means the end of accessible portion of
151 the text. If optional argument @var{buffer} is @code{nil}, the current
152 buffer is assumed. See also @code{point-max} in @xref{Point}.
155 @defun bolp &optional buffer
156 This function returns @code{t} if point is at the beginning of a line.
157 If optional argument @var{buffer} is @code{nil}, the current buffer is
158 assumed. @xref{Text Lines}. The beginning of the buffer (or its
159 accessible portion) always counts as the beginning of a line.
162 @defun eolp &optional buffer
163 This function returns @code{t} if point is at the end of a line. The
164 end of the buffer is always considered the end of a line. If optional
165 argument @var{buffer} is @code{nil}, the current buffer is assumed.
166 The end of the buffer (or of its accessible portion) is always considered
170 @node Buffer Contents
171 @section Examining Buffer Contents
173 This section describes two functions that allow a Lisp program to
174 convert any portion of the text in the buffer into a string.
176 @defun buffer-substring start end &optional buffer
177 @defunx buffer-string start end &optional buffer
178 These functions are equivalent and return a string containing a copy of
179 the text of the region defined by positions @var{start} and @var{end} in
180 the buffer. If the arguments are not positions in the accessible
181 portion of the buffer, @code{buffer-substring} signals an
182 @code{args-out-of-range} error. If optional argument @var{buffer} is
183 @code{nil}, the current buffer is assumed.
186 If the region delineated by @var{start} and @var{end} contains
187 duplicable extents, they will be remembered in the string.
188 @xref{Duplicable Extents}.
190 It is not necessary for @var{start} to be less than @var{end}; the
191 arguments can be given in either order. But most often the smaller
192 argument is written first.
196 ---------- Buffer: foo ----------
197 This is the contents of buffer foo
199 ---------- Buffer: foo ----------
203 (buffer-substring 1 10)
204 @result{} "This is t"
207 (buffer-substring (point-max) 10)
208 @result{} "he contents of buffer foo
215 @c `equal' in XEmacs does not compare text properties on strings
216 @defun buffer-substring-without-properties start end
217 This is like @code{buffer-substring}, except that it does not copy text
218 properties, just the characters themselves. @xref{Text Properties}.
219 Here's an example of using this function to get a word to look up in an
224 (assoc (buffer-substring start end)
225 '(("wood" . t) ("paper" . t)
226 ("steel" . nil) ("asbestos" . nil))))
229 If this were written using @code{buffer-substring} instead, it would not
230 work reliably; any text properties that happened to be in the word
231 copied from the buffer would make the comparisons fail.
236 @section Comparing Text
237 @cindex comparing buffer text
239 This function lets you compare portions of the text in a buffer, without
240 copying them into strings first.
242 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
243 This function lets you compare two substrings of the same buffer or two
244 different buffers. The first three arguments specify one substring,
245 giving a buffer and two positions within the buffer. The last three
246 arguments specify the other substring in the same way. You can use
247 @code{nil} for @var{buffer1}, @var{buffer2}, or both to stand for the
250 The value is negative if the first substring is less, positive if the
251 first is greater, and zero if they are equal. The absolute value of
252 the result is one plus the index of the first differing characters
253 within the substrings.
255 This function ignores case when comparing characters
256 if @code{case-fold-search} is non-@code{nil}. It always ignores
259 Suppose the current buffer contains the text @samp{foobarbar
260 haha!rara!}; then in this example the two substrings are @samp{rbar }
261 and @samp{rara!}. The value is 2 because the first substring is greater
262 at the second character.
265 (compare-buffer-substring nil 6 11 nil 16 21)
271 @section Inserting Text
272 @cindex insertion of text
273 @cindex text insertion
275 @dfn{Insertion} means adding new text to a buffer. The inserted text
276 goes at point---between the character before point and the character
279 Insertion relocates markers that point at positions after the
280 insertion point, so that they stay with the surrounding text
281 (@pxref{Markers}). When a marker points at the place of insertion,
282 insertion normally doesn't relocate the marker, so that it points to the
283 beginning of the inserted text; however, certain special functions such
284 as @code{insert-before-markers} relocate such markers to point after the
287 @cindex insertion before point
288 @cindex before point, insertion
289 Some insertion functions leave point before the inserted text, while
290 other functions leave it after. We call the former insertion @dfn{after
291 point} and the latter insertion @dfn{before point}.
294 If a string with non-@code{nil} extent data is inserted, the remembered
295 extents will also be inserted. @xref{Duplicable Extents}.
297 Insertion functions signal an error if the current buffer is
300 These functions copy text characters from strings and buffers along
301 with their properties. The inserted characters have exactly the same
302 properties as the characters they were copied from. By contrast,
303 characters specified as separate arguments, not part of a string or
304 buffer, inherit their text properties from the neighboring text.
306 @defun insert &rest args
307 This function inserts the strings and/or characters @var{args} into the
308 current buffer, at point, moving point forward. In other words, it
309 inserts the text before point. An error is signaled unless all
310 @var{args} are either strings or characters. The value is @code{nil}.
313 @defun insert-before-markers &rest args
314 This function inserts the strings and/or characters @var{args} into the
315 current buffer, at point, moving point forward. An error is signaled
316 unless all @var{args} are either strings or characters. The value is
319 This function is unlike the other insertion functions in that it
320 relocates markers initially pointing at the insertion point, to point
321 after the inserted text.
324 @defun insert-string string &optional buffer
325 This function inserts @var{string} into @var{buffer} before point.
326 @var{buffer} defaults to the current buffer if omitted. This
327 function is chiefly useful if you want to insert a string in
328 a buffer other than the current one (otherwise you could just
332 @defun insert-char character count &optional buffer
333 This function inserts @var{count} instances of @var{character} into
334 @var{buffer} before point. @var{count} must be a number, and
335 @var{character} must be a character. The value is @code{nil}. If
336 optional argument @var{buffer} is @code{nil}, the current buffer is
337 assumed. (In FSF Emacs, the third argument is called @var{inherit}
338 and refers to text properties.)
341 @defun insert-buffer-substring from-buffer-or-name &optional start end
342 This function inserts a portion of buffer @var{from-buffer-or-name}
343 (which must already exist) into the current buffer before point. The
344 text inserted is the region from @var{start} and @var{end}. (These
345 arguments default to the beginning and end of the accessible portion of
346 that buffer.) This function returns @code{nil}.
348 In this example, the form is executed with buffer @samp{bar} as the
349 current buffer. We assume that buffer @samp{bar} is initially empty.
353 ---------- Buffer: foo ----------
354 We hold these truths to be self-evident, that all
355 ---------- Buffer: foo ----------
359 (insert-buffer-substring "foo" 1 20)
362 ---------- Buffer: bar ----------
363 We hold these truth@point{}
364 ---------- Buffer: bar ----------
369 @node Commands for Insertion
370 @section User-Level Insertion Commands
372 This section describes higher-level commands for inserting text,
373 commands intended primarily for the user but useful also in Lisp
376 @deffn Command insert-buffer from-buffer-or-name
377 This command inserts the entire contents of @var{from-buffer-or-name}
378 (which must exist) into the current buffer after point. It leaves
379 the mark after the inserted text. The value is @code{nil}.
382 @deffn Command self-insert-command count
383 @cindex character insertion
384 @cindex self-insertion
385 This command inserts the last character typed; it does so @var{count}
386 times, before point, and returns @code{nil}. Most printing characters
387 are bound to this command. In routine use, @code{self-insert-command}
388 is the most frequently called function in XEmacs, but programs rarely use
389 it except to install it on a keymap.
391 In an interactive call, @var{count} is the numeric prefix argument.
393 This command calls @code{auto-fill-function} whenever that is
394 non-@code{nil} and the character inserted is a space or a newline
395 (@pxref{Auto Filling}).
397 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
398 This command performs abbrev expansion if Abbrev mode is enabled and
399 the inserted character does not have word-constituent
400 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
402 This is also responsible for calling @code{blink-paren-function} when
403 the inserted character has close parenthesis syntax (@pxref{Blinking}).
406 @deffn Command newline &optional number-of-newlines
407 This command inserts newlines into the current buffer before point.
408 If @var{number-of-newlines} is supplied, that many newline characters
411 @cindex newline and Auto Fill mode
412 This function calls @code{auto-fill-function} if the current column
413 number is greater than the value of @code{fill-column} and
414 @var{number-of-newlines} is @code{nil}. Typically what
415 @code{auto-fill-function} does is insert a newline; thus, the overall
416 result in this case is to insert two newlines at different places: one
417 at point, and another earlier in the line. @code{newline} does not
418 auto-fill if @var{number-of-newlines} is non-@code{nil}.
420 This command indents to the left margin if that is not zero.
423 The value returned is @code{nil}. In an interactive call, @var{count}
424 is the numeric prefix argument.
427 @deffn Command split-line
428 This command splits the current line, moving the portion of the line
429 after point down vertically so that it is on the next line directly
430 below where it was before. Whitespace is inserted as needed at the
431 beginning of the lower line, using the @code{indent-to} function.
432 @code{split-line} returns the position of point.
434 Programs hardly ever use this function.
437 @defvar overwrite-mode
438 This variable controls whether overwrite mode is in effect: a
439 non-@code{nil} value enables the mode. It is automatically made
440 buffer-local when set in any fashion.
444 @section Deleting Text
446 @cindex deletion vs killing
447 Deletion means removing part of the text in a buffer, without saving
448 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
449 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
450 Some deletion functions do save text in the kill ring in some special
453 All of the deletion functions operate on the current buffer, and all
454 return a value of @code{nil}.
456 @defun erase-buffer &optional buffer
457 This function deletes the entire text of @var{buffer}, leaving it
458 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
459 error. Otherwise, it deletes the text without asking for any
460 confirmation. It returns @code{nil}. @var{buffer} defaults to the
461 current buffer if omitted.
463 Normally, deleting a large amount of text from a buffer inhibits further
464 auto-saving of that buffer ``because it has shrunk''. However,
465 @code{erase-buffer} does not do this, the idea being that the future
466 text is not really related to the former text, and its size should not
467 be compared with that of the former text.
470 @deffn Command delete-region start end &optional buffer
471 This command deletes the text in @var{buffer} in the region defined by
472 @var{start} and @var{end}. The value is @code{nil}. If optional
473 argument @var{buffer} is @code{nil}, the current buffer is assumed.
476 @deffn Command delete-char count &optional killp
477 This command deletes @var{count} characters directly after point, or
478 before point if @var{count} is negative. If @var{killp} is
479 non-@code{nil}, then it saves the deleted characters in the kill ring.
481 In an interactive call, @var{count} is the numeric prefix argument, and
482 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
483 argument is supplied, the text is saved in the kill ring. If no prefix
484 argument is supplied, then one character is deleted, but not saved in
487 The value returned is always @code{nil}.
490 @deffn Command delete-backward-char count &optional killp
491 @cindex delete previous char
492 This command deletes @var{count} characters directly before point, or
493 after point if @var{count} is negative. If @var{killp} is
494 non-@code{nil}, then it saves the deleted characters in the kill ring.
496 In an interactive call, @var{count} is the numeric prefix argument, and
497 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
498 argument is supplied, the text is saved in the kill ring. If no prefix
499 argument is supplied, then one character is deleted, but not saved in
502 The value returned is always @code{nil}.
505 @deffn Command backward-delete-char-untabify count &optional killp
507 This command deletes @var{count} characters backward, changing tabs
508 into spaces. When the next character to be deleted is a tab, it is
509 first replaced with the proper number of spaces to preserve alignment
510 and then one of those spaces is deleted instead of the tab. If
511 @var{killp} is non-@code{nil}, then the command saves the deleted
512 characters in the kill ring.
514 Conversion of tabs to spaces happens only if @var{count} is positive.
515 If it is negative, exactly @minus{}@var{count} characters after point
518 In an interactive call, @var{count} is the numeric prefix argument, and
519 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
520 argument is supplied, the text is saved in the kill ring. If no prefix
521 argument is supplied, then one character is deleted, but not saved in
524 The value returned is always @code{nil}.
527 @node User-Level Deletion
528 @section User-Level Deletion Commands
530 This section describes higher-level commands for deleting text,
531 commands intended primarily for the user but useful also in Lisp
534 @deffn Command delete-horizontal-space
535 @cindex deleting whitespace
536 This function deletes all spaces and tabs around point. It returns
539 In the following examples, we call @code{delete-horizontal-space} four
540 times, once on each line, with point between the second and third
541 characters on the line each time.
545 ---------- Buffer: foo ----------
550 ---------- Buffer: foo ----------
554 (delete-horizontal-space) ; @r{Four times.}
557 ---------- Buffer: foo ----------
562 ---------- Buffer: foo ----------
567 @deffn Command delete-indentation &optional join-following-p
568 This function joins the line point is on to the previous line, deleting
569 any whitespace at the join and in some cases replacing it with one
570 space. If @var{join-following-p} is non-@code{nil},
571 @code{delete-indentation} joins this line to the following line
572 instead. The value is @code{nil}.
574 If there is a fill prefix, and the second of the lines being joined
575 starts with the prefix, then @code{delete-indentation} deletes the
576 fill prefix before joining the lines. @xref{Margins}.
578 In the example below, point is located on the line starting
579 @samp{events}, and it makes no difference if there are trailing spaces
580 in the preceding line.
584 ---------- Buffer: foo ----------
585 When in the course of human
586 @point{} events, it becomes necessary
587 ---------- Buffer: foo ----------
594 ---------- Buffer: foo ----------
595 When in the course of human@point{} events, it becomes necessary
596 ---------- Buffer: foo ----------
600 After the lines are joined, the function @code{fixup-whitespace} is
601 responsible for deciding whether to leave a space at the junction.
604 @defun fixup-whitespace
605 This function replaces all the white space surrounding point with either
606 one space or no space, according to the context. It returns @code{nil}.
608 At the beginning or end of a line, the appropriate amount of space is
609 none. Before a character with close parenthesis syntax, or after a
610 character with open parenthesis or expression-prefix syntax, no space is
611 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
614 In the example below, @code{fixup-whitespace} is called the first time
615 with point before the word @samp{spaces} in the first line. For the
616 second invocation, point is directly after the @samp{(}.
620 ---------- Buffer: foo ----------
621 This has too many @point{}spaces
622 This has too many spaces at the start of (@point{} this list)
623 ---------- Buffer: foo ----------
634 ---------- Buffer: foo ----------
635 This has too many spaces
636 This has too many spaces at the start of (this list)
637 ---------- Buffer: foo ----------
642 @deffn Command just-one-space
643 @comment !!SourceFile simple.el
644 This command replaces any spaces and tabs around point with a single
645 space. It returns @code{nil}.
648 @deffn Command delete-blank-lines
649 This function deletes blank lines surrounding point. If point is on a
650 blank line with one or more blank lines before or after it, then all but
651 one of them are deleted. If point is on an isolated blank line, then it
652 is deleted. If point is on a nonblank line, the command deletes all
653 blank lines following it.
655 A blank line is defined as a line containing only tabs and spaces.
657 @code{delete-blank-lines} returns @code{nil}.
661 @section The Kill Ring
664 @dfn{Kill} functions delete text like the deletion functions, but save
665 it so that the user can reinsert it by @dfn{yanking}. Most of these
666 functions have @samp{kill-} in their name. By contrast, the functions
667 whose names start with @samp{delete-} normally do not save text for
668 yanking (though they can still be undone); these are ``deletion''
671 Most of the kill commands are primarily for interactive use, and are
672 not described here. What we do describe are the functions provided for
673 use in writing such commands. You can use these functions to write
674 commands for killing text. When you need to delete text for internal
675 purposes within a Lisp function, you should normally use deletion
676 functions, so as not to disturb the kill ring contents.
679 Killed text is saved for later yanking in the @dfn{kill ring}. This
680 is a list that holds a number of recent kills, not just the last text
681 kill. We call this a ``ring'' because yanking treats it as having
682 elements in a cyclic order. The list is kept in the variable
683 @code{kill-ring}, and can be operated on with the usual functions for
684 lists; there are also specialized functions, described in this section,
685 that treat it as a ring.
687 Some people think this use of the word ``kill'' is unfortunate, since
688 it refers to operations that specifically @emph{do not} destroy the
689 entities ``killed''. This is in sharp contrast to ordinary life, in
690 which death is permanent and ``killed'' entities do not come back to
691 life. Therefore, other metaphors have been proposed. For example, the
692 term ``cut ring'' makes sense to people who, in pre-computer days, used
693 scissors and paste to cut up and rearrange manuscripts. However, it
694 would be difficult to change the terminology now.
697 * Kill Ring Concepts:: What text looks like in the kill ring.
698 * Kill Functions:: Functions that kill text.
699 * Yank Commands:: Commands that access the kill ring.
700 * Low-Level Kill Ring:: Functions and variables for kill ring access.
701 * Internals of Kill Ring:: Variables that hold kill-ring data.
704 @node Kill Ring Concepts
705 @subsection Kill Ring Concepts
707 The kill ring records killed text as strings in a list, most recent
708 first. A short kill ring, for example, might look like this:
711 ("some text" "a different piece of text" "even older text")
715 When the list reaches @code{kill-ring-max} entries in length, adding a
716 new entry automatically deletes the last entry.
718 When kill commands are interwoven with other commands, each kill
719 command makes a new entry in the kill ring. Multiple kill commands in
720 succession build up a single entry in the kill ring, which would be
721 yanked as a unit; the second and subsequent consecutive kill commands
722 add text to the entry made by the first one.
724 For yanking, one entry in the kill ring is designated the ``front'' of
725 the ring. Some yank commands ``rotate'' the ring by designating a
726 different element as the ``front.'' But this virtual rotation doesn't
727 change the list itself---the most recent entry always comes first in the
731 @subsection Functions for Killing
733 @code{kill-region} is the usual subroutine for killing text. Any
734 command that calls this function is a ``kill command'' (and should
735 probably have @samp{kill} in its name). @code{kill-region} puts the
736 newly killed text in a new element at the beginning of the kill ring or
737 adds it to the most recent element. It uses the @code{last-command}
738 variable to determine whether the previous command was a kill command,
739 and if so appends the killed text to the most recent entry.
741 @deffn Command kill-region start end
742 This function kills the text in the region defined by @var{start} and
743 @var{end}. The text is deleted but saved in the kill ring, along with
744 its text properties. The value is always @code{nil}.
746 In an interactive call, @var{start} and @var{end} are point and
750 If the buffer is read-only, @code{kill-region} modifies the kill ring
751 just the same, then signals an error without modifying the buffer. This
752 is convenient because it lets the user use all the kill commands to copy
753 text into the kill ring from a read-only buffer.
756 @deffn Command copy-region-as-kill start end
757 This command saves the region defined by @var{start} and @var{end} on
758 the kill ring (including text properties), but does not delete the text
759 from the buffer. It returns @code{nil}. It also indicates the extent
760 of the text copied by moving the cursor momentarily, or by displaying a
761 message in the echo area.
763 The command does not set @code{this-command} to @code{kill-region}, so a
764 subsequent kill command does not append to the same kill ring entry.
766 Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
767 support Emacs 18. For Emacs 19, it is better to use @code{kill-new} or
768 @code{kill-append} instead. @xref{Low-Level Kill Ring}.
772 @subsection Functions for Yanking
774 @dfn{Yanking} means reinserting an entry of previously killed text
775 from the kill ring. The text properties are copied too.
777 @deffn Command yank &optional arg
778 @cindex inserting killed text
779 This command inserts before point the text in the first entry in the
780 kill ring. It positions the mark at the beginning of that text, and
783 If @var{arg} is a list (which occurs interactively when the user
784 types @kbd{C-u} with no digits), then @code{yank} inserts the text as
785 described above, but puts point before the yanked text and puts the mark
788 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most
789 recently killed text---the @var{arg}th element of the kill ring list.
791 @code{yank} does not alter the contents of the kill ring or rotate it.
792 It returns @code{nil}.
795 @deffn Command yank-pop arg
796 This command replaces the just-yanked entry from the kill ring with a
797 different entry from the kill ring.
799 This is allowed only immediately after a @code{yank} or another
800 @code{yank-pop}. At such a time, the region contains text that was just
801 inserted by yanking. @code{yank-pop} deletes that text and inserts in
802 its place a different piece of killed text. It does not add the deleted
803 text to the kill ring, since it is already in the kill ring somewhere.
805 If @var{arg} is @code{nil}, then the replacement text is the previous
806 element of the kill ring. If @var{arg} is numeric, the replacement is
807 the @var{arg}th previous kill. If @var{arg} is negative, a more recent
808 kill is the replacement.
810 The sequence of kills in the kill ring wraps around, so that after the
811 oldest one comes the newest one, and before the newest one goes the
814 The value is always @code{nil}.
817 @node Low-Level Kill Ring
818 @subsection Low-Level Kill Ring
820 These functions and variables provide access to the kill ring at a lower
821 level, but still convenient for use in Lisp programs. They take care of
822 interaction with X Window selections. They do not exist in Emacs
825 @defun current-kill n &optional do-not-move
826 The function @code{current-kill} rotates the yanking pointer which
827 designates the ``front'' of the kill ring by @var{n} places (from newer
828 kills to older ones), and returns the text at that place in the ring.
830 If the optional second argument @var{do-not-move} is non-@code{nil},
831 then @code{current-kill} doesn't alter the yanking pointer; it just
832 returns the @var{n}th kill, counting from the current yanking pointer.
834 If @var{n} is zero, indicating a request for the latest kill,
835 @code{current-kill} calls the value of
836 @code{interprogram-paste-function} (documented below) before consulting
840 @defun kill-new string
841 This function puts the text @var{string} into the kill ring as a new
842 entry at the front of the ring. It discards the oldest entry if
843 appropriate. It also invokes the value of
844 @code{interprogram-cut-function} (see below).
847 @defun kill-append string before-p
848 This function appends the text @var{string} to the first entry in the
849 kill ring. Normally @var{string} goes at the end of the entry, but if
850 @var{before-p} is non-@code{nil}, it goes at the beginning. This
851 function also invokes the value of @code{interprogram-cut-function} (see
855 @defvar interprogram-paste-function
856 This variable provides a way of transferring killed text from other
857 programs, when you are using a window system. Its value should be
858 @code{nil} or a function of no arguments.
860 If the value is a function, @code{current-kill} calls it to get the
861 ``most recent kill''. If the function returns a non-@code{nil} value,
862 then that value is used as the ``most recent kill''. If it returns
863 @code{nil}, then the first element of @code{kill-ring} is used.
865 The normal use of this hook is to get the X server's primary selection
866 as the most recent kill, even if the selection belongs to another X
867 client. @xref{X Selections}.
870 @defvar interprogram-cut-function
871 This variable provides a way of communicating killed text to other
872 programs, when you are using a window system. Its value should be
873 @code{nil} or a function of one argument.
875 If the value is a function, @code{kill-new} and @code{kill-append} call
876 it with the new first element of the kill ring as an argument.
878 The normal use of this hook is to set the X server's primary selection
879 to the newly killed text.
882 @node Internals of Kill Ring
883 @subsection Internals of the Kill Ring
885 The variable @code{kill-ring} holds the kill ring contents, in the
886 form of a list of strings. The most recent kill is always at the front
889 The @code{kill-ring-yank-pointer} variable points to a link in the
890 kill ring list, whose @sc{car} is the text to yank next. We say it
891 identifies the ``front'' of the ring. Moving
892 @code{kill-ring-yank-pointer} to a different link is called
893 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
894 the functions that move the yank pointer wrap around from the end of the
895 list to the beginning, or vice-versa. Rotation of the kill ring is
896 virtual; it does not change the value of @code{kill-ring}.
898 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
899 variables whose values are normally lists. The word ``pointer'' in the
900 name of the @code{kill-ring-yank-pointer} indicates that the variable's
901 purpose is to identify one element of the list for use by the next yank
904 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
905 of the links in the kill ring list. The element it identifies is the
906 @sc{car} of that link. Kill commands, which change the kill ring, also
907 set this variable to the value of @code{kill-ring}. The effect is to
908 rotate the ring so that the newly killed text is at the front.
910 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
911 pointing to the second entry in the kill ring @code{("some text" "a
912 different piece of text" "yet older text")}.
916 kill-ring kill-ring-yank-pointer
918 | ___ ___ ---> ___ ___ ___ ___
919 --> |___|___|------> |___|___|--> |___|___|--> nil
922 | | -->"yet older text"
924 | --> "a different piece of text"
931 This state of affairs might occur after @kbd{C-y} (@code{yank})
932 immediately followed by @kbd{M-y} (@code{yank-pop}).
935 This variable holds the list of killed text sequences, most recently
939 @defvar kill-ring-yank-pointer
940 This variable's value indicates which element of the kill ring is at the
941 ``front'' of the ring for yanking. More precisely, the value is a tail
942 of the value of @code{kill-ring}, and its @sc{car} is the kill string
943 that @kbd{C-y} should yank.
946 @defopt kill-ring-max
947 The value of this variable is the maximum length to which the kill
948 ring can grow, before elements are thrown away at the end. The default
949 value for @code{kill-ring-max} is 30.
956 Most buffers have an @dfn{undo list}, which records all changes made
957 to the buffer's text so that they can be undone. (The buffers that
958 don't have one are usually special-purpose buffers for which XEmacs
959 assumes that undoing is not useful.) All the primitives that modify the
960 text in the buffer automatically add elements to the front of the undo
961 list, which is in the variable @code{buffer-undo-list}.
963 @defvar buffer-undo-list
964 This variable's value is the undo list of the current buffer.
965 A value of @code{t} disables the recording of undo information.
968 Here are the kinds of elements an undo list can have:
972 This kind of element records a previous value of point. Ordinary cursor
973 motion does not get any sort of undo record, but deletion commands use
974 these entries to record where point was before the command.
976 @item (@var{beg} . @var{end})
977 This kind of element indicates how to delete text that was inserted.
978 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
981 @item (@var{text} . @var{position})
982 This kind of element indicates how to reinsert text that was deleted.
983 The deleted text itself is the string @var{text}. The place to
984 reinsert it is @code{(abs @var{position})}.
986 @item (t @var{high} . @var{low})
987 This kind of element indicates that an unmodified buffer became
988 modified. The elements @var{high} and @var{low} are two integers, each
989 recording 16 bits of the visited file's modification time as of when it
990 was previously visited or saved. @code{primitive-undo} uses those
991 values to determine whether to mark the buffer as unmodified once again;
992 it does so only if the file's modification time matches those numbers.
994 @item (nil @var{property} @var{value} @var{beg} . @var{end})
995 This kind of element records a change in a text property.
996 Here's how you might undo the change:
999 (put-text-property @var{beg} @var{end} @var{property} @var{value})
1002 @item @var{position}
1003 This element indicates where point was at an earlier time. Undoing this
1004 element sets point to @var{position}. Deletion normally creates an
1005 element of this kind as well as a reinsertion element.
1008 This element is a boundary. The elements between two boundaries are
1009 called a @dfn{change group}; normally, each change group corresponds to
1010 one keyboard command, and undo commands normally undo an entire group as
1014 @defun undo-boundary
1015 This function places a boundary element in the undo list. The undo
1016 command stops at such a boundary, and successive undo commands undo
1017 to earlier and earlier boundaries. This function returns @code{nil}.
1019 The editor command loop automatically creates an undo boundary before
1020 each key sequence is executed. Thus, each undo normally undoes the
1021 effects of one command. Self-inserting input characters are an
1022 exception. The command loop makes a boundary for the first such
1023 character; the next 19 consecutive self-inserting input characters do
1024 not make boundaries, and then the 20th does, and so on as long as
1025 self-inserting characters continue.
1027 All buffer modifications add a boundary whenever the previous undoable
1028 change was made in some other buffer. This way, a command that modifies
1029 several buffers makes a boundary in each buffer it changes.
1031 Calling this function explicitly is useful for splitting the effects of
1032 a command into more than one unit. For example, @code{query-replace}
1033 calls @code{undo-boundary} after each replacement, so that the user can
1034 undo individual replacements one by one.
1037 @defun primitive-undo count list
1038 This is the basic function for undoing elements of an undo list.
1039 It undoes the first @var{count} elements of @var{list}, returning
1040 the rest of @var{list}. You could write this function in Lisp,
1041 but it is convenient to have it in C.
1043 @code{primitive-undo} adds elements to the buffer's undo list when it
1044 changes the buffer. Undo commands avoid confusion by saving the undo
1045 list value at the beginning of a sequence of undo operations. Then the
1046 undo operations use and update the saved value. The new elements added
1047 by undoing are not part of this saved value, so they don't interfere with
1051 @node Maintaining Undo
1052 @section Maintaining Undo Lists
1054 This section describes how to enable and disable undo information for
1055 a given buffer. It also explains how the undo list is truncated
1056 automatically so it doesn't get too big.
1058 Recording of undo information in a newly created buffer is normally
1059 enabled to start with; but if the buffer name starts with a space, the
1060 undo recording is initially disabled. You can explicitly enable or
1061 disable undo recording with the following two functions, or by setting
1062 @code{buffer-undo-list} yourself.
1064 @deffn Command buffer-enable-undo &optional buffer-or-name
1065 This command enables recording undo information for buffer
1066 @var{buffer-or-name}, so that subsequent changes can be undone. If no
1067 argument is supplied, then the current buffer is used. This function
1068 does nothing if undo recording is already enabled in the buffer. It
1071 In an interactive call, @var{buffer-or-name} is the current buffer.
1072 You cannot specify any other buffer.
1075 @defun buffer-disable-undo &optional buffer
1076 @defunx buffer-flush-undo &optional buffer
1077 @cindex disable undo
1078 This function discards the undo list of @var{buffer}, and disables
1079 further recording of undo information. As a result, it is no longer
1080 possible to undo either previous changes or any subsequent changes. If
1081 the undo list of @var{buffer} is already disabled, this function
1084 This function returns @code{nil}. It cannot be called interactively.
1086 The name @code{buffer-flush-undo} is not considered obsolete, but the
1087 preferred name @code{buffer-disable-undo} is new as of Emacs versions
1091 As editing continues, undo lists get longer and longer. To prevent
1092 them from using up all available memory space, garbage collection trims
1093 them back to size limits you can set. (For this purpose, the ``size''
1094 of an undo list measures the cons cells that make up the list, plus the
1095 strings of deleted text.) Two variables control the range of acceptable
1096 sizes: @code{undo-limit} and @code{undo-strong-limit}.
1099 This is the soft limit for the acceptable size of an undo list. The
1100 change group at which this size is exceeded is the last one kept.
1103 @defvar undo-strong-limit
1104 This is the upper limit for the acceptable size of an undo list. The
1105 change group at which this size is exceeded is discarded itself (along
1106 with all older change groups). There is one exception: the very latest
1107 change group is never discarded no matter how big it is.
1112 @cindex filling, explicit
1114 @dfn{Filling} means adjusting the lengths of lines (by moving the line
1115 breaks) so that they are nearly (but no greater than) a specified
1116 maximum width. Additionally, lines can be @dfn{justified}, which means
1117 inserting spaces to make the left and/or right margins line up
1118 precisely. The width is controlled by the variable @code{fill-column}.
1119 For ease of reading, lines should be no longer than 70 or so columns.
1121 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1122 automatically as you insert it, but changes to existing text may leave
1123 it improperly filled. Then you must fill the text explicitly.
1125 Most of the commands in this section return values that are not
1126 meaningful. All the functions that do filling take note of the current
1127 left margin, current right margin, and current justification style
1128 (@pxref{Margins}). If the current justification style is
1129 @code{none}, the filling functions don't actually do anything.
1131 Several of the filling functions have an argument @var{justify}.
1132 If it is non-@code{nil}, that requests some kind of justification. It
1133 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
1134 request a specific style of justification. If it is @code{t}, that
1135 means to use the current justification style for this part of the text
1136 (see @code{current-justification}, below).
1138 When you call the filling functions interactively, using a prefix
1139 argument implies the value @code{full} for @var{justify}.
1141 @deffn Command fill-paragraph justify
1142 @cindex filling a paragraph
1143 This command fills the paragraph at or after point. If
1144 @var{justify} is non-@code{nil}, each line is justified as well.
1145 It uses the ordinary paragraph motion commands to find paragraph
1146 boundaries. @xref{Paragraphs,,, xemacs, The XEmacs User's Manual}.
1149 @deffn Command fill-region start end &optional justify
1150 This command fills each of the paragraphs in the region from @var{start}
1151 to @var{end}. It justifies as well if @var{justify} is
1154 The variable @code{paragraph-separate} controls how to distinguish
1155 paragraphs. @xref{Standard Regexps}.
1158 @deffn Command fill-individual-paragraphs start end &optional justify mail-flag
1159 This command fills each paragraph in the region according to its
1160 individual fill prefix. Thus, if the lines of a paragraph were indented
1161 with spaces, the filled paragraph will remain indented in the same
1164 The first two arguments, @var{start} and @var{end}, are the beginning
1165 and end of the region to be filled. The third and fourth arguments,
1166 @var{justify} and @var{mail-flag}, are optional. If
1167 @var{justify} is non-@code{nil}, the paragraphs are justified as
1168 well as filled. If @var{mail-flag} is non-@code{nil}, it means the
1169 function is operating on a mail message and therefore should not fill
1172 Ordinarily, @code{fill-individual-paragraphs} regards each change in
1173 indentation as starting a new paragraph. If
1174 @code{fill-individual-varying-indent} is non-@code{nil}, then only
1175 separator lines separate paragraphs. That mode can handle indented
1176 paragraphs with additional indentation on the first line.
1179 @defopt fill-individual-varying-indent
1180 This variable alters the action of @code{fill-individual-paragraphs} as
1184 @deffn Command fill-region-as-paragraph start end &optional justify
1185 This command considers a region of text as a paragraph and fills it. If
1186 the region was made up of many paragraphs, the blank lines between
1187 paragraphs are removed. This function justifies as well as filling when
1188 @var{justify} is non-@code{nil}.
1190 In an interactive call, any prefix argument requests justification.
1192 In Adaptive Fill mode, which is enabled by default,
1193 @code{fill-region-as-paragraph} on an indented paragraph when there is
1194 no fill prefix uses the indentation of the second line of the paragraph
1198 @deffn Command justify-current-line how eop nosqueeze
1199 This command inserts spaces between the words of the current line so
1200 that the line ends exactly at @code{fill-column}. It returns
1203 The argument @var{how}, if non-@code{nil} specifies explicitly the style
1204 of justification. It can be @code{left}, @code{right}, @code{full},
1205 @code{center}, or @code{none}. If it is @code{t}, that means to do
1206 follow specified justification style (see @code{current-justification},
1207 below). @code{nil} means to do full justification.
1209 If @var{eop} is non-@code{nil}, that means do left-justification when
1210 @code{current-justification} specifies full justification. This is used
1211 for the last line of a paragraph; even if the paragraph as a whole is
1212 fully justified, the last line should not be.
1214 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1218 @defopt default-justification
1219 This variable's value specifies the style of justification to use for
1220 text that doesn't specify a style with a text property. The possible
1221 values are @code{left}, @code{right}, @code{full}, @code{center}, or
1222 @code{none}. The default value is @code{left}.
1225 @defun current-justification
1226 This function returns the proper justification style to use for filling
1227 the text around point.
1230 @defvar fill-paragraph-function
1231 This variable provides a way for major modes to override the filling of
1232 paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
1233 this function to do the work. If the function returns a non-@code{nil}
1234 value, @code{fill-paragraph} assumes the job is done, and immediately
1237 The usual use of this feature is to fill comments in programming
1238 language modes. If the function needs to fill a paragraph in the usual
1239 way, it can do so as follows:
1242 (let ((fill-paragraph-function nil))
1243 (fill-paragraph arg))
1247 @defvar use-hard-newlines
1248 If this variable is non-@code{nil}, the filling functions do not delete
1249 newlines that have the @code{hard} text property. These ``hard
1250 newlines'' act as paragraph separators.
1254 @section Margins for Filling
1257 This variable specifies a string of text that appears at the beginning
1258 of normal text lines and should be disregarded when filling them. Any
1259 line that fails to start with the fill prefix is considered the start of
1260 a paragraph; so is any line that starts with the fill prefix followed by
1261 additional whitespace. Lines that start with the fill prefix but no
1262 additional whitespace are ordinary text lines that can be filled
1263 together. The resulting filled lines also start with the fill prefix.
1265 The fill prefix follows the left margin whitespace, if any.
1269 This buffer-local variable specifies the maximum width of filled
1270 lines. Its value should be an integer, which is a number of columns.
1271 All the filling, justification and centering commands are affected by
1272 this variable, including Auto Fill mode (@pxref{Auto Filling}).
1274 As a practical matter, if you are writing text for other people to
1275 read, you should set @code{fill-column} to no more than 70. Otherwise
1276 the line will be too long for people to read comfortably, and this can
1277 make the text seem clumsy.
1280 @defvar default-fill-column
1281 The value of this variable is the default value for @code{fill-column} in
1282 buffers that do not override it. This is the same as
1283 @code{(default-value 'fill-column)}.
1285 The default value for @code{default-fill-column} is 70.
1288 @deffn Command set-left-margin from to margin
1289 This sets the @code{left-margin} property on the text from @var{from} to
1290 @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
1291 command also refills the region to fit the new margin.
1294 @deffn Command set-right-margin from to margin
1295 This sets the @code{right-margin} property on the text from @var{from}
1296 to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
1297 this command also refills the region to fit the new margin.
1300 @defun current-left-margin
1301 This function returns the proper left margin value to use for filling
1302 the text around point. The value is the sum of the @code{left-margin}
1303 property of the character at the start of the current line (or zero if
1304 none), and the value of the variable @code{left-margin}.
1307 @defun current-fill-column
1308 This function returns the proper fill column value to use for filling
1309 the text around point. The value is the value of the @code{fill-column}
1310 variable, minus the value of the @code{right-margin} property of the
1311 character after point.
1314 @deffn Command move-to-left-margin &optional n force
1315 This function moves point to the left margin of the current line. The
1316 column moved to is determined by calling the function
1317 @code{current-left-margin}. If the argument @var{n} is non-@code{nil},
1318 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
1320 If @var{force} is non-@code{nil}, that says to fix the line's
1321 indentation if that doesn't match the left margin value.
1324 @defun delete-to-left-margin from to
1325 This function removes left margin indentation from the text
1326 between @var{from} and @var{to}. The amount of indentation
1327 to delete is determined by calling @code{current-left-margin}.
1328 In no case does this function delete non-whitespace.
1331 @defun indent-to-left-margin
1332 This is the default @code{indent-line-function}, used in Fundamental
1333 mode, Text mode, etc. Its effect is to adjust the indentation at the
1334 beginning of the current line to the value specified by the variable
1335 @code{left-margin}. This may involve either inserting or deleting
1340 This variable specifies the base left margin column. In Fundamental
1341 mode, @key{LFD} indents to this column. This variable automatically
1342 becomes buffer-local when set in any fashion.
1346 @section Auto Filling
1347 @cindex filling, automatic
1348 @cindex Auto Fill mode
1350 Auto Fill mode is a minor mode that fills lines automatically as text
1351 is inserted. This section describes the hook used by Auto Fill mode.
1352 For a description of functions that you can call explicitly to fill and
1353 justify existing text, see @ref{Filling}.
1355 Auto Fill mode also enables the functions that change the margins and
1356 justification style to refill portions of the text. @xref{Margins}.
1358 @defvar auto-fill-function
1359 The value of this variable should be a function (of no arguments) to be
1360 called after self-inserting a space or a newline. It may be @code{nil},
1361 in which case nothing special is done in that case.
1363 The value of @code{auto-fill-function} is @code{do-auto-fill} when
1364 Auto-Fill mode is enabled. That is a function whose sole purpose is to
1365 implement the usual strategy for breaking a line.
1368 In older Emacs versions, this variable was named @code{auto-fill-hook},
1369 but since it is not called with the standard convention for hooks, it
1370 was renamed to @code{auto-fill-function} in version 19.
1375 @section Sorting Text
1376 @cindex sorting text
1378 The sorting functions described in this section all rearrange text in
1379 a buffer. This is in contrast to the function @code{sort}, which
1380 rearranges the order of the elements of a list (@pxref{Rearrangement}).
1381 The values returned by these functions are not meaningful.
1383 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
1384 This function is the general text-sorting routine that divides a buffer
1385 into records and sorts them. Most of the commands in this section use
1388 To understand how @code{sort-subr} works, consider the whole accessible
1389 portion of the buffer as being divided into disjoint pieces called
1390 @dfn{sort records}. The records may or may not be contiguous; they may
1391 not overlap. A portion of each sort record (perhaps all of it) is
1392 designated as the sort key. Sorting rearranges the records in order by
1395 Usually, the records are rearranged in order of ascending sort key.
1396 If the first argument to the @code{sort-subr} function, @var{reverse},
1397 is non-@code{nil}, the sort records are rearranged in order of
1398 descending sort key.
1400 The next four arguments to @code{sort-subr} are functions that are
1401 called to move point across a sort record. They are called many times
1402 from within @code{sort-subr}.
1406 @var{nextrecfun} is called with point at the end of a record. This
1407 function moves point to the start of the next record. The first record
1408 is assumed to start at the position of point when @code{sort-subr} is
1409 called. Therefore, you should usually move point to the beginning of
1410 the buffer before calling @code{sort-subr}.
1412 This function can indicate there are no more sort records by leaving
1413 point at the end of the buffer.
1416 @var{endrecfun} is called with point within a record. It moves point to
1417 the end of the record.
1420 @var{startkeyfun} is called to move point from the start of a record to
1421 the start of the sort key. This argument is optional; if it is omitted,
1422 the whole record is the sort key. If supplied, the function should
1423 either return a non-@code{nil} value to be used as the sort key, or
1424 return @code{nil} to indicate that the sort key is in the buffer
1425 starting at point. In the latter case, @var{endkeyfun} is called to
1426 find the end of the sort key.
1429 @var{endkeyfun} is called to move point from the start of the sort key
1430 to the end of the sort key. This argument is optional. If
1431 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
1432 @code{nil}), then the sort key extends to the end of the record. There
1433 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1434 non-@code{nil} value.
1437 As an example of @code{sort-subr}, here is the complete function
1438 definition for @code{sort-lines}:
1442 ;; @r{Note that the first two lines of doc string}
1443 ;; @r{are effectively one line when viewed by a user.}
1444 (defun sort-lines (reverse beg end)
1445 "Sort lines in region alphabetically.
1446 Called from a program, there are three arguments:
1449 REVERSE (non-nil means reverse order),
1450 and BEG and END (the region to sort)."
1451 (interactive "P\nr")
1453 (narrow-to-region beg end)
1454 (goto-char (point-min))
1461 Here @code{forward-line} moves point to the start of the next record,
1462 and @code{end-of-line} moves point to the end of record. We do not pass
1463 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
1464 record is used as the sort key.
1466 The @code{sort-paragraphs} function is very much the same, except that
1467 its @code{sort-subr} call looks like this:
1474 (skip-chars-forward "\n \t\f")))
1480 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
1481 This command sorts the region between @var{start} and @var{end}
1482 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
1483 If @var{reverse} is a negative integer, then sorting is in reverse
1486 Alphabetical sorting means that two sort keys are compared by
1487 comparing the first characters of each, the second characters of each,
1488 and so on. If a mismatch is found, it means that the sort keys are
1489 unequal; the sort key whose character is less at the point of first
1490 mismatch is the lesser sort key. The individual characters are compared
1491 according to their numerical values. Since Emacs uses the @sc{ascii}
1492 character set, the ordering in that set determines alphabetical order.
1493 @c version 19 change
1495 The value of the @var{record-regexp} argument specifies how to divide
1496 the buffer into sort records. At the end of each record, a search is
1497 done for this regular expression, and the text that matches it is the
1498 next record. For example, the regular expression @samp{^.+$}, which
1499 matches lines with at least one character besides a newline, would make
1500 each such line into a sort record. @xref{Regular Expressions}, for a
1501 description of the syntax and meaning of regular expressions.
1503 The value of the @var{key-regexp} argument specifies what part of each
1504 record is the sort key. The @var{key-regexp} could match the whole
1505 record, or only a part. In the latter case, the rest of the record has
1506 no effect on the sorted order of records, but it is carried along when
1507 the record moves to its new position.
1509 The @var{key-regexp} argument can refer to the text matched by a
1510 subexpression of @var{record-regexp}, or it can be a regular expression
1513 If @var{key-regexp} is:
1516 @item @samp{\@var{digit}}
1517 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
1518 grouping in @var{record-regexp} is the sort key.
1521 then the whole record is the sort key.
1523 @item a regular expression
1524 then @code{sort-regexp-fields} searches for a match for the regular
1525 expression within the record. If such a match is found, it is the sort
1526 key. If there is no match for @var{key-regexp} within a record then
1527 that record is ignored, which means its position in the buffer is not
1528 changed. (The other records may move around it.)
1531 For example, if you plan to sort all the lines in the region by the
1532 first word on each line starting with the letter @samp{f}, you should
1533 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
1534 @samp{\<f\w*\>}. The resulting expression looks like this:
1538 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
1544 If you call @code{sort-regexp-fields} interactively, it prompts for
1545 @var{record-regexp} and @var{key-regexp} in the minibuffer.
1548 @deffn Command sort-lines reverse start end
1549 This command alphabetically sorts lines in the region between
1550 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1551 is in reverse order.
1554 @deffn Command sort-paragraphs reverse start end
1555 This command alphabetically sorts paragraphs in the region between
1556 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1557 is in reverse order.
1560 @deffn Command sort-pages reverse start end
1561 This command alphabetically sorts pages in the region between
1562 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1563 is in reverse order.
1566 @deffn Command sort-fields field start end
1567 This command sorts lines in the region between @var{start} and
1568 @var{end}, comparing them alphabetically by the @var{field}th field
1569 of each line. Fields are separated by whitespace and numbered starting
1570 from 1. If @var{field} is negative, sorting is by the
1571 @w{@minus{}@var{field}th} field from the end of the line. This command
1572 is useful for sorting tables.
1575 @deffn Command sort-numeric-fields field start end
1576 This command sorts lines in the region between @var{start} and
1577 @var{end}, comparing them numerically by the @var{field}th field of each
1578 line. The specified field must contain a number in each line of the
1579 region. Fields are separated by whitespace and numbered starting from
1580 1. If @var{field} is negative, sorting is by the
1581 @w{@minus{}@var{field}th} field from the end of the line. This command
1582 is useful for sorting tables.
1585 @deffn Command sort-columns reverse &optional beg end
1586 This command sorts the lines in the region between @var{beg} and
1587 @var{end}, comparing them alphabetically by a certain range of columns.
1588 The column positions of @var{beg} and @var{end} bound the range of
1591 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
1593 One unusual thing about this command is that the entire line
1594 containing position @var{beg}, and the entire line containing position
1595 @var{end}, are included in the region sorted.
1597 Note that @code{sort-columns} uses the @code{sort} utility program,
1598 and so cannot work properly on text containing tab characters. Use
1599 @kbd{M-x @code{untabify}} to convert tabs to spaces before sorting.
1603 @comment node-name, next, previous, up
1604 @section Counting Columns
1606 @cindex counting columns
1607 @cindex horizontal position
1609 The column functions convert between a character position (counting
1610 characters from the beginning of the buffer) and a column position
1611 (counting screen characters from the beginning of a line).
1613 A character counts according to the number of columns it occupies on
1614 the screen. This means control characters count as occupying 2 or 4
1615 columns, depending upon the value of @code{ctl-arrow}, and tabs count as
1616 occupying a number of columns that depends on the value of
1617 @code{tab-width} and on the column where the tab begins. @xref{Usual Display}.
1619 Column number computations ignore the width of the window and the
1620 amount of horizontal scrolling. Consequently, a column value can be
1621 arbitrarily high. The first (or leftmost) column is numbered 0.
1623 @defun current-column
1624 This function returns the horizontal position of point, measured in
1625 columns, counting from 0 at the left margin. The column position is the
1626 sum of the widths of all the displayed representations of the characters
1627 between the start of the current line and point.
1629 For an example of using @code{current-column}, see the description of
1630 @code{count-lines} in @ref{Text Lines}.
1633 @defun move-to-column column &optional force
1634 This function moves point to @var{column} in the current line. The
1635 calculation of @var{column} takes into account the widths of the
1636 displayed representations of the characters between the start of the
1639 If column @var{column} is beyond the end of the line, point moves to the
1640 end of the line. If @var{column} is negative, point moves to the
1641 beginning of the line.
1643 If it is impossible to move to column @var{column} because that is in
1644 the middle of a multicolumn character such as a tab, point moves to the
1645 end of that character. However, if @var{force} is non-@code{nil}, and
1646 @var{column} is in the middle of a tab, then @code{move-to-column}
1647 converts the tab into spaces so that it can move precisely to column
1648 @var{column}. Other multicolumn characters can cause anomalies despite
1649 @var{force}, since there is no way to split them.
1651 The argument @var{force} also has an effect if the line isn't long
1652 enough to reach column @var{column}; in that case, it says to add
1653 whitespace at the end of the line to reach that column.
1655 If @var{column} is not an integer, an error is signaled.
1657 The return value is the column number actually moved to.
1661 @section Indentation
1664 The indentation functions are used to examine, move to, and change
1665 whitespace that is at the beginning of a line. Some of the functions
1666 can also change whitespace elsewhere on a line. Columns and indentation
1667 count from zero at the left margin.
1670 * Primitive Indent:: Functions used to count and insert indentation.
1671 * Mode-Specific Indent:: Customize indentation for different modes.
1672 * Region Indent:: Indent all the lines in a region.
1673 * Relative Indent:: Indent the current line based on previous lines.
1674 * Indent Tabs:: Adjustable, typewriter-like tab stops.
1675 * Motion by Indent:: Move to first non-blank character.
1678 @node Primitive Indent
1679 @subsection Indentation Primitives
1681 This section describes the primitive functions used to count and
1682 insert indentation. The functions in the following sections use these
1685 @defun current-indentation
1686 @comment !!Type Primitive Function
1687 @comment !!SourceFile indent.c
1688 This function returns the indentation of the current line, which is
1689 the horizontal position of the first nonblank character. If the
1690 contents are entirely blank, then this is the horizontal position of the
1694 @deffn Command indent-to column &optional minimum
1695 @comment !!Type Primitive Function
1696 @comment !!SourceFile indent.c
1697 This function indents from point with tabs and spaces until @var{column}
1698 is reached. If @var{minimum} is specified and non-@code{nil}, then at
1699 least that many spaces are inserted even if this requires going beyond
1700 @var{column}. Otherwise the function does nothing if point is already
1701 beyond @var{column}. The value is the column at which the inserted
1705 @defopt indent-tabs-mode
1706 @comment !!SourceFile indent.c
1707 If this variable is non-@code{nil}, indentation functions can insert
1708 tabs as well as spaces. Otherwise, they insert only spaces. Setting
1709 this variable automatically makes it local to the current buffer.
1712 @node Mode-Specific Indent
1713 @subsection Indentation Controlled by Major Mode
1715 An important function of each major mode is to customize the @key{TAB}
1716 key to indent properly for the language being edited. This section
1717 describes the mechanism of the @key{TAB} key and how to control it.
1718 The functions in this section return unpredictable values.
1720 @defvar indent-line-function
1721 This variable's value is the function to be used by @key{TAB} (and
1722 various commands) to indent the current line. The command
1723 @code{indent-according-to-mode} does no more than call this function.
1725 In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C
1726 mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
1727 In Fundamental mode, Text mode, and many other modes with no standard
1728 for indentation, the value is @code{indent-to-left-margin} (which is the
1732 @deffn Command indent-according-to-mode
1733 This command calls the function in @code{indent-line-function} to
1734 indent the current line in a way appropriate for the current major mode.
1737 @deffn Command indent-for-tab-command
1738 This command calls the function in @code{indent-line-function} to indent
1739 the current line; except that if that function is
1740 @code{indent-to-left-margin}, it calls @code{insert-tab} instead. (That
1741 is a trivial command that inserts a tab character.)
1744 @deffn Command newline-and-indent
1745 @comment !!SourceFile simple.el
1746 This function inserts a newline, then indents the new line (the one
1747 following the newline just inserted) according to the major mode.
1749 It does indentation by calling the current @code{indent-line-function}.
1750 In programming language modes, this is the same thing @key{TAB} does,
1751 but in some text modes, where @key{TAB} inserts a tab,
1752 @code{newline-and-indent} indents to the column specified by
1756 @deffn Command reindent-then-newline-and-indent
1757 @comment !!SourceFile simple.el
1758 This command reindents the current line, inserts a newline at point,
1759 and then reindents the new line (the one following the newline just
1762 This command does indentation on both lines according to the current
1763 major mode, by calling the current value of @code{indent-line-function}.
1764 In programming language modes, this is the same thing @key{TAB} does,
1765 but in some text modes, where @key{TAB} inserts a tab,
1766 @code{reindent-then-newline-and-indent} indents to the column specified
1767 by @code{left-margin}.
1771 @subsection Indenting an Entire Region
1773 This section describes commands that indent all the lines in the
1774 region. They return unpredictable values.
1776 @deffn Command indent-region start end to-column
1777 This command indents each nonblank line starting between @var{start}
1778 (inclusive) and @var{end} (exclusive). If @var{to-column} is
1779 @code{nil}, @code{indent-region} indents each nonblank line by calling
1780 the current mode's indentation function, the value of
1781 @code{indent-line-function}.
1783 If @var{to-column} is non-@code{nil}, it should be an integer
1784 specifying the number of columns of indentation; then this function
1785 gives each line exactly that much indentation, by either adding or
1786 deleting whitespace.
1788 If there is a fill prefix, @code{indent-region} indents each line
1789 by making it start with the fill prefix.
1792 @defvar indent-region-function
1793 The value of this variable is a function that can be used by
1794 @code{indent-region} as a short cut. You should design the function so
1795 that it will produce the same results as indenting the lines of the
1796 region one by one, but presumably faster.
1798 If the value is @code{nil}, there is no short cut, and
1799 @code{indent-region} actually works line by line.
1801 A short-cut function is useful in modes such as C mode and Lisp mode,
1802 where the @code{indent-line-function} must scan from the beginning of
1803 the function definition: applying it to each line would be quadratic in
1804 time. The short cut can update the scan information as it moves through
1805 the lines indenting them; this takes linear time. In a mode where
1806 indenting a line individually is fast, there is no need for a short cut.
1808 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
1809 a different meaning and does not use this variable.
1812 @deffn Command indent-rigidly start end count
1813 @comment !!SourceFile indent.el
1814 This command indents all lines starting between @var{start}
1815 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
1816 This ``preserves the shape'' of the affected region, moving it as a
1817 rigid unit. Consequently, this command is useful not only for indenting
1818 regions of unindented text, but also for indenting regions of formatted
1821 For example, if @var{count} is 3, this command adds 3 columns of
1822 indentation to each of the lines beginning in the region specified.
1824 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
1825 @code{indent-rigidly} to indent the text copied from the message being
1829 @defun indent-code-rigidly start end columns &optional nochange-regexp
1830 This is like @code{indent-rigidly}, except that it doesn't alter lines
1831 that start within strings or comments.
1833 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
1834 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
1837 @node Relative Indent
1838 @subsection Indentation Relative to Previous Lines
1840 This section describes two commands that indent the current line
1841 based on the contents of previous lines.
1843 @deffn Command indent-relative &optional unindented-ok
1844 This command inserts whitespace at point, extending to the same
1845 column as the next @dfn{indent point} of the previous nonblank line. An
1846 indent point is a non-whitespace character following whitespace. The
1847 next indent point is the first one at a column greater than the current
1848 column of point. For example, if point is underneath and to the left of
1849 the first non-blank character of a line of text, it moves to that column
1850 by inserting whitespace.
1852 If the previous nonblank line has no next indent point (i.e., none at a
1853 great enough column position), @code{indent-relative} either does
1854 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
1855 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right
1856 of the last column of a short line of text, this command ordinarily
1857 moves point to the next tab stop by inserting whitespace.
1859 The return value of @code{indent-relative} is unpredictable.
1861 In the following example, point is at the beginning of the second
1866 This line is indented twelve spaces.
1867 @point{}The quick brown fox jumped.
1872 Evaluation of the expression @code{(indent-relative nil)} produces the
1877 This line is indented twelve spaces.
1878 @point{}The quick brown fox jumped.
1882 In this example, point is between the @samp{m} and @samp{p} of
1887 This line is indented twelve spaces.
1888 The quick brown fox jum@point{}ped.
1893 Evaluation of the expression @code{(indent-relative nil)} produces the
1898 This line is indented twelve spaces.
1899 The quick brown fox jum @point{}ped.
1904 @deffn Command indent-relative-maybe
1905 @comment !!SourceFile indent.el
1906 This command indents the current line like the previous nonblank line.
1907 It calls @code{indent-relative} with @code{t} as the @var{unindented-ok}
1908 argument. The return value is unpredictable.
1910 If the previous nonblank line has no indent points beyond the current
1911 column, this command does nothing.
1915 @subsection Adjustable ``Tab Stops''
1916 @cindex tabs stops for indentation
1918 This section explains the mechanism for user-specified ``tab stops''
1919 and the mechanisms that use and set them. The name ``tab stops'' is
1920 used because the feature is similar to that of the tab stops on a
1921 typewriter. The feature works by inserting an appropriate number of
1922 spaces and tab characters to reach the next tab stop column; it does not
1923 affect the display of tab characters in the buffer (@pxref{Usual
1924 Display}). Note that the @key{TAB} character as input uses this tab
1925 stop feature only in a few major modes, such as Text mode.
1927 @deffn Command tab-to-tab-stop
1928 This command inserts spaces or tabs up to the next tab stop column
1929 defined by @code{tab-stop-list}. It searches the list for an element
1930 greater than the current column number, and uses that element as the
1931 column to indent to. It does nothing if no such element is found.
1934 @defopt tab-stop-list
1935 This variable is the list of tab stop columns used by
1936 @code{tab-to-tab-stops}. The elements should be integers in increasing
1937 order. The tab stop columns need not be evenly spaced.
1939 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
1943 @node Motion by Indent
1944 @subsection Indentation-Based Motion Commands
1946 These commands, primarily for interactive use, act based on the
1947 indentation in the text.
1949 @deffn Command back-to-indentation
1950 @comment !!SourceFile simple.el
1951 This command moves point to the first non-whitespace character in the
1952 current line (which is the line in which point is located). It returns
1956 @deffn Command backward-to-indentation arg
1957 @comment !!SourceFile simple.el
1958 This command moves point backward @var{arg} lines and then to the
1959 first nonblank character on that line. It returns @code{nil}.
1962 @deffn Command forward-to-indentation arg
1963 @comment !!SourceFile simple.el
1964 This command moves point forward @var{arg} lines and then to the first
1965 nonblank character on that line. It returns @code{nil}.
1969 @section Case Changes
1970 @cindex case changes
1972 The case change commands described here work on text in the current
1973 buffer. @xref{Character Case}, for case conversion commands that work
1974 on strings and characters. @xref{Case Tables}, for how to customize
1975 which characters are upper or lower case and how to convert them.
1977 @deffn Command capitalize-region start end
1978 This function capitalizes all words in the region defined by
1979 @var{start} and @var{end}. To capitalize means to convert each word's
1980 first character to upper case and convert the rest of each word to lower
1981 case. The function returns @code{nil}.
1983 If one end of the region is in the middle of a word, the part of the
1984 word within the region is treated as an entire word.
1986 When @code{capitalize-region} is called interactively, @var{start} and
1987 @var{end} are point and the mark, with the smallest first.
1991 ---------- Buffer: foo ----------
1992 This is the contents of the 5th foo.
1993 ---------- Buffer: foo ----------
1997 (capitalize-region 1 44)
2000 ---------- Buffer: foo ----------
2001 This Is The Contents Of The 5th Foo.
2002 ---------- Buffer: foo ----------
2007 @deffn Command downcase-region start end
2008 This function converts all of the letters in the region defined by
2009 @var{start} and @var{end} to lower case. The function returns
2012 When @code{downcase-region} is called interactively, @var{start} and
2013 @var{end} are point and the mark, with the smallest first.
2016 @deffn Command upcase-region start end
2017 This function converts all of the letters in the region defined by
2018 @var{start} and @var{end} to upper case. The function returns
2021 When @code{upcase-region} is called interactively, @var{start} and
2022 @var{end} are point and the mark, with the smallest first.
2025 @deffn Command capitalize-word count
2026 This function capitalizes @var{count} words after point, moving point
2027 over as it does. To capitalize means to convert each word's first
2028 character to upper case and convert the rest of each word to lower case.
2029 If @var{count} is negative, the function capitalizes the
2030 @minus{}@var{count} previous words but does not move point. The value
2033 If point is in the middle of a word, the part of the word before point
2034 is ignored when moving forward. The rest is treated as an entire word.
2036 When @code{capitalize-word} is called interactively, @var{count} is
2037 set to the numeric prefix argument.
2040 @deffn Command downcase-word count
2041 This function converts the @var{count} words after point to all lower
2042 case, moving point over as it does. If @var{count} is negative, it
2043 converts the @minus{}@var{count} previous words but does not move point.
2044 The value is @code{nil}.
2046 When @code{downcase-word} is called interactively, @var{count} is set
2047 to the numeric prefix argument.
2050 @deffn Command upcase-word count
2051 This function converts the @var{count} words after point to all upper
2052 case, moving point over as it does. If @var{count} is negative, it
2053 converts the @minus{}@var{count} previous words but does not move point.
2054 The value is @code{nil}.
2056 When @code{upcase-word} is called interactively, @var{count} is set to
2057 the numeric prefix argument.
2060 @node Text Properties
2061 @section Text Properties
2062 @cindex text properties
2063 @cindex attributes of text
2064 @cindex properties of text
2066 Text properties are an alternative interface to extents
2067 (@pxref{Extents}), and are built on top of them. They are useful when
2068 you want to view textual properties as being attached to the characters
2069 themselves rather than to intervals of characters. The text property
2070 interface is compatible with FSF Emacs.
2072 Each character position in a buffer or a string can have a @dfn{text
2073 property list}, much like the property list of a symbol (@pxref{Property
2074 Lists}). The properties belong to a particular character at a
2075 particular place, such as, the letter @samp{T} at the beginning of this
2076 sentence or the first @samp{o} in @samp{foo}---if the same character
2077 occurs in two different places, the two occurrences generally have
2078 different properties.
2080 Each property has a name and a value. Both of these can be any Lisp
2081 object, but the name is normally a symbol. The usual way to access the
2082 property list is to specify a name and ask what value corresponds to it.
2085 If a character has a @code{category} property, we call it the
2086 @dfn{category} of the character. It should be a symbol. The properties
2087 of the symbol serve as defaults for the properties of the character.
2089 Note that FSF Emacs also looks at the @code{category} property to find
2090 defaults for text properties. We consider this too bogus to implement.
2092 Copying text between strings and buffers preserves the properties
2093 along with the characters; this includes such diverse functions as
2094 @code{substring}, @code{insert}, and @code{buffer-substring}.
2097 * Examining Properties:: Looking at the properties of one character.
2098 * Changing Properties:: Setting the properties of a range of text.
2099 * Property Search:: Searching for where a property changes value.
2100 * Special Properties:: Particular properties with special meanings.
2101 * Saving Properties:: Saving text properties in files, and reading
2105 @node Examining Properties
2106 @subsection Examining Text Properties
2108 The simplest way to examine text properties is to ask for the value of
2109 a particular property of a particular character. For that, use
2110 @code{get-text-property}. Use @code{text-properties-at} to get the
2111 entire property list of a character. @xref{Property Search}, for
2112 functions to examine the properties of a number of characters at once.
2114 These functions handle both strings and buffers. (Keep in mind that
2115 positions in a string start from 0, whereas positions in a buffer start
2118 @defun get-text-property pos prop &optional object
2119 This function returns the value of the @var{prop} property of the
2120 character after position @var{pos} in @var{object} (a buffer or string).
2121 The argument @var{object} is optional and defaults to the current
2123 @ignore @c Bogus as hell!
2124 If there is no @var{prop} property strictly speaking, but the character
2125 has a category that is a symbol, then @code{get-text-property} returns
2126 the @var{prop} property of that symbol.
2130 @defun get-char-property pos prop &optional object
2131 This function is like @code{get-text-property}, except that it checks
2132 all extents, not just text-property extents.
2134 @ignore Does not apply in XEmacs
2135 The argument @var{object} may be a string, a buffer, or a window. If it
2136 is a window, then the buffer displayed in that window is used for text
2137 properties and overlays, but only the overlays active for that window
2138 are considered. If @var{object} is a buffer, then all overlays in that
2139 buffer are considered, as well as text properties. If @var{object} is a
2140 string, only text properties are considered, since strings never have
2145 @defun text-properties-at position &optional object
2146 This function returns the entire property list of the character at
2147 @var{position} in the string or buffer @var{object}. If @var{object} is
2148 @code{nil}, it defaults to the current buffer.
2151 @defvar default-text-properties
2152 This variable holds a property list giving default values for text
2153 properties. Whenever a character does not specify a value for a
2154 property, the value stored in this list is used instead. Here is
2158 (setq default-text-properties '(foo 69))
2159 ;; @r{Make sure character 1 has no properties of its own.}
2160 (set-text-properties 1 2 nil)
2161 ;; @r{What we get, when we ask, is the default value.}
2162 (get-text-property 1 'foo)
2167 @node Changing Properties
2168 @subsection Changing Text Properties
2170 The primitives for changing properties apply to a specified range of
2171 text. The function @code{set-text-properties} (see end of section) sets
2172 the entire property list of the text in that range; more often, it is
2173 useful to add, change, or delete just certain properties specified by
2176 Since text properties are considered part of the buffer's contents, and
2177 can affect how the buffer looks on the screen, any change in the text
2178 properties is considered a buffer modification. Buffer text property
2179 changes are undoable (@pxref{Undo}).
2181 @defun put-text-property start end prop value &optional object
2182 This function sets the @var{prop} property to @var{value} for the text
2183 between @var{start} and @var{end} in the string or buffer @var{object}.
2184 If @var{object} is @code{nil}, it defaults to the current buffer.
2187 @defun add-text-properties start end props &optional object
2188 This function modifies the text properties for the text between
2189 @var{start} and @var{end} in the string or buffer @var{object}. If
2190 @var{object} is @code{nil}, it defaults to the current buffer.
2192 The argument @var{props} specifies which properties to change. It
2193 should have the form of a property list (@pxref{Property Lists}): a list
2194 whose elements include the property names followed alternately by the
2195 corresponding values.
2197 The return value is @code{t} if the function actually changed some
2198 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2199 its values agree with those in the text).
2201 For example, here is how to set the @code{comment} and @code{face}
2202 properties of a range of text:
2205 (add-text-properties @var{start} @var{end}
2206 '(comment t face highlight))
2210 @defun remove-text-properties start end props &optional object
2211 This function deletes specified text properties from the text between
2212 @var{start} and @var{end} in the string or buffer @var{object}. If
2213 @var{object} is @code{nil}, it defaults to the current buffer.
2215 The argument @var{props} specifies which properties to delete. It
2216 should have the form of a property list (@pxref{Property Lists}): a list
2217 whose elements are property names alternating with corresponding values.
2218 But only the names matter---the values that accompany them are ignored.
2219 For example, here's how to remove the @code{face} property.
2222 (remove-text-properties @var{start} @var{end} '(face nil))
2225 The return value is @code{t} if the function actually changed some
2226 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2227 if no character in the specified text had any of those properties).
2230 @defun set-text-properties start end props &optional object
2231 This function completely replaces the text property list for the text
2232 between @var{start} and @var{end} in the string or buffer @var{object}.
2233 If @var{object} is @code{nil}, it defaults to the current buffer.
2235 The argument @var{props} is the new property list. It should be a list
2236 whose elements are property names alternating with corresponding values.
2238 After @code{set-text-properties} returns, all the characters in the
2239 specified range have identical properties.
2241 If @var{props} is @code{nil}, the effect is to get rid of all properties
2242 from the specified range of text. Here's an example:
2245 (set-text-properties @var{start} @var{end} nil)
2249 See also the function @code{buffer-substring-without-properties}
2250 (@pxref{Buffer Contents}) which copies text from the buffer
2251 but does not copy its properties.
2253 @node Property Search
2254 @subsection Property Search Functions
2256 In typical use of text properties, most of the time several or many
2257 consecutive characters have the same value for a property. Rather than
2258 writing your programs to examine characters one by one, it is much
2259 faster to process chunks of text that have the same property value.
2261 Here are functions you can use to do this. They use @code{eq} for
2262 comparing property values. In all cases, @var{object} defaults to the
2265 For high performance, it's very important to use the @var{limit}
2266 argument to these functions, especially the ones that search for a
2267 single property---otherwise, they may spend a long time scanning to the
2268 end of the buffer, if the property you are interested in does not change.
2270 Remember that a position is always between two characters; the position
2271 returned by these functions is between two characters with different
2274 @defun next-property-change pos &optional object limit
2275 The function scans the text forward from position @var{pos} in the
2276 string or buffer @var{object} till it finds a change in some text
2277 property, then returns the position of the change. In other words, it
2278 returns the position of the first character beyond @var{pos} whose
2279 properties are not identical to those of the character just after
2282 If @var{limit} is non-@code{nil}, then the scan ends at position
2283 @var{limit}. If there is no property change before that point,
2284 @code{next-property-change} returns @var{limit}.
2286 The value is @code{nil} if the properties remain unchanged all the way
2287 to the end of @var{object} and @var{limit} is @code{nil}. If the value
2288 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
2289 The value equals @var{pos} only when @var{limit} equals @var{pos}.
2291 Here is an example of how to scan the buffer by chunks of text within
2292 which all properties are constant:
2296 (let ((plist (text-properties-at (point)))
2298 (or (next-property-change (point) (current-buffer))
2300 @r{Process text from point to @var{next-change}@dots{}}
2301 (goto-char next-change)))
2305 @defun next-single-property-change pos prop &optional object limit
2306 The function scans the text forward from position @var{pos} in the
2307 string or buffer @var{object} till it finds a change in the @var{prop}
2308 property, then returns the position of the change. In other words, it
2309 returns the position of the first character beyond @var{pos} whose
2310 @var{prop} property differs from that of the character just after
2313 If @var{limit} is non-@code{nil}, then the scan ends at position
2314 @var{limit}. If there is no property change before that point,
2315 @code{next-single-property-change} returns @var{limit}.
2317 The value is @code{nil} if the property remains unchanged all the way to
2318 the end of @var{object} and @var{limit} is @code{nil}. If the value is
2319 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
2320 equals @var{pos} only if @var{limit} equals @var{pos}.
2323 @defun previous-property-change pos &optional object limit
2324 This is like @code{next-property-change}, but scans back from @var{pos}
2325 instead of forward. If the value is non-@code{nil}, it is a position
2326 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
2330 @defun previous-single-property-change pos prop &optional object limit
2331 This is like @code{next-single-property-change}, but scans back from
2332 @var{pos} instead of forward. If the value is non-@code{nil}, it is a
2333 position less than or equal to @var{pos}; it equals @var{pos} only if
2334 @var{limit} equals @var{pos}.
2337 @defun text-property-any start end prop value &optional object
2338 This function returns non-@code{nil} if at least one character between
2339 @var{start} and @var{end} has a property @var{prop} whose value is
2340 @var{value}. More precisely, it returns the position of the first such
2341 character. Otherwise, it returns @code{nil}.
2343 The optional fifth argument, @var{object}, specifies the string or
2344 buffer to scan. Positions are relative to @var{object}. The default
2345 for @var{object} is the current buffer.
2348 @defun text-property-not-all start end prop value &optional object
2349 This function returns non-@code{nil} if at least one character between
2350 @var{start} and @var{end} has a property @var{prop} whose value differs
2351 from @var{value}. More precisely, it returns the position of the
2352 first such character. Otherwise, it returns @code{nil}.
2354 The optional fifth argument, @var{object}, specifies the string or
2355 buffer to scan. Positions are relative to @var{object}. The default
2356 for @var{object} is the current buffer.
2359 @node Special Properties
2360 @subsection Properties with Special Meanings
2362 The predefined properties are the same as those for extents.
2363 @xref{Extent Properties}.
2365 @ignore Changed in XEmacs
2366 (deleted section describing FSF Emacs special text properties)
2369 @node Saving Properties
2370 @subsection Saving Text Properties in Files
2371 @cindex text properties in files
2372 @cindex saving text properties
2374 You can save text properties in files, and restore text properties
2375 when inserting the files, using these two hooks:
2377 @defvar write-region-annotate-functions
2378 This variable's value is a list of functions for @code{write-region} to
2379 run to encode text properties in some fashion as annotations to the text
2380 being written in the file. @xref{Writing to Files}.
2382 Each function in the list is called with two arguments: the start and
2383 end of the region to be written. These functions should not alter the
2384 contents of the buffer. Instead, they should return lists indicating
2385 annotations to write in the file in addition to the text in the
2388 Each function should return a list of elements of the form
2389 @code{(@var{position} . @var{string})}, where @var{position} is an
2390 integer specifying the relative position in the text to be written, and
2391 @var{string} is the annotation to add there.
2393 Each list returned by one of these functions must be already sorted in
2394 increasing order by @var{position}. If there is more than one function,
2395 @code{write-region} merges the lists destructively into one sorted list.
2397 When @code{write-region} actually writes the text from the buffer to the
2398 file, it intermixes the specified annotations at the corresponding
2399 positions. All this takes place without modifying the buffer.
2402 @defvar after-insert-file-functions
2403 This variable holds a list of functions for @code{insert-file-contents}
2404 to call after inserting a file's contents. These functions should scan
2405 the inserted text for annotations, and convert them to the text
2406 properties they stand for.
2408 Each function receives one argument, the length of the inserted text;
2409 point indicates the start of that text. The function should scan that
2410 text for annotations, delete them, and create the text properties that
2411 the annotations specify. The function should return the updated length
2412 of the inserted text, as it stands after those changes. The value
2413 returned by one function becomes the argument to the next function.
2415 These functions should always return with point at the beginning of
2418 The intended use of @code{after-insert-file-functions} is for converting
2419 some sort of textual annotations into actual text properties. But other
2420 uses may be possible.
2423 We invite users to write Lisp programs to store and retrieve text
2424 properties in files, using these hooks, and thus to experiment with
2425 various data formats and find good ones. Eventually we hope users
2426 will produce good, general extensions we can install in Emacs.
2428 We suggest not trying to handle arbitrary Lisp objects as property
2429 names or property values---because a program that general is probably
2430 difficult to write, and slow. Instead, choose a set of possible data
2431 types that are reasonably flexible, and not too hard to encode.
2433 @xref{Format Conversion}, for a related feature.
2436 @section Substituting for a Character Code
2438 The following functions replace characters within a specified region
2439 based on their character codes.
2441 @defun subst-char-in-region start end old-char new-char &optional noundo
2442 @cindex replace characters
2443 This function replaces all occurrences of the character @var{old-char}
2444 with the character @var{new-char} in the region of the current buffer
2445 defined by @var{start} and @var{end}.
2447 @cindex Outline mode
2448 @cindex undo avoidance
2449 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
2450 not record the change for undo and does not mark the buffer as modified.
2451 This feature is used for controlling selective display (@pxref{Selective
2454 @code{subst-char-in-region} does not move point and returns
2459 ---------- Buffer: foo ----------
2460 This is the contents of the buffer before.
2461 ---------- Buffer: foo ----------
2465 (subst-char-in-region 1 20 ?i ?X)
2468 ---------- Buffer: foo ----------
2469 ThXs Xs the contents of the buffer before.
2470 ---------- Buffer: foo ----------
2475 @defun translate-region start end table
2476 This function applies a translation table to the characters in the
2477 buffer between positions @var{start} and @var{end}. The translation
2478 table @var{table} can be either a string, a vector, or a char-table.
2480 If @var{table} is a string, its @var{n}th element is the mapping for the
2481 character with code @var{n}.
2483 If @var{table} is a vector, its @var{n}th element is the mapping for
2484 character with code @var{n}. Legal mappings are characters, strings, or
2485 @code{nil} (meaning don't replace.)
2487 If @var{table} is a char-table, its elements describe the mapping
2488 between characters and their replacements. The char-table should be of
2489 type @code{char} or @code{generic}.
2491 When the @var{table} is a string or vector and its length is less than
2492 the total number of characters (256 without Mule), any characters with
2493 codes larger than the length of @var{table} are not altered by the
2496 The return value of @code{translate-region} is the number of
2497 characters that were actually changed by the translation. This does
2498 not count characters that were mapped into themselves in the
2501 @strong{NOTE}: Prior to XEmacs 21.2, the @var{table} argument was
2502 allowed only to be a string. This is still the case in FSF Emacs.
2504 The following example creates a char-table that is passed to
2505 @code{translate-region}, which translates character @samp{a} to
2506 @samp{the letter a}, removes character @samp{b}, and translates
2507 character @samp{c} to newline.
2511 ---------- Buffer: foo ----------
2512 Here is a sentence in the buffer.
2513 ---------- Buffer: foo ----------
2517 (let ((table (make-char-table 'generic)))
2518 (put-char-table ?a "the letter a" table)
2519 (put-char-table ?b "" table)
2520 (put-char-table ?c ?\n table)
2521 (translate-region (point-min) (point-max) table))
2524 ---------- Buffer: foo ----------
2525 Here is the letter a senten
2527 ---------- Buffer: foo ----------
2536 A register is a sort of variable used in XEmacs editing that can hold a
2537 marker, a string, a rectangle, a window configuration (of one frame), or
2538 a frame configuration (of all frames). Each register is named by a
2539 single character. All characters, including control and meta characters
2540 (but with the exception of @kbd{C-g}), can be used to name registers.
2541 Thus, there are 255 possible registers. A register is designated in
2542 Emacs Lisp by a character that is its name.
2544 The functions in this section return unpredictable values unless
2546 @c Will change in version 19
2548 @defvar register-alist
2549 This variable is an alist of elements of the form @code{(@var{name} .
2550 @var{contents})}. Normally, there is one element for each XEmacs
2551 register that has been used.
2553 The object @var{name} is a character (an integer) identifying the
2554 register. The object @var{contents} is a string, marker, or list
2555 representing the register contents. A string represents text stored in
2556 the register. A marker represents a position. A list represents a
2557 rectangle; its elements are strings, one per line of the rectangle.
2560 @defun get-register reg
2561 This function returns the contents of the register
2562 @var{reg}, or @code{nil} if it has no contents.
2565 @defun set-register reg value
2566 This function sets the contents of register @var{reg} to @var{value}.
2567 A register can be set to any value, but the other register functions
2568 expect only certain data types. The return value is @var{value}.
2571 @deffn Command view-register reg
2572 This command displays what is contained in register @var{reg}.
2576 @deffn Command point-to-register reg
2577 This command stores both the current location of point and the current
2578 buffer in register @var{reg} as a marker.
2581 @deffn Command jump-to-register reg
2582 @deffnx Command register-to-point reg
2583 @comment !!SourceFile register.el
2584 This command restores the status recorded in register @var{reg}.
2586 If @var{reg} contains a marker, it moves point to the position stored in
2587 the marker. Since both the buffer and the location within the buffer
2588 are stored by the @code{point-to-register} function, this command can
2589 switch you to another buffer.
2591 If @var{reg} contains a window configuration or a frame configuration.
2592 @code{jump-to-register} restores that configuration.
2596 @deffn Command insert-register reg &optional beforep
2597 This command inserts contents of register @var{reg} into the current
2600 Normally, this command puts point before the inserted text, and the
2601 mark after it. However, if the optional second argument @var{beforep}
2602 is non-@code{nil}, it puts the mark before and point after.
2603 You can pass a non-@code{nil} second argument @var{beforep} to this
2604 function interactively by supplying any prefix argument.
2606 If the register contains a rectangle, then the rectangle is inserted
2607 with its upper left corner at point. This means that text is inserted
2608 in the current line and underneath it on successive lines.
2610 If the register contains something other than saved text (a string) or
2611 a rectangle (a list), currently useless things happen. This may be
2612 changed in the future.
2616 @deffn Command copy-to-register reg start end &optional delete-flag
2617 This command copies the region from @var{start} to @var{end} into
2618 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
2619 the region from the buffer after copying it into the register.
2622 @deffn Command prepend-to-register reg start end &optional delete-flag
2623 This command prepends the region from @var{start} to @var{end} into
2624 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
2625 the region from the buffer after copying it to the register.
2628 @deffn Command append-to-register reg start end &optional delete-flag
2629 This command appends the region from @var{start} to @var{end} to the
2630 text already in register @var{reg}. If @var{delete-flag} is
2631 non-@code{nil}, it deletes the region from the buffer after copying it
2635 @deffn Command copy-rectangle-to-register reg start end &optional delete-flag
2636 This command copies a rectangular region from @var{start} to @var{end}
2637 into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it
2638 deletes the region from the buffer after copying it to the register.
2641 @deffn Command window-configuration-to-register reg
2642 This function stores the window configuration of the selected frame in
2646 @deffn Command frame-configuration-to-register reg
2647 This function stores the current frame configuration in register
2653 @section Transposition of Text
2655 This subroutine is used by the transposition commands.
2657 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
2658 This function exchanges two nonoverlapping portions of the buffer.
2659 Arguments @var{start1} and @var{end1} specify the bounds of one portion
2660 and arguments @var{start2} and @var{end2} specify the bounds of the
2663 Normally, @code{transpose-regions} relocates markers with the transposed
2664 text; a marker previously positioned within one of the two transposed
2665 portions moves along with that portion, thus remaining between the same
2666 two characters in their new position. However, if @var{leave-markers}
2667 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
2668 all markers unrelocated.
2672 @section Change Hooks
2673 @cindex change hooks
2674 @cindex hooks for text changes
2676 These hook variables let you arrange to take notice of all changes in
2677 all buffers (or in a particular buffer, if you make them buffer-local).
2678 @ignore Not in XEmacs
2679 See also @ref{Special Properties}, for how to detect changes to specific
2683 The functions you use in these hooks should save and restore the match
2684 data if they do anything that uses regular expressions; otherwise, they
2685 will interfere in bizarre ways with the editing operations that call
2688 Buffer changes made while executing the following hooks don't
2689 themselves cause any change hooks to be invoked.
2691 @defvar before-change-functions
2692 This variable holds a list of a functions to call before any buffer
2693 modification. Each function gets two arguments, the beginning and end
2694 of the region that is about to change, represented as integers. The
2695 buffer that is about to change is always the current buffer.
2698 @defvar after-change-functions
2699 This variable holds a list of a functions to call after any buffer
2700 modification. Each function receives three arguments: the beginning and
2701 end of the region just changed, and the length of the text that existed
2702 before the change. (To get the current length, subtract the region
2703 beginning from the region end.) All three arguments are integers. The
2704 buffer that's about to change is always the current buffer.
2707 @defvar before-change-function
2708 This obsolete variable holds one function to call before any buffer
2709 modification (or @code{nil} for no function). It is called just like
2710 the functions in @code{before-change-functions}.
2713 @defvar after-change-function
2714 This obsolete variable holds one function to call after any buffer modification
2715 (or @code{nil} for no function). It is called just like the functions in
2716 @code{after-change-functions}.
2719 @defvar first-change-hook
2720 This variable is a normal hook that is run whenever a buffer is changed
2721 that was previously in the unmodified state.
2724 @node Transformations
2725 @section Textual transformations---MD5 and base64 support
2729 Some textual operations inherently require examining each character in
2730 turn, and performing arithmetic operations on them. Such operations
2731 can, of course, be implemented in Emacs Lisp, but tend to be very slow
2732 for large portions of text or data. This is why some of them are
2733 implemented in C, with an appropriate interface for Lisp programmers.
2734 Examples of algorithms thus provided are MD5 and base64 support.
2736 MD5 is an algorithm for calculating message digests, as described in
2737 rfc1321. Given a message of arbitrary length, MD5 produces an 128-bit
2738 ``fingerprint'' (``message digest'') corresponding to that message. It
2739 is considered computationally infeasible to produce two messages having
2740 the same MD5 digest, or to produce a message having a prespecified
2741 target digest. MD5 is used heavily by various authentication schemes.
2743 Emacs Lisp interface to MD5 consists of a single function @code{md5}:
2745 @defun md5 object &optional start end
2746 This function returns the MD5 message digest of @var{object}, a buffer
2749 Optional arguments @var{start} and @var{end} denote positions for
2750 computing the digest of a portion of @var{object}.
2752 Some examples of usage:
2756 ;; @r{Calculate the digest of the entire buffer}
2757 (md5 (current-buffer))
2758 @result{} "8842b04362899b1cda8d2d126dc11712"
2762 ;; @r{Calculate the digest of the current line}
2763 (md5 (current-buffer) (point-at-bol) (point-at-eol))
2764 @result{} "60614d21e9dee27dfdb01fa4e30d6d00"
2768 ;; @r{Calculate the digest of your name and email address}
2769 (md5 (concat (format "%s <%s>" (user-full-name) user-mail-address)))
2770 @result{} "0a2188c40fd38922d941fe6032fce516"
2775 Base64 is a portable encoding for arbitrary sequences of octets, in a
2776 form that need not be readable by humans. It uses a 65-character subset
2777 of US-ASCII, as described in rfc2045. Base64 is used by MIME to encode
2778 binary bodies, and to encode binary characters in message headers.
2780 The Lisp interface to base64 consists of four functions:
2782 @defun base64-encode-region beg end &optional no-line-break
2783 This function encodes the region between @var{beg} and @var{end} of the
2784 current buffer to base64 format. This means that the original region is
2785 deleted, and replaced with its base64 equivalent.
2787 Normally, encoded base64 output is multi-line, with 76-character lines.
2788 If @var{no-line-break} is non-@code{nil}, newlines will not be inserted,
2789 resulting in single-line output.
2791 Mule note: you should make sure that you convert the multibyte
2792 characters (those that do not fit into 0--255 range) to something else,
2793 because they cannot be meaningfully converted to base64. If the
2794 @code{base64-encode-region} encounters such characters, it will signal
2797 @code{base64-encode-region} returns the length of the encoded text.
2801 ;; @r{Encode the whole buffer in base64}
2802 (base64-encode-region (point-min) (point-max))
2806 The function can also be used interactively, in which case it works on
2807 the currently active region.
2810 @defun base64-encode-string string
2811 This function encodes @var{string} to base64, and returns the encoded
2814 For Mule, the same considerations apply as for
2815 @code{base64-encode-region}.
2819 (base64-encode-string "fubar")
2820 @result{} "ZnViYXI="
2825 @defun base64-decode-region beg end
2826 This function decodes the region between @var{beg} and @var{end} of the
2827 current buffer. The region should be in base64 encoding.
2829 If the region was decoded correctly, @code{base64-decode-region} returns
2830 the length of the decoded region. If the decoding failed, @code{nil} is
2835 ;; @r{Decode a base64 buffer, and replace it with the decoded version}
2836 (base64-decode-region (point-min) (point-max))
2841 @defun base64-decode-string string
2842 This function decodes @var{string} to base64, and returns the decoded
2843 string. @var{string} should be valid base64-encoded text.
2845 If encoding was not possible, @code{nil} is returned.
2849 (base64-decode-string "ZnViYXI=")
2854 (base64-decode-string "totally bogus")