f66bf59b90017fdd9109aece9df5588fe44b9d59
[chise/xemacs-chise.git.1] / man / lispref / text.texi
1 @c -*-texinfo-*-
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
7 @chapter Text
8 @cindex text
9
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
14 (@pxref{Undo}).
15
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.
26
27 @cindex buffer contents
28   Throughout this chapter, ``text'' refers to the characters in the
29 buffer, together with their properties (when relevant).
30
31 @menu
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.
57 @end menu
58
59 @node Near Point
60 @section Examining Text Near Point
61
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}.
65
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.)
71
72
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.
79
80 In the following example, assume that the first character in the
81 buffer is @samp{@@}:
82
83 @example
84 @group
85 (char-to-string (char-after 1))
86      @result{} "@@"
87 @end group
88 @end example
89 @end defun
90
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
96 assumed.
97
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
101 cursor is over.
102
103 In this example, point is between the @samp{a} and the @samp{c}.
104
105 @example
106 @group
107 ---------- Buffer: foo ----------
108 Gentlemen may cry ``Pea@point{}ce! Peace!,''
109 but there is no peace.
110 ---------- Buffer: foo ----------
111 @end group
112
113 @group
114 (char-to-string (preceding-char))
115      @result{} "a"
116 (char-to-string (following-char))
117      @result{} "c"
118 @end group
119 @end example
120 @end defun
121
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
127 is assumed.
128 @end defun
129
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
135 @ref{Point}.
136 @end defun
137
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}.
143 @end defun
144
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.
150 @end defun
151
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
157 the end of a line.
158 @end defun
159
160 @node Buffer Contents
161 @section Examining Buffer Contents
162
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.
165
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.
174
175 @c XEmacs feature.
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}.
179
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.
183
184 @example
185 @group
186 ---------- Buffer: foo ----------
187 This is the contents of buffer foo
188
189 ---------- Buffer: foo ----------
190 @end group
191
192 @group
193 (buffer-substring 1 10)
194 @result{} "This is t"
195 @end group
196 @group
197 (buffer-substring (point-max) 10)
198 @result{} "he contents of buffer foo
199 "
200 @end group
201 @end example
202 @end defun
203
204 @ignore
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
210 alist:
211
212 @example
213 (setq flammable
214       (assoc (buffer-substring start end)
215              '(("wood" . t) ("paper" . t)
216                ("steel" . nil) ("asbestos" . nil))))
217 @end example
218
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.
222 @end defun
223 @end ignore
224
225 @node Comparing Text
226 @section Comparing Text
227 @cindex comparing buffer text
228
229   This function lets you compare portions of the text in a buffer, without
230 copying them into strings first.
231
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
238 current buffer.
239
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.
244
245 This function ignores case when comparing characters
246 if @code{case-fold-search} is non-@code{nil}.  It always ignores
247 text properties.
248
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.
253
254 @example
255 (compare-buffer-substring nil 6 11 nil 16 21)
256      @result{} 2
257 @end example
258 @end defun
259
260 @node Insertion
261 @section Inserting Text
262 @cindex insertion of text
263 @cindex text insertion
264
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
267 after point.
268
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
275 inserted text.
276
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}.
282
283 @c XEmacs feature.
284   If a string with non-@code{nil} extent data is inserted, the remembered
285 extents will also be inserted.  @xref{Duplicable Extents}.
286
287   Insertion functions signal an error if the current buffer is
288 read-only.
289
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.
295
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}.
301 @end defun
302
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
307 @code{nil}.
308
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.
312 @end defun
313
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
319 use @code{insert}).
320 @end defun
321
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.)
329 @end defun
330
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}.
337
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.
340
341 @example
342 @group
343 ---------- Buffer: foo ----------
344 We hold these truths to be self-evident, that all
345 ---------- Buffer: foo ----------
346 @end group
347
348 @group
349 (insert-buffer-substring "foo" 1 20)
350      @result{} nil
351
352 ---------- Buffer: bar ----------
353 We hold these truth@point{}
354 ---------- Buffer: bar ----------
355 @end group
356 @end example
357 @end defun
358
359 @node Commands for Insertion
360 @section User-Level Insertion Commands
361
362   This section describes higher-level commands for inserting text,
363 commands intended primarily for the user but useful also in Lisp
364 programs.
365
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}.
370 @end deffn
371
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.
380
381 In an interactive call, @var{count} is the numeric prefix argument.
382
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}).
386
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}.)
391
392 This is also responsible for calling @code{blink-paren-function} when
393 the inserted character has close parenthesis syntax (@pxref{Blinking}).
394 @end deffn
395
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
399 are inserted.
400
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}.
409
410 This command indents to the left margin if that is not zero.
411 @xref{Margins}.
412
413 The value returned is @code{nil}.  In an interactive call, @var{count}
414 is the numeric prefix argument.
415 @end deffn
416
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.
423
424 Programs hardly ever use this function.
425 @end deffn
426
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.
431 @end defvar
432
433 @node Deletion
434 @section Deleting Text
435
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
441 cases.
442
443   All of the deletion functions operate on the current buffer, and all
444 return a value of @code{nil}.
445
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.
452
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.
458 @end defun
459
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.
464 @end deffn
465
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.
470
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
475 the kill ring.
476
477 The value returned is always @code{nil}.
478 @end deffn
479
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.
485
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
490 the kill ring.
491
492 The value returned is always @code{nil}.
493 @end deffn
494
495 @deffn Command backward-delete-char-untabify count &optional killp
496 @cindex tab deletion
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.
503
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
506 are deleted.
507
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
512 the kill ring.
513
514 The value returned is always @code{nil}.
515 @end deffn
516
517 @node User-Level Deletion
518 @section User-Level Deletion Commands
519
520   This section describes higher-level commands for deleting text,
521 commands intended primarily for the user but useful also in Lisp
522 programs.
523
524 @deffn Command delete-horizontal-space
525 @cindex deleting whitespace
526 This function deletes all spaces and tabs around point.  It returns
527 @code{nil}.
528
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.
532
533 @example
534 @group
535 ---------- Buffer: foo ----------
536 I @point{}thought
537 I @point{}     thought
538 We@point{} thought
539 Yo@point{}u thought
540 ---------- Buffer: foo ----------
541 @end group
542
543 @group
544 (delete-horizontal-space)   ; @r{Four times.}
545      @result{} nil
546
547 ---------- Buffer: foo ----------
548 Ithought
549 Ithought
550 Wethought
551 You thought
552 ---------- Buffer: foo ----------
553 @end group
554 @end example
555 @end deffn
556
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}.
563
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}.
567
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.
571
572 @smallexample
573 @group
574 ---------- Buffer: foo ----------
575 When in the course of human
576 @point{}    events, it becomes necessary
577 ---------- Buffer: foo ----------
578 @end group
579
580 (delete-indentation)
581      @result{} nil
582
583 @group
584 ---------- Buffer: foo ----------
585 When in the course of human@point{} events, it becomes necessary
586 ---------- Buffer: foo ----------
587 @end group
588 @end smallexample
589
590 After the lines are joined, the function @code{fixup-whitespace} is
591 responsible for deciding whether to leave a space at the junction.
592 @end deffn
593
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}.
597
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
602 Class Table}.
603
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{(}.
607
608 @smallexample
609 @group
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 ----------
614 @end group
615
616 @group
617 (fixup-whitespace)
618      @result{} nil
619 (fixup-whitespace)
620      @result{} nil
621 @end group
622
623 @group
624 ---------- Buffer: foo ----------
625 This has too many spaces
626 This has too many spaces at the start of (this list)
627 ---------- Buffer: foo ----------
628 @end group
629 @end smallexample
630 @end defun
631
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}.
636 @end deffn
637
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.
644
645 A blank line is defined as a line containing only tabs and spaces.
646
647 @code{delete-blank-lines} returns @code{nil}.
648 @end deffn
649
650 @node The Kill Ring
651 @section The Kill Ring
652 @cindex kill ring
653
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''
659 functions.
660
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.
667 @xref{Deletion}.
668
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.
676
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.
685
686 @menu
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.
692 @end menu
693
694 @node Kill Ring Concepts
695 @subsection Kill Ring Concepts
696
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:
699
700 @example
701 ("some text" "a different piece of text" "even older text")
702 @end example
703
704 @noindent
705 When the list reaches @code{kill-ring-max} entries in length, adding a
706 new entry automatically deletes the last entry.
707
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.
713
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
718 list.
719
720 @node Kill Functions
721 @subsection Functions for Killing
722
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.
730
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}.
735
736 In an interactive call, @var{start} and @var{end} are point and
737 the mark.
738
739 @c Emacs 19 feature
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.
744 @end deffn
745
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.
752
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.
755
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}.
759 @end deffn
760
761 @node Yank Commands
762 @subsection Functions for Yanking
763
764   @dfn{Yanking} means reinserting an entry of previously killed text
765 from the kill ring.  The text properties are copied too.
766
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
771 point at the end.
772
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
776 after it.
777
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.
780
781 @code{yank} does not alter the contents of the kill ring or rotate it.
782 It returns @code{nil}.
783 @end deffn
784
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.
788
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.
794
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.
799
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
802 oldest.
803
804 The value is always @code{nil}.
805 @end deffn
806
807 @node Low-Level Kill Ring
808 @subsection Low-Level Kill Ring
809
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
813 version 18.
814
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.
819
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.
823
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
827 the kill ring.
828 @end defun
829
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).
835 @end defun
836
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
842 below).
843 @end defun
844
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.
849
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.
854
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}.
858 @end defvar
859
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.
864
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.
867
868 The normal use of this hook is to set the X server's primary selection
869 to the newly killed text.
870 @end defvar
871
872 @node Internals of Kill Ring
873 @subsection Internals of the Kill Ring
874
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
877 of the list. 
878
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}.
887
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
892 command.
893
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.
899
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")}.  
903
904 @example
905 @group
906 kill-ring       kill-ring-yank-pointer
907   |               |
908   |     ___ ___    --->  ___ ___      ___ ___
909    --> |___|___|------> |___|___|--> |___|___|--> nil
910          |                |            |            
911          |                |            |            
912          |                |             -->"yet older text" 
913          |                |
914          |                 --> "a different piece of text" 
915          |
916           --> "some text"
917 @end group
918 @end example
919
920 @noindent
921 This state of affairs might occur after @kbd{C-y} (@code{yank})
922 immediately followed by @kbd{M-y} (@code{yank-pop}).
923
924 @defvar kill-ring
925 This variable holds the list of killed text sequences, most recently
926 killed first.
927 @end defvar
928
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.
934 @end defvar
935
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.
940 @end defopt
941
942 @node Undo
943 @section Undo
944 @cindex redo
945
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}.
952
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.
956 @end defvar
957
958 Here are the kinds of elements an undo list can have:
959
960 @table @code
961 @item @var{integer}
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.
965
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 
969 buffer.
970
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})}.
975
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.
983
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:
987
988 @example
989 (put-text-property @var{beg} @var{end} @var{property} @var{value})
990 @end example
991
992 @item @var{position}
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.
996
997 @item nil
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
1001 a unit.
1002 @end table
1003
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}.
1008
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.
1016
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.
1020
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.
1025 @end defun
1026
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.
1032
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
1038 continuing to undo.
1039 @end defun
1040
1041 @node Maintaining Undo
1042 @section Maintaining Undo Lists
1043
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.
1047
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.
1053
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
1059 returns @code{nil}.
1060
1061 In an interactive call, @var{buffer-or-name} is the current buffer.
1062 You cannot specify any other buffer.
1063 @end deffn
1064
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
1072 has no effect.
1073
1074 This function returns @code{nil}.  It cannot be called interactively.
1075
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
1078 19.
1079 @end defun
1080
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}.
1087
1088 @defvar undo-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.
1091 @end defvar
1092
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.
1098 @end defvar
1099
1100 @node Filling
1101 @section Filling
1102 @cindex filling, explicit
1103
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.
1110
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.
1114
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.
1120
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).
1127
1128   When you call the filling functions interactively, using a prefix
1129 argument implies the value @code{full} for @var{justify}.
1130
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}.
1137 @end deffn
1138
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
1142 non-@code{nil}.
1143
1144 The variable @code{paragraph-separate} controls how to distinguish
1145 paragraphs.  @xref{Standard Regexps}.
1146 @end deffn
1147
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
1152 fashion.
1153
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
1160 the header lines.
1161
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.
1167 @end deffn
1168
1169 @defopt fill-individual-varying-indent
1170 This variable alters the action of @code{fill-individual-paragraphs} as
1171 described above.
1172 @end defopt
1173
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}.
1179
1180 In an interactive call, any prefix argument requests justification.
1181
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
1185 as the fill prefix.
1186 @end deffn
1187
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
1191 @code{nil}.
1192
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.
1198
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.
1203
1204 If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1205 whitespace.
1206 @end deffn
1207
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}.
1213 @end defopt
1214
1215 @defun current-justification
1216 This function returns the proper justification style to use for filling
1217 the text around point.
1218 @end defun
1219
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
1225 returns that value.
1226
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:
1230
1231 @example
1232 (let ((fill-paragraph-function nil))
1233   (fill-paragraph arg))
1234 @end example
1235 @end defvar
1236
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.
1241 @end defvar
1242
1243 @node Margins
1244 @section Margins for Filling
1245
1246 @defopt fill-prefix
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.
1254
1255 The fill prefix follows the left margin whitespace, if any.
1256 @end defopt
1257
1258 @defopt fill-column
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}).
1263
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.
1268 @end defopt
1269
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)}.
1274
1275 The default value for @code{default-fill-column} is 70.
1276 @end defvar
1277
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.
1282 @end deffn
1283
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.
1288 @end deffn
1289
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}.
1295 @end defun
1296
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.
1302 @end defun
1303
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.
1309
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.
1312 @end deffn
1313
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.
1319 @end defun
1320
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
1326 whitespace.
1327 @end defun
1328
1329 @defvar left-margin
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.
1333 @end defvar
1334
1335 @node Auto Filling
1336 @section Auto Filling
1337 @cindex filling, automatic
1338 @cindex Auto Fill mode
1339
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}.
1344
1345   Auto Fill mode also enables the functions that change the margins and
1346 justification style to refill portions of the text.  @xref{Margins}.
1347
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.
1352
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.
1356
1357 @quotation
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.
1361 @end quotation
1362 @end defvar
1363
1364 @node Sorting
1365 @section Sorting Text
1366 @cindex sorting text
1367
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.
1372
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
1376 this function.
1377
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
1383 their sort keys.
1384
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.
1389
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}.
1393
1394 @enumerate
1395 @item
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}.
1401
1402 This function can indicate there are no more sort records by leaving
1403 point at the end of the buffer.
1404
1405 @item
1406 @var{endrecfun} is called with point within a record.  It moves point to
1407 the end of the record.
1408
1409 @item
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.
1417
1418 @item
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.
1425 @end enumerate
1426
1427 As an example of @code{sort-subr}, here is the complete function
1428 definition for @code{sort-lines}:
1429
1430 @example
1431 @group
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:
1437 @end group
1438 @group
1439 REVERSE (non-nil means reverse order),
1440 and BEG and END (the region to sort)."
1441   (interactive "P\nr")
1442   (save-restriction
1443     (narrow-to-region beg end)
1444     (goto-char (point-min))
1445     (sort-subr reverse
1446                'forward-line
1447                'end-of-line)))
1448 @end group
1449 @end example
1450
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.
1455
1456 The @code{sort-paragraphs} function is very much the same, except that
1457 its @code{sort-subr} call looks like this:
1458
1459 @example
1460 @group
1461 (sort-subr reverse
1462            (function 
1463             (lambda () 
1464               (skip-chars-forward "\n \t\f")))
1465            'forward-paragraph)
1466 @end group
1467 @end example
1468 @end defun
1469
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
1474 order.
1475
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
1484
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.
1492
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.
1498
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
1501 on its own.
1502
1503 If @var{key-regexp} is:
1504
1505 @table @asis
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.
1509
1510 @item @samp{\&}
1511 then the whole record is the sort key.
1512
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.)
1519 @end table
1520
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:
1525
1526 @example
1527 @group
1528 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
1529                     (region-beginning)
1530                     (region-end))
1531 @end group
1532 @end example
1533
1534 If you call @code{sort-regexp-fields} interactively, it prompts for
1535 @var{record-regexp} and @var{key-regexp} in the minibuffer.
1536 @end deffn
1537
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.
1542 @end deffn
1543
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.
1548 @end deffn
1549
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.
1554 @end deffn
1555
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.
1563 @end deffn
1564
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.
1573 @end deffn
1574
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
1579 columns to sort on.
1580
1581 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
1582
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.
1586
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.
1590 @end deffn
1591
1592 @node Columns
1593 @comment  node-name,  next,  previous,  up
1594 @section Counting Columns
1595 @cindex columns
1596 @cindex counting columns
1597 @cindex horizontal position
1598
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).
1602
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}.
1608
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.
1612
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.
1618
1619 For an example of using @code{current-column}, see the description of
1620 @code{count-lines} in @ref{Text Lines}.
1621 @end defun
1622
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
1627 line and point.
1628
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.
1632
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.
1640
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.
1644
1645 If @var{column} is not an integer, an error is signaled.
1646
1647 The return value is the column number actually moved to.
1648 @end defun
1649
1650 @node Indentation
1651 @section Indentation
1652 @cindex indentation
1653
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.
1658
1659 @menu
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.
1666 @end menu
1667
1668 @node Primitive Indent
1669 @subsection Indentation Primitives
1670
1671   This section describes the primitive functions used to count and
1672 insert indentation.  The functions in the following sections use these
1673 primitives.
1674
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
1681 end of the line.
1682 @end defun
1683
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
1692 indentation ends.
1693 @end deffn
1694
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.
1700 @end defopt
1701
1702 @node Mode-Specific Indent
1703 @subsection Indentation Controlled by Major Mode
1704
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.
1709
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.
1714
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
1719 default value).
1720 @end defvar
1721
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.
1725 @end deffn
1726
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.)
1732 @end deffn
1733
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.
1738
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
1743 @code{left-margin}.
1744 @end deffn
1745
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
1750 inserted).
1751
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}.
1758 @end deffn
1759
1760 @node Region Indent
1761 @subsection Indenting an Entire Region
1762
1763   This section describes commands that indent all the lines in the
1764 region.  They return unpredictable values.
1765
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}.
1772
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.
1777
1778 If there is a fill prefix, @code{indent-region} indents each line
1779 by making it start with the fill prefix.
1780 @end deffn
1781
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.
1787
1788 If the value is @code{nil}, there is no short cut, and
1789 @code{indent-region} actually works line by line.
1790
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.
1797
1798 @code{indent-region} with a non-@code{nil} argument @var{to-column} has
1799 a different meaning and does not use this variable.
1800 @end defvar
1801
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
1809 code.
1810
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.
1813
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
1816 replied to.
1817 @end deffn
1818
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.
1822
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}).
1825 @end defun
1826
1827 @node Relative Indent
1828 @subsection Indentation Relative to Previous Lines
1829
1830   This section describes two commands that indent the current line
1831 based on the contents of previous lines.
1832
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.
1841
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.
1848
1849 The return value of @code{indent-relative} is unpredictable.
1850
1851 In the following example, point is at the beginning of the second
1852 line:
1853
1854 @example
1855 @group
1856             This line is indented twelve spaces.
1857 @point{}The quick brown fox jumped.
1858 @end group
1859 @end example
1860
1861 @noindent
1862 Evaluation of the expression @code{(indent-relative nil)} produces the
1863 following:
1864
1865 @example
1866 @group
1867             This line is indented twelve spaces.
1868             @point{}The quick brown fox jumped.
1869 @end group
1870 @end example
1871
1872   In this example, point is between the @samp{m} and @samp{p} of
1873 @samp{jumped}:
1874
1875 @example
1876 @group
1877             This line is indented twelve spaces.
1878 The quick brown fox jum@point{}ped.
1879 @end group
1880 @end example
1881
1882 @noindent
1883 Evaluation of the expression @code{(indent-relative nil)} produces the
1884 following:
1885
1886 @example
1887 @group
1888             This line is indented twelve spaces.
1889 The quick brown fox jum  @point{}ped.
1890 @end group
1891 @end example
1892 @end deffn
1893
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.
1899
1900 If the previous nonblank line has no indent points beyond the current
1901 column, this command does nothing.
1902 @end deffn
1903
1904 @node Indent Tabs
1905 @subsection Adjustable ``Tab Stops''
1906 @cindex tabs stops for indentation
1907
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.
1916
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.
1922 @end deffn
1923
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.
1928
1929 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
1930 interactively.
1931 @end defopt
1932
1933 @node Motion by Indent
1934 @subsection Indentation-Based Motion Commands
1935
1936   These commands, primarily for interactive use, act based on the
1937 indentation in the text.
1938
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
1943 @code{nil}.
1944 @end deffn
1945
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}.
1950 @end deffn
1951
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}.
1956 @end deffn
1957
1958 @node Case Changes
1959 @section Case Changes
1960 @cindex case changes
1961
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.
1966
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}.
1972
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.
1975
1976 When @code{capitalize-region} is called interactively, @var{start} and
1977 @var{end} are point and the mark, with the smallest first.
1978
1979 @example
1980 @group
1981 ---------- Buffer: foo ----------
1982 This is the contents of the 5th foo.
1983 ---------- Buffer: foo ----------
1984 @end group
1985
1986 @group
1987 (capitalize-region 1 44)
1988 @result{} nil
1989
1990 ---------- Buffer: foo ----------
1991 This Is The Contents Of The 5th Foo.
1992 ---------- Buffer: foo ----------
1993 @end group
1994 @end example
1995 @end deffn
1996
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
2000 @code{nil}.
2001
2002 When @code{downcase-region} is called interactively, @var{start} and
2003 @var{end} are point and the mark, with the smallest first.
2004 @end deffn
2005
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
2009 @code{nil}.
2010
2011 When @code{upcase-region} is called interactively, @var{start} and
2012 @var{end} are point and the mark, with the smallest first.
2013 @end deffn
2014
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
2021 is @code{nil}.
2022
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.
2025
2026 When @code{capitalize-word} is called interactively, @var{count} is
2027 set to the numeric prefix argument.
2028 @end deffn
2029
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}.
2035
2036 When @code{downcase-word} is called interactively, @var{count} is set
2037 to the numeric prefix argument.
2038 @end deffn
2039
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}.
2045
2046 When @code{upcase-word} is called interactively, @var{count} is set to
2047 the numeric prefix argument.
2048 @end deffn
2049
2050 @node Text Properties
2051 @section Text Properties
2052 @cindex text properties
2053 @cindex attributes of text
2054 @cindex properties of text
2055
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.
2061
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.
2069
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.
2073
2074 @ignore
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.
2078 @end ignore
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.
2081
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}.
2085
2086 @menu
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
2092                                   them back.
2093 @end menu
2094
2095 @node Examining Properties
2096 @subsection Examining Text Properties
2097
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.
2103
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
2106 from 1.)
2107
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
2112 buffer.
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.
2117 @end ignore
2118 @end defun
2119
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.
2123
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
2131 overlays.
2132 @end ignore
2133 @end defun
2134
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.
2139 @end defun
2140
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
2145 an example:
2146
2147 @example
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)
2153      @result{} 69
2154 @end example
2155 @end defvar
2156
2157 @node Changing Properties
2158 @subsection Changing Text Properties
2159
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
2164 name.
2165
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}).
2170
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.
2175 @end defun
2176
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.
2181
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.
2186
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).
2190
2191 For example, here is how to set the @code{comment} and @code{face}
2192 properties of a range of text:
2193
2194 @example
2195 (add-text-properties @var{start} @var{end}
2196                      '(comment t face highlight))
2197 @end example
2198 @end defun
2199
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.
2204
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.
2210
2211 @example
2212 (remove-text-properties @var{start} @var{end} '(face nil))
2213 @end example
2214
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).
2218 @end defun
2219
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.
2224
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.
2227
2228 After @code{set-text-properties} returns, all the characters in the
2229 specified range have identical properties.
2230
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:
2233
2234 @example
2235 (set-text-properties @var{start} @var{end} nil)
2236 @end example
2237 @end defun
2238
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.
2242
2243 @node Property Search
2244 @subsection Property Search Functions
2245
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.
2250
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
2253 current buffer.
2254
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.
2259
2260 Remember that a position is always between two characters; the position
2261 returned by these functions is between two characters with different
2262 properties.
2263
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
2270 @var{pos}.
2271
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}.
2275
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}.
2280
2281 Here is an example of how to scan the buffer by chunks of text within
2282 which all properties are constant:
2283
2284 @smallexample
2285 (while (not (eobp))
2286   (let ((plist (text-properties-at (point)))
2287         (next-change
2288          (or (next-property-change (point) (current-buffer))
2289              (point-max))))
2290     @r{Process text from point to @var{next-change}@dots{}}
2291     (goto-char next-change)))
2292 @end smallexample
2293 @end defun
2294
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
2301 @var{pos}.
2302
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}.
2306
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}.
2311 @end defun
2312
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}
2317 equals @var{pos}.
2318 @end defun
2319
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}.
2325 @end defun
2326
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}.
2332
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.
2336 @end defun
2337
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}.
2343
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.
2347 @end defun
2348
2349 @node Special Properties
2350 @subsection Properties with Special Meanings
2351
2352 The predefined properties are the same as those for extents.
2353 @xref{Extent Properties}.
2354
2355 @ignore  Changed in XEmacs
2356 (deleted section describing FSF Emacs special text properties)
2357 @end ignore
2358
2359 @node Saving Properties
2360 @subsection Saving Text Properties in Files
2361 @cindex text properties in files
2362 @cindex saving text properties
2363
2364   You can save text properties in files, and restore text properties
2365 when inserting the files, using these two hooks: 
2366
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}.
2371
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
2376 buffer.
2377
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.
2382
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.
2386
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.
2390 @end defvar
2391
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.
2397
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.
2404
2405 These functions should always return with point at the beginning of
2406 the inserted text.
2407
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.
2411 @end defvar
2412
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.
2417
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.
2422
2423 @xref{Format Conversion}, for a related feature.
2424
2425 @node Substitution
2426 @section Substituting for a Character Code
2427
2428   The following functions replace characters within a specified region
2429 based on their character codes.
2430
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}.
2436
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
2442 Display}).
2443
2444 @code{subst-char-in-region} does not move point and returns
2445 @code{nil}.
2446
2447 @example
2448 @group
2449 ---------- Buffer: foo ----------
2450 This is the contents of the buffer before.
2451 ---------- Buffer: foo ----------
2452 @end group
2453
2454 @group
2455 (subst-char-in-region 1 20 ?i ?X)
2456      @result{} nil
2457
2458 ---------- Buffer: foo ----------
2459 ThXs Xs the contents of the buffer before.
2460 ---------- Buffer: foo ----------
2461 @end group
2462 @end example
2463 @end defun
2464
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}.
2468
2469 The translation table @var{table} is a string; @code{(aref @var{table}
2470 @var{ochar})} gives the translated character corresponding to
2471 @var{ochar}.  If the length of @var{table} is less than 256, any
2472 characters with codes larger than the length of @var{table} are not
2473 altered by the translation.
2474
2475 The return value of @code{translate-region} is the number of
2476 characters that were actually changed by the translation.  This does
2477 not count characters that were mapped into themselves in the
2478 translation table.
2479 @end defun
2480
2481 @node Registers
2482 @section Registers
2483 @cindex registers
2484
2485   A register is a sort of variable used in XEmacs editing that can hold a
2486 marker, a string, a rectangle, a window configuration (of one frame), or
2487 a frame configuration (of all frames).  Each register is named by a
2488 single character.  All characters, including control and meta characters
2489 (but with the exception of @kbd{C-g}), can be used to name registers.
2490 Thus, there are 255 possible registers.  A register is designated in
2491 Emacs Lisp by a character that is its name.
2492
2493   The functions in this section return unpredictable values unless
2494 otherwise stated.
2495 @c Will change in version 19
2496
2497 @defvar register-alist
2498 This variable is an alist of elements of the form @code{(@var{name} .
2499 @var{contents})}.  Normally, there is one element for each XEmacs
2500 register that has been used.
2501
2502 The object @var{name} is a character (an integer) identifying the
2503 register.  The object @var{contents} is a string, marker, or list
2504 representing the register contents.  A string represents text stored in
2505 the register.  A marker represents a position.  A list represents a
2506 rectangle; its elements are strings, one per line of the rectangle.
2507 @end defvar
2508
2509 @defun get-register reg
2510 This function returns the contents of the register
2511 @var{reg}, or @code{nil} if it has no contents.
2512 @end defun
2513
2514 @defun set-register reg value
2515 This function sets the contents of register @var{reg} to @var{value}.
2516 A register can be set to any value, but the other register functions
2517 expect only certain data types.  The return value is @var{value}.
2518 @end defun
2519
2520 @deffn Command view-register reg
2521 This command displays what is contained in register @var{reg}.
2522 @end deffn
2523
2524 @ignore
2525 @deffn Command point-to-register reg
2526 This command stores both the current location of point and the current
2527 buffer in register @var{reg} as a marker.
2528 @end deffn
2529
2530 @deffn Command jump-to-register reg
2531 @deffnx Command register-to-point reg
2532 @comment !!SourceFile register.el
2533 This command restores the status recorded in register @var{reg}.
2534
2535 If @var{reg} contains a marker, it moves point to the position stored in
2536 the marker.  Since both the buffer and the location within the buffer
2537 are stored by the @code{point-to-register} function, this command can
2538 switch you to another buffer.
2539
2540 If @var{reg} contains a window configuration or a frame configuration.
2541 @code{jump-to-register} restores that configuration.
2542 @end deffn
2543 @end ignore
2544
2545 @deffn Command insert-register reg &optional beforep
2546 This command inserts contents of register @var{reg} into the current
2547 buffer.
2548
2549 Normally, this command puts point before the inserted text, and the
2550 mark after it.  However, if the optional second argument @var{beforep}
2551 is non-@code{nil}, it puts the mark before and point after.
2552 You can pass a non-@code{nil} second argument @var{beforep} to this
2553 function interactively by supplying any prefix argument.
2554
2555 If the register contains a rectangle, then the rectangle is inserted
2556 with its upper left corner at point.  This means that text is inserted
2557 in the current line and underneath it on successive lines.
2558
2559 If the register contains something other than saved text (a string) or
2560 a rectangle (a list), currently useless things happen.  This may be
2561 changed in the future.
2562 @end deffn
2563
2564 @ignore
2565 @deffn Command copy-to-register reg start end &optional delete-flag
2566 This command copies the region from @var{start} to @var{end} into
2567 register @var{reg}.  If @var{delete-flag} is non-@code{nil}, it deletes
2568 the region from the buffer after copying it into the register.
2569 @end deffn
2570
2571 @deffn Command prepend-to-register reg start end &optional delete-flag
2572 This command prepends the region from @var{start} to @var{end} into
2573 register @var{reg}.  If @var{delete-flag} is non-@code{nil}, it deletes
2574 the region from the buffer after copying it to the register.
2575 @end deffn
2576
2577 @deffn Command append-to-register reg start end &optional delete-flag
2578 This command appends the region from @var{start} to @var{end} to the
2579 text already in register @var{reg}.  If @var{delete-flag} is
2580 non-@code{nil}, it deletes the region from the buffer after copying it
2581 to the register.
2582 @end deffn
2583
2584 @deffn Command copy-rectangle-to-register reg start end &optional delete-flag
2585 This command copies a rectangular region from @var{start} to @var{end}
2586 into register @var{reg}.  If @var{delete-flag} is non-@code{nil}, it
2587 deletes the region from the buffer after copying it to the register.
2588 @end deffn
2589
2590 @deffn Command window-configuration-to-register reg
2591 This function stores the window configuration of the selected frame in
2592 register @var{reg}.
2593 @end deffn
2594
2595 @deffn Command frame-configuration-to-register reg
2596 This function stores the current frame configuration in register
2597 @var{reg}.
2598 @end deffn
2599 @end ignore
2600
2601 @node Transposition
2602 @section Transposition of Text
2603
2604   This subroutine is used by the transposition commands.
2605
2606 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers
2607 This function exchanges two nonoverlapping portions of the buffer.
2608 Arguments @var{start1} and @var{end1} specify the bounds of one portion
2609 and arguments @var{start2} and @var{end2} specify the bounds of the
2610 other portion.
2611
2612 Normally, @code{transpose-regions} relocates markers with the transposed
2613 text; a marker previously positioned within one of the two transposed
2614 portions moves along with that portion, thus remaining between the same
2615 two characters in their new position.  However, if @var{leave-markers}
2616 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
2617 all markers unrelocated.
2618 @end defun
2619
2620 @node Change Hooks
2621 @section Change Hooks
2622 @cindex change hooks
2623 @cindex hooks for text changes
2624
2625   These hook variables let you arrange to take notice of all changes in
2626 all buffers (or in a particular buffer, if you make them buffer-local).
2627 @ignore  Not in XEmacs
2628 See also @ref{Special Properties}, for how to detect changes to specific
2629 parts of the text.
2630 @end ignore
2631
2632   The functions you use in these hooks should save and restore the match
2633 data if they do anything that uses regular expressions; otherwise, they
2634 will interfere in bizarre ways with the editing operations that call
2635 them.
2636
2637   Buffer changes made while executing the following hooks don't
2638 themselves cause any change hooks to be invoked.
2639
2640 @defvar before-change-functions
2641 This variable holds a list of a functions to call before any buffer
2642 modification.  Each function gets two arguments, the beginning and end
2643 of the region that is about to change, represented as integers.  The
2644 buffer that is about to change is always the current buffer.
2645 @end defvar
2646
2647 @defvar after-change-functions
2648 This variable holds a list of a functions to call after any buffer
2649 modification.  Each function receives three arguments: the beginning and
2650 end of the region just changed, and the length of the text that existed
2651 before the change.  (To get the current length, subtract the region
2652 beginning from the region end.)  All three arguments are integers.  The
2653 buffer that's about to change is always the current buffer.
2654 @end defvar
2655
2656 @defvar before-change-function
2657 This obsolete variable holds one function to call before any buffer
2658 modification (or @code{nil} for no function).  It is called just like
2659 the functions in @code{before-change-functions}.
2660 @end defvar
2661
2662 @defvar after-change-function
2663 This obsolete variable holds one function to call after any buffer modification
2664 (or @code{nil} for no function).  It is called just like the functions in
2665 @code{after-change-functions}.
2666 @end defvar
2667
2668 @defvar first-change-hook
2669 This variable is a normal hook that is run whenever a buffer is changed
2670 that was previously in the unmodified state.
2671 @end defvar
2672
2673 @node Transformations
2674 @section Textual transformations---MD5 and base64 support
2675 @cindex MD5 digests
2676 @cindex base64
2677
2678 Some textual operations inherently require examining each character in
2679 turn, and performing arithmetic operations on them.  Such operations
2680 can, of course, be implemented in Emacs Lisp, but tend to be very slow
2681 for large portions of text or data.  This is why some of them are
2682 implemented in C, with an appropriate interface for Lisp programmers.
2683 Examples of algorithms thus provided are MD5 and base64 support.
2684
2685 MD5 is an algorithm for calculating message digests, as described in
2686 rfc1321.  Given a message of arbitrary length, MD5 produces an 128-bit
2687 ``fingerprint'' (``message digest'') corresponding to that message.  It
2688 is considered computationally infeasible to produce two messages having
2689 the same MD5 digest, or to produce a message having a prespecified
2690 target digest.  MD5 is used heavily by various authentication schemes.
2691
2692 Emacs Lisp interface to MD5 consists of a single function @code{md5}:
2693
2694 @defun md5 object &optional start end
2695 This function returns the MD5 message digest of @var{object}, a buffer
2696 or string.
2697
2698 Optional arguments @var{start} and @var{end} denote positions for
2699 computing the digest of a portion of @var{object}.
2700
2701 Some examples of usage:
2702
2703 @example
2704 @group
2705 ;; @r{Calculate the digest of the entire buffer}
2706 (md5 (current-buffer))
2707      @result{} "8842b04362899b1cda8d2d126dc11712"
2708 @end group
2709
2710 @group
2711 ;; @r{Calculate the digest of the current line}
2712 (md5 (current-buffer) (point-at-bol) (point-at-eol))
2713      @result{} "60614d21e9dee27dfdb01fa4e30d6d00"
2714 @end group
2715
2716 @group
2717 ;; @r{Calculate the digest of your name and email address}
2718 (md5 (concat (format "%s <%s>" (user-full-name) user-mail-address)))
2719      @result{} "0a2188c40fd38922d941fe6032fce516"
2720 @end group
2721 @end example
2722 @end defun
2723
2724 Base64 is a portable encoding for arbitrary sequences of octets, in a
2725 form that need not be readable by humans.  It uses a 65-character subset
2726 of US-ASCII, as described in rfc2045.  Base64 is used by MIME to encode
2727 binary bodies, and to encode binary characters in message headers.
2728
2729 The Lisp interface to base64 consists of four functions:
2730
2731 @defun base64-encode-region beg end &optional no-line-break
2732 This function encodes the region between @var{beg} and @var{end} of the
2733 current buffer to base64 format.  This means that the original region is 
2734 deleted, and replaced with its base64 equivalent.
2735
2736 Normally, encoded base64 output is multi-line, with 76-character lines.
2737 If @var{no-line-break} is non-@code{nil}, newlines will not be inserted, 
2738 resulting in single-line output.
2739
2740 Mule note: you should make sure that you convert the multibyte
2741 characters (those that do not fit into 0--255 range) to something else,
2742 because they cannot be meaningfully converted to base64.  If the
2743 @code{base64-encode-region} encounters such characters, it will signal
2744 an error.
2745
2746 @code{base64-encode-region} returns the length of the encoded text.
2747
2748 @example
2749 @group
2750 ;; @r{Encode the whole buffer in base64}
2751 (base64-encode-region (point-min) (point-max))
2752 @end group
2753 @end example
2754
2755 The function can also be used interactively, in which case it works on
2756 the currently active region.
2757 @end defun
2758
2759 @defun base64-encode-string string
2760 This function encodes @var{string} to base64, and returns the encoded
2761 string.
2762
2763 For Mule, the same considerations apply as for
2764 @code{base64-encode-region}.
2765
2766 @example
2767 @group
2768 (base64-encode-string "fubar")
2769     @result{} "ZnViYXI="
2770 @end group
2771 @end example
2772 @end defun
2773
2774 @defun base64-decode-region beg end
2775 This function decodes the region between @var{beg} and @var{end} of the
2776 current buffer.  The region should be in base64 encoding.
2777
2778 If the region was decoded correctly, @code{base64-decode-region} returns
2779 the length of the decoded region.  If the decoding failed, @code{nil} is 
2780 returned.
2781
2782 @example
2783 @group
2784 ;; @r{Decode a base64 buffer, and replace it with the decoded version}
2785 (base64-decode-region (point-min) (point-max))
2786 @end group
2787 @end example
2788 @end defun
2789
2790 @defun base64-decode-string string
2791 This function decodes @var{string} to base64, and returns the decoded
2792 string.  @var{string} should be valid base64-encoded text.
2793
2794 If encoding was not possible, @code{nil} is returned.
2795
2796 @example
2797 @group
2798 (base64-decode-string "ZnViYXI=")
2799     @result{} "fubar"
2800 @end group
2801
2802 @group
2803 (base64-decode-string "totally bogus")
2804     @result{} nil
2805 @end group
2806 @end example
2807 @end defun