Mercurial > emacs
comparison lispref/text.texi @ 22252:40089afa2b1d
*** empty log message ***
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Tue, 26 May 1998 18:56:56 +0000 |
parents | d4ac295a98b3 |
children | dfac7398266b |
comparison
equal
deleted
inserted
replaced
22251:5989fa41cda6 | 22252:40089afa2b1d |
---|---|
40 * Undo:: Undoing changes to the text of a buffer. | 40 * Undo:: Undoing changes to the text of a buffer. |
41 * Maintaining Undo:: How to enable and disable undo information. | 41 * Maintaining Undo:: How to enable and disable undo information. |
42 How to control how much information is kept. | 42 How to control how much information is kept. |
43 * Filling:: Functions for explicit filling. | 43 * Filling:: Functions for explicit filling. |
44 * Margins:: How to specify margins for filling commands. | 44 * Margins:: How to specify margins for filling commands. |
45 * Adaptive Fill: Adaptive Fill mode chooses a fill prefix from context. | |
45 * Auto Filling:: How auto-fill mode is implemented to break lines. | 46 * Auto Filling:: How auto-fill mode is implemented to break lines. |
46 * Sorting:: Functions for sorting parts of the buffer. | 47 * Sorting:: Functions for sorting parts of the buffer. |
47 * Columns:: Computing horizontal positions, and using them. | 48 * Columns:: Computing horizontal positions, and using them. |
48 * Indentation:: Functions to insert or adjust indentation. | 49 * Indentation:: Functions to insert or adjust indentation. |
49 * Case Changes:: Case conversion of parts of the buffer. | 50 * Case Changes:: Case conversion of parts of the buffer. |
60 | 61 |
61 Many functions are provided to look at the characters around point. | 62 Many functions are provided to look at the characters around point. |
62 Several simple functions are described here. See also @code{looking-at} | 63 Several simple functions are described here. See also @code{looking-at} |
63 in @ref{Regexp Search}. | 64 in @ref{Regexp Search}. |
64 | 65 |
65 @defun char-after position | 66 @defun char-after &optional position |
66 This function returns the character in the current buffer at (i.e., | 67 This function returns the character in the current buffer at (i.e., |
67 immediately after) position @var{position}. If @var{position} is out of | 68 immediately after) position @var{position}. If @var{position} is out of |
68 range for this purpose, either before the beginning of the buffer, or at | 69 range for this purpose, either before the beginning of the buffer, or at |
69 or beyond the end, then the value is @code{nil}. | 70 or beyond the end, then the value is @code{nil}. The default for |
71 @var{position} is point. | |
70 | 72 |
71 In the following example, assume that the first character in the | 73 In the following example, assume that the first character in the |
72 buffer is @samp{@@}: | 74 buffer is @samp{@@}: |
73 | 75 |
74 @example | 76 @example |
77 @result{} "@@" | 79 @result{} "@@" |
78 @end group | 80 @end group |
79 @end example | 81 @end example |
80 @end defun | 82 @end defun |
81 | 83 |
82 @defun char-before position | 84 @defun char-before &optional position |
83 This function returns the character in the current buffer immediately | 85 This function returns the character in the current buffer immediately |
84 before position @var{position}. If @var{position} is out of range for | 86 before position @var{position}. If @var{position} is out of range for |
85 this purpose, either before the beginning of the buffer, or at or beyond | 87 this purpose, either before the beginning of the buffer, or at or beyond |
86 the end, then the value is @code{nil}. | 88 the end, then the value is @code{nil}. The default for |
89 @var{position} is point. | |
87 @end defun | 90 @end defun |
88 | 91 |
89 @defun following-char | 92 @defun following-char |
90 This function returns the character following point in the current | 93 This function returns the character following point in the current |
91 buffer. This is similar to @code{(char-after (point))}. However, if | 94 buffer. This is similar to @code{(char-after (point))}. However, if |
447 | 450 |
448 Programs hardly ever use this function. | 451 Programs hardly ever use this function. |
449 @end deffn | 452 @end deffn |
450 | 453 |
451 @defvar overwrite-mode | 454 @defvar overwrite-mode |
452 This variable controls whether overwrite mode is in effect: a | 455 This variable controls whether overwrite mode is in effect. The value |
453 non-@code{nil} value enables the mode. It is automatically made | 456 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary}, |
454 buffer-local when set in any fashion. | 457 or @code{nil}. @code{overwrite-mode-textual} specifies textual |
458 overwrite mode (treats newlines and tabs specially), and | |
459 @code{overwrite-mode-binary} specifies binary overwrite mode (treats | |
460 newlines and tabs like any other characters). | |
455 @end defvar | 461 @end defvar |
456 | 462 |
457 @node Deletion | 463 @node Deletion |
458 @section Deleting Text | 464 @section Deleting Text |
459 | 465 |
465 cases. | 471 cases. |
466 | 472 |
467 All of the deletion functions operate on the current buffer, and all | 473 All of the deletion functions operate on the current buffer, and all |
468 return a value of @code{nil}. | 474 return a value of @code{nil}. |
469 | 475 |
470 @defun erase-buffer | 476 @deffn Command erase-buffer |
471 This function deletes the entire text of the current buffer, leaving it | 477 This function deletes the entire text of the current buffer, leaving it |
472 empty. If the buffer is read-only, it signals a @code{buffer-read-only} | 478 empty. If the buffer is read-only, it signals a @code{buffer-read-only} |
473 error. Otherwise, it deletes the text without asking for any | 479 error. Otherwise, it deletes the text without asking for any |
474 confirmation. It returns @code{nil}. | 480 confirmation. It returns @code{nil}. |
475 | 481 |
476 Normally, deleting a large amount of text from a buffer inhibits further | 482 Normally, deleting a large amount of text from a buffer inhibits further |
477 auto-saving of that buffer ``because it has shrunk''. However, | 483 auto-saving of that buffer ``because it has shrunk''. However, |
478 @code{erase-buffer} does not do this, the idea being that the future | 484 @code{erase-buffer} does not do this, the idea being that the future |
479 text is not really related to the former text, and its size should not | 485 text is not really related to the former text, and its size should not |
480 be compared with that of the former text. | 486 be compared with that of the former text. |
481 @end defun | 487 @end deffn |
482 | 488 |
483 @deffn Command delete-region start end | 489 @deffn Command delete-region start end |
484 This command deletes the text in the current buffer in the region | 490 This command deletes the text in the current buffer in the region |
485 defined by @var{start} and @var{end}. The value is @code{nil}. If | 491 defined by @var{start} and @var{end}. The value is @code{nil}. If |
486 point was inside the deleted region, its value afterward is @var{start}. | 492 point was inside the deleted region, its value afterward is @var{start}. |
776 If the buffer is read-only, @code{kill-region} modifies the kill ring | 782 If the buffer is read-only, @code{kill-region} modifies the kill ring |
777 just the same, then signals an error without modifying the buffer. This | 783 just the same, then signals an error without modifying the buffer. This |
778 is convenient because it lets the user use all the kill commands to copy | 784 is convenient because it lets the user use all the kill commands to copy |
779 text into the kill ring from a read-only buffer. | 785 text into the kill ring from a read-only buffer. |
780 @end deffn | 786 @end deffn |
787 | |
788 @defopt kill-read-only-ok | |
789 If this option is non-@code{nil}, @code{kill-region} does not get an | |
790 error if the buffer is read-only. Instead, it simply returns, updating | |
791 the kill ring but not changing the buffer. | |
792 @end defopt | |
781 | 793 |
782 @deffn Command copy-region-as-kill start end | 794 @deffn Command copy-region-as-kill start end |
783 This command saves the region defined by @var{start} and @var{end} on | 795 This command saves the region defined by @var{start} and @var{end} on |
784 the kill ring (including text properties), but does not delete the text | 796 the kill ring (including text properties), but does not delete the text |
785 from the buffer. It returns @code{nil}. It also indicates the extent | 797 from the buffer. It returns @code{nil}. It also indicates the extent |
998 @end defvar | 1010 @end defvar |
999 | 1011 |
1000 Here are the kinds of elements an undo list can have: | 1012 Here are the kinds of elements an undo list can have: |
1001 | 1013 |
1002 @table @code | 1014 @table @code |
1003 @item @var{integer} | 1015 @item @var{position} |
1004 This kind of element records a previous value of point. Ordinary cursor | 1016 This kind of element records a previous value of point; undoing this |
1005 motion does not get any sort of undo record, but deletion operations use | 1017 element moves point to @var{position}. Ordinary cursor motion does not |
1006 these entries to record where point was before the command. | 1018 make any sort of undo record, but deletion operations use these entries |
1019 to record where point was before the command. | |
1007 | 1020 |
1008 @item (@var{beg} . @var{end}) | 1021 @item (@var{beg} . @var{end}) |
1009 This kind of element indicates how to delete text that was inserted. | 1022 This kind of element indicates how to delete text that was inserted. |
1010 Upon insertion, the text occupied the range @var{beg}--@var{end} in the | 1023 Upon insertion, the text occupied the range @var{beg}--@var{end} in the |
1011 buffer. | 1024 buffer. |
1034 @item (@var{marker} . @var{adjustment}) | 1047 @item (@var{marker} . @var{adjustment}) |
1035 This kind of element records the fact that the marker @var{marker} was | 1048 This kind of element records the fact that the marker @var{marker} was |
1036 relocated due to deletion of surrounding text, and that it moved | 1049 relocated due to deletion of surrounding text, and that it moved |
1037 @var{adjustment} character positions. Undoing this element moves | 1050 @var{adjustment} character positions. Undoing this element moves |
1038 @var{marker} @minus{} @var{adjustment} characters. | 1051 @var{marker} @minus{} @var{adjustment} characters. |
1039 | |
1040 @item @var{position} | |
1041 This element indicates where point was at an earlier time. Undoing this | |
1042 element sets point to @var{position}. Deletion normally creates an | |
1043 element of this kind as well as a reinsertion element. | |
1044 | 1052 |
1045 @item nil | 1053 @item nil |
1046 This element is a boundary. The elements between two boundaries are | 1054 This element is a boundary. The elements between two boundaries are |
1047 called a @dfn{change group}; normally, each change group corresponds to | 1055 called a @dfn{change group}; normally, each change group corresponds to |
1048 one keyboard command, and undo commands normally undo an entire group as | 1056 one keyboard command, and undo commands normally undo an entire group as |
1183 @var{justify} is non-@code{nil}, each line is justified as well. | 1191 @var{justify} is non-@code{nil}, each line is justified as well. |
1184 It uses the ordinary paragraph motion commands to find paragraph | 1192 It uses the ordinary paragraph motion commands to find paragraph |
1185 boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}. | 1193 boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}. |
1186 @end deffn | 1194 @end deffn |
1187 | 1195 |
1188 @deffn Command fill-region start end &optional justify | 1196 @deffn Command fill-region start end &optional justify nosqueeze |
1189 This command fills each of the paragraphs in the region from @var{start} | 1197 This command fills each of the paragraphs in the region from @var{start} |
1190 to @var{end}. It justifies as well if @var{justify} is | 1198 to @var{end}. It justifies as well if @var{justify} is |
1191 non-@code{nil}. | 1199 non-@code{nil}. |
1200 | |
1201 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace | |
1202 other than line breaks untouched. If @var{to-eop} is non-@code{nil}, | |
1203 that means to keep filling to the end of the paragraph---or next hard | |
1204 newline, if @code{use-hard-newlines} is enabled (see below). | |
1192 | 1205 |
1193 The variable @code{paragraph-separate} controls how to distinguish | 1206 The variable @code{paragraph-separate} controls how to distinguish |
1194 paragraphs. @xref{Standard Regexps}. | 1207 paragraphs. @xref{Standard Regexps}. |
1195 @end deffn | 1208 @end deffn |
1196 | 1209 |
1218 @defopt fill-individual-varying-indent | 1231 @defopt fill-individual-varying-indent |
1219 This variable alters the action of @code{fill-individual-paragraphs} as | 1232 This variable alters the action of @code{fill-individual-paragraphs} as |
1220 described above. | 1233 described above. |
1221 @end defopt | 1234 @end defopt |
1222 | 1235 |
1223 @deffn Command fill-region-as-paragraph start end &optional justify | 1236 @deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after |
1224 This command considers a region of text as a single paragraph and fills | 1237 This command considers a region of text as a single paragraph and fills |
1225 it. If the region was made up of many paragraphs, the blank lines | 1238 it. If the region was made up of many paragraphs, the blank lines |
1226 between paragraphs are removed. This function justifies as well as | 1239 between paragraphs are removed. This function justifies as well as |
1227 filling when @var{justify} is non-@code{nil}. | 1240 filling when @var{justify} is non-@code{nil}. |
1228 | 1241 |
1229 In an interactive call, any prefix argument requests justification. | 1242 In an interactive call, any prefix argument requests justification. |
1230 | 1243 |
1231 @cindex Adaptive Fill mode | 1244 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace |
1232 In Adaptive Fill mode, which is enabled by default, calling the function | 1245 other than line breaks untouched. If @var{squeeze-after} is |
1233 @code{fill-region-as-paragraph} on an indented paragraph when there is | 1246 non-@code{nil}, specifies a position in the region, and means don't |
1234 no fill prefix uses the indentation of the second line of the paragraph | 1247 canonicalize spaces before that position. |
1235 as the fill prefix. | 1248 |
1249 In Adaptive Fill mode, this command calls @code{fill-context-prefix} to | |
1250 choose a fill prefix by default. @xref{Adaptive Fill}. | |
1236 @end deffn | 1251 @end deffn |
1237 | 1252 |
1238 @deffn Command justify-current-line how eop nosqueeze | 1253 @deffn Command justify-current-line how eop nosqueeze |
1239 This command inserts spaces between the words of the current line so | 1254 This command inserts spaces between the words of the current line so |
1240 that the line ends exactly at @code{fill-column}. It returns | 1255 that the line ends exactly at @code{fill-column}. It returns |
1264 | 1279 |
1265 @defun current-justification | 1280 @defun current-justification |
1266 This function returns the proper justification style to use for filling | 1281 This function returns the proper justification style to use for filling |
1267 the text around point. | 1282 the text around point. |
1268 @end defun | 1283 @end defun |
1284 | |
1285 @defopt sentence-end-double-space | |
1286 If this variable is non-@code{nil}, a period followed by just one space | |
1287 does not count as the end of a sentence, and the filling functions | |
1288 avoid breaking the line at such a place. | |
1289 @end defopt | |
1269 | 1290 |
1270 @defvar fill-paragraph-function | 1291 @defvar fill-paragraph-function |
1271 This variable provides a way for major modes to override the filling of | 1292 This variable provides a way for major modes to override the filling of |
1272 paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls | 1293 paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls |
1273 this function to do the work. If the function returns a non-@code{nil} | 1294 this function to do the work. If the function returns a non-@code{nil} |
1304 together. The resulting filled lines also start with the fill prefix. | 1325 together. The resulting filled lines also start with the fill prefix. |
1305 | 1326 |
1306 The fill prefix follows the left margin whitespace, if any. | 1327 The fill prefix follows the left margin whitespace, if any. |
1307 @end defopt | 1328 @end defopt |
1308 | 1329 |
1309 @defvar fill-column | 1330 @defopt fill-column |
1310 This buffer-local variable specifies the maximum width of filled lines. | 1331 This buffer-local variable specifies the maximum width of filled lines. |
1311 Its value should be an integer, which is a number of columns. All the | 1332 Its value should be an integer, which is a number of columns. All the |
1312 filling, justification, and centering commands are affected by this | 1333 filling, justification, and centering commands are affected by this |
1313 variable, including Auto Fill mode (@pxref{Auto Filling}). | 1334 variable, including Auto Fill mode (@pxref{Auto Filling}). |
1314 | 1335 |
1315 As a practical matter, if you are writing text for other people to | 1336 As a practical matter, if you are writing text for other people to |
1316 read, you should set @code{fill-column} to no more than 70. Otherwise | 1337 read, you should set @code{fill-column} to no more than 70. Otherwise |
1317 the line will be too long for people to read comfortably, and this can | 1338 the line will be too long for people to read comfortably, and this can |
1318 make the text seem clumsy. | 1339 make the text seem clumsy. |
1319 @end defvar | 1340 @end defopt |
1320 | 1341 |
1321 @defvar default-fill-column | 1342 @defvar default-fill-column |
1322 The value of this variable is the default value for @code{fill-column} in | 1343 The value of this variable is the default value for @code{fill-column} in |
1323 buffers that do not override it. This is the same as | 1344 buffers that do not override it. This is the same as |
1324 @code{(default-value 'fill-column)}. | 1345 @code{(default-value 'fill-column)}. |
1389 certain places. Its value should be a function. This function is | 1410 certain places. Its value should be a function. This function is |
1390 called during filling, with no arguments and with point located at the | 1411 called during filling, with no arguments and with point located at the |
1391 place where a break is being considered. If the function returns | 1412 place where a break is being considered. If the function returns |
1392 non-@code{nil}, then the line won't be broken there. | 1413 non-@code{nil}, then the line won't be broken there. |
1393 @end defvar | 1414 @end defvar |
1415 | |
1416 @node Adaptive Fill | |
1417 @section Adaptive Fill Mode | |
1418 @cindex Adaptive Fill mode | |
1419 | |
1420 Adaptive Fill mode chooses a fill prefix automatically from the text | |
1421 in each paragraph being filled. | |
1422 | |
1423 @defopt adaptive-fill-mode | |
1424 Adaptive Fill mode is enabled when this variable is non-@code{nil}. | |
1425 It is @code{t} by default. | |
1426 @end defopt | |
1427 | |
1428 @defun fill-context-prefix from to | |
1429 This function implements the heart of Adaptive Fill mode; it chooses a | |
1430 fill prefix based on the text between @var{from} and @var{to}. It does | |
1431 this by looking at the first two lines of the paragraph, based on the | |
1432 variables described below. | |
1433 @end defun | |
1434 | |
1435 @defopt adaptive-fill-regexp | |
1436 This variable holds a regular expression to control Adaptive Fill mode. | |
1437 Whichever characters starting after the line's left margin match this | |
1438 regular expression, those are the candidate for the fill prefix. | |
1439 @end defopt | |
1440 | |
1441 @defopt adaptive-fill-first-line-regexp | |
1442 In a one-line paragraph, if the candidate fill prefix matches | |
1443 this regular expression, or if it matches @code{comment-start-skip}, | |
1444 then it is used---otherwise, it is replaced with an equivalent | |
1445 number of spaces. | |
1446 | |
1447 However, the fill prefix is never taken from a one-line paragraph | |
1448 if it would act as a paragraph starter on subsequent lines. | |
1449 @end defopt | |
1450 | |
1451 @defopt adaptive-fill-function | |
1452 You can specify more complex ways of choosing a fill prefix | |
1453 automatically by setting this variable to a function. The function is | |
1454 called when @code{adaptive-fill-regexp} does not match, with point after | |
1455 the left margin of a line, and it should return the appropriate fill | |
1456 prefix based on that line. If it returns @code{nil}, that means it sees | |
1457 no fill prefix in that line. | |
1458 @end defopt | |
1394 | 1459 |
1395 @node Auto Filling | 1460 @node Auto Filling |
1396 @comment node-name, next, previous, up | 1461 @comment node-name, next, previous, up |
1397 @section Auto Filling | 1462 @section Auto Filling |
1398 @cindex filling, automatic | 1463 @cindex filling, automatic |
1511 whether alphabetic case affects | 1576 whether alphabetic case affects |
1512 the sort order. | 1577 the sort order. |
1513 @end group | 1578 @end group |
1514 @group | 1579 @group |
1515 (interactive "P\nr") | 1580 (interactive "P\nr") |
1516 (save-restriction | 1581 (save-excursion |
1517 (narrow-to-region beg end) | 1582 (save-restriction |
1518 (goto-char (point-min)) | 1583 (narrow-to-region beg end) |
1519 (sort-subr reverse 'forward-line 'end-of-line))) | 1584 (goto-char (point-min)) |
1585 (sort-subr reverse 'forward-line 'end-of-line)))) | |
1520 @end group | 1586 @end group |
1521 @end example | 1587 @end example |
1522 | 1588 |
1523 Here @code{forward-line} moves point to the start of the next record, | 1589 Here @code{forward-line} moves point to the start of the next record, |
1524 and @code{end-of-line} moves point to the end of record. We do not pass | 1590 and @code{end-of-line} moves point to the end of record. We do not pass |
1529 its @code{sort-subr} call looks like this: | 1595 its @code{sort-subr} call looks like this: |
1530 | 1596 |
1531 @example | 1597 @example |
1532 @group | 1598 @group |
1533 (sort-subr reverse | 1599 (sort-subr reverse |
1534 (function | 1600 (function |
1535 (lambda () (skip-chars-forward "\n \t\f"))) | 1601 (lambda () |
1602 (while (and (not (eobp)) | |
1603 (looking-at paragraph-separate)) | |
1604 (forward-line 1)))) | |
1536 'forward-paragraph) | 1605 'forward-paragraph) |
1537 @end group | 1606 @end group |
1538 @end example | 1607 @end example |
1539 | 1608 |
1540 Markers pointing into any sort records are left with no useful | 1609 Markers pointing into any sort records are left with no useful |
1541 position after @code{sort-subr} returns. | 1610 position after @code{sort-subr} returns. |
1542 @end defun | 1611 @end defun |
1612 | |
1613 @defopt sort-fold-case | |
1614 If this variable is non-@code{nil}, @code{sort-subr} and the other | |
1615 buffer sorting functions ignore case when comparing strings. | |
1616 @end defopt | |
1543 | 1617 |
1544 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end | 1618 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end |
1545 This command sorts the region between @var{start} and @var{end} | 1619 This command sorts the region between @var{start} and @var{end} |
1546 alphabetically as specified by @var{record-regexp} and @var{key-regexp}. | 1620 alphabetically as specified by @var{record-regexp} and @var{key-regexp}. |
1547 If @var{reverse} is a negative integer, then sorting is in reverse | 1621 If @var{reverse} is a negative integer, then sorting is in reverse |
1821 @end deffn | 1895 @end deffn |
1822 | 1896 |
1823 @deffn Command reindent-then-newline-and-indent | 1897 @deffn Command reindent-then-newline-and-indent |
1824 @comment !!SourceFile simple.el | 1898 @comment !!SourceFile simple.el |
1825 This command reindents the current line, inserts a newline at point, | 1899 This command reindents the current line, inserts a newline at point, |
1826 and then reindents the new line (the one following the newline just | 1900 and then indents the new line (the one following the newline just |
1827 inserted). | 1901 inserted). |
1828 | 1902 |
1829 This command does indentation on both lines according to the current | 1903 This command does indentation on both lines according to the current |
1830 major mode, by calling the current value of @code{indent-line-function}. | 1904 major mode, by calling the current value of @code{indent-line-function}. |
1831 In programming language modes, this is the same thing @key{TAB} does, | 1905 In programming language modes, this is the same thing @key{TAB} does, |
3175 modification. Each function receives three arguments: the beginning and | 3249 modification. Each function receives three arguments: the beginning and |
3176 end of the region just changed, and the length of the text that existed | 3250 end of the region just changed, and the length of the text that existed |
3177 before the change. All three arguments are integers. The buffer that's | 3251 before the change. All three arguments are integers. The buffer that's |
3178 about to change is always the current buffer. | 3252 about to change is always the current buffer. |
3179 | 3253 |
3180 The length of the old text the difference between the buffer positions | 3254 The length of the old text is the difference between the buffer positions |
3181 before and after that text as it was before the change. As for the | 3255 before and after that text as it was before the change. As for the |
3182 changed text, its length is simply the difference between the first two | 3256 changed text, its length is simply the difference between the first two |
3183 arguments. | 3257 arguments. |
3184 @end defvar | 3258 @end defvar |
3185 | 3259 |