* lisp/erc/erc-desktop-notifications.el (dbus-debug): Declare.
[bpt/emacs.git] / doc / lispref / text.texi
CommitLineData
b8d4c8d0
GM
1@c -*-texinfo-*-
2@c This is part of the GNU Emacs Lisp Reference Manual.
ab422c4d 3@c Copyright (C) 1990-1995, 1998-2013 Free Software Foundation, Inc.
b8d4c8d0 4@c See the file elisp.texi for copying conditions.
ecc6530d 5@node Text
b8d4c8d0
GM
6@chapter Text
7@cindex text
8
9 This chapter describes the functions that deal with the text in a
10buffer. Most examine, insert, or delete text in the current buffer,
11often operating at point or on text adjacent to point. Many are
12interactive. All the functions that change the text provide for undoing
13the changes (@pxref{Undo}).
14
15 Many text-related functions operate on a region of text defined by two
16buffer positions passed in arguments named @var{start} and @var{end}.
17These arguments should be either markers (@pxref{Markers}) or numeric
18character positions (@pxref{Positions}). The order of these arguments
19does not matter; it is all right for @var{start} to be the end of the
20region and @var{end} the beginning. For example, @code{(delete-region 1
2110)} and @code{(delete-region 10 1)} are equivalent. An
22@code{args-out-of-range} error is signaled if either @var{start} or
23@var{end} is outside the accessible portion of the buffer. In an
24interactive call, point and the mark are used for these arguments.
25
26@cindex buffer contents
27 Throughout this chapter, ``text'' refers to the characters in the
28buffer, together with their properties (when relevant). Keep in mind
29that point is always between two characters, and the cursor appears on
30the character after point.
31
32@menu
33* Near Point:: Examining text in the vicinity of point.
34* Buffer Contents:: Examining text in a general fashion.
35* Comparing Text:: Comparing substrings of buffers.
36* Insertion:: Adding new text to a buffer.
37* Commands for Insertion:: User-level commands to insert text.
38* Deletion:: Removing text from a buffer.
39* User-Level Deletion:: User-level commands to delete text.
40* The Kill Ring:: Where removed text sometimes is saved for later use.
41* Undo:: Undoing changes to the text of a buffer.
42* Maintaining Undo:: How to enable and disable undo information.
d24880de 43 How to control how much information is kept.
b8d4c8d0
GM
44* Filling:: Functions for explicit filling.
45* Margins:: How to specify margins for filling commands.
46* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context.
47* Auto Filling:: How auto-fill mode is implemented to break lines.
48* Sorting:: Functions for sorting parts of the buffer.
49* Columns:: Computing horizontal positions, and using them.
50* Indentation:: Functions to insert or adjust indentation.
51* Case Changes:: Case conversion of parts of the buffer.
52* Text Properties:: Assigning Lisp property lists to text characters.
53* Substitution:: Replacing a given character wherever it appears.
b8d4c8d0
GM
54* Registers:: How registers are implemented. Accessing the text or
55 position stored in a register.
d4913798 56* Transposition:: Swapping two portions of a buffer.
b8d4c8d0 57* Base 64:: Conversion to or from base 64 encoding.
483ab230
CY
58* Checksum/Hash:: Computing cryptographic hashes.
59* Parsing HTML/XML:: Parsing HTML and XML.
b8d4c8d0
GM
60* Atomic Changes:: Installing several buffer changes "atomically".
61* Change Hooks:: Supplying functions to be run when text is changed.
62@end menu
63
64@node Near Point
65@section Examining Text Near Point
66@cindex text near point
67
68 Many functions are provided to look at the characters around point.
69Several simple functions are described here. See also @code{looking-at}
70in @ref{Regexp Search}.
71
72In the following four functions, ``beginning'' or ``end'' of buffer
73refers to the beginning or end of the accessible portion.
74
75@defun char-after &optional position
76This function returns the character in the current buffer at (i.e.,
77immediately after) position @var{position}. If @var{position} is out of
78range for this purpose, either before the beginning of the buffer, or at
79or beyond the end, then the value is @code{nil}. The default for
80@var{position} is point.
81
82In the following example, assume that the first character in the
83buffer is @samp{@@}:
84
85@example
86@group
3e99b825 87(string (char-after 1))
b8d4c8d0
GM
88 @result{} "@@"
89@end group
90@end example
91@end defun
92
93@defun char-before &optional position
94This function returns the character in the current buffer immediately
95before position @var{position}. If @var{position} is out of range for
96this purpose, either at or before the beginning of the buffer, or beyond
97the end, then the value is @code{nil}. The default for
98@var{position} is point.
99@end defun
100
101@defun following-char
102This function returns the character following point in the current
103buffer. This is similar to @code{(char-after (point))}. However, if
104point is at the end of the buffer, then @code{following-char} returns 0.
105
106Remember that point is always between characters, and the cursor
107normally appears over the character following point. Therefore, the
108character returned by @code{following-char} is the character the
109cursor is over.
110
111In this example, point is between the @samp{a} and the @samp{c}.
112
113@example
114@group
115---------- Buffer: foo ----------
116Gentlemen may cry ``Pea@point{}ce! Peace!,''
117but there is no peace.
118---------- Buffer: foo ----------
119@end group
120
121@group
3e99b825 122(string (preceding-char))
b8d4c8d0 123 @result{} "a"
3e99b825 124(string (following-char))
b8d4c8d0
GM
125 @result{} "c"
126@end group
127@end example
128@end defun
129
130@defun preceding-char
131This function returns the character preceding point in the current
132buffer. See above, under @code{following-char}, for an example. If
133point is at the beginning of the buffer, @code{preceding-char} returns
1340.
135@end defun
136
137@defun bobp
138This function returns @code{t} if point is at the beginning of the
139buffer. If narrowing is in effect, this means the beginning of the
140accessible portion of the text. See also @code{point-min} in
141@ref{Point}.
142@end defun
143
144@defun eobp
145This function returns @code{t} if point is at the end of the buffer.
146If narrowing is in effect, this means the end of accessible portion of
147the text. See also @code{point-max} in @xref{Point}.
148@end defun
149
150@defun bolp
151This function returns @code{t} if point is at the beginning of a line.
152@xref{Text Lines}. The beginning of the buffer (or of its accessible
153portion) always counts as the beginning of a line.
154@end defun
155
156@defun eolp
157This function returns @code{t} if point is at the end of a line. The
158end of the buffer (or of its accessible portion) is always considered
159the end of a line.
160@end defun
161
162@node Buffer Contents
163@section Examining Buffer Contents
164
165 This section describes functions that allow a Lisp program to
166convert any portion of the text in the buffer into a string.
167
168@defun buffer-substring start end
169This function returns a string containing a copy of the text of the
170region defined by positions @var{start} and @var{end} in the current
67cd45a2
CY
171buffer. If the arguments are not positions in the accessible portion
172of the buffer, @code{buffer-substring} signals an
173@code{args-out-of-range} error.
b8d4c8d0
GM
174
175Here's an example which assumes Font-Lock mode is not enabled:
176
177@example
178@group
179---------- Buffer: foo ----------
180This is the contents of buffer foo
181
182---------- Buffer: foo ----------
183@end group
184
185@group
186(buffer-substring 1 10)
187 @result{} "This is t"
188@end group
189@group
190(buffer-substring (point-max) 10)
191 @result{} "he contents of buffer foo\n"
192@end group
193@end example
194
195If the text being copied has any text properties, these are copied into
196the string along with the characters they belong to. @xref{Text
197Properties}. However, overlays (@pxref{Overlays}) in the buffer and
198their properties are ignored, not copied.
199
200For example, if Font-Lock mode is enabled, you might get results like
201these:
202
203@example
204@group
205(buffer-substring 1 10)
206 @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t))
207@end group
208@end example
209@end defun
210
211@defun buffer-substring-no-properties start end
212This is like @code{buffer-substring}, except that it does not copy text
213properties, just the characters themselves. @xref{Text Properties}.
214@end defun
215
67cd45a2
CY
216@defun buffer-string
217This function returns the contents of the entire accessible portion of
84f4a531 218the current buffer, as a string.
67cd45a2
CY
219@end defun
220
34c99998 221@defun filter-buffer-substring start end &optional delete
b8d4c8d0 222This function passes the buffer text between @var{start} and @var{end}
34c99998 223through the filter functions specified by the wrapper hook
67cd45a2
CY
224@code{filter-buffer-substring-functions}, and returns the result. The
225obsolete variable @code{buffer-substring-filters} is also consulted.
226If both of these variables are @code{nil}, the value is the unaltered
1df7defd 227text from the buffer, i.e., what @code{buffer-substring} would
67cd45a2 228return.
b8d4c8d0
GM
229
230If @var{delete} is non-@code{nil}, this function deletes the text
231between @var{start} and @var{end} after copying it, like
232@code{delete-and-extract-region}.
233
b8d4c8d0
GM
234Lisp code should use this function instead of @code{buffer-substring},
235@code{buffer-substring-no-properties},
236or @code{delete-and-extract-region} when copying into user-accessible
237data structures such as the kill-ring, X clipboard, and registers.
238Major and minor modes can add functions to
34c99998
GM
239@code{filter-buffer-substring-functions} to alter such text as it is
240copied out of the buffer.
b8d4c8d0
GM
241@end defun
242
2bede2ed 243@c FIXME: `filter-buffer-substring-function' should be documented.
34c99998
GM
244@defvar filter-buffer-substring-functions
245This variable is a wrapper hook (@pxref{Running Hooks}), whose members
246should be functions that accept four arguments: @var{fun},
247@var{start}, @var{end}, and @var{delete}. @var{fun} is a function
248that takes three arguments (@var{start}, @var{end}, and @var{delete}),
249and returns a string. In both cases, the @var{start}, @var{end}, and
250@var{delete} arguments are the same as those of
251@code{filter-buffer-substring}.
252
253The first hook function is passed a @var{fun} that is equivalent to
1df7defd 254the default operation of @code{filter-buffer-substring}, i.e., it
34c99998
GM
255returns the buffer-substring between @var{start} and @var{end}
256(processed by any @code{buffer-substring-filters}) and optionally
257deletes the original text from the buffer. In most cases, the hook
258function will call @var{fun} once, and then do its own processing of
259the result. The next hook function receives a @var{fun} equivalent to
260this, and so on. The actual return value is the result of all the
261hook functions acting in sequence.
b8d4c8d0
GM
262@end defvar
263
67cd45a2
CY
264@defvar buffer-substring-filters
265This variable is obsoleted by
266@code{filter-buffer-substring-functions}, but is still supported for
267backward compatibility. Its value should should be a list of
268functions which accept a single string argument and return another
269string. @code{filter-buffer-substring} passes the buffer substring to
270the first function in this list, and the return value of each function
271is passed to the next function. The return value of the last function
272is passed to @code{filter-buffer-substring-functions}.
273@end defvar
b8d4c8d0
GM
274
275@defun current-word &optional strict really-word
67cd45a2
CY
276This function returns the symbol (or word) at or near point, as a
277string. The return value includes no text properties.
b8d4c8d0
GM
278
279If the optional argument @var{really-word} is non-@code{nil}, it finds a
280word; otherwise, it finds a symbol (which includes both word
281characters and symbol constituent characters).
282
283If the optional argument @var{strict} is non-@code{nil}, then point
284must be in or next to the symbol or word---if no symbol or word is
285there, the function returns @code{nil}. Otherwise, a nearby symbol or
286word on the same line is acceptable.
287@end defun
288
289@defun thing-at-point thing
290Return the @var{thing} around or next to point, as a string.
291
292The argument @var{thing} is a symbol which specifies a kind of syntactic
293entity. Possibilities include @code{symbol}, @code{list}, @code{sexp},
294@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
295@code{whitespace}, @code{line}, @code{page}, and others.
296
297@example
298---------- Buffer: foo ----------
299Gentlemen may cry ``Pea@point{}ce! Peace!,''
300but there is no peace.
301---------- Buffer: foo ----------
302
303(thing-at-point 'word)
304 @result{} "Peace"
305(thing-at-point 'line)
306 @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
307(thing-at-point 'whitespace)
308 @result{} nil
309@end example
310@end defun
311
312@node Comparing Text
313@section Comparing Text
314@cindex comparing buffer text
315
316 This function lets you compare portions of the text in a buffer, without
317copying them into strings first.
318
319@defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
320This function lets you compare two substrings of the same buffer or two
321different buffers. The first three arguments specify one substring,
322giving a buffer (or a buffer name) and two positions within the
323buffer. The last three arguments specify the other substring in the
324same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or
325both to stand for the current buffer.
326
327The value is negative if the first substring is less, positive if the
328first is greater, and zero if they are equal. The absolute value of
329the result is one plus the index of the first differing characters
330within the substrings.
331
332This function ignores case when comparing characters
333if @code{case-fold-search} is non-@code{nil}. It always ignores
334text properties.
335
336Suppose the current buffer contains the text @samp{foobarbar
337haha!rara!}; then in this example the two substrings are @samp{rbar }
338and @samp{rara!}. The value is 2 because the first substring is greater
339at the second character.
340
341@example
342(compare-buffer-substrings nil 6 11 nil 16 21)
343 @result{} 2
344@end example
345@end defun
346
347@node Insertion
348@section Inserting Text
349@cindex insertion of text
350@cindex text insertion
351
352@cindex insertion before point
353@cindex before point, insertion
354 @dfn{Insertion} means adding new text to a buffer. The inserted text
355goes at point---between the character before point and the character
356after point. Some insertion functions leave point before the inserted
357text, while other functions leave it after. We call the former
358insertion @dfn{after point} and the latter insertion @dfn{before point}.
359
568f7b79
LMI
360 Insertion moves markers located at positions after the insertion
361point, so that they stay with the surrounding text (@pxref{Markers}).
362When a marker points at the place of insertion, insertion may or may
363not relocate the marker, depending on the marker's insertion type
364(@pxref{Marker Insertion Types}). Certain special functions such as
365@code{insert-before-markers} relocate all such markers to point after
366the inserted text, regardless of the markers' insertion type.
b8d4c8d0
GM
367
368 Insertion functions signal an error if the current buffer is
8b8bf4a3
XF
369read-only (@pxref{Read Only Buffers}) or if they insert within
370read-only text (@pxref{Special Properties}).
b8d4c8d0
GM
371
372 These functions copy text characters from strings and buffers along
373with their properties. The inserted characters have exactly the same
374properties as the characters they were copied from. By contrast,
375characters specified as separate arguments, not part of a string or
376buffer, inherit their text properties from the neighboring text.
377
378 The insertion functions convert text from unibyte to multibyte in
379order to insert in a multibyte buffer, and vice versa---if the text
380comes from a string or from a buffer. However, they do not convert
381unibyte character codes 128 through 255 to multibyte characters, not
382even if the current buffer is a multibyte buffer. @xref{Converting
383Representations}.
384
385@defun insert &rest args
386This function inserts the strings and/or characters @var{args} into the
387current buffer, at point, moving point forward. In other words, it
388inserts the text before point. An error is signaled unless all
389@var{args} are either strings or characters. The value is @code{nil}.
390@end defun
391
392@defun insert-before-markers &rest args
393This function inserts the strings and/or characters @var{args} into the
394current buffer, at point, moving point forward. An error is signaled
395unless all @var{args} are either strings or characters. The value is
396@code{nil}.
397
398This function is unlike the other insertion functions in that it
399relocates markers initially pointing at the insertion point, to point
400after the inserted text. If an overlay begins at the insertion point,
401the inserted text falls outside the overlay; if a nonempty overlay
402ends at the insertion point, the inserted text falls inside that
403overlay.
404@end defun
405
9ea10cc3
CY
406@deffn Command insert-char character &optional count inherit
407This command inserts @var{count} instances of @var{character} into the
408current buffer before point. The argument @var{count} must be an
409integer, and @var{character} must be a character.
410
411If called interactively, this command prompts for @var{character}
412using its Unicode name or its code point. @xref{Inserting Text,,,
413emacs, The GNU Emacs Manual}.
b8d4c8d0
GM
414
415This function does not convert unibyte character codes 128 through 255
416to multibyte characters, not even if the current buffer is a multibyte
417buffer. @xref{Converting Representations}.
418
9ea10cc3 419If @var{inherit} is non-@code{nil}, the inserted characters inherit
b8d4c8d0
GM
420sticky text properties from the two characters before and after the
421insertion point. @xref{Sticky Properties}.
9ea10cc3 422@end deffn
b8d4c8d0
GM
423
424@defun insert-buffer-substring from-buffer-or-name &optional start end
425This function inserts a portion of buffer @var{from-buffer-or-name}
c8068af5
XF
426into the current buffer before point. The text inserted is the region
427between @var{start} (inclusive) and @var{end} (exclusive). (These
428arguments default to the beginning and end of the accessible portion
429of that buffer.) This function returns @code{nil}.
b8d4c8d0
GM
430
431In this example, the form is executed with buffer @samp{bar} as the
432current buffer. We assume that buffer @samp{bar} is initially empty.
433
434@example
435@group
436---------- Buffer: foo ----------
437We hold these truths to be self-evident, that all
438---------- Buffer: foo ----------
439@end group
440
441@group
442(insert-buffer-substring "foo" 1 20)
443 @result{} nil
444
445---------- Buffer: bar ----------
446We hold these truth@point{}
447---------- Buffer: bar ----------
448@end group
449@end example
450@end defun
451
452@defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
453This is like @code{insert-buffer-substring} except that it does not
454copy any text properties.
455@end defun
456
457 @xref{Sticky Properties}, for other insertion functions that inherit
458text properties from the nearby text in addition to inserting it.
459Whitespace inserted by indentation functions also inherits text
460properties.
461
462@node Commands for Insertion
463@section User-Level Insertion Commands
464
465 This section describes higher-level commands for inserting text,
466commands intended primarily for the user but useful also in Lisp
467programs.
468
469@deffn Command insert-buffer from-buffer-or-name
470This command inserts the entire accessible contents of
471@var{from-buffer-or-name} (which must exist) into the current buffer
472after point. It leaves the mark after the inserted text. The value
473is @code{nil}.
474@end deffn
475
476@deffn Command self-insert-command count
477@cindex character insertion
478@cindex self-insertion
479This command inserts the last character typed; it does so @var{count}
480times, before point, and returns @code{nil}. Most printing characters
481are bound to this command. In routine use, @code{self-insert-command}
482is the most frequently called function in Emacs, but programs rarely use
483it except to install it on a keymap.
484
485In an interactive call, @var{count} is the numeric prefix argument.
486
bd805d5b 487@c FIXME: This variable is obsolete since 23.1.
ab992d66
EZ
488Self-insertion translates the input character through
489@code{translation-table-for-input}. @xref{Translation of Characters}.
490
b8d4c8d0
GM
491This command calls @code{auto-fill-function} whenever that is
492non-@code{nil} and the character inserted is in the table
493@code{auto-fill-chars} (@pxref{Auto Filling}).
494
495@c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
496This command performs abbrev expansion if Abbrev mode is enabled and
497the inserted character does not have word-constituent
498syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also
499responsible for calling @code{blink-paren-function} when the inserted
500character has close parenthesis syntax (@pxref{Blinking}).
501
f58b9822
GM
502@vindex post-self-insert-hook
503The final thing this command does is to run the hook
504@code{post-self-insert-hook}. You could use this to automatically
505reindent text as it is typed, for example.
506
b8d4c8d0
GM
507Do not try substituting your own definition of
508@code{self-insert-command} for the standard one. The editor command
509loop handles this function specially.
510@end deffn
511
512@deffn Command newline &optional number-of-newlines
513This command inserts newlines into the current buffer before point.
514If @var{number-of-newlines} is supplied, that many newline characters
515are inserted.
516
517@cindex newline and Auto Fill mode
518This function calls @code{auto-fill-function} if the current column
519number is greater than the value of @code{fill-column} and
520@var{number-of-newlines} is @code{nil}. Typically what
521@code{auto-fill-function} does is insert a newline; thus, the overall
522result in this case is to insert two newlines at different places: one
523at point, and another earlier in the line. @code{newline} does not
524auto-fill if @var{number-of-newlines} is non-@code{nil}.
525
526This command indents to the left margin if that is not zero.
527@xref{Margins}.
528
529The value returned is @code{nil}. In an interactive call, @var{count}
530is the numeric prefix argument.
531@end deffn
532
533@defvar overwrite-mode
534This variable controls whether overwrite mode is in effect. The value
535should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
536or @code{nil}. @code{overwrite-mode-textual} specifies textual
537overwrite mode (treats newlines and tabs specially), and
538@code{overwrite-mode-binary} specifies binary overwrite mode (treats
539newlines and tabs like any other characters).
540@end defvar
541
542@node Deletion
543@section Deleting Text
544@cindex text deletion
545
546@cindex deleting text vs killing
547 Deletion means removing part of the text in a buffer, without saving
548it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be
549yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
550Some deletion functions do save text in the kill ring in some special
551cases.
552
553 All of the deletion functions operate on the current buffer.
554
555@deffn Command erase-buffer
556This function deletes the entire text of the current buffer
557(@emph{not} just the accessible portion), leaving it
558empty. If the buffer is read-only, it signals a @code{buffer-read-only}
559error; if some of the text in it is read-only, it signals a
560@code{text-read-only} error. Otherwise, it deletes the text without
561asking for any confirmation. It returns @code{nil}.
562
563Normally, deleting a large amount of text from a buffer inhibits further
16152b76 564auto-saving of that buffer ``because it has shrunk''. However,
b8d4c8d0
GM
565@code{erase-buffer} does not do this, the idea being that the future
566text is not really related to the former text, and its size should not
567be compared with that of the former text.
568@end deffn
569
570@deffn Command delete-region start end
571This command deletes the text between positions @var{start} and
572@var{end} in the current buffer, and returns @code{nil}. If point was
573inside the deleted region, its value afterward is @var{start}.
574Otherwise, point relocates with the surrounding text, as markers do.
575@end deffn
576
577@defun delete-and-extract-region start end
578This function deletes the text between positions @var{start} and
579@var{end} in the current buffer, and returns a string containing the
580text just deleted.
581
582If point was inside the deleted region, its value afterward is
583@var{start}. Otherwise, point relocates with the surrounding text, as
584markers do.
585@end defun
586
587@deffn Command delete-char count &optional killp
588This command deletes @var{count} characters directly after point, or
589before point if @var{count} is negative. If @var{killp} is
590non-@code{nil}, then it saves the deleted characters in the kill ring.
591
592In an interactive call, @var{count} is the numeric prefix argument, and
593@var{killp} is the unprocessed prefix argument. Therefore, if a prefix
594argument is supplied, the text is saved in the kill ring. If no prefix
595argument is supplied, then one character is deleted, but not saved in
596the kill ring.
597
598The value returned is always @code{nil}.
599@end deffn
600
601@deffn Command delete-backward-char count &optional killp
602@cindex deleting previous char
603This command deletes @var{count} characters directly before point, or
604after point if @var{count} is negative. If @var{killp} is
605non-@code{nil}, then it saves the deleted characters in the kill ring.
606
607In an interactive call, @var{count} is the numeric prefix argument, and
608@var{killp} is the unprocessed prefix argument. Therefore, if a prefix
609argument is supplied, the text is saved in the kill ring. If no prefix
610argument is supplied, then one character is deleted, but not saved in
611the kill ring.
612
613The value returned is always @code{nil}.
614@end deffn
615
616@deffn Command backward-delete-char-untabify count &optional killp
617@cindex tab deletion
618This command deletes @var{count} characters backward, changing tabs
619into spaces. When the next character to be deleted is a tab, it is
620first replaced with the proper number of spaces to preserve alignment
621and then one of those spaces is deleted instead of the tab. If
622@var{killp} is non-@code{nil}, then the command saves the deleted
623characters in the kill ring.
624
625Conversion of tabs to spaces happens only if @var{count} is positive.
626If it is negative, exactly @minus{}@var{count} characters after point
627are deleted.
628
629In an interactive call, @var{count} is the numeric prefix argument, and
630@var{killp} is the unprocessed prefix argument. Therefore, if a prefix
631argument is supplied, the text is saved in the kill ring. If no prefix
632argument is supplied, then one character is deleted, but not saved in
633the kill ring.
634
635The value returned is always @code{nil}.
636@end deffn
637
638@defopt backward-delete-char-untabify-method
639This option specifies how @code{backward-delete-char-untabify} should
640deal with whitespace. Possible values include @code{untabify}, the
641default, meaning convert a tab to many spaces and delete one;
642@code{hungry}, meaning delete all tabs and spaces before point with
643one command; @code{all} meaning delete all tabs, spaces and newlines
644before point, and @code{nil}, meaning do nothing special for
645whitespace characters.
646@end defopt
647
648@node User-Level Deletion
649@section User-Level Deletion Commands
650
651 This section describes higher-level commands for deleting text,
652commands intended primarily for the user but useful also in Lisp
653programs.
654
655@deffn Command delete-horizontal-space &optional backward-only
656@cindex deleting whitespace
657This function deletes all spaces and tabs around point. It returns
658@code{nil}.
659
660If @var{backward-only} is non-@code{nil}, the function deletes
661spaces and tabs before point, but not after point.
662
663In the following examples, we call @code{delete-horizontal-space} four
664times, once on each line, with point between the second and third
665characters on the line each time.
666
667@example
668@group
669---------- Buffer: foo ----------
670I @point{}thought
671I @point{} thought
672We@point{} thought
673Yo@point{}u thought
674---------- Buffer: foo ----------
675@end group
676
677@group
678(delete-horizontal-space) ; @r{Four times.}
679 @result{} nil
680
681---------- Buffer: foo ----------
682Ithought
683Ithought
684Wethought
685You thought
686---------- Buffer: foo ----------
687@end group
688@end example
689@end deffn
690
691@deffn Command delete-indentation &optional join-following-p
692This function joins the line point is on to the previous line, deleting
693any whitespace at the join and in some cases replacing it with one
694space. If @var{join-following-p} is non-@code{nil},
695@code{delete-indentation} joins this line to the following line
696instead. The function returns @code{nil}.
697
698If there is a fill prefix, and the second of the lines being joined
699starts with the prefix, then @code{delete-indentation} deletes the
700fill prefix before joining the lines. @xref{Margins}.
701
702In the example below, point is located on the line starting
703@samp{events}, and it makes no difference if there are trailing spaces
704in the preceding line.
705
706@smallexample
707@group
708---------- Buffer: foo ----------
709When in the course of human
710@point{} events, it becomes necessary
711---------- Buffer: foo ----------
712@end group
713
714(delete-indentation)
715 @result{} nil
716
717@group
718---------- Buffer: foo ----------
719When in the course of human@point{} events, it becomes necessary
720---------- Buffer: foo ----------
721@end group
722@end smallexample
723
724After the lines are joined, the function @code{fixup-whitespace} is
725responsible for deciding whether to leave a space at the junction.
726@end deffn
727
728@deffn Command fixup-whitespace
729This function replaces all the horizontal whitespace surrounding point
730with either one space or no space, according to the context. It
731returns @code{nil}.
732
733At the beginning or end of a line, the appropriate amount of space is
734none. Before a character with close parenthesis syntax, or after a
735character with open parenthesis or expression-prefix syntax, no space is
736also appropriate. Otherwise, one space is appropriate. @xref{Syntax
737Class Table}.
738
739In the example below, @code{fixup-whitespace} is called the first time
740with point before the word @samp{spaces} in the first line. For the
741second invocation, point is directly after the @samp{(}.
742
743@smallexample
744@group
745---------- Buffer: foo ----------
746This has too many @point{}spaces
747This has too many spaces at the start of (@point{} this list)
748---------- Buffer: foo ----------
749@end group
750
751@group
752(fixup-whitespace)
753 @result{} nil
754(fixup-whitespace)
755 @result{} nil
756@end group
757
758@group
759---------- Buffer: foo ----------
760This has too many spaces
761This has too many spaces at the start of (this list)
762---------- Buffer: foo ----------
763@end group
764@end smallexample
765@end deffn
766
767@deffn Command just-one-space &optional n
768@comment !!SourceFile simple.el
769This command replaces any spaces and tabs around point with a single
770space, or @var{n} spaces if @var{n} is specified. It returns
771@code{nil}.
772@end deffn
773
774@deffn Command delete-blank-lines
775This function deletes blank lines surrounding point. If point is on a
776blank line with one or more blank lines before or after it, then all but
777one of them are deleted. If point is on an isolated blank line, then it
778is deleted. If point is on a nonblank line, the command deletes all
779blank lines immediately following it.
780
781A blank line is defined as a line containing only tabs and spaces.
7bef426b 782@c and the Newline character?
b8d4c8d0
GM
783
784@code{delete-blank-lines} returns @code{nil}.
785@end deffn
786
787@node The Kill Ring
788@section The Kill Ring
789@cindex kill ring
790
791 @dfn{Kill functions} delete text like the deletion functions, but save
792it so that the user can reinsert it by @dfn{yanking}. Most of these
793functions have @samp{kill-} in their name. By contrast, the functions
794whose names start with @samp{delete-} normally do not save text for
795yanking (though they can still be undone); these are ``deletion''
796functions.
797
798 Most of the kill commands are primarily for interactive use, and are
799not described here. What we do describe are the functions provided for
800use in writing such commands. You can use these functions to write
801commands for killing text. When you need to delete text for internal
802purposes within a Lisp function, you should normally use deletion
803functions, so as not to disturb the kill ring contents.
804@xref{Deletion}.
805
806 Killed text is saved for later yanking in the @dfn{kill ring}. This
807is a list that holds a number of recent kills, not just the last text
808kill. We call this a ``ring'' because yanking treats it as having
809elements in a cyclic order. The list is kept in the variable
810@code{kill-ring}, and can be operated on with the usual functions for
811lists; there are also specialized functions, described in this section,
812that treat it as a ring.
813
814 Some people think this use of the word ``kill'' is unfortunate, since
815it refers to operations that specifically @emph{do not} destroy the
16152b76 816entities ``killed''. This is in sharp contrast to ordinary life, in
b8d4c8d0
GM
817which death is permanent and ``killed'' entities do not come back to
818life. Therefore, other metaphors have been proposed. For example, the
819term ``cut ring'' makes sense to people who, in pre-computer days, used
820scissors and paste to cut up and rearrange manuscripts. However, it
821would be difficult to change the terminology now.
822
823@menu
824* Kill Ring Concepts:: What text looks like in the kill ring.
825* Kill Functions:: Functions that kill text.
826* Yanking:: How yanking is done.
827* Yank Commands:: Commands that access the kill ring.
d24880de 828* Low-Level Kill Ring:: Functions and variables for kill ring access.
b8d4c8d0
GM
829* Internals of Kill Ring:: Variables that hold kill ring data.
830@end menu
831
832@node Kill Ring Concepts
b8d4c8d0
GM
833@subsection Kill Ring Concepts
834
835 The kill ring records killed text as strings in a list, most recent
836first. A short kill ring, for example, might look like this:
837
838@example
839("some text" "a different piece of text" "even older text")
840@end example
841
842@noindent
843When the list reaches @code{kill-ring-max} entries in length, adding a
844new entry automatically deletes the last entry.
845
846 When kill commands are interwoven with other commands, each kill
847command makes a new entry in the kill ring. Multiple kill commands in
848succession build up a single kill ring entry, which would be yanked as a
849unit; the second and subsequent consecutive kill commands add text to
850the entry made by the first one.
851
852 For yanking, one entry in the kill ring is designated the ``front'' of
853the ring. Some yank commands ``rotate'' the ring by designating a
16152b76 854different element as the ``front''. But this virtual rotation doesn't
b8d4c8d0
GM
855change the list itself---the most recent entry always comes first in the
856list.
857
858@node Kill Functions
b8d4c8d0
GM
859@subsection Functions for Killing
860
861 @code{kill-region} is the usual subroutine for killing text. Any
862command that calls this function is a ``kill command'' (and should
863probably have @samp{kill} in its name). @code{kill-region} puts the
864newly killed text in a new element at the beginning of the kill ring or
865adds it to the most recent element. It determines automatically (using
866@code{last-command}) whether the previous command was a kill command,
867and if so appends the killed text to the most recent entry.
868
ec8a6295 869@deffn Command kill-region start end
b8d4c8d0
GM
870This function kills the text in the region defined by @var{start} and
871@var{end}. The text is deleted but saved in the kill ring, along with
872its text properties. The value is always @code{nil}.
873
874In an interactive call, @var{start} and @var{end} are point and
875the mark.
876
b8d4c8d0
GM
877If the buffer or text is read-only, @code{kill-region} modifies the kill
878ring just the same, then signals an error without modifying the buffer.
879This is convenient because it lets the user use a series of kill
880commands to copy text from a read-only buffer into the kill ring.
b8d4c8d0
GM
881@end deffn
882
883@defopt kill-read-only-ok
884If this option is non-@code{nil}, @code{kill-region} does not signal an
885error if the buffer or text is read-only. Instead, it simply returns,
886updating the kill ring but not changing the buffer.
887@end defopt
888
889@deffn Command copy-region-as-kill start end
890This command saves the region defined by @var{start} and @var{end} on
891the kill ring (including text properties), but does not delete the text
892from the buffer. It returns @code{nil}.
893
894The command does not set @code{this-command} to @code{kill-region}, so a
895subsequent kill command does not append to the same kill ring entry.
896
cde08ac9
GM
897@c FIXME Why is it better? Why isn't copy-region-as-kill obsolete then?
898@c Why is it used in many places in Emacs?
899In Lisp programs, it is better to use @code{kill-new} or
900@code{kill-append} instead of this command. @xref{Low-Level Kill Ring}.
b8d4c8d0
GM
901@end deffn
902
903@node Yanking
904@subsection Yanking
905
05b621a6
CY
906 Yanking means inserting text from the kill ring, but it does not
907insert the text blindly. The @code{yank} command, and related
908commands, use @code{insert-for-yank} to perform special processing on
909the text before it is inserted.
b8d4c8d0
GM
910
911@defun insert-for-yank string
05b621a6
CY
912This function works like @code{insert}, except that it processes the
913text in @var{string} according to the @code{yank-handler} text
914property, as well as the variables @code{yank-handled-properties} and
915@code{yank-excluded-properties} (see below), before inserting the
916result into the current buffer.
b8d4c8d0
GM
917@end defun
918
919@defun insert-buffer-substring-as-yank buf &optional start end
05b621a6
CY
920This function resembles @code{insert-buffer-substring}, except that it
921processes the text according to @code{yank-handled-properties} and
922@code{yank-excluded-properties}. (It does not handle the
923@code{yank-handler} property, which does not normally occur in buffer
924text anyway.)
b8d4c8d0
GM
925@end defun
926
90769946 927@c FIXME: Add an index for yank-handler.
05b621a6
CY
928 If you put a @code{yank-handler} text property on all or part of a
929string, that alters how @code{insert-for-yank} inserts the string. If
930different parts of the string have different @code{yank-handler}
931values (comparison being done with @code{eq}), each substring is
932handled separately. The property value must be a list of one to four
933elements, with the following format (where elements after the first
934may be omitted):
b8d4c8d0
GM
935
936@example
937(@var{function} @var{param} @var{noexclude} @var{undo})
938@end example
939
940 Here is what the elements do:
941
942@table @var
943@item function
05b621a6
CY
944When @var{function} is non-@code{nil}, it is called instead of
945@code{insert} to insert the string, with one argument---the string to
946insert.
b8d4c8d0
GM
947
948@item param
949If @var{param} is present and non-@code{nil}, it replaces @var{string}
05b621a6
CY
950(or the substring of @var{string} being processed) as the object
951passed to @var{function} (or @code{insert}). For example, if
952@var{function} is @code{yank-rectangle}, @var{param} should be a list
953of strings to insert as a rectangle.
b8d4c8d0
GM
954
955@item noexclude
05b621a6
CY
956If @var{noexclude} is present and non-@code{nil}, that disables the
957normal action of @code{yank-handled-properties} and
958@code{yank-excluded-properties} on the inserted string.
b8d4c8d0
GM
959
960@item undo
961If @var{undo} is present and non-@code{nil}, it is a function that will be
962called by @code{yank-pop} to undo the insertion of the current object.
963It is called with two arguments, the start and end of the current
964region. @var{function} can set @code{yank-undo-function} to override
965the @var{undo} value.
966@end table
967
50b063c3 968@cindex yanking and text properties
05b621a6
CY
969@defopt yank-handled-properties
970This variable specifies special text property handling conditions for
971yanked text. It takes effect after the text has been inserted (either
972normally, or via the @code{yank-handler} property), and prior to
973@code{yank-excluded-properties} taking effect.
974
975The value should be an alist of elements @code{(@var{prop}
976. @var{fun})}. Each alist element is handled in order. The inserted
977text is scanned for stretches of text having text properties @code{eq}
978to @var{prop}; for each such stretch, @var{fun} is called with three
979arguments: the value of the property, and the start and end positions
980of the text.
981@end defopt
982
50b063c3 983@defopt yank-excluded-properties
05b621a6
CY
984The value of this variable is the list of properties to remove from
985inserted text. Its default value contains properties that might lead
986to annoying results, such as causing the text to respond to the mouse
987or specifying key bindings. It takes effect after
988@code{yank-handled-properties}.
50b063c3
CY
989@end defopt
990
05b621a6 991
b8d4c8d0 992@node Yank Commands
b8d4c8d0
GM
993@subsection Functions for Yanking
994
995 This section describes higher-level commands for yanking, which are
996intended primarily for the user but useful also in Lisp programs.
997Both @code{yank} and @code{yank-pop} honor the
998@code{yank-excluded-properties} variable and @code{yank-handler} text
999property (@pxref{Yanking}).
1000
1001@deffn Command yank &optional arg
1002@cindex inserting killed text
2bad3299
CY
1003This command inserts before point the text at the front of the kill
1004ring. It sets the mark at the beginning of that text, using
1005@code{push-mark} (@pxref{The Mark}), and puts point at the end.
b8d4c8d0
GM
1006
1007If @var{arg} is a non-@code{nil} list (which occurs interactively when
1008the user types @kbd{C-u} with no digits), then @code{yank} inserts the
1009text as described above, but puts point before the yanked text and
2bad3299 1010sets the mark after it.
b8d4c8d0
GM
1011
1012If @var{arg} is a number, then @code{yank} inserts the @var{arg}th
1013most recently killed text---the @var{arg}th element of the kill ring
1014list, counted cyclically from the front, which is considered the
1015first element for this purpose.
1016
1017@code{yank} does not alter the contents of the kill ring, unless it
1018used text provided by another program, in which case it pushes that text
1019onto the kill ring. However if @var{arg} is an integer different from
1020one, it rotates the kill ring to place the yanked string at the front.
1021
1022@code{yank} returns @code{nil}.
1023@end deffn
1024
1025@deffn Command yank-pop &optional arg
1026This command replaces the just-yanked entry from the kill ring with a
1027different entry from the kill ring.
1028
1029This is allowed only immediately after a @code{yank} or another
1030@code{yank-pop}. At such a time, the region contains text that was just
1031inserted by yanking. @code{yank-pop} deletes that text and inserts in
1032its place a different piece of killed text. It does not add the deleted
1033text to the kill ring, since it is already in the kill ring somewhere.
1034It does however rotate the kill ring to place the newly yanked string at
1035the front.
1036
1037If @var{arg} is @code{nil}, then the replacement text is the previous
1038element of the kill ring. If @var{arg} is numeric, the replacement is
1039the @var{arg}th previous kill. If @var{arg} is negative, a more recent
1040kill is the replacement.
1041
1042The sequence of kills in the kill ring wraps around, so that after the
1043oldest one comes the newest one, and before the newest one goes the
1044oldest.
1045
1046The return value is always @code{nil}.
1047@end deffn
1048
1049@defvar yank-undo-function
1050If this variable is non-@code{nil}, the function @code{yank-pop} uses
1051its value instead of @code{delete-region} to delete the text
1052inserted by the previous @code{yank} or
1053@code{yank-pop} command. The value must be a function of two
1054arguments, the start and end of the current region.
1055
1056The function @code{insert-for-yank} automatically sets this variable
1057according to the @var{undo} element of the @code{yank-handler}
1058text property, if there is one.
1059@end defvar
1060
1061@node Low-Level Kill Ring
1062@subsection Low-Level Kill Ring
1063
1064 These functions and variables provide access to the kill ring at a
cde08ac9
GM
1065lower level, but are still convenient for use in Lisp programs,
1066because they take care of interaction with window system selections
b8d4c8d0
GM
1067(@pxref{Window System Selections}).
1068
1069@defun current-kill n &optional do-not-move
1070The function @code{current-kill} rotates the yanking pointer, which
1071designates the ``front'' of the kill ring, by @var{n} places (from newer
1072kills to older ones), and returns the text at that place in the ring.
1073
1074If the optional second argument @var{do-not-move} is non-@code{nil},
1075then @code{current-kill} doesn't alter the yanking pointer; it just
1076returns the @var{n}th kill, counting from the current yanking pointer.
1077
1078If @var{n} is zero, indicating a request for the latest kill,
1079@code{current-kill} calls the value of
1080@code{interprogram-paste-function} (documented below) before
1081consulting the kill ring. If that value is a function and calling it
8e8c1a72
EZ
1082returns a string or a list of several string, @code{current-kill}
1083pushes the strings onto the kill ring and returns the first string.
a053dae0
EZ
1084It also sets the yanking pointer to point to the kill-ring entry of
1085the first string returned by @code{interprogram-paste-function},
8e8c1a72
EZ
1086regardless of the value of @var{do-not-move}. Otherwise,
1087@code{current-kill} does not treat a zero value for @var{n} specially:
1088it returns the entry pointed at by the yanking pointer and does not
1089move the yanking pointer.
b8d4c8d0
GM
1090@end defun
1091
ec8a6295 1092@defun kill-new string &optional replace
b8d4c8d0
GM
1093This function pushes the text @var{string} onto the kill ring and
1094makes the yanking pointer point to it. It discards the oldest entry
1095if appropriate. It also invokes the value of
1096@code{interprogram-cut-function} (see below).
1097
1098If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the
1099first element of the kill ring with @var{string}, rather than pushing
1100@var{string} onto the kill ring.
b8d4c8d0
GM
1101@end defun
1102
ec8a6295 1103@defun kill-append string before-p
b8d4c8d0
GM
1104This function appends the text @var{string} to the first entry in the
1105kill ring and makes the yanking pointer point to the combined entry.
1106Normally @var{string} goes at the end of the entry, but if
1107@var{before-p} is non-@code{nil}, it goes at the beginning. This
1108function also invokes the value of @code{interprogram-cut-function}
ec8a6295 1109(see below).
b8d4c8d0
GM
1110@end defun
1111
1112@defvar interprogram-paste-function
1113This variable provides a way of transferring killed text from other
1114programs, when you are using a window system. Its value should be
1115@code{nil} or a function of no arguments.
1116
1117If the value is a function, @code{current-kill} calls it to get the
16152b76
GM
1118``most recent kill''. If the function returns a non-@code{nil} value,
1119then that value is used as the ``most recent kill''. If it returns
b8d4c8d0
GM
1120@code{nil}, then the front of the kill ring is used.
1121
8e8c1a72
EZ
1122To facilitate support for window systems that support multiple
1123selections, this function may also return a list of strings. In that
1124case, the first string is used as the ``most recent kill'', and all
1125the other strings are pushed onto the kill ring, for easy access by
1126@code{yank-pop}.
1127
67cd45a2
CY
1128The normal use of this function is to get the window system's
1129clipboard as the most recent kill, even if the selection belongs to
8e8c1a72 1130another application. @xref{Window System Selections}. However, if
67cd45a2
CY
1131the clipboard contents come from the current Emacs session, this
1132function should return @code{nil}.
b8d4c8d0
GM
1133@end defvar
1134
1135@defvar interprogram-cut-function
1136This variable provides a way of communicating killed text to other
1137programs, when you are using a window system. Its value should be
45240125 1138@code{nil} or a function of one required argument.
b8d4c8d0
GM
1139
1140If the value is a function, @code{kill-new} and @code{kill-append} call
45240125 1141it with the new first element of the kill ring as the argument.
b8d4c8d0 1142
67cd45a2
CY
1143The normal use of this function is to put newly killed text in the
1144window system's clipboard. @xref{Window System Selections}.
b8d4c8d0
GM
1145@end defvar
1146
1147@node Internals of Kill Ring
b8d4c8d0
GM
1148@subsection Internals of the Kill Ring
1149
1150 The variable @code{kill-ring} holds the kill ring contents, in the
1151form of a list of strings. The most recent kill is always at the front
1152of the list.
1153
1154 The @code{kill-ring-yank-pointer} variable points to a link in the
1155kill ring list, whose @sc{car} is the text to yank next. We say it
1156identifies the ``front'' of the ring. Moving
1157@code{kill-ring-yank-pointer} to a different link is called
1158@dfn{rotating the kill ring}. We call the kill ring a ``ring'' because
1159the functions that move the yank pointer wrap around from the end of the
1160list to the beginning, or vice-versa. Rotation of the kill ring is
1161virtual; it does not change the value of @code{kill-ring}.
1162
1163 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
1164variables whose values are normally lists. The word ``pointer'' in the
1165name of the @code{kill-ring-yank-pointer} indicates that the variable's
1166purpose is to identify one element of the list for use by the next yank
1167command.
1168
1169 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
1170of the links in the kill ring list. The element it identifies is the
1171@sc{car} of that link. Kill commands, which change the kill ring, also
1172set this variable to the value of @code{kill-ring}. The effect is to
1173rotate the ring so that the newly killed text is at the front.
1174
1175 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
1176pointing to the second entry in the kill ring @code{("some text" "a
1177different piece of text" "yet older text")}.
1178
1179@example
1180@group
1181kill-ring ---- kill-ring-yank-pointer
1182 | |
1183 | v
1184 | --- --- --- --- --- ---
1185 --> | | |------> | | |--> | | |--> nil
1186 --- --- --- --- --- ---
1187 | | |
1188 | | |
1189 | | -->"yet older text"
1190 | |
1191 | --> "a different piece of text"
1192 |
1193 --> "some text"
1194@end group
1195@end example
1196
1197@noindent
1198This state of affairs might occur after @kbd{C-y} (@code{yank})
1199immediately followed by @kbd{M-y} (@code{yank-pop}).
1200
1201@defvar kill-ring
1202This variable holds the list of killed text sequences, most recently
1203killed first.
1204@end defvar
1205
1206@defvar kill-ring-yank-pointer
1207This variable's value indicates which element of the kill ring is at the
1208``front'' of the ring for yanking. More precisely, the value is a tail
1209of the value of @code{kill-ring}, and its @sc{car} is the kill string
1210that @kbd{C-y} should yank.
1211@end defvar
1212
1213@defopt kill-ring-max
1214The value of this variable is the maximum length to which the kill
1215ring can grow, before elements are thrown away at the end. The default
1216value for @code{kill-ring-max} is 60.
1217@end defopt
1218
1219@node Undo
b8d4c8d0
GM
1220@section Undo
1221@cindex redo
1222
1223 Most buffers have an @dfn{undo list}, which records all changes made
1224to the buffer's text so that they can be undone. (The buffers that
1225don't have one are usually special-purpose buffers for which Emacs
1226assumes that undoing is not useful. In particular, any buffer whose
1227name begins with a space has its undo recording off by default;
1228see @ref{Buffer Names}.) All the primitives that modify the
1229text in the buffer automatically add elements to the front of the undo
1230list, which is in the variable @code{buffer-undo-list}.
1231
1232@defvar buffer-undo-list
1233This buffer-local variable's value is the undo list of the current
254408ca 1234buffer. A value of @code{t} disables the recording of undo information.
b8d4c8d0
GM
1235@end defvar
1236
1237Here are the kinds of elements an undo list can have:
1238
1239@table @code
1240@item @var{position}
1241This kind of element records a previous value of point; undoing this
1242element moves point to @var{position}. Ordinary cursor motion does not
1243make any sort of undo record, but deletion operations use these entries
1244to record where point was before the command.
1245
1246@item (@var{beg} . @var{end})
1247This kind of element indicates how to delete text that was inserted.
1248Upon insertion, the text occupied the range @var{beg}--@var{end} in the
1249buffer.
1250
1251@item (@var{text} . @var{position})
1252This kind of element indicates how to reinsert text that was deleted.
1253The deleted text itself is the string @var{text}. The place to
1254reinsert it is @code{(abs @var{position})}. If @var{position} is
1255positive, point was at the beginning of the deleted text, otherwise it
1256was at the end.
1257
954b166e 1258@item (t . @var{time-flag})
b8d4c8d0 1259This kind of element indicates that an unmodified buffer became
954b166e
PE
1260modified. A @var{time-flag} of the form
1261@code{(@var{sec-high} @var{sec-low} @var{microsec}
c4132fd4
PE
1262@var{picosec})} represents the visited file's modification time as of
1263when it was previously visited or saved, using the same format as
954b166e
PE
1264@code{current-time}; see @ref{Time of Day}.
1265A @var{time-flag} of 0 means the buffer does not correspond to any file;
1266@minus{}1 means the visited file previously did not exist.
1267@code{primitive-undo} uses these
b8d4c8d0 1268values to determine whether to mark the buffer as unmodified once again;
954b166e 1269it does so only if the file's status matches that of @var{time-flag}.
b8d4c8d0
GM
1270
1271@item (nil @var{property} @var{value} @var{beg} . @var{end})
1272This kind of element records a change in a text property.
1273Here's how you might undo the change:
1274
1275@example
1276(put-text-property @var{beg} @var{end} @var{property} @var{value})
1277@end example
1278
1279@item (@var{marker} . @var{adjustment})
1280This kind of element records the fact that the marker @var{marker} was
1281relocated due to deletion of surrounding text, and that it moved
1282@var{adjustment} character positions. Undoing this element moves
1283@var{marker} @minus{} @var{adjustment} characters.
1284
1285@item (apply @var{funname} . @var{args})
1286This is an extensible undo item, which is undone by calling
1287@var{funname} with arguments @var{args}.
1288
1289@item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
1290This is an extensible undo item, which records a change limited to the
1291range @var{beg} to @var{end}, which increased the size of the buffer
70ff8240 1292by @var{delta} characters. It is undone by calling @var{funname} with
e4043ba0 1293arguments @var{args}.
b8d4c8d0
GM
1294
1295This kind of element enables undo limited to a region to determine
1296whether the element pertains to that region.
1297
1298@item nil
1299This element is a boundary. The elements between two boundaries are
1300called a @dfn{change group}; normally, each change group corresponds to
1301one keyboard command, and undo commands normally undo an entire group as
1302a unit.
1303@end table
1304
1305@defun undo-boundary
1306This function places a boundary element in the undo list. The undo
1307command stops at such a boundary, and successive undo commands undo
1308to earlier and earlier boundaries. This function returns @code{nil}.
1309
51422d6d
CY
1310The editor command loop automatically calls @code{undo-boundary} just
1311before executing each key sequence, so that each undo normally undoes
1312the effects of one command. As an exception, the command
1313@code{self-insert-command}, which produces self-inserting input
1314characters (@pxref{Commands for Insertion}), may remove the boundary
1315inserted by the command loop: a boundary is accepted for the first
1316such character, the next 19 consecutive self-inserting input
1317characters do not have boundaries, and then the 20th does; and so on
1318as long as the self-inserting characters continue. Hence, sequences
1319of consecutive character insertions can be undone as a group.
b8d4c8d0
GM
1320
1321All buffer modifications add a boundary whenever the previous undoable
1322change was made in some other buffer. This is to ensure that
1323each command makes a boundary in each buffer where it makes changes.
1324
1325Calling this function explicitly is useful for splitting the effects of
1326a command into more than one unit. For example, @code{query-replace}
1327calls @code{undo-boundary} after each replacement, so that the user can
1328undo individual replacements one by one.
1329@end defun
1330
1331@defvar undo-in-progress
1332This variable is normally @code{nil}, but the undo commands bind it to
1333@code{t}. This is so that various kinds of change hooks can tell when
1334they're being called for the sake of undoing.
1335@end defvar
1336
1337@defun primitive-undo count list
1338This is the basic function for undoing elements of an undo list.
1339It undoes the first @var{count} elements of @var{list}, returning
1340the rest of @var{list}.
1341
1342@code{primitive-undo} adds elements to the buffer's undo list when it
1343changes the buffer. Undo commands avoid confusion by saving the undo
1344list value at the beginning of a sequence of undo operations. Then the
1345undo operations use and update the saved value. The new elements added
1346by undoing are not part of this saved value, so they don't interfere with
1347continuing to undo.
1348
1349This function does not bind @code{undo-in-progress}.
1350@end defun
1351
1352@node Maintaining Undo
1353@section Maintaining Undo Lists
1354
1355 This section describes how to enable and disable undo information for
1356a given buffer. It also explains how the undo list is truncated
1357automatically so it doesn't get too big.
1358
1359 Recording of undo information in a newly created buffer is normally
1360enabled to start with; but if the buffer name starts with a space, the
1361undo recording is initially disabled. You can explicitly enable or
1362disable undo recording with the following two functions, or by setting
1363@code{buffer-undo-list} yourself.
1364
1365@deffn Command buffer-enable-undo &optional buffer-or-name
1366This command enables recording undo information for buffer
1367@var{buffer-or-name}, so that subsequent changes can be undone. If no
1368argument is supplied, then the current buffer is used. This function
1369does nothing if undo recording is already enabled in the buffer. It
1370returns @code{nil}.
1371
1372In an interactive call, @var{buffer-or-name} is the current buffer.
1373You cannot specify any other buffer.
1374@end deffn
1375
1376@deffn Command buffer-disable-undo &optional buffer-or-name
1377@cindex disabling undo
1378This function discards the undo list of @var{buffer-or-name}, and disables
1379further recording of undo information. As a result, it is no longer
1380possible to undo either previous changes or any subsequent changes. If
1381the undo list of @var{buffer-or-name} is already disabled, this function
1382has no effect.
1383
278d6dd0
XF
1384In an interactive call, BUFFER-OR-NAME is the current buffer. You
1385cannot specify any other buffer. This function returns @code{nil}.
b8d4c8d0
GM
1386@end deffn
1387
1388 As editing continues, undo lists get longer and longer. To prevent
1389them from using up all available memory space, garbage collection trims
1390them back to size limits you can set. (For this purpose, the ``size''
1391of an undo list measures the cons cells that make up the list, plus the
1392strings of deleted text.) Three variables control the range of acceptable
1393sizes: @code{undo-limit}, @code{undo-strong-limit} and
1394@code{undo-outer-limit}. In these variables, size is counted as the
1395number of bytes occupied, which includes both saved text and other
1396data.
1397
1398@defopt undo-limit
1399This is the soft limit for the acceptable size of an undo list. The
1400change group at which this size is exceeded is the last one kept.
1401@end defopt
1402
1403@defopt undo-strong-limit
1404This is the upper limit for the acceptable size of an undo list. The
1405change group at which this size is exceeded is discarded itself (along
1406with all older change groups). There is one exception: the very latest
1407change group is only discarded if it exceeds @code{undo-outer-limit}.
1408@end defopt
1409
1410@defopt undo-outer-limit
1411If at garbage collection time the undo info for the current command
1412exceeds this limit, Emacs discards the info and displays a warning.
1413This is a last ditch limit to prevent memory overflow.
1414@end defopt
1415
1416@defopt undo-ask-before-discard
1417If this variable is non-@code{nil}, when the undo info exceeds
1418@code{undo-outer-limit}, Emacs asks in the echo area whether to
1419discard the info. The default value is @code{nil}, which means to
1420discard it automatically.
1421
1422This option is mainly intended for debugging. Garbage collection is
1423inhibited while the question is asked, which means that Emacs might
1424leak memory if the user waits too long before answering the question.
1425@end defopt
1426
1427@node Filling
b8d4c8d0
GM
1428@section Filling
1429@cindex filling text
1430
1431 @dfn{Filling} means adjusting the lengths of lines (by moving the line
1432breaks) so that they are nearly (but no greater than) a specified
1433maximum width. Additionally, lines can be @dfn{justified}, which means
1434inserting spaces to make the left and/or right margins line up
1435precisely. The width is controlled by the variable @code{fill-column}.
1436For ease of reading, lines should be no longer than 70 or so columns.
1437
1438 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
1439automatically as you insert it, but changes to existing text may leave
1440it improperly filled. Then you must fill the text explicitly.
1441
1442 Most of the commands in this section return values that are not
1443meaningful. All the functions that do filling take note of the current
1444left margin, current right margin, and current justification style
1445(@pxref{Margins}). If the current justification style is
1446@code{none}, the filling functions don't actually do anything.
1447
1448 Several of the filling functions have an argument @var{justify}.
1449If it is non-@code{nil}, that requests some kind of justification. It
1450can be @code{left}, @code{right}, @code{full}, or @code{center}, to
1451request a specific style of justification. If it is @code{t}, that
1452means to use the current justification style for this part of the text
1453(see @code{current-justification}, below). Any other value is treated
1454as @code{full}.
1455
1456 When you call the filling functions interactively, using a prefix
1457argument implies the value @code{full} for @var{justify}.
1458
65ced25f 1459@deffn Command fill-paragraph &optional justify region
b8d4c8d0
GM
1460This command fills the paragraph at or after point. If
1461@var{justify} is non-@code{nil}, each line is justified as well.
1462It uses the ordinary paragraph motion commands to find paragraph
1463boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
2bad3299
CY
1464
1465When @var{region} is non-@code{nil}, then if Transient Mark mode is
1466enabled and the mark is active, this command calls @code{fill-region}
1467to fill all the paragraphs in the region, instead of filling only the
1468current paragraph. When this command is called interactively,
1469@var{region} is @code{t}.
b8d4c8d0
GM
1470@end deffn
1471
1472@deffn Command fill-region start end &optional justify nosqueeze to-eop
1473This command fills each of the paragraphs in the region from @var{start}
1474to @var{end}. It justifies as well if @var{justify} is
1475non-@code{nil}.
1476
1477If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1478other than line breaks untouched. If @var{to-eop} is non-@code{nil},
1479that means to keep filling to the end of the paragraph---or the next hard
1480newline, if @code{use-hard-newlines} is enabled (see below).
1481
1482The variable @code{paragraph-separate} controls how to distinguish
1483paragraphs. @xref{Standard Regexps}.
1484@end deffn
1485
1486@deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
1487This command fills each paragraph in the region according to its
1488individual fill prefix. Thus, if the lines of a paragraph were indented
1489with spaces, the filled paragraph will remain indented in the same
1490fashion.
1491
1492The first two arguments, @var{start} and @var{end}, are the beginning
1493and end of the region to be filled. The third and fourth arguments,
1494@var{justify} and @var{citation-regexp}, are optional. If
1495@var{justify} is non-@code{nil}, the paragraphs are justified as
1496well as filled. If @var{citation-regexp} is non-@code{nil}, it means the
1497function is operating on a mail message and therefore should not fill
1498the header lines. If @var{citation-regexp} is a string, it is used as
1499a regular expression; if it matches the beginning of a line, that line
1500is treated as a citation marker.
1501
f33650d8 1502@c FIXME: "That mode" is confusing. It isn't a major/minor mode.
b8d4c8d0
GM
1503Ordinarily, @code{fill-individual-paragraphs} regards each change in
1504indentation as starting a new paragraph. If
1505@code{fill-individual-varying-indent} is non-@code{nil}, then only
1506separator lines separate paragraphs. That mode can handle indented
1507paragraphs with additional indentation on the first line.
1508@end deffn
1509
1510@defopt fill-individual-varying-indent
1511This variable alters the action of @code{fill-individual-paragraphs} as
1512described above.
1513@end defopt
1514
1515@deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
1516This command considers a region of text as a single paragraph and fills
1517it. If the region was made up of many paragraphs, the blank lines
1518between paragraphs are removed. This function justifies as well as
1519filling when @var{justify} is non-@code{nil}.
1520
1521If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
1522other than line breaks untouched. If @var{squeeze-after} is
1523non-@code{nil}, it specifies a position in the region, and means don't
1524canonicalize spaces before that position.
1525
1526In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
1527choose a fill prefix by default. @xref{Adaptive Fill}.
1528@end deffn
1529
1530@deffn Command justify-current-line &optional how eop nosqueeze
1531This command inserts spaces between the words of the current line so
1532that the line ends exactly at @code{fill-column}. It returns
1533@code{nil}.
1534
1535The argument @var{how}, if non-@code{nil} specifies explicitly the style
1536of justification. It can be @code{left}, @code{right}, @code{full},
1537@code{center}, or @code{none}. If it is @code{t}, that means to do
1538follow specified justification style (see @code{current-justification},
1539below). @code{nil} means to do full justification.
1540
1541If @var{eop} is non-@code{nil}, that means do only left-justification
1542if @code{current-justification} specifies full justification. This is
1543used for the last line of a paragraph; even if the paragraph as a
1544whole is fully justified, the last line should not be.
1545
1546If @var{nosqueeze} is non-@code{nil}, that means do not change interior
1547whitespace.
1548@end deffn
1549
1550@defopt default-justification
1551This variable's value specifies the style of justification to use for
1552text that doesn't specify a style with a text property. The possible
1553values are @code{left}, @code{right}, @code{full}, @code{center}, or
1554@code{none}. The default value is @code{left}.
1555@end defopt
1556
1557@defun current-justification
1558This function returns the proper justification style to use for filling
1559the text around point.
1560
1561This returns the value of the @code{justification} text property at
1562point, or the variable @var{default-justification} if there is no such
1563text property. However, it returns @code{nil} rather than @code{none}
1564to mean ``don't justify''.
1565@end defun
1566
1567@defopt sentence-end-double-space
1568@anchor{Definition of sentence-end-double-space}
1569If this variable is non-@code{nil}, a period followed by just one space
1570does not count as the end of a sentence, and the filling functions
1571avoid breaking the line at such a place.
1572@end defopt
1573
1574@defopt sentence-end-without-period
1575If this variable is non-@code{nil}, a sentence can end without a
1576period. This is used for languages like Thai, where sentences end
1577with a double space but without a period.
1578@end defopt
1579
1580@defopt sentence-end-without-space
1581If this variable is non-@code{nil}, it should be a string of
1582characters that can end a sentence without following spaces.
1583@end defopt
1584
1585@defvar fill-paragraph-function
2bad3299
CY
1586This variable provides a way to override the filling of paragraphs.
1587If its value is non-@code{nil}, @code{fill-paragraph} calls this
1588function to do the work. If the function returns a non-@code{nil}
b8d4c8d0
GM
1589value, @code{fill-paragraph} assumes the job is done, and immediately
1590returns that value.
1591
1592The usual use of this feature is to fill comments in programming
1593language modes. If the function needs to fill a paragraph in the usual
1594way, it can do so as follows:
1595
1596@example
1597(let ((fill-paragraph-function nil))
1598 (fill-paragraph arg))
1599@end example
1600@end defvar
1601
2bad3299
CY
1602@defvar fill-forward-paragraph-function
1603This variable provides a way to override how the filling functions,
1604such as @code{fill-region} and @code{fill-paragraph}, move forward to
1605the next paragraph. Its value should be a function, which is called
1606with a single argument @var{n}, the number of paragraphs to move, and
1607should return the difference between @var{n} and the number of
1608paragraphs actually moved. The default value of this variable is
1609@code{forward-paragraph}. @xref{Paragraphs,,, emacs, The GNU Emacs
1610Manual}.
1611@end defvar
1612
b8d4c8d0
GM
1613@defvar use-hard-newlines
1614If this variable is non-@code{nil}, the filling functions do not delete
1615newlines that have the @code{hard} text property. These ``hard
c9b39934
XF
1616newlines'' act as paragraph separators. @xref{Hard and Soft
1617Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
b8d4c8d0
GM
1618@end defvar
1619
1620@node Margins
1621@section Margins for Filling
bd805d5b 1622@cindex margins, filling
b8d4c8d0
GM
1623
1624@defopt fill-prefix
1625This buffer-local variable, if non-@code{nil}, specifies a string of
1626text that appears at the beginning of normal text lines and should be
1627disregarded when filling them. Any line that fails to start with the
1628fill prefix is considered the start of a paragraph; so is any line
1629that starts with the fill prefix followed by additional whitespace.
1630Lines that start with the fill prefix but no additional whitespace are
1631ordinary text lines that can be filled together. The resulting filled
1632lines also start with the fill prefix.
1633
1634The fill prefix follows the left margin whitespace, if any.
1635@end defopt
1636
1637@defopt fill-column
1638This buffer-local variable specifies the maximum width of filled lines.
1639Its value should be an integer, which is a number of columns. All the
1640filling, justification, and centering commands are affected by this
1641variable, including Auto Fill mode (@pxref{Auto Filling}).
1642
1643As a practical matter, if you are writing text for other people to
1644read, you should set @code{fill-column} to no more than 70. Otherwise
1645the line will be too long for people to read comfortably, and this can
1646make the text seem clumsy.
b8d4c8d0 1647
4e3b4528
SM
1648The default value for @code{fill-column} is 70.
1649@end defopt
b8d4c8d0
GM
1650
1651@deffn Command set-left-margin from to margin
1652This sets the @code{left-margin} property on the text from @var{from} to
1653@var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
1654command also refills the region to fit the new margin.
1655@end deffn
1656
1657@deffn Command set-right-margin from to margin
1658This sets the @code{right-margin} property on the text from @var{from}
1659to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
1660this command also refills the region to fit the new margin.
1661@end deffn
1662
1663@defun current-left-margin
1664This function returns the proper left margin value to use for filling
1665the text around point. The value is the sum of the @code{left-margin}
1666property of the character at the start of the current line (or zero if
1667none), and the value of the variable @code{left-margin}.
1668@end defun
1669
1670@defun current-fill-column
1671This function returns the proper fill column value to use for filling
1672the text around point. The value is the value of the @code{fill-column}
1673variable, minus the value of the @code{right-margin} property of the
1674character after point.
1675@end defun
1676
1677@deffn Command move-to-left-margin &optional n force
1678This function moves point to the left margin of the current line. The
1679column moved to is determined by calling the function
1680@code{current-left-margin}. If the argument @var{n} is non-@code{nil},
1681@code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
1682
1683If @var{force} is non-@code{nil}, that says to fix the line's
1684indentation if that doesn't match the left margin value.
1685@end deffn
1686
1687@defun delete-to-left-margin &optional from to
1688This function removes left margin indentation from the text between
1689@var{from} and @var{to}. The amount of indentation to delete is
1690determined by calling @code{current-left-margin}. In no case does this
1691function delete non-whitespace. If @var{from} and @var{to} are omitted,
1692they default to the whole buffer.
1693@end defun
1694
1695@defun indent-to-left-margin
1696This function adjusts the indentation at the beginning of the current
1697line to the value specified by the variable @code{left-margin}. (That
1698may involve either inserting or deleting whitespace.) This function
1699is value of @code{indent-line-function} in Paragraph-Indent Text mode.
1700@end defun
1701
01f17ae2 1702@defopt left-margin
b8d4c8d0
GM
1703This variable specifies the base left margin column. In Fundamental
1704mode, @kbd{C-j} indents to this column. This variable automatically
1705becomes buffer-local when set in any fashion.
01f17ae2 1706@end defopt
b8d4c8d0 1707
01f17ae2 1708@defopt fill-nobreak-predicate
b8d4c8d0
GM
1709This variable gives major modes a way to specify not to break a line
1710at certain places. Its value should be a list of functions. Whenever
1711filling considers breaking the line at a certain place in the buffer,
1712it calls each of these functions with no arguments and with point
1713located at that place. If any of the functions returns
1714non-@code{nil}, then the line won't be broken there.
01f17ae2 1715@end defopt
b8d4c8d0
GM
1716
1717@node Adaptive Fill
1718@section Adaptive Fill Mode
1719@c @cindex Adaptive Fill mode "adaptive-fill-mode" is adjacent.
1720
1721 When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill
1722prefix automatically from the text in each paragraph being filled
1723rather than using a predetermined value. During filling, this fill
1724prefix gets inserted at the start of the second and subsequent lines
1725of the paragraph as described in @ref{Filling}, and in @ref{Auto
1726Filling}.
1727
1728@defopt adaptive-fill-mode
1729Adaptive Fill mode is enabled when this variable is non-@code{nil}.
1730It is @code{t} by default.
1731@end defopt
1732
1733@defun fill-context-prefix from to
1734This function implements the heart of Adaptive Fill mode; it chooses a
1735fill prefix based on the text between @var{from} and @var{to},
1736typically the start and end of a paragraph. It does this by looking
1737at the first two lines of the paragraph, based on the variables
1738described below.
1739@c The optional argument first-line-regexp is not documented
1740@c because it exists for internal purposes and might be eliminated
1741@c in the future.
1742
1743Usually, this function returns the fill prefix, a string. However,
1744before doing this, the function makes a final check (not specially
1745mentioned in the following) that a line starting with this prefix
1746wouldn't look like the start of a paragraph. Should this happen, the
1747function signals the anomaly by returning @code{nil} instead.
1748
1749In detail, @code{fill-context-prefix} does this:
1750
1751@enumerate
1752@item
1753It takes a candidate for the fill prefix from the first line---it
1754tries first the function in @code{adaptive-fill-function} (if any),
1755then the regular expression @code{adaptive-fill-regexp} (see below).
1756The first non-@code{nil} result of these, or the empty string if
1757they're both @code{nil}, becomes the first line's candidate.
1758@item
1759If the paragraph has as yet only one line, the function tests the
1760validity of the prefix candidate just found. The function then
1761returns the candidate if it's valid, or a string of spaces otherwise.
1762(see the description of @code{adaptive-fill-first-line-regexp} below).
1763@item
1764When the paragraph already has two lines, the function next looks for
1765a prefix candidate on the second line, in just the same way it did for
1766the first line. If it doesn't find one, it returns @code{nil}.
1767@item
1768The function now compares the two candidate prefixes heuristically: if
1769the non-whitespace characters in the line 2 candidate occur in the
1770same order in the line 1 candidate, the function returns the line 2
1771candidate. Otherwise, it returns the largest initial substring which
1772is common to both candidates (which might be the empty string).
1773@end enumerate
1774@end defun
1775
1776@defopt adaptive-fill-regexp
1777Adaptive Fill mode matches this regular expression against the text
1778starting after the left margin whitespace (if any) on a line; the
1779characters it matches are that line's candidate for the fill prefix.
1780
1781The default value matches whitespace with certain punctuation
1782characters intermingled.
1783@end defopt
1784
1785@defopt adaptive-fill-first-line-regexp
1786Used only in one-line paragraphs, this regular expression acts as an
1787additional check of the validity of the one available candidate fill
1788prefix: the candidate must match this regular expression, or match
1789@code{comment-start-skip}. If it doesn't, @code{fill-context-prefix}
1790replaces the candidate with a string of spaces ``of the same width''
1791as it.
1792
1793The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which
1794matches only a string of whitespace. The effect of this default is to
1795force the fill prefixes found in one-line paragraphs always to be pure
1796whitespace.
1797@end defopt
1798
1799@defopt adaptive-fill-function
1800You can specify more complex ways of choosing a fill prefix
1801automatically by setting this variable to a function. The function is
1802called with point after the left margin (if any) of a line, and it
1803must preserve point. It should return either ``that line's'' fill
1804prefix or @code{nil}, meaning it has failed to determine a prefix.
1805@end defopt
1806
1807@node Auto Filling
b8d4c8d0
GM
1808@section Auto Filling
1809@cindex filling, automatic
1810@cindex Auto Fill mode
1811
d3110177 1812@c FIXME: I don't think any of the variables below is a/an normal/abnormal hook.
b8d4c8d0
GM
1813 Auto Fill mode is a minor mode that fills lines automatically as text
1814is inserted. This section describes the hook used by Auto Fill mode.
1815For a description of functions that you can call explicitly to fill and
1816justify existing text, see @ref{Filling}.
1817
1818 Auto Fill mode also enables the functions that change the margins and
1819justification style to refill portions of the text. @xref{Margins}.
1820
1821@defvar auto-fill-function
1822The value of this buffer-local variable should be a function (of no
1823arguments) to be called after self-inserting a character from the table
1824@code{auto-fill-chars}. It may be @code{nil}, in which case nothing
1825special is done in that case.
1826
1827The value of @code{auto-fill-function} is @code{do-auto-fill} when
1828Auto-Fill mode is enabled. That is a function whose sole purpose is to
1829implement the usual strategy for breaking a line.
b8d4c8d0
GM
1830@end defvar
1831
1832@defvar normal-auto-fill-function
1833This variable specifies the function to use for
1834@code{auto-fill-function}, if and when Auto Fill is turned on. Major
1835modes can set buffer-local values for this variable to alter how Auto
1836Fill works.
1837@end defvar
1838
1839@defvar auto-fill-chars
1840A char table of characters which invoke @code{auto-fill-function} when
1841self-inserted---space and newline in most language environments. They
1842have an entry @code{t} in the table.
1843@end defvar
1844
1845@node Sorting
1846@section Sorting Text
1847@cindex sorting text
1848
1849 The sorting functions described in this section all rearrange text in
1850a buffer. This is in contrast to the function @code{sort}, which
1851rearranges the order of the elements of a list (@pxref{Rearrangement}).
1852The values returned by these functions are not meaningful.
1853
1854@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate
1855This function is the general text-sorting routine that subdivides a
1856buffer into records and then sorts them. Most of the commands in this
1857section use this function.
1858
1859To understand how @code{sort-subr} works, consider the whole accessible
1860portion of the buffer as being divided into disjoint pieces called
1861@dfn{sort records}. The records may or may not be contiguous, but they
1862must not overlap. A portion of each sort record (perhaps all of it) is
1863designated as the sort key. Sorting rearranges the records in order by
1864their sort keys.
1865
1866Usually, the records are rearranged in order of ascending sort key.
1867If the first argument to the @code{sort-subr} function, @var{reverse},
1868is non-@code{nil}, the sort records are rearranged in order of
1869descending sort key.
1870
1871The next four arguments to @code{sort-subr} are functions that are
1872called to move point across a sort record. They are called many times
1873from within @code{sort-subr}.
1874
1875@enumerate
1876@item
1877@var{nextrecfun} is called with point at the end of a record. This
1878function moves point to the start of the next record. The first record
1879is assumed to start at the position of point when @code{sort-subr} is
1880called. Therefore, you should usually move point to the beginning of
1881the buffer before calling @code{sort-subr}.
1882
1883This function can indicate there are no more sort records by leaving
1884point at the end of the buffer.
1885
1886@item
1887@var{endrecfun} is called with point within a record. It moves point to
1888the end of the record.
1889
1890@item
1891@var{startkeyfun} is called to move point from the start of a record to
1892the start of the sort key. This argument is optional; if it is omitted,
1893the whole record is the sort key. If supplied, the function should
1894either return a non-@code{nil} value to be used as the sort key, or
1895return @code{nil} to indicate that the sort key is in the buffer
1896starting at point. In the latter case, @var{endkeyfun} is called to
1897find the end of the sort key.
1898
1899@item
1900@var{endkeyfun} is called to move point from the start of the sort key
1901to the end of the sort key. This argument is optional. If
1902@var{startkeyfun} returns @code{nil} and this argument is omitted (or
1903@code{nil}), then the sort key extends to the end of the record. There
1904is no need for @var{endkeyfun} if @var{startkeyfun} returns a
1905non-@code{nil} value.
1906@end enumerate
1907
1908The argument @var{predicate} is the function to use to compare keys.
1909If keys are numbers, it defaults to @code{<}; otherwise it defaults to
1910@code{string<}.
1911
1912As an example of @code{sort-subr}, here is the complete function
1913definition for @code{sort-lines}:
1914
1915@example
1916@group
1917;; @r{Note that the first two lines of doc string}
1918;; @r{are effectively one line when viewed by a user.}
1919(defun sort-lines (reverse beg end)
1920 "Sort lines in region alphabetically;\
1921 argument means descending order.
1922Called from a program, there are three arguments:
1923@end group
1924@group
1925REVERSE (non-nil means reverse order),\
1926 BEG and END (region to sort).
1927The variable `sort-fold-case' determines\
1928 whether alphabetic case affects
1929the sort order."
1930@end group
1931@group
1932 (interactive "P\nr")
1933 (save-excursion
1934 (save-restriction
1935 (narrow-to-region beg end)
1936 (goto-char (point-min))
1937 (let ((inhibit-field-text-motion t))
1938 (sort-subr reverse 'forward-line 'end-of-line)))))
1939@end group
1940@end example
1941
1942Here @code{forward-line} moves point to the start of the next record,
1943and @code{end-of-line} moves point to the end of record. We do not pass
1944the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
1945record is used as the sort key.
1946
1947The @code{sort-paragraphs} function is very much the same, except that
1948its @code{sort-subr} call looks like this:
1949
1950@example
1951@group
1952(sort-subr reverse
1953 (function
d3110177
XF
1954 (lambda ()
1955 (while (and (not (eobp))
1956 (looking-at paragraph-separate))
1957 (forward-line 1))))
b8d4c8d0
GM
1958 'forward-paragraph)
1959@end group
1960@end example
1961
1962Markers pointing into any sort records are left with no useful
1963position after @code{sort-subr} returns.
1964@end defun
1965
1966@defopt sort-fold-case
1967If this variable is non-@code{nil}, @code{sort-subr} and the other
1968buffer sorting functions ignore case when comparing strings.
1969@end defopt
1970
1971@deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
1972This command sorts the region between @var{start} and @var{end}
1973alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
1974If @var{reverse} is a negative integer, then sorting is in reverse
1975order.
1976
1977Alphabetical sorting means that two sort keys are compared by
1978comparing the first characters of each, the second characters of each,
1979and so on. If a mismatch is found, it means that the sort keys are
1980unequal; the sort key whose character is less at the point of first
1981mismatch is the lesser sort key. The individual characters are compared
1982according to their numerical character codes in the Emacs character set.
1983
1984The value of the @var{record-regexp} argument specifies how to divide
1985the buffer into sort records. At the end of each record, a search is
1986done for this regular expression, and the text that matches it is taken
1987as the next record. For example, the regular expression @samp{^.+$},
1988which matches lines with at least one character besides a newline, would
1989make each such line into a sort record. @xref{Regular Expressions}, for
1990a description of the syntax and meaning of regular expressions.
1991
1992The value of the @var{key-regexp} argument specifies what part of each
1993record is the sort key. The @var{key-regexp} could match the whole
1994record, or only a part. In the latter case, the rest of the record has
1995no effect on the sorted order of records, but it is carried along when
1996the record moves to its new position.
1997
1998The @var{key-regexp} argument can refer to the text matched by a
1999subexpression of @var{record-regexp}, or it can be a regular expression
2000on its own.
2001
2002If @var{key-regexp} is:
2003
2004@table @asis
2005@item @samp{\@var{digit}}
2006then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
2007grouping in @var{record-regexp} is the sort key.
2008
2009@item @samp{\&}
2010then the whole record is the sort key.
2011
2012@item a regular expression
2013then @code{sort-regexp-fields} searches for a match for the regular
2014expression within the record. If such a match is found, it is the sort
2015key. If there is no match for @var{key-regexp} within a record then
2016that record is ignored, which means its position in the buffer is not
2017changed. (The other records may move around it.)
2018@end table
2019
2020For example, if you plan to sort all the lines in the region by the
2021first word on each line starting with the letter @samp{f}, you should
2022set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
2023@samp{\<f\w*\>}. The resulting expression looks like this:
2024
2025@example
2026@group
2027(sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
2028 (region-beginning)
2029 (region-end))
2030@end group
2031@end example
2032
2033If you call @code{sort-regexp-fields} interactively, it prompts for
2034@var{record-regexp} and @var{key-regexp} in the minibuffer.
2035@end deffn
2036
2037@deffn Command sort-lines reverse start end
2038This command alphabetically sorts lines in the region between
2039@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2040is in reverse order.
2041@end deffn
2042
2043@deffn Command sort-paragraphs reverse start end
2044This command alphabetically sorts paragraphs in the region between
2045@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2046is in reverse order.
2047@end deffn
2048
2049@deffn Command sort-pages reverse start end
2050This command alphabetically sorts pages in the region between
2051@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort
2052is in reverse order.
2053@end deffn
2054
2055@deffn Command sort-fields field start end
2056This command sorts lines in the region between @var{start} and
2057@var{end}, comparing them alphabetically by the @var{field}th field
2058of each line. Fields are separated by whitespace and numbered starting
2059from 1. If @var{field} is negative, sorting is by the
2060@w{@minus{}@var{field}th} field from the end of the line. This command
2061is useful for sorting tables.
2062@end deffn
2063
2064@deffn Command sort-numeric-fields field start end
2065This command sorts lines in the region between @var{start} and
2066@var{end}, comparing them numerically by the @var{field}th field of
2067each line. Fields are separated by whitespace and numbered starting
2068from 1. The specified field must contain a number in each line of the
2069region. Numbers starting with 0 are treated as octal, and numbers
2070starting with @samp{0x} are treated as hexadecimal.
2071
2072If @var{field} is negative, sorting is by the
2073@w{@minus{}@var{field}th} field from the end of the line. This
2074command is useful for sorting tables.
2075@end deffn
2076
2077@defopt sort-numeric-base
2078This variable specifies the default radix for
2079@code{sort-numeric-fields} to parse numbers.
2080@end defopt
2081
2082@deffn Command sort-columns reverse &optional beg end
2083This command sorts the lines in the region between @var{beg} and
2084@var{end}, comparing them alphabetically by a certain range of
2085columns. The column positions of @var{beg} and @var{end} bound the
2086range of columns to sort on.
2087
2088If @var{reverse} is non-@code{nil}, the sort is in reverse order.
2089
2090One unusual thing about this command is that the entire line
2091containing position @var{beg}, and the entire line containing position
2092@var{end}, are included in the region sorted.
2093
2094Note that @code{sort-columns} rejects text that contains tabs, because
2095tabs could be split across the specified columns. Use @kbd{M-x
2096untabify} to convert tabs to spaces before sorting.
2097
2098When possible, this command actually works by calling the @code{sort}
2099utility program.
2100@end deffn
2101
2102@node Columns
b8d4c8d0
GM
2103@section Counting Columns
2104@cindex columns
2105@cindex counting columns
2106@cindex horizontal position
2107
2108 The column functions convert between a character position (counting
2109characters from the beginning of the buffer) and a column position
2110(counting screen characters from the beginning of a line).
2111
2112 These functions count each character according to the number of
2113columns it occupies on the screen. This means control characters count
2114as occupying 2 or 4 columns, depending upon the value of
2115@code{ctl-arrow}, and tabs count as occupying a number of columns that
2116depends on the value of @code{tab-width} and on the column where the tab
2117begins. @xref{Usual Display}.
2118
2119 Column number computations ignore the width of the window and the
2120amount of horizontal scrolling. Consequently, a column value can be
2121arbitrarily high. The first (or leftmost) column is numbered 0. They
2122also ignore overlays and text properties, aside from invisibility.
2123
2124@defun current-column
2125This function returns the horizontal position of point, measured in
2126columns, counting from 0 at the left margin. The column position is the
2127sum of the widths of all the displayed representations of the characters
2128between the start of the current line and point.
2129
2130For an example of using @code{current-column}, see the description of
2131@code{count-lines} in @ref{Text Lines}.
2132@end defun
2133
106e6894 2134@deffn Command move-to-column column &optional force
b8d4c8d0
GM
2135This function moves point to @var{column} in the current line. The
2136calculation of @var{column} takes into account the widths of the
2137displayed representations of the characters between the start of the
2138line and point.
2139
106e6894
CY
2140When called interactively, @var{column} is the value of prefix numeric
2141argument. If @var{column} is not an integer, an error is signaled.
2142
38b4c7f8
XF
2143@c This behavior used to be documented until 2013/08.
2144@ignore
106e6894
CY
2145If column @var{column} is beyond the end of the line, point moves to
2146the end of the line. If @var{column} is negative, point moves to the
b8d4c8d0 2147beginning of the line.
38b4c7f8 2148@end ignore
b8d4c8d0
GM
2149
2150If it is impossible to move to column @var{column} because that is in
2151the middle of a multicolumn character such as a tab, point moves to the
2152end of that character. However, if @var{force} is non-@code{nil}, and
2153@var{column} is in the middle of a tab, then @code{move-to-column}
2154converts the tab into spaces so that it can move precisely to column
2155@var{column}. Other multicolumn characters can cause anomalies despite
2156@var{force}, since there is no way to split them.
2157
2158The argument @var{force} also has an effect if the line isn't long
2159enough to reach column @var{column}; if it is @code{t}, that means to
2160add whitespace at the end of the line to reach that column.
2161
b8d4c8d0 2162The return value is the column number actually moved to.
106e6894 2163@end deffn
b8d4c8d0
GM
2164
2165@node Indentation
2166@section Indentation
2167@cindex indentation
2168
2169 The indentation functions are used to examine, move to, and change
2170whitespace that is at the beginning of a line. Some of the functions
2171can also change whitespace elsewhere on a line. Columns and indentation
2172count from zero at the left margin.
2173
2174@menu
2175* Primitive Indent:: Functions used to count and insert indentation.
2176* Mode-Specific Indent:: Customize indentation for different modes.
2177* Region Indent:: Indent all the lines in a region.
2178* Relative Indent:: Indent the current line based on previous lines.
2179* Indent Tabs:: Adjustable, typewriter-like tab stops.
2180* Motion by Indent:: Move to first non-blank character.
2181@end menu
2182
2183@node Primitive Indent
2184@subsection Indentation Primitives
2185
2186 This section describes the primitive functions used to count and
2187insert indentation. The functions in the following sections use these
2188primitives. @xref{Width}, for related functions.
2189
2190@defun current-indentation
2191@comment !!Type Primitive Function
2192@comment !!SourceFile indent.c
2193This function returns the indentation of the current line, which is
2194the horizontal position of the first nonblank character. If the
2195contents are entirely blank, then this is the horizontal position of the
2196end of the line.
2197@end defun
2198
2199@deffn Command indent-to column &optional minimum
2200@comment !!Type Primitive Function
2201@comment !!SourceFile indent.c
2202This function indents from point with tabs and spaces until @var{column}
2203is reached. If @var{minimum} is specified and non-@code{nil}, then at
2204least that many spaces are inserted even if this requires going beyond
2205@var{column}. Otherwise the function does nothing if point is already
2206beyond @var{column}. The value is the column at which the inserted
2207indentation ends.
2208
2209The inserted whitespace characters inherit text properties from the
2210surrounding text (usually, from the preceding text only). @xref{Sticky
2211Properties}.
2212@end deffn
2213
2214@defopt indent-tabs-mode
2215@comment !!SourceFile indent.c
2216If this variable is non-@code{nil}, indentation functions can insert
2217tabs as well as spaces. Otherwise, they insert only spaces. Setting
2218this variable automatically makes it buffer-local in the current buffer.
2219@end defopt
2220
2221@node Mode-Specific Indent
2222@subsection Indentation Controlled by Major Mode
2223
2224 An important function of each major mode is to customize the @key{TAB}
2225key to indent properly for the language being edited. This section
2226describes the mechanism of the @key{TAB} key and how to control it.
2227The functions in this section return unpredictable values.
2228
483ab230
CY
2229@deffn Command indent-for-tab-command &optional rigid
2230This is the command bound to @key{TAB} in most editing modes. Its
2231usual action is to indent the current line, but it can alternatively
2232insert a tab character or indent a region.
2233
2234Here is what it does:
b8d4c8d0 2235
483ab230
CY
2236@itemize
2237@item
2238First, it checks whether Transient Mark mode is enabled and the region
2239is active. If so, it called @code{indent-region} to indent all the
2240text in the region (@pxref{Region Indent}).
2241
2242@item
2243Otherwise, if the indentation function in @code{indent-line-function}
2244is @code{indent-to-left-margin} (a trivial command that inserts a tab
2245character), or if the variable @code{tab-always-indent} specifies that
2246a tab character ought to be inserted (see below), then it inserts a
2247tab character.
2248
2249@item
2250Otherwise, it indents the current line; this is done by calling the
2251function in @code{indent-line-function}. If the line is already
2252indented, and the value of @code{tab-always-indent} is @code{complete}
2253(see below), it tries completing the text at point.
2254@end itemize
2255
2256If @var{rigid} is non-@code{nil} (interactively, with a prefix
2257argument), then after this command indents a line or inserts a tab, it
2258also rigidly indents the entire balanced expression which starts at
2259the beginning of the current line, in order to reflect the new
2260indentation. This argument is ignored if the command indents the
2261region.
2262@end deffn
2263
2264@defvar indent-line-function
2265This variable's value is the function to be used by
2266@code{indent-for-tab-command}, and various other indentation commands,
2267to indent the current line. It is usually assigned by the major mode;
2268for instance, Lisp mode sets it to @code{lisp-indent-line}, C mode
2269sets it to @code{c-indent-line}, and so on. The default value is
2270@code{indent-relative}. @xref{Auto-Indentation}.
b8d4c8d0
GM
2271@end defvar
2272
2273@deffn Command indent-according-to-mode
2274This command calls the function in @code{indent-line-function} to
2275indent the current line in a way appropriate for the current major mode.
2276@end deffn
2277
b8d4c8d0 2278@deffn Command newline-and-indent
b8d4c8d0 2279This function inserts a newline, then indents the new line (the one
483ab230
CY
2280following the newline just inserted) according to the major mode. It
2281does indentation by calling @code{indent-according-to-mode}.
b8d4c8d0
GM
2282@end deffn
2283
2284@deffn Command reindent-then-newline-and-indent
b8d4c8d0
GM
2285This command reindents the current line, inserts a newline at point,
2286and then indents the new line (the one following the newline just
483ab230
CY
2287inserted). It does indentation on both lines by calling
2288@code{indent-according-to-mode}.
b8d4c8d0
GM
2289@end deffn
2290
483ab230
CY
2291@defopt tab-always-indent
2292This variable can be used to customize the behavior of the @key{TAB}
2293(@code{indent-for-tab-command}) command. If the value is @code{t}
2294(the default), the command normally just indents the current line. If
2295the value is @code{nil}, the command indents the current line only if
2296point is at the left margin or in the line's indentation; otherwise,
2297it inserts a tab character. If the value is @code{complete}, the
2298command first tries to indent the current line, and if the line was
2299already indented, it calls @code{completion-at-point} to complete the
2300text at point (@pxref{Completion in Buffers}).
2301@end defopt
2302
b8d4c8d0
GM
2303@node Region Indent
2304@subsection Indenting an Entire Region
2305
2306 This section describes commands that indent all the lines in the
2307region. They return unpredictable values.
2308
106e6894 2309@deffn Command indent-region start end &optional to-column
b8d4c8d0
GM
2310This command indents each nonblank line starting between @var{start}
2311(inclusive) and @var{end} (exclusive). If @var{to-column} is
2312@code{nil}, @code{indent-region} indents each nonblank line by calling
2313the current mode's indentation function, the value of
2314@code{indent-line-function}.
2315
2316If @var{to-column} is non-@code{nil}, it should be an integer
2317specifying the number of columns of indentation; then this function
2318gives each line exactly that much indentation, by either adding or
2319deleting whitespace.
2320
2321If there is a fill prefix, @code{indent-region} indents each line
2322by making it start with the fill prefix.
2323@end deffn
2324
2325@defvar indent-region-function
2326The value of this variable is a function that can be used by
2327@code{indent-region} as a short cut. It should take two arguments, the
2328start and end of the region. You should design the function so
2329that it will produce the same results as indenting the lines of the
2330region one by one, but presumably faster.
2331
2332If the value is @code{nil}, there is no short cut, and
2333@code{indent-region} actually works line by line.
2334
2335A short-cut function is useful in modes such as C mode and Lisp mode,
2336where the @code{indent-line-function} must scan from the beginning of
2337the function definition: applying it to each line would be quadratic in
2338time. The short cut can update the scan information as it moves through
2339the lines indenting them; this takes linear time. In a mode where
2340indenting a line individually is fast, there is no need for a short cut.
2341
2342@code{indent-region} with a non-@code{nil} argument @var{to-column} has
2343a different meaning and does not use this variable.
2344@end defvar
2345
2346@deffn Command indent-rigidly start end count
b8d4c8d0
GM
2347This command indents all lines starting between @var{start}
2348(inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
2349This ``preserves the shape'' of the affected region, moving it as a
2350rigid unit. Consequently, this command is useful not only for indenting
2351regions of unindented text, but also for indenting regions of formatted
2352code.
2353
2354For example, if @var{count} is 3, this command adds 3 columns of
2355indentation to each of the lines beginning in the region specified.
2356
ad6643fe
XF
2357@c FIXME: I suggest using message-indent-citation as the example, or
2358@c just remove this paragraph. --xfq
b8d4c8d0
GM
2359In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
2360@code{indent-rigidly} to indent the text copied from the message being
2361replied to.
2362@end deffn
2363
106e6894 2364@deffn Command indent-code-rigidly start end columns &optional nochange-regexp
b8d4c8d0
GM
2365This is like @code{indent-rigidly}, except that it doesn't alter lines
2366that start within strings or comments.
2367
2368In addition, it doesn't alter a line if @var{nochange-regexp} matches at
2369the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
106e6894 2370@end deffn
b8d4c8d0
GM
2371
2372@node Relative Indent
2373@subsection Indentation Relative to Previous Lines
2374
2375 This section describes two commands that indent the current line
2376based on the contents of previous lines.
2377
2378@deffn Command indent-relative &optional unindented-ok
2379This command inserts whitespace at point, extending to the same
2380column as the next @dfn{indent point} of the previous nonblank line. An
2381indent point is a non-whitespace character following whitespace. The
2382next indent point is the first one at a column greater than the current
2383column of point. For example, if point is underneath and to the left of
2384the first non-blank character of a line of text, it moves to that column
2385by inserting whitespace.
2386
2387If the previous nonblank line has no next indent point (i.e., none at a
2388great enough column position), @code{indent-relative} either does
2389nothing (if @var{unindented-ok} is non-@code{nil}) or calls
2390@code{tab-to-tab-stop}. Thus, if point is underneath and to the right
2391of the last column of a short line of text, this command ordinarily
2392moves point to the next tab stop by inserting whitespace.
2393
2394The return value of @code{indent-relative} is unpredictable.
2395
2396In the following example, point is at the beginning of the second
2397line:
2398
2399@example
2400@group
2401 This line is indented twelve spaces.
2402@point{}The quick brown fox jumped.
2403@end group
2404@end example
2405
2406@noindent
2407Evaluation of the expression @code{(indent-relative nil)} produces the
2408following:
2409
2410@example
2411@group
2412 This line is indented twelve spaces.
2413 @point{}The quick brown fox jumped.
2414@end group
2415@end example
2416
2417 In this next example, point is between the @samp{m} and @samp{p} of
2418@samp{jumped}:
2419
2420@example
2421@group
2422 This line is indented twelve spaces.
2423The quick brown fox jum@point{}ped.
2424@end group
2425@end example
2426
2427@noindent
2428Evaluation of the expression @code{(indent-relative nil)} produces the
2429following:
2430
2431@example
2432@group
2433 This line is indented twelve spaces.
2434The quick brown fox jum @point{}ped.
2435@end group
2436@end example
2437@end deffn
2438
2439@deffn Command indent-relative-maybe
2440@comment !!SourceFile indent.el
2441This command indents the current line like the previous nonblank line,
2442by calling @code{indent-relative} with @code{t} as the
2443@var{unindented-ok} argument. The return value is unpredictable.
2444
2445If the previous nonblank line has no indent points beyond the current
2446column, this command does nothing.
2447@end deffn
2448
2449@node Indent Tabs
b8d4c8d0
GM
2450@subsection Adjustable ``Tab Stops''
2451@cindex tabs stops for indentation
2452
2453 This section explains the mechanism for user-specified ``tab stops''
2454and the mechanisms that use and set them. The name ``tab stops'' is
2455used because the feature is similar to that of the tab stops on a
2456typewriter. The feature works by inserting an appropriate number of
2457spaces and tab characters to reach the next tab stop column; it does not
2458affect the display of tab characters in the buffer (@pxref{Usual
2459Display}). Note that the @key{TAB} character as input uses this tab
2460stop feature only in a few major modes, such as Text mode.
2461@xref{Tab Stops,,, emacs, The GNU Emacs Manual}.
2462
2463@deffn Command tab-to-tab-stop
2464This command inserts spaces or tabs before point, up to the next tab
2465stop column defined by @code{tab-stop-list}. It searches the list for
2466an element greater than the current column number, and uses that element
2467as the column to indent to. It does nothing if no such element is
2468found.
2469@end deffn
2470
2471@defopt tab-stop-list
2472This variable is the list of tab stop columns used by
2473@code{tab-to-tab-stops}. The elements should be integers in increasing
2474order. The tab stop columns need not be evenly spaced.
2475
2476Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
2477interactively.
2478@end defopt
2479
2480@node Motion by Indent
2481@subsection Indentation-Based Motion Commands
2482
2483 These commands, primarily for interactive use, act based on the
2484indentation in the text.
2485
2486@deffn Command back-to-indentation
2487@comment !!SourceFile simple.el
2488This command moves point to the first non-whitespace character in the
2489current line (which is the line in which point is located). It returns
2490@code{nil}.
2491@end deffn
2492
2493@deffn Command backward-to-indentation &optional arg
2494@comment !!SourceFile simple.el
2495This command moves point backward @var{arg} lines and then to the
2496first nonblank character on that line. It returns @code{nil}.
2497If @var{arg} is omitted or @code{nil}, it defaults to 1.
2498@end deffn
2499
2500@deffn Command forward-to-indentation &optional arg
2501@comment !!SourceFile simple.el
2502This command moves point forward @var{arg} lines and then to the first
2503nonblank character on that line. It returns @code{nil}.
2504If @var{arg} is omitted or @code{nil}, it defaults to 1.
2505@end deffn
2506
2507@node Case Changes
b8d4c8d0
GM
2508@section Case Changes
2509@cindex case conversion in buffers
2510
2511 The case change commands described here work on text in the current
2512buffer. @xref{Case Conversion}, for case conversion functions that work
2513on strings and characters. @xref{Case Tables}, for how to customize
2514which characters are upper or lower case and how to convert them.
2515
2516@deffn Command capitalize-region start end
2517This function capitalizes all words in the region defined by
2518@var{start} and @var{end}. To capitalize means to convert each word's
2519first character to upper case and convert the rest of each word to lower
2520case. The function returns @code{nil}.
2521
2522If one end of the region is in the middle of a word, the part of the
2523word within the region is treated as an entire word.
2524
2525When @code{capitalize-region} is called interactively, @var{start} and
2526@var{end} are point and the mark, with the smallest first.
2527
2528@example
2529@group
2530---------- Buffer: foo ----------
2531This is the contents of the 5th foo.
2532---------- Buffer: foo ----------
2533@end group
2534
2535@group
ad6643fe 2536(capitalize-region 1 37)
b8d4c8d0
GM
2537@result{} nil
2538
2539---------- Buffer: foo ----------
2540This Is The Contents Of The 5th Foo.
2541---------- Buffer: foo ----------
2542@end group
2543@end example
2544@end deffn
2545
2546@deffn Command downcase-region start end
2547This function converts all of the letters in the region defined by
2548@var{start} and @var{end} to lower case. The function returns
2549@code{nil}.
2550
2551When @code{downcase-region} is called interactively, @var{start} and
2552@var{end} are point and the mark, with the smallest first.
2553@end deffn
2554
2555@deffn Command upcase-region start end
2556This function converts all of the letters in the region defined by
2557@var{start} and @var{end} to upper case. The function returns
2558@code{nil}.
2559
2560When @code{upcase-region} is called interactively, @var{start} and
2561@var{end} are point and the mark, with the smallest first.
2562@end deffn
2563
2564@deffn Command capitalize-word count
2565This function capitalizes @var{count} words after point, moving point
2566over as it does. To capitalize means to convert each word's first
2567character to upper case and convert the rest of each word to lower case.
2568If @var{count} is negative, the function capitalizes the
2569@minus{}@var{count} previous words but does not move point. The value
2570is @code{nil}.
2571
2572If point is in the middle of a word, the part of the word before point
2573is ignored when moving forward. The rest is treated as an entire word.
2574
2575When @code{capitalize-word} is called interactively, @var{count} is
2576set to the numeric prefix argument.
2577@end deffn
2578
2579@deffn Command downcase-word count
2580This function converts the @var{count} words after point to all lower
2581case, moving point over as it does. If @var{count} is negative, it
2582converts the @minus{}@var{count} previous words but does not move point.
2583The value is @code{nil}.
2584
2585When @code{downcase-word} is called interactively, @var{count} is set
2586to the numeric prefix argument.
2587@end deffn
2588
2589@deffn Command upcase-word count
2590This function converts the @var{count} words after point to all upper
2591case, moving point over as it does. If @var{count} is negative, it
2592converts the @minus{}@var{count} previous words but does not move point.
2593The value is @code{nil}.
2594
2595When @code{upcase-word} is called interactively, @var{count} is set to
2596the numeric prefix argument.
2597@end deffn
2598
2599@node Text Properties
2600@section Text Properties
2601@cindex text properties
2602@cindex attributes of text
2603@cindex properties of text
2604
2605 Each character position in a buffer or a string can have a @dfn{text
2606property list}, much like the property list of a symbol (@pxref{Property
2607Lists}). The properties belong to a particular character at a
2608particular place, such as, the letter @samp{T} at the beginning of this
2609sentence or the first @samp{o} in @samp{foo}---if the same character
2610occurs in two different places, the two occurrences in general have
2611different properties.
2612
2613 Each property has a name and a value. Both of these can be any Lisp
2614object, but the name is normally a symbol. Typically each property
2615name symbol is used for a particular purpose; for instance, the text
2616property @code{face} specifies the faces for displaying the character
2617(@pxref{Special Properties}). The usual way to access the property
2618list is to specify a name and ask what value corresponds to it.
2619
2620 If a character has a @code{category} property, we call it the
2621@dfn{property category} of the character. It should be a symbol. The
2622properties of the symbol serve as defaults for the properties of the
2623character.
2624
2625 Copying text between strings and buffers preserves the properties
2626along with the characters; this includes such diverse functions as
2627@code{substring}, @code{insert}, and @code{buffer-substring}.
2628
2629@menu
2630* Examining Properties:: Looking at the properties of one character.
d24880de
GM
2631* Changing Properties:: Setting the properties of a range of text.
2632* Property Search:: Searching for where a property changes value.
2633* Special Properties:: Particular properties with special meanings.
b8d4c8d0
GM
2634* Format Properties:: Properties for representing formatting of text.
2635* Sticky Properties:: How inserted text gets properties from
2636 neighboring text.
2637* Lazy Properties:: Computing text properties in a lazy fashion
2638 only when text is examined.
2639* Clickable Text:: Using text properties to make regions of text
2640 do something when you click on them.
b8d4c8d0
GM
2641* Fields:: The @code{field} property defines
2642 fields within the buffer.
d24880de
GM
2643* Not Intervals:: Why text properties do not use
2644 Lisp-visible text intervals.
b8d4c8d0
GM
2645@end menu
2646
2647@node Examining Properties
2648@subsection Examining Text Properties
2649
2650 The simplest way to examine text properties is to ask for the value of
2651a particular property of a particular character. For that, use
2652@code{get-text-property}. Use @code{text-properties-at} to get the
2653entire property list of a character. @xref{Property Search}, for
2654functions to examine the properties of a number of characters at once.
2655
2656 These functions handle both strings and buffers. Keep in mind that
2657positions in a string start from 0, whereas positions in a buffer start
2658from 1.
2659
2660@defun get-text-property pos prop &optional object
2661This function returns the value of the @var{prop} property of the
2662character after position @var{pos} in @var{object} (a buffer or
2663string). The argument @var{object} is optional and defaults to the
2664current buffer.
2665
2666If there is no @var{prop} property strictly speaking, but the character
2667has a property category that is a symbol, then @code{get-text-property} returns
2668the @var{prop} property of that symbol.
2669@end defun
2670
2671@defun get-char-property position prop &optional object
2672This function is like @code{get-text-property}, except that it checks
2673overlays first and then text properties. @xref{Overlays}.
2674
af23e1e8
RS
2675The argument @var{object} may be a string, a buffer, or a window. If
2676it is a window, then the buffer displayed in that window is used for
2677text properties and overlays, but only the overlays active for that
2678window are considered. If @var{object} is a buffer, then overlays in
2679that buffer are considered first, in order of decreasing priority,
2680followed by the text properties. If @var{object} is a string, only
2681text properties are considered, since strings never have overlays.
b8d4c8d0
GM
2682@end defun
2683
2684@defun get-char-property-and-overlay position prop &optional object
2685This is like @code{get-char-property}, but gives extra information
2686about the overlay that the property value comes from.
2687
2688Its value is a cons cell whose @sc{car} is the property value, the
2689same value @code{get-char-property} would return with the same
2690arguments. Its @sc{cdr} is the overlay in which the property was
2691found, or @code{nil}, if it was found as a text property or not found
2692at all.
2693
2694If @var{position} is at the end of @var{object}, both the @sc{car} and
2695the @sc{cdr} of the value are @code{nil}.
2696@end defun
2697
2698@defvar char-property-alias-alist
2699This variable holds an alist which maps property names to a list of
2700alternative property names. If a character does not specify a direct
2701value for a property, the alternative property names are consulted in
2702order; the first non-@code{nil} value is used. This variable takes
2703precedence over @code{default-text-properties}, and @code{category}
2704properties take precedence over this variable.
2705@end defvar
2706
2707@defun text-properties-at position &optional object
2708This function returns the entire property list of the character at
2709@var{position} in the string or buffer @var{object}. If @var{object} is
2710@code{nil}, it defaults to the current buffer.
2711@end defun
2712
2713@defvar default-text-properties
2714This variable holds a property list giving default values for text
2715properties. Whenever a character does not specify a value for a
2716property, neither directly, through a category symbol, or through
2717@code{char-property-alias-alist}, the value stored in this list is
2718used instead. Here is an example:
2719
2720@example
2721(setq default-text-properties '(foo 69)
2722 char-property-alias-alist nil)
2723;; @r{Make sure character 1 has no properties of its own.}
2724(set-text-properties 1 2 nil)
2725;; @r{What we get, when we ask, is the default value.}
2726(get-text-property 1 'foo)
2727 @result{} 69
2728@end example
2729@end defvar
2730
2731@node Changing Properties
2732@subsection Changing Text Properties
2733
2734 The primitives for changing properties apply to a specified range of
2735text in a buffer or string. The function @code{set-text-properties}
2736(see end of section) sets the entire property list of the text in that
2737range; more often, it is useful to add, change, or delete just certain
2738properties specified by name.
2739
2740 Since text properties are considered part of the contents of the
2741buffer (or string), and can affect how a buffer looks on the screen,
2742any change in buffer text properties marks the buffer as modified.
2743Buffer text property changes are undoable also (@pxref{Undo}).
2744Positions in a string start from 0, whereas positions in a buffer
2745start from 1.
2746
2747@defun put-text-property start end prop value &optional object
2748This function sets the @var{prop} property to @var{value} for the text
2749between @var{start} and @var{end} in the string or buffer @var{object}.
2750If @var{object} is @code{nil}, it defaults to the current buffer.
2751@end defun
2752
2753@defun add-text-properties start end props &optional object
2754This function adds or overrides text properties for the text between
2755@var{start} and @var{end} in the string or buffer @var{object}. If
2756@var{object} is @code{nil}, it defaults to the current buffer.
2757
2758The argument @var{props} specifies which properties to add. It should
2759have the form of a property list (@pxref{Property Lists}): a list whose
2760elements include the property names followed alternately by the
2761corresponding values.
2762
2763The return value is @code{t} if the function actually changed some
2764property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2765its values agree with those in the text).
2766
2767For example, here is how to set the @code{comment} and @code{face}
2768properties of a range of text:
2769
2770@example
2771(add-text-properties @var{start} @var{end}
2772 '(comment t face highlight))
2773@end example
2774@end defun
2775
2776@defun remove-text-properties start end props &optional object
2777This function deletes specified text properties from the text between
2778@var{start} and @var{end} in the string or buffer @var{object}. If
2779@var{object} is @code{nil}, it defaults to the current buffer.
2780
2781The argument @var{props} specifies which properties to delete. It
2782should have the form of a property list (@pxref{Property Lists}): a list
2783whose elements are property names alternating with corresponding values.
2784But only the names matter---the values that accompany them are ignored.
2785For example, here's how to remove the @code{face} property.
2786
2787@example
2788(remove-text-properties @var{start} @var{end} '(face nil))
2789@end example
2790
2791The return value is @code{t} if the function actually changed some
2792property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
2793if no character in the specified text had any of those properties).
2794
2795To remove all text properties from certain text, use
2796@code{set-text-properties} and specify @code{nil} for the new property
2797list.
2798@end defun
2799
2800@defun remove-list-of-text-properties start end list-of-properties &optional object
2801Like @code{remove-text-properties} except that
2802@var{list-of-properties} is a list of property names only, not an
2803alternating list of property names and values.
2804@end defun
2805
2806@defun set-text-properties start end props &optional object
2807This function completely replaces the text property list for the text
2808between @var{start} and @var{end} in the string or buffer @var{object}.
2809If @var{object} is @code{nil}, it defaults to the current buffer.
2810
2811The argument @var{props} is the new property list. It should be a list
2812whose elements are property names alternating with corresponding values.
2813
2814After @code{set-text-properties} returns, all the characters in the
2815specified range have identical properties.
2816
2817If @var{props} is @code{nil}, the effect is to get rid of all properties
2818from the specified range of text. Here's an example:
2819
2820@example
2821(set-text-properties @var{start} @var{end} nil)
2822@end example
2823
2824Do not rely on the return value of this function.
708e05f6
LMI
2825@end defun
2826
2827@defun add-face-text-property start end face &optional appendp object
2828@code{face} text attributes can be combined. If you want to make a
2829section both italic and green, you can either define a new face that
2830have those attributes, or you can add both these attributes separately
2831to text:
2832
2833@example
2834(add-face-text-property @var{start} @var{end} 'italic)
2835(add-face-text-property @var{start} @var{end} '(:foreground "#00ff00"))
2836@end example
2837
2838The attribute is (by default) prepended to the list of face
2839attributes, and the first attribute of the same type takes
254408ca 2840precedence. So if you have two @code{:foreground} specifications, the
708e05f6
LMI
2841first one will take effect.
2842
2843If you pass in @var{appendp}, the attribute will be appended instead
2844of prepended, which means that it will have no effect if there is
2845already an attribute of the same type.
2846
b8d4c8d0
GM
2847@end defun
2848
2849 The easiest way to make a string with text properties
2850is with @code{propertize}:
2851
2852@defun propertize string &rest properties
2853This function returns a copy of @var{string} which has the text
2854properties @var{properties}. These properties apply to all the
2855characters in the string that is returned. Here is an example that
2856constructs a string with a @code{face} property and a @code{mouse-face}
2857property:
2858
2859@smallexample
2860(propertize "foo" 'face 'italic
2861 'mouse-face 'bold-italic)
2862 @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
2863@end smallexample
2864
2865To put different properties on various parts of a string, you can
2866construct each part with @code{propertize} and then combine them with
2867@code{concat}:
2868
2869@smallexample
2870(concat
2871 (propertize "foo" 'face 'italic
2872 'mouse-face 'bold-italic)
2873 " and "
2874 (propertize "bar" 'face 'italic
2875 'mouse-face 'bold-italic))
2876 @result{} #("foo and bar"
2877 0 3 (face italic mouse-face bold-italic)
2878 3 8 nil
2879 8 11 (face italic mouse-face bold-italic))
2880@end smallexample
2881@end defun
2882
049bcbcb
CY
2883 @xref{Buffer Contents}, for the function
2884@code{buffer-substring-no-properties}, which copies text from the
2885buffer but does not copy its properties.
b8d4c8d0
GM
2886
2887@node Property Search
2888@subsection Text Property Search Functions
2889
2890 In typical use of text properties, most of the time several or many
2891consecutive characters have the same value for a property. Rather than
2892writing your programs to examine characters one by one, it is much
2893faster to process chunks of text that have the same property value.
2894
2895 Here are functions you can use to do this. They use @code{eq} for
2896comparing property values. In all cases, @var{object} defaults to the
2897current buffer.
2898
483ab230 2899 For good performance, it's very important to use the @var{limit}
b8d4c8d0
GM
2900argument to these functions, especially the ones that search for a
2901single property---otherwise, they may spend a long time scanning to the
2902end of the buffer, if the property you are interested in does not change.
2903
2904 These functions do not move point; instead, they return a position (or
2905@code{nil}). Remember that a position is always between two characters;
2906the position returned by these functions is between two characters with
2907different properties.
2908
2909@defun next-property-change pos &optional object limit
2910The function scans the text forward from position @var{pos} in the
483ab230 2911string or buffer @var{object} until it finds a change in some text
b8d4c8d0
GM
2912property, then returns the position of the change. In other words, it
2913returns the position of the first character beyond @var{pos} whose
2914properties are not identical to those of the character just after
2915@var{pos}.
2916
2917If @var{limit} is non-@code{nil}, then the scan ends at position
483ab230
CY
2918@var{limit}. If there is no property change before that point, this
2919function returns @var{limit}.
b8d4c8d0
GM
2920
2921The value is @code{nil} if the properties remain unchanged all the way
2922to the end of @var{object} and @var{limit} is @code{nil}. If the value
2923is non-@code{nil}, it is a position greater than or equal to @var{pos}.
2924The value equals @var{pos} only when @var{limit} equals @var{pos}.
2925
2926Here is an example of how to scan the buffer by chunks of text within
2927which all properties are constant:
2928
2929@smallexample
2930(while (not (eobp))
2931 (let ((plist (text-properties-at (point)))
2932 (next-change
2933 (or (next-property-change (point) (current-buffer))
2934 (point-max))))
2935 @r{Process text from point to @var{next-change}@dots{}}
2936 (goto-char next-change)))
2937@end smallexample
2938@end defun
2939
2940@defun previous-property-change pos &optional object limit
2941This is like @code{next-property-change}, but scans back from @var{pos}
2942instead of forward. If the value is non-@code{nil}, it is a position
2943less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
2944equals @var{pos}.
2945@end defun
2946
2947@defun next-single-property-change pos prop &optional object limit
2948The function scans text for a change in the @var{prop} property, then
2949returns the position of the change. The scan goes forward from
2950position @var{pos} in the string or buffer @var{object}. In other
2951words, this function returns the position of the first character
2952beyond @var{pos} whose @var{prop} property differs from that of the
2953character just after @var{pos}.
2954
2955If @var{limit} is non-@code{nil}, then the scan ends at position
2956@var{limit}. If there is no property change before that point,
2957@code{next-single-property-change} returns @var{limit}.
2958
2959The value is @code{nil} if the property remains unchanged all the way to
2960the end of @var{object} and @var{limit} is @code{nil}. If the value is
2961non-@code{nil}, it is a position greater than or equal to @var{pos}; it
2962equals @var{pos} only if @var{limit} equals @var{pos}.
2963@end defun
2964
2965@defun previous-single-property-change pos prop &optional object limit
2966This is like @code{next-single-property-change}, but scans back from
2967@var{pos} instead of forward. If the value is non-@code{nil}, it is a
2968position less than or equal to @var{pos}; it equals @var{pos} only if
2969@var{limit} equals @var{pos}.
2970@end defun
2971
2972@defun next-char-property-change pos &optional limit
2973This is like @code{next-property-change} except that it considers
2974overlay properties as well as text properties, and if no change is
2975found before the end of the buffer, it returns the maximum buffer
2976position rather than @code{nil} (in this sense, it resembles the
2977corresponding overlay function @code{next-overlay-change}, rather than
2978@code{next-property-change}). There is no @var{object} operand
2979because this function operates only on the current buffer. It returns
2980the next address at which either kind of property changes.
2981@end defun
2982
2983@defun previous-char-property-change pos &optional limit
2984This is like @code{next-char-property-change}, but scans back from
2985@var{pos} instead of forward, and returns the minimum buffer
2986position if no change is found.
2987@end defun
2988
2989@defun next-single-char-property-change pos prop &optional object limit
2990This is like @code{next-single-property-change} except that it
2991considers overlay properties as well as text properties, and if no
2992change is found before the end of the @var{object}, it returns the
2993maximum valid position in @var{object} rather than @code{nil}. Unlike
2994@code{next-char-property-change}, this function @emph{does} have an
2995@var{object} operand; if @var{object} is not a buffer, only
2996text-properties are considered.
2997@end defun
2998
2999@defun previous-single-char-property-change pos prop &optional object limit
3000This is like @code{next-single-char-property-change}, but scans back
3001from @var{pos} instead of forward, and returns the minimum valid
3002position in @var{object} if no change is found.
3003@end defun
3004
3005@defun text-property-any start end prop value &optional object
3006This function returns non-@code{nil} if at least one character between
3007@var{start} and @var{end} has a property @var{prop} whose value is
3008@var{value}. More precisely, it returns the position of the first such
3009character. Otherwise, it returns @code{nil}.
3010
3011The optional fifth argument, @var{object}, specifies the string or
3012buffer to scan. Positions are relative to @var{object}. The default
3013for @var{object} is the current buffer.
3014@end defun
3015
3016@defun text-property-not-all start end prop value &optional object
3017This function returns non-@code{nil} if at least one character between
3018@var{start} and @var{end} does not have a property @var{prop} with value
3019@var{value}. More precisely, it returns the position of the first such
3020character. Otherwise, it returns @code{nil}.
3021
3022The optional fifth argument, @var{object}, specifies the string or
3023buffer to scan. Positions are relative to @var{object}. The default
3024for @var{object} is the current buffer.
3025@end defun
3026
3027@node Special Properties
3028@subsection Properties with Special Meanings
3029
3030 Here is a table of text property names that have special built-in
3031meanings. The following sections list a few additional special property
3032names that control filling and property inheritance. All other names
3033have no standard meaning, and you can use them as you like.
3034
3035 Note: the properties @code{composition}, @code{display},
3036@code{invisible} and @code{intangible} can also cause point to move to
3037an acceptable place, after each Emacs command. @xref{Adjusting
3038Point}.
3039
3040@table @code
3041@cindex property category of text character
e4043ba0 3042@c FIXME: Isn't @kindex for keyboard commands?
b8d4c8d0
GM
3043@kindex category @r{(text property)}
3044@item category
3045If a character has a @code{category} property, we call it the
3046@dfn{property category} of the character. It should be a symbol. The
3047properties of this symbol serve as defaults for the properties of the
3048character.
3049
3050@item face
3051@cindex face codes of text
3052@kindex face @r{(text property)}
cd542620
CY
3053The @code{face} property controls the appearance of the character
3054(@pxref{Faces}). The value of the property can be the following:
b8d4c8d0
GM
3055
3056@itemize @bullet
3057@item
3058A face name (a symbol or string).
3059
3060@item
cd542620
CY
3061An anonymous face: a property list of the form @code{(@var{keyword}
3062@var{value} @dots{})}, where each @var{keyword} is a face attribute
3063name and @var{value} is a value for that attribute.
b8d4c8d0 3064
483ab230 3065@item
cd542620
CY
3066A list of faces. Each list element should be either a face name or an
3067anonymous face. This specifies a face which is an aggregate of the
6175e34b 3068attributes of each of the listed faces. Faces occurring earlier in
cd542620
CY
3069the list have higher priority.
3070
3071@item
3072A cons cell of the form @code{(foreground-color . @var{color-name})}
3073or @code{(background-color . @var{color-name})}. This specifies the
3074foreground or background color, similar to @code{(:foreground
3075@var{color-name})} or @code{(:background @var{color-name})}. This
3076form is supported for backward compatibility only, and should be
3077avoided.
483ab230 3078@end itemize
db3625ba
RS
3079
3080Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
3081dynamically updating the @code{face} property of characters based on
3082the context.
b8d4c8d0
GM
3083
3084@item font-lock-face
3085@kindex font-lock-face @r{(text property)}
eeafcea7
CY
3086This property specifies a value for the @code{face} property that Font
3087Lock mode should apply to the underlying text. It is one of the
3088fontification methods used by Font Lock mode, and is useful for
3089special modes that implement their own highlighting.
3090@xref{Precalculated Fontification}. When Font Lock mode is disabled,
db3625ba 3091@code{font-lock-face} has no effect.
b8d4c8d0 3092
b8d4c8d0
GM
3093@item mouse-face
3094@kindex mouse-face @r{(text property)}
eeafcea7
CY
3095This property is used instead of @code{face} when the mouse is on or
3096near the character. For this purpose, ``near'' means that all text
3097between the character and where the mouse is have the same
b8d4c8d0
GM
3098@code{mouse-face} property value.
3099
ebb552ed 3100Emacs ignores all face attributes from the @code{mouse-face} property
1df7defd 3101that alter the text size (e.g., @code{:height}, @code{:weight}, and
ebb552ed
CY
3102@code{:slant}). Those attributes are always the same as for the
3103unhighlighted text.
3104
b8d4c8d0
GM
3105@item fontified
3106@kindex fontified @r{(text property)}
3107This property says whether the text is ready for display. If
3108@code{nil}, Emacs's redisplay routine calls the functions in
3109@code{fontification-functions} (@pxref{Auto Faces}) to prepare this
3110part of the buffer before it is displayed. It is used internally by
3111the ``just in time'' font locking code.
3112
3113@item display
3114This property activates various features that change the
3115way text is displayed. For example, it can make text appear taller
3116or shorter, higher or lower, wider or narrow, or replaced with an image.
3117@xref{Display Property}.
3118
3119@item help-echo
3120@kindex help-echo @r{(text property)}
3121@cindex tooltip
3122@anchor{Text help-echo}
3123If text has a string as its @code{help-echo} property, then when you
3124move the mouse onto that text, Emacs displays that string in the echo
3125area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
3126Manual}).
3127
3128If the value of the @code{help-echo} property is a function, that
3129function is called with three arguments, @var{window}, @var{object} and
3130@var{pos} and should return a help string or @code{nil} for
3131none. The first argument, @var{window} is the window in which
3132the help was found. The second, @var{object}, is the buffer, overlay or
3133string which had the @code{help-echo} property. The @var{pos}
3134argument is as follows:
3135
3136@itemize @bullet{}
3137@item
3138If @var{object} is a buffer, @var{pos} is the position in the buffer.
3139@item
3140If @var{object} is an overlay, that overlay has a @code{help-echo}
3141property, and @var{pos} is the position in the overlay's buffer.
3142@item
3143If @var{object} is a string (an overlay string or a string displayed
3144with the @code{display} property), @var{pos} is the position in that
3145string.
3146@end itemize
3147
3148If the value of the @code{help-echo} property is neither a function nor
3149a string, it is evaluated to obtain a help string.
3150
3151You can alter the way help text is displayed by setting the variable
3152@code{show-help-function} (@pxref{Help display}).
3153
3154This feature is used in the mode line and for other active text.
3155
3156@item keymap
3157@cindex keymap of character
3158@kindex keymap @r{(text property)}
3159The @code{keymap} property specifies an additional keymap for
3160commands. When this keymap applies, it is used for key lookup before
3161the minor mode keymaps and before the buffer's local map.
3162@xref{Active Keymaps}. If the property value is a symbol, the
3163symbol's function definition is used as the keymap.
3164
3165The property's value for the character before point applies if it is
3166non-@code{nil} and rear-sticky, and the property's value for the
3167character after point applies if it is non-@code{nil} and
3168front-sticky. (For mouse clicks, the position of the click is used
3169instead of the position of point.)
3170
3171@item local-map
3172@kindex local-map @r{(text property)}
3173This property works like @code{keymap} except that it specifies a
3174keymap to use @emph{instead of} the buffer's local map. For most
3175purposes (perhaps all purposes), it is better to use the @code{keymap}
3176property.
3177
3178@item syntax-table
3179The @code{syntax-table} property overrides what the syntax table says
3180about this particular character. @xref{Syntax Properties}.
3181
3182@item read-only
3183@cindex read-only character
3184@kindex read-only @r{(text property)}
3185If a character has the property @code{read-only}, then modifying that
3186character is not allowed. Any command that would do so gets an error,
3187@code{text-read-only}. If the property value is a string, that string
3188is used as the error message.
3189
3190Insertion next to a read-only character is an error if inserting
3191ordinary text there would inherit the @code{read-only} property due to
3192stickiness. Thus, you can control permission to insert next to
3193read-only text by controlling the stickiness. @xref{Sticky Properties}.
3194
3195Since changing properties counts as modifying the buffer, it is not
3196possible to remove a @code{read-only} property unless you know the
3197special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
3198and then remove the property. @xref{Read Only Buffers}.
3199
3200@item invisible
3201@kindex invisible @r{(text property)}
3202A non-@code{nil} @code{invisible} property can make a character invisible
3203on the screen. @xref{Invisible Text}, for details.
3204
3205@item intangible
3206@kindex intangible @r{(text property)}
3207If a group of consecutive characters have equal and non-@code{nil}
3208@code{intangible} properties, then you cannot place point between them.
3209If you try to move point forward into the group, point actually moves to
3210the end of the group. If you try to move point backward into the group,
3211point actually moves to the start of the group.
3212
3213If consecutive characters have unequal non-@code{nil}
3214@code{intangible} properties, they belong to separate groups; each
3215group is separately treated as described above.
3216
3217When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
3218the @code{intangible} property is ignored.
3219
a7cdbfce
SM
3220Beware: this property operates at a very low level, and affects a lot of code
3221in unexpected ways. So use it with extreme caution. A common misuse is to put
3222an intangible property on invisible text, which is actually unnecessary since
3223the command loop will move point outside of the invisible text at the end of
3224each command anyway. @xref{Adjusting Point}.
3225
b8d4c8d0
GM
3226@item field
3227@kindex field @r{(text property)}
3228Consecutive characters with the same @code{field} property constitute a
3229@dfn{field}. Some motion functions including @code{forward-word} and
3230@code{beginning-of-line} stop moving at a field boundary.
3231@xref{Fields}.
3232
3233@item cursor
3234@kindex cursor @r{(text property)}
50fe197c
EZ
3235Normally, the cursor is displayed at the beginning or the end of any
3236overlay and text property strings present at the current buffer
3237position. You can place the cursor on any desired character of these
3238strings by giving that character a non-@code{nil} @code{cursor} text
3239property. In addition, if the value of the @code{cursor} property is
3240an integer number, it specifies the number of buffer's character
3241positions, starting with the position where the overlay or the
3242@code{display} property begins, for which the cursor should be
3243displayed on that character. Specifically, if the value of the
3244@code{cursor} property of a character is the number @var{n}, the
3245cursor will be displayed on this character for any buffer position in
3246the range @code{[@var{ovpos}..@var{ovpos}+@var{n})}, where @var{ovpos}
3247is the overlay's starting position given by @code{overlay-start}
3248(@pxref{Managing Overlays}), or the position where the @code{display}
3249text property begins in the buffer.
3250
3251In other words, the string character with the @code{cursor} property
3252of any non-@code{nil} value is the character where to display the
3253cursor. The value of the property says for which buffer positions to
3254display the cursor there. If the value is an integer number @var{n},
3255the cursor is displayed there when point is anywhere between the
3256beginning of the overlay or @code{display} property and @var{n}
3257positions after that. If the value is anything else and
3258non-@code{nil}, the cursor is displayed there only when point is at
3259the beginning of the @code{display} property or at
3260@code{overlay-start}.
3261
3262@cindex cursor position for @code{display} properties and overlays
3263When the buffer has many overlay strings (e.g., @pxref{Overlay
3264Properties, before-string}) or @code{display} properties that are
3265strings, it is a good idea to use the @code{cursor} property on these
3266strings to cue the Emacs display about the places where to put the
3267cursor while traversing these strings. This directly communicates to
3268the display engine where the Lisp program wants to put the cursor, or
3269where the user would expect the cursor.
b8d4c8d0
GM
3270
3271@item pointer
3272@kindex pointer @r{(text property)}
3273This specifies a specific pointer shape when the mouse pointer is over
3274this text or image. @xref{Pointer Shape}, for possible pointer
3275shapes.
3276
3277@item line-spacing
3278@kindex line-spacing @r{(text property)}
3279A newline can have a @code{line-spacing} text or overlay property that
3280controls the height of the display line ending with that newline. The
3281property value overrides the default frame line spacing and the buffer
3282local @code{line-spacing} variable. @xref{Line Height}.
3283
3284@item line-height
3285@kindex line-height @r{(text property)}
3286A newline can have a @code{line-height} text or overlay property that
3287controls the total height of the display line ending in that newline.
3288@xref{Line Height}.
3289
c4f4682b
MB
3290@item wrap-prefix
3291If text has a @code{wrap-prefix} property, the prefix it defines will
579ebf8f 3292be added at display time to the beginning of every continuation line
c4f4682b 3293due to text wrapping (so if lines are truncated, the wrap-prefix is
579ebf8f
EZ
3294never used). It may be a string or an image (@pxref{Other Display
3295Specs}), or a stretch of whitespace such as specified by the
3296@code{:width} or @code{:align-to} display properties (@pxref{Specified
3297Space}).
c4f4682b
MB
3298
3299A wrap-prefix may also be specified for an entire buffer using the
3300@code{wrap-prefix} buffer-local variable (however, a
3301@code{wrap-prefix} text-property takes precedence over the value of
3302the @code{wrap-prefix} variable). @xref{Truncation}.
3303
3304@item line-prefix
3305If text has a @code{line-prefix} property, the prefix it defines will
579ebf8f
EZ
3306be added at display time to the beginning of every non-continuation
3307line. It may be a string or an image (@pxref{Other Display
3308Specs}), or a stretch of whitespace such as specified by the
3309@code{:width} or @code{:align-to} display properties (@pxref{Specified
3310Space}).
c4f4682b
MB
3311
3312A line-prefix may also be specified for an entire buffer using the
3313@code{line-prefix} buffer-local variable (however, a
3314@code{line-prefix} text-property takes precedence over the value of
3315the @code{line-prefix} variable). @xref{Truncation}.
3316
b8d4c8d0
GM
3317@item modification-hooks
3318@cindex change hooks for a character
3319@cindex hooks for changing a character
3320@kindex modification-hooks @r{(text property)}
3321If a character has the property @code{modification-hooks}, then its
f816790b
SM
3322value should be a list of functions; modifying that character calls
3323all of those functions before the actual modification. Each function
3324receives two arguments: the beginning and end of the part of the
3325buffer being modified. Note that if a particular modification hook
3326function appears on several characters being modified by a single
3327primitive, you can't predict how many times the function will
3328be called.
3329Furthermore, insertion will not modify any existing character, so this
3330hook will only be run when removing some characters, replacing them
3331with others, or changing their text-properties.
b8d4c8d0
GM
3332
3333If these functions modify the buffer, they should bind
3334@code{inhibit-modification-hooks} to @code{t} around doing so, to
3335avoid confusing the internal mechanism that calls these hooks.
3336
3337Overlays also support the @code{modification-hooks} property, but the
3338details are somewhat different (@pxref{Overlay Properties}).
3339
3340@item insert-in-front-hooks
3341@itemx insert-behind-hooks
3342@kindex insert-in-front-hooks @r{(text property)}
3343@kindex insert-behind-hooks @r{(text property)}
3344The operation of inserting text in a buffer also calls the functions
3345listed in the @code{insert-in-front-hooks} property of the following
3346character and in the @code{insert-behind-hooks} property of the
3347preceding character. These functions receive two arguments, the
3348beginning and end of the inserted text. The functions are called
3349@emph{after} the actual insertion takes place.
3350
3351See also @ref{Change Hooks}, for other hooks that are called
3352when you change text in a buffer.
3353
3354@item point-entered
3355@itemx point-left
3356@cindex hooks for motion of point
3357@kindex point-entered @r{(text property)}
3358@kindex point-left @r{(text property)}
3359The special properties @code{point-entered} and @code{point-left}
3360record hook functions that report motion of point. Each time point
3361moves, Emacs compares these two property values:
3362
3363@itemize @bullet
3364@item
3365the @code{point-left} property of the character after the old location,
3366and
3367@item
3368the @code{point-entered} property of the character after the new
3369location.
3370@end itemize
3371
3372@noindent
3373If these two values differ, each of them is called (if not @code{nil})
3374with two arguments: the old value of point, and the new one.
3375
3376The same comparison is made for the characters before the old and new
3377locations. The result may be to execute two @code{point-left} functions
3378(which may be the same function) and/or two @code{point-entered}
3379functions (which may be the same function). In any case, all the
3380@code{point-left} functions are called first, followed by all the
3381@code{point-entered} functions.
3382
e3934a8a 3383It is possible to use @code{char-after} to examine characters at various
b8d4c8d0
GM
3384buffer positions without moving point to those positions. Only an
3385actual change in the value of point runs these hook functions.
3386
e3934a8a
EZ
3387The variable @code{inhibit-point-motion-hooks} can inhibit running the
3388@code{point-left} and @code{point-entered} hooks, see @ref{Inhibit
3389point motion hooks}.
3390
3391@item composition
3392@kindex composition @r{(text property)}
3393This text property is used to display a sequence of characters as a
3394single glyph composed from components. But the value of the property
3395itself is completely internal to Emacs and should not be manipulated
3396directly by, for instance, @code{put-text-property}.
3397
3398@end table
3399
b8d4c8d0 3400@defvar inhibit-point-motion-hooks
e3934a8a
EZ
3401@anchor{Inhibit point motion hooks} When this variable is
3402non-@code{nil}, @code{point-left} and @code{point-entered} hooks are
3403not run, and the @code{intangible} property has no effect. Do not set
3404this variable globally; bind it with @code{let}.
b8d4c8d0
GM
3405@end defvar
3406
3407@defvar show-help-function
3408@anchor{Help display} If this variable is non-@code{nil}, it specifies a
3409function called to display help strings. These may be @code{help-echo}
3410properties, menu help strings (@pxref{Simple Menu Items},
3411@pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
3412Bar}). The specified function is called with one argument, the help
3413string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs
3414Manual}) provides an example.
3415@end defvar
3416
b8d4c8d0
GM
3417@node Format Properties
3418@subsection Formatted Text Properties
3419
3420 These text properties affect the behavior of the fill commands. They
3421are used for representing formatted text. @xref{Filling}, and
3422@ref{Margins}.
3423
3424@table @code
3425@item hard
3426If a newline character has this property, it is a ``hard'' newline.
3427The fill commands do not alter hard newlines and do not move words
3428across them. However, this property takes effect only if the
3429@code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft
3430Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
3431
3432@item right-margin
3433This property specifies an extra right margin for filling this part of the
3434text.
3435
3436@item left-margin
3437This property specifies an extra left margin for filling this part of the
3438text.
3439
3440@item justification
3441This property specifies the style of justification for filling this part
3442of the text.
3443@end table
3444
3445@node Sticky Properties
3446@subsection Stickiness of Text Properties
3447@cindex sticky text properties
02676e5d 3448@cindex inheritance, text property
b8d4c8d0
GM
3449
3450 Self-inserting characters normally take on the same properties as the
3451preceding character. This is called @dfn{inheritance} of properties.
3452
483ab230
CY
3453 A Lisp program can do insertion with inheritance or without,
3454depending on the choice of insertion primitive. The ordinary text
3455insertion functions, such as @code{insert}, do not inherit any
3456properties. They insert text with precisely the properties of the
3457string being inserted, and no others. This is correct for programs
3458that copy text from one context to another---for example, into or out
3459of the kill ring. To insert with inheritance, use the special
3460primitives described in this section. Self-inserting characters
3461inherit properties because they work using these primitives.
b8d4c8d0
GM
3462
3463 When you do insertion with inheritance, @emph{which} properties are
3464inherited, and from where, depends on which properties are @dfn{sticky}.
3465Insertion after a character inherits those of its properties that are
3466@dfn{rear-sticky}. Insertion before a character inherits those of its
3467properties that are @dfn{front-sticky}. When both sides offer different
3468sticky values for the same property, the previous character's value
3469takes precedence.
3470
3471 By default, a text property is rear-sticky but not front-sticky; thus,
3472the default is to inherit all the properties of the preceding character,
3473and nothing from the following character.
3474
3475 You can control the stickiness of various text properties with two
3476specific text properties, @code{front-sticky} and @code{rear-nonsticky},
3477and with the variable @code{text-property-default-nonsticky}. You can
3478use the variable to specify a different default for a given property.
3479You can use those two text properties to make any specific properties
3480sticky or nonsticky in any particular part of the text.
3481
3482 If a character's @code{front-sticky} property is @code{t}, then all
3483its properties are front-sticky. If the @code{front-sticky} property is
3484a list, then the sticky properties of the character are those whose
3485names are in the list. For example, if a character has a
3486@code{front-sticky} property whose value is @code{(face read-only)},
3487then insertion before the character can inherit its @code{face} property
3488and its @code{read-only} property, but no others.
3489
3490 The @code{rear-nonsticky} property works the opposite way. Most
3491properties are rear-sticky by default, so the @code{rear-nonsticky}
3492property says which properties are @emph{not} rear-sticky. If a
3493character's @code{rear-nonsticky} property is @code{t}, then none of its
3494properties are rear-sticky. If the @code{rear-nonsticky} property is a
3495list, properties are rear-sticky @emph{unless} their names are in the
3496list.
3497
3498@defvar text-property-default-nonsticky
3499This variable holds an alist which defines the default rear-stickiness
3500of various text properties. Each element has the form
3501@code{(@var{property} . @var{nonstickiness})}, and it defines the
3502stickiness of a particular text property, @var{property}.
3503
3504If @var{nonstickiness} is non-@code{nil}, this means that the property
3505@var{property} is rear-nonsticky by default. Since all properties are
3506front-nonsticky by default, this makes @var{property} nonsticky in both
3507directions by default.
3508
3509The text properties @code{front-sticky} and @code{rear-nonsticky}, when
3510used, take precedence over the default @var{nonstickiness} specified in
3511@code{text-property-default-nonsticky}.
3512@end defvar
3513
3514 Here are the functions that insert text with inheritance of properties:
3515
3516@defun insert-and-inherit &rest strings
3517Insert the strings @var{strings}, just like the function @code{insert},
3518but inherit any sticky properties from the adjoining text.
3519@end defun
3520
3521@defun insert-before-markers-and-inherit &rest strings
3522Insert the strings @var{strings}, just like the function
3523@code{insert-before-markers}, but inherit any sticky properties from the
3524adjoining text.
3525@end defun
3526
3527 @xref{Insertion}, for the ordinary insertion functions which do not
3528inherit.
3529
3530@node Lazy Properties
3531@subsection Lazy Computation of Text Properties
3532
3533 Instead of computing text properties for all the text in the buffer,
3534you can arrange to compute the text properties for parts of the text
3535when and if something depends on them.
3536
3537 The primitive that extracts text from the buffer along with its
3538properties is @code{buffer-substring}. Before examining the properties,
3539this function runs the abnormal hook @code{buffer-access-fontify-functions}.
3540
3541@defvar buffer-access-fontify-functions
3542This variable holds a list of functions for computing text properties.
3543Before @code{buffer-substring} copies the text and text properties for a
3544portion of the buffer, it calls all the functions in this list. Each of
3545the functions receives two arguments that specify the range of the
3546buffer being accessed. (The buffer itself is always the current
3547buffer.)
3548@end defvar
3549
3550 The function @code{buffer-substring-no-properties} does not call these
3551functions, since it ignores text properties anyway.
3552
3553 In order to prevent the hook functions from being called more than
3554once for the same part of the buffer, you can use the variable
3555@code{buffer-access-fontified-property}.
3556
3557@defvar buffer-access-fontified-property
3558If this variable's value is non-@code{nil}, it is a symbol which is used
3559as a text property name. A non-@code{nil} value for that text property
3560means, ``the other text properties for this character have already been
16152b76 3561computed''.
b8d4c8d0
GM
3562
3563If all the characters in the range specified for @code{buffer-substring}
3564have a non-@code{nil} value for this property, @code{buffer-substring}
3565does not call the @code{buffer-access-fontify-functions} functions. It
3566assumes these characters already have the right text properties, and
3567just copies the properties they already have.
3568
3569The normal way to use this feature is that the
3570@code{buffer-access-fontify-functions} functions add this property, as
3571well as others, to the characters they operate on. That way, they avoid
3572being called over and over for the same text.
3573@end defvar
3574
3575@node Clickable Text
3576@subsection Defining Clickable Text
3577@cindex clickable text
2bad3299
CY
3578@cindex follow links
3579@cindex mouse-1
b8d4c8d0
GM
3580
3581 @dfn{Clickable text} is text that can be clicked, with either the
2bad3299
CY
3582mouse or via a keyboard command, to produce some result. Many major
3583modes use clickable text to implement textual hyper-links, or
3584@dfn{links} for short.
3585
3586 The easiest way to insert and manipulate links is to use the
3587@code{button} package. @xref{Buttons}. In this section, we will
3588explain how to manually set up clickable text in a buffer, using text
3589properties. For simplicity, we will refer to the clickable text as a
3590@dfn{link}.
3591
3592 Implementing a link involves three separate steps: (1) indicating
0b128ac4 3593clickability when the mouse moves over the link; (2) making @key{RET}
2bad3299
CY
3594or @kbd{Mouse-2} on that link do something; and (3) setting up a
3595@code{follow-link} condition so that the link obeys
3596@code{mouse-1-click-follows-link}.
3597
3598 To indicate clickability, add the @code{mouse-face} text property to
3599the text of the link; then Emacs will highlight the link when the
3600mouse moves over it. In addition, you should define a tooltip or echo
3601area message, using the @code{help-echo} text property. @xref{Special
3602Properties}. For instance, here is how Dired indicates that file
3603names are clickable:
b8d4c8d0
GM
3604
3605@smallexample
2bad3299
CY
3606 (if (dired-move-to-filename)
3607 (add-text-properties
3608 (point)
3609 (save-excursion
3610 (dired-move-to-end-of-filename)
3611 (point))
3612 '(mouse-face highlight
3613 help-echo "mouse-2: visit this file in other window")))
b8d4c8d0
GM
3614@end smallexample
3615
2bad3299
CY
3616 To make the link clickable, bind @key{RET} and @kbd{Mouse-2} to
3617commands that perform the desired action. Each command should check
3618to see whether it was called on a link, and act accordingly. For
3619instance, Dired's major mode keymap binds @kbd{Mouse-2} to the
3620following command:
b8d4c8d0
GM
3621
3622@smallexample
3623(defun dired-mouse-find-file-other-window (event)
3624 "In Dired, visit the file or directory name you click on."
3625 (interactive "e")
c57008f6
SM
3626 (let ((window (posn-window (event-end event)))
3627 (pos (posn-point (event-end event)))
3628 file)
3629 (if (not (windowp window))
3630 (error "No file chosen"))
3631 (with-current-buffer (window-buffer window)
b8d4c8d0
GM
3632 (goto-char pos)
3633 (setq file (dired-get-file-for-visit)))
3634 (if (file-directory-p file)
3635 (or (and (cdr dired-subdir-alist)
3636 (dired-goto-subdir file))
3637 (progn
3638 (select-window window)
3639 (dired-other-window file)))
3640 (select-window window)
3641 (find-file-other-window (file-name-sans-versions file t)))))
3642@end smallexample
3643
3644@noindent
2bad3299
CY
3645This command uses the functions @code{posn-window} and
3646@code{posn-point} to determine where the click occurred, and
3647@code{dired-get-file-for-visit} to determine which file to visit.
b8d4c8d0 3648
2bad3299
CY
3649 Instead of binding the mouse command in a major mode keymap, you can
3650bind it within the link text, using the @code{keymap} text property
3651(@pxref{Special Properties}). For instance:
b8d4c8d0
GM
3652
3653@example
3654(let ((map (make-sparse-keymap)))
3655 (define-key map [mouse-2] 'operate-this-button)
2bad3299 3656 (put-text-property link-start link-end 'keymap map))
b8d4c8d0
GM
3657@end example
3658
3659@noindent
2bad3299
CY
3660With this method, you can easily define different commands for
3661different links. Furthermore, the global definition of @key{RET} and
3662@kbd{Mouse-2} remain available for the rest of the text in the buffer.
3663
3664@vindex mouse-1-click-follows-link
3665 The basic Emacs command for clicking on links is @kbd{Mouse-2}.
3666However, for compatibility with other graphical applications, Emacs
3667also recognizes @kbd{Mouse-1} clicks on links, provided the user
3668clicks on the link quickly without moving the mouse. This behavior is
3669controlled by the user option @code{mouse-1-click-follows-link}.
3670@xref{Mouse References,,, emacs, The GNU Emacs Manual}.
3671
3672 To set up the link so that it obeys
3673@code{mouse-1-click-follows-link}, you must either (1) apply a
3674@code{follow-link} text or overlay property to the link text, or (2)
3675bind the @code{follow-link} event to a keymap (which can be a major
3676mode keymap or a local keymap specified via the @code{keymap} text
3677property). The value of the @code{follow-link} property, or the
3678binding for the @code{follow-link} event, acts as a ``condition'' for
3679the link action. This condition tells Emacs two things: the
3680circumstances under which a @kbd{Mouse-1} click should be regarded as
3681occurring ``inside'' the link, and how to compute an ``action code''
3682that says what to translate the @kbd{Mouse-1} click into. The link
3683action condition can be one of the following:
b8d4c8d0
GM
3684
3685@table @asis
3686@item @code{mouse-face}
2bad3299
CY
3687If the condition is the symbol @code{mouse-face}, a position is inside
3688a link if there is a non-@code{nil} @code{mouse-face} property at that
3689position. The action code is always @code{t}.
b8d4c8d0
GM
3690
3691For example, here is how Info mode handles @key{Mouse-1}:
3692
3693@smallexample
3694(define-key Info-mode-map [follow-link] 'mouse-face)
3695@end smallexample
3696
3697@item a function
2bad3299
CY
3698If the condition is a function, @var{func}, then a position @var{pos}
3699is inside a link if @code{(@var{func} @var{pos})} evaluates to
3700non-@code{nil}. The value returned by @var{func} serves as the action
3701code.
b8d4c8d0 3702
2bad3299 3703For example, here is how pcvs enables @kbd{Mouse-1} to follow links on
b8d4c8d0
GM
3704file names only:
3705
3706@smallexample
3707(define-key map [follow-link]
3708 (lambda (pos)
3709 (eq (get-char-property pos 'face) 'cvs-filename-face)))
3710@end smallexample
3711
3712@item anything else
3713If the condition value is anything else, then the position is inside a
2bad3299
CY
3714link and the condition itself is the action code. Clearly, you should
3715specify this kind of condition only when applying the condition via a
3716text or property overlay on the link text (so that it does not apply
3717to the entire buffer).
b8d4c8d0
GM
3718@end table
3719
3720@noindent
2bad3299 3721The action code tells @kbd{Mouse-1} how to follow the link:
b8d4c8d0
GM
3722
3723@table @asis
3724@item a string or vector
2bad3299 3725If the action code is a string or vector, the @kbd{Mouse-1} event is
b8d4c8d0 3726translated into the first element of the string or vector; i.e., the
2bad3299 3727action of the @kbd{Mouse-1} click is the local or global binding of
b8d4c8d0 3728that character or symbol. Thus, if the action code is @code{"foo"},
2bad3299
CY
3729@kbd{Mouse-1} translates into @kbd{f}. If it is @code{[foo]},
3730@kbd{Mouse-1} translates into @key{foo}.
b8d4c8d0
GM
3731
3732@item anything else
2bad3299
CY
3733For any other non-@code{nil} action code, the @kbd{Mouse-1} event is
3734translated into a @kbd{Mouse-2} event at the same position.
b8d4c8d0
GM
3735@end table
3736
2bad3299 3737 To define @kbd{Mouse-1} to activate a button defined with
b8d4c8d0 3738@code{define-button-type}, give the button a @code{follow-link}
2bad3299
CY
3739property. The property value should be a link action condition, as
3740described above. @xref{Buttons}. For example, here is how Help mode
3741handles @kbd{Mouse-1}:
b8d4c8d0
GM
3742
3743@smallexample
3744(define-button-type 'help-xref
3745 'follow-link t
3746 'action #'help-button-action)
3747@end smallexample
3748
2bad3299
CY
3749 To define @kbd{Mouse-1} on a widget defined with
3750@code{define-widget}, give the widget a @code{:follow-link} property.
3751The property value should be a link action condition, as described
3752above. For example, here is how the @code{link} widget specifies that
b8d4c8d0
GM
3753a @key{Mouse-1} click shall be translated to @key{RET}:
3754
3755@smallexample
3756(define-widget 'link 'item
3757 "An embedded link."
3758 :button-prefix 'widget-link-prefix
3759 :button-suffix 'widget-link-suffix
3760 :follow-link "\C-m"
3761 :help-echo "Follow the link."
3762 :format "%[%t%]")
3763@end smallexample
3764
3765@defun mouse-on-link-p pos
3766This function returns non-@code{nil} if position @var{pos} in the
3767current buffer is on a link. @var{pos} can also be a mouse event
db3625ba 3768location, as returned by @code{event-start} (@pxref{Accessing Mouse}).
b8d4c8d0
GM
3769@end defun
3770
3771@node Fields
3772@subsection Defining and Using Fields
3773@cindex fields
3774
3775 A field is a range of consecutive characters in the buffer that are
3776identified by having the same value (comparing with @code{eq}) of the
3777@code{field} property (either a text-property or an overlay property).
3778This section describes special functions that are available for
3779operating on fields.
3780
3781 You specify a field with a buffer position, @var{pos}. We think of
3782each field as containing a range of buffer positions, so the position
3783you specify stands for the field containing that position.
3784
3785 When the characters before and after @var{pos} are part of the same
3786field, there is no doubt which field contains @var{pos}: the one those
3787characters both belong to. When @var{pos} is at a boundary between
3788fields, which field it belongs to depends on the stickiness of the
3789@code{field} properties of the two surrounding characters (@pxref{Sticky
3790Properties}). The field whose property would be inherited by text
3791inserted at @var{pos} is the field that contains @var{pos}.
3792
3793 There is an anomalous case where newly inserted text at @var{pos}
3794would not inherit the @code{field} property from either side. This
3795happens if the previous character's @code{field} property is not
3796rear-sticky, and the following character's @code{field} property is not
3797front-sticky. In this case, @var{pos} belongs to neither the preceding
3798field nor the following field; the field functions treat it as belonging
3799to an empty field whose beginning and end are both at @var{pos}.
3800
3801 In all of these functions, if @var{pos} is omitted or @code{nil}, the
3802value of point is used by default. If narrowing is in effect, then
3803@var{pos} should fall within the accessible portion. @xref{Narrowing}.
3804
3805@defun field-beginning &optional pos escape-from-edge limit
3806This function returns the beginning of the field specified by @var{pos}.
3807
3808If @var{pos} is at the beginning of its field, and
3809@var{escape-from-edge} is non-@code{nil}, then the return value is
3810always the beginning of the preceding field that @emph{ends} at @var{pos},
3811regardless of the stickiness of the @code{field} properties around
3812@var{pos}.
3813
3814If @var{limit} is non-@code{nil}, it is a buffer position; if the
3815beginning of the field is before @var{limit}, then @var{limit} will be
3816returned instead.
3817@end defun
3818
3819@defun field-end &optional pos escape-from-edge limit
3820This function returns the end of the field specified by @var{pos}.
3821
3822If @var{pos} is at the end of its field, and @var{escape-from-edge} is
3823non-@code{nil}, then the return value is always the end of the following
3824field that @emph{begins} at @var{pos}, regardless of the stickiness of
3825the @code{field} properties around @var{pos}.
3826
3827If @var{limit} is non-@code{nil}, it is a buffer position; if the end
3828of the field is after @var{limit}, then @var{limit} will be returned
3829instead.
3830@end defun
3831
3832@defun field-string &optional pos
3833This function returns the contents of the field specified by @var{pos},
3834as a string.
3835@end defun
3836
3837@defun field-string-no-properties &optional pos
3838This function returns the contents of the field specified by @var{pos},
3839as a string, discarding text properties.
3840@end defun
3841
3842@defun delete-field &optional pos
3843This function deletes the text of the field specified by @var{pos}.
3844@end defun
3845
3846@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
3847This function ``constrains'' @var{new-pos} to the field that
3848@var{old-pos} belongs to---in other words, it returns the position
3849closest to @var{new-pos} that is in the same field as @var{old-pos}.
3850
3851If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
3852the value of point instead, and moves point to the resulting position
66c5eebd 3853in addition to returning that position.
b8d4c8d0
GM
3854
3855If @var{old-pos} is at the boundary of two fields, then the acceptable
3856final positions depend on the argument @var{escape-from-edge}. If
3857@var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in
3858the field whose @code{field} property equals what new characters
3859inserted at @var{old-pos} would inherit. (This depends on the
3860stickiness of the @code{field} property for the characters before and
3861after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
3862@var{new-pos} can be anywhere in the two adjacent fields.
3863Additionally, if two fields are separated by another field with the
3864special value @code{boundary}, then any point within this special
16152b76 3865field is also considered to be ``on the boundary''.
b8d4c8d0 3866
e4920bc9 3867Commands like @kbd{C-a} with no argument, that normally move backward
b8d4c8d0
GM
3868to a specific kind of location and stay there once there, probably
3869should specify @code{nil} for @var{escape-from-edge}. Other motion
3870commands that check fields should probably pass @code{t}.
3871
3872If the optional argument @var{only-in-line} is non-@code{nil}, and
3873constraining @var{new-pos} in the usual way would move it to a different
3874line, @var{new-pos} is returned unconstrained. This used in commands
3875that move by line, such as @code{next-line} and
3876@code{beginning-of-line}, so that they respect field boundaries only in
3877the case where they can still move to the right line.
3878
3879If the optional argument @var{inhibit-capture-property} is
3880non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that
3881name, then any field boundaries are ignored.
3882
3883You can cause @code{constrain-to-field} to ignore all field boundaries
3884(and so never constrain anything) by binding the variable
3885@code{inhibit-field-text-motion} to a non-@code{nil} value.
3886@end defun
3887
3888@node Not Intervals
3889@subsection Why Text Properties are not Intervals
3890@cindex intervals
3891
3892 Some editors that support adding attributes to text in the buffer do
3893so by letting the user specify ``intervals'' within the text, and adding
3894the properties to the intervals. Those editors permit the user or the
3895programmer to determine where individual intervals start and end. We
3896deliberately provided a different sort of interface in Emacs Lisp to
3897avoid certain paradoxical behavior associated with text modification.
3898
3899 If the actual subdivision into intervals is meaningful, that means you
3900can distinguish between a buffer that is just one interval with a
3901certain property, and a buffer containing the same text subdivided into
3902two intervals, both of which have that property.
3903
3904 Suppose you take the buffer with just one interval and kill part of
3905the text. The text remaining in the buffer is one interval, and the
3906copy in the kill ring (and the undo list) becomes a separate interval.
3907Then if you yank back the killed text, you get two intervals with the
3908same properties. Thus, editing does not preserve the distinction
3909between one interval and two.
3910
3911 Suppose we ``fix'' this problem by coalescing the two intervals when
3912the text is inserted. That works fine if the buffer originally was a
3913single interval. But suppose instead that we have two adjacent
3914intervals with the same properties, and we kill the text of one interval
3915and yank it back. The same interval-coalescence feature that rescues
3916the other case causes trouble in this one: after yanking, we have just
3917one interval. One again, editing does not preserve the distinction
3918between one interval and two.
3919
3920 Insertion of text at the border between intervals also raises
3921questions that have no satisfactory answer.
3922
3923 However, it is easy to arrange for editing to behave consistently for
3924questions of the form, ``What are the properties of this character?''
3925So we have decided these are the only questions that make sense; we have
3926not implemented asking questions about where intervals start or end.
3927
3928 In practice, you can usually use the text property search functions in
3929place of explicit interval boundaries. You can think of them as finding
3930the boundaries of intervals, assuming that intervals are always
3931coalesced whenever possible. @xref{Property Search}.
3932
3933 Emacs also provides explicit intervals as a presentation feature; see
3934@ref{Overlays}.
3935
3936@node Substitution
3937@section Substituting for a Character Code
3938
3939 The following functions replace characters within a specified region
3940based on their character codes.
3941
3942@defun subst-char-in-region start end old-char new-char &optional noundo
3943@cindex replace characters
3944This function replaces all occurrences of the character @var{old-char}
3945with the character @var{new-char} in the region of the current buffer
3946defined by @var{start} and @var{end}.
3947
3948@cindex undo avoidance
3949If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
3950not record the change for undo and does not mark the buffer as modified.
3951This was useful for controlling the old selective display feature
3952(@pxref{Selective Display}).
3953
3954@code{subst-char-in-region} does not move point and returns
3955@code{nil}.
3956
3957@example
3958@group
3959---------- Buffer: foo ----------
3960This is the contents of the buffer before.
3961---------- Buffer: foo ----------
3962@end group
3963
3964@group
3965(subst-char-in-region 1 20 ?i ?X)
3966 @result{} nil
3967
3968---------- Buffer: foo ----------
3969ThXs Xs the contents of the buffer before.
3970---------- Buffer: foo ----------
3971@end group
3972@end example
3973@end defun
3974
106e6894 3975@deffn Command translate-region start end table
b8d4c8d0
GM
3976This function applies a translation table to the characters in the
3977buffer between positions @var{start} and @var{end}.
3978
3979The translation table @var{table} is a string or a char-table;
3980@code{(aref @var{table} @var{ochar})} gives the translated character
3981corresponding to @var{ochar}. If @var{table} is a string, any
3982characters with codes larger than the length of @var{table} are not
3983altered by the translation.
3984
3985The return value of @code{translate-region} is the number of
3986characters that were actually changed by the translation. This does
3987not count characters that were mapped into themselves in the
3988translation table.
106e6894 3989@end deffn
b8d4c8d0
GM
3990
3991@node Registers
3992@section Registers
3993@cindex registers
3994
3995 A register is a sort of variable used in Emacs editing that can hold a
3996variety of different kinds of values. Each register is named by a
3997single character. All @acronym{ASCII} characters and their meta variants
3998(but with the exception of @kbd{C-g}) can be used to name registers.
3999Thus, there are 255 possible registers. A register is designated in
4000Emacs Lisp by the character that is its name.
4001
4002@defvar register-alist
4003This variable is an alist of elements of the form @code{(@var{name} .
4004@var{contents})}. Normally, there is one element for each Emacs
4005register that has been used.
4006
4007The object @var{name} is a character (an integer) identifying the
4008register.
4009@end defvar
4010
4011 The @var{contents} of a register can have several possible types:
4012
4013@table @asis
4014@item a number
4015A number stands for itself. If @code{insert-register} finds a number
4016in the register, it converts the number to decimal.
4017
4018@item a marker
4019A marker represents a buffer position to jump to.
4020
4021@item a string
4022A string is text saved in the register.
4023
4024@item a rectangle
4025A rectangle is represented by a list of strings.
4026
4027@item @code{(@var{window-configuration} @var{position})}
4028This represents a window configuration to restore in one frame, and a
4029position to jump to in the current buffer.
4030
c5074806 4031@c FIXME: Mention frameset here.
b8d4c8d0
GM
4032@item @code{(@var{frame-configuration} @var{position})}
4033This represents a frame configuration to restore, and a position
4034to jump to in the current buffer.
4035
4036@item (file @var{filename})
4037This represents a file to visit; jumping to this value visits file
4038@var{filename}.
4039
4040@item (file-query @var{filename} @var{position})
4041This represents a file to visit and a position in it; jumping to this
4042value visits file @var{filename} and goes to buffer position
4043@var{position}. Restoring this type of position asks the user for
4044confirmation first.
4045@end table
4046
4047 The functions in this section return unpredictable values unless
4048otherwise stated.
4049
4050@defun get-register reg
4051This function returns the contents of the register
4052@var{reg}, or @code{nil} if it has no contents.
4053@end defun
4054
4055@defun set-register reg value
4056This function sets the contents of register @var{reg} to @var{value}.
4057A register can be set to any value, but the other register functions
4058expect only certain data types. The return value is @var{value}.
4059@end defun
4060
4061@deffn Command view-register reg
4062This command displays what is contained in register @var{reg}.
4063@end deffn
4064
b8d4c8d0
GM
4065@deffn Command insert-register reg &optional beforep
4066This command inserts contents of register @var{reg} into the current
4067buffer.
4068
4069Normally, this command puts point before the inserted text, and the
4070mark after it. However, if the optional second argument @var{beforep}
4071is non-@code{nil}, it puts the mark before and point after.
4072You can pass a non-@code{nil} second argument @var{beforep} to this
4073function interactively by supplying any prefix argument.
4074
4075If the register contains a rectangle, then the rectangle is inserted
4076with its upper left corner at point. This means that text is inserted
4077in the current line and underneath it on successive lines.
4078
4079If the register contains something other than saved text (a string) or
4080a rectangle (a list), currently useless things happen. This may be
4081changed in the future.
4082@end deffn
4083
b8d4c8d0
GM
4084@node Transposition
4085@section Transposition of Text
4086
10256988 4087 This function can be used to transpose stretches of text:
b8d4c8d0
GM
4088
4089@defun transpose-regions start1 end1 start2 end2 &optional leave-markers
4090This function exchanges two nonoverlapping portions of the buffer.
4091Arguments @var{start1} and @var{end1} specify the bounds of one portion
4092and arguments @var{start2} and @var{end2} specify the bounds of the
4093other portion.
4094
4095Normally, @code{transpose-regions} relocates markers with the transposed
4096text; a marker previously positioned within one of the two transposed
4097portions moves along with that portion, thus remaining between the same
4098two characters in their new position. However, if @var{leave-markers}
4099is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
4100all markers unrelocated.
4101@end defun
4102
4103@node Base 64
4104@section Base 64 Encoding
4105@cindex base 64 encoding
4106
4107 Base 64 code is used in email to encode a sequence of 8-bit bytes as
4108a longer sequence of @acronym{ASCII} graphic characters. It is defined in
4109Internet RFC@footnote{
4110An RFC, an acronym for @dfn{Request for Comments}, is a numbered
4111Internet informational document describing a standard. RFCs are
4112usually written by technical experts acting on their own initiative,
4113and are traditionally written in a pragmatic, experience-driven
4114manner.
4115}2045. This section describes the functions for
4116converting to and from this code.
4117
106e6894 4118@deffn Command base64-encode-region beg end &optional no-line-break
b8d4c8d0
GM
4119This function converts the region from @var{beg} to @var{end} into base
412064 code. It returns the length of the encoded text. An error is
1df7defd 4121signaled if a character in the region is multibyte, i.e., in a
b8d4c8d0
GM
4122multibyte buffer the region must contain only characters from the
4123charsets @code{ascii}, @code{eight-bit-control} and
4124@code{eight-bit-graphic}.
4125
4126Normally, this function inserts newline characters into the encoded
4127text, to avoid overlong lines. However, if the optional argument
4128@var{no-line-break} is non-@code{nil}, these newlines are not added, so
4129the output is just one long line.
106e6894 4130@end deffn
b8d4c8d0 4131
0b128ac4 4132@defun base64-encode-string string &optional no-line-break
b8d4c8d0
GM
4133This function converts the string @var{string} into base 64 code. It
4134returns a string containing the encoded text. As for
4135@code{base64-encode-region}, an error is signaled if a character in the
4136string is multibyte.
4137
4138Normally, this function inserts newline characters into the encoded
4139text, to avoid overlong lines. However, if the optional argument
4140@var{no-line-break} is non-@code{nil}, these newlines are not added, so
4141the result string is just one long line.
0b128ac4 4142@end defun
b8d4c8d0 4143
0b128ac4 4144@deffn Command base64-decode-region beg end
b8d4c8d0
GM
4145This function converts the region from @var{beg} to @var{end} from base
414664 code into the corresponding decoded text. It returns the length of
4147the decoded text.
4148
4149The decoding functions ignore newline characters in the encoded text.
0b128ac4 4150@end deffn
b8d4c8d0
GM
4151
4152@defun base64-decode-string string
4153This function converts the string @var{string} from base 64 code into
4154the corresponding decoded text. It returns a unibyte string containing the
4155decoded text.
4156
4157The decoding functions ignore newline characters in the encoded text.
4158@end defun
4159
5f5e4ea1
GM
4160@node Checksum/Hash
4161@section Checksum/Hash
b8d4c8d0 4162@cindex MD5 checksum
483ab230
CY
4163@cindex SHA hash
4164@cindex hash, cryptographic
4165@cindex cryptographic hash
4166
4167 Emacs has built-in support for computing @dfn{cryptographic hashes}.
4168A cryptographic hash, or @dfn{checksum}, is a digital ``fingerprint''
1df7defd 4169of a piece of data (e.g., a block of text) which can be used to check
483ab230
CY
4170that you have an unaltered copy of that data.
4171
4172@cindex message digest
4173 Emacs supports several common cryptographic hash algorithms: MD5,
4174SHA-1, SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512. MD5 is the
4175oldest of these algorithms, and is commonly used in @dfn{message
4176digests} to check the integrity of messages transmitted over a
1df7defd 4177network. MD5 is not ``collision resistant'' (i.e., it is possible to
483ab230
CY
4178deliberately design different pieces of data which have the same MD5
4179hash), so you should not used it for anything security-related. A
4180similar theoretical weakness also exists in SHA-1. Therefore, for
4181security-related applications you should use the other hash types,
4182such as SHA-2.
b8d4c8d0 4183
483ab230
CY
4184@defun secure-hash algorithm object &optional start end binary
4185This function returns a hash for @var{object}. The argument
4186@var{algorithm} is a symbol stating which hash to compute: one of
4187@code{md5}, @code{sha1}, @code{sha224}, @code{sha256}, @code{sha384}
4188or @code{sha512}. The argument @var{object} should be a buffer or a
4189string.
b8d4c8d0 4190
483ab230 4191The optional arguments @var{start} and @var{end} are character
b8d4c8d0 4192positions specifying the portion of @var{object} to compute the
483ab230 4193message digest for. If they are @code{nil} or omitted, the hash is
b8d4c8d0
GM
4194computed for the whole of @var{object}.
4195
483ab230
CY
4196If the argument @var{binary} is omitted or @code{nil}, the function
4197returns the @dfn{text form} of the hash, as an ordinary Lisp string.
4198If @var{binary} is non-@code{nil}, it returns the hash in @dfn{binary
4199form}, as a sequence of bytes stored in a unibyte string.
4200
4201This function does not compute the hash directly from the internal
4202representation of @var{object}'s text (@pxref{Text Representations}).
4203Instead, it encodes the text using a coding system (@pxref{Coding
4204Systems}), and computes the hash from that encoded text. If
4205@var{object} is a buffer, the coding system used is the one which
4206would be chosen by default for writing the text into a file. If
4207@var{object} is a string, the user's preferred coding system is used
4208(@pxref{Recognize Coding,,, emacs, GNU Emacs Manual}).
4209@end defun
4210
4211@defun md5 object &optional start end coding-system noerror
4212This function returns an MD5 hash. It is semi-obsolete, since for
4213most purposes it is equivalent to calling @code{secure-hash} with
4214@code{md5} as the @var{algorithm} argument. The @var{object},
4215@var{start} and @var{end} arguments have the same meanings as in
4216@code{secure-hash}.
4217
4218If @var{coding-system} is non-@code{nil}, it specifies a coding system
4219to use to encode the text; if omitted or @code{nil}, the default
4220coding system is used, like in @code{secure-hash}.
b8d4c8d0
GM
4221
4222Normally, @code{md5} signals an error if the text can't be encoded
4223using the specified or chosen coding system. However, if
4224@var{noerror} is non-@code{nil}, it silently uses @code{raw-text}
4225coding instead.
4226@end defun
4227
483ab230
CY
4228@node Parsing HTML/XML
4229@section Parsing HTML and XML
381408e2 4230@cindex parsing html
381408e2 4231
483ab230
CY
4232When Emacs is compiled with libxml2 support, the following functions
4233are available to parse HTML or XML text into Lisp object trees.
4234
35a30759 4235@defun libxml-parse-html-region start end &optional base-url
483ab230
CY
4236This function parses the text between @var{start} and @var{end} as
4237HTML, and returns a list representing the HTML @dfn{parse tree}. It
4238attempts to handle ``real world'' HTML by robustly coping with syntax
4239mistakes.
381408e2 4240
483ab230
CY
4241The optional argument @var{base-url}, if non-@code{nil}, should be a
4242string specifying the base URL for relative URLs occurring in links.
381408e2 4243
483ab230
CY
4244In the parse tree, each HTML node is represented by a list in which
4245the first element is a symbol representing the node name, the second
4246element is an alist of node attributes, and the remaining elements are
4247the subnodes.
4248
4249The following example demonstrates this. Given this (malformed) HTML
4250document:
381408e2
LMI
4251
4252@example
483ab230 4253<html><head></head><body width=101><div class=thing>Foo<div>Yes
381408e2
LMI
4254@end example
4255
483ab230
CY
4256@noindent
4257A call to @code{libxml-parse-html-region} returns this:
381408e2
LMI
4258
4259@example
483ab230
CY
4260(html ()
4261 (head ())
4262 (body ((width . "101"))
4263 (div ((class . "thing"))
4264 "Foo"
4265 (div ()
4266 "Yes"))))
381408e2 4267@end example
35a30759
N
4268@end defun
4269
4270@cindex parsing xml
4271@defun libxml-parse-xml-region start end &optional base-url
483ab230
CY
4272This function is the same as @code{libxml-parse-html-region}, except
4273that it parses the text as XML rather than HTML (so it is stricter
4274about syntax).
35a30759 4275@end defun
381408e2 4276
b8d4c8d0
GM
4277@node Atomic Changes
4278@section Atomic Change Groups
4279@cindex atomic changes
4280
35a30759 4281 In database terminology, an @dfn{atomic} change is an indivisible
b8d4c8d0
GM
4282change---it can succeed entirely or it can fail entirely, but it
4283cannot partly succeed. A Lisp program can make a series of changes to
4284one or several buffers as an @dfn{atomic change group}, meaning that
4285either the entire series of changes will be installed in their buffers
4286or, in case of an error, none of them will be.
4287
4288 To do this for one buffer, the one already current, simply write a
4289call to @code{atomic-change-group} around the code that makes the
4290changes, like this:
4291
4292@example
4293(atomic-change-group
4294 (insert foo)
4295 (delete-region x y))
4296@end example
4297
4298@noindent
4299If an error (or other nonlocal exit) occurs inside the body of
4300@code{atomic-change-group}, it unmakes all the changes in that buffer
4301that were during the execution of the body. This kind of change group
4302has no effect on any other buffers---any such changes remain.
4303
4304 If you need something more sophisticated, such as to make changes in
4305various buffers constitute one atomic group, you must directly call
4306lower-level functions that @code{atomic-change-group} uses.
4307
4308@defun prepare-change-group &optional buffer
4309This function sets up a change group for buffer @var{buffer}, which
4310defaults to the current buffer. It returns a ``handle'' that
4311represents the change group. You must use this handle to activate the
4312change group and subsequently to finish it.
4313@end defun
4314
4315 To use the change group, you must @dfn{activate} it. You must do
4316this before making any changes in the text of @var{buffer}.
4317
4318@defun activate-change-group handle
4319This function activates the change group that @var{handle} designates.
4320@end defun
4321
4322 After you activate the change group, any changes you make in that
4323buffer become part of it. Once you have made all the desired changes
4324in the buffer, you must @dfn{finish} the change group. There are two
4325ways to do this: you can either accept (and finalize) all the changes,
4326or cancel them all.
4327
4328@defun accept-change-group handle
4329This function accepts all the changes in the change group specified by
4330@var{handle}, making them final.
4331@end defun
4332
4333@defun cancel-change-group handle
4334This function cancels and undoes all the changes in the change group
4335specified by @var{handle}.
4336@end defun
4337
4338 Your code should use @code{unwind-protect} to make sure the group is
4339always finished. The call to @code{activate-change-group} should be
4340inside the @code{unwind-protect}, in case the user types @kbd{C-g}
4341just after it runs. (This is one reason why
4342@code{prepare-change-group} and @code{activate-change-group} are
4343separate functions, because normally you would call
4344@code{prepare-change-group} before the start of that
4345@code{unwind-protect}.) Once you finish the group, don't use the
4346handle again---in particular, don't try to finish the same group
4347twice.
4348
4349 To make a multibuffer change group, call @code{prepare-change-group}
4350once for each buffer you want to cover, then use @code{nconc} to
4351combine the returned values, like this:
4352
4353@example
4354(nconc (prepare-change-group buffer-1)
4355 (prepare-change-group buffer-2))
4356@end example
4357
4358You can then activate the multibuffer change group with a single call
4359to @code{activate-change-group}, and finish it with a single call to
4360@code{accept-change-group} or @code{cancel-change-group}.
4361
4362 Nested use of several change groups for the same buffer works as you
4363would expect. Non-nested use of change groups for the same buffer
4364will get Emacs confused, so don't let it happen; the first change
4365group you start for any given buffer should be the last one finished.
4366
4367@node Change Hooks
4368@section Change Hooks
4369@cindex change hooks
4370@cindex hooks for text changes
4371
4372 These hook variables let you arrange to take notice of all changes in
4373all buffers (or in a particular buffer, if you make them buffer-local).
4374See also @ref{Special Properties}, for how to detect changes to specific
4375parts of the text.
4376
4377 The functions you use in these hooks should save and restore the match
4378data if they do anything that uses regular expressions; otherwise, they
4379will interfere in bizarre ways with the editing operations that call
4380them.
4381
4382@defvar before-change-functions
4383This variable holds a list of functions to call before any buffer
4384modification. Each function gets two arguments, the beginning and end
4385of the region that is about to change, represented as integers. The
4386buffer that is about to change is always the current buffer.
4387@end defvar
4388
4389@defvar after-change-functions
4390This variable holds a list of functions to call after any buffer
5a5fd9f3
CY
4391modification. Each function receives three arguments: the beginning
4392and end of the region just changed, and the length of the text that
4393existed before the change. All three arguments are integers. The
93c2fa46 4394buffer that has been changed is always the current buffer.
5a5fd9f3
CY
4395
4396The length of the old text is the difference between the buffer
4397positions before and after that text as it was before the change. As
4398for the changed text, its length is simply the difference between the
4399first two arguments.
b8d4c8d0
GM
4400@end defvar
4401
2bb0eca1 4402 Output of messages into the @file{*Messages*} buffer does not
b8d4c8d0
GM
4403call these functions.
4404
4405@defmac combine-after-change-calls body@dots{}
4406The macro executes @var{body} normally, but arranges to call the
4407after-change functions just once for a series of several changes---if
4408that seems safe.
4409
4410If a program makes several text changes in the same area of the buffer,
4411using the macro @code{combine-after-change-calls} around that part of
4412the program can make it run considerably faster when after-change hooks
4413are in use. When the after-change hooks are ultimately called, the
4414arguments specify a portion of the buffer including all of the changes
4415made within the @code{combine-after-change-calls} body.
4416
4417@strong{Warning:} You must not alter the values of
4418@code{after-change-functions} within
4419the body of a @code{combine-after-change-calls} form.
4420
4421@strong{Warning:} if the changes you combine occur in widely scattered
4422parts of the buffer, this will still work, but it is not advisable,
4423because it may lead to inefficient behavior for some change hook
4424functions.
4425@end defmac
4426
4427@defvar first-change-hook
4428This variable is a normal hook that is run whenever a buffer is changed
4429that was previously in the unmodified state.
4430@end defvar
4431
4432@defvar inhibit-modification-hooks
4433If this variable is non-@code{nil}, all of the change hooks are
4434disabled; none of them run. This affects all the hook variables
4435described above in this section, as well as the hooks attached to
4436certain special text properties (@pxref{Special Properties}) and overlay
4437properties (@pxref{Overlay Properties}).
4438
4439Also, this variable is bound to non-@code{nil} while running those
4440same hook variables, so that by default modifying the buffer from
4441a modification hook does not cause other modification hooks to be run.
4442If you do want modification hooks to be run in a particular piece of
4443code that is itself run from a modification hook, then rebind locally
4444@code{inhibit-modification-hooks} to @code{nil}.
4445@end defvar