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 &optional count ignored 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.
337 If optional argument @var{buffer} is @code{nil}, the current buffer is
338 assumed. (In FSF Emacs, the third argument is called @var{inherit} and
339 refers to text properties. In XEmacs, it is always ignored.)
341 This function always returns @code{nil}.
344 @defun insert-buffer-substring from-buffer-or-name &optional start end
345 This function inserts a portion of buffer @var{from-buffer-or-name}
346 (which must already exist) into the current buffer before point. The
347 text inserted is the region from @var{start} and @var{end}. (These
348 arguments default to the beginning and end of the accessible portion of
349 that buffer.) This function returns @code{nil}.
351 In this example, the form is executed with buffer @samp{bar} as the
352 current buffer. We assume that buffer @samp{bar} is initially empty.
356 ---------- Buffer: foo ----------
357 We hold these truths to be self-evident, that all
358 ---------- Buffer: foo ----------
362 (insert-buffer-substring "foo" 1 20)
365 ---------- Buffer: bar ----------
366 We hold these truth@point{}
367 ---------- Buffer: bar ----------
372 @node Commands for Insertion
373 @section User-Level Insertion Commands
375 This section describes higher-level commands for inserting text,
376 commands intended primarily for the user but useful also in Lisp
379 @deffn Command insert-buffer from-buffer-or-name
380 This command inserts the entire contents of @var{from-buffer-or-name}
381 (which must exist) into the current buffer after point. It leaves
382 the mark after the inserted text. The value is @code{nil}.
385 @deffn Command self-insert-command count
386 @cindex character insertion
387 @cindex self-insertion
388 This command inserts the last character typed; it does so @var{count}
389 times, before point, and returns @code{nil}. Most printing characters
390 are bound to this command. In routine use, @code{self-insert-command}
391 is the most frequently called function in XEmacs, but programs rarely use
392 it except to install it on a keymap.
394 In an interactive call, @var{count} is the numeric prefix argument.
396 This command calls @code{auto-fill-function} whenever that is
397 non-@code{nil} and the character inserted is a space or a newline
398 (@pxref{Auto Filling}).
400 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
401 This command performs abbrev expansion if Abbrev mode is enabled and
402 the inserted character does not have word-constituent
403 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
405 This is also responsible for calling @code{blink-paren-function} when
406 the inserted character has close parenthesis syntax (@pxref{Blinking}).
409 @deffn Command newline &optional count
410 This command inserts newlines into the current buffer before point.
411 If @var{count} is supplied, that many newline characters
414 @cindex newline and Auto Fill mode
415 This function calls @code{auto-fill-function} if the current column
416 number is greater than the value of @code{fill-column} and
417 @var{count} is @code{nil}. Typically what
418 @code{auto-fill-function} does is insert a newline; thus, the overall
419 result in this case is to insert two newlines at different places: one
420 at point, and another earlier in the line. @code{newline} does not
421 auto-fill if @var{count} is non-@code{nil}.
423 This command indents to the left margin if that is not zero.
426 The value returned is @code{nil}. In an interactive call, @var{count}
427 is the numeric prefix argument.
430 @deffn Command split-line
431 This command splits the current line, moving the portion of the line
432 after point down vertically so that it is on the next line directly
433 below where it was before. Whitespace is inserted as needed at the
434 beginning of the lower line, using the @code{indent-to} function.
435 @code{split-line} returns the position of point.
437 Programs hardly ever use this function.
440 @defvar overwrite-mode
441 This variable controls whether overwrite mode is in effect: a
442 non-@code{nil} value enables the mode. It is automatically made
443 buffer-local when set in any fashion.
447 @section Deleting Text
449 @cindex deletion vs killing
450 Deletion means removing part of the text in a buffer, without saving
451 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
452 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
453 Some deletion functions do save text in the kill ring in some special
456 All of the deletion functions operate on the current buffer, and all
457 return a value of @code{nil}.
459 @deffn Command erase-buffer &optional buffer
460 This function deletes the entire text of @var{buffer}, leaving it
461 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
462 error. Otherwise, it deletes the text without asking for any
463 confirmation. It returns @code{nil}. @var{buffer} defaults to the
464 current buffer if omitted.
466 Normally, deleting a large amount of text from a buffer inhibits further
467 auto-saving of that buffer ``because it has shrunk''. However,
468 @code{erase-buffer} does not do this, the idea being that the future
469 text is not really related to the former text, and its size should not
470 be compared with that of the former text.
473 @deffn Command delete-region start end &optional buffer
474 This command deletes the text in @var{buffer} in the region defined by
475 @var{start} and @var{end}. The value is @code{nil}. If optional
476 argument @var{buffer} is @code{nil}, the current buffer is assumed.
479 @deffn Command delete-char count &optional killp
480 This command deletes @var{count} characters directly after point, or
481 before point if @var{count} is negative. If @var{killp} is
482 non-@code{nil}, then it saves the deleted characters in the kill ring.
484 In an interactive call, @var{count} is the numeric prefix argument, and
485 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
486 argument is supplied, the text is saved in the kill ring. If no prefix
487 argument is supplied, then one character is deleted, but not saved in
490 The value returned is always @code{nil}.
493 @deffn Command delete-backward-char count &optional killp
494 @cindex delete previous char
495 This command deletes @var{count} characters directly before point, or
496 after point if @var{count} is negative. If @var{killp} is
497 non-@code{nil}, then it saves the deleted characters in the kill ring.
499 In an interactive call, @var{count} is the numeric prefix argument, and
500 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
501 argument is supplied, the text is saved in the kill ring. If no prefix
502 argument is supplied, then one character is deleted, but not saved in
505 The value returned is always @code{nil}.
508 @deffn Command backward-delete-char-untabify count &optional killp
510 This command deletes @var{count} characters backward, changing tabs
511 into spaces. When the next character to be deleted is a tab, it is
512 first replaced with the proper number of spaces to preserve alignment
513 and then one of those spaces is deleted instead of the tab. If
514 @var{killp} is non-@code{nil}, then the command saves the deleted
515 characters in the kill ring.
517 Conversion of tabs to spaces happens only if @var{count} is positive.
518 If it is negative, exactly @minus{}@var{count} characters after point
521 In an interactive call, @var{count} is the numeric prefix argument, and
522 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
523 argument is supplied, the text is saved in the kill ring. If no prefix
524 argument is supplied, then one character is deleted, but not saved in
527 The value returned is always @code{nil}.
530 @node User-Level Deletion
531 @section User-Level Deletion Commands
533 This section describes higher-level commands for deleting text,
534 commands intended primarily for the user but useful also in Lisp
537 @deffn Command delete-horizontal-space
538 @cindex deleting whitespace
539 This function deletes all spaces and tabs around point. It returns
542 In the following examples, we call @code{delete-horizontal-space} four
543 times, once on each line, with point between the second and third
544 characters on the line each time.
548 ---------- Buffer: foo ----------
553 ---------- Buffer: foo ----------
557 (delete-horizontal-space) ; @r{Four times.}
560 ---------- Buffer: foo ----------
565 ---------- Buffer: foo ----------
570 @deffn Command delete-indentation &optional join-following-p
571 This function joins the line point is on to the previous line, deleting
572 any whitespace at the join and in some cases replacing it with one
573 space. If @var{join-following-p} is non-@code{nil},
574 @code{delete-indentation} joins this line to the following line
575 instead. The value is @code{nil}.
577 If there is a fill prefix, and the second of the lines being joined
578 starts with the prefix, then @code{delete-indentation} deletes the
579 fill prefix before joining the lines. @xref{Margins}.
581 In the example below, point is located on the line starting
582 @samp{events}, and it makes no difference if there are trailing spaces
583 in the preceding line.
587 ---------- Buffer: foo ----------
588 When in the course of human
589 @point{} events, it becomes necessary
590 ---------- Buffer: foo ----------
597 ---------- Buffer: foo ----------
598 When in the course of human@point{} events, it becomes necessary
599 ---------- Buffer: foo ----------
603 After the lines are joined, the function @code{fixup-whitespace} is
604 responsible for deciding whether to leave a space at the junction.
607 @deffn Command fixup-whitespace
608 This function replaces all the white space surrounding point with either
609 one space or no space, according to the context. It returns @code{nil}.
611 At the beginning or end of a line, the appropriate amount of space is
612 none. Before a character with close parenthesis syntax, or after a
613 character with open parenthesis or expression-prefix syntax, no space is
614 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
617 In the example below, @code{fixup-whitespace} is called the first time
618 with point before the word @samp{spaces} in the first line. For the
619 second invocation, point is directly after the @samp{(}.
623 ---------- Buffer: foo ----------
624 This has too many @point{}spaces
625 This has too many spaces at the start of (@point{} this list)
626 ---------- Buffer: foo ----------
637 ---------- Buffer: foo ----------
638 This has too many spaces
639 This has too many spaces at the start of (this list)
640 ---------- Buffer: foo ----------
645 @deffn Command just-one-space
646 @comment !!SourceFile simple.el
647 This command replaces any spaces and tabs around point with a single
648 space. It returns @code{nil}.
651 @deffn Command delete-blank-lines
652 This function deletes blank lines surrounding point. If point is on a
653 blank line with one or more blank lines before or after it, then all but
654 one of them are deleted. If point is on an isolated blank line, then it
655 is deleted. If point is on a nonblank line, the command deletes all
656 blank lines following it.
658 A blank line is defined as a line containing only tabs and spaces.
660 @code{delete-blank-lines} returns @code{nil}.
664 @section The Kill Ring
667 @dfn{Kill} functions delete text like the deletion functions, but save
668 it so that the user can reinsert it by @dfn{yanking}. Most of these
669 functions have @samp{kill-} in their name. By contrast, the functions
670 whose names start with @samp{delete-} normally do not save text for
671 yanking (though they can still be undone); these are ``deletion''
674 Most of the kill commands are primarily for interactive use, and are
675 not described here. What we do describe are the functions provided for
676 use in writing such commands. You can use these functions to write
677 commands for killing text. When you need to delete text for internal
678 purposes within a Lisp function, you should normally use deletion
679 functions, so as not to disturb the kill ring contents.
682 Killed text is saved for later yanking in the @dfn{kill ring}. This
683 is a list that holds a number of recent kills, not just the last text
684 kill. We call this a ``ring'' because yanking treats it as having
685 elements in a cyclic order. The list is kept in the variable
686 @code{kill-ring}, and can be operated on with the usual functions for
687 lists; there are also specialized functions, described in this section,
688 that treat it as a ring.
690 Some people think this use of the word ``kill'' is unfortunate, since
691 it refers to operations that specifically @emph{do not} destroy the
692 entities ``killed''. This is in sharp contrast to ordinary life, in
693 which death is permanent and ``killed'' entities do not come back to
694 life. Therefore, other metaphors have been proposed. For example, the
695 term ``cut ring'' makes sense to people who, in pre-computer days, used
696 scissors and paste to cut up and rearrange manuscripts. However, it
697 would be difficult to change the terminology now.
700 * Kill Ring Concepts:: What text looks like in the kill ring.
701 * Kill Functions:: Functions that kill text.
702 * Yank Commands:: Commands that access the kill ring.
703 * Low-Level Kill Ring:: Functions and variables for kill ring access.
704 * Internals of Kill Ring:: Variables that hold kill-ring data.
707 @node Kill Ring Concepts
708 @subsection Kill Ring Concepts
710 The kill ring records killed text as strings in a list, most recent
711 first. A short kill ring, for example, might look like this:
714 ("some text" "a different piece of text" "even older text")
718 When the list reaches @code{kill-ring-max} entries in length, adding a
719 new entry automatically deletes the last entry.
721 When kill commands are interwoven with other commands, each kill
722 command makes a new entry in the kill ring. Multiple kill commands in
723 succession build up a single entry in the kill ring, which would be
724 yanked as a unit; the second and subsequent consecutive kill commands
725 add text to the entry made by the first one.
727 For yanking, one entry in the kill ring is designated the ``front'' of
728 the ring. Some yank commands ``rotate'' the ring by designating a
729 different element as the ``front.'' But this virtual rotation doesn't
730 change the list itself---the most recent entry always comes first in the
734 @subsection Functions for Killing
736 @code{kill-region} is the usual subroutine for killing text. Any
737 command that calls this function is a ``kill command'' (and should
738 probably have @samp{kill} in its name). @code{kill-region} puts the
739 newly killed text in a new element at the beginning of the kill ring or
740 adds it to the most recent element. It uses the @code{last-command}
741 variable to determine whether the previous command was a kill command,
742 and if so appends the killed text to the most recent entry.
744 @deffn Command kill-region start end &optional verbose
745 This function kills the text in the region defined by @var{start} and
746 @var{end}. The text is deleted but saved in the kill ring, along with
747 its text properties. The value is always @code{nil}.
749 In an interactive call, @var{start} and @var{end} are point and
753 If the buffer is read-only, @code{kill-region} modifies the kill ring
754 just the same, then signals an error without modifying the buffer. This
755 is convenient because it lets the user use all the kill commands to copy
756 text into the kill ring from a read-only buffer.
759 @deffn Command copy-region-as-kill start end
760 This command saves the region defined by @var{start} and @var{end} on
761 the kill ring (including text properties), but does not delete the text
762 from the buffer. It returns @code{nil}. It also indicates the extent
763 of the text copied by moving the cursor momentarily, or by displaying a
764 message in the echo area.
766 The command does not set @code{this-command} to @code{kill-region}, so a
767 subsequent kill command does not append to the same kill ring entry.
769 Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
770 support Emacs 18. For Emacs 19, it is better to use @code{kill-new} or
771 @code{kill-append} instead. @xref{Low-Level Kill Ring}.
775 @subsection Functions for Yanking
777 @dfn{Yanking} means reinserting an entry of previously killed text
778 from the kill ring. The text properties are copied too.
780 @deffn Command yank &optional arg
781 @cindex inserting killed text
782 This command inserts before point the text in the first entry in the
783 kill ring. It positions the mark at the beginning of that text, and
786 If @var{arg} is a list (which occurs interactively when the user
787 types @kbd{C-u} with no digits), then @code{yank} inserts the text as
788 described above, but puts point before the yanked text and puts the mark
791 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most
792 recently killed text---the @var{arg}th element of the kill ring list.
794 @code{yank} does not alter the contents of the kill ring or rotate it.
795 It returns @code{nil}.
798 @deffn Command yank-pop arg
799 This command replaces the just-yanked entry from the kill ring with a
800 different entry from the kill ring.
802 This is allowed only immediately after a @code{yank} or another
803 @code{yank-pop}. At such a time, the region contains text that was just
804 inserted by yanking. @code{yank-pop} deletes that text and inserts in
805 its place a different piece of killed text. It does not add the deleted
806 text to the kill ring, since it is already in the kill ring somewhere.
808 If @var{arg} is @code{nil}, then the replacement text is the previous
809 element of the kill ring. If @var{arg} is numeric, the replacement is
810 the @var{arg}th previous kill. If @var{arg} is negative, a more recent
811 kill is the replacement.
813 The sequence of kills in the kill ring wraps around, so that after the
814 oldest one comes the newest one, and before the newest one goes the
817 The value is always @code{nil}.
820 @node Low-Level Kill Ring
821 @subsection Low-Level Kill Ring
823 These functions and variables provide access to the kill ring at a lower
824 level, but still convenient for use in Lisp programs. They take care of
825 interaction with X Window selections. They do not exist in Emacs
828 @defun current-kill count &optional do-not-move
829 The function @code{current-kill} rotates the yanking pointer which
830 designates the ``front'' of the kill ring by @var{count} places (from newer
831 kills to older ones), and returns the text at that place in the ring.
833 If the optional second argument @var{do-not-move} is non-@code{nil},
834 then @code{current-kill} doesn't alter the yanking pointer; it just
835 returns the @var{count}th kill, counting from the current yanking pointer.
837 If @var{count} is zero, indicating a request for the latest kill,
838 @code{current-kill} calls the value of
839 @code{interprogram-paste-function} (documented below) before consulting
843 @defun kill-new string &optional replace
844 This function makes the text @var{string} the latest entry in the kill
845 ring, and sets @code{kill-ring-yank-pointer} to point to it.
847 Normally, @var{string} is added to the front of the kill ring as a new
848 entry. However, if optional argument @var{replace} is non-@code{nil},
849 the entry previously at the front of the kill ring is discarded, and
850 @var{string} replaces it.
852 This function runs the functions on @code{kill-hooks}, and also invokes
853 the value of @code{interprogram-cut-function} (see below).
856 @defun kill-append string before-p
857 This function appends the text @var{string} to the first entry in the
858 kill ring. Normally @var{string} goes at the end of the entry, but if
859 @var{before-p} is non-@code{nil}, it goes at the beginning. This
860 function also invokes the value of @code{interprogram-cut-function} (see
864 @defvar interprogram-paste-function
865 This variable provides a way of transferring killed text from other
866 programs, when you are using a window system. Its value should be
867 @code{nil} or a function of no arguments.
869 If the value is a function, @code{current-kill} calls it to get the
870 ``most recent kill''. If the function returns a non-@code{nil} value,
871 then that value is used as the ``most recent kill''. If it returns
872 @code{nil}, then the first element of @code{kill-ring} is used.
874 The normal use of this hook is to get the X server's primary selection
875 as the most recent kill, even if the selection belongs to another X
876 client. @xref{X Selections}.
879 @defvar interprogram-cut-function
880 This variable provides a way of communicating killed text to other
881 programs, when you are using a window system. Its value should be
882 @code{nil} or a function of one argument.
884 If the value is a function, @code{kill-new} and @code{kill-append} call
885 it with the new first element of the kill ring as an argument.
887 The normal use of this hook is to set the X server's primary selection
888 to the newly killed text.
891 @node Internals of Kill Ring
892 @subsection Internals of the Kill Ring
894 The variable @code{kill-ring} holds the kill ring contents, in the
895 form of a list of strings. The most recent kill is always at the front
898 The @code{kill-ring-yank-pointer} variable points to a link in the
899 kill ring list, whose @sc{car} is the text to yank next. We say it
900 identifies the ``front'' of the ring. Moving
901 @code{kill-ring-yank-pointer} to a different link is called
902 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
903 the functions that move the yank pointer wrap around from the end of the
904 list to the beginning, or vice-versa. Rotation of the kill ring is
905 virtual; it does not change the value of @code{kill-ring}.
907 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
908 variables whose values are normally lists. The word ``pointer'' in the
909 name of the @code{kill-ring-yank-pointer} indicates that the variable's
910 purpose is to identify one element of the list for use by the next yank
913 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
914 of the links in the kill ring list. The element it identifies is the
915 @sc{car} of that link. Kill commands, which change the kill ring, also
916 set this variable to the value of @code{kill-ring}. The effect is to
917 rotate the ring so that the newly killed text is at the front.
919 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
920 pointing to the second entry in the kill ring @code{("some text" "a
921 different piece of text" "yet older text")}.
925 kill-ring kill-ring-yank-pointer
927 | ___ ___ ---> ___ ___ ___ ___
928 --> |___|___|------> |___|___|--> |___|___|--> nil
931 | | -->"yet older text"
933 | --> "a different piece of text"
940 This state of affairs might occur after @kbd{C-y} (@code{yank})
941 immediately followed by @kbd{M-y} (@code{yank-pop}).
944 This variable holds the list of killed text sequences, most recently
948 @defvar kill-ring-yank-pointer
949 This variable's value indicates which element of the kill ring is at the
950 ``front'' of the ring for yanking. More precisely, the value is a tail
951 of the value of @code{kill-ring}, and its @sc{car} is the kill string
952 that @kbd{C-y} should yank.
955 @defopt kill-ring-max
956 The value of this variable is the maximum length to which the kill
957 ring can grow, before elements are thrown away at the end. The default
958 value for @code{kill-ring-max} is 30.
965 Most buffers have an @dfn{undo list}, which records all changes made
966 to the buffer's text so that they can be undone. (The buffers that
967 don't have one are usually special-purpose buffers for which XEmacs
968 assumes that undoing is not useful.) All the primitives that modify the
969 text in the buffer automatically add elements to the front of the undo
970 list, which is in the variable @code{buffer-undo-list}.
972 @defvar buffer-undo-list
973 This variable's value is the undo list of the current buffer.
974 A value of @code{t} disables the recording of undo information.
977 Here are the kinds of elements an undo list can have:
981 This kind of element records a previous value of point. Ordinary cursor
982 motion does not get any sort of undo record, but deletion commands use
983 these entries to record where point was before the command.
985 @item (@var{start} . @var{end})
986 This kind of element indicates how to delete text that was inserted.
987 Upon insertion, the text occupied the range @var{start}--@var{end} in the
990 @item (@var{text} . @var{position})
991 This kind of element indicates how to reinsert text that was deleted.
992 The deleted text itself is the string @var{text}. The place to
993 reinsert it is @code{(abs @var{position})}.
995 @item (t @var{high} . @var{low})
996 This kind of element indicates that an unmodified buffer became
997 modified. The elements @var{high} and @var{low} are two integers, each
998 recording 16 bits of the visited file's modification time as of when it
999 was previously visited or saved. @code{primitive-undo} uses those
1000 values to determine whether to mark the buffer as unmodified once again;
1001 it does so only if the file's modification time matches those numbers.
1003 @item (nil @var{property} @var{value} @var{start} . @var{end})
1004 This kind of element records a change in a text property.
1005 Here's how you might undo the change:
1008 (put-text-property @var{start} @var{end} @var{property} @var{value})
1011 @item @var{position}
1012 This element indicates where point was at an earlier time. Undoing this
1013 element sets point to @var{position}. Deletion normally creates an
1014 element of this kind as well as a reinsertion element.
1017 This element is a boundary. The elements between two boundaries are
1018 called a @dfn{change group}; normally, each change group corresponds to
1019 one keyboard command, and undo commands normally undo an entire group as
1023 @defun undo-boundary
1024 This function places a boundary element in the undo list. The undo
1025 command stops at such a boundary, and successive undo commands undo
1026 to earlier and earlier boundaries. This function returns @code{nil}.
1028 The editor command loop automatically creates an undo boundary before
1029 each key sequence is executed. Thus, each undo normally undoes the
1030 effects of one command. Self-inserting input characters are an
1031 exception. The command loop makes a boundary for the first such
1032 character; the next 19 consecutive self-inserting input characters do
1033 not make boundaries, and then the 20th does, and so on as long as
1034 self-inserting characters continue.
1036 All buffer modifications add a boundary whenever the previous undoable
1037 change was made in some other buffer. This way, a command that modifies
1038 several buffers makes a boundary in each buffer it changes.
1040 Calling this function explicitly is useful for splitting the effects of
1041 a command into more than one unit. For example, @code{query-replace}
1042 calls @code{undo-boundary} after each replacement, so that the user can
1043 undo individual replacements one by one.
1046 @defun primitive-undo count list
1047 This is the basic function for undoing elements of an undo list.
1048 It undoes the first @var{count} elements of @var{list}, returning
1049 the rest of @var{list}. You could write this function in Lisp,
1050 but it is convenient to have it in C.
1052 @code{primitive-undo} adds elements to the buffer's undo list when it
1053 changes the buffer. Undo commands avoid confusion by saving the undo
1054 list value at the beginning of a sequence of undo operations. Then the
1055 undo operations use and update the saved value. The new elements added
1056 by undoing are not part of this saved value, so they don't interfere with
1060 @node Maintaining Undo
1061 @section Maintaining Undo Lists
1063 This section describes how to enable and disable undo information for
1064 a given buffer. It also explains how the undo list is truncated
1065 automatically so it doesn't get too big.
1067 Recording of undo information in a newly created buffer is normally
1068 enabled to start with; but if the buffer name starts with a space, the
1069 undo recording is initially disabled. You can explicitly enable or
1070 disable undo recording with the following two functions, or by setting
1071 @code{buffer-undo-list} yourself.
1073 @deffn Command buffer-enable-undo &optional buffer-or-name
1074 This command enables recording undo information for buffer
1075 @var{buffer-or-name}, so that subsequent changes can be undone. If no
1076 argument is supplied, then the current buffer is used. This function
1077 does nothing if undo recording is already enabled in the buffer. It
1080 In an interactive call, @var{buffer-or-name} is the current buffer.
1081 You cannot specify any other buffer.
1084 @deffn Command buffer-disable-undo &optional buffer
1085 @deffnx Command buffer-flush-undo &optional buffer
1086 @cindex disable undo
1087 This function discards the undo list of @var{buffer}, and disables
1088 further recording of undo information. As a result, it is no longer
1089 possible to undo either previous changes or any subsequent changes. If
1090 the undo list of @var{buffer} is already disabled, this function
1093 This function returns @code{nil}. It cannot be called interactively.
1095 The name @code{buffer-flush-undo} is not considered obsolete, but the
1096 preferred name @code{buffer-disable-undo} is new as of Emacs versions
1100 As editing continues, undo lists get longer and longer. To prevent
1101 them from using up all available memory space, garbage collection trims
1102 them back to size limits you can set. (For this purpose, the ``size''
1103 of an undo list measures the cons cells that make up the list, plus the
1104 strings of deleted text.) Two variables control the range of acceptable
1105 sizes: @code{undo-limit} and @code{undo-strong-limit}.
1108 This is the soft limit for the acceptable size of an undo list. The
1109 change group at which this size is exceeded is the last one kept.
1112 @defvar undo-strong-limit
1113 This is the upper limit for the acceptable size of an undo list. The
1114 change group at which this size is exceeded is discarded itself (along
1115 with all older change groups). There is one exception: the very latest
1116 change group is never discarded no matter how big it is.
1121 @cindex filling, explicit
1123 @dfn{Filling} means adjusting the lengths of lines (by moving the line
1124 breaks) so that they are nearly (but no greater than) a specified
1125 maximum width. Additionally, lines can be @dfn{justified}, which means
1126 inserting spaces to make the left and/or right margins line up
1127 precisely. The width is controlled by the variable @code{fill-column}.
1128 For ease of reading, lines should be no longer than 70 or so columns.
1130 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1131 automatically as you insert it, but changes to existing text may leave
1132 it improperly filled. Then you must fill the text explicitly.
1134 Most of the commands in this section return values that are not
1135 meaningful. All the functions that do filling take note of the current
1136 left margin, current right margin, and current justification style
1137 (@pxref{Margins}). If the current justification style is
1138 @code{none}, the filling functions don't actually do anything.
1140 Several of the filling functions have an argument @var{justify}.
1141 If it is non-@code{nil}, that requests some kind of justification. It
1142 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
1143 request a specific style of justification. If it is @code{t}, that
1144 means to use the current justification style for this part of the text
1145 (see @code{current-justification}, below).
1147 When you call the filling functions interactively, using a prefix
1148 argument implies the value @code{full} for @var{justify}.
1150 @deffn Command fill-paragraph justify
1151 @cindex filling a paragraph
1152 This command fills the paragraph at or after point. If
1153 @var{justify} is non-@code{nil}, each line is justified as well.
1154 It uses the ordinary paragraph motion commands to find paragraph
1155 boundaries. @xref{Paragraphs,,, xemacs, The XEmacs User's Manual}.
1158 @deffn Command fill-region start end &optional justify
1159 This command fills each of the paragraphs in the region from @var{start}
1160 to @var{end}. It justifies as well if @var{justify} is
1163 The variable @code{paragraph-separate} controls how to distinguish
1164 paragraphs. @xref{Standard Regexps}.
1167 @deffn Command fill-individual-paragraphs start end &optional justify mail-flag
1168 This command fills each paragraph in the region according to its
1169 individual fill prefix. Thus, if the lines of a paragraph were indented
1170 with spaces, the filled paragraph will remain indented in the same
1173 The first two arguments, @var{start} and @var{end}, are the beginning
1174 and end of the region to be filled. The third and fourth arguments,
1175 @var{justify} and @var{mail-flag}, are optional. If
1176 @var{justify} is non-@code{nil}, the paragraphs are justified as
1177 well as filled. If @var{mail-flag} is non-@code{nil}, it means the
1178 function is operating on a mail message and therefore should not fill
1181 Ordinarily, @code{fill-individual-paragraphs} regards each change in
1182 indentation as starting a new paragraph. If
1183 @code{fill-individual-varying-indent} is non-@code{nil}, then only
1184 separator lines separate paragraphs. That mode can handle indented
1185 paragraphs with additional indentation on the first line.
1188 @defopt fill-individual-varying-indent
1189 This variable alters the action of @code{fill-individual-paragraphs} as
1193 @deffn Command fill-region-as-paragraph start end &optional justify
1194 This command considers a region of text as a paragraph and fills it. If
1195 the region was made up of many paragraphs, the blank lines between
1196 paragraphs are removed. This function justifies as well as filling when
1197 @var{justify} is non-@code{nil}.
1199 In an interactive call, any prefix argument requests justification.
1201 In Adaptive Fill mode, which is enabled by default,
1202 @code{fill-region-as-paragraph} on an indented paragraph when there is
1203 no fill prefix uses the indentation of the second line of the paragraph
1207 @deffn Command justify-current-line how eop nosqueeze
1208 This command inserts spaces between the words of the current line so
1209 that the line ends exactly at @code{fill-column}. It returns
1212 The argument @var{how}, if non-@code{nil} specifies explicitly the style
1213 of justification. It can be @code{left}, @code{right}, @code{full},
1214 @code{center}, or @code{none}. If it is @code{t}, that means to do
1215 follow specified justification style (see @code{current-justification},
1216 below). @code{nil} means to do full justification.
1218 If @var{eop} is non-@code{nil}, that means do left-justification when
1219 @code{current-justification} specifies full justification. This is used
1220 for the last line of a paragraph; even if the paragraph as a whole is
1221 fully justified, the last line should not be.
1223 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1227 @defopt default-justification
1228 This variable's value specifies the style of justification to use for
1229 text that doesn't specify a style with a text property. The possible
1230 values are @code{left}, @code{right}, @code{full}, @code{center}, or
1231 @code{none}. The default value is @code{left}.
1234 @defun current-justification
1235 This function returns the proper justification style to use for filling
1236 the text around point.
1239 @defvar fill-paragraph-function
1240 This variable provides a way for major modes to override the filling of
1241 paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
1242 this function to do the work. If the function returns a non-@code{nil}
1243 value, @code{fill-paragraph} assumes the job is done, and immediately
1246 The usual use of this feature is to fill comments in programming
1247 language modes. If the function needs to fill a paragraph in the usual
1248 way, it can do so as follows:
1251 (let ((fill-paragraph-function nil))
1252 (fill-paragraph arg))
1256 @defvar use-hard-newlines
1257 If this variable is non-@code{nil}, the filling functions do not delete
1258 newlines that have the @code{hard} text property. These ``hard
1259 newlines'' act as paragraph separators.
1263 @section Margins for Filling
1266 This variable specifies a string of text that appears at the beginning
1267 of normal text lines and should be disregarded when filling them. Any
1268 line that fails to start with the fill prefix is considered the start of
1269 a paragraph; so is any line that starts with the fill prefix followed by
1270 additional whitespace. Lines that start with the fill prefix but no
1271 additional whitespace are ordinary text lines that can be filled
1272 together. The resulting filled lines also start with the fill prefix.
1274 The fill prefix follows the left margin whitespace, if any.
1278 This buffer-local variable specifies the maximum width of filled
1279 lines. Its value should be an integer, which is a number of columns.
1280 All the filling, justification and centering commands are affected by
1281 this variable, including Auto Fill mode (@pxref{Auto Filling}).
1283 As a practical matter, if you are writing text for other people to
1284 read, you should set @code{fill-column} to no more than 70. Otherwise
1285 the line will be too long for people to read comfortably, and this can
1286 make the text seem clumsy.
1289 @defvar default-fill-column
1290 The value of this variable is the default value for @code{fill-column} in
1291 buffers that do not override it. This is the same as
1292 @code{(default-value 'fill-column)}.
1294 The default value for @code{default-fill-column} is 70.
1297 @deffn Command set-left-margin from to margin
1298 This sets the @code{left-margin} property on the text from @var{from} to
1299 @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
1300 command also refills the region to fit the new margin.
1303 @deffn Command set-right-margin from to margin
1304 This sets the @code{right-margin} property on the text from @var{from}
1305 to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
1306 this command also refills the region to fit the new margin.
1309 @defun current-left-margin
1310 This function returns the proper left margin value to use for filling
1311 the text around point. The value is the sum of the @code{left-margin}
1312 property of the character at the start of the current line (or zero if
1313 none), and the value of the variable @code{left-margin}.
1316 @defun current-fill-column
1317 This function returns the proper fill column value to use for filling
1318 the text around point. The value is the value of the @code{fill-column}
1319 variable, minus the value of the @code{right-margin} property of the
1320 character after point.
1323 @deffn Command move-to-left-margin &optional n force
1324 This function moves point to the left margin of the current line. The
1325 column moved to is determined by calling the function
1326 @code{current-left-margin}. If the argument @var{n} is non-@code{nil},
1327 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
1329 If @var{force} is non-@code{nil}, that says to fix the line's
1330 indentation if that doesn't match the left margin value.
1333 @defun delete-to-left-margin &optional from to
1334 This function removes left margin indentation from the text
1335 between @var{from} and @var{to}. The amount of indentation
1336 to delete is determined by calling @code{current-left-margin}.
1337 In no case does this function delete non-whitespace.
1339 The arguments @var{from} and @var{to} are optional; the default is the
1343 @defun indent-to-left-margin
1344 This is the default @code{indent-line-function}, used in Fundamental
1345 mode, Text mode, etc. Its effect is to adjust the indentation at the
1346 beginning of the current line to the value specified by the variable
1347 @code{left-margin}. This may involve either inserting or deleting
1352 This variable specifies the base left margin column. In Fundamental
1353 mode, @key{LFD} indents to this column. This variable automatically
1354 becomes buffer-local when set in any fashion.
1358 @section Auto Filling
1359 @cindex filling, automatic
1360 @cindex Auto Fill mode
1362 Auto Fill mode is a minor mode that fills lines automatically as text
1363 is inserted. This section describes the hook used by Auto Fill mode.
1364 For a description of functions that you can call explicitly to fill and
1365 justify existing text, see @ref{Filling}.
1367 Auto Fill mode also enables the functions that change the margins and
1368 justification style to refill portions of the text. @xref{Margins}.
1370 @defvar auto-fill-function
1371 The value of this variable should be a function (of no arguments) to be
1372 called after self-inserting a space or a newline. It may be @code{nil},
1373 in which case nothing special is done in that case.
1375 The value of @code{auto-fill-function} is @code{do-auto-fill} when
1376 Auto-Fill mode is enabled. That is a function whose sole purpose is to
1377 implement the usual strategy for breaking a line.
1380 In older Emacs versions, this variable was named @code{auto-fill-hook},
1381 but since it is not called with the standard convention for hooks, it
1382 was renamed to @code{auto-fill-function} in version 19.
1387 @section Sorting Text
1388 @cindex sorting text
1390 The sorting functions described in this section all rearrange text in
1391 a buffer. This is in contrast to the function @code{sort}, which
1392 rearranges the order of the elements of a list (@pxref{Rearrangement}).
1393 The values returned by these functions are not meaningful.
1395 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
1396 This function is the general text-sorting routine that divides a buffer
1397 into records and sorts them. Most of the commands in this section use
1400 To understand how @code{sort-subr} works, consider the whole accessible
1401 portion of the buffer as being divided into disjoint pieces called
1402 @dfn{sort records}. The records may or may not be contiguous; they may
1403 not overlap. A portion of each sort record (perhaps all of it) is
1404 designated as the sort key. Sorting rearranges the records in order by
1407 Usually, the records are rearranged in order of ascending sort key.
1408 If the first argument to the @code{sort-subr} function, @var{reverse},
1409 is non-@code{nil}, the sort records are rearranged in order of
1410 descending sort key.
1412 The next four arguments to @code{sort-subr} are functions that are
1413 called to move point across a sort record. They are called many times
1414 from within @code{sort-subr}.
1418 @var{nextrecfun} is called with point at the end of a record. This
1419 function moves point to the start of the next record. The first record
1420 is assumed to start at the position of point when @code{sort-subr} is
1421 called. Therefore, you should usually move point to the beginning of
1422 the buffer before calling @code{sort-subr}.
1424 This function can indicate there are no more sort records by leaving
1425 point at the end of the buffer.
1428 @var{endrecfun} is called with point within a record. It moves point to
1429 the end of the record.
1432 @var{startkeyfun} is called to move point from the start of a record to
1433 the start of the sort key. This argument is optional; if it is omitted,
1434 the whole record is the sort key. If supplied, the function should
1435 either return a non-@code{nil} value to be used as the sort key, or
1436 return @code{nil} to indicate that the sort key is in the buffer
1437 starting at point. In the latter case, @var{endkeyfun} is called to
1438 find the end of the sort key.
1441 @var{endkeyfun} is called to move point from the start of the sort key
1442 to the end of the sort key. This argument is optional. If
1443 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
1444 @code{nil}), then the sort key extends to the end of the record. There
1445 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1446 non-@code{nil} value.
1449 As an example of @code{sort-subr}, here is the complete function
1450 definition for @code{sort-lines}:
1454 ;; @r{Note that the first two lines of doc string}
1455 ;; @r{are effectively one line when viewed by a user.}
1456 (defun sort-lines (reverse start end)
1457 "Sort lines in region alphabetically.
1458 Called from a program, there are three arguments:
1461 REVERSE (non-nil means reverse order),
1462 and START and END (the region to sort)."
1463 (interactive "P\nr")
1465 (narrow-to-region start end)
1466 (goto-char (point-min))
1473 Here @code{forward-line} moves point to the start of the next record,
1474 and @code{end-of-line} moves point to the end of record. We do not pass
1475 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
1476 record is used as the sort key.
1478 The @code{sort-paragraphs} function is very much the same, except that
1479 its @code{sort-subr} call looks like this:
1486 (skip-chars-forward "\n \t\f")))
1492 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
1493 This command sorts the region between @var{start} and @var{end}
1494 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
1495 If @var{reverse} is a negative integer, then sorting is in reverse
1498 Alphabetical sorting means that two sort keys are compared by
1499 comparing the first characters of each, the second characters of each,
1500 and so on. If a mismatch is found, it means that the sort keys are
1501 unequal; the sort key whose character is less at the point of first
1502 mismatch is the lesser sort key. The individual characters are compared
1503 according to their numerical values. Since Emacs uses the @sc{ascii}
1504 character set, the ordering in that set determines alphabetical order.
1505 @c version 19 change
1507 The value of the @var{record-regexp} argument specifies how to divide
1508 the buffer into sort records. At the end of each record, a search is
1509 done for this regular expression, and the text that matches it is the
1510 next record. For example, the regular expression @samp{^.+$}, which
1511 matches lines with at least one character besides a newline, would make
1512 each such line into a sort record. @xref{Regular Expressions}, for a
1513 description of the syntax and meaning of regular expressions.
1515 The value of the @var{key-regexp} argument specifies what part of each
1516 record is the sort key. The @var{key-regexp} could match the whole
1517 record, or only a part. In the latter case, the rest of the record has
1518 no effect on the sorted order of records, but it is carried along when
1519 the record moves to its new position.
1521 The @var{key-regexp} argument can refer to the text matched by a
1522 subexpression of @var{record-regexp}, or it can be a regular expression
1525 If @var{key-regexp} is:
1528 @item @samp{\@var{digit}}
1529 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
1530 grouping in @var{record-regexp} is the sort key.
1533 then the whole record is the sort key.
1535 @item a regular expression
1536 then @code{sort-regexp-fields} searches for a match for the regular
1537 expression within the record. If such a match is found, it is the sort
1538 key. If there is no match for @var{key-regexp} within a record then
1539 that record is ignored, which means its position in the buffer is not
1540 changed. (The other records may move around it.)
1543 For example, if you plan to sort all the lines in the region by the
1544 first word on each line starting with the letter @samp{f}, you should
1545 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
1546 @samp{\<f\w*\>}. The resulting expression looks like this:
1550 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
1556 If you call @code{sort-regexp-fields} interactively, it prompts for
1557 @var{record-regexp} and @var{key-regexp} in the minibuffer.
1560 @deffn Command sort-lines reverse start end
1561 This command alphabetically sorts lines 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-paragraphs reverse start end
1567 This command alphabetically sorts paragraphs in the region between
1568 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1569 is in reverse order.
1572 @deffn Command sort-pages reverse start end
1573 This command alphabetically sorts pages in the region between
1574 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1575 is in reverse order.
1578 @deffn Command sort-fields field start end
1579 This command sorts lines in the region between @var{start} and
1580 @var{end}, comparing them alphabetically by the @var{field}th field
1581 of each line. Fields are separated by whitespace and numbered starting
1582 from 1. If @var{field} is negative, sorting is by the
1583 @w{@minus{}@var{field}th} field from the end of the line. This command
1584 is useful for sorting tables.
1587 @deffn Command sort-numeric-fields field start end
1588 This command sorts lines in the region between @var{start} and
1589 @var{end}, comparing them numerically by the @var{field}th field of each
1590 line. The specified field must contain a number in each line of the
1591 region. Fields are separated by whitespace and numbered starting from
1592 1. If @var{field} is negative, sorting is by the
1593 @w{@minus{}@var{field}th} field from the end of the line. This command
1594 is useful for sorting tables.
1597 @deffn Command sort-columns reverse &optional start end
1598 This command sorts the lines in the region between @var{start} and
1599 @var{end}, comparing them alphabetically by a certain range of columns.
1600 The column positions of @var{start} and @var{end} bound the range of
1603 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
1605 One unusual thing about this command is that the entire line
1606 containing position @var{start}, and the entire line containing position
1607 @var{end}, are included in the region sorted.
1609 Note that @code{sort-columns} uses the @code{sort} utility program,
1610 and so cannot work properly on text containing tab characters. Use
1611 @kbd{M-x @code{untabify}} to convert tabs to spaces before sorting.
1615 @comment node-name, next, previous, up
1616 @section Counting Columns
1618 @cindex counting columns
1619 @cindex horizontal position
1621 The column functions convert between a character position (counting
1622 characters from the beginning of the buffer) and a column position
1623 (counting screen characters from the beginning of a line).
1625 A character counts according to the number of columns it occupies on
1626 the screen. This means control characters count as occupying 2 or 4
1627 columns, depending upon the value of @code{ctl-arrow}, and tabs count as
1628 occupying a number of columns that depends on the value of
1629 @code{tab-width} and on the column where the tab begins. @xref{Usual Display}.
1631 Column number computations ignore the width of the window and the
1632 amount of horizontal scrolling. Consequently, a column value can be
1633 arbitrarily high. The first (or leftmost) column is numbered 0.
1635 @defun current-column &optional buffer
1636 This function returns the horizontal position of point, measured in
1637 columns, counting from 0 at the left margin.
1639 This is calculated by adding together the widths of all the displayed
1640 representations of the character between the start of the previous line
1641 and point. (e.g. control characters will have a width of 2 or 4, tabs
1642 will have a variable width.)
1644 Ignores the finite width of frame displaying the buffer, which means
1645 that this function may return values greater than
1646 @code{(frame-width)}.
1648 Whether the line is visible (if @code{selective-display} is t) has no effect;
1649 however, ^M is treated as end of line when @code{selective-display} is t.
1651 If @var{buffer} is nil, the current buffer is assumed.
1653 For an example of using @code{current-column}, see the description of
1654 @code{count-lines} in @ref{Text Lines}.
1657 @defun move-to-column column &optional force buffer
1658 This function moves point to @var{column} in the current line. The
1659 calculation of @var{column} takes into account the widths of the
1660 displayed representations of the characters between the start of the
1663 If column @var{column} is beyond the end of the line, point moves to the
1664 end of the line. If @var{column} is negative, point moves to the
1665 beginning of the line.
1667 If it is impossible to move to column @var{column} because that is in
1668 the middle of a multicolumn character such as a tab, point moves to the
1669 end of that character. However, if @var{force} is non-@code{nil}, and
1670 @var{column} is in the middle of a tab, then @code{move-to-column}
1671 converts the tab into spaces so that it can move precisely to column
1672 @var{column}. Other multicolumn characters can cause anomalies despite
1673 @var{force}, since there is no way to split them.
1675 The argument @var{force} also has an effect if the line isn't long
1676 enough to reach column @var{column}; in that case, unless the value of
1677 @var{force} is the special value @code{coerce}, it says to add
1678 whitespace at the end of the line to reach that column.
1680 If @var{column} is not a non-negative integer, an error is signaled.
1682 The return value is the column number actually moved to.
1686 @section Indentation
1689 The indentation functions are used to examine, move to, and change
1690 whitespace that is at the beginning of a line. Some of the functions
1691 can also change whitespace elsewhere on a line. Columns and indentation
1692 count from zero at the left margin.
1695 * Primitive Indent:: Functions used to count and insert indentation.
1696 * Mode-Specific Indent:: Customize indentation for different modes.
1697 * Region Indent:: Indent all the lines in a region.
1698 * Relative Indent:: Indent the current line based on previous lines.
1699 * Indent Tabs:: Adjustable, typewriter-like tab stops.
1700 * Motion by Indent:: Move to first non-blank character.
1703 @node Primitive Indent
1704 @subsection Indentation Primitives
1706 This section describes the primitive functions used to count and
1707 insert indentation. The functions in the following sections use these
1710 @defun current-indentation &optional buffer
1711 @comment !!Type Primitive Function
1712 @comment !!SourceFile indent.c
1713 This function returns the indentation of the current line, which is
1714 the horizontal position of the first nonblank character. If the
1715 contents are entirely blank, then this is the horizontal position of the
1719 @deffn Command indent-to column &optional minimum buffer
1720 @comment !!Type Primitive Function
1721 @comment !!SourceFile indent.c
1722 This function indents from point with tabs and spaces until @var{column}
1723 is reached. If @var{minimum} is specified and non-@code{nil}, then at
1724 least that many spaces are inserted even if this requires going beyond
1725 @var{column}. Otherwise the function does nothing if point is already
1726 beyond @var{column}. The value is the column at which the inserted
1727 indentation ends. If @var{buffer} is @code{nil}, the current buffer is assumed.
1730 @defopt indent-tabs-mode
1731 @comment !!SourceFile indent.c
1732 If this variable is non-@code{nil}, indentation functions can insert
1733 tabs as well as spaces. Otherwise, they insert only spaces. Setting
1734 this variable automatically makes it local to the current buffer.
1737 @node Mode-Specific Indent
1738 @subsection Indentation Controlled by Major Mode
1740 An important function of each major mode is to customize the @key{TAB}
1741 key to indent properly for the language being edited. This section
1742 describes the mechanism of the @key{TAB} key and how to control it.
1743 The functions in this section return unpredictable values.
1745 @defvar indent-line-function
1746 This variable's value is the function to be used by @key{TAB} (and
1747 various commands) to indent the current line. The command
1748 @code{indent-according-to-mode} does no more than call this function.
1750 In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C
1751 mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
1752 In Fundamental mode, Text mode, and many other modes with no standard
1753 for indentation, the value is @code{indent-to-left-margin} (which is the
1757 @deffn Command indent-according-to-mode
1758 This command calls the function in @code{indent-line-function} to
1759 indent the current line in a way appropriate for the current major mode.
1762 @deffn Command indent-for-tab-command &optional prefix-arg
1763 This command calls the function in @code{indent-line-function} to indent
1764 the current line; except that if that function is
1765 @code{indent-to-left-margin}, it calls @code{insert-tab} instead. (That
1766 is a trivial command that inserts a tab character.)
1769 @deffn Command newline-and-indent
1770 @comment !!SourceFile simple.el
1771 This function inserts a newline, then indents the new line (the one
1772 following the newline just inserted) according to the major mode.
1774 It does indentation by calling the current @code{indent-line-function}.
1775 In programming language modes, this is the same thing @key{TAB} does,
1776 but in some text modes, where @key{TAB} inserts a tab,
1777 @code{newline-and-indent} indents to the column specified by
1781 @deffn Command reindent-then-newline-and-indent
1782 @comment !!SourceFile simple.el
1783 This command reindents the current line, inserts a newline at point,
1784 and then reindents the new line (the one following the newline just
1787 This command does indentation on both lines according to the current
1788 major mode, by calling the current value of @code{indent-line-function}.
1789 In programming language modes, this is the same thing @key{TAB} does,
1790 but in some text modes, where @key{TAB} inserts a tab,
1791 @code{reindent-then-newline-and-indent} indents to the column specified
1792 by @code{left-margin}.
1796 @subsection Indenting an Entire Region
1798 This section describes commands that indent all the lines in the
1799 region. They return unpredictable values.
1801 @deffn Command indent-region start end to-column
1802 This command indents each nonblank line starting between @var{start}
1803 (inclusive) and @var{end} (exclusive). If @var{to-column} is
1804 @code{nil}, @code{indent-region} indents each nonblank line by calling
1805 the current mode's indentation function, the value of
1806 @code{indent-line-function}.
1808 If @var{to-column} is non-@code{nil}, it should be an integer
1809 specifying the number of columns of indentation; then this function
1810 gives each line exactly that much indentation, by either adding or
1811 deleting whitespace.
1813 If there is a fill prefix, @code{indent-region} indents each line
1814 by making it start with the fill prefix.
1817 @defvar indent-region-function
1818 The value of this variable is a function that can be used by
1819 @code{indent-region} as a short cut. You should design the function so
1820 that it will produce the same results as indenting the lines of the
1821 region one by one, but presumably faster.
1823 If the value is @code{nil}, there is no short cut, and
1824 @code{indent-region} actually works line by line.
1826 A short-cut function is useful in modes such as C mode and Lisp mode,
1827 where the @code{indent-line-function} must scan from the beginning of
1828 the function definition: applying it to each line would be quadratic in
1829 time. The short cut can update the scan information as it moves through
1830 the lines indenting them; this takes linear time. In a mode where
1831 indenting a line individually is fast, there is no need for a short cut.
1833 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
1834 a different meaning and does not use this variable.
1837 @deffn Command indent-rigidly start end count
1838 @comment !!SourceFile indent.el
1839 This command indents all lines starting between @var{start}
1840 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
1841 This ``preserves the shape'' of the affected region, moving it as a
1842 rigid unit. Consequently, this command is useful not only for indenting
1843 regions of unindented text, but also for indenting regions of formatted
1846 For example, if @var{count} is 3, this command adds 3 columns of
1847 indentation to each of the lines beginning in the region specified.
1849 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
1850 @code{indent-rigidly} to indent the text copied from the message being
1854 @deffn Command indent-code-rigidly start end columns &optional nochange-regexp
1855 This is like @code{indent-rigidly}, except that it doesn't alter lines
1856 that start within strings or comments.
1858 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
1859 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
1862 @node Relative Indent
1863 @subsection Indentation Relative to Previous Lines
1865 This section describes two commands that indent the current line
1866 based on the contents of previous lines.
1868 @deffn Command indent-relative &optional unindented-ok
1869 This command inserts whitespace at point, extending to the same
1870 column as the next @dfn{indent point} of the previous nonblank line. An
1871 indent point is a non-whitespace character following whitespace. The
1872 next indent point is the first one at a column greater than the current
1873 column of point. For example, if point is underneath and to the left of
1874 the first non-blank character of a line of text, it moves to that column
1875 by inserting whitespace.
1877 If the previous nonblank line has no next indent point (i.e., none at a
1878 great enough column position), @code{indent-relative} either does
1879 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
1880 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right
1881 of the last column of a short line of text, this command ordinarily
1882 moves point to the next tab stop by inserting whitespace.
1884 The return value of @code{indent-relative} is unpredictable.
1886 In the following example, point is at the beginning of the second
1891 This line is indented twelve spaces.
1892 @point{}The quick brown fox jumped.
1897 Evaluation of the expression @code{(indent-relative nil)} produces the
1902 This line is indented twelve spaces.
1903 @point{}The quick brown fox jumped.
1907 In this example, point is between the @samp{m} and @samp{p} of
1912 This line is indented twelve spaces.
1913 The quick brown fox jum@point{}ped.
1918 Evaluation of the expression @code{(indent-relative nil)} produces the
1923 This line is indented twelve spaces.
1924 The quick brown fox jum @point{}ped.
1929 @deffn Command indent-relative-maybe
1930 @comment !!SourceFile indent.el
1931 This command indents the current line like the previous nonblank line.
1932 It calls @code{indent-relative} with @code{t} as the @var{unindented-ok}
1933 argument. The return value is unpredictable.
1935 If the previous nonblank line has no indent points beyond the current
1936 column, this command does nothing.
1940 @subsection Adjustable ``Tab Stops''
1941 @cindex tabs stops for indentation
1943 This section explains the mechanism for user-specified ``tab stops''
1944 and the mechanisms that use and set them. The name ``tab stops'' is
1945 used because the feature is similar to that of the tab stops on a
1946 typewriter. The feature works by inserting an appropriate number of
1947 spaces and tab characters to reach the next tab stop column; it does not
1948 affect the display of tab characters in the buffer (@pxref{Usual
1949 Display}). Note that the @key{TAB} character as input uses this tab
1950 stop feature only in a few major modes, such as Text mode.
1952 @deffn Command tab-to-tab-stop
1953 This command inserts spaces or tabs up to the next tab stop column
1954 defined by @code{tab-stop-list}. It searches the list for an element
1955 greater than the current column number, and uses that element as the
1956 column to indent to. It does nothing if no such element is found.
1959 @defopt tab-stop-list
1960 This variable is the list of tab stop columns used by
1961 @code{tab-to-tab-stops}. The elements should be integers in increasing
1962 order. The tab stop columns need not be evenly spaced.
1964 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
1968 @node Motion by Indent
1969 @subsection Indentation-Based Motion Commands
1971 These commands, primarily for interactive use, act based on the
1972 indentation in the text.
1974 @deffn Command back-to-indentation
1975 @comment !!SourceFile simple.el
1976 This command moves point to the first non-whitespace character in the
1977 current line (which is the line in which point is located). It returns
1981 @deffn Command backward-to-indentation arg
1982 @comment !!SourceFile simple.el
1983 This command moves point backward @var{arg} lines and then to the
1984 first nonblank character on that line. It returns @code{nil}.
1987 @deffn Command forward-to-indentation arg
1988 @comment !!SourceFile simple.el
1989 This command moves point forward @var{arg} lines and then to the first
1990 nonblank character on that line. It returns @code{nil}.
1994 @section Case Changes
1995 @cindex case changes
1997 The case change commands described here work on text in the current
1998 buffer. @xref{Character Case}, for case conversion commands that work
1999 on strings and characters. @xref{Case Tables}, for how to customize
2000 which characters are upper or lower case and how to convert them.
2002 @deffn Command capitalize-region start end &optional buffer
2003 This function capitalizes all words in the region defined by
2004 @var{start} and @var{end}. To capitalize means to convert each word's
2005 first character to upper case and convert the rest of each word to lower
2006 case. The function returns @code{nil}.
2008 If one end of the region is in the middle of a word, the part of the
2009 word within the region is treated as an entire word.
2011 When @code{capitalize-region} is called interactively, @var{start} and
2012 @var{end} are point and the mark, with the smallest first.
2016 ---------- Buffer: foo ----------
2017 This is the contents of the 5th foo.
2018 ---------- Buffer: foo ----------
2022 (capitalize-region 1 44)
2025 ---------- Buffer: foo ----------
2026 This Is The Contents Of The 5th Foo.
2027 ---------- Buffer: foo ----------
2032 @deffn Command downcase-region start end &optional buffer
2033 This function converts all of the letters in the region defined by
2034 @var{start} and @var{end} to lower case. The function returns
2037 When @code{downcase-region} is called interactively, @var{start} and
2038 @var{end} are point and the mark, with the smallest first.
2041 @deffn Command upcase-region start end &optional buffer
2042 This function converts all of the letters in the region defined by
2043 @var{start} and @var{end} to upper case. The function returns
2046 When @code{upcase-region} is called interactively, @var{start} and
2047 @var{end} are point and the mark, with the smallest first.
2050 @deffn Command capitalize-word count &optional buffer
2051 This function capitalizes @var{count} words after point, moving point
2052 over as it does. To capitalize means to convert each word's first
2053 character to upper case and convert the rest of each word to lower case.
2054 If @var{count} is negative, the function capitalizes the
2055 @minus{}@var{count} previous words but does not move point. The value
2058 If point is in the middle of a word, the part of the word before point
2059 is ignored when moving forward. The rest is treated as an entire word.
2061 When @code{capitalize-word} is called interactively, @var{count} is
2062 set to the numeric prefix argument.
2065 @deffn Command downcase-word count &optional buffer
2066 This function converts the @var{count} words after point to all lower
2067 case, moving point over as it does. If @var{count} is negative, it
2068 converts the @minus{}@var{count} previous words but does not move point.
2069 The value is @code{nil}.
2071 When @code{downcase-word} is called interactively, @var{count} is set
2072 to the numeric prefix argument.
2075 @deffn Command upcase-word count &optional buffer
2076 This function converts the @var{count} words after point to all upper
2077 case, moving point over as it does. If @var{count} is negative, it
2078 converts the @minus{}@var{count} previous words but does not move point.
2079 The value is @code{nil}.
2081 When @code{upcase-word} is called interactively, @var{count} is set to
2082 the numeric prefix argument.
2085 @node Text Properties
2086 @section Text Properties
2087 @cindex text properties
2088 @cindex attributes of text
2089 @cindex properties of text
2091 Text properties are an alternative interface to extents
2092 (@pxref{Extents}), and are built on top of them. They are useful when
2093 you want to view textual properties as being attached to the characters
2094 themselves rather than to intervals of characters. The text property
2095 interface is compatible with FSF Emacs.
2097 Each character position in a buffer or a string can have a @dfn{text
2098 property list}, much like the property list of a symbol (@pxref{Property
2099 Lists}). The properties belong to a particular character at a
2100 particular place, such as, the letter @samp{T} at the beginning of this
2101 sentence or the first @samp{o} in @samp{foo}---if the same character
2102 occurs in two different places, the two occurrences generally have
2103 different properties.
2105 Each property has a name and a value. Both of these can be any Lisp
2106 object, but the name is normally a symbol. The usual way to access the
2107 property list is to specify a name and ask what value corresponds to it.
2110 If a character has a @code{category} property, we call it the
2111 @dfn{category} of the character. It should be a symbol. The properties
2112 of the symbol serve as defaults for the properties of the character.
2114 Note that FSF Emacs also looks at the @code{category} property to find
2115 defaults for text properties. We consider this too bogus to implement.
2117 Copying text between strings and buffers preserves the properties
2118 along with the characters; this includes such diverse functions as
2119 @code{substring}, @code{insert}, and @code{buffer-substring}.
2122 * Examining Properties:: Looking at the properties of one character.
2123 * Changing Properties:: Setting the properties of a range of text.
2124 * Property Search:: Searching for where a property changes value.
2125 * Special Properties:: Particular properties with special meanings.
2126 * Saving Properties:: Saving text properties in files, and reading
2130 @node Examining Properties
2131 @subsection Examining Text Properties
2133 The simplest way to examine text properties is to ask for the value of
2134 a particular property of a particular character. For that, use
2135 @code{get-text-property}. Use @code{text-properties-at} to get the
2136 entire property list of a character. @xref{Property Search}, for
2137 functions to examine the properties of a number of characters at once.
2139 These functions handle both strings and buffers. (Keep in mind that
2140 positions in a string start from 0, whereas positions in a buffer start
2143 @defun get-text-property pos prop &optional object at-flag
2144 This function returns the value of the @var{prop} property of the
2145 character after position @var{pos} in @var{object} (a buffer or string).
2146 The argument @var{object} is optional and defaults to the current
2148 @ignore @c Bogus as hell!
2149 If there is no @var{prop} property strictly speaking, but the character
2150 has a category that is a symbol, then @code{get-text-property} returns
2151 the @var{prop} property of that symbol.
2155 @defun get-char-property pos prop &optional object at-flag
2156 This function is like @code{get-text-property}, except that it checks
2157 all extents, not just text-property extents.
2159 @ignore Does not apply in XEmacs
2160 The argument @var{object} may be a string, a buffer, or a window. If it
2161 is a window, then the buffer displayed in that window is used for text
2162 properties and overlays, but only the overlays active for that window
2163 are considered. If @var{object} is a buffer, then all overlays in that
2164 buffer are considered, as well as text properties. If @var{object} is a
2165 string, only text properties are considered, since strings never have
2170 @defun text-properties-at position &optional object
2171 This function returns the entire property list of the character at
2172 @var{position} in the string or buffer @var{object}. If @var{object} is
2173 @code{nil}, it defaults to the current buffer.
2176 @defvar default-text-properties
2177 This variable holds a property list giving default values for text
2178 properties. Whenever a character does not specify a value for a
2179 property, the value stored in this list is used instead. Here is
2183 (setq default-text-properties '(foo 69))
2184 ;; @r{Make sure character 1 has no properties of its own.}
2185 (set-text-properties 1 2 nil)
2186 ;; @r{What we get, when we ask, is the default value.}
2187 (get-text-property 1 'foo)
2192 @node Changing Properties
2193 @subsection Changing Text Properties
2195 The primitives for changing properties apply to a specified range of
2196 text. The function @code{set-text-properties} (see end of section) sets
2197 the entire property list of the text in that range; more often, it is
2198 useful to add, change, or delete just certain properties specified by
2201 Since text properties are considered part of the buffer's contents, and
2202 can affect how the buffer looks on the screen, any change in the text
2203 properties is considered a buffer modification. Buffer text property
2204 changes are undoable (@pxref{Undo}).
2206 @defun put-text-property start end prop value &optional object
2207 This function sets the @var{prop} property to @var{value} for the text
2208 between @var{start} and @var{end} in the string or buffer @var{object}.
2209 If @var{object} is @code{nil}, it defaults to the current buffer.
2212 @defun add-text-properties start end props &optional object
2213 This function modifies the text properties for the text between
2214 @var{start} and @var{end} in the string or buffer @var{object}. If
2215 @var{object} is @code{nil}, it defaults to the current buffer.
2217 The argument @var{props} specifies which properties to change. It
2218 should have the form of a property list (@pxref{Property Lists}): a list
2219 whose elements include the property names followed alternately by the
2220 corresponding values.
2222 The return value is @code{t} if the function actually changed some
2223 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2224 its values agree with those in the text).
2226 For example, here is how to set the @code{comment} and @code{face}
2227 properties of a range of text:
2230 (add-text-properties @var{start} @var{end}
2231 '(comment t face highlight))
2235 @defun remove-text-properties start end props &optional object
2236 This function deletes specified text properties from the text between
2237 @var{start} and @var{end} in the string or buffer @var{object}. If
2238 @var{object} is @code{nil}, it defaults to the current buffer.
2240 The argument @var{props} specifies which properties to delete. It
2241 should have the form of a property list (@pxref{Property Lists}): a list
2242 whose elements are property names alternating with corresponding values.
2243 But only the names matter---the values that accompany them are ignored.
2244 For example, here's how to remove the @code{face} property.
2247 (remove-text-properties @var{start} @var{end} '(face nil))
2250 The return value is @code{t} if the function actually changed some
2251 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2252 if no character in the specified text had any of those properties).
2255 @defun set-text-properties start end props &optional object
2256 This function completely replaces the text property list for the text
2257 between @var{start} and @var{end} in the string or buffer @var{object}.
2258 If @var{object} is @code{nil}, it defaults to the current buffer.
2260 The argument @var{props} is the new property list. It should be a list
2261 whose elements are property names alternating with corresponding values.
2263 After @code{set-text-properties} returns, all the characters in the
2264 specified range have identical properties.
2266 If @var{props} is @code{nil}, the effect is to get rid of all properties
2267 from the specified range of text. Here's an example:
2270 (set-text-properties @var{start} @var{end} nil)
2274 See also the function @code{buffer-substring-without-properties}
2275 (@pxref{Buffer Contents}) which copies text from the buffer
2276 but does not copy its properties.
2278 @node Property Search
2279 @subsection Property Search Functions
2281 In typical use of text properties, most of the time several or many
2282 consecutive characters have the same value for a property. Rather than
2283 writing your programs to examine characters one by one, it is much
2284 faster to process chunks of text that have the same property value.
2286 Here are functions you can use to do this. They use @code{eq} for
2287 comparing property values. In all cases, @var{object} defaults to the
2290 For high performance, it's very important to use the @var{limit}
2291 argument to these functions, especially the ones that search for a
2292 single property---otherwise, they may spend a long time scanning to the
2293 end of the buffer, if the property you are interested in does not change.
2295 Remember that a position is always between two characters; the position
2296 returned by these functions is between two characters with different
2299 @defun next-property-change pos &optional object limit
2300 The function scans the text forward from position @var{pos} in the
2301 string or buffer @var{object} till it finds a change in some text
2302 property, then returns the position of the change. In other words, it
2303 returns the position of the first character beyond @var{pos} whose
2304 properties are not identical to those of the character just after
2307 If @var{limit} is non-@code{nil}, then the scan ends at position
2308 @var{limit}. If there is no property change before that point,
2309 @code{next-property-change} returns @var{limit}.
2311 The value is @code{nil} if the properties remain unchanged all the way
2312 to the end of @var{object} and @var{limit} is @code{nil}. If the value
2313 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
2314 The value equals @var{pos} only when @var{limit} equals @var{pos}.
2316 Here is an example of how to scan the buffer by chunks of text within
2317 which all properties are constant:
2321 (let ((plist (text-properties-at (point)))
2323 (or (next-property-change (point) (current-buffer))
2325 @r{Process text from point to @var{next-change}@dots{}}
2326 (goto-char next-change)))
2330 @defun next-single-property-change pos prop &optional object limit
2331 The function scans the text forward from position @var{pos} in the
2332 string or buffer @var{object} till it finds a change in the @var{prop}
2333 property, then returns the position of the change. In other words, it
2334 returns the position of the first character beyond @var{pos} whose
2335 @var{prop} property differs from that of the character just after
2338 If @var{limit} is non-@code{nil}, then the scan ends at position
2339 @var{limit}. If there is no property change before that point,
2340 @code{next-single-property-change} returns @var{limit}.
2342 The value is @code{nil} if the property remains unchanged all the way to
2343 the end of @var{object} and @var{limit} is @code{nil}. If the value is
2344 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
2345 equals @var{pos} only if @var{limit} equals @var{pos}.
2348 @defun previous-property-change pos &optional object limit
2349 This is like @code{next-property-change}, but scans backward from @var{pos}
2350 instead of forward. If the value is non-@code{nil}, it is a position
2351 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
2355 @defun previous-single-property-change pos prop &optional object limit
2356 This is like @code{next-single-property-change}, but scans backward from
2357 @var{pos} instead of forward. If the value is non-@code{nil}, it is a
2358 position less than or equal to @var{pos}; it equals @var{pos} only if
2359 @var{limit} equals @var{pos}.
2362 @defun text-property-any start end prop value &optional object
2363 This function returns non-@code{nil} if at least one character between
2364 @var{start} and @var{end} has a property @var{prop} whose value is
2365 @var{value}. More precisely, it returns the position of the first such
2366 character. Otherwise, it returns @code{nil}.
2368 The optional fifth argument, @var{object}, specifies the string or
2369 buffer to scan. Positions are relative to @var{object}. The default
2370 for @var{object} is the current buffer.
2373 @defun text-property-not-all start end prop value &optional object
2374 This function returns non-@code{nil} if at least one character between
2375 @var{start} and @var{end} has a property @var{prop} whose value differs
2376 from @var{value}. More precisely, it returns the position of the
2377 first such character. Otherwise, it returns @code{nil}.
2379 The optional fifth argument, @var{object}, specifies the string or
2380 buffer to scan. Positions are relative to @var{object}. The default
2381 for @var{object} is the current buffer.
2384 @node Special Properties
2385 @subsection Properties with Special Meanings
2387 The predefined properties are the same as those for extents.
2388 @xref{Extent Properties}.
2390 @ignore Changed in XEmacs
2391 (deleted section describing FSF Emacs special text properties)
2394 @node Saving Properties
2395 @subsection Saving Text Properties in Files
2396 @cindex text properties in files
2397 @cindex saving text properties
2399 You can save text properties in files, and restore text properties
2400 when inserting the files, using these two hooks:
2402 @defvar write-region-annotate-functions
2403 This variable's value is a list of functions for @code{write-region} to
2404 run to encode text properties in some fashion as annotations to the text
2405 being written in the file. @xref{Writing to Files}.
2407 Each function in the list is called with two arguments: the start and
2408 end of the region to be written. These functions should not alter the
2409 contents of the buffer. Instead, they should return lists indicating
2410 annotations to write in the file in addition to the text in the
2413 Each function should return a list of elements of the form
2414 @code{(@var{position} . @var{string})}, where @var{position} is an
2415 integer specifying the relative position in the text to be written, and
2416 @var{string} is the annotation to add there.
2418 Each list returned by one of these functions must be already sorted in
2419 increasing order by @var{position}. If there is more than one function,
2420 @code{write-region} merges the lists destructively into one sorted list.
2422 When @code{write-region} actually writes the text from the buffer to the
2423 file, it intermixes the specified annotations at the corresponding
2424 positions. All this takes place without modifying the buffer.
2427 @defvar after-insert-file-functions
2428 This variable holds a list of functions for @code{insert-file-contents}
2429 to call after inserting a file's contents. These functions should scan
2430 the inserted text for annotations, and convert them to the text
2431 properties they stand for.
2433 Each function receives one argument, the length of the inserted text;
2434 point indicates the start of that text. The function should scan that
2435 text for annotations, delete them, and create the text properties that
2436 the annotations specify. The function should return the updated length
2437 of the inserted text, as it stands after those changes. The value
2438 returned by one function becomes the argument to the next function.
2440 These functions should always return with point at the beginning of
2443 The intended use of @code{after-insert-file-functions} is for converting
2444 some sort of textual annotations into actual text properties. But other
2445 uses may be possible.
2448 We invite users to write Lisp programs to store and retrieve text
2449 properties in files, using these hooks, and thus to experiment with
2450 various data formats and find good ones. Eventually we hope users
2451 will produce good, general extensions we can install in Emacs.
2453 We suggest not trying to handle arbitrary Lisp objects as property
2454 names or property values---because a program that general is probably
2455 difficult to write, and slow. Instead, choose a set of possible data
2456 types that are reasonably flexible, and not too hard to encode.
2458 @xref{Format Conversion}, for a related feature.
2461 @section Substituting for a Character Code
2463 The following functions replace characters within a specified region
2464 based on their character codes.
2466 @defun subst-char-in-region start end old-char new-char &optional noundo
2467 @cindex replace characters
2468 This function replaces all occurrences of the character @var{old-char}
2469 with the character @var{new-char} in the region of the current buffer
2470 defined by @var{start} and @var{end}.
2472 @cindex Outline mode
2473 @cindex undo avoidance
2474 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
2475 not record the change for undo and does not mark the buffer as modified.
2476 This feature is used for controlling selective display (@pxref{Selective
2479 @code{subst-char-in-region} does not move point and returns
2484 ---------- Buffer: foo ----------
2485 This is the contents of the buffer before.
2486 ---------- Buffer: foo ----------
2490 (subst-char-in-region 1 20 ?i ?X)
2493 ---------- Buffer: foo ----------
2494 ThXs Xs the contents of the buffer before.
2495 ---------- Buffer: foo ----------
2500 @defun translate-region start end table
2501 This function applies a translation table to the characters in the
2502 buffer between positions @var{start} and @var{end}. The translation
2503 table @var{table} can be either a string, a vector, or a char-table.
2505 If @var{table} is a string, its @var{n}th element is the mapping for the
2506 character with code @var{n}.
2508 If @var{table} is a vector, its @var{n}th element is the mapping for
2509 character with code @var{n}. Legal mappings are characters, strings, or
2510 @code{nil} (meaning don't replace.)
2512 If @var{table} is a char-table, its elements describe the mapping
2513 between characters and their replacements. The char-table should be of
2514 type @code{char} or @code{generic}.
2516 When the @var{table} is a string or vector and its length is less than
2517 the total number of characters (256 without Mule), any characters with
2518 codes larger than the length of @var{table} are not altered by the
2521 The return value of @code{translate-region} is the number of
2522 characters that were actually changed by the translation. This does
2523 not count characters that were mapped into themselves in the
2526 @strong{NOTE}: Prior to XEmacs 21.2, the @var{table} argument was
2527 allowed only to be a string. This is still the case in FSF Emacs.
2529 The following example creates a char-table that is passed to
2530 @code{translate-region}, which translates character @samp{a} to
2531 @samp{the letter a}, removes character @samp{b}, and translates
2532 character @samp{c} to newline.
2536 ---------- Buffer: foo ----------
2537 Here is a sentence in the buffer.
2538 ---------- Buffer: foo ----------
2542 (let ((table (make-char-table 'generic)))
2543 (put-char-table ?a "the letter a" table)
2544 (put-char-table ?b "" table)
2545 (put-char-table ?c ?\n table)
2546 (translate-region (point-min) (point-max) table))
2549 ---------- Buffer: foo ----------
2550 Here is the letter a senten
2552 ---------- Buffer: foo ----------
2561 A register is a sort of variable used in XEmacs editing that can hold a
2562 marker, a string, a rectangle, a window configuration (of one frame), or
2563 a frame configuration (of all frames). Each register is named by a
2564 single character. All characters, including control and meta characters
2565 (but with the exception of @kbd{C-g}), can be used to name registers.
2566 Thus, there are 255 possible registers. A register is designated in
2567 Emacs Lisp by a character that is its name.
2569 The functions in this section return unpredictable values unless
2571 @c Will change in version 19
2573 @defvar register-alist
2574 This variable is an alist of elements of the form @code{(@var{name} .
2575 @var{contents})}. Normally, there is one element for each XEmacs
2576 register that has been used.
2578 The object @var{name} is a character (an integer) identifying the
2579 register. The object @var{contents} is a string, marker, or list
2580 representing the register contents. A string represents text stored in
2581 the register. A marker represents a position. A list represents a
2582 rectangle; its elements are strings, one per line of the rectangle.
2585 @defun get-register register
2586 This function returns the contents of the register
2587 @var{register}, or @code{nil} if it has no contents.
2590 @defun set-register register value
2591 This function sets the contents of register @var{register} to @var{value}.
2592 A register can be set to any value, but the other register functions
2593 expect only certain data types. The return value is @var{value}.
2596 @deffn Command view-register register
2597 This command displays what is contained in register @var{register}.
2601 @deffn Command point-to-register register
2602 This command stores both the current location of point and the current
2603 buffer in register @var{register} as a marker.
2606 @deffn Command jump-to-register register
2607 @deffnx Command register-to-point register
2608 @comment !!SourceFile register.el
2609 This command restores the status recorded in register @var{register}.
2611 If @var{register} contains a marker, it moves point to the position
2612 stored in the marker. Since both the buffer and the location within the
2613 buffer are stored by the @code{point-to-register} function, this command
2614 can switch you to another buffer.
2616 If @var{register} contains a window configuration or a frame configuration.
2617 @code{jump-to-register} restores that configuration.
2621 @deffn Command insert-register register &optional beforep
2622 This command inserts contents of register @var{register} into the current
2625 Normally, this command puts point before the inserted text, and the
2626 mark after it. However, if the optional second argument @var{beforep}
2627 is non-@code{nil}, it puts the mark before and point after.
2628 You can pass a non-@code{nil} second argument @var{beforep} to this
2629 function interactively by supplying any prefix argument.
2631 If the register contains a rectangle, then the rectangle is inserted
2632 with its upper left corner at point. This means that text is inserted
2633 in the current line and underneath it on successive lines.
2635 If the register contains something other than saved text (a string) or
2636 a rectangle (a list), currently useless things happen. This may be
2637 changed in the future.
2641 @deffn Command copy-to-register register start end &optional delete-flag
2642 This command copies the region from @var{start} to @var{end} into
2643 register @var{register}. If @var{delete-flag} is non-@code{nil}, it deletes
2644 the region from the buffer after copying it into the register.
2647 @deffn Command prepend-to-register register start end &optional delete-flag
2648 This command prepends the region from @var{start} to @var{end} into
2649 register @var{register}. If @var{delete-flag} is non-@code{nil}, it deletes
2650 the region from the buffer after copying it to the register.
2653 @deffn Command append-to-register register start end &optional delete-flag
2654 This command appends the region from @var{start} to @var{end} to the
2655 text already in register @var{register}. If @var{delete-flag} is
2656 non-@code{nil}, it deletes the region from the buffer after copying it
2660 @deffn Command copy-rectangle-to-register register start end &optional delete-flag
2661 This command copies a rectangular region from @var{start} to @var{end}
2662 into register @var{register}. If @var{delete-flag} is non-@code{nil}, it
2663 deletes the region from the buffer after copying it to the register.
2666 @deffn Command window-configuration-to-register register
2667 This function stores the window configuration of the selected frame in
2668 register @var{register}.
2671 @deffn Command frame-configuration-to-register register
2672 This function stores the current frame configuration in register
2678 @section Transposition of Text
2680 This subroutine is used by the transposition commands.
2682 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
2683 This function exchanges two nonoverlapping portions of the buffer.
2684 Arguments @var{start1} and @var{end1} specify the bounds of one portion
2685 and arguments @var{start2} and @var{end2} specify the bounds of the
2688 Normally, @code{transpose-regions} relocates markers with the transposed
2689 text; a marker previously positioned within one of the two transposed
2690 portions moves along with that portion, thus remaining between the same
2691 two characters in their new position. However, if @var{leave-markers}
2692 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
2693 all markers unrelocated.
2697 @section Change Hooks
2698 @cindex change hooks
2699 @cindex hooks for text changes
2701 These hook variables let you arrange to take notice of all changes in
2702 all buffers (or in a particular buffer, if you make them buffer-local).
2703 @ignore Not in XEmacs
2704 See also @ref{Special Properties}, for how to detect changes to specific
2708 The functions you use in these hooks should save and restore the match
2709 data if they do anything that uses regular expressions; otherwise, they
2710 will interfere in bizarre ways with the editing operations that call
2713 Buffer changes made while executing the following hooks don't
2714 themselves cause any change hooks to be invoked.
2716 @defvar before-change-functions
2717 This variable holds a list of a functions to call before any buffer
2718 modification. Each function gets two arguments, the beginning and end
2719 of the region that is about to change, represented as integers. The
2720 buffer that is about to change is always the current buffer.
2723 @defvar after-change-functions
2724 This variable holds a list of a functions to call after any buffer
2725 modification. Each function receives three arguments: the beginning and
2726 end of the region just changed, and the length of the text that existed
2727 before the change. (To get the current length, subtract the region
2728 beginning from the region end.) All three arguments are integers. The
2729 buffer that's about to change is always the current buffer.
2732 @defvar before-change-function
2733 This obsolete variable holds one function to call before any buffer
2734 modification (or @code{nil} for no function). It is called just like
2735 the functions in @code{before-change-functions}.
2738 @defvar after-change-function
2739 This obsolete variable holds one function to call after any buffer modification
2740 (or @code{nil} for no function). It is called just like the functions in
2741 @code{after-change-functions}.
2744 @defvar first-change-hook
2745 This variable is a normal hook that is run whenever a buffer is changed
2746 that was previously in the unmodified state.
2749 @node Transformations
2750 @section Textual transformations---MD5 and base64 support
2754 Some textual operations inherently require examining each character in
2755 turn, and performing arithmetic operations on them. Such operations
2756 can, of course, be implemented in Emacs Lisp, but tend to be very slow
2757 for large portions of text or data. This is why some of them are
2758 implemented in C, with an appropriate interface for Lisp programmers.
2759 Examples of algorithms thus provided are MD5 and base64 support.
2761 MD5 is an algorithm for calculating message digests, as described in
2762 rfc1321. Given a message of arbitrary length, MD5 produces an 128-bit
2763 ``fingerprint'' (``message digest'') corresponding to that message. It
2764 is considered computationally infeasible to produce two messages having
2765 the same MD5 digest, or to produce a message having a prespecified
2766 target digest. MD5 is used heavily by various authentication schemes.
2768 Emacs Lisp interface to MD5 consists of a single function @code{md5}:
2770 @defun md5 object &optional start end coding noerror
2771 This function returns the MD5 message digest of @var{object}, a buffer
2774 Optional arguments @var{start} and @var{end} denote positions for
2775 computing the digest of a portion of @var{object}.
2777 The optional @var{coding} argument specifies the coding system the text
2778 is to be represented in while computing the digest. If unspecified, it
2779 defaults to the current format of the data, or is guessed.
2781 If @var{noerror} is non-@code{nil}, silently assume binary coding if the
2782 guesswork fails. Normally, an error is signaled in such case.
2784 @var{coding} and @var{noerror} arguments are meaningful only in XEmacsen
2785 with file-coding or Mule support. Otherwise, they are ignored. Some
2790 ;; @r{Calculate the digest of the entire buffer}
2791 (md5 (current-buffer))
2792 @result{} "8842b04362899b1cda8d2d126dc11712"
2796 ;; @r{Calculate the digest of the current line}
2797 (md5 (current-buffer) (point-at-bol) (point-at-eol))
2798 @result{} "60614d21e9dee27dfdb01fa4e30d6d00"
2802 ;; @r{Calculate the digest of your name and email address}
2803 (md5 (concat (format "%s <%s>" (user-full-name) user-mail-address)))
2804 @result{} "0a2188c40fd38922d941fe6032fce516"
2809 Base64 is a portable encoding for arbitrary sequences of octets, in a
2810 form that need not be readable by humans. It uses a 65-character subset
2811 of US-ASCII, as described in rfc2045. Base64 is used by MIME to encode
2812 binary bodies, and to encode binary characters in message headers.
2814 The Lisp interface to base64 consists of four functions:
2816 @deffn Command base64-encode-region start end &optional no-line-break
2817 This function encodes the region between @var{start} and @var{end} of the
2818 current buffer to base64 format. This means that the original region is
2819 deleted, and replaced with its base64 equivalent.
2821 Normally, encoded base64 output is multi-line, with 76-character lines.
2822 If @var{no-line-break} is non-@code{nil}, newlines will not be inserted,
2823 resulting in single-line output.
2825 Mule note: you should make sure that you convert the multibyte
2826 characters (those that do not fit into 0--255 range) to something else,
2827 because they cannot be meaningfully converted to base64. If the
2828 @code{base64-encode-region} encounters such characters, it will signal
2831 @code{base64-encode-region} returns the length of the encoded text.
2835 ;; @r{Encode the whole buffer in base64}
2836 (base64-encode-region (point-min) (point-max))
2840 The function can also be used interactively, in which case it works on
2841 the currently active region.
2844 @defun base64-encode-string string &optional no-line-break
2845 This function encodes @var{string} to base64, and returns the encoded
2848 Normally, encoded base64 output is multi-line, with 76-character lines.
2849 If @var{no-line-break} is non-@code{nil}, newlines will not be inserted,
2850 resulting in single-line output.
2852 For Mule, the same considerations apply as for
2853 @code{base64-encode-region}.
2857 (base64-encode-string "fubar")
2858 @result{} "ZnViYXI="
2863 @deffn Command base64-decode-region start end
2864 This function decodes the region between @var{start} and @var{end} of the
2865 current buffer. The region should be in base64 encoding.
2867 If the region was decoded correctly, @code{base64-decode-region} returns
2868 the length of the decoded region. If the decoding failed, @code{nil} is
2873 ;; @r{Decode a base64 buffer, and replace it with the decoded version}
2874 (base64-decode-region (point-min) (point-max))
2879 @defun base64-decode-string string
2880 This function decodes @var{string} to base64, and returns the decoded
2881 string. @var{string} should be valid base64-encoded text.
2883 If encoding was not possible, @code{nil} is returned.
2887 (base64-decode-string "ZnViYXI=")
2892 (base64-decode-string "totally bogus")