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 position &optional 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}. If optional argument
78 @var{buffer} is @code{nil}, the current buffer is assumed.
80 In the following example, assume that the first character in the
85 (char-to-string (char-after 1))
91 @defun following-char &optional buffer
92 This function returns the character following point in the buffer.
93 This is similar to @code{(char-after (point))}. However, if point is at
94 the end of the buffer, then the result of @code{following-char} is 0.
95 If optional argument @var{buffer} is @code{nil}, the current buffer is
98 Remember that point is always between characters, and the terminal
99 cursor normally appears over the character following point. Therefore,
100 the character returned by @code{following-char} is the character the
103 In this example, point is between the @samp{a} and the @samp{c}.
107 ---------- Buffer: foo ----------
108 Gentlemen may cry ``Pea@point{}ce! Peace!,''
109 but there is no peace.
110 ---------- Buffer: foo ----------
114 (char-to-string (preceding-char))
116 (char-to-string (following-char))
122 @defun preceding-char &optional buffer
123 This function returns the character preceding point in the buffer.
124 See above, under @code{following-char}, for an example. If
125 point is at the beginning of the buffer, @code{preceding-char} returns
126 0. If optional argument @var{buffer} is @code{nil}, the current buffer
130 @defun bobp &optional buffer
131 This function returns @code{t} if point is at the beginning of the
132 buffer. If narrowing is in effect, this means the beginning of the
133 accessible portion of the text. If optional argument @var{buffer} is
134 @code{nil}, the current buffer is assumed. See also @code{point-min} in
138 @defun eobp &optional buffer
139 This function returns @code{t} if point is at the end of the buffer.
140 If narrowing is in effect, this means the end of accessible portion of
141 the text. If optional argument @var{buffer} is @code{nil}, the current
142 buffer is assumed. See also @code{point-max} in @xref{Point}.
145 @defun bolp &optional buffer
146 This function returns @code{t} if point is at the beginning of a line.
147 If optional argument @var{buffer} is @code{nil}, the current buffer is
148 assumed. @xref{Text Lines}. The beginning of the buffer (or its
149 accessible portion) always counts as the beginning of a line.
152 @defun eolp &optional buffer
153 This function returns @code{t} if point is at the end of a line. The
154 end of the buffer is always considered the end of a line. If optional
155 argument @var{buffer} is @code{nil}, the current buffer is assumed.
156 The end of the buffer (or of its accessible portion) is always considered
160 @node Buffer Contents
161 @section Examining Buffer Contents
163 This section describes two functions that allow a Lisp program to
164 convert any portion of the text in the buffer into a string.
166 @defun buffer-substring start end &optional buffer
167 @defunx buffer-string start end &optional buffer
168 These functions are equivalent and return a string containing a copy of
169 the text of the region defined by positions @var{start} and @var{end} in
170 the buffer. If the arguments are not positions in the accessible
171 portion of the buffer, @code{buffer-substring} signals an
172 @code{args-out-of-range} error. If optional argument @var{buffer} is
173 @code{nil}, the current buffer is assumed.
176 If the region delineated by @var{start} and @var{end} contains
177 duplicable extents, they will be remembered in the string.
178 @xref{Duplicable Extents}.
180 It is not necessary for @var{start} to be less than @var{end}; the
181 arguments can be given in either order. But most often the smaller
182 argument is written first.
186 ---------- Buffer: foo ----------
187 This is the contents of buffer foo
189 ---------- Buffer: foo ----------
193 (buffer-substring 1 10)
194 @result{} "This is t"
197 (buffer-substring (point-max) 10)
198 @result{} "he contents of buffer foo
205 @c `equal' in XEmacs does not compare text properties on strings
206 @defun buffer-substring-without-properties start end
207 This is like @code{buffer-substring}, except that it does not copy text
208 properties, just the characters themselves. @xref{Text Properties}.
209 Here's an example of using this function to get a word to look up in an
214 (assoc (buffer-substring start end)
215 '(("wood" . t) ("paper" . t)
216 ("steel" . nil) ("asbestos" . nil))))
219 If this were written using @code{buffer-substring} instead, it would not
220 work reliably; any text properties that happened to be in the word
221 copied from the buffer would make the comparisons fail.
226 @section Comparing Text
227 @cindex comparing buffer text
229 This function lets you compare portions of the text in a buffer, without
230 copying them into strings first.
232 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
233 This function lets you compare two substrings of the same buffer or two
234 different buffers. The first three arguments specify one substring,
235 giving a buffer and two positions within the buffer. The last three
236 arguments specify the other substring in the same way. You can use
237 @code{nil} for @var{buffer1}, @var{buffer2}, or both to stand for the
240 The value is negative if the first substring is less, positive if the
241 first is greater, and zero if they are equal. The absolute value of
242 the result is one plus the index of the first differing characters
243 within the substrings.
245 This function ignores case when comparing characters
246 if @code{case-fold-search} is non-@code{nil}. It always ignores
249 Suppose the current buffer contains the text @samp{foobarbar
250 haha!rara!}; then in this example the two substrings are @samp{rbar }
251 and @samp{rara!}. The value is 2 because the first substring is greater
252 at the second character.
255 (compare-buffer-substring nil 6 11 nil 16 21)
261 @section Inserting Text
262 @cindex insertion of text
263 @cindex text insertion
265 @dfn{Insertion} means adding new text to a buffer. The inserted text
266 goes at point---between the character before point and the character
269 Insertion relocates markers that point at positions after the
270 insertion point, so that they stay with the surrounding text
271 (@pxref{Markers}). When a marker points at the place of insertion,
272 insertion normally doesn't relocate the marker, so that it points to the
273 beginning of the inserted text; however, certain special functions such
274 as @code{insert-before-markers} relocate such markers to point after the
277 @cindex insertion before point
278 @cindex before point, insertion
279 Some insertion functions leave point before the inserted text, while
280 other functions leave it after. We call the former insertion @dfn{after
281 point} and the latter insertion @dfn{before point}.
284 If a string with non-@code{nil} extent data is inserted, the remembered
285 extents will also be inserted. @xref{Duplicable Extents}.
287 Insertion functions signal an error if the current buffer is
290 These functions copy text characters from strings and buffers along
291 with their properties. The inserted characters have exactly the same
292 properties as the characters they were copied from. By contrast,
293 characters specified as separate arguments, not part of a string or
294 buffer, inherit their text properties from the neighboring text.
296 @defun insert &rest args
297 This function inserts the strings and/or characters @var{args} into the
298 current buffer, at point, moving point forward. In other words, it
299 inserts the text before point. An error is signaled unless all
300 @var{args} are either strings or characters. The value is @code{nil}.
303 @defun insert-before-markers &rest args
304 This function inserts the strings and/or characters @var{args} into the
305 current buffer, at point, moving point forward. An error is signaled
306 unless all @var{args} are either strings or characters. The value is
309 This function is unlike the other insertion functions in that it
310 relocates markers initially pointing at the insertion point, to point
311 after the inserted text.
314 @defun insert-string string &optional buffer
315 This function inserts @var{string} into @var{buffer} before point.
316 @var{buffer} defaults to the current buffer if omitted. This
317 function is chiefly useful if you want to insert a string in
318 a buffer other than the current one (otherwise you could just
322 @defun insert-char character count &optional buffer
323 This function inserts @var{count} instances of @var{character} into
324 @var{buffer} before point. @var{count} must be a number, and
325 @var{character} must be a character. The value is @code{nil}. If
326 optional argument @var{buffer} is @code{nil}, the current buffer is
327 assumed. (In FSF Emacs, the third argument is called @var{inherit}
328 and refers to text properties.)
331 @defun insert-buffer-substring from-buffer-or-name &optional start end
332 This function inserts a portion of buffer @var{from-buffer-or-name}
333 (which must already exist) into the current buffer before point. The
334 text inserted is the region from @var{start} and @var{end}. (These
335 arguments default to the beginning and end of the accessible portion of
336 that buffer.) This function returns @code{nil}.
338 In this example, the form is executed with buffer @samp{bar} as the
339 current buffer. We assume that buffer @samp{bar} is initially empty.
343 ---------- Buffer: foo ----------
344 We hold these truths to be self-evident, that all
345 ---------- Buffer: foo ----------
349 (insert-buffer-substring "foo" 1 20)
352 ---------- Buffer: bar ----------
353 We hold these truth@point{}
354 ---------- Buffer: bar ----------
359 @node Commands for Insertion
360 @section User-Level Insertion Commands
362 This section describes higher-level commands for inserting text,
363 commands intended primarily for the user but useful also in Lisp
366 @deffn Command insert-buffer from-buffer-or-name
367 This command inserts the entire contents of @var{from-buffer-or-name}
368 (which must exist) into the current buffer after point. It leaves
369 the mark after the inserted text. The value is @code{nil}.
372 @deffn Command self-insert-command count
373 @cindex character insertion
374 @cindex self-insertion
375 This command inserts the last character typed; it does so @var{count}
376 times, before point, and returns @code{nil}. Most printing characters
377 are bound to this command. In routine use, @code{self-insert-command}
378 is the most frequently called function in XEmacs, but programs rarely use
379 it except to install it on a keymap.
381 In an interactive call, @var{count} is the numeric prefix argument.
383 This command calls @code{auto-fill-function} whenever that is
384 non-@code{nil} and the character inserted is a space or a newline
385 (@pxref{Auto Filling}).
387 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
388 This command performs abbrev expansion if Abbrev mode is enabled and
389 the inserted character does not have word-constituent
390 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
392 This is also responsible for calling @code{blink-paren-function} when
393 the inserted character has close parenthesis syntax (@pxref{Blinking}).
396 @deffn Command newline &optional number-of-newlines
397 This command inserts newlines into the current buffer before point.
398 If @var{number-of-newlines} is supplied, that many newline characters
401 @cindex newline and Auto Fill mode
402 This function calls @code{auto-fill-function} if the current column
403 number is greater than the value of @code{fill-column} and
404 @var{number-of-newlines} is @code{nil}. Typically what
405 @code{auto-fill-function} does is insert a newline; thus, the overall
406 result in this case is to insert two newlines at different places: one
407 at point, and another earlier in the line. @code{newline} does not
408 auto-fill if @var{number-of-newlines} is non-@code{nil}.
410 This command indents to the left margin if that is not zero.
413 The value returned is @code{nil}. In an interactive call, @var{count}
414 is the numeric prefix argument.
417 @deffn Command split-line
418 This command splits the current line, moving the portion of the line
419 after point down vertically so that it is on the next line directly
420 below where it was before. Whitespace is inserted as needed at the
421 beginning of the lower line, using the @code{indent-to} function.
422 @code{split-line} returns the position of point.
424 Programs hardly ever use this function.
427 @defvar overwrite-mode
428 This variable controls whether overwrite mode is in effect: a
429 non-@code{nil} value enables the mode. It is automatically made
430 buffer-local when set in any fashion.
434 @section Deleting Text
436 @cindex deletion vs killing
437 Deletion means removing part of the text in a buffer, without saving
438 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
439 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
440 Some deletion functions do save text in the kill ring in some special
443 All of the deletion functions operate on the current buffer, and all
444 return a value of @code{nil}.
446 @defun erase-buffer &optional buffer
447 This function deletes the entire text of @var{buffer}, leaving it
448 empty. If the buffer is read-only, it signals a @code{buffer-read-only}
449 error. Otherwise, it deletes the text without asking for any
450 confirmation. It returns @code{nil}. @var{buffer} defaults to the
451 current buffer if omitted.
453 Normally, deleting a large amount of text from a buffer inhibits further
454 auto-saving of that buffer ``because it has shrunk''. However,
455 @code{erase-buffer} does not do this, the idea being that the future
456 text is not really related to the former text, and its size should not
457 be compared with that of the former text.
460 @deffn Command delete-region start end &optional buffer
461 This command deletes the text in @var{buffer} in the region defined by
462 @var{start} and @var{end}. The value is @code{nil}. If optional
463 argument @var{buffer} is @code{nil}, the current buffer is assumed.
466 @deffn Command delete-char count &optional killp
467 This command deletes @var{count} characters directly after point, or
468 before point if @var{count} is negative. If @var{killp} is
469 non-@code{nil}, then it saves the deleted characters in the kill ring.
471 In an interactive call, @var{count} is the numeric prefix argument, and
472 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
473 argument is supplied, the text is saved in the kill ring. If no prefix
474 argument is supplied, then one character is deleted, but not saved in
477 The value returned is always @code{nil}.
480 @deffn Command delete-backward-char count &optional killp
481 @cindex delete previous char
482 This command deletes @var{count} characters directly before point, or
483 after point if @var{count} is negative. If @var{killp} is
484 non-@code{nil}, then it saves the deleted characters in the kill ring.
486 In an interactive call, @var{count} is the numeric prefix argument, and
487 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
488 argument is supplied, the text is saved in the kill ring. If no prefix
489 argument is supplied, then one character is deleted, but not saved in
492 The value returned is always @code{nil}.
495 @deffn Command backward-delete-char-untabify count &optional killp
497 This command deletes @var{count} characters backward, changing tabs
498 into spaces. When the next character to be deleted is a tab, it is
499 first replaced with the proper number of spaces to preserve alignment
500 and then one of those spaces is deleted instead of the tab. If
501 @var{killp} is non-@code{nil}, then the command saves the deleted
502 characters in the kill ring.
504 Conversion of tabs to spaces happens only if @var{count} is positive.
505 If it is negative, exactly @minus{}@var{count} characters after point
508 In an interactive call, @var{count} is the numeric prefix argument, and
509 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix
510 argument is supplied, the text is saved in the kill ring. If no prefix
511 argument is supplied, then one character is deleted, but not saved in
514 The value returned is always @code{nil}.
517 @node User-Level Deletion
518 @section User-Level Deletion Commands
520 This section describes higher-level commands for deleting text,
521 commands intended primarily for the user but useful also in Lisp
524 @deffn Command delete-horizontal-space
525 @cindex deleting whitespace
526 This function deletes all spaces and tabs around point. It returns
529 In the following examples, we call @code{delete-horizontal-space} four
530 times, once on each line, with point between the second and third
531 characters on the line each time.
535 ---------- Buffer: foo ----------
540 ---------- Buffer: foo ----------
544 (delete-horizontal-space) ; @r{Four times.}
547 ---------- Buffer: foo ----------
552 ---------- Buffer: foo ----------
557 @deffn Command delete-indentation &optional join-following-p
558 This function joins the line point is on to the previous line, deleting
559 any whitespace at the join and in some cases replacing it with one
560 space. If @var{join-following-p} is non-@code{nil},
561 @code{delete-indentation} joins this line to the following line
562 instead. The value is @code{nil}.
564 If there is a fill prefix, and the second of the lines being joined
565 starts with the prefix, then @code{delete-indentation} deletes the
566 fill prefix before joining the lines. @xref{Margins}.
568 In the example below, point is located on the line starting
569 @samp{events}, and it makes no difference if there are trailing spaces
570 in the preceding line.
574 ---------- Buffer: foo ----------
575 When in the course of human
576 @point{} events, it becomes necessary
577 ---------- Buffer: foo ----------
584 ---------- Buffer: foo ----------
585 When in the course of human@point{} events, it becomes necessary
586 ---------- Buffer: foo ----------
590 After the lines are joined, the function @code{fixup-whitespace} is
591 responsible for deciding whether to leave a space at the junction.
594 @defun fixup-whitespace
595 This function replaces all the white space surrounding point with either
596 one space or no space, according to the context. It returns @code{nil}.
598 At the beginning or end of a line, the appropriate amount of space is
599 none. Before a character with close parenthesis syntax, or after a
600 character with open parenthesis or expression-prefix syntax, no space is
601 also appropriate. Otherwise, one space is appropriate. @xref{Syntax
604 In the example below, @code{fixup-whitespace} is called the first time
605 with point before the word @samp{spaces} in the first line. For the
606 second invocation, point is directly after the @samp{(}.
610 ---------- Buffer: foo ----------
611 This has too many @point{}spaces
612 This has too many spaces at the start of (@point{} this list)
613 ---------- Buffer: foo ----------
624 ---------- Buffer: foo ----------
625 This has too many spaces
626 This has too many spaces at the start of (this list)
627 ---------- Buffer: foo ----------
632 @deffn Command just-one-space
633 @comment !!SourceFile simple.el
634 This command replaces any spaces and tabs around point with a single
635 space. It returns @code{nil}.
638 @deffn Command delete-blank-lines
639 This function deletes blank lines surrounding point. If point is on a
640 blank line with one or more blank lines before or after it, then all but
641 one of them are deleted. If point is on an isolated blank line, then it
642 is deleted. If point is on a nonblank line, the command deletes all
643 blank lines following it.
645 A blank line is defined as a line containing only tabs and spaces.
647 @code{delete-blank-lines} returns @code{nil}.
651 @section The Kill Ring
654 @dfn{Kill} functions delete text like the deletion functions, but save
655 it so that the user can reinsert it by @dfn{yanking}. Most of these
656 functions have @samp{kill-} in their name. By contrast, the functions
657 whose names start with @samp{delete-} normally do not save text for
658 yanking (though they can still be undone); these are ``deletion''
661 Most of the kill commands are primarily for interactive use, and are
662 not described here. What we do describe are the functions provided for
663 use in writing such commands. You can use these functions to write
664 commands for killing text. When you need to delete text for internal
665 purposes within a Lisp function, you should normally use deletion
666 functions, so as not to disturb the kill ring contents.
669 Killed text is saved for later yanking in the @dfn{kill ring}. This
670 is a list that holds a number of recent kills, not just the last text
671 kill. We call this a ``ring'' because yanking treats it as having
672 elements in a cyclic order. The list is kept in the variable
673 @code{kill-ring}, and can be operated on with the usual functions for
674 lists; there are also specialized functions, described in this section,
675 that treat it as a ring.
677 Some people think this use of the word ``kill'' is unfortunate, since
678 it refers to operations that specifically @emph{do not} destroy the
679 entities ``killed''. This is in sharp contrast to ordinary life, in
680 which death is permanent and ``killed'' entities do not come back to
681 life. Therefore, other metaphors have been proposed. For example, the
682 term ``cut ring'' makes sense to people who, in pre-computer days, used
683 scissors and paste to cut up and rearrange manuscripts. However, it
684 would be difficult to change the terminology now.
687 * Kill Ring Concepts:: What text looks like in the kill ring.
688 * Kill Functions:: Functions that kill text.
689 * Yank Commands:: Commands that access the kill ring.
690 * Low-Level Kill Ring:: Functions and variables for kill ring access.
691 * Internals of Kill Ring:: Variables that hold kill-ring data.
694 @node Kill Ring Concepts
695 @subsection Kill Ring Concepts
697 The kill ring records killed text as strings in a list, most recent
698 first. A short kill ring, for example, might look like this:
701 ("some text" "a different piece of text" "even older text")
705 When the list reaches @code{kill-ring-max} entries in length, adding a
706 new entry automatically deletes the last entry.
708 When kill commands are interwoven with other commands, each kill
709 command makes a new entry in the kill ring. Multiple kill commands in
710 succession build up a single entry in the kill ring, which would be
711 yanked as a unit; the second and subsequent consecutive kill commands
712 add text to the entry made by the first one.
714 For yanking, one entry in the kill ring is designated the ``front'' of
715 the ring. Some yank commands ``rotate'' the ring by designating a
716 different element as the ``front.'' But this virtual rotation doesn't
717 change the list itself---the most recent entry always comes first in the
721 @subsection Functions for Killing
723 @code{kill-region} is the usual subroutine for killing text. Any
724 command that calls this function is a ``kill command'' (and should
725 probably have @samp{kill} in its name). @code{kill-region} puts the
726 newly killed text in a new element at the beginning of the kill ring or
727 adds it to the most recent element. It uses the @code{last-command}
728 variable to determine whether the previous command was a kill command,
729 and if so appends the killed text to the most recent entry.
731 @deffn Command kill-region start end
732 This function kills the text in the region defined by @var{start} and
733 @var{end}. The text is deleted but saved in the kill ring, along with
734 its text properties. The value is always @code{nil}.
736 In an interactive call, @var{start} and @var{end} are point and
740 If the buffer is read-only, @code{kill-region} modifies the kill ring
741 just the same, then signals an error without modifying the buffer. This
742 is convenient because it lets the user use all the kill commands to copy
743 text into the kill ring from a read-only buffer.
746 @deffn Command copy-region-as-kill start end
747 This command saves the region defined by @var{start} and @var{end} on
748 the kill ring (including text properties), but does not delete the text
749 from the buffer. It returns @code{nil}. It also indicates the extent
750 of the text copied by moving the cursor momentarily, or by displaying a
751 message in the echo area.
753 The command does not set @code{this-command} to @code{kill-region}, so a
754 subsequent kill command does not append to the same kill ring entry.
756 Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
757 support Emacs 18. For Emacs 19, it is better to use @code{kill-new} or
758 @code{kill-append} instead. @xref{Low-Level Kill Ring}.
762 @subsection Functions for Yanking
764 @dfn{Yanking} means reinserting an entry of previously killed text
765 from the kill ring. The text properties are copied too.
767 @deffn Command yank &optional arg
768 @cindex inserting killed text
769 This command inserts before point the text in the first entry in the
770 kill ring. It positions the mark at the beginning of that text, and
773 If @var{arg} is a list (which occurs interactively when the user
774 types @kbd{C-u} with no digits), then @code{yank} inserts the text as
775 described above, but puts point before the yanked text and puts the mark
778 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most
779 recently killed text---the @var{arg}th element of the kill ring list.
781 @code{yank} does not alter the contents of the kill ring or rotate it.
782 It returns @code{nil}.
785 @deffn Command yank-pop arg
786 This command replaces the just-yanked entry from the kill ring with a
787 different entry from the kill ring.
789 This is allowed only immediately after a @code{yank} or another
790 @code{yank-pop}. At such a time, the region contains text that was just
791 inserted by yanking. @code{yank-pop} deletes that text and inserts in
792 its place a different piece of killed text. It does not add the deleted
793 text to the kill ring, since it is already in the kill ring somewhere.
795 If @var{arg} is @code{nil}, then the replacement text is the previous
796 element of the kill ring. If @var{arg} is numeric, the replacement is
797 the @var{arg}th previous kill. If @var{arg} is negative, a more recent
798 kill is the replacement.
800 The sequence of kills in the kill ring wraps around, so that after the
801 oldest one comes the newest one, and before the newest one goes the
804 The value is always @code{nil}.
807 @node Low-Level Kill Ring
808 @subsection Low-Level Kill Ring
810 These functions and variables provide access to the kill ring at a lower
811 level, but still convenient for use in Lisp programs. They take care of
812 interaction with X Window selections. They do not exist in Emacs
815 @defun current-kill n &optional do-not-move
816 The function @code{current-kill} rotates the yanking pointer which
817 designates the ``front'' of the kill ring by @var{n} places (from newer
818 kills to older ones), and returns the text at that place in the ring.
820 If the optional second argument @var{do-not-move} is non-@code{nil},
821 then @code{current-kill} doesn't alter the yanking pointer; it just
822 returns the @var{n}th kill, counting from the current yanking pointer.
824 If @var{n} is zero, indicating a request for the latest kill,
825 @code{current-kill} calls the value of
826 @code{interprogram-paste-function} (documented below) before consulting
830 @defun kill-new string
831 This function puts the text @var{string} into the kill ring as a new
832 entry at the front of the ring. It discards the oldest entry if
833 appropriate. It also invokes the value of
834 @code{interprogram-cut-function} (see below).
837 @defun kill-append string before-p
838 This function appends the text @var{string} to the first entry in the
839 kill ring. Normally @var{string} goes at the end of the entry, but if
840 @var{before-p} is non-@code{nil}, it goes at the beginning. This
841 function also invokes the value of @code{interprogram-cut-function} (see
845 @defvar interprogram-paste-function
846 This variable provides a way of transferring killed text from other
847 programs, when you are using a window system. Its value should be
848 @code{nil} or a function of no arguments.
850 If the value is a function, @code{current-kill} calls it to get the
851 ``most recent kill''. If the function returns a non-@code{nil} value,
852 then that value is used as the ``most recent kill''. If it returns
853 @code{nil}, then the first element of @code{kill-ring} is used.
855 The normal use of this hook is to get the X server's primary selection
856 as the most recent kill, even if the selection belongs to another X
857 client. @xref{X Selections}.
860 @defvar interprogram-cut-function
861 This variable provides a way of communicating killed text to other
862 programs, when you are using a window system. Its value should be
863 @code{nil} or a function of one argument.
865 If the value is a function, @code{kill-new} and @code{kill-append} call
866 it with the new first element of the kill ring as an argument.
868 The normal use of this hook is to set the X server's primary selection
869 to the newly killed text.
872 @node Internals of Kill Ring
873 @subsection Internals of the Kill Ring
875 The variable @code{kill-ring} holds the kill ring contents, in the
876 form of a list of strings. The most recent kill is always at the front
879 The @code{kill-ring-yank-pointer} variable points to a link in the
880 kill ring list, whose @sc{car} is the text to yank next. We say it
881 identifies the ``front'' of the ring. Moving
882 @code{kill-ring-yank-pointer} to a different link is called
883 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
884 the functions that move the yank pointer wrap around from the end of the
885 list to the beginning, or vice-versa. Rotation of the kill ring is
886 virtual; it does not change the value of @code{kill-ring}.
888 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
889 variables whose values are normally lists. The word ``pointer'' in the
890 name of the @code{kill-ring-yank-pointer} indicates that the variable's
891 purpose is to identify one element of the list for use by the next yank
894 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
895 of the links in the kill ring list. The element it identifies is the
896 @sc{car} of that link. Kill commands, which change the kill ring, also
897 set this variable to the value of @code{kill-ring}. The effect is to
898 rotate the ring so that the newly killed text is at the front.
900 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
901 pointing to the second entry in the kill ring @code{("some text" "a
902 different piece of text" "yet older text")}.
906 kill-ring kill-ring-yank-pointer
908 | ___ ___ ---> ___ ___ ___ ___
909 --> |___|___|------> |___|___|--> |___|___|--> nil
912 | | -->"yet older text"
914 | --> "a different piece of text"
921 This state of affairs might occur after @kbd{C-y} (@code{yank})
922 immediately followed by @kbd{M-y} (@code{yank-pop}).
925 This variable holds the list of killed text sequences, most recently
929 @defvar kill-ring-yank-pointer
930 This variable's value indicates which element of the kill ring is at the
931 ``front'' of the ring for yanking. More precisely, the value is a tail
932 of the value of @code{kill-ring}, and its @sc{car} is the kill string
933 that @kbd{C-y} should yank.
936 @defopt kill-ring-max
937 The value of this variable is the maximum length to which the kill
938 ring can grow, before elements are thrown away at the end. The default
939 value for @code{kill-ring-max} is 30.
946 Most buffers have an @dfn{undo list}, which records all changes made
947 to the buffer's text so that they can be undone. (The buffers that
948 don't have one are usually special-purpose buffers for which XEmacs
949 assumes that undoing is not useful.) All the primitives that modify the
950 text in the buffer automatically add elements to the front of the undo
951 list, which is in the variable @code{buffer-undo-list}.
953 @defvar buffer-undo-list
954 This variable's value is the undo list of the current buffer.
955 A value of @code{t} disables the recording of undo information.
958 Here are the kinds of elements an undo list can have:
962 This kind of element records a previous value of point. Ordinary cursor
963 motion does not get any sort of undo record, but deletion commands use
964 these entries to record where point was before the command.
966 @item (@var{beg} . @var{end})
967 This kind of element indicates how to delete text that was inserted.
968 Upon insertion, the text occupied the range @var{beg}--@var{end} in the
971 @item (@var{text} . @var{position})
972 This kind of element indicates how to reinsert text that was deleted.
973 The deleted text itself is the string @var{text}. The place to
974 reinsert it is @code{(abs @var{position})}.
976 @item (t @var{high} . @var{low})
977 This kind of element indicates that an unmodified buffer became
978 modified. The elements @var{high} and @var{low} are two integers, each
979 recording 16 bits of the visited file's modification time as of when it
980 was previously visited or saved. @code{primitive-undo} uses those
981 values to determine whether to mark the buffer as unmodified once again;
982 it does so only if the file's modification time matches those numbers.
984 @item (nil @var{property} @var{value} @var{beg} . @var{end})
985 This kind of element records a change in a text property.
986 Here's how you might undo the change:
989 (put-text-property @var{beg} @var{end} @var{property} @var{value})
993 This element indicates where point was at an earlier time. Undoing this
994 element sets point to @var{position}. Deletion normally creates an
995 element of this kind as well as a reinsertion element.
998 This element is a boundary. The elements between two boundaries are
999 called a @dfn{change group}; normally, each change group corresponds to
1000 one keyboard command, and undo commands normally undo an entire group as
1004 @defun undo-boundary
1005 This function places a boundary element in the undo list. The undo
1006 command stops at such a boundary, and successive undo commands undo
1007 to earlier and earlier boundaries. This function returns @code{nil}.
1009 The editor command loop automatically creates an undo boundary before
1010 each key sequence is executed. Thus, each undo normally undoes the
1011 effects of one command. Self-inserting input characters are an
1012 exception. The command loop makes a boundary for the first such
1013 character; the next 19 consecutive self-inserting input characters do
1014 not make boundaries, and then the 20th does, and so on as long as
1015 self-inserting characters continue.
1017 All buffer modifications add a boundary whenever the previous undoable
1018 change was made in some other buffer. This way, a command that modifies
1019 several buffers makes a boundary in each buffer it changes.
1021 Calling this function explicitly is useful for splitting the effects of
1022 a command into more than one unit. For example, @code{query-replace}
1023 calls @code{undo-boundary} after each replacement, so that the user can
1024 undo individual replacements one by one.
1027 @defun primitive-undo count list
1028 This is the basic function for undoing elements of an undo list.
1029 It undoes the first @var{count} elements of @var{list}, returning
1030 the rest of @var{list}. You could write this function in Lisp,
1031 but it is convenient to have it in C.
1033 @code{primitive-undo} adds elements to the buffer's undo list when it
1034 changes the buffer. Undo commands avoid confusion by saving the undo
1035 list value at the beginning of a sequence of undo operations. Then the
1036 undo operations use and update the saved value. The new elements added
1037 by undoing are not part of this saved value, so they don't interfere with
1041 @node Maintaining Undo
1042 @section Maintaining Undo Lists
1044 This section describes how to enable and disable undo information for
1045 a given buffer. It also explains how the undo list is truncated
1046 automatically so it doesn't get too big.
1048 Recording of undo information in a newly created buffer is normally
1049 enabled to start with; but if the buffer name starts with a space, the
1050 undo recording is initially disabled. You can explicitly enable or
1051 disable undo recording with the following two functions, or by setting
1052 @code{buffer-undo-list} yourself.
1054 @deffn Command buffer-enable-undo &optional buffer-or-name
1055 This command enables recording undo information for buffer
1056 @var{buffer-or-name}, so that subsequent changes can be undone. If no
1057 argument is supplied, then the current buffer is used. This function
1058 does nothing if undo recording is already enabled in the buffer. It
1061 In an interactive call, @var{buffer-or-name} is the current buffer.
1062 You cannot specify any other buffer.
1065 @defun buffer-disable-undo &optional buffer
1066 @defunx buffer-flush-undo &optional buffer
1067 @cindex disable undo
1068 This function discards the undo list of @var{buffer}, and disables
1069 further recording of undo information. As a result, it is no longer
1070 possible to undo either previous changes or any subsequent changes. If
1071 the undo list of @var{buffer} is already disabled, this function
1074 This function returns @code{nil}. It cannot be called interactively.
1076 The name @code{buffer-flush-undo} is not considered obsolete, but the
1077 preferred name @code{buffer-disable-undo} is new as of Emacs versions
1081 As editing continues, undo lists get longer and longer. To prevent
1082 them from using up all available memory space, garbage collection trims
1083 them back to size limits you can set. (For this purpose, the ``size''
1084 of an undo list measures the cons cells that make up the list, plus the
1085 strings of deleted text.) Two variables control the range of acceptable
1086 sizes: @code{undo-limit} and @code{undo-strong-limit}.
1089 This is the soft limit for the acceptable size of an undo list. The
1090 change group at which this size is exceeded is the last one kept.
1093 @defvar undo-strong-limit
1094 This is the upper limit for the acceptable size of an undo list. The
1095 change group at which this size is exceeded is discarded itself (along
1096 with all older change groups). There is one exception: the very latest
1097 change group is never discarded no matter how big it is.
1102 @cindex filling, explicit
1104 @dfn{Filling} means adjusting the lengths of lines (by moving the line
1105 breaks) so that they are nearly (but no greater than) a specified
1106 maximum width. Additionally, lines can be @dfn{justified}, which means
1107 inserting spaces to make the left and/or right margins line up
1108 precisely. The width is controlled by the variable @code{fill-column}.
1109 For ease of reading, lines should be no longer than 70 or so columns.
1111 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1112 automatically as you insert it, but changes to existing text may leave
1113 it improperly filled. Then you must fill the text explicitly.
1115 Most of the commands in this section return values that are not
1116 meaningful. All the functions that do filling take note of the current
1117 left margin, current right margin, and current justification style
1118 (@pxref{Margins}). If the current justification style is
1119 @code{none}, the filling functions don't actually do anything.
1121 Several of the filling functions have an argument @var{justify}.
1122 If it is non-@code{nil}, that requests some kind of justification. It
1123 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
1124 request a specific style of justification. If it is @code{t}, that
1125 means to use the current justification style for this part of the text
1126 (see @code{current-justification}, below).
1128 When you call the filling functions interactively, using a prefix
1129 argument implies the value @code{full} for @var{justify}.
1131 @deffn Command fill-paragraph justify
1132 @cindex filling a paragraph
1133 This command fills the paragraph at or after point. If
1134 @var{justify} is non-@code{nil}, each line is justified as well.
1135 It uses the ordinary paragraph motion commands to find paragraph
1136 boundaries. @xref{Paragraphs,,, xemacs, The XEmacs User's Manual}.
1139 @deffn Command fill-region start end &optional justify
1140 This command fills each of the paragraphs in the region from @var{start}
1141 to @var{end}. It justifies as well if @var{justify} is
1144 The variable @code{paragraph-separate} controls how to distinguish
1145 paragraphs. @xref{Standard Regexps}.
1148 @deffn Command fill-individual-paragraphs start end &optional justify mail-flag
1149 This command fills each paragraph in the region according to its
1150 individual fill prefix. Thus, if the lines of a paragraph were indented
1151 with spaces, the filled paragraph will remain indented in the same
1154 The first two arguments, @var{start} and @var{end}, are the beginning
1155 and end of the region to be filled. The third and fourth arguments,
1156 @var{justify} and @var{mail-flag}, are optional. If
1157 @var{justify} is non-@code{nil}, the paragraphs are justified as
1158 well as filled. If @var{mail-flag} is non-@code{nil}, it means the
1159 function is operating on a mail message and therefore should not fill
1162 Ordinarily, @code{fill-individual-paragraphs} regards each change in
1163 indentation as starting a new paragraph. If
1164 @code{fill-individual-varying-indent} is non-@code{nil}, then only
1165 separator lines separate paragraphs. That mode can handle indented
1166 paragraphs with additional indentation on the first line.
1169 @defopt fill-individual-varying-indent
1170 This variable alters the action of @code{fill-individual-paragraphs} as
1174 @deffn Command fill-region-as-paragraph start end &optional justify
1175 This command considers a region of text as a paragraph and fills it. If
1176 the region was made up of many paragraphs, the blank lines between
1177 paragraphs are removed. This function justifies as well as filling when
1178 @var{justify} is non-@code{nil}.
1180 In an interactive call, any prefix argument requests justification.
1182 In Adaptive Fill mode, which is enabled by default,
1183 @code{fill-region-as-paragraph} on an indented paragraph when there is
1184 no fill prefix uses the indentation of the second line of the paragraph
1188 @deffn Command justify-current-line how eop nosqueeze
1189 This command inserts spaces between the words of the current line so
1190 that the line ends exactly at @code{fill-column}. It returns
1193 The argument @var{how}, if non-@code{nil} specifies explicitly the style
1194 of justification. It can be @code{left}, @code{right}, @code{full},
1195 @code{center}, or @code{none}. If it is @code{t}, that means to do
1196 follow specified justification style (see @code{current-justification},
1197 below). @code{nil} means to do full justification.
1199 If @var{eop} is non-@code{nil}, that means do left-justification when
1200 @code{current-justification} specifies full justification. This is used
1201 for the last line of a paragraph; even if the paragraph as a whole is
1202 fully justified, the last line should not be.
1204 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1208 @defopt default-justification
1209 This variable's value specifies the style of justification to use for
1210 text that doesn't specify a style with a text property. The possible
1211 values are @code{left}, @code{right}, @code{full}, @code{center}, or
1212 @code{none}. The default value is @code{left}.
1215 @defun current-justification
1216 This function returns the proper justification style to use for filling
1217 the text around point.
1220 @defvar fill-paragraph-function
1221 This variable provides a way for major modes to override the filling of
1222 paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
1223 this function to do the work. If the function returns a non-@code{nil}
1224 value, @code{fill-paragraph} assumes the job is done, and immediately
1227 The usual use of this feature is to fill comments in programming
1228 language modes. If the function needs to fill a paragraph in the usual
1229 way, it can do so as follows:
1232 (let ((fill-paragraph-function nil))
1233 (fill-paragraph arg))
1237 @defvar use-hard-newlines
1238 If this variable is non-@code{nil}, the filling functions do not delete
1239 newlines that have the @code{hard} text property. These ``hard
1240 newlines'' act as paragraph separators.
1244 @section Margins for Filling
1247 This variable specifies a string of text that appears at the beginning
1248 of normal text lines and should be disregarded when filling them. Any
1249 line that fails to start with the fill prefix is considered the start of
1250 a paragraph; so is any line that starts with the fill prefix followed by
1251 additional whitespace. Lines that start with the fill prefix but no
1252 additional whitespace are ordinary text lines that can be filled
1253 together. The resulting filled lines also start with the fill prefix.
1255 The fill prefix follows the left margin whitespace, if any.
1259 This buffer-local variable specifies the maximum width of filled
1260 lines. Its value should be an integer, which is a number of columns.
1261 All the filling, justification and centering commands are affected by
1262 this variable, including Auto Fill mode (@pxref{Auto Filling}).
1264 As a practical matter, if you are writing text for other people to
1265 read, you should set @code{fill-column} to no more than 70. Otherwise
1266 the line will be too long for people to read comfortably, and this can
1267 make the text seem clumsy.
1270 @defvar default-fill-column
1271 The value of this variable is the default value for @code{fill-column} in
1272 buffers that do not override it. This is the same as
1273 @code{(default-value 'fill-column)}.
1275 The default value for @code{default-fill-column} is 70.
1278 @deffn Command set-left-margin from to margin
1279 This sets the @code{left-margin} property on the text from @var{from} to
1280 @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
1281 command also refills the region to fit the new margin.
1284 @deffn Command set-right-margin from to margin
1285 This sets the @code{right-margin} property on the text from @var{from}
1286 to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
1287 this command also refills the region to fit the new margin.
1290 @defun current-left-margin
1291 This function returns the proper left margin value to use for filling
1292 the text around point. The value is the sum of the @code{left-margin}
1293 property of the character at the start of the current line (or zero if
1294 none), and the value of the variable @code{left-margin}.
1297 @defun current-fill-column
1298 This function returns the proper fill column value to use for filling
1299 the text around point. The value is the value of the @code{fill-column}
1300 variable, minus the value of the @code{right-margin} property of the
1301 character after point.
1304 @deffn Command move-to-left-margin &optional n force
1305 This function moves point to the left margin of the current line. The
1306 column moved to is determined by calling the function
1307 @code{current-left-margin}. If the argument @var{n} is non-@code{nil},
1308 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
1310 If @var{force} is non-@code{nil}, that says to fix the line's
1311 indentation if that doesn't match the left margin value.
1314 @defun delete-to-left-margin from to
1315 This function removes left margin indentation from the text
1316 between @var{from} and @var{to}. The amount of indentation
1317 to delete is determined by calling @code{current-left-margin}.
1318 In no case does this function delete non-whitespace.
1321 @defun indent-to-left-margin
1322 This is the default @code{indent-line-function}, used in Fundamental
1323 mode, Text mode, etc. Its effect is to adjust the indentation at the
1324 beginning of the current line to the value specified by the variable
1325 @code{left-margin}. This may involve either inserting or deleting
1330 This variable specifies the base left margin column. In Fundamental
1331 mode, @key{LFD} indents to this column. This variable automatically
1332 becomes buffer-local when set in any fashion.
1336 @section Auto Filling
1337 @cindex filling, automatic
1338 @cindex Auto Fill mode
1340 Auto Fill mode is a minor mode that fills lines automatically as text
1341 is inserted. This section describes the hook used by Auto Fill mode.
1342 For a description of functions that you can call explicitly to fill and
1343 justify existing text, see @ref{Filling}.
1345 Auto Fill mode also enables the functions that change the margins and
1346 justification style to refill portions of the text. @xref{Margins}.
1348 @defvar auto-fill-function
1349 The value of this variable should be a function (of no arguments) to be
1350 called after self-inserting a space or a newline. It may be @code{nil},
1351 in which case nothing special is done in that case.
1353 The value of @code{auto-fill-function} is @code{do-auto-fill} when
1354 Auto-Fill mode is enabled. That is a function whose sole purpose is to
1355 implement the usual strategy for breaking a line.
1358 In older Emacs versions, this variable was named @code{auto-fill-hook},
1359 but since it is not called with the standard convention for hooks, it
1360 was renamed to @code{auto-fill-function} in version 19.
1365 @section Sorting Text
1366 @cindex sorting text
1368 The sorting functions described in this section all rearrange text in
1369 a buffer. This is in contrast to the function @code{sort}, which
1370 rearranges the order of the elements of a list (@pxref{Rearrangement}).
1371 The values returned by these functions are not meaningful.
1373 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
1374 This function is the general text-sorting routine that divides a buffer
1375 into records and sorts them. Most of the commands in this section use
1378 To understand how @code{sort-subr} works, consider the whole accessible
1379 portion of the buffer as being divided into disjoint pieces called
1380 @dfn{sort records}. The records may or may not be contiguous; they may
1381 not overlap. A portion of each sort record (perhaps all of it) is
1382 designated as the sort key. Sorting rearranges the records in order by
1385 Usually, the records are rearranged in order of ascending sort key.
1386 If the first argument to the @code{sort-subr} function, @var{reverse},
1387 is non-@code{nil}, the sort records are rearranged in order of
1388 descending sort key.
1390 The next four arguments to @code{sort-subr} are functions that are
1391 called to move point across a sort record. They are called many times
1392 from within @code{sort-subr}.
1396 @var{nextrecfun} is called with point at the end of a record. This
1397 function moves point to the start of the next record. The first record
1398 is assumed to start at the position of point when @code{sort-subr} is
1399 called. Therefore, you should usually move point to the beginning of
1400 the buffer before calling @code{sort-subr}.
1402 This function can indicate there are no more sort records by leaving
1403 point at the end of the buffer.
1406 @var{endrecfun} is called with point within a record. It moves point to
1407 the end of the record.
1410 @var{startkeyfun} is called to move point from the start of a record to
1411 the start of the sort key. This argument is optional; if it is omitted,
1412 the whole record is the sort key. If supplied, the function should
1413 either return a non-@code{nil} value to be used as the sort key, or
1414 return @code{nil} to indicate that the sort key is in the buffer
1415 starting at point. In the latter case, @var{endkeyfun} is called to
1416 find the end of the sort key.
1419 @var{endkeyfun} is called to move point from the start of the sort key
1420 to the end of the sort key. This argument is optional. If
1421 @var{startkeyfun} returns @code{nil} and this argument is omitted (or
1422 @code{nil}), then the sort key extends to the end of the record. There
1423 is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1424 non-@code{nil} value.
1427 As an example of @code{sort-subr}, here is the complete function
1428 definition for @code{sort-lines}:
1432 ;; @r{Note that the first two lines of doc string}
1433 ;; @r{are effectively one line when viewed by a user.}
1434 (defun sort-lines (reverse beg end)
1435 "Sort lines in region alphabetically.
1436 Called from a program, there are three arguments:
1439 REVERSE (non-nil means reverse order),
1440 and BEG and END (the region to sort)."
1441 (interactive "P\nr")
1443 (narrow-to-region beg end)
1444 (goto-char (point-min))
1451 Here @code{forward-line} moves point to the start of the next record,
1452 and @code{end-of-line} moves point to the end of record. We do not pass
1453 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
1454 record is used as the sort key.
1456 The @code{sort-paragraphs} function is very much the same, except that
1457 its @code{sort-subr} call looks like this:
1464 (skip-chars-forward "\n \t\f")))
1470 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
1471 This command sorts the region between @var{start} and @var{end}
1472 alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
1473 If @var{reverse} is a negative integer, then sorting is in reverse
1476 Alphabetical sorting means that two sort keys are compared by
1477 comparing the first characters of each, the second characters of each,
1478 and so on. If a mismatch is found, it means that the sort keys are
1479 unequal; the sort key whose character is less at the point of first
1480 mismatch is the lesser sort key. The individual characters are compared
1481 according to their numerical values. Since Emacs uses the @sc{ASCII}
1482 character set, the ordering in that set determines alphabetical order.
1483 @c version 19 change
1485 The value of the @var{record-regexp} argument specifies how to divide
1486 the buffer into sort records. At the end of each record, a search is
1487 done for this regular expression, and the text that matches it is the
1488 next record. For example, the regular expression @samp{^.+$}, which
1489 matches lines with at least one character besides a newline, would make
1490 each such line into a sort record. @xref{Regular Expressions}, for a
1491 description of the syntax and meaning of regular expressions.
1493 The value of the @var{key-regexp} argument specifies what part of each
1494 record is the sort key. The @var{key-regexp} could match the whole
1495 record, or only a part. In the latter case, the rest of the record has
1496 no effect on the sorted order of records, but it is carried along when
1497 the record moves to its new position.
1499 The @var{key-regexp} argument can refer to the text matched by a
1500 subexpression of @var{record-regexp}, or it can be a regular expression
1503 If @var{key-regexp} is:
1506 @item @samp{\@var{digit}}
1507 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
1508 grouping in @var{record-regexp} is the sort key.
1511 then the whole record is the sort key.
1513 @item a regular expression
1514 then @code{sort-regexp-fields} searches for a match for the regular
1515 expression within the record. If such a match is found, it is the sort
1516 key. If there is no match for @var{key-regexp} within a record then
1517 that record is ignored, which means its position in the buffer is not
1518 changed. (The other records may move around it.)
1521 For example, if you plan to sort all the lines in the region by the
1522 first word on each line starting with the letter @samp{f}, you should
1523 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
1524 @samp{\<f\w*\>}. The resulting expression looks like this:
1528 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
1534 If you call @code{sort-regexp-fields} interactively, it prompts for
1535 @var{record-regexp} and @var{key-regexp} in the minibuffer.
1538 @deffn Command sort-lines reverse start end
1539 This command alphabetically sorts lines in the region between
1540 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1541 is in reverse order.
1544 @deffn Command sort-paragraphs reverse start end
1545 This command alphabetically sorts paragraphs in the region between
1546 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1547 is in reverse order.
1550 @deffn Command sort-pages reverse start end
1551 This command alphabetically sorts pages in the region between
1552 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
1553 is in reverse order.
1556 @deffn Command sort-fields field start end
1557 This command sorts lines in the region between @var{start} and
1558 @var{end}, comparing them alphabetically by the @var{field}th field
1559 of each line. Fields are separated by whitespace and numbered starting
1560 from 1. If @var{field} is negative, sorting is by the
1561 @w{@minus{}@var{field}th} field from the end of the line. This command
1562 is useful for sorting tables.
1565 @deffn Command sort-numeric-fields field start end
1566 This command sorts lines in the region between @var{start} and
1567 @var{end}, comparing them numerically by the @var{field}th field of each
1568 line. The specified field must contain a number in each line of the
1569 region. Fields are separated by whitespace and numbered starting from
1570 1. If @var{field} is negative, sorting is by the
1571 @w{@minus{}@var{field}th} field from the end of the line. This command
1572 is useful for sorting tables.
1575 @deffn Command sort-columns reverse &optional beg end
1576 This command sorts the lines in the region between @var{beg} and
1577 @var{end}, comparing them alphabetically by a certain range of columns.
1578 The column positions of @var{beg} and @var{end} bound the range of
1581 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
1583 One unusual thing about this command is that the entire line
1584 containing position @var{beg}, and the entire line containing position
1585 @var{end}, are included in the region sorted.
1587 Note that @code{sort-columns} uses the @code{sort} utility program,
1588 and so cannot work properly on text containing tab characters. Use
1589 @kbd{M-x @code{untabify}} to convert tabs to spaces before sorting.
1593 @comment node-name, next, previous, up
1594 @section Counting Columns
1596 @cindex counting columns
1597 @cindex horizontal position
1599 The column functions convert between a character position (counting
1600 characters from the beginning of the buffer) and a column position
1601 (counting screen characters from the beginning of a line).
1603 A character counts according to the number of columns it occupies on
1604 the screen. This means control characters count as occupying 2 or 4
1605 columns, depending upon the value of @code{ctl-arrow}, and tabs count as
1606 occupying a number of columns that depends on the value of
1607 @code{tab-width} and on the column where the tab begins. @xref{Usual Display}.
1609 Column number computations ignore the width of the window and the
1610 amount of horizontal scrolling. Consequently, a column value can be
1611 arbitrarily high. The first (or leftmost) column is numbered 0.
1613 @defun current-column
1614 This function returns the horizontal position of point, measured in
1615 columns, counting from 0 at the left margin. The column position is the
1616 sum of the widths of all the displayed representations of the characters
1617 between the start of the current line and point.
1619 For an example of using @code{current-column}, see the description of
1620 @code{count-lines} in @ref{Text Lines}.
1623 @defun move-to-column column &optional force
1624 This function moves point to @var{column} in the current line. The
1625 calculation of @var{column} takes into account the widths of the
1626 displayed representations of the characters between the start of the
1629 If column @var{column} is beyond the end of the line, point moves to the
1630 end of the line. If @var{column} is negative, point moves to the
1631 beginning of the line.
1633 If it is impossible to move to column @var{column} because that is in
1634 the middle of a multicolumn character such as a tab, point moves to the
1635 end of that character. However, if @var{force} is non-@code{nil}, and
1636 @var{column} is in the middle of a tab, then @code{move-to-column}
1637 converts the tab into spaces so that it can move precisely to column
1638 @var{column}. Other multicolumn characters can cause anomalies despite
1639 @var{force}, since there is no way to split them.
1641 The argument @var{force} also has an effect if the line isn't long
1642 enough to reach column @var{column}; in that case, it says to add
1643 whitespace at the end of the line to reach that column.
1645 If @var{column} is not an integer, an error is signaled.
1647 The return value is the column number actually moved to.
1651 @section Indentation
1654 The indentation functions are used to examine, move to, and change
1655 whitespace that is at the beginning of a line. Some of the functions
1656 can also change whitespace elsewhere on a line. Columns and indentation
1657 count from zero at the left margin.
1660 * Primitive Indent:: Functions used to count and insert indentation.
1661 * Mode-Specific Indent:: Customize indentation for different modes.
1662 * Region Indent:: Indent all the lines in a region.
1663 * Relative Indent:: Indent the current line based on previous lines.
1664 * Indent Tabs:: Adjustable, typewriter-like tab stops.
1665 * Motion by Indent:: Move to first non-blank character.
1668 @node Primitive Indent
1669 @subsection Indentation Primitives
1671 This section describes the primitive functions used to count and
1672 insert indentation. The functions in the following sections use these
1675 @defun current-indentation
1676 @comment !!Type Primitive Function
1677 @comment !!SourceFile indent.c
1678 This function returns the indentation of the current line, which is
1679 the horizontal position of the first nonblank character. If the
1680 contents are entirely blank, then this is the horizontal position of the
1684 @deffn Command indent-to column &optional minimum
1685 @comment !!Type Primitive Function
1686 @comment !!SourceFile indent.c
1687 This function indents from point with tabs and spaces until @var{column}
1688 is reached. If @var{minimum} is specified and non-@code{nil}, then at
1689 least that many spaces are inserted even if this requires going beyond
1690 @var{column}. Otherwise the function does nothing if point is already
1691 beyond @var{column}. The value is the column at which the inserted
1695 @defopt indent-tabs-mode
1696 @comment !!SourceFile indent.c
1697 If this variable is non-@code{nil}, indentation functions can insert
1698 tabs as well as spaces. Otherwise, they insert only spaces. Setting
1699 this variable automatically makes it local to the current buffer.
1702 @node Mode-Specific Indent
1703 @subsection Indentation Controlled by Major Mode
1705 An important function of each major mode is to customize the @key{TAB}
1706 key to indent properly for the language being edited. This section
1707 describes the mechanism of the @key{TAB} key and how to control it.
1708 The functions in this section return unpredictable values.
1710 @defvar indent-line-function
1711 This variable's value is the function to be used by @key{TAB} (and
1712 various commands) to indent the current line. The command
1713 @code{indent-according-to-mode} does no more than call this function.
1715 In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C
1716 mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
1717 In Fundamental mode, Text mode, and many other modes with no standard
1718 for indentation, the value is @code{indent-to-left-margin} (which is the
1722 @deffn Command indent-according-to-mode
1723 This command calls the function in @code{indent-line-function} to
1724 indent the current line in a way appropriate for the current major mode.
1727 @deffn Command indent-for-tab-command
1728 This command calls the function in @code{indent-line-function} to indent
1729 the current line; except that if that function is
1730 @code{indent-to-left-margin}, it calls @code{insert-tab} instead. (That
1731 is a trivial command that inserts a tab character.)
1734 @deffn Command newline-and-indent
1735 @comment !!SourceFile simple.el
1736 This function inserts a newline, then indents the new line (the one
1737 following the newline just inserted) according to the major mode.
1739 It does indentation by calling the current @code{indent-line-function}.
1740 In programming language modes, this is the same thing @key{TAB} does,
1741 but in some text modes, where @key{TAB} inserts a tab,
1742 @code{newline-and-indent} indents to the column specified by
1746 @deffn Command reindent-then-newline-and-indent
1747 @comment !!SourceFile simple.el
1748 This command reindents the current line, inserts a newline at point,
1749 and then reindents the new line (the one following the newline just
1752 This command does indentation on both lines according to the current
1753 major mode, by calling the current value of @code{indent-line-function}.
1754 In programming language modes, this is the same thing @key{TAB} does,
1755 but in some text modes, where @key{TAB} inserts a tab,
1756 @code{reindent-then-newline-and-indent} indents to the column specified
1757 by @code{left-margin}.
1761 @subsection Indenting an Entire Region
1763 This section describes commands that indent all the lines in the
1764 region. They return unpredictable values.
1766 @deffn Command indent-region start end to-column
1767 This command indents each nonblank line starting between @var{start}
1768 (inclusive) and @var{end} (exclusive). If @var{to-column} is
1769 @code{nil}, @code{indent-region} indents each nonblank line by calling
1770 the current mode's indentation function, the value of
1771 @code{indent-line-function}.
1773 If @var{to-column} is non-@code{nil}, it should be an integer
1774 specifying the number of columns of indentation; then this function
1775 gives each line exactly that much indentation, by either adding or
1776 deleting whitespace.
1778 If there is a fill prefix, @code{indent-region} indents each line
1779 by making it start with the fill prefix.
1782 @defvar indent-region-function
1783 The value of this variable is a function that can be used by
1784 @code{indent-region} as a short cut. You should design the function so
1785 that it will produce the same results as indenting the lines of the
1786 region one by one, but presumably faster.
1788 If the value is @code{nil}, there is no short cut, and
1789 @code{indent-region} actually works line by line.
1791 A short-cut function is useful in modes such as C mode and Lisp mode,
1792 where the @code{indent-line-function} must scan from the beginning of
1793 the function definition: applying it to each line would be quadratic in
1794 time. The short cut can update the scan information as it moves through
1795 the lines indenting them; this takes linear time. In a mode where
1796 indenting a line individually is fast, there is no need for a short cut.
1798 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
1799 a different meaning and does not use this variable.
1802 @deffn Command indent-rigidly start end count
1803 @comment !!SourceFile indent.el
1804 This command indents all lines starting between @var{start}
1805 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
1806 This ``preserves the shape'' of the affected region, moving it as a
1807 rigid unit. Consequently, this command is useful not only for indenting
1808 regions of unindented text, but also for indenting regions of formatted
1811 For example, if @var{count} is 3, this command adds 3 columns of
1812 indentation to each of the lines beginning in the region specified.
1814 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
1815 @code{indent-rigidly} to indent the text copied from the message being
1819 @defun indent-code-rigidly start end columns &optional nochange-regexp
1820 This is like @code{indent-rigidly}, except that it doesn't alter lines
1821 that start within strings or comments.
1823 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
1824 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
1827 @node Relative Indent
1828 @subsection Indentation Relative to Previous Lines
1830 This section describes two commands that indent the current line
1831 based on the contents of previous lines.
1833 @deffn Command indent-relative &optional unindented-ok
1834 This command inserts whitespace at point, extending to the same
1835 column as the next @dfn{indent point} of the previous nonblank line. An
1836 indent point is a non-whitespace character following whitespace. The
1837 next indent point is the first one at a column greater than the current
1838 column of point. For example, if point is underneath and to the left of
1839 the first non-blank character of a line of text, it moves to that column
1840 by inserting whitespace.
1842 If the previous nonblank line has no next indent point (i.e., none at a
1843 great enough column position), @code{indent-relative} either does
1844 nothing (if @var{unindented-ok} is non-@code{nil}) or calls
1845 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right
1846 of the last column of a short line of text, this command ordinarily
1847 moves point to the next tab stop by inserting whitespace.
1849 The return value of @code{indent-relative} is unpredictable.
1851 In the following example, point is at the beginning of the second
1856 This line is indented twelve spaces.
1857 @point{}The quick brown fox jumped.
1862 Evaluation of the expression @code{(indent-relative nil)} produces the
1867 This line is indented twelve spaces.
1868 @point{}The quick brown fox jumped.
1872 In this example, point is between the @samp{m} and @samp{p} of
1877 This line is indented twelve spaces.
1878 The quick brown fox jum@point{}ped.
1883 Evaluation of the expression @code{(indent-relative nil)} produces the
1888 This line is indented twelve spaces.
1889 The quick brown fox jum @point{}ped.
1894 @deffn Command indent-relative-maybe
1895 @comment !!SourceFile indent.el
1896 This command indents the current line like the previous nonblank line.
1897 It calls @code{indent-relative} with @code{t} as the @var{unindented-ok}
1898 argument. The return value is unpredictable.
1900 If the previous nonblank line has no indent points beyond the current
1901 column, this command does nothing.
1905 @subsection Adjustable ``Tab Stops''
1906 @cindex tabs stops for indentation
1908 This section explains the mechanism for user-specified ``tab stops''
1909 and the mechanisms that use and set them. The name ``tab stops'' is
1910 used because the feature is similar to that of the tab stops on a
1911 typewriter. The feature works by inserting an appropriate number of
1912 spaces and tab characters to reach the next tab stop column; it does not
1913 affect the display of tab characters in the buffer (@pxref{Usual
1914 Display}). Note that the @key{TAB} character as input uses this tab
1915 stop feature only in a few major modes, such as Text mode.
1917 @deffn Command tab-to-tab-stop
1918 This command inserts spaces or tabs up to the next tab stop column
1919 defined by @code{tab-stop-list}. It searches the list for an element
1920 greater than the current column number, and uses that element as the
1921 column to indent to. It does nothing if no such element is found.
1924 @defopt tab-stop-list
1925 This variable is the list of tab stop columns used by
1926 @code{tab-to-tab-stops}. The elements should be integers in increasing
1927 order. The tab stop columns need not be evenly spaced.
1929 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
1933 @node Motion by Indent
1934 @subsection Indentation-Based Motion Commands
1936 These commands, primarily for interactive use, act based on the
1937 indentation in the text.
1939 @deffn Command back-to-indentation
1940 @comment !!SourceFile simple.el
1941 This command moves point to the first non-whitespace character in the
1942 current line (which is the line in which point is located). It returns
1946 @deffn Command backward-to-indentation arg
1947 @comment !!SourceFile simple.el
1948 This command moves point backward @var{arg} lines and then to the
1949 first nonblank character on that line. It returns @code{nil}.
1952 @deffn Command forward-to-indentation arg
1953 @comment !!SourceFile simple.el
1954 This command moves point forward @var{arg} lines and then to the first
1955 nonblank character on that line. It returns @code{nil}.
1959 @section Case Changes
1960 @cindex case changes
1962 The case change commands described here work on text in the current
1963 buffer. @xref{Character Case}, for case conversion commands that work
1964 on strings and characters. @xref{Case Tables}, for how to customize
1965 which characters are upper or lower case and how to convert them.
1967 @deffn Command capitalize-region start end
1968 This function capitalizes all words in the region defined by
1969 @var{start} and @var{end}. To capitalize means to convert each word's
1970 first character to upper case and convert the rest of each word to lower
1971 case. The function returns @code{nil}.
1973 If one end of the region is in the middle of a word, the part of the
1974 word within the region is treated as an entire word.
1976 When @code{capitalize-region} is called interactively, @var{start} and
1977 @var{end} are point and the mark, with the smallest first.
1981 ---------- Buffer: foo ----------
1982 This is the contents of the 5th foo.
1983 ---------- Buffer: foo ----------
1987 (capitalize-region 1 44)
1990 ---------- Buffer: foo ----------
1991 This Is The Contents Of The 5th Foo.
1992 ---------- Buffer: foo ----------
1997 @deffn Command downcase-region start end
1998 This function converts all of the letters in the region defined by
1999 @var{start} and @var{end} to lower case. The function returns
2002 When @code{downcase-region} is called interactively, @var{start} and
2003 @var{end} are point and the mark, with the smallest first.
2006 @deffn Command upcase-region start end
2007 This function converts all of the letters in the region defined by
2008 @var{start} and @var{end} to upper case. The function returns
2011 When @code{upcase-region} is called interactively, @var{start} and
2012 @var{end} are point and the mark, with the smallest first.
2015 @deffn Command capitalize-word count
2016 This function capitalizes @var{count} words after point, moving point
2017 over as it does. To capitalize means to convert each word's first
2018 character to upper case and convert the rest of each word to lower case.
2019 If @var{count} is negative, the function capitalizes the
2020 @minus{}@var{count} previous words but does not move point. The value
2023 If point is in the middle of a word, the part of the word before point
2024 is ignored when moving forward. The rest is treated as an entire word.
2026 When @code{capitalize-word} is called interactively, @var{count} is
2027 set to the numeric prefix argument.
2030 @deffn Command downcase-word count
2031 This function converts the @var{count} words after point to all lower
2032 case, moving point over as it does. If @var{count} is negative, it
2033 converts the @minus{}@var{count} previous words but does not move point.
2034 The value is @code{nil}.
2036 When @code{downcase-word} is called interactively, @var{count} is set
2037 to the numeric prefix argument.
2040 @deffn Command upcase-word count
2041 This function converts the @var{count} words after point to all upper
2042 case, moving point over as it does. If @var{count} is negative, it
2043 converts the @minus{}@var{count} previous words but does not move point.
2044 The value is @code{nil}.
2046 When @code{upcase-word} is called interactively, @var{count} is set to
2047 the numeric prefix argument.
2050 @node Text Properties
2051 @section Text Properties
2052 @cindex text properties
2053 @cindex attributes of text
2054 @cindex properties of text
2056 Text properties are an alternative interface to extents
2057 (@pxref{Extents}), and are built on top of them. They are useful when
2058 you want to view textual properties as being attached to the characters
2059 themselves rather than to intervals of characters. The text property
2060 interface is compatible with FSF Emacs.
2062 Each character position in a buffer or a string can have a @dfn{text
2063 property list}, much like the property list of a symbol (@pxref{Property
2064 Lists}). The properties belong to a particular character at a
2065 particular place, such as, the letter @samp{T} at the beginning of this
2066 sentence or the first @samp{o} in @samp{foo}---if the same character
2067 occurs in two different places, the two occurrences generally have
2068 different properties.
2070 Each property has a name and a value. Both of these can be any Lisp
2071 object, but the name is normally a symbol. The usual way to access the
2072 property list is to specify a name and ask what value corresponds to it.
2075 If a character has a @code{category} property, we call it the
2076 @dfn{category} of the character. It should be a symbol. The properties
2077 of the symbol serve as defaults for the properties of the character.
2079 Note that FSF Emacs also looks at the @code{category} property to find
2080 defaults for text properties. We consider this too bogus to implement.
2082 Copying text between strings and buffers preserves the properties
2083 along with the characters; this includes such diverse functions as
2084 @code{substring}, @code{insert}, and @code{buffer-substring}.
2087 * Examining Properties:: Looking at the properties of one character.
2088 * Changing Properties:: Setting the properties of a range of text.
2089 * Property Search:: Searching for where a property changes value.
2090 * Special Properties:: Particular properties with special meanings.
2091 * Saving Properties:: Saving text properties in files, and reading
2095 @node Examining Properties
2096 @subsection Examining Text Properties
2098 The simplest way to examine text properties is to ask for the value of
2099 a particular property of a particular character. For that, use
2100 @code{get-text-property}. Use @code{text-properties-at} to get the
2101 entire property list of a character. @xref{Property Search}, for
2102 functions to examine the properties of a number of characters at once.
2104 These functions handle both strings and buffers. (Keep in mind that
2105 positions in a string start from 0, whereas positions in a buffer start
2108 @defun get-text-property pos prop &optional object
2109 This function returns the value of the @var{prop} property of the
2110 character after position @var{pos} in @var{object} (a buffer or string).
2111 The argument @var{object} is optional and defaults to the current
2113 @ignore @c Bogus as hell!
2114 If there is no @var{prop} property strictly speaking, but the character
2115 has a category that is a symbol, then @code{get-text-property} returns
2116 the @var{prop} property of that symbol.
2120 @defun get-char-property pos prop &optional object
2121 This function is like @code{get-text-property}, except that it checks
2122 all extents, not just text-property extents.
2124 @ignore Does not apply in XEmacs
2125 The argument @var{object} may be a string, a buffer, or a window. If it
2126 is a window, then the buffer displayed in that window is used for text
2127 properties and overlays, but only the overlays active for that window
2128 are considered. If @var{object} is a buffer, then all overlays in that
2129 buffer are considered, as well as text properties. If @var{object} is a
2130 string, only text properties are considered, since strings never have
2135 @defun text-properties-at position &optional object
2136 This function returns the entire property list of the character at
2137 @var{position} in the string or buffer @var{object}. If @var{object} is
2138 @code{nil}, it defaults to the current buffer.
2141 @defvar default-text-properties
2142 This variable holds a property list giving default values for text
2143 properties. Whenever a character does not specify a value for a
2144 property, the value stored in this list is used instead. Here is
2148 (setq default-text-properties '(foo 69))
2149 ;; @r{Make sure character 1 has no properties of its own.}
2150 (set-text-properties 1 2 nil)
2151 ;; @r{What we get, when we ask, is the default value.}
2152 (get-text-property 1 'foo)
2157 @node Changing Properties
2158 @subsection Changing Text Properties
2160 The primitives for changing properties apply to a specified range of
2161 text. The function @code{set-text-properties} (see end of section) sets
2162 the entire property list of the text in that range; more often, it is
2163 useful to add, change, or delete just certain properties specified by
2166 Since text properties are considered part of the buffer's contents, and
2167 can affect how the buffer looks on the screen, any change in the text
2168 properties is considered a buffer modification. Buffer text property
2169 changes are undoable (@pxref{Undo}).
2171 @defun put-text-property start end prop value &optional object
2172 This function sets the @var{prop} property to @var{value} for the text
2173 between @var{start} and @var{end} in the string or buffer @var{object}.
2174 If @var{object} is @code{nil}, it defaults to the current buffer.
2177 @defun add-text-properties start end props &optional object
2178 This function modifies the text properties for the text between
2179 @var{start} and @var{end} in the string or buffer @var{object}. If
2180 @var{object} is @code{nil}, it defaults to the current buffer.
2182 The argument @var{props} specifies which properties to change. It
2183 should have the form of a property list (@pxref{Property Lists}): a list
2184 whose elements include the property names followed alternately by the
2185 corresponding values.
2187 The return value is @code{t} if the function actually changed some
2188 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2189 its values agree with those in the text).
2191 For example, here is how to set the @code{comment} and @code{face}
2192 properties of a range of text:
2195 (add-text-properties @var{start} @var{end}
2196 '(comment t face highlight))
2200 @defun remove-text-properties start end props &optional object
2201 This function deletes specified text properties from the text between
2202 @var{start} and @var{end} in the string or buffer @var{object}. If
2203 @var{object} is @code{nil}, it defaults to the current buffer.
2205 The argument @var{props} specifies which properties to delete. It
2206 should have the form of a property list (@pxref{Property Lists}): a list
2207 whose elements are property names alternating with corresponding values.
2208 But only the names matter---the values that accompany them are ignored.
2209 For example, here's how to remove the @code{face} property.
2212 (remove-text-properties @var{start} @var{end} '(face nil))
2215 The return value is @code{t} if the function actually changed some
2216 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2217 if no character in the specified text had any of those properties).
2220 @defun set-text-properties start end props &optional object
2221 This function completely replaces the text property list for the text
2222 between @var{start} and @var{end} in the string or buffer @var{object}.
2223 If @var{object} is @code{nil}, it defaults to the current buffer.
2225 The argument @var{props} is the new property list. It should be a list
2226 whose elements are property names alternating with corresponding values.
2228 After @code{set-text-properties} returns, all the characters in the
2229 specified range have identical properties.
2231 If @var{props} is @code{nil}, the effect is to get rid of all properties
2232 from the specified range of text. Here's an example:
2235 (set-text-properties @var{start} @var{end} nil)
2239 See also the function @code{buffer-substring-without-properties}
2240 (@pxref{Buffer Contents}) which copies text from the buffer
2241 but does not copy its properties.
2243 @node Property Search
2244 @subsection Property Search Functions
2246 In typical use of text properties, most of the time several or many
2247 consecutive characters have the same value for a property. Rather than
2248 writing your programs to examine characters one by one, it is much
2249 faster to process chunks of text that have the same property value.
2251 Here are functions you can use to do this. They use @code{eq} for
2252 comparing property values. In all cases, @var{object} defaults to the
2255 For high performance, it's very important to use the @var{limit}
2256 argument to these functions, especially the ones that search for a
2257 single property---otherwise, they may spend a long time scanning to the
2258 end of the buffer, if the property you are interested in does not change.
2260 Remember that a position is always between two characters; the position
2261 returned by these functions is between two characters with different
2264 @defun next-property-change pos &optional object limit
2265 The function scans the text forward from position @var{pos} in the
2266 string or buffer @var{object} till it finds a change in some text
2267 property, then returns the position of the change. In other words, it
2268 returns the position of the first character beyond @var{pos} whose
2269 properties are not identical to those of the character just after
2272 If @var{limit} is non-@code{nil}, then the scan ends at position
2273 @var{limit}. If there is no property change before that point,
2274 @code{next-property-change} returns @var{limit}.
2276 The value is @code{nil} if the properties remain unchanged all the way
2277 to the end of @var{object} and @var{limit} is @code{nil}. If the value
2278 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
2279 The value equals @var{pos} only when @var{limit} equals @var{pos}.
2281 Here is an example of how to scan the buffer by chunks of text within
2282 which all properties are constant:
2286 (let ((plist (text-properties-at (point)))
2288 (or (next-property-change (point) (current-buffer))
2290 @r{Process text from point to @var{next-change}@dots{}}
2291 (goto-char next-change)))
2295 @defun next-single-property-change pos prop &optional object limit
2296 The function scans the text forward from position @var{pos} in the
2297 string or buffer @var{object} till it finds a change in the @var{prop}
2298 property, then returns the position of the change. In other words, it
2299 returns the position of the first character beyond @var{pos} whose
2300 @var{prop} property differs from that of the character just after
2303 If @var{limit} is non-@code{nil}, then the scan ends at position
2304 @var{limit}. If there is no property change before that point,
2305 @code{next-single-property-change} returns @var{limit}.
2307 The value is @code{nil} if the property remains unchanged all the way to
2308 the end of @var{object} and @var{limit} is @code{nil}. If the value is
2309 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
2310 equals @var{pos} only if @var{limit} equals @var{pos}.
2313 @defun previous-property-change pos &optional object limit
2314 This is like @code{next-property-change}, but scans back from @var{pos}
2315 instead of forward. If the value is non-@code{nil}, it is a position
2316 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
2320 @defun previous-single-property-change pos prop &optional object limit
2321 This is like @code{next-single-property-change}, but scans back from
2322 @var{pos} instead of forward. If the value is non-@code{nil}, it is a
2323 position less than or equal to @var{pos}; it equals @var{pos} only if
2324 @var{limit} equals @var{pos}.
2327 @defun text-property-any start end prop value &optional object
2328 This function returns non-@code{nil} if at least one character between
2329 @var{start} and @var{end} has a property @var{prop} whose value is
2330 @var{value}. More precisely, it returns the position of the first such
2331 character. Otherwise, it returns @code{nil}.
2333 The optional fifth argument, @var{object}, specifies the string or
2334 buffer to scan. Positions are relative to @var{object}. The default
2335 for @var{object} is the current buffer.
2338 @defun text-property-not-all start end prop value &optional object
2339 This function returns non-@code{nil} if at least one character between
2340 @var{start} and @var{end} has a property @var{prop} whose value differs
2341 from @var{value}. More precisely, it returns the position of the
2342 first such character. Otherwise, it returns @code{nil}.
2344 The optional fifth argument, @var{object}, specifies the string or
2345 buffer to scan. Positions are relative to @var{object}. The default
2346 for @var{object} is the current buffer.
2349 @node Special Properties
2350 @subsection Properties with Special Meanings
2352 The predefined properties are the same as those for extents.
2353 @xref{Extent Properties}.
2355 @ignore Changed in XEmacs
2356 (deleted section describing FSF Emacs special text properties)
2359 @node Saving Properties
2360 @subsection Saving Text Properties in Files
2361 @cindex text properties in files
2362 @cindex saving text properties
2364 You can save text properties in files, and restore text properties
2365 when inserting the files, using these two hooks:
2367 @defvar write-region-annotate-functions
2368 This variable's value is a list of functions for @code{write-region} to
2369 run to encode text properties in some fashion as annotations to the text
2370 being written in the file. @xref{Writing to Files}.
2372 Each function in the list is called with two arguments: the start and
2373 end of the region to be written. These functions should not alter the
2374 contents of the buffer. Instead, they should return lists indicating
2375 annotations to write in the file in addition to the text in the
2378 Each function should return a list of elements of the form
2379 @code{(@var{position} . @var{string})}, where @var{position} is an
2380 integer specifying the relative position in the text to be written, and
2381 @var{string} is the annotation to add there.
2383 Each list returned by one of these functions must be already sorted in
2384 increasing order by @var{position}. If there is more than one function,
2385 @code{write-region} merges the lists destructively into one sorted list.
2387 When @code{write-region} actually writes the text from the buffer to the
2388 file, it intermixes the specified annotations at the corresponding
2389 positions. All this takes place without modifying the buffer.
2392 @defvar after-insert-file-functions
2393 This variable holds a list of functions for @code{insert-file-contents}
2394 to call after inserting a file's contents. These functions should scan
2395 the inserted text for annotations, and convert them to the text
2396 properties they stand for.
2398 Each function receives one argument, the length of the inserted text;
2399 point indicates the start of that text. The function should scan that
2400 text for annotations, delete them, and create the text properties that
2401 the annotations specify. The function should return the updated length
2402 of the inserted text, as it stands after those changes. The value
2403 returned by one function becomes the argument to the next function.
2405 These functions should always return with point at the beginning of
2408 The intended use of @code{after-insert-file-functions} is for converting
2409 some sort of textual annotations into actual text properties. But other
2410 uses may be possible.
2413 We invite users to write Lisp programs to store and retrieve text
2414 properties in files, using these hooks, and thus to experiment with
2415 various data formats and find good ones. Eventually we hope users
2416 will produce good, general extensions we can install in Emacs.
2418 We suggest not trying to handle arbitrary Lisp objects as property
2419 names or property values---because a program that general is probably
2420 difficult to write, and slow. Instead, choose a set of possible data
2421 types that are reasonably flexible, and not too hard to encode.
2423 @xref{Format Conversion}, for a related feature.
2426 @section Substituting for a Character Code
2428 The following functions replace characters within a specified region
2429 based on their character codes.
2431 @defun subst-char-in-region start end old-char new-char &optional noundo
2432 @cindex replace characters
2433 This function replaces all occurrences of the character @var{old-char}
2434 with the character @var{new-char} in the region of the current buffer
2435 defined by @var{start} and @var{end}.
2437 @cindex Outline mode
2438 @cindex undo avoidance
2439 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
2440 not record the change for undo and does not mark the buffer as modified.
2441 This feature is used for controlling selective display (@pxref{Selective
2444 @code{subst-char-in-region} does not move point and returns
2449 ---------- Buffer: foo ----------
2450 This is the contents of the buffer before.
2451 ---------- Buffer: foo ----------
2455 (subst-char-in-region 1 20 ?i ?X)
2458 ---------- Buffer: foo ----------
2459 ThXs Xs the contents of the buffer before.
2460 ---------- Buffer: foo ----------
2465 @defun translate-region start end table
2466 This function applies a translation table to the characters in the
2467 buffer between positions @var{start} and @var{end}. The translation
2468 table @var{table} can be either a string, a vector, or a char-table.
2470 If @var{table} is a string, its @var{n}th element is the mapping for the
2471 character with code @var{n}.
2473 If @var{table} is a vector, its @var{n}th element is the mapping for
2474 character with code @var{n}. Legal mappings are characters, strings, or
2475 @code{nil} (meaning don't replace.)
2477 If @var{table} is a char-table, its elements describe the mapping
2478 between characters and their replacements. The char-table should be of
2479 type @code{char} or @code{generic}.
2481 When the @var{table} is a string or vector and its length is less than
2482 the total number of characters (256 without Mule), any characters with
2483 codes larger than the length of @var{table} are not altered by the
2486 The return value of @code{translate-region} is the number of
2487 characters that were actually changed by the translation. This does
2488 not count characters that were mapped into themselves in the
2491 @strong{NOTE}: Prior to XEmacs 21.2, the @var{table} argument was
2492 allowed only to be a string. This is still the case in FSF Emacs.
2494 The following example creates a char-table that is passed to
2495 @code{translate-region}, which translates character @samp{a} to
2496 @samp{the letter a}, removes character @samp{b}, and translates
2497 character @samp{c} to newline.
2501 ---------- Buffer: foo ----------
2502 Here is a sentence in the buffer.
2503 ---------- Buffer: foo ----------
2507 (let ((table (make-char-table 'generic)))
2508 (put-char-table ?a "the letter a" table)
2509 (put-char-table ?b "" table)
2510 (put-char-table ?c ?\n table)
2511 (translate-region (point-min) (point-max) table))
2514 ---------- Buffer: foo ----------
2515 Here is the letter a senten
2517 ---------- Buffer: foo ----------
2526 A register is a sort of variable used in XEmacs editing that can hold a
2527 marker, a string, a rectangle, a window configuration (of one frame), or
2528 a frame configuration (of all frames). Each register is named by a
2529 single character. All characters, including control and meta characters
2530 (but with the exception of @kbd{C-g}), can be used to name registers.
2531 Thus, there are 255 possible registers. A register is designated in
2532 Emacs Lisp by a character that is its name.
2534 The functions in this section return unpredictable values unless
2536 @c Will change in version 19
2538 @defvar register-alist
2539 This variable is an alist of elements of the form @code{(@var{name} .
2540 @var{contents})}. Normally, there is one element for each XEmacs
2541 register that has been used.
2543 The object @var{name} is a character (an integer) identifying the
2544 register. The object @var{contents} is a string, marker, or list
2545 representing the register contents. A string represents text stored in
2546 the register. A marker represents a position. A list represents a
2547 rectangle; its elements are strings, one per line of the rectangle.
2550 @defun get-register reg
2551 This function returns the contents of the register
2552 @var{reg}, or @code{nil} if it has no contents.
2555 @defun set-register reg value
2556 This function sets the contents of register @var{reg} to @var{value}.
2557 A register can be set to any value, but the other register functions
2558 expect only certain data types. The return value is @var{value}.
2561 @deffn Command view-register reg
2562 This command displays what is contained in register @var{reg}.
2566 @deffn Command point-to-register reg
2567 This command stores both the current location of point and the current
2568 buffer in register @var{reg} as a marker.
2571 @deffn Command jump-to-register reg
2572 @deffnx Command register-to-point reg
2573 @comment !!SourceFile register.el
2574 This command restores the status recorded in register @var{reg}.
2576 If @var{reg} contains a marker, it moves point to the position stored in
2577 the marker. Since both the buffer and the location within the buffer
2578 are stored by the @code{point-to-register} function, this command can
2579 switch you to another buffer.
2581 If @var{reg} contains a window configuration or a frame configuration.
2582 @code{jump-to-register} restores that configuration.
2586 @deffn Command insert-register reg &optional beforep
2587 This command inserts contents of register @var{reg} into the current
2590 Normally, this command puts point before the inserted text, and the
2591 mark after it. However, if the optional second argument @var{beforep}
2592 is non-@code{nil}, it puts the mark before and point after.
2593 You can pass a non-@code{nil} second argument @var{beforep} to this
2594 function interactively by supplying any prefix argument.
2596 If the register contains a rectangle, then the rectangle is inserted
2597 with its upper left corner at point. This means that text is inserted
2598 in the current line and underneath it on successive lines.
2600 If the register contains something other than saved text (a string) or
2601 a rectangle (a list), currently useless things happen. This may be
2602 changed in the future.
2606 @deffn Command copy-to-register reg start end &optional delete-flag
2607 This command copies the region from @var{start} to @var{end} into
2608 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
2609 the region from the buffer after copying it into the register.
2612 @deffn Command prepend-to-register reg start end &optional delete-flag
2613 This command prepends the region from @var{start} to @var{end} into
2614 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
2615 the region from the buffer after copying it to the register.
2618 @deffn Command append-to-register reg start end &optional delete-flag
2619 This command appends the region from @var{start} to @var{end} to the
2620 text already in register @var{reg}. If @var{delete-flag} is
2621 non-@code{nil}, it deletes the region from the buffer after copying it
2625 @deffn Command copy-rectangle-to-register reg start end &optional delete-flag
2626 This command copies a rectangular region from @var{start} to @var{end}
2627 into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it
2628 deletes the region from the buffer after copying it to the register.
2631 @deffn Command window-configuration-to-register reg
2632 This function stores the window configuration of the selected frame in
2636 @deffn Command frame-configuration-to-register reg
2637 This function stores the current frame configuration in register
2643 @section Transposition of Text
2645 This subroutine is used by the transposition commands.
2647 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
2648 This function exchanges two nonoverlapping portions of the buffer.
2649 Arguments @var{start1} and @var{end1} specify the bounds of one portion
2650 and arguments @var{start2} and @var{end2} specify the bounds of the
2653 Normally, @code{transpose-regions} relocates markers with the transposed
2654 text; a marker previously positioned within one of the two transposed
2655 portions moves along with that portion, thus remaining between the same
2656 two characters in their new position. However, if @var{leave-markers}
2657 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
2658 all markers unrelocated.
2662 @section Change Hooks
2663 @cindex change hooks
2664 @cindex hooks for text changes
2666 These hook variables let you arrange to take notice of all changes in
2667 all buffers (or in a particular buffer, if you make them buffer-local).
2668 @ignore Not in XEmacs
2669 See also @ref{Special Properties}, for how to detect changes to specific
2673 The functions you use in these hooks should save and restore the match
2674 data if they do anything that uses regular expressions; otherwise, they
2675 will interfere in bizarre ways with the editing operations that call
2678 Buffer changes made while executing the following hooks don't
2679 themselves cause any change hooks to be invoked.
2681 @defvar before-change-functions
2682 This variable holds a list of a functions to call before any buffer
2683 modification. Each function gets two arguments, the beginning and end
2684 of the region that is about to change, represented as integers. The
2685 buffer that is about to change is always the current buffer.
2688 @defvar after-change-functions
2689 This variable holds a list of a functions to call after any buffer
2690 modification. Each function receives three arguments: the beginning and
2691 end of the region just changed, and the length of the text that existed
2692 before the change. (To get the current length, subtract the region
2693 beginning from the region end.) All three arguments are integers. The
2694 buffer that's about to change is always the current buffer.
2697 @defvar before-change-function
2698 This obsolete variable holds one function to call before any buffer
2699 modification (or @code{nil} for no function). It is called just like
2700 the functions in @code{before-change-functions}.
2703 @defvar after-change-function
2704 This obsolete variable holds one function to call after any buffer modification
2705 (or @code{nil} for no function). It is called just like the functions in
2706 @code{after-change-functions}.
2709 @defvar first-change-hook
2710 This variable is a normal hook that is run whenever a buffer is changed
2711 that was previously in the unmodified state.
2714 @node Transformations
2715 @section Textual transformations---MD5 and base64 support
2719 Some textual operations inherently require examining each character in
2720 turn, and performing arithmetic operations on them. Such operations
2721 can, of course, be implemented in Emacs Lisp, but tend to be very slow
2722 for large portions of text or data. This is why some of them are
2723 implemented in C, with an appropriate interface for Lisp programmers.
2724 Examples of algorithms thus provided are MD5 and base64 support.
2726 MD5 is an algorithm for calculating message digests, as described in
2727 rfc1321. Given a message of arbitrary length, MD5 produces an 128-bit
2728 ``fingerprint'' (``message digest'') corresponding to that message. It
2729 is considered computationally infeasible to produce two messages having
2730 the same MD5 digest, or to produce a message having a prespecified
2731 target digest. MD5 is used heavily by various authentication schemes.
2733 Emacs Lisp interface to MD5 consists of a single function @code{md5}:
2735 @defun md5 object &optional start end
2736 This function returns the MD5 message digest of @var{object}, a buffer
2739 Optional arguments @var{start} and @var{end} denote positions for
2740 computing the digest of a portion of @var{object}.
2742 Some examples of usage:
2746 ;; @r{Calculate the digest of the entire buffer}
2747 (md5 (current-buffer))
2748 @result{} "8842b04362899b1cda8d2d126dc11712"
2752 ;; @r{Calculate the digest of the current line}
2753 (md5 (current-buffer) (point-at-bol) (point-at-eol))
2754 @result{} "60614d21e9dee27dfdb01fa4e30d6d00"
2758 ;; @r{Calculate the digest of your name and email address}
2759 (md5 (concat (format "%s <%s>" (user-full-name) user-mail-address)))
2760 @result{} "0a2188c40fd38922d941fe6032fce516"
2765 Base64 is a portable encoding for arbitrary sequences of octets, in a
2766 form that need not be readable by humans. It uses a 65-character subset
2767 of US-ASCII, as described in rfc2045. Base64 is used by MIME to encode
2768 binary bodies, and to encode binary characters in message headers.
2770 The Lisp interface to base64 consists of four functions:
2772 @defun base64-encode-region beg end &optional no-line-break
2773 This function encodes the region between @var{beg} and @var{end} of the
2774 current buffer to base64 format. This means that the original region is
2775 deleted, and replaced with its base64 equivalent.
2777 Normally, encoded base64 output is multi-line, with 76-character lines.
2778 If @var{no-line-break} is non-@code{nil}, newlines will not be inserted,
2779 resulting in single-line output.
2781 Mule note: you should make sure that you convert the multibyte
2782 characters (those that do not fit into 0--255 range) to something else,
2783 because they cannot be meaningfully converted to base64. If the
2784 @code{base64-encode-region} encounters such characters, it will signal
2787 @code{base64-encode-region} returns the length of the encoded text.
2791 ;; @r{Encode the whole buffer in base64}
2792 (base64-encode-region (point-min) (point-max))
2796 The function can also be used interactively, in which case it works on
2797 the currently active region.
2800 @defun base64-encode-string string
2801 This function encodes @var{string} to base64, and returns the encoded
2804 For Mule, the same considerations apply as for
2805 @code{base64-encode-region}.
2809 (base64-encode-string "fubar")
2810 @result{} "ZnViYXI="
2815 @defun base64-decode-region beg end
2816 This function decodes the region between @var{beg} and @var{end} of the
2817 current buffer. The region should be in base64 encoding.
2819 If the region was decoded correctly, @code{base64-decode-region} returns
2820 the length of the decoded region. If the decoding failed, @code{nil} is
2825 ;; @r{Decode a base64 buffer, and replace it with the decoded version}
2826 (base64-decode-region (point-min) (point-max))
2831 @defun base64-decode-string string
2832 This function decodes @var{string} to base64, and returns the decoded
2833 string. @var{string} should be valid base64-encoded text.
2835 If encoding was not possible, @code{nil} is returned.
2839 (base64-decode-string "ZnViYXI=")
2844 (base64-decode-string "totally bogus")