Mercurial > emacs
comparison lispref/text.texi @ 88155:d7ddb3e565de
sync with trunk
author | Henrik Enberg <henrik.enberg@telia.com> |
---|---|
date | Mon, 16 Jan 2006 00:03:54 +0000 |
parents | 5c2d8e3b81b4 |
children |
comparison
equal
deleted
inserted
replaced
88154:8ce476d3ba36 | 88155:d7ddb3e565de |
---|---|
1 @c -*-texinfo-*- | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | 2 @c This is part of the GNU Emacs Lisp Reference Manual. |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, |
4 @c Free Software Foundation, Inc. | 4 @c 2002, 2003, 2004, 2005 Free Software Foundation, Inc. |
5 @c See the file elisp.texi for copying conditions. | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/text | 6 @setfilename ../info/text |
7 @node Text, Non-ASCII Characters, Markers, Top | 7 @node Text, Non-ASCII Characters, Markers, Top |
8 @chapter Text | 8 @chapter Text |
9 @cindex text | 9 @cindex text |
56 * Transposition:: Swapping two portions of a buffer. | 56 * Transposition:: Swapping two portions of a buffer. |
57 * Registers:: How registers are implemented. Accessing the text or | 57 * Registers:: How registers are implemented. Accessing the text or |
58 position stored in a register. | 58 position stored in a register. |
59 * Base 64:: Conversion to or from base 64 encoding. | 59 * Base 64:: Conversion to or from base 64 encoding. |
60 * MD5 Checksum:: Compute the MD5 ``message digest''/``checksum''. | 60 * MD5 Checksum:: Compute the MD5 ``message digest''/``checksum''. |
61 * Atomic Changes:: Installing several buffer changes ``atomically''. | |
61 * Change Hooks:: Supplying functions to be run when text is changed. | 62 * Change Hooks:: Supplying functions to be run when text is changed. |
62 @end menu | 63 @end menu |
63 | 64 |
64 @node Near Point | 65 @node Near Point |
65 @section Examining Text Near Point | 66 @section Examining Text Near Point |
66 | 67 |
67 Many functions are provided to look at the characters around point. | 68 Many functions are provided to look at the characters around point. |
68 Several simple functions are described here. See also @code{looking-at} | 69 Several simple functions are described here. See also @code{looking-at} |
69 in @ref{Regexp Search}. | 70 in @ref{Regexp Search}. |
71 | |
72 In the following four functions, ``beginning'' or ``end'' of buffer | |
73 refers to the beginning or end of the accessible portion. | |
70 | 74 |
71 @defun char-after &optional position | 75 @defun char-after &optional position |
72 This function returns the character in the current buffer at (i.e., | 76 This function returns the character in the current buffer at (i.e., |
73 immediately after) position @var{position}. If @var{position} is out of | 77 immediately after) position @var{position}. If @var{position} is out of |
74 range for this purpose, either before the beginning of the buffer, or at | 78 range for this purpose, either before the beginning of the buffer, or at |
87 @end defun | 91 @end defun |
88 | 92 |
89 @defun char-before &optional position | 93 @defun char-before &optional position |
90 This function returns the character in the current buffer immediately | 94 This function returns the character in the current buffer immediately |
91 before position @var{position}. If @var{position} is out of range for | 95 before position @var{position}. If @var{position} is out of range for |
92 this purpose, either before the beginning of the buffer, or at or beyond | 96 this purpose, either at or before the beginning of the buffer, or beyond |
93 the end, then the value is @code{nil}. The default for | 97 the end, then the value is @code{nil}. The default for |
94 @var{position} is point. | 98 @var{position} is point. |
95 @end defun | 99 @end defun |
96 | 100 |
97 @defun following-char | 101 @defun following-char |
156 @end defun | 160 @end defun |
157 | 161 |
158 @node Buffer Contents | 162 @node Buffer Contents |
159 @section Examining Buffer Contents | 163 @section Examining Buffer Contents |
160 | 164 |
161 This section describes two functions that allow a Lisp program to | 165 This section describes functions that allow a Lisp program to |
162 convert any portion of the text in the buffer into a string. | 166 convert any portion of the text in the buffer into a string. |
163 | 167 |
164 @defun buffer-substring start end | 168 @defun buffer-substring start end |
165 This function returns a string containing a copy of the text of the | 169 This function returns a string containing a copy of the text of the |
166 region defined by positions @var{start} and @var{end} in the current | 170 region defined by positions @var{start} and @var{end} in the current |
185 ---------- Buffer: foo ---------- | 189 ---------- Buffer: foo ---------- |
186 @end group | 190 @end group |
187 | 191 |
188 @group | 192 @group |
189 (buffer-substring 1 10) | 193 (buffer-substring 1 10) |
190 @result{} "This is t" | 194 @result{} "This is t" |
191 @end group | 195 @end group |
192 @group | 196 @group |
193 (buffer-substring (point-max) 10) | 197 (buffer-substring (point-max) 10) |
194 @result{} "he contents of buffer foo | 198 @result{} "he contents of buffer foo\n" |
195 " | |
196 @end group | 199 @end group |
197 @end example | 200 @end example |
198 @end defun | 201 @end defun |
199 | 202 |
200 @defun buffer-substring-no-properties start end | 203 @defun buffer-substring-no-properties start end |
201 This is like @code{buffer-substring}, except that it does not copy text | 204 This is like @code{buffer-substring}, except that it does not copy text |
202 properties, just the characters themselves. @xref{Text Properties}. | 205 properties, just the characters themselves. @xref{Text Properties}. |
203 @end defun | 206 @end defun |
207 | |
208 @defun filter-buffer-substring start end &optional delete | |
209 This function passes the buffer text between @var{start} and @var{end} | |
210 through the filter functions specified by the variable | |
211 @code{buffer-substring-filters}, and returns the value from the last | |
212 filter function. If @code{buffer-substring-filters} is @code{nil}, | |
213 the value is the unaltered text from the buffer, what | |
214 @code{buffer-substring} would return. | |
215 | |
216 If @var{delete} is non-@code{nil}, this function deletes the text | |
217 between @var{start} and @var{end} after copying it, like | |
218 @code{delete-and-extract-region}. | |
219 | |
220 Lisp code should use this function instead of @code{buffer-substring} | |
221 or @code{delete-and-extract-region} when copying into user-accessible | |
222 data structures such as the kill-ring, X clipboard, and registers. | |
223 Major and minor modes can add functions to | |
224 @code{buffer-substring-filters} to alter such text as it is copied out | |
225 of the buffer. | |
226 @end defun | |
227 | |
228 @defvar buffer-substring-filters | |
229 This variable should be a list of functions that accept a single | |
230 argument, a string, and return a string. | |
231 @code{filter-buffer-substring} passes the buffer substring to the | |
232 first function in this list, and the return value of each function is | |
233 passed to the next function. The return value of the last function is | |
234 used as the return value of @code{filter-buffer-substring}. | |
235 | |
236 As a special convention, point is set to the start of the buffer text | |
237 being operated on (i.e., the @var{start} argument for | |
238 @code{filter-buffer-substring}) before these functions are called. | |
239 | |
240 If this variable is @code{nil}, no filtering is performed. | |
241 @end defvar | |
204 | 242 |
205 @defun buffer-string | 243 @defun buffer-string |
206 This function returns the contents of the entire accessible portion of | 244 This function returns the contents of the entire accessible portion of |
207 the current buffer as a string. It is equivalent to | 245 the current buffer as a string. It is equivalent to |
208 | 246 |
216 This is the contents of buffer foo | 254 This is the contents of buffer foo |
217 | 255 |
218 ---------- Buffer: foo ---------- | 256 ---------- Buffer: foo ---------- |
219 | 257 |
220 (buffer-string) | 258 (buffer-string) |
221 @result{} "This is the contents of buffer foo | 259 @result{} "This is the contents of buffer foo\n" |
222 " | |
223 @end group | 260 @end group |
224 @end example | 261 @end example |
262 @end defun | |
263 | |
264 @tindex current-word | |
265 @defun current-word &optional strict really-word | |
266 This function returns the symbol (or word) at or near point, as a string. | |
267 The return value includes no text properties. | |
268 | |
269 If the optional argument @var{really-word} is non-@code{nil}, it finds a | |
270 word; otherwise, it finds a symbol (which includes both word | |
271 characters and symbol constituent characters). | |
272 | |
273 If the optional argument @var{strict} is non-@code{nil}, then point | |
274 must be in or next to the symbol or word---if no symbol or word is | |
275 there, the function returns @code{nil}. Otherwise, a nearby symbol or | |
276 word on the same line is acceptable. | |
225 @end defun | 277 @end defun |
226 | 278 |
227 @defun thing-at-point thing | 279 @defun thing-at-point thing |
228 Return the @var{thing} around or next to point, as a string. | 280 Return the @var{thing} around or next to point, as a string. |
229 | 281 |
255 copying them into strings first. | 307 copying them into strings first. |
256 | 308 |
257 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2 | 309 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2 |
258 This function lets you compare two substrings of the same buffer or two | 310 This function lets you compare two substrings of the same buffer or two |
259 different buffers. The first three arguments specify one substring, | 311 different buffers. The first three arguments specify one substring, |
260 giving a buffer and two positions within the buffer. The last three | 312 giving a buffer (or a buffer name) and two positions within the |
261 arguments specify the other substring in the same way. You can use | 313 buffer. The last three arguments specify the other substring in the |
262 @code{nil} for @var{buffer1}, @var{buffer2}, or both to stand for the | 314 same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or |
263 current buffer. | 315 both to stand for the current buffer. |
264 | 316 |
265 The value is negative if the first substring is less, positive if the | 317 The value is negative if the first substring is less, positive if the |
266 first is greater, and zero if they are equal. The absolute value of | 318 first is greater, and zero if they are equal. The absolute value of |
267 the result is one plus the index of the first differing characters | 319 the result is one plus the index of the first differing characters |
268 within the substrings. | 320 within the substrings. |
333 unless all @var{args} are either strings or characters. The value is | 385 unless all @var{args} are either strings or characters. The value is |
334 @code{nil}. | 386 @code{nil}. |
335 | 387 |
336 This function is unlike the other insertion functions in that it | 388 This function is unlike the other insertion functions in that it |
337 relocates markers initially pointing at the insertion point, to point | 389 relocates markers initially pointing at the insertion point, to point |
338 after the inserted text. If an overlay begins the insertion point, the | 390 after the inserted text. If an overlay begins at the insertion point, |
339 inserted text falls outside the overlay; if a nonempty overlay ends at | 391 the inserted text falls outside the overlay; if a nonempty overlay |
340 the insertion point, the inserted text falls inside that overlay. | 392 ends at the insertion point, the inserted text falls inside that |
393 overlay. | |
341 @end defun | 394 @end defun |
342 | 395 |
343 @defun insert-char character count &optional inherit | 396 @defun insert-char character count &optional inherit |
344 This function inserts @var{count} instances of @var{character} into the | 397 This function inserts @var{count} instances of @var{character} into the |
345 current buffer before point. The argument @var{count} should be a | 398 current buffer before point. The argument @var{count} should be an |
346 number (@code{nil} means 1), and @var{character} must be a character. | 399 integer, and @var{character} must be a character. The value is @code{nil}. |
347 The value is @code{nil}. | |
348 | 400 |
349 This function does not convert unibyte character codes 128 through 255 | 401 This function does not convert unibyte character codes 128 through 255 |
350 to multibyte characters, not even if the current buffer is a multibyte | 402 to multibyte characters, not even if the current buffer is a multibyte |
351 buffer. @xref{Converting Representations}. | 403 buffer. @xref{Converting Representations}. |
352 | 404 |
356 @end defun | 408 @end defun |
357 | 409 |
358 @defun insert-buffer-substring from-buffer-or-name &optional start end | 410 @defun insert-buffer-substring from-buffer-or-name &optional start end |
359 This function inserts a portion of buffer @var{from-buffer-or-name} | 411 This function inserts a portion of buffer @var{from-buffer-or-name} |
360 (which must already exist) into the current buffer before point. The | 412 (which must already exist) into the current buffer before point. The |
361 text inserted is the region from @var{start} and @var{end}. (These | 413 text inserted is the region between @var{start} and @var{end}. (These |
362 arguments default to the beginning and end of the accessible portion of | 414 arguments default to the beginning and end of the accessible portion of |
363 that buffer.) This function returns @code{nil}. | 415 that buffer.) This function returns @code{nil}. |
364 | 416 |
365 In this example, the form is executed with buffer @samp{bar} as the | 417 In this example, the form is executed with buffer @samp{bar} as the |
366 current buffer. We assume that buffer @samp{bar} is initially empty. | 418 current buffer. We assume that buffer @samp{bar} is initially empty. |
381 ---------- Buffer: bar ---------- | 433 ---------- Buffer: bar ---------- |
382 @end group | 434 @end group |
383 @end example | 435 @end example |
384 @end defun | 436 @end defun |
385 | 437 |
438 @defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end | |
439 This is like @code{insert-buffer-substring} except that it does not | |
440 copy any text properties. | |
441 @end defun | |
442 | |
386 @xref{Sticky Properties}, for other insertion functions that inherit | 443 @xref{Sticky Properties}, for other insertion functions that inherit |
387 text properties from the nearby text in addition to inserting it. | 444 text properties from the nearby text in addition to inserting it. |
388 Whitespace inserted by indentation functions also inherits text | 445 Whitespace inserted by indentation functions also inherits text |
389 properties. | 446 properties. |
390 | 447 |
394 This section describes higher-level commands for inserting text, | 451 This section describes higher-level commands for inserting text, |
395 commands intended primarily for the user but useful also in Lisp | 452 commands intended primarily for the user but useful also in Lisp |
396 programs. | 453 programs. |
397 | 454 |
398 @deffn Command insert-buffer from-buffer-or-name | 455 @deffn Command insert-buffer from-buffer-or-name |
399 This command inserts the entire contents of @var{from-buffer-or-name} | 456 This command inserts the entire accessible contents of |
400 (which must exist) into the current buffer after point. It leaves | 457 @var{from-buffer-or-name} (which must exist) into the current buffer |
401 the mark after the inserted text. The value is @code{nil}. | 458 after point. It leaves the mark after the inserted text. The value |
459 is @code{nil}. | |
402 @end deffn | 460 @end deffn |
403 | 461 |
404 @deffn Command self-insert-command count | 462 @deffn Command self-insert-command count |
405 @cindex character insertion | 463 @cindex character insertion |
406 @cindex self-insertion | 464 @cindex self-insertion |
410 is the most frequently called function in Emacs, but programs rarely use | 468 is the most frequently called function in Emacs, but programs rarely use |
411 it except to install it on a keymap. | 469 it except to install it on a keymap. |
412 | 470 |
413 In an interactive call, @var{count} is the numeric prefix argument. | 471 In an interactive call, @var{count} is the numeric prefix argument. |
414 | 472 |
473 Self-insertion translates the input character through | |
474 @code{translation-table-for-input}. @xref{Translation of Characters}. | |
475 | |
415 This command calls @code{auto-fill-function} whenever that is | 476 This command calls @code{auto-fill-function} whenever that is |
416 non-@code{nil} and the character inserted is in the table | 477 non-@code{nil} and the character inserted is in the table |
417 @code{auto-fill-chars} (@pxref{Auto Filling}). | 478 @code{auto-fill-chars} (@pxref{Auto Filling}). |
418 | 479 |
419 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92 | 480 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92 |
420 This command performs abbrev expansion if Abbrev mode is enabled and | 481 This command performs abbrev expansion if Abbrev mode is enabled and |
421 the inserted character does not have word-constituent | 482 the inserted character does not have word-constituent |
422 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) | 483 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also |
423 | 484 responsible for calling @code{blink-paren-function} when the inserted |
424 This is also responsible for calling @code{blink-paren-function} when | 485 character has close parenthesis syntax (@pxref{Blinking}). |
425 the inserted character has close parenthesis syntax (@pxref{Blinking}). | |
426 | 486 |
427 Do not try substituting your own definition of | 487 Do not try substituting your own definition of |
428 @code{self-insert-command} for the standard one. The editor command | 488 @code{self-insert-command} for the standard one. The editor command |
429 loop handles this function specially. | 489 loop handles this function specially. |
430 @end deffn | 490 @end deffn |
477 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be | 537 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be |
478 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}). | 538 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}). |
479 Some deletion functions do save text in the kill ring in some special | 539 Some deletion functions do save text in the kill ring in some special |
480 cases. | 540 cases. |
481 | 541 |
482 All of the deletion functions operate on the current buffer, and all | 542 All of the deletion functions operate on the current buffer. |
483 return a value of @code{nil}. | |
484 | 543 |
485 @deffn Command erase-buffer | 544 @deffn Command erase-buffer |
486 This function deletes the entire text of the current buffer, leaving it | 545 This function deletes the entire text of the current buffer |
546 (@emph{not} just the accessible portion), leaving it | |
487 empty. If the buffer is read-only, it signals a @code{buffer-read-only} | 547 empty. If the buffer is read-only, it signals a @code{buffer-read-only} |
488 error; if some of the text in it is read-only, it signals a | 548 error; if some of the text in it is read-only, it signals a |
489 @code{text-read-only} error. Otherwise, it deletes the text without | 549 @code{text-read-only} error. Otherwise, it deletes the text without |
490 asking for any confirmation. It returns @code{nil}. | 550 asking for any confirmation. It returns @code{nil}. |
491 | 551 |
567 | 627 |
568 @defopt backward-delete-char-untabify-method | 628 @defopt backward-delete-char-untabify-method |
569 This option specifies how @code{backward-delete-char-untabify} should | 629 This option specifies how @code{backward-delete-char-untabify} should |
570 deal with whitespace. Possible values include @code{untabify}, the | 630 deal with whitespace. Possible values include @code{untabify}, the |
571 default, meaning convert a tab to many spaces and delete one; | 631 default, meaning convert a tab to many spaces and delete one; |
572 @code{hungry}, meaning delete all the whitespace characters before point | 632 @code{hungry}, meaning delete all tabs and spaces before point with |
573 with one command, and @code{nil}, meaning do nothing special for | 633 one command; @code{all} meaning delete all tabs, spaces and newlines |
634 before point, and @code{nil}, meaning do nothing special for | |
574 whitespace characters. | 635 whitespace characters. |
575 @end defopt | 636 @end defopt |
576 | 637 |
577 @node User-Level Deletion | 638 @node User-Level Deletion |
578 @section User-Level Deletion Commands | 639 @section User-Level Deletion Commands |
579 | 640 |
580 This section describes higher-level commands for deleting text, | 641 This section describes higher-level commands for deleting text, |
581 commands intended primarily for the user but useful also in Lisp | 642 commands intended primarily for the user but useful also in Lisp |
582 programs. | 643 programs. |
583 | 644 |
584 @deffn Command delete-horizontal-space | 645 @deffn Command delete-horizontal-space &optional backward-only |
585 @cindex deleting whitespace | 646 @cindex deleting whitespace |
586 This function deletes all spaces and tabs around point. It returns | 647 This function deletes all spaces and tabs around point. It returns |
587 @code{nil}. | 648 @code{nil}. |
649 | |
650 If @var{backward-only} is non-@code{nil}, the function deletes | |
651 spaces and tabs before point, but not after point. | |
588 | 652 |
589 In the following examples, we call @code{delete-horizontal-space} four | 653 In the following examples, we call @code{delete-horizontal-space} four |
590 times, once on each line, with point between the second and third | 654 times, once on each line, with point between the second and third |
591 characters on the line each time. | 655 characters on the line each time. |
592 | 656 |
649 | 713 |
650 After the lines are joined, the function @code{fixup-whitespace} is | 714 After the lines are joined, the function @code{fixup-whitespace} is |
651 responsible for deciding whether to leave a space at the junction. | 715 responsible for deciding whether to leave a space at the junction. |
652 @end deffn | 716 @end deffn |
653 | 717 |
654 @defun fixup-whitespace | 718 @deffn Command fixup-whitespace |
655 This function replaces all the whitespace surrounding point with either | 719 This function replaces all the horizontal whitespace surrounding point |
656 one space or no space, according to the context. It returns @code{nil}. | 720 with either one space or no space, according to the context. It |
721 returns @code{nil}. | |
657 | 722 |
658 At the beginning or end of a line, the appropriate amount of space is | 723 At the beginning or end of a line, the appropriate amount of space is |
659 none. Before a character with close parenthesis syntax, or after a | 724 none. Before a character with close parenthesis syntax, or after a |
660 character with open parenthesis or expression-prefix syntax, no space is | 725 character with open parenthesis or expression-prefix syntax, no space is |
661 also appropriate. Otherwise, one space is appropriate. @xref{Syntax | 726 also appropriate. Otherwise, one space is appropriate. @xref{Syntax |
685 This has too many spaces | 750 This has too many spaces |
686 This has too many spaces at the start of (this list) | 751 This has too many spaces at the start of (this list) |
687 ---------- Buffer: foo ---------- | 752 ---------- Buffer: foo ---------- |
688 @end group | 753 @end group |
689 @end smallexample | 754 @end smallexample |
690 @end defun | 755 @end deffn |
691 | 756 |
692 @deffn Command just-one-space | 757 @deffn Command just-one-space &optional n |
693 @comment !!SourceFile simple.el | 758 @comment !!SourceFile simple.el |
694 This command replaces any spaces and tabs around point with a single | 759 This command replaces any spaces and tabs around point with a single |
695 space. It returns @code{nil}. | 760 space, or @var{n} spaces if @var{n} is specified. It returns |
761 @code{nil}. | |
696 @end deffn | 762 @end deffn |
697 | 763 |
698 @deffn Command delete-blank-lines | 764 @deffn Command delete-blank-lines |
699 This function deletes blank lines surrounding point. If point is on a | 765 This function deletes blank lines surrounding point. If point is on a |
700 blank line with one or more blank lines before or after it, then all but | 766 blank line with one or more blank lines before or after it, then all but |
701 one of them are deleted. If point is on an isolated blank line, then it | 767 one of them are deleted. If point is on an isolated blank line, then it |
702 is deleted. If point is on a nonblank line, the command deletes all | 768 is deleted. If point is on a nonblank line, the command deletes all |
703 blank lines following it. | 769 blank lines immediately following it. |
704 | 770 |
705 A blank line is defined as a line containing only tabs and spaces. | 771 A blank line is defined as a line containing only tabs and spaces. |
706 | 772 |
707 @code{delete-blank-lines} returns @code{nil}. | 773 @code{delete-blank-lines} returns @code{nil}. |
708 @end deffn | 774 @end deffn |
744 would be difficult to change the terminology now. | 810 would be difficult to change the terminology now. |
745 | 811 |
746 @menu | 812 @menu |
747 * Kill Ring Concepts:: What text looks like in the kill ring. | 813 * Kill Ring Concepts:: What text looks like in the kill ring. |
748 * Kill Functions:: Functions that kill text. | 814 * Kill Functions:: Functions that kill text. |
815 * Yanking:: How yanking is done. | |
749 * Yank Commands:: Commands that access the kill ring. | 816 * Yank Commands:: Commands that access the kill ring. |
750 * Low-Level Kill Ring:: Functions and variables for kill ring access. | 817 * Low-Level Kill Ring:: Functions and variables for kill ring access. |
751 * Internals of Kill Ring:: Variables that hold kill-ring data. | 818 * Internals of Kill Ring:: Variables that hold kill ring data. |
752 @end menu | 819 @end menu |
753 | 820 |
754 @node Kill Ring Concepts | 821 @node Kill Ring Concepts |
755 @comment node-name, next, previous, up | 822 @comment node-name, next, previous, up |
756 @subsection Kill Ring Concepts | 823 @subsection Kill Ring Concepts |
766 When the list reaches @code{kill-ring-max} entries in length, adding a | 833 When the list reaches @code{kill-ring-max} entries in length, adding a |
767 new entry automatically deletes the last entry. | 834 new entry automatically deletes the last entry. |
768 | 835 |
769 When kill commands are interwoven with other commands, each kill | 836 When kill commands are interwoven with other commands, each kill |
770 command makes a new entry in the kill ring. Multiple kill commands in | 837 command makes a new entry in the kill ring. Multiple kill commands in |
771 succession build up a single kill-ring entry, which would be yanked as a | 838 succession build up a single kill ring entry, which would be yanked as a |
772 unit; the second and subsequent consecutive kill commands add text to | 839 unit; the second and subsequent consecutive kill commands add text to |
773 the entry made by the first one. | 840 the entry made by the first one. |
774 | 841 |
775 For yanking, one entry in the kill ring is designated the ``front'' of | 842 For yanking, one entry in the kill ring is designated the ``front'' of |
776 the ring. Some yank commands ``rotate'' the ring by designating a | 843 the ring. Some yank commands ``rotate'' the ring by designating a |
788 newly killed text in a new element at the beginning of the kill ring or | 855 newly killed text in a new element at the beginning of the kill ring or |
789 adds it to the most recent element. It determines automatically (using | 856 adds it to the most recent element. It determines automatically (using |
790 @code{last-command}) whether the previous command was a kill command, | 857 @code{last-command}) whether the previous command was a kill command, |
791 and if so appends the killed text to the most recent entry. | 858 and if so appends the killed text to the most recent entry. |
792 | 859 |
793 @deffn Command kill-region start end | 860 @deffn Command kill-region start end &optional yank-handler |
794 This function kills the text in the region defined by @var{start} and | 861 This function kills the text in the region defined by @var{start} and |
795 @var{end}. The text is deleted but saved in the kill ring, along with | 862 @var{end}. The text is deleted but saved in the kill ring, along with |
796 its text properties. The value is always @code{nil}. | 863 its text properties. The value is always @code{nil}. |
797 | 864 |
798 In an interactive call, @var{start} and @var{end} are point and | 865 In an interactive call, @var{start} and @var{end} are point and |
801 @c Emacs 19 feature | 868 @c Emacs 19 feature |
802 If the buffer or text is read-only, @code{kill-region} modifies the kill | 869 If the buffer or text is read-only, @code{kill-region} modifies the kill |
803 ring just the same, then signals an error without modifying the buffer. | 870 ring just the same, then signals an error without modifying the buffer. |
804 This is convenient because it lets the user use a series of kill | 871 This is convenient because it lets the user use a series of kill |
805 commands to copy text from a read-only buffer into the kill ring. | 872 commands to copy text from a read-only buffer into the kill ring. |
873 | |
874 If @var{yank-handler} is non-@code{nil}, this puts that value onto | |
875 the string of killed text, as a @code{yank-handler} text property. | |
876 @xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, any | |
877 @code{yank-handler} properties present on the killed text are copied | |
878 onto the kill ring, like other text properties. | |
806 @end deffn | 879 @end deffn |
807 | 880 |
808 @defopt kill-read-only-ok | 881 @defopt kill-read-only-ok |
809 If this option is non-@code{nil}, @code{kill-region} does not signal an | 882 If this option is non-@code{nil}, @code{kill-region} does not signal an |
810 error if the buffer or text is read-only. Instead, it simply returns, | 883 error if the buffer or text is read-only. Instead, it simply returns, |
812 @end defopt | 885 @end defopt |
813 | 886 |
814 @deffn Command copy-region-as-kill start end | 887 @deffn Command copy-region-as-kill start end |
815 This command saves the region defined by @var{start} and @var{end} on | 888 This command saves the region defined by @var{start} and @var{end} on |
816 the kill ring (including text properties), but does not delete the text | 889 the kill ring (including text properties), but does not delete the text |
817 from the buffer. It returns @code{nil}. It also indicates the extent | 890 from the buffer. It returns @code{nil}. |
818 of the text copied by moving the cursor momentarily, or by displaying a | |
819 message in the echo area. | |
820 | 891 |
821 The command does not set @code{this-command} to @code{kill-region}, so a | 892 The command does not set @code{this-command} to @code{kill-region}, so a |
822 subsequent kill command does not append to the same kill ring entry. | 893 subsequent kill command does not append to the same kill ring entry. |
823 | 894 |
824 Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to | 895 Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to |
825 support Emacs 18. For newer Emacs versions, it is better to use | 896 support Emacs 18. For newer Emacs versions, it is better to use |
826 @code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill | 897 @code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill |
827 Ring}. | 898 Ring}. |
828 @end deffn | 899 @end deffn |
829 | 900 |
901 @node Yanking | |
902 @subsection Yanking | |
903 | |
904 Yanking means inserting text from the kill ring, but it does | |
905 not insert the text blindly. Yank commands and some other commands | |
906 use @code{insert-for-yank} to perform special processing on the | |
907 text that they copy into the buffer. | |
908 | |
909 @defun insert-for-yank string | |
910 This function normally works like @code{insert} except that it doesn't | |
911 insert the text properties in the @code{yank-excluded-properties} | |
912 list. However, if any part of @var{string} has a non-@code{nil} | |
913 @code{yank-handler} text property, that property can do various | |
914 special processing on that part of the text being inserted. | |
915 @end defun | |
916 | |
917 @defun insert-buffer-substring-as-yank buf &optional start end | |
918 This function resembles @code{insert-buffer-substring} except that it | |
919 doesn't insert the text properties in the | |
920 @code{yank-excluded-properties} list. | |
921 @end defun | |
922 | |
923 You can put a @code{yank-handler} text property on all or part of | |
924 the text to control how it will be inserted if it is yanked. The | |
925 @code{insert-for-yank} function looks for that property. The property | |
926 value must be a list of one to four elements, with the following | |
927 format (where elements after the first may be omitted): | |
928 | |
929 @example | |
930 (@var{function} @var{param} @var{noexclude} @var{undo}) | |
931 @end example | |
932 | |
933 Here is what the elements do: | |
934 | |
935 @table @var | |
936 @item function | |
937 When @var{function} is present and non-@code{nil}, it is called instead of | |
938 @code{insert} to insert the string. @var{function} takes one | |
939 argument---the string to insert. | |
940 | |
941 @item param | |
942 If @var{param} is present and non-@code{nil}, it replaces @var{string} | |
943 (or the part of @var{string} being processed) as the object passed to | |
944 @var{function} (or @code{insert}); for example, if @var{function} is | |
945 @code{yank-rectangle}, @var{param} should be a list of strings to | |
946 insert as a rectangle. | |
947 | |
948 @item noexclude | |
949 If @var{noexclude} is present and non-@code{nil}, the normal removal of the | |
950 yank-excluded-properties is not performed; instead @var{function} is | |
951 responsible for removing those properties. This may be necessary | |
952 if @var{function} adjusts point before or after inserting the object. | |
953 | |
954 @item undo | |
955 If @var{undo} is present and non-@code{nil}, it is a function that will be | |
956 called by @code{yank-pop} to undo the insertion of the current object. | |
957 It is called with two arguments, the start and end of the current | |
958 region. @var{function} can set @code{yank-undo-function} to override | |
959 the @var{undo} value. | |
960 @end table | |
961 | |
830 @node Yank Commands | 962 @node Yank Commands |
831 @comment node-name, next, previous, up | 963 @comment node-name, next, previous, up |
832 @subsection Functions for Yanking | 964 @subsection Functions for Yanking |
833 | 965 |
834 @dfn{Yanking} means reinserting an entry of previously killed text | 966 @dfn{Yanking} means reinserting an entry of previously killed text |
835 from the kill ring. The text properties are copied too. | 967 from the kill ring. The text properties are copied too. |
836 | 968 |
837 @deffn Command yank &optional arg | 969 @deffn Command yank &optional arg |
838 @cindex inserting killed text | 970 @cindex inserting killed text |
839 This command inserts before point the text in the first entry in the | 971 This command inserts before point the text at the front of the |
840 kill ring. It positions the mark at the beginning of that text, and | 972 kill ring. It positions the mark at the beginning of that text, and |
841 point at the end. | 973 point at the end. |
842 | 974 |
843 If @var{arg} is a list (which occurs interactively when the user | 975 If @var{arg} is a non-@code{nil} list (which occurs interactively when |
844 types @kbd{C-u} with no digits), then @code{yank} inserts the text as | 976 the user types @kbd{C-u} with no digits), then @code{yank} inserts the |
845 described above, but puts point before the yanked text and puts the mark | 977 text as described above, but puts point before the yanked text and |
846 after it. | 978 puts the mark after it. |
847 | 979 |
848 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most | 980 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th |
849 recently killed text---the @var{arg}th element of the kill ring list. | 981 most recently killed text---the @var{arg}th element of the kill ring |
850 | 982 list, counted cyclically from the front, which is considered the |
851 @code{yank} does not alter the contents of the kill ring or rotate it. | 983 first element for this purpose. |
852 It returns @code{nil}. | 984 |
853 @end deffn | 985 @code{yank} does not alter the contents of the kill ring, unless it |
854 | 986 used text provided by another program, in which case it pushes that text |
855 @deffn Command yank-pop arg | 987 onto the kill ring. However if @var{arg} is an integer different from |
988 one, it rotates the kill ring to place the yanked string at the front. | |
989 | |
990 @code{yank} returns @code{nil}. | |
991 @end deffn | |
992 | |
993 @deffn Command yank-pop &optional arg | |
856 This command replaces the just-yanked entry from the kill ring with a | 994 This command replaces the just-yanked entry from the kill ring with a |
857 different entry from the kill ring. | 995 different entry from the kill ring. |
858 | 996 |
859 This is allowed only immediately after a @code{yank} or another | 997 This is allowed only immediately after a @code{yank} or another |
860 @code{yank-pop}. At such a time, the region contains text that was just | 998 @code{yank-pop}. At such a time, the region contains text that was just |
861 inserted by yanking. @code{yank-pop} deletes that text and inserts in | 999 inserted by yanking. @code{yank-pop} deletes that text and inserts in |
862 its place a different piece of killed text. It does not add the deleted | 1000 its place a different piece of killed text. It does not add the deleted |
863 text to the kill ring, since it is already in the kill ring somewhere. | 1001 text to the kill ring, since it is already in the kill ring somewhere. |
1002 It does however rotate the kill ring to place the newly yanked string at | |
1003 the front. | |
864 | 1004 |
865 If @var{arg} is @code{nil}, then the replacement text is the previous | 1005 If @var{arg} is @code{nil}, then the replacement text is the previous |
866 element of the kill ring. If @var{arg} is numeric, the replacement is | 1006 element of the kill ring. If @var{arg} is numeric, the replacement is |
867 the @var{arg}th previous kill. If @var{arg} is negative, a more recent | 1007 the @var{arg}th previous kill. If @var{arg} is negative, a more recent |
868 kill is the replacement. | 1008 kill is the replacement. |
872 oldest. | 1012 oldest. |
873 | 1013 |
874 The return value is always @code{nil}. | 1014 The return value is always @code{nil}. |
875 @end deffn | 1015 @end deffn |
876 | 1016 |
1017 @defvar yank-undo-function | |
1018 If this variable is non-@code{nil}, the function @code{yank-pop} uses | |
1019 its value instead of @code{delete-region} to delete the text | |
1020 inserted by the previous @code{yank} or | |
1021 @code{yank-pop} command. The value must be a function of two | |
1022 arguments, the start and end of the current region. | |
1023 | |
1024 The function @code{insert-for-yank} automatically sets this variable | |
1025 according to the @var{undo} element of the @code{yank-handler} | |
1026 text property, if there is one. | |
1027 @end defvar | |
1028 | |
877 @node Low-Level Kill Ring | 1029 @node Low-Level Kill Ring |
878 @subsection Low-Level Kill Ring | 1030 @subsection Low-Level Kill Ring |
879 | 1031 |
880 These functions and variables provide access to the kill ring at a | 1032 These functions and variables provide access to the kill ring at a |
881 lower level, but still convenient for use in Lisp programs, because they | 1033 lower level, but still convenient for use in Lisp programs, because they |
891 then @code{current-kill} doesn't alter the yanking pointer; it just | 1043 then @code{current-kill} doesn't alter the yanking pointer; it just |
892 returns the @var{n}th kill, counting from the current yanking pointer. | 1044 returns the @var{n}th kill, counting from the current yanking pointer. |
893 | 1045 |
894 If @var{n} is zero, indicating a request for the latest kill, | 1046 If @var{n} is zero, indicating a request for the latest kill, |
895 @code{current-kill} calls the value of | 1047 @code{current-kill} calls the value of |
896 @code{interprogram-paste-function} (documented below) before consulting | 1048 @code{interprogram-paste-function} (documented below) before |
897 the kill ring. | 1049 consulting the kill ring. If that value is a function and calling it |
898 @end defun | 1050 returns a string, @code{current-kill} pushes that string onto the kill |
899 | 1051 ring and returns it. It also sets the yanking pointer to point to |
900 @defun kill-new string | 1052 that new entry, regardless of the value of @var{do-not-move}. |
901 This function puts the text @var{string} into the kill ring as a new | 1053 Otherwise, @code{current-kill} does not treat a zero value for @var{n} |
902 entry at the front of the ring. It discards the oldest entry if | 1054 specially: it returns the entry pointed at by the yanking pointer and |
903 appropriate. It also invokes the value of | 1055 does not move the yanking pointer. |
1056 @end defun | |
1057 | |
1058 @defun kill-new string &optional replace yank-handler | |
1059 This function pushes the text @var{string} onto the kill ring and | |
1060 makes the yanking pointer point to it. It discards the oldest entry | |
1061 if appropriate. It also invokes the value of | |
904 @code{interprogram-cut-function} (see below). | 1062 @code{interprogram-cut-function} (see below). |
905 @end defun | 1063 |
906 | 1064 If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the |
907 @defun kill-append string before-p | 1065 first element of the kill ring with @var{string}, rather than pushing |
1066 @var{string} onto the kill ring. | |
1067 | |
1068 If @var{yank-handler} is non-@code{nil}, this puts that value onto | |
1069 the string of killed text, as a @code{yank-handler} property. | |
1070 @xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, then | |
1071 @code{kill-new} copies any @code{yank-handler} properties present on | |
1072 @var{string} onto the kill ring, as it does with other text properties. | |
1073 @end defun | |
1074 | |
1075 @defun kill-append string before-p &optional yank-handler | |
908 This function appends the text @var{string} to the first entry in the | 1076 This function appends the text @var{string} to the first entry in the |
909 kill ring. Normally @var{string} goes at the end of the entry, but if | 1077 kill ring and makes the yanking pointer point to the combined entry. |
1078 Normally @var{string} goes at the end of the entry, but if | |
910 @var{before-p} is non-@code{nil}, it goes at the beginning. This | 1079 @var{before-p} is non-@code{nil}, it goes at the beginning. This |
911 function also invokes the value of @code{interprogram-cut-function} (see | 1080 function also invokes the value of @code{interprogram-cut-function} |
912 below). | 1081 (see below). This handles @var{yank-handler} just like |
1082 @code{kill-new}, except that if @var{yank-handler} is different from | |
1083 the @code{yank-handler} property of the first entry of the kill ring, | |
1084 @code{kill-append} pushes the concatenated string onto the kill ring, | |
1085 instead of replacing the original first entry with it. | |
913 @end defun | 1086 @end defun |
914 | 1087 |
915 @defvar interprogram-paste-function | 1088 @defvar interprogram-paste-function |
916 This variable provides a way of transferring killed text from other | 1089 This variable provides a way of transferring killed text from other |
917 programs, when you are using a window system. Its value should be | 1090 programs, when you are using a window system. Its value should be |
918 @code{nil} or a function of no arguments. | 1091 @code{nil} or a function of no arguments. |
919 | 1092 |
920 If the value is a function, @code{current-kill} calls it to get the | 1093 If the value is a function, @code{current-kill} calls it to get the |
921 ``most recent kill''. If the function returns a non-@code{nil} value, | 1094 ``most recent kill''. If the function returns a non-@code{nil} value, |
922 then that value is used as the ``most recent kill''. If it returns | 1095 then that value is used as the ``most recent kill''. If it returns |
923 @code{nil}, then the first element of @code{kill-ring} is used. | 1096 @code{nil}, then the front of the kill ring is used. |
924 | 1097 |
925 The normal use of this hook is to get the window system's primary | 1098 The normal use of this hook is to get the window system's primary |
926 selection as the most recent kill, even if the selection belongs to | 1099 selection as the most recent kill, even if the selection belongs to |
927 another application. @xref{Window System Selections}. | 1100 another application. @xref{Window System Selections}. |
928 @end defvar | 1101 @end defvar |
929 | 1102 |
930 @defvar interprogram-cut-function | 1103 @defvar interprogram-cut-function |
931 This variable provides a way of communicating killed text to other | 1104 This variable provides a way of communicating killed text to other |
932 programs, when you are using a window system. Its value should be | 1105 programs, when you are using a window system. Its value should be |
933 @code{nil} or a function of one argument. | 1106 @code{nil} or a function of one required and one optional argument. |
934 | 1107 |
935 If the value is a function, @code{kill-new} and @code{kill-append} call | 1108 If the value is a function, @code{kill-new} and @code{kill-append} call |
936 it with the new first element of the kill ring as an argument. | 1109 it with the new first element of the kill ring as the first argument. |
1110 The second, optional, argument has the same meaning as the @var{push} | |
1111 argument to @code{x-set-cut-buffer} (@pxref{Definition of | |
1112 x-set-cut-buffer}) and only affects the second and later cut buffers. | |
937 | 1113 |
938 The normal use of this hook is to set the window system's primary | 1114 The normal use of this hook is to set the window system's primary |
939 selection from the newly killed text. @xref{Window System Selections}. | 1115 selection (and first cut buffer) from the newly killed text. |
1116 @xref{Window System Selections}. | |
940 @end defvar | 1117 @end defvar |
941 | 1118 |
942 @node Internals of Kill Ring | 1119 @node Internals of Kill Ring |
943 @comment node-name, next, previous, up | 1120 @comment node-name, next, previous, up |
944 @subsection Internals of the Kill Ring | 1121 @subsection Internals of the Kill Ring |
1007 @end defvar | 1184 @end defvar |
1008 | 1185 |
1009 @defopt kill-ring-max | 1186 @defopt kill-ring-max |
1010 The value of this variable is the maximum length to which the kill | 1187 The value of this variable is the maximum length to which the kill |
1011 ring can grow, before elements are thrown away at the end. The default | 1188 ring can grow, before elements are thrown away at the end. The default |
1012 value for @code{kill-ring-max} is 30. | 1189 value for @code{kill-ring-max} is 60. |
1013 @end defopt | 1190 @end defopt |
1014 | 1191 |
1015 @node Undo | 1192 @node Undo |
1016 @comment node-name, next, previous, up | 1193 @comment node-name, next, previous, up |
1017 @section Undo | 1194 @section Undo |
1023 assumes that undoing is not useful.) All the primitives that modify the | 1200 assumes that undoing is not useful.) All the primitives that modify the |
1024 text in the buffer automatically add elements to the front of the undo | 1201 text in the buffer automatically add elements to the front of the undo |
1025 list, which is in the variable @code{buffer-undo-list}. | 1202 list, which is in the variable @code{buffer-undo-list}. |
1026 | 1203 |
1027 @defvar buffer-undo-list | 1204 @defvar buffer-undo-list |
1028 This variable's value is the undo list of the current buffer. | 1205 This buffer-local variable's value is the undo list of the current |
1029 A value of @code{t} disables the recording of undo information. | 1206 buffer. A value of @code{t} disables the recording of undo information. |
1030 @end defvar | 1207 @end defvar |
1031 | 1208 |
1032 Here are the kinds of elements an undo list can have: | 1209 Here are the kinds of elements an undo list can have: |
1033 | 1210 |
1034 @table @code | 1211 @table @code |
1044 buffer. | 1221 buffer. |
1045 | 1222 |
1046 @item (@var{text} . @var{position}) | 1223 @item (@var{text} . @var{position}) |
1047 This kind of element indicates how to reinsert text that was deleted. | 1224 This kind of element indicates how to reinsert text that was deleted. |
1048 The deleted text itself is the string @var{text}. The place to | 1225 The deleted text itself is the string @var{text}. The place to |
1049 reinsert it is @code{(abs @var{position})}. | 1226 reinsert it is @code{(abs @var{position})}. If @var{position} is |
1227 positive, point was at the beginning of the deleted text, otherwise it | |
1228 was at the end. | |
1050 | 1229 |
1051 @item (t @var{high} . @var{low}) | 1230 @item (t @var{high} . @var{low}) |
1052 This kind of element indicates that an unmodified buffer became | 1231 This kind of element indicates that an unmodified buffer became |
1053 modified. The elements @var{high} and @var{low} are two integers, each | 1232 modified. The elements @var{high} and @var{low} are two integers, each |
1054 recording 16 bits of the visited file's modification time as of when it | 1233 recording 16 bits of the visited file's modification time as of when it |
1068 This kind of element records the fact that the marker @var{marker} was | 1247 This kind of element records the fact that the marker @var{marker} was |
1069 relocated due to deletion of surrounding text, and that it moved | 1248 relocated due to deletion of surrounding text, and that it moved |
1070 @var{adjustment} character positions. Undoing this element moves | 1249 @var{adjustment} character positions. Undoing this element moves |
1071 @var{marker} @minus{} @var{adjustment} characters. | 1250 @var{marker} @minus{} @var{adjustment} characters. |
1072 | 1251 |
1252 @item (apply @var{funname} . @var{args}) | |
1253 This is an extensible undo item, which is undone by calling | |
1254 @var{funname} with arguments @var{args}. | |
1255 | |
1256 @item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args}) | |
1257 This is an extensible undo item, which records a change limited to the | |
1258 range @var{beg} to @var{end}, which increased the size of the buffer | |
1259 by @var{delta}. It is undone by calling @var{funname} with arguments | |
1260 @var{args}. | |
1261 | |
1262 This kind of element enables undo limited to a region to determine | |
1263 whether the element pertains to that region. | |
1264 | |
1073 @item nil | 1265 @item nil |
1074 This element is a boundary. The elements between two boundaries are | 1266 This element is a boundary. The elements between two boundaries are |
1075 called a @dfn{change group}; normally, each change group corresponds to | 1267 called a @dfn{change group}; normally, each change group corresponds to |
1076 one keyboard command, and undo commands normally undo an entire group as | 1268 one keyboard command, and undo commands normally undo an entire group as |
1077 a unit. | 1269 a unit. |
1098 a command into more than one unit. For example, @code{query-replace} | 1290 a command into more than one unit. For example, @code{query-replace} |
1099 calls @code{undo-boundary} after each replacement, so that the user can | 1291 calls @code{undo-boundary} after each replacement, so that the user can |
1100 undo individual replacements one by one. | 1292 undo individual replacements one by one. |
1101 @end defun | 1293 @end defun |
1102 | 1294 |
1295 @defvar undo-in-progress | |
1296 This variable is normally @code{nil}, but the undo commands bind it to | |
1297 @code{t}. This is so that various kinds of change hooks can tell when | |
1298 they're being called for the sake of undoing. | |
1299 @end defvar | |
1300 | |
1103 @defun primitive-undo count list | 1301 @defun primitive-undo count list |
1104 This is the basic function for undoing elements of an undo list. | 1302 This is the basic function for undoing elements of an undo list. |
1105 It undoes the first @var{count} elements of @var{list}, returning | 1303 It undoes the first @var{count} elements of @var{list}, returning |
1106 the rest of @var{list}. You could write this function in Lisp, | 1304 the rest of @var{list}. You could write this function in Lisp, |
1107 but it is convenient to have it in C. | 1305 but it is convenient to have it in C. |
1110 changes the buffer. Undo commands avoid confusion by saving the undo | 1308 changes the buffer. Undo commands avoid confusion by saving the undo |
1111 list value at the beginning of a sequence of undo operations. Then the | 1309 list value at the beginning of a sequence of undo operations. Then the |
1112 undo operations use and update the saved value. The new elements added | 1310 undo operations use and update the saved value. The new elements added |
1113 by undoing are not part of this saved value, so they don't interfere with | 1311 by undoing are not part of this saved value, so they don't interfere with |
1114 continuing to undo. | 1312 continuing to undo. |
1313 | |
1314 This function does not bind @code{undo-in-progress}. | |
1115 @end defun | 1315 @end defun |
1116 | 1316 |
1117 @node Maintaining Undo | 1317 @node Maintaining Undo |
1118 @section Maintaining Undo Lists | 1318 @section Maintaining Undo Lists |
1119 | 1319 |
1136 | 1336 |
1137 In an interactive call, @var{buffer-or-name} is the current buffer. | 1337 In an interactive call, @var{buffer-or-name} is the current buffer. |
1138 You cannot specify any other buffer. | 1338 You cannot specify any other buffer. |
1139 @end deffn | 1339 @end deffn |
1140 | 1340 |
1141 @deffn Command buffer-disable-undo &optional buffer | 1341 @deffn Command buffer-disable-undo &optional buffer-or-name |
1142 @deffnx Command buffer-flush-undo &optional buffer | |
1143 @cindex disable undo | 1342 @cindex disable undo |
1144 This function discards the undo list of @var{buffer}, and disables | 1343 This function discards the undo list of @var{buffer-or-name}, and disables |
1145 further recording of undo information. As a result, it is no longer | 1344 further recording of undo information. As a result, it is no longer |
1146 possible to undo either previous changes or any subsequent changes. If | 1345 possible to undo either previous changes or any subsequent changes. If |
1147 the undo list of @var{buffer} is already disabled, this function | 1346 the undo list of @var{buffer-or-name} is already disabled, this function |
1148 has no effect. | 1347 has no effect. |
1149 | 1348 |
1150 This function returns @code{nil}. | 1349 This function returns @code{nil}. |
1151 | |
1152 The name @code{buffer-flush-undo} is not considered obsolete, but the | |
1153 preferred name is @code{buffer-disable-undo}. | |
1154 @end deffn | 1350 @end deffn |
1155 | 1351 |
1156 As editing continues, undo lists get longer and longer. To prevent | 1352 As editing continues, undo lists get longer and longer. To prevent |
1157 them from using up all available memory space, garbage collection trims | 1353 them from using up all available memory space, garbage collection trims |
1158 them back to size limits you can set. (For this purpose, the ``size'' | 1354 them back to size limits you can set. (For this purpose, the ``size'' |
1159 of an undo list measures the cons cells that make up the list, plus the | 1355 of an undo list measures the cons cells that make up the list, plus the |
1160 strings of deleted text.) Two variables control the range of acceptable | 1356 strings of deleted text.) Three variables control the range of acceptable |
1161 sizes: @code{undo-limit} and @code{undo-strong-limit}. | 1357 sizes: @code{undo-limit}, @code{undo-strong-limit} and |
1162 | 1358 @code{undo-outer-limit}. |
1163 @defvar undo-limit | 1359 |
1360 @defopt undo-limit | |
1164 This is the soft limit for the acceptable size of an undo list. The | 1361 This is the soft limit for the acceptable size of an undo list. The |
1165 change group at which this size is exceeded is the last one kept. | 1362 change group at which this size is exceeded is the last one kept. |
1166 @end defvar | 1363 @end defopt |
1167 | 1364 |
1168 @defvar undo-strong-limit | 1365 @defopt undo-strong-limit |
1169 This is the upper limit for the acceptable size of an undo list. The | 1366 This is the upper limit for the acceptable size of an undo list. The |
1170 change group at which this size is exceeded is discarded itself (along | 1367 change group at which this size is exceeded is discarded itself (along |
1171 with all older change groups). There is one exception: the very latest | 1368 with all older change groups). There is one exception: the very latest |
1172 change group is never discarded no matter how big it is. | 1369 change group is only discarded if it exceeds @code{undo-outer-limit}. |
1173 @end defvar | 1370 @end defopt |
1371 | |
1372 @defopt undo-outer-limit | |
1373 If at garbage collection time the undo info for the current command | |
1374 exceeds this limit, Emacs discards the info and displays a warning. | |
1375 This is a last ditch limit to prevent memory overflow. | |
1376 @end defopt | |
1174 | 1377 |
1175 @node Filling | 1378 @node Filling |
1176 @comment node-name, next, previous, up | 1379 @comment node-name, next, previous, up |
1177 @section Filling | 1380 @section Filling |
1178 @cindex filling, explicit | 1381 @cindex filling, explicit |
1281 of justification. It can be @code{left}, @code{right}, @code{full}, | 1484 of justification. It can be @code{left}, @code{right}, @code{full}, |
1282 @code{center}, or @code{none}. If it is @code{t}, that means to do | 1485 @code{center}, or @code{none}. If it is @code{t}, that means to do |
1283 follow specified justification style (see @code{current-justification}, | 1486 follow specified justification style (see @code{current-justification}, |
1284 below). @code{nil} means to do full justification. | 1487 below). @code{nil} means to do full justification. |
1285 | 1488 |
1286 If @var{eop} is non-@code{nil}, that means do left-justification if | 1489 If @var{eop} is non-@code{nil}, that means do only left-justification |
1287 @code{current-justification} specifies full justification. This is used | 1490 if @code{current-justification} specifies full justification. This is |
1288 for the last line of a paragraph; even if the paragraph as a whole is | 1491 used for the last line of a paragraph; even if the paragraph as a |
1289 fully justified, the last line should not be. | 1492 whole is fully justified, the last line should not be. |
1290 | 1493 |
1291 If @var{nosqueeze} is non-@code{nil}, that means do not change interior | 1494 If @var{nosqueeze} is non-@code{nil}, that means do not change interior |
1292 whitespace. | 1495 whitespace. |
1293 @end deffn | 1496 @end deffn |
1294 | 1497 |
1303 This function returns the proper justification style to use for filling | 1506 This function returns the proper justification style to use for filling |
1304 the text around point. | 1507 the text around point. |
1305 @end defun | 1508 @end defun |
1306 | 1509 |
1307 @defopt sentence-end-double-space | 1510 @defopt sentence-end-double-space |
1511 @anchor{Definition of sentence-end-double-space} | |
1308 If this variable is non-@code{nil}, a period followed by just one space | 1512 If this variable is non-@code{nil}, a period followed by just one space |
1309 does not count as the end of a sentence, and the filling functions | 1513 does not count as the end of a sentence, and the filling functions |
1310 avoid breaking the line at such a place. | 1514 avoid breaking the line at such a place. |
1515 @end defopt | |
1516 | |
1517 @defopt sentence-end-without-period | |
1518 If this variable is non-@code{nil}, a sentence can end without a | |
1519 period. This is used for languages like Thai, where sentences end | |
1520 with a double space but without a period. | |
1521 @end defopt | |
1522 | |
1523 @defopt sentence-end-without-space | |
1524 If this variable is non-@code{nil}, it should be a string of | |
1525 characters that can end a sentence without following spaces. | |
1311 @end defopt | 1526 @end defopt |
1312 | 1527 |
1313 @defvar fill-paragraph-function | 1528 @defvar fill-paragraph-function |
1314 This variable provides a way for major modes to override the filling of | 1529 This variable provides a way for major modes to override the filling of |
1315 paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls | 1530 paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls |
1426 mode, @kbd{C-j} indents to this column. This variable automatically | 1641 mode, @kbd{C-j} indents to this column. This variable automatically |
1427 becomes buffer-local when set in any fashion. | 1642 becomes buffer-local when set in any fashion. |
1428 @end defvar | 1643 @end defvar |
1429 | 1644 |
1430 @defvar fill-nobreak-predicate | 1645 @defvar fill-nobreak-predicate |
1431 This variable gives major modes a way to specify not to break a line at | 1646 This variable gives major modes a way to specify not to break a line |
1432 certain places. Its value should be a function. This function is | 1647 at certain places. Its value should be a list of functions, but a |
1433 called during filling, with no arguments and with point located at the | 1648 single function is also supported for compatibility. Whenever filling |
1434 place where a break is being considered. If the function returns | 1649 considers breaking the line at a certain place in the buffer, it calls |
1435 non-@code{nil}, then the line won't be broken there. | 1650 each of these functions with no arguments and with point located at |
1651 that place. If any of the functions returns non-@code{nil}, then the | |
1652 line won't be broken there. | |
1436 @end defvar | 1653 @end defvar |
1437 | 1654 |
1438 @node Adaptive Fill | 1655 @node Adaptive Fill |
1439 @section Adaptive Fill Mode | 1656 @section Adaptive Fill Mode |
1440 @cindex Adaptive Fill mode | 1657 @cindex Adaptive Fill mode |
1441 | 1658 |
1442 Adaptive Fill mode chooses a fill prefix automatically from the text | 1659 When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill |
1443 in each paragraph being filled. | 1660 prefix automatically from the text in each paragraph being filled |
1661 rather than using a predetermined value. During filling, this fill | |
1662 prefix gets inserted at the start of the second and subsequent lines | |
1663 of the paragraph as described in @ref{Filling}, and in @ref{Auto | |
1664 Filling}. | |
1444 | 1665 |
1445 @defopt adaptive-fill-mode | 1666 @defopt adaptive-fill-mode |
1446 Adaptive Fill mode is enabled when this variable is non-@code{nil}. | 1667 Adaptive Fill mode is enabled when this variable is non-@code{nil}. |
1447 It is @code{t} by default. | 1668 It is @code{t} by default. |
1448 @end defopt | 1669 @end defopt |
1449 | 1670 |
1450 @defun fill-context-prefix from to | 1671 @defun fill-context-prefix from to |
1451 This function implements the heart of Adaptive Fill mode; it chooses a | 1672 This function implements the heart of Adaptive Fill mode; it chooses a |
1452 fill prefix based on the text between @var{from} and @var{to}. It does | 1673 fill prefix based on the text between @var{from} and @var{to}, |
1453 this by looking at the first two lines of the paragraph, based on the | 1674 typically the start and end of a paragraph. It does this by looking |
1454 variables described below. | 1675 at the first two lines of the paragraph, based on the variables |
1676 described below. | |
1455 @c The optional argument first-line-regexp is not documented | 1677 @c The optional argument first-line-regexp is not documented |
1456 @c because it exists for internal purposes and might be eliminated | 1678 @c because it exists for internal purposes and might be eliminated |
1457 @c in the future. | 1679 @c in the future. |
1680 | |
1681 Usually, this function returns the fill prefix, a string. However, | |
1682 before doing this, the function makes a final check (not specially | |
1683 mentioned in the following) that a line starting with this prefix | |
1684 wouldn't look like the start of a paragraph. Should this happen, the | |
1685 function signals the anomaly by returning @code{nil} instead. | |
1686 | |
1687 In detail, @code{fill-context-prefix} does this: | |
1688 | |
1689 @enumerate | |
1690 @item | |
1691 It takes a candidate for the fill prefix from the first line---it | |
1692 tries first the function in @code{adaptive-fill-function} (if any), | |
1693 then the regular expression @code{adaptive-fill-regexp} (see below). | |
1694 The first non-@code{nil} result of these, or the empty string if | |
1695 they're both @code{nil}, becomes the first line's candidate. | |
1696 @item | |
1697 If the paragraph has as yet only one line, the function tests the | |
1698 validity of the prefix candidate just found. The function then | |
1699 returns the candidate if it's valid, or a string of spaces otherwise. | |
1700 (see the description of @code{adaptive-fill-first-line-regexp} below). | |
1701 @item | |
1702 When the paragraph already has two lines, the function next looks for | |
1703 a prefix candidate on the second line, in just the same way it did for | |
1704 the first line. If it doesn't find one, it returns @code{nil}. | |
1705 @item | |
1706 The function now compares the two candidate prefixes heuristically: if | |
1707 the non-whitespace characters in the line 2 candidate occur in the | |
1708 same order in the line 1 candidate, the function returns the line 2 | |
1709 candidate. Otherwise, it returns the largest initial substring which | |
1710 is common to both candidates (which might be the empty string). | |
1711 @end enumerate | |
1458 @end defun | 1712 @end defun |
1459 | 1713 |
1460 @defopt adaptive-fill-regexp | 1714 @defopt adaptive-fill-regexp |
1461 This variable holds a regular expression to control Adaptive Fill mode. | |
1462 Adaptive Fill mode matches this regular expression against the text | 1715 Adaptive Fill mode matches this regular expression against the text |
1463 starting after the left margin whitespace (if any) on a line; the | 1716 starting after the left margin whitespace (if any) on a line; the |
1464 characters it matches are that line's candidate for the fill prefix. | 1717 characters it matches are that line's candidate for the fill prefix. |
1718 | |
1719 @w{@samp{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}} is the | |
1720 default value. This matches a number enclosed in parentheses or | |
1721 followed by a period, or certain punctuation characters, or any | |
1722 sequence of these intermingled with whitespace. In particular, it | |
1723 matches a sequence of whitespace, possibly empty. | |
1465 @end defopt | 1724 @end defopt |
1466 | 1725 |
1467 @defopt adaptive-fill-first-line-regexp | 1726 @defopt adaptive-fill-first-line-regexp |
1468 In a one-line paragraph, if the candidate fill prefix matches this | 1727 Used only in one-line paragraphs, this regular expression acts as an |
1469 regular expression, or if it matches @code{comment-start-skip}, then it | 1728 additional check of the validity of the one available candidate fill |
1470 is used---otherwise, spaces amounting to the same width are used | 1729 prefix: the candidate must match this regular expression, or match |
1471 instead. | 1730 @code{comment-start-skip}. If it doesn't, @code{fill-context-prefix} |
1472 | 1731 replaces the candidate with a string of spaces ``of the same width'' |
1473 However, the fill prefix is never taken from a one-line paragraph | 1732 as it. |
1474 if it would act as a paragraph starter on subsequent lines. | 1733 |
1734 The default value of this variable is @w{@samp{"\\`[ \t]*\\'"}}, which | |
1735 matches only a string of whitespace. The effect of this default is to | |
1736 force the fill prefixes found in one-line paragraphs always to be pure | |
1737 whitespace. | |
1475 @end defopt | 1738 @end defopt |
1476 | 1739 |
1477 @defopt adaptive-fill-function | 1740 @defopt adaptive-fill-function |
1478 You can specify more complex ways of choosing a fill prefix | 1741 You can specify more complex ways of choosing a fill prefix |
1479 automatically by setting this variable to a function. The function is | 1742 automatically by setting this variable to a function. The function is |
1480 called when @code{adaptive-fill-regexp} does not match, with point after | 1743 called with point after the left margin (if any) of a line, and it |
1481 the left margin of a line, and it should return the appropriate fill | 1744 must preserve point. It should return either ``that line's'' fill |
1482 prefix based on that line. If it returns @code{nil}, that means it sees | 1745 prefix or @code{nil}, meaning it has failed to determine a prefix. |
1483 no fill prefix in that line. | |
1484 @end defopt | 1746 @end defopt |
1485 | 1747 |
1486 @node Auto Filling | 1748 @node Auto Filling |
1487 @comment node-name, next, previous, up | 1749 @comment node-name, next, previous, up |
1488 @section Auto Filling | 1750 @section Auto Filling |
1496 | 1758 |
1497 Auto Fill mode also enables the functions that change the margins and | 1759 Auto Fill mode also enables the functions that change the margins and |
1498 justification style to refill portions of the text. @xref{Margins}. | 1760 justification style to refill portions of the text. @xref{Margins}. |
1499 | 1761 |
1500 @defvar auto-fill-function | 1762 @defvar auto-fill-function |
1501 The value of this variable should be a function (of no arguments) to be | 1763 The value of this buffer-local variable should be a function (of no |
1502 called after self-inserting a character from the table | 1764 arguments) to be called after self-inserting a character from the table |
1503 @code{auto-fill-chars}. It may be @code{nil}, in which case nothing | 1765 @code{auto-fill-chars}. It may be @code{nil}, in which case nothing |
1504 special is done in that case. | 1766 special is done in that case. |
1505 | 1767 |
1506 The value of @code{auto-fill-function} is @code{do-auto-fill} when | 1768 The value of @code{auto-fill-function} is @code{do-auto-fill} when |
1507 Auto-Fill mode is enabled. That is a function whose sole purpose is to | 1769 Auto-Fill mode is enabled. That is a function whose sole purpose is to |
1534 The sorting functions described in this section all rearrange text in | 1796 The sorting functions described in this section all rearrange text in |
1535 a buffer. This is in contrast to the function @code{sort}, which | 1797 a buffer. This is in contrast to the function @code{sort}, which |
1536 rearranges the order of the elements of a list (@pxref{Rearrangement}). | 1798 rearranges the order of the elements of a list (@pxref{Rearrangement}). |
1537 The values returned by these functions are not meaningful. | 1799 The values returned by these functions are not meaningful. |
1538 | 1800 |
1539 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun | 1801 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate |
1540 This function is the general text-sorting routine that subdivides a | 1802 This function is the general text-sorting routine that subdivides a |
1541 buffer into records and then sorts them. Most of the commands in this | 1803 buffer into records and then sorts them. Most of the commands in this |
1542 section use this function. | 1804 section use this function. |
1543 | 1805 |
1544 To understand how @code{sort-subr} works, consider the whole accessible | 1806 To understand how @code{sort-subr} works, consider the whole accessible |
1587 @var{startkeyfun} returns @code{nil} and this argument is omitted (or | 1849 @var{startkeyfun} returns @code{nil} and this argument is omitted (or |
1588 @code{nil}), then the sort key extends to the end of the record. There | 1850 @code{nil}), then the sort key extends to the end of the record. There |
1589 is no need for @var{endkeyfun} if @var{startkeyfun} returns a | 1851 is no need for @var{endkeyfun} if @var{startkeyfun} returns a |
1590 non-@code{nil} value. | 1852 non-@code{nil} value. |
1591 @end enumerate | 1853 @end enumerate |
1854 | |
1855 The argument @var{predicate} is the function to use to compare keys. | |
1856 If keys are numbers, it defaults to @code{<}; otherwise it defaults to | |
1857 @code{string<}. | |
1592 | 1858 |
1593 As an example of @code{sort-subr}, here is the complete function | 1859 As an example of @code{sort-subr}, here is the complete function |
1594 definition for @code{sort-lines}: | 1860 definition for @code{sort-lines}: |
1595 | 1861 |
1596 @example | 1862 @example |
1605 @group | 1871 @group |
1606 REVERSE (non-nil means reverse order),\ | 1872 REVERSE (non-nil means reverse order),\ |
1607 BEG and END (region to sort). | 1873 BEG and END (region to sort). |
1608 The variable `sort-fold-case' determines\ | 1874 The variable `sort-fold-case' determines\ |
1609 whether alphabetic case affects | 1875 whether alphabetic case affects |
1610 the sort order. | 1876 the sort order." |
1611 @end group | 1877 @end group |
1612 @group | 1878 @group |
1613 (interactive "P\nr") | 1879 (interactive "P\nr") |
1614 (save-excursion | 1880 (save-excursion |
1615 (save-restriction | 1881 (save-restriction |
1741 is useful for sorting tables. | 2007 is useful for sorting tables. |
1742 @end deffn | 2008 @end deffn |
1743 | 2009 |
1744 @deffn Command sort-numeric-fields field start end | 2010 @deffn Command sort-numeric-fields field start end |
1745 This command sorts lines in the region between @var{start} and | 2011 This command sorts lines in the region between @var{start} and |
1746 @var{end}, comparing them numerically by the @var{field}th field of each | 2012 @var{end}, comparing them numerically by the @var{field}th field of |
1747 line. The specified field must contain a number in each line of the | 2013 each line. Fields are separated by whitespace and numbered starting |
1748 region. Fields are separated by whitespace and numbered starting from | 2014 from 1. The specified field must contain a number in each line of the |
1749 1. If @var{field} is negative, sorting is by the | 2015 region. Numbers starting with 0 are treated as octal, and numbers |
1750 @w{@minus{}@var{field}th} field from the end of the line. This command | 2016 starting with @samp{0x} are treated as hexadecimal. |
1751 is useful for sorting tables. | 2017 |
1752 @end deffn | 2018 If @var{field} is negative, sorting is by the |
2019 @w{@minus{}@var{field}th} field from the end of the line. This | |
2020 command is useful for sorting tables. | |
2021 @end deffn | |
2022 | |
2023 @defopt sort-numeric-base | |
2024 This variable specifies the default radix for | |
2025 @code{sort-numeric-fields} to parse numbers. | |
2026 @end defopt | |
1753 | 2027 |
1754 @deffn Command sort-columns reverse &optional beg end | 2028 @deffn Command sort-columns reverse &optional beg end |
1755 This command sorts the lines in the region between @var{beg} and | 2029 This command sorts the lines in the region between @var{beg} and |
1756 @var{end}, comparing them alphabetically by a certain range of columns. | 2030 @var{end}, comparing them alphabetically by a certain range of |
1757 The column positions of @var{beg} and @var{end} bound the range of | 2031 columns. The column positions of @var{beg} and @var{end} bound the |
1758 columns to sort on. | 2032 range of columns to sort on. |
1759 | 2033 |
1760 If @var{reverse} is non-@code{nil}, the sort is in reverse order. | 2034 If @var{reverse} is non-@code{nil}, the sort is in reverse order. |
1761 | 2035 |
1762 One unusual thing about this command is that the entire line | 2036 One unusual thing about this command is that the entire line |
1763 containing position @var{beg}, and the entire line containing position | 2037 containing position @var{beg}, and the entire line containing position |
1786 depends on the value of @code{tab-width} and on the column where the tab | 2060 depends on the value of @code{tab-width} and on the column where the tab |
1787 begins. @xref{Usual Display}. | 2061 begins. @xref{Usual Display}. |
1788 | 2062 |
1789 Column number computations ignore the width of the window and the | 2063 Column number computations ignore the width of the window and the |
1790 amount of horizontal scrolling. Consequently, a column value can be | 2064 amount of horizontal scrolling. Consequently, a column value can be |
1791 arbitrarily high. The first (or leftmost) column is numbered 0. | 2065 arbitrarily high. The first (or leftmost) column is numbered 0. They |
2066 also ignore overlays and text properties, aside from invisibility. | |
1792 | 2067 |
1793 @defun current-column | 2068 @defun current-column |
1794 This function returns the horizontal position of point, measured in | 2069 This function returns the horizontal position of point, measured in |
1795 columns, counting from 0 at the left margin. The column position is the | 2070 columns, counting from 0 at the left margin. The column position is the |
1796 sum of the widths of all the displayed representations of the characters | 2071 sum of the widths of all the displayed representations of the characters |
2128 This command moves point to the first non-whitespace character in the | 2403 This command moves point to the first non-whitespace character in the |
2129 current line (which is the line in which point is located). It returns | 2404 current line (which is the line in which point is located). It returns |
2130 @code{nil}. | 2405 @code{nil}. |
2131 @end deffn | 2406 @end deffn |
2132 | 2407 |
2133 @deffn Command backward-to-indentation arg | 2408 @deffn Command backward-to-indentation &optional arg |
2134 @comment !!SourceFile simple.el | 2409 @comment !!SourceFile simple.el |
2135 This command moves point backward @var{arg} lines and then to the | 2410 This command moves point backward @var{arg} lines and then to the |
2136 first nonblank character on that line. It returns @code{nil}. | 2411 first nonblank character on that line. It returns @code{nil}. |
2137 @end deffn | 2412 If @var{arg} is omitted or @code{nil}, it defaults to 1. |
2138 | 2413 @end deffn |
2139 @deffn Command forward-to-indentation arg | 2414 |
2415 @deffn Command forward-to-indentation &optional arg | |
2140 @comment !!SourceFile simple.el | 2416 @comment !!SourceFile simple.el |
2141 This command moves point forward @var{arg} lines and then to the first | 2417 This command moves point forward @var{arg} lines and then to the first |
2142 nonblank character on that line. It returns @code{nil}. | 2418 nonblank character on that line. It returns @code{nil}. |
2419 If @var{arg} is omitted or @code{nil}, it defaults to 1. | |
2143 @end deffn | 2420 @end deffn |
2144 | 2421 |
2145 @node Case Changes | 2422 @node Case Changes |
2146 @comment node-name, next, previous, up | 2423 @comment node-name, next, previous, up |
2147 @section Case Changes | 2424 @section Case Changes |
2273 them back. | 2550 them back. |
2274 * Lazy Properties:: Computing text properties in a lazy fashion | 2551 * Lazy Properties:: Computing text properties in a lazy fashion |
2275 only when text is examined. | 2552 only when text is examined. |
2276 * Clickable Text:: Using text properties to make regions of text | 2553 * Clickable Text:: Using text properties to make regions of text |
2277 do something when you click on them. | 2554 do something when you click on them. |
2555 * Links and Mouse-1:: How to make @key{Mouse-1} follow a link. | |
2278 * Fields:: The @code{field} property defines | 2556 * Fields:: The @code{field} property defines |
2279 fields within the buffer. | 2557 fields within the buffer. |
2280 * Not Intervals:: Why text properties do not use | 2558 * Not Intervals:: Why text properties do not use |
2281 Lisp-visible text intervals. | 2559 Lisp-visible text intervals. |
2282 @end menu | 2560 @end menu |
2303 If there is no @var{prop} property strictly speaking, but the character | 2581 If there is no @var{prop} property strictly speaking, but the character |
2304 has a category that is a symbol, then @code{get-text-property} returns | 2582 has a category that is a symbol, then @code{get-text-property} returns |
2305 the @var{prop} property of that symbol. | 2583 the @var{prop} property of that symbol. |
2306 @end defun | 2584 @end defun |
2307 | 2585 |
2308 @defun get-char-property pos prop &optional object | 2586 @defun get-char-property position prop &optional object |
2309 This function is like @code{get-text-property}, except that it checks | 2587 This function is like @code{get-text-property}, except that it checks |
2310 overlays first and then text properties. @xref{Overlays}. | 2588 overlays first and then text properties. @xref{Overlays}. |
2311 | 2589 |
2312 The argument @var{object} may be a string, a buffer, or a window. If it | 2590 The argument @var{object} may be a string, a buffer, or a window. If it |
2313 is a window, then the buffer displayed in that window is used for text | 2591 is a window, then the buffer displayed in that window is used for text |
2316 buffer are considered, as well as text properties. If @var{object} is a | 2594 buffer are considered, as well as text properties. If @var{object} is a |
2317 string, only text properties are considered, since strings never have | 2595 string, only text properties are considered, since strings never have |
2318 overlays. | 2596 overlays. |
2319 @end defun | 2597 @end defun |
2320 | 2598 |
2599 @defun get-char-property-and-overlay position prop &optional object | |
2600 This is like @code{get-char-property}, but gives extra information | |
2601 about the overlay that the property value comes from. | |
2602 | |
2603 Its value is a cons cell whose @sc{car} is the property value, the | |
2604 same value @code{get-char-property} would return with the same | |
2605 arguments. Its @sc{cdr} is the overlay in which the property was | |
2606 found, or @code{nil}, if it was found as a text property or not found | |
2607 at all. | |
2608 | |
2609 If @var{position} is at the end of @var{object}, both the @sc{car} and | |
2610 the @sc{cdr} of the value are @code{nil}. | |
2611 @end defun | |
2612 | |
2321 @defvar char-property-alias-alist | 2613 @defvar char-property-alias-alist |
2322 This variable holds an alist which maps property names to a list of | 2614 This variable holds an alist which maps property names to a list of |
2323 alternative property names. If a character does not specify a direct | 2615 alternative property names. If a character does not specify a direct |
2324 value for a property, the alternative property names are consulted in | 2616 value for a property, the alternative property names are consulted in |
2325 order; the first non-nil value is used. This variable takes | 2617 order; the first non-@code{nil} value is used. This variable takes |
2326 precedence over @code{default-text-properties}, and @code{category} | 2618 precedence over @code{default-text-properties}, and @code{category} |
2327 properties take precedence over this variable. | 2619 properties take precedence over this variable. |
2328 @end defvar | 2620 @end defvar |
2329 | 2621 |
2330 @defun text-properties-at position &optional object | 2622 @defun text-properties-at position &optional object |
2418 To remove all text properties from certain text, use | 2710 To remove all text properties from certain text, use |
2419 @code{set-text-properties} and specify @code{nil} for the new property | 2711 @code{set-text-properties} and specify @code{nil} for the new property |
2420 list. | 2712 list. |
2421 @end defun | 2713 @end defun |
2422 | 2714 |
2715 @defun remove-list-of-text-properties start end list-of-properties &optional object | |
2716 Like @code{remove-text-properties} except that | |
2717 @var{list-of-properties} is a list of property names only, not an | |
2718 alternating list of property names and values. | |
2719 @end defun | |
2720 | |
2423 @defun set-text-properties start end props &optional object | 2721 @defun set-text-properties start end props &optional object |
2424 This function completely replaces the text property list for the text | 2722 This function completely replaces the text property list for the text |
2425 between @var{start} and @var{end} in the string or buffer @var{object}. | 2723 between @var{start} and @var{end} in the string or buffer @var{object}. |
2426 If @var{object} is @code{nil}, it defaults to the current buffer. | 2724 If @var{object} is @code{nil}, it defaults to the current buffer. |
2427 | 2725 |
2435 from the specified range of text. Here's an example: | 2733 from the specified range of text. Here's an example: |
2436 | 2734 |
2437 @example | 2735 @example |
2438 (set-text-properties @var{start} @var{end} nil) | 2736 (set-text-properties @var{start} @var{end} nil) |
2439 @end example | 2737 @end example |
2738 | |
2739 Do not rely on the return value of this function. | |
2440 @end defun | 2740 @end defun |
2441 | 2741 |
2442 The easiest way to make a string with text properties | 2742 The easiest way to make a string with text properties |
2443 is with @code{propertize}: | 2743 is with @code{propertize}: |
2444 | 2744 |
2648 @itemize @bullet | 2948 @itemize @bullet |
2649 @item | 2949 @item |
2650 A face name (a symbol or string). | 2950 A face name (a symbol or string). |
2651 | 2951 |
2652 @item | 2952 @item |
2653 Starting in Emacs 21, a property list of face attributes. This has the | 2953 A property list of face attributes. This has the |
2654 form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a | 2954 form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a |
2655 face attribute name and @var{value} is a meaningful value for that | 2955 face attribute name and @var{value} is a meaningful value for that |
2656 attribute. With this feature, you do not need to create a face each | 2956 attribute. With this feature, you do not need to create a face each |
2657 time you want to specify a particular attribute for certain text. | 2957 time you want to specify a particular attribute for certain text. |
2658 @xref{Face Attributes}. | 2958 @xref{Face Attributes}. |
2661 A cons cell of the form @code{(foreground-color . @var{color-name})} or | 2961 A cons cell of the form @code{(foreground-color . @var{color-name})} or |
2662 @code{(background-color . @var{color-name})}. These elements specify | 2962 @code{(background-color . @var{color-name})}. These elements specify |
2663 just the foreground color or just the background color. | 2963 just the foreground color or just the background color. |
2664 | 2964 |
2665 @code{(foreground-color . @var{color-name})} is equivalent to | 2965 @code{(foreground-color . @var{color-name})} is equivalent to |
2666 @code{(:foreground @var{color-name})}, and likewise for the background. | 2966 specifying @code{(:foreground @var{color-name})}, and likewise for the |
2967 background. | |
2667 @end itemize | 2968 @end itemize |
2668 | 2969 |
2669 You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically | 2970 You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically |
2670 update @code{face} properties based on the contents of the text. | 2971 update @code{face} properties based on the contents of the text. |
2671 | 2972 |
2680 | 2981 |
2681 Strictly speaking, @code{font-lock-face} is not a built-in text | 2982 Strictly speaking, @code{font-lock-face} is not a built-in text |
2682 property; rather, it is implemented in Font Lock mode using | 2983 property; rather, it is implemented in Font Lock mode using |
2683 @code{char-property-alias-alist}. @xref{Examining Properties}. | 2984 @code{char-property-alias-alist}. @xref{Examining Properties}. |
2684 | 2985 |
2685 This property is new in Emacs 21.4. | 2986 This property is new in Emacs 22.1. |
2686 | 2987 |
2687 @item mouse-face | 2988 @item mouse-face |
2688 @kindex mouse-face @r{(text property)} | 2989 @kindex mouse-face @r{(text property)} |
2689 The property @code{mouse-face} is used instead of @code{face} when the | 2990 The property @code{mouse-face} is used instead of @code{face} when the |
2690 mouse is on or near the character. For this purpose, ``near'' means | 2991 mouse is on or near the character. For this purpose, ``near'' means |
2713 area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs | 3014 area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs |
2714 Manual}). | 3015 Manual}). |
2715 | 3016 |
2716 If the value of the @code{help-echo} property is a function, that | 3017 If the value of the @code{help-echo} property is a function, that |
2717 function is called with three arguments, @var{window}, @var{object} and | 3018 function is called with three arguments, @var{window}, @var{object} and |
2718 @var{position} and should return a help string or @var{nil} for | 3019 @var{pos} and should return a help string or @code{nil} for |
2719 none. The first argument, @var{window} is the window in which | 3020 none. The first argument, @var{window} is the window in which |
2720 the help was found. The second, @var{object}, is the buffer, overlay or | 3021 the help was found. The second, @var{object}, is the buffer, overlay or |
2721 string which had the @code{help-echo} property. The @var{position} | 3022 string which had the @code{help-echo} property. The @var{pos} |
2722 argument is as follows: | 3023 argument is as follows: |
2723 | 3024 |
2724 @itemize @bullet{} | 3025 @itemize @bullet{} |
2725 @item | 3026 @item |
2726 If @var{object} is a buffer, @var{pos} is the position in the buffer | 3027 If @var{object} is a buffer, @var{pos} is the position in the buffer |
2745 | 3046 |
2746 @item keymap | 3047 @item keymap |
2747 @cindex keymap of character | 3048 @cindex keymap of character |
2748 @kindex keymap @r{(text property)} | 3049 @kindex keymap @r{(text property)} |
2749 The @code{keymap} property specifies an additional keymap for | 3050 The @code{keymap} property specifies an additional keymap for |
2750 commands. The property's value for the character after point, if | 3051 commands. The property's value for the character before point applies |
2751 non-@code{nil}, is used for key lookup before the buffer's local map. | 3052 if it is non-@code{nil} and rear-sticky, and the property's value for |
2752 (For mouse clicks, the @code{keymap} property of the character clicked | 3053 the character after point applies if it is non-@code{nil} and |
2753 on is the one used.) If the property value is a symbol, the symbol's | 3054 front-sticky. (For mouse clicks, the position of the click is used |
2754 function definition is used as the keymap. @xref{Active Keymaps}. | 3055 instead of the position of point.) If the property value is a symbol, |
3056 the symbol's function definition is used as the keymap. | |
3057 | |
3058 When this keymap applies, it is used for key lookup before the minor | |
3059 mode keymaps and before the buffer's local map. @xref{Active | |
3060 Keymaps}. | |
2755 | 3061 |
2756 @item local-map | 3062 @item local-map |
2757 @kindex local-map @r{(text property)} | 3063 @kindex local-map @r{(text property)} |
2758 This property specifies a keymap to use @emph{instead of} the buffer's | 3064 This property works like @code{keymap} except that it specifies a |
2759 local map. If the property value is a symbol, the symbol's function | 3065 keymap to use @emph{instead of} the buffer's local map. For most |
2760 definition is used as the keymap. For most purposes (perhaps all | 3066 purposes (perhaps all purposes), the @code{keymap} is superior. |
2761 purposes), the @code{keymap} is superior. | |
2762 | 3067 |
2763 @item syntax-table | 3068 @item syntax-table |
2764 The @code{syntax-table} property overrides what the syntax table says | 3069 The @code{syntax-table} property overrides what the syntax table says |
2765 about this particular character. @xref{Syntax Properties}. | 3070 about this particular character. @xref{Syntax Properties}. |
2766 | 3071 |
2801 @kindex field @r{(text property)} | 3106 @kindex field @r{(text property)} |
2802 Consecutive characters with the same @code{field} property constitute a | 3107 Consecutive characters with the same @code{field} property constitute a |
2803 @dfn{field}. Some motion functions including @code{forward-word} and | 3108 @dfn{field}. Some motion functions including @code{forward-word} and |
2804 @code{beginning-of-line} stop moving at a field boundary. | 3109 @code{beginning-of-line} stop moving at a field boundary. |
2805 @xref{Fields}. | 3110 @xref{Fields}. |
3111 | |
3112 @item cursor | |
3113 @kindex cursor @r{(text property)} | |
3114 Normally, the cursor is displayed at the end of any overlay and text | |
3115 property strings present at the current window position. You can | |
3116 place the cursor on any desired character of these strings by giving | |
3117 that character a non-@code{nil} @var{cursor} text property. | |
3118 | |
3119 @item pointer | |
3120 @kindex pointer @r{(text property)} | |
3121 This specifies a specific pointer shape when the mouse pointer is over | |
3122 this text or image. @xref{Pointer Shape}, for possible pointer | |
3123 shapes. | |
3124 | |
3125 @item line-spacing | |
3126 @kindex line-spacing @r{(text property)} | |
3127 A newline can have a @code{line-spacing} text or overlay property that | |
3128 controls the height of the display line ending with that newline. The | |
3129 property value overrides the default frame line spacing and the buffer | |
3130 local @code{line-spacing} variable. @xref{Line Height}. | |
3131 | |
3132 @item line-height | |
3133 @kindex line-height @r{(text property)} | |
3134 A newline can have a @code{line-height} text or overlay property that | |
3135 controls the total height of the display line ending in that newline. | |
3136 @xref{Line Height}. | |
2806 | 3137 |
2807 @item modification-hooks | 3138 @item modification-hooks |
2808 @cindex change hooks for a character | 3139 @cindex change hooks for a character |
2809 @cindex hooks for changing a character | 3140 @cindex hooks for changing a character |
2810 @kindex modification-hooks @r{(text property)} | 3141 @kindex modification-hooks @r{(text property)} |
2814 and end of the part of the buffer being modified. Note that if a | 3145 and end of the part of the buffer being modified. Note that if a |
2815 particular modification hook function appears on several characters | 3146 particular modification hook function appears on several characters |
2816 being modified by a single primitive, you can't predict how many times | 3147 being modified by a single primitive, you can't predict how many times |
2817 the function will be called. | 3148 the function will be called. |
2818 | 3149 |
3150 If these functions modify the buffer, they should bind | |
3151 @code{inhibit-modification-hooks} to @code{t} around doing so, to | |
3152 avoid confusing the internal mechanism that calls these hooks. | |
3153 | |
2819 @item insert-in-front-hooks | 3154 @item insert-in-front-hooks |
2820 @itemx insert-behind-hooks | 3155 @itemx insert-behind-hooks |
2821 @kindex insert-in-front-hooks @r{(text property)} | 3156 @kindex insert-in-front-hooks @r{(text property)} |
2822 @kindex insert-behind-hooks @r{(text property)} | 3157 @kindex insert-behind-hooks @r{(text property)} |
2823 The operation of inserting text in a buffer also calls the functions | 3158 The operation of inserting text in a buffer also calls the functions |
2857 (which may be the same function) and/or two @code{point-entered} | 3192 (which may be the same function) and/or two @code{point-entered} |
2858 functions (which may be the same function). In any case, all the | 3193 functions (which may be the same function). In any case, all the |
2859 @code{point-left} functions are called first, followed by all the | 3194 @code{point-left} functions are called first, followed by all the |
2860 @code{point-entered} functions. | 3195 @code{point-entered} functions. |
2861 | 3196 |
2862 It is possible using @code{char-after} to examine characters at various | 3197 It is possible with @code{char-after} to examine characters at various |
2863 positions without moving point to those positions. Only an actual | 3198 buffer positions without moving point to those positions. Only an |
2864 change in the value of point runs these hook functions. | 3199 actual change in the value of point runs these hook functions. |
2865 @end table | 3200 @end table |
2866 | 3201 |
2867 @defvar inhibit-point-motion-hooks | 3202 @defvar inhibit-point-motion-hooks |
2868 When this variable is non-@code{nil}, @code{point-left} and | 3203 When this variable is non-@code{nil}, @code{point-left} and |
2869 @code{point-entered} hooks are not run, and the @code{intangible} | 3204 @code{point-entered} hooks are not run, and the @code{intangible} |
2891 | 3226 |
2892 @table @code | 3227 @table @code |
2893 @item hard | 3228 @item hard |
2894 If a newline character has this property, it is a ``hard'' newline. | 3229 If a newline character has this property, it is a ``hard'' newline. |
2895 The fill commands do not alter hard newlines and do not move words | 3230 The fill commands do not alter hard newlines and do not move words |
2896 across them. However, this property takes effect only if the variable | 3231 across them. However, this property takes effect only if the |
2897 @code{use-hard-newlines} is non-@code{nil}. | 3232 @code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft |
3233 Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}. | |
2898 | 3234 |
2899 @item right-margin | 3235 @item right-margin |
2900 This property specifies an extra right margin for filling this part of the | 3236 This property specifies an extra right margin for filling this part of the |
2901 text. | 3237 text. |
2902 | 3238 |
3180 This method makes it possible to define different commands for various | 3516 This method makes it possible to define different commands for various |
3181 clickable pieces of text. Also, the major mode definition (or the | 3517 clickable pieces of text. Also, the major mode definition (or the |
3182 global definition) remains available for the rest of the text in the | 3518 global definition) remains available for the rest of the text in the |
3183 buffer. | 3519 buffer. |
3184 | 3520 |
3521 @node Links and Mouse-1 | |
3522 @subsection Links and Mouse-1 | |
3523 @cindex follow links | |
3524 @cindex mouse-1 | |
3525 | |
3526 The normal Emacs command for activating text in read-only buffers is | |
3527 @key{Mouse-2}, which includes following textual links. However, most | |
3528 graphical applications use @key{Mouse-1} for following links. For | |
3529 compatibility, @key{Mouse-1} follows links in Emacs too, when you | |
3530 click on a link quickly without moving the mouse. The user can | |
3531 customize this behavior through the variable | |
3532 @code{mouse-1-click-follows-link}. | |
3533 | |
3534 To define text as a link at the Lisp level, you should bind the | |
3535 @code{mouse-2} event to a command to follow the link. Then, to indicate that | |
3536 @key{Mouse-1} should also follow the link, you should specify a | |
3537 @code{follow-link} condition either as a text property or as a key | |
3538 binding: | |
3539 | |
3540 @table @asis | |
3541 @item @code{follow-link} property | |
3542 If the clickable text has a non-@code{nil} @code{follow-link} text or overlay | |
3543 property, that specifies the condition. | |
3544 | |
3545 @item @code{follow-link} event | |
3546 If there is a binding for the @code{follow-link} event, either on the | |
3547 clickable text or in the local keymap, the binding is the condition. | |
3548 @end table | |
3549 | |
3550 Regardless of how you set the @code{follow-link} condition, its | |
3551 value is used as follows to determine whether the given position is | |
3552 inside a link, and (if so) to compute an @dfn{action code} saying how | |
3553 @key{Mouse-1} should handle the link. | |
3554 | |
3555 @table @asis | |
3556 @item @code{mouse-face} | |
3557 If the condition is @code{mouse-face}, a position is inside a link if | |
3558 there is a non-@code{nil} @code{mouse-face} property at that position. | |
3559 The action code is always @code{t}. | |
3560 | |
3561 For example, here is how Info mode handles @key{Mouse-1}: | |
3562 | |
3563 @smallexample | |
3564 (define-key Info-mode-map [follow-link] 'mouse-face) | |
3565 @end smallexample | |
3566 | |
3567 @item a function | |
3568 If the condition is a valid function, @var{func}, then a position | |
3569 @var{pos} is inside a link if @code{(@var{func} @var{pos})} evaluates | |
3570 to non-@code{nil}. The value returned by @var{func} serves as the | |
3571 action code. | |
3572 | |
3573 For example, here is how pcvs enables @key{Mouse-1} to follow links on | |
3574 file names only: | |
3575 | |
3576 @smallexample | |
3577 (define-key map [follow-link] | |
3578 (lambda (pos) | |
3579 (eq (get-char-property pos 'face) 'cvs-filename-face))) | |
3580 @end smallexample | |
3581 | |
3582 @item anything else | |
3583 If the condition value is anything else, then the position is inside a | |
3584 link and the condition itself is the action code. Clearly you should | |
3585 only specify this kind of condition on the text that constitutes a | |
3586 link. | |
3587 @end table | |
3588 | |
3589 @noindent | |
3590 The action code tells @key{Mouse-1} how to follow the link: | |
3591 | |
3592 @table @asis | |
3593 @item a string or vector | |
3594 If the action code is a string or vector, the @key{Mouse-1} event is | |
3595 translated into the first element of the string or vector; i.e., the | |
3596 action of the @key{Mouse-1} click is the local or global binding of | |
3597 that character or symbol. Thus, if the action code is @code{"foo"}, | |
3598 @key{Mouse-1} translates into @kbd{f}. If it is @code{[foo]}, | |
3599 @key{Mouse-1} translates into @key{foo}. | |
3600 | |
3601 @item anything else | |
3602 For any other non-@code{nil} action code, the @code{mouse-1} event is | |
3603 translated into a @code{mouse-2} event at the same position. | |
3604 @end table | |
3605 | |
3606 To define @key{Mouse-1} to activate a button defined with | |
3607 @code{define-button-type}, give the button a @code{follow-link} | |
3608 property with a value as specified above to determine how to follow | |
3609 the link. For example, here is how Help mode handles @key{Mouse-1}: | |
3610 | |
3611 @smallexample | |
3612 (define-button-type 'help-xref | |
3613 'follow-link t | |
3614 'action #'help-button-action) | |
3615 @end smallexample | |
3616 | |
3617 To define @key{Mouse-1} on a widget defined with | |
3618 @code{define-widget}, give the widget a @code{:follow-link} property | |
3619 with a value as specified above to determine how to follow the link. | |
3620 | |
3621 For example, here is how the @code{link} widget specifies that | |
3622 a @key{Mouse-1} click shall be translated to @key{RET}: | |
3623 | |
3624 @smallexample | |
3625 (define-widget 'link 'item | |
3626 "An embedded link." | |
3627 :button-prefix 'widget-link-prefix | |
3628 :button-suffix 'widget-link-suffix | |
3629 :follow-link "\C-m" | |
3630 :help-echo "Follow the link." | |
3631 :format "%[%t%]") | |
3632 @end smallexample | |
3633 | |
3634 @defun mouse-on-link-p pos | |
3635 @tindex mouse-on-link-p | |
3636 This function returns non-@code{nil} if position @var{pos} in the | |
3637 current buffer is on a link. | |
3638 @end defun | |
3639 | |
3185 @node Fields | 3640 @node Fields |
3186 @subsection Defining and Using Fields | 3641 @subsection Defining and Using Fields |
3187 @cindex fields | 3642 @cindex fields |
3188 | 3643 |
3189 A field is a range of consecutive characters in the buffer that are | 3644 A field is a range of consecutive characters in the buffer that are |
3294 non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that | 3749 non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that |
3295 name, then any field boundaries are ignored. | 3750 name, then any field boundaries are ignored. |
3296 | 3751 |
3297 You can cause @code{constrain-to-field} to ignore all field boundaries | 3752 You can cause @code{constrain-to-field} to ignore all field boundaries |
3298 (and so never constrain anything) by binding the variable | 3753 (and so never constrain anything) by binding the variable |
3299 @code{inhibit-field-text-motion} to a non-nil value. | 3754 @code{inhibit-field-text-motion} to a non-@code{nil} value. |
3300 @end defun | 3755 @end defun |
3301 | 3756 |
3302 @node Not Intervals | 3757 @node Not Intervals |
3303 @subsection Why Text Properties are not Intervals | 3758 @subsection Why Text Properties are not Intervals |
3304 @cindex intervals | 3759 @cindex intervals |
3388 | 3843 |
3389 @defun translate-region start end table | 3844 @defun translate-region start end table |
3390 This function applies a translation table to the characters in the | 3845 This function applies a translation table to the characters in the |
3391 buffer between positions @var{start} and @var{end}. | 3846 buffer between positions @var{start} and @var{end}. |
3392 | 3847 |
3393 The translation table @var{table} is a string; @code{(aref @var{table} | 3848 The translation table @var{table} is a string or a char-table; |
3394 @var{ochar})} gives the translated character corresponding to | 3849 @code{(aref @var{table} @var{ochar})} gives the translated character |
3395 @var{ochar}. If the length of @var{table} is less than 256, any | 3850 corresponding to @var{ochar}. If @var{table} is a string, any |
3396 characters with codes larger than the length of @var{table} are not | 3851 characters with codes larger than the length of @var{table} are not |
3397 altered by the translation. | 3852 altered by the translation. |
3398 | 3853 |
3399 The return value of @code{translate-region} is the number of | 3854 The return value of @code{translate-region} is the number of |
3400 characters that were actually changed by the translation. This does | 3855 characters that were actually changed by the translation. This does |
3406 @section Registers | 3861 @section Registers |
3407 @cindex registers | 3862 @cindex registers |
3408 | 3863 |
3409 A register is a sort of variable used in Emacs editing that can hold a | 3864 A register is a sort of variable used in Emacs editing that can hold a |
3410 variety of different kinds of values. Each register is named by a | 3865 variety of different kinds of values. Each register is named by a |
3411 single character. All @sc{ascii} characters and their meta variants | 3866 single character. All @acronym{ASCII} characters and their meta variants |
3412 (but with the exception of @kbd{C-g}) can be used to name registers. | 3867 (but with the exception of @kbd{C-g}) can be used to name registers. |
3413 Thus, there are 255 possible registers. A register is designated in | 3868 Thus, there are 255 possible registers. A register is designated in |
3414 Emacs Lisp by the character that is its name. | 3869 Emacs Lisp by the character that is its name. |
3415 | 3870 |
3416 @defvar register-alist | 3871 @defvar register-alist |
3574 @node Base 64 | 4029 @node Base 64 |
3575 @section Base 64 Encoding | 4030 @section Base 64 Encoding |
3576 @cindex base 64 encoding | 4031 @cindex base 64 encoding |
3577 | 4032 |
3578 Base 64 code is used in email to encode a sequence of 8-bit bytes as | 4033 Base 64 code is used in email to encode a sequence of 8-bit bytes as |
3579 a longer sequence of @sc{ascii} graphic characters. It is defined in | 4034 a longer sequence of @acronym{ASCII} graphic characters. It is defined in |
3580 Internet RFC@footnote{ | 4035 Internet RFC@footnote{ |
3581 An RFC, an acronym for @dfn{Request for Comments}, is a numbered | 4036 An RFC, an acronym for @dfn{Request for Comments}, is a numbered |
3582 Internet informational document describing a standard. RFCs are | 4037 Internet informational document describing a standard. RFCs are |
3583 usually written by technical experts acting on their own initiative, | 4038 usually written by technical experts acting on their own initiative, |
3584 and are traditionally written in a pragmatic, experience-driven | 4039 and are traditionally written in a pragmatic, experience-driven |
3624 @end defun | 4079 @end defun |
3625 | 4080 |
3626 @defun base64-decode-string string | 4081 @defun base64-decode-string string |
3627 @tindex base64-decode-string | 4082 @tindex base64-decode-string |
3628 This function converts the string @var{string} from base 64 code into | 4083 This function converts the string @var{string} from base 64 code into |
3629 the corresponding decoded text. It returns a string containing the | 4084 the corresponding decoded text. It returns a unibyte string containing the |
3630 decoded text. | 4085 decoded text. |
3631 | 4086 |
3632 The decoding functions ignore newline characters in the encoded text. | 4087 The decoding functions ignore newline characters in the encoded text. |
3633 @end defun | 4088 @end defun |
3634 | 4089 |
3678 using the specified or chosen coding system. However, if | 4133 using the specified or chosen coding system. However, if |
3679 @var{noerror} is non-@code{nil}, it silently uses @code{raw-text} | 4134 @var{noerror} is non-@code{nil}, it silently uses @code{raw-text} |
3680 coding instead. | 4135 coding instead. |
3681 @end defun | 4136 @end defun |
3682 | 4137 |
4138 @node Atomic Changes | |
4139 @section Atomic Change Groups | |
4140 @cindex atomic changes | |
4141 | |
4142 In data base terminology, an @dfn{atomic} change is an indivisible | |
4143 change---it can succeed entirely or it can fail entirely, but it | |
4144 cannot partly succeed. A Lisp program can make a series of changes to | |
4145 one or several buffers as an @dfn{atomic change group}, meaning that | |
4146 either the entire series of changes will be installed in their buffers | |
4147 or, in case of an error, none of them will be. | |
4148 | |
4149 To do this for one buffer, the one already current, simply write a | |
4150 call to @code{atomic-change-group} around the code that makes the | |
4151 changes, like this: | |
4152 | |
4153 @example | |
4154 (atomic-change-group | |
4155 (insert foo) | |
4156 (delete-region x y)) | |
4157 @end example | |
4158 | |
4159 @noindent | |
4160 If an error (or other nonlocal exit) occurs inside the body of | |
4161 @code{atomic-change-group}, it unmakes all the changes in that buffer | |
4162 that were during the execution of the body. This kind of change group | |
4163 has no effect on any other buffers---any such changes remain. | |
4164 | |
4165 If you need something more sophisticated, such as to make changes in | |
4166 various buffers constitute one atomic group, you must directly call | |
4167 lower-level functions that @code{atomic-change-group} uses. | |
4168 | |
4169 @defun prepare-change-group &optional buffer | |
4170 This function sets up a change group for buffer @var{buffer}, which | |
4171 defaults to the current buffer. It returns a ``handle'' that | |
4172 represents the change group. You must use this handle to activate the | |
4173 change group and subsequently to finish it. | |
4174 @end defun | |
4175 | |
4176 To use the change group, you must @dfn{activate} it. You must do | |
4177 this before making any changes in the text of @var{buffer}. | |
4178 | |
4179 @defun activate-change-group handle | |
4180 This function activates the change group that @var{handle} designates. | |
4181 @end defun | |
4182 | |
4183 After you activate the change group, any changes you make in that | |
4184 buffer become part of it. Once you have made all the desired changes | |
4185 in the buffer, you must @dfn{finish} the change group. There are two | |
4186 ways to do this: you can either accept (and finalize) all the changes, | |
4187 or cancel them all. | |
4188 | |
4189 @defun accept-change-group handle | |
4190 This function accepts all the changes in the change group specified by | |
4191 @var{handle}, making them final. | |
4192 @end defun | |
4193 | |
4194 @defun cancel-change-group handle | |
4195 This function cancels and undoes all the changes in the change group | |
4196 specified by @var{handle}. | |
4197 @end defun | |
4198 | |
4199 Your code should use @code{unwind-protect} to make sure the group is | |
4200 always finished. The call to @code{activate-change-group} should be | |
4201 inside the @code{unwind-protect}, in case the user types @kbd{C-g} | |
4202 just after it runs. (This is one reason why | |
4203 @code{prepare-change-group} and @code{activate-change-group} are | |
4204 separate functions, because normally you would call | |
4205 @code{prepare-change-group} before the start of that | |
4206 @code{unwind-protect}.) Once you finish the group, don't use the | |
4207 handle again---in particular, don't try to finish the same group | |
4208 twice. | |
4209 | |
4210 To make a multibuffer change group, call @code{prepare-change-group} | |
4211 once for each buffer you want to cover, then use @code{nconc} to | |
4212 combine the returned values, like this: | |
4213 | |
4214 @example | |
4215 (nconc (prepare-change-group buffer-1) | |
4216 (prepare-change-group buffer-2)) | |
4217 @end example | |
4218 | |
4219 You can then activate the multibuffer change group with a single call | |
4220 to @code{activate-change-group}, and finish it with a single call to | |
4221 @code{accept-change-group} or @code{cancel-change-group}. | |
4222 | |
4223 Nested use of several change groups for the same buffer works as you | |
4224 would expect. Non-nested use of change groups for the same buffer | |
4225 will get Emacs confused, so don't let it happen; the first change | |
4226 group you start for any given buffer should be the last one finished. | |
4227 | |
3683 @node Change Hooks | 4228 @node Change Hooks |
3684 @section Change Hooks | 4229 @section Change Hooks |
3685 @cindex change hooks | 4230 @cindex change hooks |
3686 @cindex hooks for text changes | 4231 @cindex hooks for text changes |
3687 | 4232 |
3713 before and after that text as it was before the change. As for the | 4258 before and after that text as it was before the change. As for the |
3714 changed text, its length is simply the difference between the first two | 4259 changed text, its length is simply the difference between the first two |
3715 arguments. | 4260 arguments. |
3716 @end defvar | 4261 @end defvar |
3717 | 4262 |
3718 @defmac combine-after-change-calls body... | 4263 Output of messages into the @samp{*Messages*} buffer does not |
4264 call these functions. | |
4265 | |
4266 @defmac combine-after-change-calls body@dots{} | |
3719 The macro executes @var{body} normally, but arranges to call the | 4267 The macro executes @var{body} normally, but arranges to call the |
3720 after-change functions just once for a series of several changes---if | 4268 after-change functions just once for a series of several changes---if |
3721 that seems safe. | 4269 that seems safe. |
3722 | 4270 |
3723 If a program makes several text changes in the same area of the buffer, | 4271 If a program makes several text changes in the same area of the buffer, |
3729 | 4277 |
3730 @strong{Warning:} You must not alter the values of | 4278 @strong{Warning:} You must not alter the values of |
3731 @code{after-change-functions} within | 4279 @code{after-change-functions} within |
3732 the body of a @code{combine-after-change-calls} form. | 4280 the body of a @code{combine-after-change-calls} form. |
3733 | 4281 |
3734 @strong{Note:} If the changes you combine occur in widely scattered | 4282 @strong{Warning:} if the changes you combine occur in widely scattered |
3735 parts of the buffer, this will still work, but it is not advisable, | 4283 parts of the buffer, this will still work, but it is not advisable, |
3736 because it may lead to inefficient behavior for some change hook | 4284 because it may lead to inefficient behavior for some change hook |
3737 functions. | 4285 functions. |
3738 @end defmac | 4286 @end defmac |
3739 | 4287 |
3776 If this variable is non-@code{nil}, all of the change hooks are | 4324 If this variable is non-@code{nil}, all of the change hooks are |
3777 disabled; none of them run. This affects all the hook variables | 4325 disabled; none of them run. This affects all the hook variables |
3778 described above in this section, as well as the hooks attached to | 4326 described above in this section, as well as the hooks attached to |
3779 certain special text properties (@pxref{Special Properties}) and overlay | 4327 certain special text properties (@pxref{Special Properties}) and overlay |
3780 properties (@pxref{Overlay Properties}). | 4328 properties (@pxref{Overlay Properties}). |
3781 | |
3782 This variable is available starting in Emacs 21. | |
3783 @end defvar | 4329 @end defvar |
4330 | |
4331 @ignore | |
4332 arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b | |
4333 @end ignore |