Mercurial > emacs
annotate lispref/text.texi @ 28285:c54d62415e91
Changed the type of parameter passed to the
function defined by `quickurl-format-function'. Before only the
text of the URL was passed. Now the whole URL structure is passed
and the function is responsible for extracting the parts it
requires. Changed the default of `quickurl-format-function'
accordingly.
(quickurl-insert): Changed the `funcall' of
`quickurl-format-function' to match the above change.
(quickurl-list-insert): Changed the `url' case so that it makes
use of `quickurl-format-function', previous to this the format was
hard wired.
author | Gerd Moellmann <gerd@gnu.org> |
---|---|
date | Thu, 23 Mar 2000 13:53:14 +0000 |
parents | cabb1b4c4424 |
children | 951c07315d97 |
rev | line source |
---|---|
6558 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
27189 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 |
4 @c Free Software Foundation, Inc. | |
6558 | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/text | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
7 @node Text, Non-ASCII Characters, Markers, Top |
6558 | 8 @chapter Text |
9 @cindex text | |
10 | |
11 This chapter describes the functions that deal with the text in a | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
12 buffer. Most examine, insert, or delete text in the current buffer, |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
13 often operating at point or on text adjacent to point. Many are |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
14 interactive. All the functions that change the text provide for undoing |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
15 the changes (@pxref{Undo}). |
6558 | 16 |
17 Many text-related functions operate on a region of text defined by two | |
18 buffer positions passed in arguments named @var{start} and @var{end}. | |
19 These arguments should be either markers (@pxref{Markers}) or numeric | |
20 character positions (@pxref{Positions}). The order of these arguments | |
21 does not matter; it is all right for @var{start} to be the end of the | |
22 region and @var{end} the beginning. For example, @code{(delete-region 1 | |
23 10)} and @code{(delete-region 10 1)} are equivalent. An | |
24 @code{args-out-of-range} error is signaled if either @var{start} or | |
25 @var{end} is outside the accessible portion of the buffer. In an | |
26 interactive call, point and the mark are used for these arguments. | |
27 | |
28 @cindex buffer contents | |
29 Throughout this chapter, ``text'' refers to the characters in the | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
30 buffer, together with their properties (when relevant). Keep in mind |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
31 that point is always between two characters, and the cursor appears on |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
32 the character after point. |
6558 | 33 |
34 @menu | |
35 * Near Point:: Examining text in the vicinity of point. | |
36 * Buffer Contents:: Examining text in a general fashion. | |
37 * Comparing Text:: Comparing substrings of buffers. | |
38 * Insertion:: Adding new text to a buffer. | |
39 * Commands for Insertion:: User-level commands to insert text. | |
40 * Deletion:: Removing text from a buffer. | |
41 * User-Level Deletion:: User-level commands to delete text. | |
42 * The Kill Ring:: Where removed text sometimes is saved for later use. | |
43 * Undo:: Undoing changes to the text of a buffer. | |
44 * Maintaining Undo:: How to enable and disable undo information. | |
45 How to control how much information is kept. | |
46 * Filling:: Functions for explicit filling. | |
12098 | 47 * Margins:: How to specify margins for filling commands. |
23147 | 48 * Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context. |
6558 | 49 * Auto Filling:: How auto-fill mode is implemented to break lines. |
50 * Sorting:: Functions for sorting parts of the buffer. | |
51 * Columns:: Computing horizontal positions, and using them. | |
52 * Indentation:: Functions to insert or adjust indentation. | |
53 * Case Changes:: Case conversion of parts of the buffer. | |
54 * Text Properties:: Assigning Lisp property lists to text characters. | |
55 * Substitution:: Replacing a given character wherever it appears. | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
56 * Transposition:: Swapping two portions of a buffer. |
6558 | 57 * Registers:: How registers are implemented. Accessing the text or |
58 position stored in a register. | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
59 * Base 64:: Conversion to or from base 64 encoding. |
6558 | 60 * Change Hooks:: Supplying functions to be run when text is changed. |
61 @end menu | |
62 | |
63 @node Near Point | |
64 @section Examining Text Near Point | |
65 | |
66 Many functions are provided to look at the characters around point. | |
67 Several simple functions are described here. See also @code{looking-at} | |
68 in @ref{Regexp Search}. | |
69 | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
70 @defun char-after &optional position |
6558 | 71 This function returns the character in the current buffer at (i.e., |
72 immediately after) position @var{position}. If @var{position} is out of | |
73 range for this purpose, either before the beginning of the buffer, or at | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
74 or beyond the end, then the value is @code{nil}. The default for |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
75 @var{position} is point. |
6558 | 76 |
77 In the following example, assume that the first character in the | |
78 buffer is @samp{@@}: | |
79 | |
80 @example | |
81 @group | |
82 (char-to-string (char-after 1)) | |
83 @result{} "@@" | |
84 @end group | |
85 @end example | |
86 @end defun | |
87 | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
88 @defun char-before &optional position |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
89 This function returns the character in the current buffer immediately |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
90 before position @var{position}. If @var{position} is out of range for |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
91 this purpose, either before the beginning of the buffer, or at or beyond |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
92 the end, then the value is @code{nil}. The default for |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
93 @var{position} is point. |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
94 @end defun |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
95 |
6558 | 96 @defun following-char |
97 This function returns the character following point in the current | |
98 buffer. This is similar to @code{(char-after (point))}. However, if | |
99 point is at the end of the buffer, then @code{following-char} returns 0. | |
100 | |
101 Remember that point is always between characters, and the terminal | |
102 cursor normally appears over the character following point. Therefore, | |
103 the character returned by @code{following-char} is the character the | |
104 cursor is over. | |
105 | |
106 In this example, point is between the @samp{a} and the @samp{c}. | |
107 | |
108 @example | |
109 @group | |
110 ---------- Buffer: foo ---------- | |
111 Gentlemen may cry ``Pea@point{}ce! Peace!,'' | |
112 but there is no peace. | |
113 ---------- Buffer: foo ---------- | |
114 @end group | |
115 | |
116 @group | |
117 (char-to-string (preceding-char)) | |
118 @result{} "a" | |
119 (char-to-string (following-char)) | |
120 @result{} "c" | |
121 @end group | |
122 @end example | |
123 @end defun | |
124 | |
125 @defun preceding-char | |
126 This function returns the character preceding point in the current | |
127 buffer. See above, under @code{following-char}, for an example. If | |
128 point is at the beginning of the buffer, @code{preceding-char} returns | |
129 0. | |
130 @end defun | |
131 | |
132 @defun bobp | |
133 This function returns @code{t} if point is at the beginning of the | |
134 buffer. If narrowing is in effect, this means the beginning of the | |
135 accessible portion of the text. See also @code{point-min} in | |
136 @ref{Point}. | |
137 @end defun | |
138 | |
139 @defun eobp | |
140 This function returns @code{t} if point is at the end of the buffer. | |
141 If narrowing is in effect, this means the end of accessible portion of | |
142 the text. See also @code{point-max} in @xref{Point}. | |
143 @end defun | |
144 | |
145 @defun bolp | |
146 This function returns @code{t} if point is at the beginning of a line. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
147 @xref{Text Lines}. The beginning of the buffer (or of its accessible |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
148 portion) always counts as the beginning of a line. |
6558 | 149 @end defun |
150 | |
151 @defun eolp | |
152 This function returns @code{t} if point is at the end of a line. The | |
153 end of the buffer (or of its accessible portion) is always considered | |
154 the end of a line. | |
155 @end defun | |
156 | |
157 @node Buffer Contents | |
158 @section Examining Buffer Contents | |
159 | |
160 This section describes two functions that allow a Lisp program to | |
161 convert any portion of the text in the buffer into a string. | |
162 | |
163 @defun buffer-substring start end | |
164 This function returns a string containing a copy of the text of the | |
165 region defined by positions @var{start} and @var{end} in the current | |
166 buffer. If the arguments are not positions in the accessible portion of | |
167 the buffer, @code{buffer-substring} signals an @code{args-out-of-range} | |
168 error. | |
169 | |
170 It is not necessary for @var{start} to be less than @var{end}; the | |
171 arguments can be given in either order. But most often the smaller | |
172 argument is written first. | |
173 | |
12067 | 174 If the text being copied has any text properties, these are copied into |
175 the string along with the characters they belong to. @xref{Text | |
176 Properties}. However, overlays (@pxref{Overlays}) in the buffer and | |
177 their properties are ignored, not copied. | |
178 | |
6558 | 179 @example |
180 @group | |
181 ---------- Buffer: foo ---------- | |
182 This is the contents of buffer foo | |
183 | |
184 ---------- Buffer: foo ---------- | |
185 @end group | |
186 | |
187 @group | |
188 (buffer-substring 1 10) | |
189 @result{} "This is t" | |
190 @end group | |
191 @group | |
192 (buffer-substring (point-max) 10) | |
193 @result{} "he contents of buffer foo | |
194 " | |
195 @end group | |
196 @end example | |
197 @end defun | |
198 | |
13109
acb0ab49f4e7
Fix name of buffer-substring-no-properties.
Richard M. Stallman <rms@gnu.org>
parents:
12775
diff
changeset
|
199 @defun buffer-substring-no-properties start end |
12067 | 200 This is like @code{buffer-substring}, except that it does not copy text |
201 properties, just the characters themselves. @xref{Text Properties}. | |
202 @end defun | |
203 | |
6558 | 204 @defun buffer-string |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
205 This function returns the contents of the entire accessible portion of |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
206 the current buffer as a string. It is equivalent to |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
207 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
208 @example |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
209 (buffer-substring (point-min) (point-max)) |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
210 @end example |
6558 | 211 |
212 @example | |
213 @group | |
214 ---------- Buffer: foo ---------- | |
215 This is the contents of buffer foo | |
216 | |
217 ---------- Buffer: foo ---------- | |
218 | |
219 (buffer-string) | |
220 @result{} "This is the contents of buffer foo | |
221 " | |
222 @end group | |
223 @end example | |
224 @end defun | |
225 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
226 @defun thing-at-point thing |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
227 Return the @var{thing} around or next to point, as a string. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
228 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
229 The argument @var{thing} is a symbol which specifies a kind of syntactic |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
230 entity. Possibilities include @code{symbol}, @code{list}, @code{sexp}, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
231 @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence}, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
232 @code{whitespace}, @code{line}, @code{page}, and others. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
233 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
234 @example |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
235 ---------- Buffer: foo ---------- |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
236 Gentlemen may cry ``Pea@point{}ce! Peace!,'' |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
237 but there is no peace. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
238 ---------- Buffer: foo ---------- |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
239 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
240 (thing-at-point 'word) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
241 @result{} "Peace" |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
242 (thing-at-point 'line) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
243 @result{} "Gentlemen may cry ``Peace! Peace!,''\n" |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
244 (thing-at-point 'whitespace) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
245 @result{} nil |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
246 @end example |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
247 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
248 |
6558 | 249 @node Comparing Text |
250 @section Comparing Text | |
251 @cindex comparing buffer text | |
252 | |
253 This function lets you compare portions of the text in a buffer, without | |
254 copying them into strings first. | |
255 | |
256 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2 | |
257 This function lets you compare two substrings of the same buffer or two | |
258 different buffers. The first three arguments specify one substring, | |
259 giving a buffer and two positions within the buffer. The last three | |
260 arguments specify the other substring in the same way. You can use | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
261 @code{nil} for @var{buffer1}, @var{buffer2}, or both to stand for the |
6558 | 262 current buffer. |
263 | |
264 The value is negative if the first substring is less, positive if the | |
265 first is greater, and zero if they are equal. The absolute value of | |
266 the result is one plus the index of the first differing characters | |
267 within the substrings. | |
268 | |
269 This function ignores case when comparing characters | |
12098 | 270 if @code{case-fold-search} is non-@code{nil}. It always ignores |
271 text properties. | |
6558 | 272 |
273 Suppose the current buffer contains the text @samp{foobarbar | |
274 haha!rara!}; then in this example the two substrings are @samp{rbar } | |
275 and @samp{rara!}. The value is 2 because the first substring is greater | |
276 at the second character. | |
277 | |
278 @example | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
279 (compare-buffer-substrings nil 6 11 nil 16 21) |
6558 | 280 @result{} 2 |
281 @end example | |
282 @end defun | |
283 | |
284 @node Insertion | |
12098 | 285 @section Inserting Text |
6558 | 286 @cindex insertion of text |
287 @cindex text insertion | |
288 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
289 @cindex insertion before point |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
290 @cindex before point, insertion |
6558 | 291 @dfn{Insertion} means adding new text to a buffer. The inserted text |
292 goes at point---between the character before point and the character | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
293 after point. Some insertion functions leave point before the inserted |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
294 text, while other functions leave it after. We call the former |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
295 insertion @dfn{after point} and the latter insertion @dfn{before point}. |
6558 | 296 |
297 Insertion relocates markers that point at positions after the | |
298 insertion point, so that they stay with the surrounding text | |
299 (@pxref{Markers}). When a marker points at the place of insertion, | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
300 insertion may or may not relocate the marker, depending on the marker's |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
301 insertion type (@pxref{Marker Insertion Types}). Certain special |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
302 functions such as @code{insert-before-markers} relocate all such markers |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
303 to point after the inserted text, regardless of the markers' insertion |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
304 type. |
6558 | 305 |
306 Insertion functions signal an error if the current buffer is | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
307 read-only or if they insert within read-only text. |
6558 | 308 |
12098 | 309 These functions copy text characters from strings and buffers along |
310 with their properties. The inserted characters have exactly the same | |
311 properties as the characters they were copied from. By contrast, | |
312 characters specified as separate arguments, not part of a string or | |
313 buffer, inherit their text properties from the neighboring text. | |
314 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
315 The insertion functions convert text from unibyte to multibyte in |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
316 order to insert in a multibyte buffer, and vice versa---if the text |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
317 comes from a string or from a buffer. However, they do not convert |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
318 unibyte character codes 128 through 255 to multibyte characters, not |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
319 even if the current buffer is a multibyte buffer. @xref{Converting |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
320 Representations}. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
321 |
6558 | 322 @defun insert &rest args |
323 This function inserts the strings and/or characters @var{args} into the | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
324 current buffer, at point, moving point forward. In other words, it |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
325 inserts the text before point. An error is signaled unless all |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
326 @var{args} are either strings or characters. The value is @code{nil}. |
6558 | 327 @end defun |
328 | |
329 @defun insert-before-markers &rest args | |
330 This function inserts the strings and/or characters @var{args} into the | |
331 current buffer, at point, moving point forward. An error is signaled | |
332 unless all @var{args} are either strings or characters. The value is | |
333 @code{nil}. | |
334 | |
335 This function is unlike the other insertion functions in that it | |
336 relocates markers initially pointing at the insertion point, to point | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
337 after the inserted text. If an overlay begins the insertion point, the |
16934
853f638bbc81
Document how insert-before-markers affects overlays.
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
338 inserted text falls outside the overlay; if a nonempty overlay ends at |
853f638bbc81
Document how insert-before-markers affects overlays.
Richard M. Stallman <rms@gnu.org>
parents:
16736
diff
changeset
|
339 the insertion point, the inserted text falls inside that overlay. |
6558 | 340 @end defun |
341 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
342 @defun insert-char character &optional count inherit |
6558 | 343 This function inserts @var{count} instances of @var{character} into the |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
344 current buffer before point. The argument @var{count} should be a |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
345 number (@code{nil} means 1), and @var{character} must be a character. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
346 The value is @code{nil}. |
8644 | 347 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
348 This function does not convert unibyte character codes 128 through 255 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
349 to multibyte characters, not even if the current buffer is a multibyte |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
350 buffer. @xref{Converting Representations}. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
351 |
8644 | 352 If @var{inherit} is non-@code{nil}, then the inserted characters inherit |
353 sticky text properties from the two characters before and after the | |
354 insertion point. @xref{Sticky Properties}. | |
6558 | 355 @end defun |
356 | |
357 @defun insert-buffer-substring from-buffer-or-name &optional start end | |
358 This function inserts a portion of buffer @var{from-buffer-or-name} | |
359 (which must already exist) into the current buffer before point. The | |
360 text inserted is the region from @var{start} and @var{end}. (These | |
361 arguments default to the beginning and end of the accessible portion of | |
362 that buffer.) This function returns @code{nil}. | |
363 | |
364 In this example, the form is executed with buffer @samp{bar} as the | |
365 current buffer. We assume that buffer @samp{bar} is initially empty. | |
366 | |
367 @example | |
368 @group | |
369 ---------- Buffer: foo ---------- | |
370 We hold these truths to be self-evident, that all | |
371 ---------- Buffer: foo ---------- | |
372 @end group | |
373 | |
374 @group | |
375 (insert-buffer-substring "foo" 1 20) | |
376 @result{} nil | |
377 | |
378 ---------- Buffer: bar ---------- | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
379 We hold these truth@point{} |
6558 | 380 ---------- Buffer: bar ---------- |
381 @end group | |
382 @end example | |
383 @end defun | |
384 | |
385 @xref{Sticky Properties}, for other insertion functions that inherit | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
386 text properties from the nearby text in addition to inserting it. |
8644 | 387 Whitespace inserted by indentation functions also inherits text |
388 properties. | |
6558 | 389 |
390 @node Commands for Insertion | |
391 @section User-Level Insertion Commands | |
392 | |
393 This section describes higher-level commands for inserting text, | |
394 commands intended primarily for the user but useful also in Lisp | |
395 programs. | |
396 | |
397 @deffn Command insert-buffer from-buffer-or-name | |
398 This command inserts the entire contents of @var{from-buffer-or-name} | |
399 (which must exist) into the current buffer after point. It leaves | |
400 the mark after the inserted text. The value is @code{nil}. | |
401 @end deffn | |
402 | |
403 @deffn Command self-insert-command count | |
404 @cindex character insertion | |
405 @cindex self-insertion | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
406 This command inserts the last character typed; it does so @var{count} |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
407 times, before point, and returns @code{nil}. Most printing characters |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
408 are bound to this command. In routine use, @code{self-insert-command} |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
409 is the most frequently called function in Emacs, but programs rarely use |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
410 it except to install it on a keymap. |
6558 | 411 |
412 In an interactive call, @var{count} is the numeric prefix argument. | |
413 | |
12067 | 414 This command calls @code{auto-fill-function} whenever that is |
415 non-@code{nil} and the character inserted is a space or a newline | |
416 (@pxref{Auto Filling}). | |
6558 | 417 |
418 @c Cross refs reworded to prevent overfull hbox. --rjc 15mar92 | |
12067 | 419 This command performs abbrev expansion if Abbrev mode is enabled and |
6558 | 420 the inserted character does not have word-constituent |
421 syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) | |
422 | |
12067 | 423 This is also responsible for calling @code{blink-paren-function} when |
424 the inserted character has close parenthesis syntax (@pxref{Blinking}). | |
25875 | 425 |
426 Do not try substituting your own definition of | |
427 @code{self-insert-command} for the standard one. The editor command | |
428 loop handles this function specially. | |
6558 | 429 @end deffn |
430 | |
431 @deffn Command newline &optional number-of-newlines | |
432 This command inserts newlines into the current buffer before point. | |
433 If @var{number-of-newlines} is supplied, that many newline characters | |
434 are inserted. | |
435 | |
436 @cindex newline and Auto Fill mode | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
437 This function calls @code{auto-fill-function} if the current column |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
438 number is greater than the value of @code{fill-column} and |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
439 @var{number-of-newlines} is @code{nil}. Typically what |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
440 @code{auto-fill-function} does is insert a newline; thus, the overall |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
441 result in this case is to insert two newlines at different places: one |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
442 at point, and another earlier in the line. @code{newline} does not |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
443 auto-fill if @var{number-of-newlines} is non-@code{nil}. |
6558 | 444 |
12098 | 445 This command indents to the left margin if that is not zero. |
446 @xref{Margins}. | |
447 | |
6558 | 448 The value returned is @code{nil}. In an interactive call, @var{count} |
449 is the numeric prefix argument. | |
450 @end deffn | |
451 | |
452 @deffn Command split-line | |
453 This command splits the current line, moving the portion of the line | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
454 after point down vertically so that it is on the next line directly |
6558 | 455 below where it was before. Whitespace is inserted as needed at the |
456 beginning of the lower line, using the @code{indent-to} function. | |
457 @code{split-line} returns the position of point. | |
458 | |
459 Programs hardly ever use this function. | |
460 @end deffn | |
461 | |
462 @defvar overwrite-mode | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
463 This variable controls whether overwrite mode is in effect. The value |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
464 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary}, |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
465 or @code{nil}. @code{overwrite-mode-textual} specifies textual |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
466 overwrite mode (treats newlines and tabs specially), and |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
467 @code{overwrite-mode-binary} specifies binary overwrite mode (treats |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
468 newlines and tabs like any other characters). |
6558 | 469 @end defvar |
470 | |
471 @node Deletion | |
12098 | 472 @section Deleting Text |
6558 | 473 |
474 @cindex deletion vs killing | |
475 Deletion means removing part of the text in a buffer, without saving | |
476 it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be | |
477 yanked, but can be reinserted using the undo mechanism (@pxref{Undo}). | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
478 Some deletion functions do save text in the kill ring in some special |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
479 cases. |
6558 | 480 |
481 All of the deletion functions operate on the current buffer, and all | |
482 return a value of @code{nil}. | |
483 | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
484 @deffn Command erase-buffer |
6558 | 485 This function deletes the entire text of the current buffer, leaving it |
486 empty. If the buffer is read-only, it signals a @code{buffer-read-only} | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
487 error; if some of the text in it is read-only, it signals a |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
488 @code{text-read-only} error. Otherwise, it deletes the text without |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
489 asking for any confirmation. It returns @code{nil}. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
490 |
6558 | 491 Normally, deleting a large amount of text from a buffer inhibits further |
492 auto-saving of that buffer ``because it has shrunk''. However, | |
493 @code{erase-buffer} does not do this, the idea being that the future | |
494 text is not really related to the former text, and its size should not | |
495 be compared with that of the former text. | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
496 @end deffn |
6558 | 497 |
498 @deffn Command delete-region start end | |
27654
cabb1b4c4424
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27374
diff
changeset
|
499 This command deletes the text between positions @var{start} and |
cabb1b4c4424
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27374
diff
changeset
|
500 @var{end} in the current buffer, and returns @code{nil}. If point was |
cabb1b4c4424
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27374
diff
changeset
|
501 inside the deleted region, its value afterward is @var{start}. |
12775
a8cd9be43025
Explain how delete-region alters point.
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
502 Otherwise, point relocates with the surrounding text, as markers do. |
6558 | 503 @end deffn |
504 | |
27654
cabb1b4c4424
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27374
diff
changeset
|
505 @defun delete-and-extract-region start end |
cabb1b4c4424
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27374
diff
changeset
|
506 @tindex delete-and-extract-region |
cabb1b4c4424
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27374
diff
changeset
|
507 This function deletes the text between positions @var{start} and |
cabb1b4c4424
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27374
diff
changeset
|
508 @var{end} in the current buffer, and returns a string containing the |
cabb1b4c4424
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27374
diff
changeset
|
509 text just deleted. |
cabb1b4c4424
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27374
diff
changeset
|
510 |
cabb1b4c4424
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27374
diff
changeset
|
511 If point was inside the deleted region, its value afterward is |
cabb1b4c4424
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27374
diff
changeset
|
512 @var{start}. Otherwise, point relocates with the surrounding text, as |
cabb1b4c4424
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27374
diff
changeset
|
513 markers do. |
cabb1b4c4424
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27374
diff
changeset
|
514 @end defun |
cabb1b4c4424
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27374
diff
changeset
|
515 |
6558 | 516 @deffn Command delete-char count &optional killp |
517 This command deletes @var{count} characters directly after point, or | |
518 before point if @var{count} is negative. If @var{killp} is | |
519 non-@code{nil}, then it saves the deleted characters in the kill ring. | |
520 | |
521 In an interactive call, @var{count} is the numeric prefix argument, and | |
522 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix | |
523 argument is supplied, the text is saved in the kill ring. If no prefix | |
524 argument is supplied, then one character is deleted, but not saved in | |
525 the kill ring. | |
526 | |
527 The value returned is always @code{nil}. | |
528 @end deffn | |
529 | |
530 @deffn Command delete-backward-char count &optional killp | |
531 @cindex delete previous char | |
532 This command deletes @var{count} characters directly before point, or | |
533 after point if @var{count} is negative. If @var{killp} is | |
534 non-@code{nil}, then it saves the deleted characters in the kill ring. | |
535 | |
536 In an interactive call, @var{count} is the numeric prefix argument, and | |
537 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix | |
538 argument is supplied, the text is saved in the kill ring. If no prefix | |
539 argument is supplied, then one character is deleted, but not saved in | |
540 the kill ring. | |
541 | |
542 The value returned is always @code{nil}. | |
543 @end deffn | |
544 | |
545 @deffn Command backward-delete-char-untabify count &optional killp | |
546 @cindex tab deletion | |
547 This command deletes @var{count} characters backward, changing tabs | |
548 into spaces. When the next character to be deleted is a tab, it is | |
549 first replaced with the proper number of spaces to preserve alignment | |
550 and then one of those spaces is deleted instead of the tab. If | |
551 @var{killp} is non-@code{nil}, then the command saves the deleted | |
552 characters in the kill ring. | |
553 | |
554 Conversion of tabs to spaces happens only if @var{count} is positive. | |
555 If it is negative, exactly @minus{}@var{count} characters after point | |
556 are deleted. | |
557 | |
558 In an interactive call, @var{count} is the numeric prefix argument, and | |
559 @var{killp} is the unprocessed prefix argument. Therefore, if a prefix | |
560 argument is supplied, the text is saved in the kill ring. If no prefix | |
561 argument is supplied, then one character is deleted, but not saved in | |
562 the kill ring. | |
563 | |
564 The value returned is always @code{nil}. | |
565 @end deffn | |
566 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
567 @defopt backward-delete-char-untabify-method |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
568 This option specifies how @code{backward-delete-char-untabify} should |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
569 deal with whitespace. Possible values include @code{untabify}, the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
570 default, meaning convert a tab to many spaces and delete one; |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
571 @code{hungry}, meaning delete all the whitespace characters before point |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
572 with one command, and @code{nil}, meaning do nothing special for |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
573 whitespace characters. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
574 @end defopt |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
575 |
6558 | 576 @node User-Level Deletion |
577 @section User-Level Deletion Commands | |
578 | |
579 This section describes higher-level commands for deleting text, | |
580 commands intended primarily for the user but useful also in Lisp | |
581 programs. | |
582 | |
583 @deffn Command delete-horizontal-space | |
584 @cindex deleting whitespace | |
585 This function deletes all spaces and tabs around point. It returns | |
586 @code{nil}. | |
587 | |
588 In the following examples, we call @code{delete-horizontal-space} four | |
589 times, once on each line, with point between the second and third | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
590 characters on the line each time. |
6558 | 591 |
592 @example | |
593 @group | |
594 ---------- Buffer: foo ---------- | |
595 I @point{}thought | |
596 I @point{} thought | |
597 We@point{} thought | |
598 Yo@point{}u thought | |
599 ---------- Buffer: foo ---------- | |
600 @end group | |
601 | |
602 @group | |
603 (delete-horizontal-space) ; @r{Four times.} | |
604 @result{} nil | |
605 | |
606 ---------- Buffer: foo ---------- | |
607 Ithought | |
608 Ithought | |
609 Wethought | |
610 You thought | |
611 ---------- Buffer: foo ---------- | |
612 @end group | |
613 @end example | |
614 @end deffn | |
615 | |
616 @deffn Command delete-indentation &optional join-following-p | |
617 This function joins the line point is on to the previous line, deleting | |
618 any whitespace at the join and in some cases replacing it with one | |
619 space. If @var{join-following-p} is non-@code{nil}, | |
620 @code{delete-indentation} joins this line to the following line | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
621 instead. The function returns @code{nil}. |
6558 | 622 |
623 If there is a fill prefix, and the second of the lines being joined | |
624 starts with the prefix, then @code{delete-indentation} deletes the | |
12098 | 625 fill prefix before joining the lines. @xref{Margins}. |
6558 | 626 |
627 In the example below, point is located on the line starting | |
628 @samp{events}, and it makes no difference if there are trailing spaces | |
629 in the preceding line. | |
630 | |
631 @smallexample | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
632 @group |
6558 | 633 ---------- Buffer: foo ---------- |
634 When in the course of human | |
635 @point{} events, it becomes necessary | |
636 ---------- Buffer: foo ---------- | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
637 @end group |
6558 | 638 |
639 (delete-indentation) | |
640 @result{} nil | |
641 | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
642 @group |
6558 | 643 ---------- Buffer: foo ---------- |
644 When in the course of human@point{} events, it becomes necessary | |
645 ---------- Buffer: foo ---------- | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
646 @end group |
6558 | 647 @end smallexample |
648 | |
649 After the lines are joined, the function @code{fixup-whitespace} is | |
650 responsible for deciding whether to leave a space at the junction. | |
651 @end deffn | |
652 | |
653 @defun fixup-whitespace | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
654 This function replaces all the whitespace surrounding point with either |
6558 | 655 one space or no space, according to the context. It returns @code{nil}. |
656 | |
657 At the beginning or end of a line, the appropriate amount of space is | |
658 none. Before a character with close parenthesis syntax, or after a | |
659 character with open parenthesis or expression-prefix syntax, no space is | |
660 also appropriate. Otherwise, one space is appropriate. @xref{Syntax | |
661 Class Table}. | |
662 | |
663 In the example below, @code{fixup-whitespace} is called the first time | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
664 with point before the word @samp{spaces} in the first line. For the |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
665 second invocation, point is directly after the @samp{(}. |
6558 | 666 |
667 @smallexample | |
668 @group | |
669 ---------- Buffer: foo ---------- | |
670 This has too many @point{}spaces | |
671 This has too many spaces at the start of (@point{} this list) | |
672 ---------- Buffer: foo ---------- | |
673 @end group | |
674 | |
675 @group | |
676 (fixup-whitespace) | |
677 @result{} nil | |
678 (fixup-whitespace) | |
679 @result{} nil | |
680 @end group | |
681 | |
682 @group | |
683 ---------- Buffer: foo ---------- | |
684 This has too many spaces | |
685 This has too many spaces at the start of (this list) | |
686 ---------- Buffer: foo ---------- | |
687 @end group | |
688 @end smallexample | |
689 @end defun | |
690 | |
691 @deffn Command just-one-space | |
692 @comment !!SourceFile simple.el | |
693 This command replaces any spaces and tabs around point with a single | |
694 space. It returns @code{nil}. | |
695 @end deffn | |
696 | |
697 @deffn Command delete-blank-lines | |
698 This function deletes blank lines surrounding point. If point is on a | |
699 blank line with one or more blank lines before or after it, then all but | |
700 one of them are deleted. If point is on an isolated blank line, then it | |
701 is deleted. If point is on a nonblank line, the command deletes all | |
702 blank lines following it. | |
703 | |
704 A blank line is defined as a line containing only tabs and spaces. | |
705 | |
706 @code{delete-blank-lines} returns @code{nil}. | |
707 @end deffn | |
708 | |
709 @node The Kill Ring | |
710 @section The Kill Ring | |
711 @cindex kill ring | |
712 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
713 @dfn{Kill functions} delete text like the deletion functions, but save |
6558 | 714 it so that the user can reinsert it by @dfn{yanking}. Most of these |
715 functions have @samp{kill-} in their name. By contrast, the functions | |
716 whose names start with @samp{delete-} normally do not save text for | |
717 yanking (though they can still be undone); these are ``deletion'' | |
718 functions. | |
719 | |
720 Most of the kill commands are primarily for interactive use, and are | |
721 not described here. What we do describe are the functions provided for | |
722 use in writing such commands. You can use these functions to write | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
723 commands for killing text. When you need to delete text for internal |
6558 | 724 purposes within a Lisp function, you should normally use deletion |
725 functions, so as not to disturb the kill ring contents. | |
726 @xref{Deletion}. | |
727 | |
728 Killed text is saved for later yanking in the @dfn{kill ring}. This | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
729 is a list that holds a number of recent kills, not just the last text |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
730 kill. We call this a ``ring'' because yanking treats it as having |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
731 elements in a cyclic order. The list is kept in the variable |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
732 @code{kill-ring}, and can be operated on with the usual functions for |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
733 lists; there are also specialized functions, described in this section, |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
734 that treat it as a ring. |
6558 | 735 |
736 Some people think this use of the word ``kill'' is unfortunate, since | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
737 it refers to operations that specifically @emph{do not} destroy the |
6558 | 738 entities ``killed''. This is in sharp contrast to ordinary life, in |
739 which death is permanent and ``killed'' entities do not come back to | |
740 life. Therefore, other metaphors have been proposed. For example, the | |
741 term ``cut ring'' makes sense to people who, in pre-computer days, used | |
742 scissors and paste to cut up and rearrange manuscripts. However, it | |
743 would be difficult to change the terminology now. | |
744 | |
745 @menu | |
746 * Kill Ring Concepts:: What text looks like in the kill ring. | |
747 * Kill Functions:: Functions that kill text. | |
748 * Yank Commands:: Commands that access the kill ring. | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
749 * Low-Level Kill Ring:: Functions and variables for kill ring access. |
6558 | 750 * Internals of Kill Ring:: Variables that hold kill-ring data. |
751 @end menu | |
752 | |
753 @node Kill Ring Concepts | |
754 @comment node-name, next, previous, up | |
755 @subsection Kill Ring Concepts | |
756 | |
757 The kill ring records killed text as strings in a list, most recent | |
758 first. A short kill ring, for example, might look like this: | |
759 | |
760 @example | |
761 ("some text" "a different piece of text" "even older text") | |
762 @end example | |
763 | |
764 @noindent | |
765 When the list reaches @code{kill-ring-max} entries in length, adding a | |
766 new entry automatically deletes the last entry. | |
767 | |
768 When kill commands are interwoven with other commands, each kill | |
769 command makes a new entry in the kill ring. Multiple kill commands in | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
770 succession build up a single kill-ring entry, which would be yanked as a |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
771 unit; the second and subsequent consecutive kill commands add text to |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
772 the entry made by the first one. |
6558 | 773 |
774 For yanking, one entry in the kill ring is designated the ``front'' of | |
775 the ring. Some yank commands ``rotate'' the ring by designating a | |
776 different element as the ``front.'' But this virtual rotation doesn't | |
777 change the list itself---the most recent entry always comes first in the | |
778 list. | |
779 | |
780 @node Kill Functions | |
781 @comment node-name, next, previous, up | |
782 @subsection Functions for Killing | |
783 | |
784 @code{kill-region} is the usual subroutine for killing text. Any | |
785 command that calls this function is a ``kill command'' (and should | |
786 probably have @samp{kill} in its name). @code{kill-region} puts the | |
787 newly killed text in a new element at the beginning of the kill ring or | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
788 adds it to the most recent element. It determines automatically (using |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
789 @code{last-command}) whether the previous command was a kill command, |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
790 and if so appends the killed text to the most recent entry. |
6558 | 791 |
792 @deffn Command kill-region start end | |
793 This function kills the text in the region defined by @var{start} and | |
12098 | 794 @var{end}. The text is deleted but saved in the kill ring, along with |
795 its text properties. The value is always @code{nil}. | |
6558 | 796 |
797 In an interactive call, @var{start} and @var{end} are point and | |
798 the mark. | |
799 | |
800 @c Emacs 19 feature | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
801 If the buffer or text is read-only, @code{kill-region} modifies the kill |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
802 ring just the same, then signals an error without modifying the buffer. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
803 This is convenient because it lets the user use a series of kill |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
804 commands to copy text from a read-only buffer into the kill ring. |
6558 | 805 @end deffn |
806 | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
807 @defopt kill-read-only-ok |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
808 If this option is non-@code{nil}, @code{kill-region} does not signal an |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
809 error if the buffer or text is read-only. Instead, it simply returns, |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
810 updating the kill ring but not changing the buffer. |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
811 @end defopt |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
812 |
6558 | 813 @deffn Command copy-region-as-kill start end |
814 This command saves the region defined by @var{start} and @var{end} on | |
12098 | 815 the kill ring (including text properties), but does not delete the text |
816 from the buffer. It returns @code{nil}. It also indicates the extent | |
817 of the text copied by moving the cursor momentarily, or by displaying a | |
818 message in the echo area. | |
6558 | 819 |
12067 | 820 The command does not set @code{this-command} to @code{kill-region}, so a |
821 subsequent kill command does not append to the same kill ring entry. | |
822 | |
6558 | 823 Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
824 support Emacs 18. For newer Emacs versions, it is better to use |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
825 @code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
826 Ring}. |
6558 | 827 @end deffn |
828 | |
829 @node Yank Commands | |
830 @comment node-name, next, previous, up | |
831 @subsection Functions for Yanking | |
832 | |
833 @dfn{Yanking} means reinserting an entry of previously killed text | |
12098 | 834 from the kill ring. The text properties are copied too. |
6558 | 835 |
836 @deffn Command yank &optional arg | |
837 @cindex inserting killed text | |
838 This command inserts before point the text in the first entry in the | |
839 kill ring. It positions the mark at the beginning of that text, and | |
840 point at the end. | |
841 | |
842 If @var{arg} is a list (which occurs interactively when the user | |
843 types @kbd{C-u} with no digits), then @code{yank} inserts the text as | |
844 described above, but puts point before the yanked text and puts the mark | |
845 after it. | |
846 | |
847 If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most | |
848 recently killed text---the @var{arg}th element of the kill ring list. | |
849 | |
850 @code{yank} does not alter the contents of the kill ring or rotate it. | |
851 It returns @code{nil}. | |
852 @end deffn | |
853 | |
854 @deffn Command yank-pop arg | |
855 This command replaces the just-yanked entry from the kill ring with a | |
856 different entry from the kill ring. | |
857 | |
858 This is allowed only immediately after a @code{yank} or another | |
859 @code{yank-pop}. At such a time, the region contains text that was just | |
860 inserted by yanking. @code{yank-pop} deletes that text and inserts in | |
861 its place a different piece of killed text. It does not add the deleted | |
862 text to the kill ring, since it is already in the kill ring somewhere. | |
863 | |
864 If @var{arg} is @code{nil}, then the replacement text is the previous | |
865 element of the kill ring. If @var{arg} is numeric, the replacement is | |
866 the @var{arg}th previous kill. If @var{arg} is negative, a more recent | |
867 kill is the replacement. | |
868 | |
869 The sequence of kills in the kill ring wraps around, so that after the | |
870 oldest one comes the newest one, and before the newest one goes the | |
871 oldest. | |
872 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
873 The return value is always @code{nil}. |
6558 | 874 @end deffn |
875 | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
876 @node Low-Level Kill Ring |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
877 @subsection Low-Level Kill Ring |
6558 | 878 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
879 These functions and variables provide access to the kill ring at a |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
880 lower level, but still convenient for use in Lisp programs, because they |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
881 take care of interaction with window system selections |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
882 (@pxref{Window System Selections}). |
6558 | 883 |
884 @defun current-kill n &optional do-not-move | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
885 The function @code{current-kill} rotates the yanking pointer, which |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
886 designates the ``front'' of the kill ring, by @var{n} places (from newer |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
887 kills to older ones), and returns the text at that place in the ring. |
6558 | 888 |
889 If the optional second argument @var{do-not-move} is non-@code{nil}, | |
890 then @code{current-kill} doesn't alter the yanking pointer; it just | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
891 returns the @var{n}th kill, counting from the current yanking pointer. |
6558 | 892 |
893 If @var{n} is zero, indicating a request for the latest kill, | |
894 @code{current-kill} calls the value of | |
895 @code{interprogram-paste-function} (documented below) before consulting | |
896 the kill ring. | |
897 @end defun | |
898 | |
899 @defun kill-new string | |
900 This function puts the text @var{string} into the kill ring as a new | |
901 entry at the front of the ring. It discards the oldest entry if | |
902 appropriate. It also invokes the value of | |
903 @code{interprogram-cut-function} (see below). | |
904 @end defun | |
905 | |
906 @defun kill-append string before-p | |
907 This function appends the text @var{string} to the first entry in the | |
908 kill ring. Normally @var{string} goes at the end of the entry, but if | |
909 @var{before-p} is non-@code{nil}, it goes at the beginning. This | |
910 function also invokes the value of @code{interprogram-cut-function} (see | |
911 below). | |
912 @end defun | |
913 | |
914 @defvar interprogram-paste-function | |
915 This variable provides a way of transferring killed text from other | |
916 programs, when you are using a window system. Its value should be | |
917 @code{nil} or a function of no arguments. | |
918 | |
919 If the value is a function, @code{current-kill} calls it to get the | |
920 ``most recent kill''. If the function returns a non-@code{nil} value, | |
921 then that value is used as the ``most recent kill''. If it returns | |
922 @code{nil}, then the first element of @code{kill-ring} is used. | |
923 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
924 The normal use of this hook is to get the window system's primary |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
925 selection as the most recent kill, even if the selection belongs to |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
926 another application. @xref{Window System Selections}. |
6558 | 927 @end defvar |
928 | |
929 @defvar interprogram-cut-function | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
930 This variable provides a way of communicating killed text to other |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
931 programs, when you are using a window system. Its value should be |
6558 | 932 @code{nil} or a function of one argument. |
933 | |
934 If the value is a function, @code{kill-new} and @code{kill-append} call | |
935 it with the new first element of the kill ring as an argument. | |
936 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
937 The normal use of this hook is to set the window system's primary |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
938 selection from the newly killed text. @xref{Window System Selections}. |
6558 | 939 @end defvar |
940 | |
941 @node Internals of Kill Ring | |
942 @comment node-name, next, previous, up | |
943 @subsection Internals of the Kill Ring | |
944 | |
945 The variable @code{kill-ring} holds the kill ring contents, in the | |
946 form of a list of strings. The most recent kill is always at the front | |
947 of the list. | |
948 | |
949 The @code{kill-ring-yank-pointer} variable points to a link in the | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
950 kill ring list, whose @sc{car} is the text to yank next. We say it |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
951 identifies the ``front'' of the ring. Moving |
6558 | 952 @code{kill-ring-yank-pointer} to a different link is called |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
953 @dfn{rotating the kill ring}. We call the kill ring a ``ring'' because |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
954 the functions that move the yank pointer wrap around from the end of the |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
955 list to the beginning, or vice-versa. Rotation of the kill ring is |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
956 virtual; it does not change the value of @code{kill-ring}. |
6558 | 957 |
958 Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp | |
959 variables whose values are normally lists. The word ``pointer'' in the | |
960 name of the @code{kill-ring-yank-pointer} indicates that the variable's | |
961 purpose is to identify one element of the list for use by the next yank | |
962 command. | |
963 | |
964 The value of @code{kill-ring-yank-pointer} is always @code{eq} to one | |
965 of the links in the kill ring list. The element it identifies is the | |
966 @sc{car} of that link. Kill commands, which change the kill ring, also | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
967 set this variable to the value of @code{kill-ring}. The effect is to |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
968 rotate the ring so that the newly killed text is at the front. |
6558 | 969 |
970 Here is a diagram that shows the variable @code{kill-ring-yank-pointer} | |
971 pointing to the second entry in the kill ring @code{("some text" "a | |
972 different piece of text" "yet older text")}. | |
973 | |
974 @example | |
975 @group | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
976 kill-ring ---- kill-ring-yank-pointer |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
977 | | |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
978 | v |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
979 | --- --- --- --- --- --- |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
980 --> | | |------> | | |--> | | |--> nil |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
981 --- --- --- --- --- --- |
6558 | 982 | | | |
983 | | | | |
984 | | -->"yet older text" | |
985 | | | |
986 | --> "a different piece of text" | |
987 | | |
988 --> "some text" | |
989 @end group | |
990 @end example | |
991 | |
992 @noindent | |
993 This state of affairs might occur after @kbd{C-y} (@code{yank}) | |
994 immediately followed by @kbd{M-y} (@code{yank-pop}). | |
995 | |
996 @defvar kill-ring | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
997 This variable holds the list of killed text sequences, most recently |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
998 killed first. |
6558 | 999 @end defvar |
1000 | |
1001 @defvar kill-ring-yank-pointer | |
1002 This variable's value indicates which element of the kill ring is at the | |
1003 ``front'' of the ring for yanking. More precisely, the value is a tail | |
1004 of the value of @code{kill-ring}, and its @sc{car} is the kill string | |
1005 that @kbd{C-y} should yank. | |
1006 @end defvar | |
1007 | |
1008 @defopt kill-ring-max | |
1009 The value of this variable is the maximum length to which the kill | |
1010 ring can grow, before elements are thrown away at the end. The default | |
1011 value for @code{kill-ring-max} is 30. | |
1012 @end defopt | |
1013 | |
1014 @node Undo | |
1015 @comment node-name, next, previous, up | |
1016 @section Undo | |
1017 @cindex redo | |
1018 | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1019 Most buffers have an @dfn{undo list}, which records all changes made |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1020 to the buffer's text so that they can be undone. (The buffers that |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1021 don't have one are usually special-purpose buffers for which Emacs |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1022 assumes that undoing is not useful.) All the primitives that modify the |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1023 text in the buffer automatically add elements to the front of the undo |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1024 list, which is in the variable @code{buffer-undo-list}. |
6558 | 1025 |
1026 @defvar buffer-undo-list | |
1027 This variable's value is the undo list of the current buffer. | |
1028 A value of @code{t} disables the recording of undo information. | |
1029 @end defvar | |
1030 | |
1031 Here are the kinds of elements an undo list can have: | |
1032 | |
1033 @table @code | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1034 @item @var{position} |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1035 This kind of element records a previous value of point; undoing this |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1036 element moves point to @var{position}. Ordinary cursor motion does not |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1037 make any sort of undo record, but deletion operations use these entries |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1038 to record where point was before the command. |
6558 | 1039 |
1040 @item (@var{beg} . @var{end}) | |
1041 This kind of element indicates how to delete text that was inserted. | |
1042 Upon insertion, the text occupied the range @var{beg}--@var{end} in the | |
1043 buffer. | |
1044 | |
10364 | 1045 @item (@var{text} . @var{position}) |
6558 | 1046 This kind of element indicates how to reinsert text that was deleted. |
10364 | 1047 The deleted text itself is the string @var{text}. The place to |
1048 reinsert it is @code{(abs @var{position})}. | |
6558 | 1049 |
1050 @item (t @var{high} . @var{low}) | |
1051 This kind of element indicates that an unmodified buffer became | |
1052 modified. The elements @var{high} and @var{low} are two integers, each | |
1053 recording 16 bits of the visited file's modification time as of when it | |
1054 was previously visited or saved. @code{primitive-undo} uses those | |
1055 values to determine whether to mark the buffer as unmodified once again; | |
1056 it does so only if the file's modification time matches those numbers. | |
1057 | |
1058 @item (nil @var{property} @var{value} @var{beg} . @var{end}) | |
1059 This kind of element records a change in a text property. | |
1060 Here's how you might undo the change: | |
1061 | |
1062 @example | |
1063 (put-text-property @var{beg} @var{end} @var{property} @var{value}) | |
1064 @end example | |
1065 | |
15760
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
1066 @item (@var{marker} . @var{adjustment}) |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
1067 This kind of element records the fact that the marker @var{marker} was |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
1068 relocated due to deletion of surrounding text, and that it moved |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
1069 @var{adjustment} character positions. Undoing this element moves |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
1070 @var{marker} @minus{} @var{adjustment} characters. |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
1071 |
6558 | 1072 @item nil |
1073 This element is a boundary. The elements between two boundaries are | |
1074 called a @dfn{change group}; normally, each change group corresponds to | |
1075 one keyboard command, and undo commands normally undo an entire group as | |
1076 a unit. | |
1077 @end table | |
1078 | |
1079 @defun undo-boundary | |
1080 This function places a boundary element in the undo list. The undo | |
1081 command stops at such a boundary, and successive undo commands undo | |
1082 to earlier and earlier boundaries. This function returns @code{nil}. | |
1083 | |
11555
4cc0a5e1bdac
Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents:
10364
diff
changeset
|
1084 The editor command loop automatically creates an undo boundary before |
4cc0a5e1bdac
Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents:
10364
diff
changeset
|
1085 each key sequence is executed. Thus, each undo normally undoes the |
4cc0a5e1bdac
Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents:
10364
diff
changeset
|
1086 effects of one command. Self-inserting input characters are an |
4cc0a5e1bdac
Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents:
10364
diff
changeset
|
1087 exception. The command loop makes a boundary for the first such |
4cc0a5e1bdac
Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents:
10364
diff
changeset
|
1088 character; the next 19 consecutive self-inserting input characters do |
4cc0a5e1bdac
Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents:
10364
diff
changeset
|
1089 not make boundaries, and then the 20th does, and so on as long as |
4cc0a5e1bdac
Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents:
10364
diff
changeset
|
1090 self-inserting characters continue. |
4cc0a5e1bdac
Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents:
10364
diff
changeset
|
1091 |
4cc0a5e1bdac
Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents:
10364
diff
changeset
|
1092 All buffer modifications add a boundary whenever the previous undoable |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1093 change was made in some other buffer. This is to ensure that |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1094 each command makes a boundary in each buffer where it makes changes. |
11555
4cc0a5e1bdac
Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents:
10364
diff
changeset
|
1095 |
4cc0a5e1bdac
Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents:
10364
diff
changeset
|
1096 Calling this function explicitly is useful for splitting the effects of |
4cc0a5e1bdac
Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents:
10364
diff
changeset
|
1097 a command into more than one unit. For example, @code{query-replace} |
4cc0a5e1bdac
Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents:
10364
diff
changeset
|
1098 calls @code{undo-boundary} after each replacement, so that the user can |
4cc0a5e1bdac
Explan when boundaries are made automatically.
Richard M. Stallman <rms@gnu.org>
parents:
10364
diff
changeset
|
1099 undo individual replacements one by one. |
6558 | 1100 @end defun |
1101 | |
1102 @defun primitive-undo count list | |
1103 This is the basic function for undoing elements of an undo list. | |
1104 It undoes the first @var{count} elements of @var{list}, returning | |
1105 the rest of @var{list}. You could write this function in Lisp, | |
1106 but it is convenient to have it in C. | |
1107 | |
1108 @code{primitive-undo} adds elements to the buffer's undo list when it | |
1109 changes the buffer. Undo commands avoid confusion by saving the undo | |
1110 list value at the beginning of a sequence of undo operations. Then the | |
1111 undo operations use and update the saved value. The new elements added | |
12098 | 1112 by undoing are not part of this saved value, so they don't interfere with |
6558 | 1113 continuing to undo. |
1114 @end defun | |
1115 | |
1116 @node Maintaining Undo | |
1117 @section Maintaining Undo Lists | |
1118 | |
1119 This section describes how to enable and disable undo information for | |
1120 a given buffer. It also explains how the undo list is truncated | |
1121 automatically so it doesn't get too big. | |
1122 | |
1123 Recording of undo information in a newly created buffer is normally | |
1124 enabled to start with; but if the buffer name starts with a space, the | |
1125 undo recording is initially disabled. You can explicitly enable or | |
1126 disable undo recording with the following two functions, or by setting | |
1127 @code{buffer-undo-list} yourself. | |
1128 | |
1129 @deffn Command buffer-enable-undo &optional buffer-or-name | |
1130 This command enables recording undo information for buffer | |
1131 @var{buffer-or-name}, so that subsequent changes can be undone. If no | |
1132 argument is supplied, then the current buffer is used. This function | |
1133 does nothing if undo recording is already enabled in the buffer. It | |
1134 returns @code{nil}. | |
1135 | |
1136 In an interactive call, @var{buffer-or-name} is the current buffer. | |
1137 You cannot specify any other buffer. | |
1138 @end deffn | |
1139 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1140 @deffn Command buffer-disable-undo &optional buffer |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1141 @deffnx Command buffer-flush-undo &optional buffer |
6558 | 1142 @cindex disable undo |
1143 This function discards the undo list of @var{buffer}, and disables | |
1144 further recording of undo information. As a result, it is no longer | |
1145 possible to undo either previous changes or any subsequent changes. If | |
1146 the undo list of @var{buffer} is already disabled, this function | |
1147 has no effect. | |
1148 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1149 This function returns @code{nil}. |
6558 | 1150 |
1151 The name @code{buffer-flush-undo} is not considered obsolete, but the | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1152 preferred name is @code{buffer-disable-undo}. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1153 @end deffn |
6558 | 1154 |
1155 As editing continues, undo lists get longer and longer. To prevent | |
1156 them from using up all available memory space, garbage collection trims | |
1157 them back to size limits you can set. (For this purpose, the ``size'' | |
1158 of an undo list measures the cons cells that make up the list, plus the | |
1159 strings of deleted text.) Two variables control the range of acceptable | |
1160 sizes: @code{undo-limit} and @code{undo-strong-limit}. | |
1161 | |
1162 @defvar undo-limit | |
1163 This is the soft limit for the acceptable size of an undo list. The | |
1164 change group at which this size is exceeded is the last one kept. | |
1165 @end defvar | |
1166 | |
1167 @defvar undo-strong-limit | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1168 This is the upper limit for the acceptable size of an undo list. The |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1169 change group at which this size is exceeded is discarded itself (along |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1170 with all older change groups). There is one exception: the very latest |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12098
diff
changeset
|
1171 change group is never discarded no matter how big it is. |
6558 | 1172 @end defvar |
1173 | |
1174 @node Filling | |
1175 @comment node-name, next, previous, up | |
1176 @section Filling | |
1177 @cindex filling, explicit | |
1178 | |
1179 @dfn{Filling} means adjusting the lengths of lines (by moving the line | |
1180 breaks) so that they are nearly (but no greater than) a specified | |
1181 maximum width. Additionally, lines can be @dfn{justified}, which means | |
12098 | 1182 inserting spaces to make the left and/or right margins line up |
1183 precisely. The width is controlled by the variable @code{fill-column}. | |
1184 For ease of reading, lines should be no longer than 70 or so columns. | |
6558 | 1185 |
1186 You can use Auto Fill mode (@pxref{Auto Filling}) to fill text | |
1187 automatically as you insert it, but changes to existing text may leave | |
1188 it improperly filled. Then you must fill the text explicitly. | |
1189 | |
12067 | 1190 Most of the commands in this section return values that are not |
1191 meaningful. All the functions that do filling take note of the current | |
12098 | 1192 left margin, current right margin, and current justification style |
1193 (@pxref{Margins}). If the current justification style is | |
1194 @code{none}, the filling functions don't actually do anything. | |
1195 | |
1196 Several of the filling functions have an argument @var{justify}. | |
1197 If it is non-@code{nil}, that requests some kind of justification. It | |
1198 can be @code{left}, @code{right}, @code{full}, or @code{center}, to | |
1199 request a specific style of justification. If it is @code{t}, that | |
1200 means to use the current justification style for this part of the text | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1201 (see @code{current-justification}, below). Any other value is treated |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1202 as @code{full}. |
12098 | 1203 |
1204 When you call the filling functions interactively, using a prefix | |
1205 argument implies the value @code{full} for @var{justify}. | |
1206 | |
1207 @deffn Command fill-paragraph justify | |
6558 | 1208 @cindex filling a paragraph |
1209 This command fills the paragraph at or after point. If | |
12098 | 1210 @var{justify} is non-@code{nil}, each line is justified as well. |
6558 | 1211 It uses the ordinary paragraph motion commands to find paragraph |
1212 boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}. | |
1213 @end deffn | |
1214 | |
25454 | 1215 @deffn Command fill-region start end &optional justify nosqueeze to-eop |
6558 | 1216 This command fills each of the paragraphs in the region from @var{start} |
12098 | 1217 to @var{end}. It justifies as well if @var{justify} is |
6558 | 1218 non-@code{nil}. |
1219 | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1220 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1221 other than line breaks untouched. If @var{to-eop} is non-@code{nil}, |
22267
dfac7398266b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1222 that means to keep filling to the end of the paragraph---or the next hard |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1223 newline, if @code{use-hard-newlines} is enabled (see below). |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1224 |
6558 | 1225 The variable @code{paragraph-separate} controls how to distinguish |
1226 paragraphs. @xref{Standard Regexps}. | |
1227 @end deffn | |
1228 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1229 @deffn Command fill-individual-paragraphs start end &optional justify citation-regexp |
6558 | 1230 This command fills each paragraph in the region according to its |
1231 individual fill prefix. Thus, if the lines of a paragraph were indented | |
1232 with spaces, the filled paragraph will remain indented in the same | |
1233 fashion. | |
1234 | |
1235 The first two arguments, @var{start} and @var{end}, are the beginning | |
1236 and end of the region to be filled. The third and fourth arguments, | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1237 @var{justify} and @var{citation-regexp}, are optional. If |
12098 | 1238 @var{justify} is non-@code{nil}, the paragraphs are justified as |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1239 well as filled. If @var{citation-regexp} is non-@code{nil}, it means the |
6558 | 1240 function is operating on a mail message and therefore should not fill |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1241 the header lines. If @var{citation-regexp} is a string, it is used as |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1242 a regular expression; if it matches the beginning of a line, that line |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1243 is treated as a citation marker. |
6558 | 1244 |
1245 Ordinarily, @code{fill-individual-paragraphs} regards each change in | |
1246 indentation as starting a new paragraph. If | |
1247 @code{fill-individual-varying-indent} is non-@code{nil}, then only | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1248 separator lines separate paragraphs. That mode can handle indented |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1249 paragraphs with additional indentation on the first line. |
6558 | 1250 @end deffn |
1251 | |
1252 @defopt fill-individual-varying-indent | |
1253 This variable alters the action of @code{fill-individual-paragraphs} as | |
1254 described above. | |
1255 @end defopt | |
1256 | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1257 @deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1258 This command considers a region of text as a single paragraph and fills |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1259 it. If the region was made up of many paragraphs, the blank lines |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1260 between paragraphs are removed. This function justifies as well as |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1261 filling when @var{justify} is non-@code{nil}. |
12067 | 1262 |
1263 In an interactive call, any prefix argument requests justification. | |
6558 | 1264 |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1265 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1266 other than line breaks untouched. If @var{squeeze-after} is |
22267
dfac7398266b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1267 non-@code{nil}, it specifies a position in the region, and means don't |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1268 canonicalize spaces before that position. |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1269 |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1270 In Adaptive Fill mode, this command calls @code{fill-context-prefix} to |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1271 choose a fill prefix by default. @xref{Adaptive Fill}. |
6558 | 1272 @end deffn |
1273 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1274 @deffn Command justify-current-line &optional how eop nosqueeze |
6558 | 1275 This command inserts spaces between the words of the current line so |
1276 that the line ends exactly at @code{fill-column}. It returns | |
1277 @code{nil}. | |
12067 | 1278 |
1279 The argument @var{how}, if non-@code{nil} specifies explicitly the style | |
1280 of justification. It can be @code{left}, @code{right}, @code{full}, | |
1281 @code{center}, or @code{none}. If it is @code{t}, that means to do | |
1282 follow specified justification style (see @code{current-justification}, | |
1283 below). @code{nil} means to do full justification. | |
1284 | |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
16702
diff
changeset
|
1285 If @var{eop} is non-@code{nil}, that means do left-justification if |
12067 | 1286 @code{current-justification} specifies full justification. This is used |
1287 for the last line of a paragraph; even if the paragraph as a whole is | |
1288 fully justified, the last line should not be. | |
1289 | |
1290 If @var{nosqueeze} is non-@code{nil}, that means do not change interior | |
1291 whitespace. | |
6558 | 1292 @end deffn |
1293 | |
12067 | 1294 @defopt default-justification |
1295 This variable's value specifies the style of justification to use for | |
1296 text that doesn't specify a style with a text property. The possible | |
1297 values are @code{left}, @code{right}, @code{full}, @code{center}, or | |
12098 | 1298 @code{none}. The default value is @code{left}. |
12067 | 1299 @end defopt |
1300 | |
1301 @defun current-justification | |
1302 This function returns the proper justification style to use for filling | |
1303 the text around point. | |
1304 @end defun | |
1305 | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1306 @defopt sentence-end-double-space |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1307 If this variable is non-@code{nil}, a period followed by just one space |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1308 does not count as the end of a sentence, and the filling functions |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1309 avoid breaking the line at such a place. |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1310 @end defopt |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1311 |
12098 | 1312 @defvar fill-paragraph-function |
1313 This variable provides a way for major modes to override the filling of | |
1314 paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls | |
1315 this function to do the work. If the function returns a non-@code{nil} | |
1316 value, @code{fill-paragraph} assumes the job is done, and immediately | |
1317 returns that value. | |
1318 | |
1319 The usual use of this feature is to fill comments in programming | |
1320 language modes. If the function needs to fill a paragraph in the usual | |
1321 way, it can do so as follows: | |
1322 | |
1323 @example | |
1324 (let ((fill-paragraph-function nil)) | |
1325 (fill-paragraph arg)) | |
1326 @end example | |
1327 @end defvar | |
1328 | |
1329 @defvar use-hard-newlines | |
1330 If this variable is non-@code{nil}, the filling functions do not delete | |
1331 newlines that have the @code{hard} text property. These ``hard | |
1332 newlines'' act as paragraph separators. | |
1333 @end defvar | |
1334 | |
1335 @node Margins | |
1336 @section Margins for Filling | |
1337 | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1338 @defopt fill-prefix |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1339 This buffer-local variable specifies a string of text that appears at |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1340 the beginning |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1341 of normal text lines and should be disregarded when filling them. Any |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1342 line that fails to start with the fill prefix is considered the start of |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1343 a paragraph; so is any line that starts with the fill prefix followed by |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1344 additional whitespace. Lines that start with the fill prefix but no |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1345 additional whitespace are ordinary text lines that can be filled |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1346 together. The resulting filled lines also start with the fill prefix. |
12098 | 1347 |
1348 The fill prefix follows the left margin whitespace, if any. | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1349 @end defopt |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1350 |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1351 @defopt fill-column |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1352 This buffer-local variable specifies the maximum width of filled lines. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1353 Its value should be an integer, which is a number of columns. All the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1354 filling, justification, and centering commands are affected by this |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1355 variable, including Auto Fill mode (@pxref{Auto Filling}). |
6558 | 1356 |
1357 As a practical matter, if you are writing text for other people to | |
1358 read, you should set @code{fill-column} to no more than 70. Otherwise | |
1359 the line will be too long for people to read comfortably, and this can | |
1360 make the text seem clumsy. | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1361 @end defopt |
6558 | 1362 |
1363 @defvar default-fill-column | |
1364 The value of this variable is the default value for @code{fill-column} in | |
1365 buffers that do not override it. This is the same as | |
1366 @code{(default-value 'fill-column)}. | |
1367 | |
1368 The default value for @code{default-fill-column} is 70. | |
1369 @end defvar | |
1370 | |
12067 | 1371 @deffn Command set-left-margin from to margin |
1372 This sets the @code{left-margin} property on the text from @var{from} to | |
1373 @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this | |
1374 command also refills the region to fit the new margin. | |
1375 @end deffn | |
1376 | |
1377 @deffn Command set-right-margin from to margin | |
12098 | 1378 This sets the @code{right-margin} property on the text from @var{from} |
1379 to @var{to} to the value @var{margin}. If Auto Fill mode is enabled, | |
1380 this command also refills the region to fit the new margin. | |
12067 | 1381 @end deffn |
1382 | |
1383 @defun current-left-margin | |
1384 This function returns the proper left margin value to use for filling | |
1385 the text around point. The value is the sum of the @code{left-margin} | |
1386 property of the character at the start of the current line (or zero if | |
12098 | 1387 none), and the value of the variable @code{left-margin}. |
12067 | 1388 @end defun |
1389 | |
1390 @defun current-fill-column | |
1391 This function returns the proper fill column value to use for filling | |
1392 the text around point. The value is the value of the @code{fill-column} | |
1393 variable, minus the value of the @code{right-margin} property of the | |
1394 character after point. | |
1395 @end defun | |
1396 | |
1397 @deffn Command move-to-left-margin &optional n force | |
1398 This function moves point to the left margin of the current line. The | |
1399 column moved to is determined by calling the function | |
12098 | 1400 @code{current-left-margin}. If the argument @var{n} is non-@code{nil}, |
12067 | 1401 @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first. |
1402 | |
1403 If @var{force} is non-@code{nil}, that says to fix the line's | |
1404 indentation if that doesn't match the left margin value. | |
1405 @end deffn | |
1406 | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1407 @defun delete-to-left-margin &optional from to |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1408 This function removes left margin indentation from the text between |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1409 @var{from} and @var{to}. The amount of indentation to delete is |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1410 determined by calling @code{current-left-margin}. In no case does this |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1411 function delete non-whitespace. If @var{from} and @var{to} are omitted, |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1412 they default to the whole buffer. |
12067 | 1413 @end defun |
1414 | |
12098 | 1415 @defun indent-to-left-margin |
1416 This is the default @code{indent-line-function}, used in Fundamental | |
1417 mode, Text mode, etc. Its effect is to adjust the indentation at the | |
1418 beginning of the current line to the value specified by the variable | |
1419 @code{left-margin}. This may involve either inserting or deleting | |
1420 whitespace. | |
1421 @end defun | |
1422 | |
1423 @defvar left-margin | |
1424 This variable specifies the base left margin column. In Fundamental | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1425 mode, @kbd{C-j} indents to this column. This variable automatically |
12098 | 1426 becomes buffer-local when set in any fashion. |
1427 @end defvar | |
1428 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1429 @defvar fill-nobreak-predicate |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1430 This variable gives major modes a way to specify not to break a line at |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1431 certain places. Its value should be a function. This function is |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1432 called during filling, with no arguments and with point located at the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1433 place where a break is being considered. If the function returns |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1434 non-@code{nil}, then the line won't be broken there. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1435 @end defvar |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1436 |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1437 @node Adaptive Fill |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1438 @section Adaptive Fill Mode |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1439 @cindex Adaptive Fill mode |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1440 |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1441 Adaptive Fill mode chooses a fill prefix automatically from the text |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1442 in each paragraph being filled. |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1443 |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1444 @defopt adaptive-fill-mode |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1445 Adaptive Fill mode is enabled when this variable is non-@code{nil}. |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1446 It is @code{t} by default. |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1447 @end defopt |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1448 |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1449 @defun fill-context-prefix from to |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1450 This function implements the heart of Adaptive Fill mode; it chooses a |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1451 fill prefix based on the text between @var{from} and @var{to}. It does |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1452 this by looking at the first two lines of the paragraph, based on the |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1453 variables described below. |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1454 @c The optional argument first-line-regexp is not documented |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1455 @c because it exists for internal purposes and might be eliminated |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
1456 @c in the future. |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1457 @end defun |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1458 |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1459 @defopt adaptive-fill-regexp |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1460 This variable holds a regular expression to control Adaptive Fill mode. |
22267
dfac7398266b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1461 Adaptive Fill mode matches this regular expression against the text |
dfac7398266b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1462 starting after the left margin whitespace (if any) on a line; the |
dfac7398266b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1463 characters it matches are that line's candidate for the fill prefix. |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1464 @end defopt |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1465 |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1466 @defopt adaptive-fill-first-line-regexp |
22267
dfac7398266b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1467 In a one-line paragraph, if the candidate fill prefix matches this |
dfac7398266b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1468 regular expression, or if it matches @code{comment-start-skip}, then it |
dfac7398266b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1469 is used---otherwise, spaces amounting to the same width are used |
dfac7398266b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1470 instead. |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1471 |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1472 However, the fill prefix is never taken from a one-line paragraph |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1473 if it would act as a paragraph starter on subsequent lines. |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1474 @end defopt |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1475 |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1476 @defopt adaptive-fill-function |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1477 You can specify more complex ways of choosing a fill prefix |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1478 automatically by setting this variable to a function. The function is |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1479 called when @code{adaptive-fill-regexp} does not match, with point after |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1480 the left margin of a line, and it should return the appropriate fill |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1481 prefix based on that line. If it returns @code{nil}, that means it sees |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1482 no fill prefix in that line. |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1483 @end defopt |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1484 |
6558 | 1485 @node Auto Filling |
1486 @comment node-name, next, previous, up | |
1487 @section Auto Filling | |
1488 @cindex filling, automatic | |
1489 @cindex Auto Fill mode | |
1490 | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1491 Auto Fill mode is a minor mode that fills lines automatically as text |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12098
diff
changeset
|
1492 is inserted. This section describes the hook used by Auto Fill mode. |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1493 For a description of functions that you can call explicitly to fill and |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1494 justify existing text, see @ref{Filling}. |
6558 | 1495 |
12098 | 1496 Auto Fill mode also enables the functions that change the margins and |
1497 justification style to refill portions of the text. @xref{Margins}. | |
1498 | |
6558 | 1499 @defvar auto-fill-function |
12067 | 1500 The value of this variable should be a function (of no arguments) to be |
1501 called after self-inserting a space or a newline. It may be @code{nil}, | |
1502 in which case nothing special is done in that case. | |
6558 | 1503 |
1504 The value of @code{auto-fill-function} is @code{do-auto-fill} when | |
1505 Auto-Fill mode is enabled. That is a function whose sole purpose is to | |
1506 implement the usual strategy for breaking a line. | |
1507 | |
1508 @quotation | |
1509 In older Emacs versions, this variable was named @code{auto-fill-hook}, | |
1510 but since it is not called with the standard convention for hooks, it | |
1511 was renamed to @code{auto-fill-function} in version 19. | |
1512 @end quotation | |
1513 @end defvar | |
1514 | |
16702
7704b62dafa8
Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents:
16398
diff
changeset
|
1515 @defvar normal-auto-fill-function |
7704b62dafa8
Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents:
16398
diff
changeset
|
1516 This variable specifies the function to use for |
7704b62dafa8
Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents:
16398
diff
changeset
|
1517 @code{auto-fill-function}, if and when Auto Fill is turned on. Major |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1518 modes can set buffer-local values for this variable to alter how Auto |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1519 Fill works. |
16702
7704b62dafa8
Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents:
16398
diff
changeset
|
1520 @end defvar |
7704b62dafa8
Add normal-auto-fill-function.
Richard M. Stallman <rms@gnu.org>
parents:
16398
diff
changeset
|
1521 |
6558 | 1522 @node Sorting |
1523 @section Sorting Text | |
1524 @cindex sorting text | |
1525 | |
1526 The sorting functions described in this section all rearrange text in | |
1527 a buffer. This is in contrast to the function @code{sort}, which | |
1528 rearranges the order of the elements of a list (@pxref{Rearrangement}). | |
1529 The values returned by these functions are not meaningful. | |
1530 | |
1531 @defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1532 This function is the general text-sorting routine that subdivides a |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1533 buffer into records and then sorts them. Most of the commands in this |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1534 section use this function. |
6558 | 1535 |
1536 To understand how @code{sort-subr} works, consider the whole accessible | |
1537 portion of the buffer as being divided into disjoint pieces called | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1538 @dfn{sort records}. The records may or may not be contiguous, but they |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1539 must not overlap. A portion of each sort record (perhaps all of it) is |
6558 | 1540 designated as the sort key. Sorting rearranges the records in order by |
1541 their sort keys. | |
1542 | |
1543 Usually, the records are rearranged in order of ascending sort key. | |
1544 If the first argument to the @code{sort-subr} function, @var{reverse}, | |
1545 is non-@code{nil}, the sort records are rearranged in order of | |
1546 descending sort key. | |
1547 | |
1548 The next four arguments to @code{sort-subr} are functions that are | |
1549 called to move point across a sort record. They are called many times | |
1550 from within @code{sort-subr}. | |
1551 | |
1552 @enumerate | |
1553 @item | |
1554 @var{nextrecfun} is called with point at the end of a record. This | |
1555 function moves point to the start of the next record. The first record | |
1556 is assumed to start at the position of point when @code{sort-subr} is | |
1557 called. Therefore, you should usually move point to the beginning of | |
1558 the buffer before calling @code{sort-subr}. | |
1559 | |
1560 This function can indicate there are no more sort records by leaving | |
1561 point at the end of the buffer. | |
1562 | |
1563 @item | |
1564 @var{endrecfun} is called with point within a record. It moves point to | |
1565 the end of the record. | |
1566 | |
1567 @item | |
1568 @var{startkeyfun} is called to move point from the start of a record to | |
1569 the start of the sort key. This argument is optional; if it is omitted, | |
1570 the whole record is the sort key. If supplied, the function should | |
1571 either return a non-@code{nil} value to be used as the sort key, or | |
1572 return @code{nil} to indicate that the sort key is in the buffer | |
1573 starting at point. In the latter case, @var{endkeyfun} is called to | |
1574 find the end of the sort key. | |
1575 | |
1576 @item | |
1577 @var{endkeyfun} is called to move point from the start of the sort key | |
1578 to the end of the sort key. This argument is optional. If | |
1579 @var{startkeyfun} returns @code{nil} and this argument is omitted (or | |
1580 @code{nil}), then the sort key extends to the end of the record. There | |
1581 is no need for @var{endkeyfun} if @var{startkeyfun} returns a | |
1582 non-@code{nil} value. | |
1583 @end enumerate | |
1584 | |
1585 As an example of @code{sort-subr}, here is the complete function | |
1586 definition for @code{sort-lines}: | |
1587 | |
1588 @example | |
1589 @group | |
1590 ;; @r{Note that the first two lines of doc string} | |
1591 ;; @r{are effectively one line when viewed by a user.} | |
1592 (defun sort-lines (reverse beg end) | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1593 "Sort lines in region alphabetically;\ |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1594 argument means descending order. |
6558 | 1595 Called from a program, there are three arguments: |
1596 @end group | |
1597 @group | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1598 REVERSE (non-nil means reverse order),\ |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1599 BEG and END (region to sort). |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1600 The variable `sort-fold-case' determines\ |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1601 whether alphabetic case affects |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1602 the sort order. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1603 @end group |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1604 @group |
6558 | 1605 (interactive "P\nr") |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1606 (save-excursion |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1607 (save-restriction |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1608 (narrow-to-region beg end) |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1609 (goto-char (point-min)) |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1610 (sort-subr reverse 'forward-line 'end-of-line)))) |
6558 | 1611 @end group |
1612 @end example | |
1613 | |
1614 Here @code{forward-line} moves point to the start of the next record, | |
1615 and @code{end-of-line} moves point to the end of record. We do not pass | |
1616 the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire | |
1617 record is used as the sort key. | |
1618 | |
1619 The @code{sort-paragraphs} function is very much the same, except that | |
1620 its @code{sort-subr} call looks like this: | |
1621 | |
1622 @example | |
1623 @group | |
1624 (sort-subr reverse | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1625 (function |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1626 (lambda () |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1627 (while (and (not (eobp)) |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1628 (looking-at paragraph-separate)) |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1629 (forward-line 1)))) |
6558 | 1630 'forward-paragraph) |
1631 @end group | |
1632 @end example | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1633 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1634 Markers pointing into any sort records are left with no useful |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1635 position after @code{sort-subr} returns. |
6558 | 1636 @end defun |
1637 | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1638 @defopt sort-fold-case |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1639 If this variable is non-@code{nil}, @code{sort-subr} and the other |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1640 buffer sorting functions ignore case when comparing strings. |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1641 @end defopt |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1642 |
6558 | 1643 @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end |
1644 This command sorts the region between @var{start} and @var{end} | |
1645 alphabetically as specified by @var{record-regexp} and @var{key-regexp}. | |
1646 If @var{reverse} is a negative integer, then sorting is in reverse | |
1647 order. | |
1648 | |
1649 Alphabetical sorting means that two sort keys are compared by | |
1650 comparing the first characters of each, the second characters of each, | |
1651 and so on. If a mismatch is found, it means that the sort keys are | |
1652 unequal; the sort key whose character is less at the point of first | |
1653 mismatch is the lesser sort key. The individual characters are compared | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1654 according to their numerical character codes in the Emacs character set. |
6558 | 1655 |
1656 The value of the @var{record-regexp} argument specifies how to divide | |
1657 the buffer into sort records. At the end of each record, a search is | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1658 done for this regular expression, and the text that matches it is taken |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1659 as the next record. For example, the regular expression @samp{^.+$}, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1660 which matches lines with at least one character besides a newline, would |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1661 make each such line into a sort record. @xref{Regular Expressions}, for |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1662 a description of the syntax and meaning of regular expressions. |
6558 | 1663 |
1664 The value of the @var{key-regexp} argument specifies what part of each | |
1665 record is the sort key. The @var{key-regexp} could match the whole | |
1666 record, or only a part. In the latter case, the rest of the record has | |
1667 no effect on the sorted order of records, but it is carried along when | |
1668 the record moves to its new position. | |
1669 | |
1670 The @var{key-regexp} argument can refer to the text matched by a | |
1671 subexpression of @var{record-regexp}, or it can be a regular expression | |
1672 on its own. | |
1673 | |
1674 If @var{key-regexp} is: | |
1675 | |
1676 @table @asis | |
1677 @item @samp{\@var{digit}} | |
1678 then the text matched by the @var{digit}th @samp{\(...\)} parenthesis | |
1679 grouping in @var{record-regexp} is the sort key. | |
1680 | |
1681 @item @samp{\&} | |
1682 then the whole record is the sort key. | |
1683 | |
1684 @item a regular expression | |
1685 then @code{sort-regexp-fields} searches for a match for the regular | |
1686 expression within the record. If such a match is found, it is the sort | |
1687 key. If there is no match for @var{key-regexp} within a record then | |
1688 that record is ignored, which means its position in the buffer is not | |
1689 changed. (The other records may move around it.) | |
1690 @end table | |
1691 | |
1692 For example, if you plan to sort all the lines in the region by the | |
1693 first word on each line starting with the letter @samp{f}, you should | |
1694 set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to | |
1695 @samp{\<f\w*\>}. The resulting expression looks like this: | |
1696 | |
1697 @example | |
1698 @group | |
1699 (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>" | |
1700 (region-beginning) | |
1701 (region-end)) | |
1702 @end group | |
1703 @end example | |
1704 | |
1705 If you call @code{sort-regexp-fields} interactively, it prompts for | |
1706 @var{record-regexp} and @var{key-regexp} in the minibuffer. | |
1707 @end deffn | |
1708 | |
1709 @deffn Command sort-lines reverse start end | |
1710 This command alphabetically sorts lines in the region between | |
1711 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort | |
1712 is in reverse order. | |
1713 @end deffn | |
1714 | |
1715 @deffn Command sort-paragraphs reverse start end | |
1716 This command alphabetically sorts paragraphs in the region between | |
1717 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort | |
1718 is in reverse order. | |
1719 @end deffn | |
1720 | |
1721 @deffn Command sort-pages reverse start end | |
1722 This command alphabetically sorts pages in the region between | |
1723 @var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort | |
1724 is in reverse order. | |
1725 @end deffn | |
1726 | |
1727 @deffn Command sort-fields field start end | |
1728 This command sorts lines in the region between @var{start} and | |
1729 @var{end}, comparing them alphabetically by the @var{field}th field | |
1730 of each line. Fields are separated by whitespace and numbered starting | |
1731 from 1. If @var{field} is negative, sorting is by the | |
1732 @w{@minus{}@var{field}th} field from the end of the line. This command | |
1733 is useful for sorting tables. | |
1734 @end deffn | |
1735 | |
1736 @deffn Command sort-numeric-fields field start end | |
1737 This command sorts lines in the region between @var{start} and | |
1738 @var{end}, comparing them numerically by the @var{field}th field of each | |
1739 line. The specified field must contain a number in each line of the | |
1740 region. Fields are separated by whitespace and numbered starting from | |
1741 1. If @var{field} is negative, sorting is by the | |
1742 @w{@minus{}@var{field}th} field from the end of the line. This command | |
1743 is useful for sorting tables. | |
1744 @end deffn | |
1745 | |
1746 @deffn Command sort-columns reverse &optional beg end | |
1747 This command sorts the lines in the region between @var{beg} and | |
1748 @var{end}, comparing them alphabetically by a certain range of columns. | |
1749 The column positions of @var{beg} and @var{end} bound the range of | |
1750 columns to sort on. | |
1751 | |
1752 If @var{reverse} is non-@code{nil}, the sort is in reverse order. | |
1753 | |
1754 One unusual thing about this command is that the entire line | |
1755 containing position @var{beg}, and the entire line containing position | |
1756 @var{end}, are included in the region sorted. | |
1757 | |
1758 Note that @code{sort-columns} uses the @code{sort} utility program, | |
1759 and so cannot work properly on text containing tab characters. Use | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1760 @kbd{M-x untabify} to convert tabs to spaces before sorting. |
6558 | 1761 @end deffn |
1762 | |
1763 @node Columns | |
1764 @comment node-name, next, previous, up | |
1765 @section Counting Columns | |
1766 @cindex columns | |
1767 @cindex counting columns | |
1768 @cindex horizontal position | |
1769 | |
1770 The column functions convert between a character position (counting | |
1771 characters from the beginning of the buffer) and a column position | |
1772 (counting screen characters from the beginning of a line). | |
1773 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1774 These functions count each character according to the number of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1775 columns it occupies on the screen. This means control characters count |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1776 as occupying 2 or 4 columns, depending upon the value of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1777 @code{ctl-arrow}, and tabs count as occupying a number of columns that |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1778 depends on the value of @code{tab-width} and on the column where the tab |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
1779 begins. @xref{Usual Display}. |
6558 | 1780 |
1781 Column number computations ignore the width of the window and the | |
1782 amount of horizontal scrolling. Consequently, a column value can be | |
1783 arbitrarily high. The first (or leftmost) column is numbered 0. | |
1784 | |
1785 @defun current-column | |
1786 This function returns the horizontal position of point, measured in | |
1787 columns, counting from 0 at the left margin. The column position is the | |
1788 sum of the widths of all the displayed representations of the characters | |
1789 between the start of the current line and point. | |
1790 | |
1791 For an example of using @code{current-column}, see the description of | |
1792 @code{count-lines} in @ref{Text Lines}. | |
1793 @end defun | |
1794 | |
1795 @defun move-to-column column &optional force | |
1796 This function moves point to @var{column} in the current line. The | |
1797 calculation of @var{column} takes into account the widths of the | |
1798 displayed representations of the characters between the start of the | |
1799 line and point. | |
1800 | |
1801 If column @var{column} is beyond the end of the line, point moves to the | |
1802 end of the line. If @var{column} is negative, point moves to the | |
1803 beginning of the line. | |
1804 | |
1805 If it is impossible to move to column @var{column} because that is in | |
1806 the middle of a multicolumn character such as a tab, point moves to the | |
1807 end of that character. However, if @var{force} is non-@code{nil}, and | |
1808 @var{column} is in the middle of a tab, then @code{move-to-column} | |
1809 converts the tab into spaces so that it can move precisely to column | |
1810 @var{column}. Other multicolumn characters can cause anomalies despite | |
1811 @var{force}, since there is no way to split them. | |
1812 | |
1813 The argument @var{force} also has an effect if the line isn't long | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
1814 enough to reach column @var{column}; if it is @code{t}, that means to |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
1815 add whitespace at the end of the line to reach that column. |
6558 | 1816 |
1817 If @var{column} is not an integer, an error is signaled. | |
1818 | |
1819 The return value is the column number actually moved to. | |
1820 @end defun | |
1821 | |
1822 @node Indentation | |
1823 @section Indentation | |
1824 @cindex indentation | |
1825 | |
1826 The indentation functions are used to examine, move to, and change | |
1827 whitespace that is at the beginning of a line. Some of the functions | |
1828 can also change whitespace elsewhere on a line. Columns and indentation | |
1829 count from zero at the left margin. | |
1830 | |
1831 @menu | |
1832 * Primitive Indent:: Functions used to count and insert indentation. | |
1833 * Mode-Specific Indent:: Customize indentation for different modes. | |
1834 * Region Indent:: Indent all the lines in a region. | |
1835 * Relative Indent:: Indent the current line based on previous lines. | |
1836 * Indent Tabs:: Adjustable, typewriter-like tab stops. | |
1837 * Motion by Indent:: Move to first non-blank character. | |
1838 @end menu | |
1839 | |
1840 @node Primitive Indent | |
1841 @subsection Indentation Primitives | |
1842 | |
1843 This section describes the primitive functions used to count and | |
1844 insert indentation. The functions in the following sections use these | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1845 primitives. @xref{Width}, for related functions. |
6558 | 1846 |
1847 @defun current-indentation | |
1848 @comment !!Type Primitive Function | |
1849 @comment !!SourceFile indent.c | |
1850 This function returns the indentation of the current line, which is | |
1851 the horizontal position of the first nonblank character. If the | |
1852 contents are entirely blank, then this is the horizontal position of the | |
1853 end of the line. | |
1854 @end defun | |
1855 | |
1856 @deffn Command indent-to column &optional minimum | |
1857 @comment !!Type Primitive Function | |
1858 @comment !!SourceFile indent.c | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1859 This function indents from point with tabs and spaces until @var{column} |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1860 is reached. If @var{minimum} is specified and non-@code{nil}, then at |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1861 least that many spaces are inserted even if this requires going beyond |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1862 @var{column}. Otherwise the function does nothing if point is already |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1863 beyond @var{column}. The value is the column at which the inserted |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1864 indentation ends. |
8644 | 1865 |
1866 The inserted whitespace characters inherit text properties from the | |
1867 surrounding text (usually, from the preceding text only). @xref{Sticky | |
1868 Properties}. | |
6558 | 1869 @end deffn |
1870 | |
1871 @defopt indent-tabs-mode | |
1872 @comment !!SourceFile indent.c | |
1873 If this variable is non-@code{nil}, indentation functions can insert | |
1874 tabs as well as spaces. Otherwise, they insert only spaces. Setting | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1875 this variable automatically makes it buffer-local in the current buffer. |
6558 | 1876 @end defopt |
1877 | |
1878 @node Mode-Specific Indent | |
1879 @subsection Indentation Controlled by Major Mode | |
1880 | |
1881 An important function of each major mode is to customize the @key{TAB} | |
1882 key to indent properly for the language being edited. This section | |
1883 describes the mechanism of the @key{TAB} key and how to control it. | |
1884 The functions in this section return unpredictable values. | |
1885 | |
1886 @defvar indent-line-function | |
1887 This variable's value is the function to be used by @key{TAB} (and | |
1888 various commands) to indent the current line. The command | |
1889 @code{indent-according-to-mode} does no more than call this function. | |
1890 | |
1891 In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C | |
1892 mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}. | |
1893 In Fundamental mode, Text mode, and many other modes with no standard | |
1894 for indentation, the value is @code{indent-to-left-margin} (which is the | |
1895 default value). | |
1896 @end defvar | |
1897 | |
1898 @deffn Command indent-according-to-mode | |
1899 This command calls the function in @code{indent-line-function} to | |
1900 indent the current line in a way appropriate for the current major mode. | |
1901 @end deffn | |
1902 | |
1903 @deffn Command indent-for-tab-command | |
1904 This command calls the function in @code{indent-line-function} to indent | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1905 the current line; however, if that function is |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1906 @code{indent-to-left-margin}, @code{insert-tab} is called instead. (That |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1907 is a trivial command that inserts a tab character.) |
6558 | 1908 @end deffn |
1909 | |
1910 @deffn Command newline-and-indent | |
1911 @comment !!SourceFile simple.el | |
1912 This function inserts a newline, then indents the new line (the one | |
1913 following the newline just inserted) according to the major mode. | |
1914 | |
1915 It does indentation by calling the current @code{indent-line-function}. | |
1916 In programming language modes, this is the same thing @key{TAB} does, | |
1917 but in some text modes, where @key{TAB} inserts a tab, | |
1918 @code{newline-and-indent} indents to the column specified by | |
1919 @code{left-margin}. | |
1920 @end deffn | |
1921 | |
1922 @deffn Command reindent-then-newline-and-indent | |
1923 @comment !!SourceFile simple.el | |
1924 This command reindents the current line, inserts a newline at point, | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1925 and then indents the new line (the one following the newline just |
6558 | 1926 inserted). |
1927 | |
1928 This command does indentation on both lines according to the current | |
1929 major mode, by calling the current value of @code{indent-line-function}. | |
1930 In programming language modes, this is the same thing @key{TAB} does, | |
1931 but in some text modes, where @key{TAB} inserts a tab, | |
1932 @code{reindent-then-newline-and-indent} indents to the column specified | |
1933 by @code{left-margin}. | |
1934 @end deffn | |
1935 | |
1936 @node Region Indent | |
1937 @subsection Indenting an Entire Region | |
1938 | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1939 This section describes commands that indent all the lines in the |
6558 | 1940 region. They return unpredictable values. |
1941 | |
1942 @deffn Command indent-region start end to-column | |
1943 This command indents each nonblank line starting between @var{start} | |
1944 (inclusive) and @var{end} (exclusive). If @var{to-column} is | |
1945 @code{nil}, @code{indent-region} indents each nonblank line by calling | |
1946 the current mode's indentation function, the value of | |
1947 @code{indent-line-function}. | |
1948 | |
1949 If @var{to-column} is non-@code{nil}, it should be an integer | |
1950 specifying the number of columns of indentation; then this function | |
1951 gives each line exactly that much indentation, by either adding or | |
1952 deleting whitespace. | |
1953 | |
1954 If there is a fill prefix, @code{indent-region} indents each line | |
1955 by making it start with the fill prefix. | |
1956 @end deffn | |
1957 | |
1958 @defvar indent-region-function | |
1959 The value of this variable is a function that can be used by | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1960 @code{indent-region} as a short cut. It should take two arguments, the |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1961 start and end of the region. You should design the function so |
6558 | 1962 that it will produce the same results as indenting the lines of the |
1963 region one by one, but presumably faster. | |
1964 | |
1965 If the value is @code{nil}, there is no short cut, and | |
1966 @code{indent-region} actually works line by line. | |
1967 | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1968 A short-cut function is useful in modes such as C mode and Lisp mode, |
6558 | 1969 where the @code{indent-line-function} must scan from the beginning of |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1970 the function definition: applying it to each line would be quadratic in |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1971 time. The short cut can update the scan information as it moves through |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1972 the lines indenting them; this takes linear time. In a mode where |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1973 indenting a line individually is fast, there is no need for a short cut. |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1974 |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1975 @code{indent-region} with a non-@code{nil} argument @var{to-column} has |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
1976 a different meaning and does not use this variable. |
6558 | 1977 @end defvar |
1978 | |
1979 @deffn Command indent-rigidly start end count | |
1980 @comment !!SourceFile indent.el | |
1981 This command indents all lines starting between @var{start} | |
1982 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns. | |
1983 This ``preserves the shape'' of the affected region, moving it as a | |
1984 rigid unit. Consequently, this command is useful not only for indenting | |
1985 regions of unindented text, but also for indenting regions of formatted | |
1986 code. | |
1987 | |
1988 For example, if @var{count} is 3, this command adds 3 columns of | |
1989 indentation to each of the lines beginning in the region specified. | |
1990 | |
1991 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses | |
1992 @code{indent-rigidly} to indent the text copied from the message being | |
1993 replied to. | |
1994 @end deffn | |
1995 | |
1996 @defun indent-code-rigidly start end columns &optional nochange-regexp | |
1997 This is like @code{indent-rigidly}, except that it doesn't alter lines | |
1998 that start within strings or comments. | |
1999 | |
2000 In addition, it doesn't alter a line if @var{nochange-regexp} matches at | |
2001 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}). | |
2002 @end defun | |
2003 | |
2004 @node Relative Indent | |
2005 @subsection Indentation Relative to Previous Lines | |
2006 | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2007 This section describes two commands that indent the current line |
6558 | 2008 based on the contents of previous lines. |
2009 | |
2010 @deffn Command indent-relative &optional unindented-ok | |
2011 This command inserts whitespace at point, extending to the same | |
2012 column as the next @dfn{indent point} of the previous nonblank line. An | |
2013 indent point is a non-whitespace character following whitespace. The | |
2014 next indent point is the first one at a column greater than the current | |
2015 column of point. For example, if point is underneath and to the left of | |
2016 the first non-blank character of a line of text, it moves to that column | |
2017 by inserting whitespace. | |
2018 | |
2019 If the previous nonblank line has no next indent point (i.e., none at a | |
2020 great enough column position), @code{indent-relative} either does | |
2021 nothing (if @var{unindented-ok} is non-@code{nil}) or calls | |
2022 @code{tab-to-tab-stop}. Thus, if point is underneath and to the right | |
2023 of the last column of a short line of text, this command ordinarily | |
2024 moves point to the next tab stop by inserting whitespace. | |
2025 | |
2026 The return value of @code{indent-relative} is unpredictable. | |
2027 | |
2028 In the following example, point is at the beginning of the second | |
2029 line: | |
2030 | |
2031 @example | |
2032 @group | |
2033 This line is indented twelve spaces. | |
2034 @point{}The quick brown fox jumped. | |
2035 @end group | |
2036 @end example | |
2037 | |
2038 @noindent | |
2039 Evaluation of the expression @code{(indent-relative nil)} produces the | |
2040 following: | |
2041 | |
2042 @example | |
2043 @group | |
2044 This line is indented twelve spaces. | |
2045 @point{}The quick brown fox jumped. | |
2046 @end group | |
2047 @end example | |
2048 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2049 In this next example, point is between the @samp{m} and @samp{p} of |
6558 | 2050 @samp{jumped}: |
2051 | |
2052 @example | |
2053 @group | |
2054 This line is indented twelve spaces. | |
2055 The quick brown fox jum@point{}ped. | |
2056 @end group | |
2057 @end example | |
2058 | |
2059 @noindent | |
2060 Evaluation of the expression @code{(indent-relative nil)} produces the | |
2061 following: | |
2062 | |
2063 @example | |
2064 @group | |
2065 This line is indented twelve spaces. | |
2066 The quick brown fox jum @point{}ped. | |
2067 @end group | |
2068 @end example | |
2069 @end deffn | |
2070 | |
2071 @deffn Command indent-relative-maybe | |
2072 @comment !!SourceFile indent.el | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2073 This command indents the current line like the previous nonblank line, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2074 by calling @code{indent-relative} with @code{t} as the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2075 @var{unindented-ok} argument. The return value is unpredictable. |
6558 | 2076 |
2077 If the previous nonblank line has no indent points beyond the current | |
2078 column, this command does nothing. | |
2079 @end deffn | |
2080 | |
2081 @node Indent Tabs | |
2082 @comment node-name, next, previous, up | |
2083 @subsection Adjustable ``Tab Stops'' | |
2084 @cindex tabs stops for indentation | |
2085 | |
2086 This section explains the mechanism for user-specified ``tab stops'' | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2087 and the mechanisms that use and set them. The name ``tab stops'' is |
6558 | 2088 used because the feature is similar to that of the tab stops on a |
2089 typewriter. The feature works by inserting an appropriate number of | |
2090 spaces and tab characters to reach the next tab stop column; it does not | |
2091 affect the display of tab characters in the buffer (@pxref{Usual | |
2092 Display}). Note that the @key{TAB} character as input uses this tab | |
2093 stop feature only in a few major modes, such as Text mode. | |
2094 | |
2095 @deffn Command tab-to-tab-stop | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2096 This command inserts spaces or tabs before point, up to the next tab |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2097 stop column defined by @code{tab-stop-list}. It searches the list for |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2098 an element greater than the current column number, and uses that element |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2099 as the column to indent to. It does nothing if no such element is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2100 found. |
6558 | 2101 @end deffn |
2102 | |
2103 @defopt tab-stop-list | |
2104 This variable is the list of tab stop columns used by | |
2105 @code{tab-to-tab-stops}. The elements should be integers in increasing | |
2106 order. The tab stop columns need not be evenly spaced. | |
2107 | |
2108 Use @kbd{M-x edit-tab-stops} to edit the location of tab stops | |
2109 interactively. | |
2110 @end defopt | |
2111 | |
2112 @node Motion by Indent | |
2113 @subsection Indentation-Based Motion Commands | |
2114 | |
2115 These commands, primarily for interactive use, act based on the | |
2116 indentation in the text. | |
2117 | |
2118 @deffn Command back-to-indentation | |
2119 @comment !!SourceFile simple.el | |
2120 This command moves point to the first non-whitespace character in the | |
2121 current line (which is the line in which point is located). It returns | |
2122 @code{nil}. | |
2123 @end deffn | |
2124 | |
2125 @deffn Command backward-to-indentation arg | |
2126 @comment !!SourceFile simple.el | |
2127 This command moves point backward @var{arg} lines and then to the | |
2128 first nonblank character on that line. It returns @code{nil}. | |
2129 @end deffn | |
2130 | |
2131 @deffn Command forward-to-indentation arg | |
2132 @comment !!SourceFile simple.el | |
2133 This command moves point forward @var{arg} lines and then to the first | |
2134 nonblank character on that line. It returns @code{nil}. | |
2135 @end deffn | |
2136 | |
2137 @node Case Changes | |
2138 @comment node-name, next, previous, up | |
2139 @section Case Changes | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2140 @cindex case conversion in buffers |
6558 | 2141 |
2142 The case change commands described here work on text in the current | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2143 buffer. @xref{Case Conversion}, for case conversion functions that work |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2144 on strings and characters. @xref{Case Tables}, for how to customize |
6558 | 2145 which characters are upper or lower case and how to convert them. |
2146 | |
2147 @deffn Command capitalize-region start end | |
2148 This function capitalizes all words in the region defined by | |
2149 @var{start} and @var{end}. To capitalize means to convert each word's | |
2150 first character to upper case and convert the rest of each word to lower | |
2151 case. The function returns @code{nil}. | |
2152 | |
2153 If one end of the region is in the middle of a word, the part of the | |
2154 word within the region is treated as an entire word. | |
2155 | |
2156 When @code{capitalize-region} is called interactively, @var{start} and | |
2157 @var{end} are point and the mark, with the smallest first. | |
2158 | |
2159 @example | |
2160 @group | |
2161 ---------- Buffer: foo ---------- | |
2162 This is the contents of the 5th foo. | |
2163 ---------- Buffer: foo ---------- | |
2164 @end group | |
2165 | |
2166 @group | |
2167 (capitalize-region 1 44) | |
2168 @result{} nil | |
2169 | |
2170 ---------- Buffer: foo ---------- | |
2171 This Is The Contents Of The 5th Foo. | |
2172 ---------- Buffer: foo ---------- | |
2173 @end group | |
2174 @end example | |
2175 @end deffn | |
2176 | |
2177 @deffn Command downcase-region start end | |
2178 This function converts all of the letters in the region defined by | |
2179 @var{start} and @var{end} to lower case. The function returns | |
2180 @code{nil}. | |
2181 | |
2182 When @code{downcase-region} is called interactively, @var{start} and | |
2183 @var{end} are point and the mark, with the smallest first. | |
2184 @end deffn | |
2185 | |
2186 @deffn Command upcase-region start end | |
2187 This function converts all of the letters in the region defined by | |
2188 @var{start} and @var{end} to upper case. The function returns | |
2189 @code{nil}. | |
2190 | |
2191 When @code{upcase-region} is called interactively, @var{start} and | |
2192 @var{end} are point and the mark, with the smallest first. | |
2193 @end deffn | |
2194 | |
2195 @deffn Command capitalize-word count | |
2196 This function capitalizes @var{count} words after point, moving point | |
2197 over as it does. To capitalize means to convert each word's first | |
2198 character to upper case and convert the rest of each word to lower case. | |
2199 If @var{count} is negative, the function capitalizes the | |
2200 @minus{}@var{count} previous words but does not move point. The value | |
2201 is @code{nil}. | |
2202 | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2203 If point is in the middle of a word, the part of the word before point |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2204 is ignored when moving forward. The rest is treated as an entire word. |
6558 | 2205 |
2206 When @code{capitalize-word} is called interactively, @var{count} is | |
2207 set to the numeric prefix argument. | |
2208 @end deffn | |
2209 | |
2210 @deffn Command downcase-word count | |
2211 This function converts the @var{count} words after point to all lower | |
2212 case, moving point over as it does. If @var{count} is negative, it | |
2213 converts the @minus{}@var{count} previous words but does not move point. | |
2214 The value is @code{nil}. | |
2215 | |
2216 When @code{downcase-word} is called interactively, @var{count} is set | |
2217 to the numeric prefix argument. | |
2218 @end deffn | |
2219 | |
2220 @deffn Command upcase-word count | |
2221 This function converts the @var{count} words after point to all upper | |
2222 case, moving point over as it does. If @var{count} is negative, it | |
2223 converts the @minus{}@var{count} previous words but does not move point. | |
2224 The value is @code{nil}. | |
2225 | |
2226 When @code{upcase-word} is called interactively, @var{count} is set to | |
2227 the numeric prefix argument. | |
2228 @end deffn | |
2229 | |
2230 @node Text Properties | |
2231 @section Text Properties | |
2232 @cindex text properties | |
2233 @cindex attributes of text | |
2234 @cindex properties of text | |
2235 | |
2236 Each character position in a buffer or a string can have a @dfn{text | |
2237 property list}, much like the property list of a symbol (@pxref{Property | |
2238 Lists}). The properties belong to a particular character at a | |
2239 particular place, such as, the letter @samp{T} at the beginning of this | |
2240 sentence or the first @samp{o} in @samp{foo}---if the same character | |
2241 occurs in two different places, the two occurrences generally have | |
2242 different properties. | |
2243 | |
2244 Each property has a name and a value. Both of these can be any Lisp | |
2245 object, but the name is normally a symbol. The usual way to access the | |
2246 property list is to specify a name and ask what value corresponds to it. | |
2247 | |
2248 If a character has a @code{category} property, we call it the | |
2249 @dfn{category} of the character. It should be a symbol. The properties | |
2250 of the symbol serve as defaults for the properties of the character. | |
2251 | |
2252 Copying text between strings and buffers preserves the properties | |
2253 along with the characters; this includes such diverse functions as | |
2254 @code{substring}, @code{insert}, and @code{buffer-substring}. | |
2255 | |
2256 @menu | |
2257 * Examining Properties:: Looking at the properties of one character. | |
2258 * Changing Properties:: Setting the properties of a range of text. | |
2259 * Property Search:: Searching for where a property changes value. | |
2260 * Special Properties:: Particular properties with special meanings. | |
12067 | 2261 * Format Properties:: Properties for representing formatting of text. |
6558 | 2262 * Sticky Properties:: How inserted text gets properties from |
2263 neighboring text. | |
2264 * Saving Properties:: Saving text properties in files, and reading | |
2265 them back. | |
15760
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2266 * Lazy Properties:: Computing text properties in a lazy fashion |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2267 only when text is examined. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2268 * Clickable Text:: Using text properties to make regions of text |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2269 do something when you click on them. |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2270 * Fields:: The @code{field} property defines |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2271 fields within the buffer. |
6558 | 2272 * Not Intervals:: Why text properties do not use |
2273 Lisp-visible text intervals. | |
2274 @end menu | |
2275 | |
2276 @node Examining Properties | |
2277 @subsection Examining Text Properties | |
2278 | |
2279 The simplest way to examine text properties is to ask for the value of | |
2280 a particular property of a particular character. For that, use | |
2281 @code{get-text-property}. Use @code{text-properties-at} to get the | |
2282 entire property list of a character. @xref{Property Search}, for | |
2283 functions to examine the properties of a number of characters at once. | |
2284 | |
2285 These functions handle both strings and buffers. Keep in mind that | |
2286 positions in a string start from 0, whereas positions in a buffer start | |
2287 from 1. | |
2288 | |
2289 @defun get-text-property pos prop &optional object | |
2290 This function returns the value of the @var{prop} property of the | |
2291 character after position @var{pos} in @var{object} (a buffer or | |
2292 string). The argument @var{object} is optional and defaults to the | |
2293 current buffer. | |
2294 | |
2295 If there is no @var{prop} property strictly speaking, but the character | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2296 has a category that is a symbol, then @code{get-text-property} returns |
6558 | 2297 the @var{prop} property of that symbol. |
2298 @end defun | |
2299 | |
2300 @defun get-char-property pos prop &optional object | |
2301 This function is like @code{get-text-property}, except that it checks | |
2302 overlays first and then text properties. @xref{Overlays}. | |
2303 | |
2304 The argument @var{object} may be a string, a buffer, or a window. If it | |
2305 is a window, then the buffer displayed in that window is used for text | |
2306 properties and overlays, but only the overlays active for that window | |
2307 are considered. If @var{object} is a buffer, then all overlays in that | |
2308 buffer are considered, as well as text properties. If @var{object} is a | |
2309 string, only text properties are considered, since strings never have | |
2310 overlays. | |
2311 @end defun | |
2312 | |
2313 @defun text-properties-at position &optional object | |
2314 This function returns the entire property list of the character at | |
2315 @var{position} in the string or buffer @var{object}. If @var{object} is | |
2316 @code{nil}, it defaults to the current buffer. | |
2317 @end defun | |
2318 | |
12067 | 2319 @defvar default-text-properties |
2320 This variable holds a property list giving default values for text | |
2321 properties. Whenever a character does not specify a value for a | |
12098 | 2322 property, neither directly nor through a category symbol, the value |
2323 stored in this list is used instead. Here is an example: | |
12067 | 2324 |
2325 @example | |
2326 (setq default-text-properties '(foo 69)) | |
2327 ;; @r{Make sure character 1 has no properties of its own.} | |
2328 (set-text-properties 1 2 nil) | |
2329 ;; @r{What we get, when we ask, is the default value.} | |
2330 (get-text-property 1 'foo) | |
2331 @result{} 69 | |
2332 @end example | |
2333 @end defvar | |
2334 | |
6558 | 2335 @node Changing Properties |
2336 @subsection Changing Text Properties | |
2337 | |
2338 The primitives for changing properties apply to a specified range of | |
18339
7def48db254a
Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents:
16934
diff
changeset
|
2339 text in a buffer or string. The function @code{set-text-properties} |
7def48db254a
Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents:
16934
diff
changeset
|
2340 (see end of section) sets the entire property list of the text in that |
7def48db254a
Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents:
16934
diff
changeset
|
2341 range; more often, it is useful to add, change, or delete just certain |
7def48db254a
Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents:
16934
diff
changeset
|
2342 properties specified by name. |
7def48db254a
Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents:
16934
diff
changeset
|
2343 |
7def48db254a
Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents:
16934
diff
changeset
|
2344 Since text properties are considered part of the contents of the |
7def48db254a
Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents:
16934
diff
changeset
|
2345 buffer (or string), and can affect how a buffer looks on the screen, any |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2346 change in buffer text properties marks the buffer as modified. Buffer |
18339
7def48db254a
Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents:
16934
diff
changeset
|
2347 text property changes are undoable also (@pxref{Undo}). |
6558 | 2348 |
12098 | 2349 @defun put-text-property start end prop value &optional object |
2350 This function sets the @var{prop} property to @var{value} for the text | |
2351 between @var{start} and @var{end} in the string or buffer @var{object}. | |
2352 If @var{object} is @code{nil}, it defaults to the current buffer. | |
2353 @end defun | |
2354 | |
6558 | 2355 @defun add-text-properties start end props &optional object |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2356 This function adds or overrides text properties for the text between |
6558 | 2357 @var{start} and @var{end} in the string or buffer @var{object}. If |
2358 @var{object} is @code{nil}, it defaults to the current buffer. | |
2359 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2360 The argument @var{props} specifies which properties to add. It should |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2361 have the form of a property list (@pxref{Property Lists}): a list whose |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2362 elements include the property names followed alternately by the |
6558 | 2363 corresponding values. |
2364 | |
2365 The return value is @code{t} if the function actually changed some | |
2366 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or | |
2367 its values agree with those in the text). | |
2368 | |
2369 For example, here is how to set the @code{comment} and @code{face} | |
2370 properties of a range of text: | |
2371 | |
2372 @example | |
2373 (add-text-properties @var{start} @var{end} | |
2374 '(comment t face highlight)) | |
2375 @end example | |
2376 @end defun | |
2377 | |
2378 @defun remove-text-properties start end props &optional object | |
2379 This function deletes specified text properties from the text between | |
2380 @var{start} and @var{end} in the string or buffer @var{object}. If | |
2381 @var{object} is @code{nil}, it defaults to the current buffer. | |
2382 | |
2383 The argument @var{props} specifies which properties to delete. It | |
2384 should have the form of a property list (@pxref{Property Lists}): a list | |
2385 whose elements are property names alternating with corresponding values. | |
2386 But only the names matter---the values that accompany them are ignored. | |
2387 For example, here's how to remove the @code{face} property. | |
2388 | |
2389 @example | |
2390 (remove-text-properties @var{start} @var{end} '(face nil)) | |
2391 @end example | |
2392 | |
2393 The return value is @code{t} if the function actually changed some | |
2394 property's value; @code{nil} otherwise (if @var{props} is @code{nil} or | |
2395 if no character in the specified text had any of those properties). | |
18339
7def48db254a
Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents:
16934
diff
changeset
|
2396 |
7def48db254a
Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents:
16934
diff
changeset
|
2397 To remove all text properties from certain text, use |
7def48db254a
Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents:
16934
diff
changeset
|
2398 @code{set-text-properties} and specify @code{nil} for the new property |
7def48db254a
Clarify about text props in strings and how to remove all of them.
Richard M. Stallman <rms@gnu.org>
parents:
16934
diff
changeset
|
2399 list. |
6558 | 2400 @end defun |
2401 | |
2402 @defun set-text-properties start end props &optional object | |
2403 This function completely replaces the text property list for the text | |
2404 between @var{start} and @var{end} in the string or buffer @var{object}. | |
2405 If @var{object} is @code{nil}, it defaults to the current buffer. | |
2406 | |
2407 The argument @var{props} is the new property list. It should be a list | |
2408 whose elements are property names alternating with corresponding values. | |
2409 | |
2410 After @code{set-text-properties} returns, all the characters in the | |
2411 specified range have identical properties. | |
2412 | |
2413 If @var{props} is @code{nil}, the effect is to get rid of all properties | |
2414 from the specified range of text. Here's an example: | |
2415 | |
2416 @example | |
2417 (set-text-properties @var{start} @var{end} nil) | |
2418 @end example | |
2419 @end defun | |
2420 | |
25875 | 2421 The easiest way to make a string with text properties |
2422 is with @code{propertize}: | |
2423 | |
2424 @defun propertize string &rest properties | |
2425 @tindex propertize | |
2426 This function returns a copy of @var{string} which has the text | |
2427 properties @var{properties}. These properties apply to all the | |
2428 characters in the string that is returned. Here is an example that | |
2429 constructs a string with a @code{face} property and a @code{mouse-face} | |
2430 property: | |
2431 | |
2432 @smallexample | |
2433 (propertize "foo" 'face 'italic | |
2434 'mouse-face 'bold-italic) | |
2435 @result{} #("foo" 0 3 (mouse-face bold-italic face italic)) | |
2436 @end smallexample | |
2437 | |
2438 To put different properties on various parts of a string, you can | |
2439 construct each part with @code{propertize} and then combine them with | |
2440 @code{concat}: | |
2441 | |
2442 @smallexample | |
2443 (concat | |
2444 (propertize "foo" 'face 'italic | |
2445 'mouse-face 'bold-italic) | |
2446 " and " | |
2447 (propertize "bar" 'face 'italic | |
2448 'mouse-face 'bold-italic)) | |
2449 @result{} #("foo and bar" | |
2450 0 3 (face italic mouse-face bold-italic) | |
2451 3 8 nil | |
2452 8 11 (face italic mouse-face bold-italic)) | |
2453 @end smallexample | |
2454 @end defun | |
2455 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2456 See also the function @code{buffer-substring-no-properties} |
12067 | 2457 (@pxref{Buffer Contents}) which copies text from the buffer |
2458 but does not copy its properties. | |
2459 | |
6558 | 2460 @node Property Search |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2461 @subsection Text Property Search Functions |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2462 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2463 In typical use of text properties, most of the time several or many |
6558 | 2464 consecutive characters have the same value for a property. Rather than |
2465 writing your programs to examine characters one by one, it is much | |
2466 faster to process chunks of text that have the same property value. | |
2467 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2468 Here are functions you can use to do this. They use @code{eq} for |
12098 | 2469 comparing property values. In all cases, @var{object} defaults to the |
2470 current buffer. | |
6558 | 2471 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2472 For high performance, it's very important to use the @var{limit} |
6558 | 2473 argument to these functions, especially the ones that search for a |
12098 | 2474 single property---otherwise, they may spend a long time scanning to the |
2475 end of the buffer, if the property you are interested in does not change. | |
6558 | 2476 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2477 These functions do not move point; instead, they return a position (or |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2478 @code{nil}). Remember that a position is always between two characters; |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2479 the position returned by these functions is between two characters with |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2480 different properties. |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2481 |
6558 | 2482 @defun next-property-change pos &optional object limit |
2483 The function scans the text forward from position @var{pos} in the | |
2484 string or buffer @var{object} till it finds a change in some text | |
2485 property, then returns the position of the change. In other words, it | |
2486 returns the position of the first character beyond @var{pos} whose | |
2487 properties are not identical to those of the character just after | |
2488 @var{pos}. | |
2489 | |
2490 If @var{limit} is non-@code{nil}, then the scan ends at position | |
2491 @var{limit}. If there is no property change before that point, | |
2492 @code{next-property-change} returns @var{limit}. | |
2493 | |
2494 The value is @code{nil} if the properties remain unchanged all the way | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2495 to the end of @var{object} and @var{limit} is @code{nil}. If the value |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2496 is non-@code{nil}, it is a position greater than or equal to @var{pos}. |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2497 The value equals @var{pos} only when @var{limit} equals @var{pos}. |
6558 | 2498 |
2499 Here is an example of how to scan the buffer by chunks of text within | |
2500 which all properties are constant: | |
2501 | |
2502 @smallexample | |
2503 (while (not (eobp)) | |
2504 (let ((plist (text-properties-at (point))) | |
2505 (next-change | |
2506 (or (next-property-change (point) (current-buffer)) | |
2507 (point-max)))) | |
2508 @r{Process text from point to @var{next-change}@dots{}} | |
2509 (goto-char next-change))) | |
2510 @end smallexample | |
2511 @end defun | |
2512 | |
2513 @defun next-single-property-change pos prop &optional object limit | |
2514 The function scans the text forward from position @var{pos} in the | |
2515 string or buffer @var{object} till it finds a change in the @var{prop} | |
2516 property, then returns the position of the change. In other words, it | |
2517 returns the position of the first character beyond @var{pos} whose | |
2518 @var{prop} property differs from that of the character just after | |
2519 @var{pos}. | |
2520 | |
2521 If @var{limit} is non-@code{nil}, then the scan ends at position | |
2522 @var{limit}. If there is no property change before that point, | |
2523 @code{next-single-property-change} returns @var{limit}. | |
2524 | |
2525 The value is @code{nil} if the property remains unchanged all the way to | |
2526 the end of @var{object} and @var{limit} is @code{nil}. If the value is | |
2527 non-@code{nil}, it is a position greater than or equal to @var{pos}; it | |
2528 equals @var{pos} only if @var{limit} equals @var{pos}. | |
2529 @end defun | |
2530 | |
2531 @defun previous-property-change pos &optional object limit | |
2532 This is like @code{next-property-change}, but scans back from @var{pos} | |
2533 instead of forward. If the value is non-@code{nil}, it is a position | |
2534 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit} | |
2535 equals @var{pos}. | |
2536 @end defun | |
2537 | |
2538 @defun previous-single-property-change pos prop &optional object limit | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2539 This is like @code{next-single-property-change}, but scans back from |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2540 @var{pos} instead of forward. If the value is non-@code{nil}, it is a |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2541 position less than or equal to @var{pos}; it equals @var{pos} only if |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2542 @var{limit} equals @var{pos}. |
6558 | 2543 @end defun |
2544 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2545 @defun next-char-property-change position &optional limit |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2546 This is like @code{next-property-change} except that it considers |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2547 overlay properties as well as text properties. There is no @var{object} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2548 operand because this function operates only on the current buffer. It |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2549 returns the next address at which either kind of property changes. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2550 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2551 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
2552 @defun previous-char-property-change position &optional limit |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2553 This is like @code{next-char-property-change}, but scans back from |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2554 @var{position} instead of forward. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2555 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2556 |
6558 | 2557 @defun text-property-any start end prop value &optional object |
2558 This function returns non-@code{nil} if at least one character between | |
2559 @var{start} and @var{end} has a property @var{prop} whose value is | |
2560 @var{value}. More precisely, it returns the position of the first such | |
2561 character. Otherwise, it returns @code{nil}. | |
2562 | |
2563 The optional fifth argument, @var{object}, specifies the string or | |
2564 buffer to scan. Positions are relative to @var{object}. The default | |
2565 for @var{object} is the current buffer. | |
2566 @end defun | |
2567 | |
2568 @defun text-property-not-all start end prop value &optional object | |
2569 This function returns non-@code{nil} if at least one character between | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2570 @var{start} and @var{end} does not have a property @var{prop} with value |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2571 @var{value}. More precisely, it returns the position of the first such |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2572 character. Otherwise, it returns @code{nil}. |
6558 | 2573 |
2574 The optional fifth argument, @var{object}, specifies the string or | |
2575 buffer to scan. Positions are relative to @var{object}. The default | |
2576 for @var{object} is the current buffer. | |
2577 @end defun | |
2578 | |
2579 @node Special Properties | |
2580 @subsection Properties with Special Meanings | |
2581 | |
12098 | 2582 Here is a table of text property names that have special built-in |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2583 meanings. The following sections list a few additional special property |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2584 names that control filling and property inheritance. All other names |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
2585 have no standard meaning, and you can use them as you like. |
12098 | 2586 |
6558 | 2587 @table @code |
2588 @cindex category of text character | |
2589 @kindex category @r{(text property)} | |
2590 @item category | |
2591 If a character has a @code{category} property, we call it the | |
2592 @dfn{category} of the character. It should be a symbol. The properties | |
2593 of the symbol serve as defaults for the properties of the character. | |
2594 | |
2595 @item face | |
2596 @cindex face codes of text | |
2597 @kindex face @r{(text property)} | |
2598 You can use the property @code{face} to control the font and color of | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2599 text. @xref{Faces}, for more information. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2600 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2601 In the simplest case, the value is a face name. It can also be a list; |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2602 then each element can be any of these possibilities; |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2603 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2604 @itemize @bullet |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2605 @item |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2606 A face name (a symbol or string). |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2607 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2608 @item |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2609 Starting in Emacs 21, a property list of face attributes. This has the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2610 form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2611 face attribute name and @var{value} is a meaningful value for that |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2612 attribute. With this feature, you do not need to create a face each |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2613 time you want to specify a particular attribute for certain text. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2614 @xref{Face Attributes}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2615 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2616 @item |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2617 A cons cell of the form @code{(foreground-color . @var{color-name})} or |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2618 @code{(background-color . @var{color-name})}. These elements specify |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2619 just the foreground color or just the background color. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2620 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2621 @code{(foreground-color . @var{color-name})} is equivalent to |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2622 @code{(:foreground @var{color-name})}, and likewise for the background. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2623 @end itemize |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2624 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2625 @xref{Font Lock Mode}, for information on how to update @code{face} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2626 properties automatically based on the contents of the text. |
6558 | 2627 |
2628 @item mouse-face | |
2629 @kindex mouse-face @r{(text property)} | |
2630 The property @code{mouse-face} is used instead of @code{face} when the | |
2631 mouse is on or near the character. For this purpose, ``near'' means | |
2632 that all text between the character and where the mouse is have the same | |
2633 @code{mouse-face} property value. | |
2634 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2635 @item fontified |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2636 @kindex fontified @r{(text property)} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2637 This property, if non-@code{nil}, says that text in the buffer has |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2638 had faces assigned automatically by a feature such as Font-Lock mode. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2639 @xref{Auto Faces}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2640 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2641 @item display |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2642 @kindex display @r{(text property)} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2643 This property activates various features that change the |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2644 way text is displayed. For example, it can make text appear taller |
27374
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
2645 or shorter, higher or lower, wider or narrow, or replaced with an image. |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2646 @xref{Display Property}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2647 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2648 @item help-echo |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2649 @kindex help-echo @r{(text property)} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2650 If text has a string as its @code{help-echo} property, then when you |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2651 move the mouse onto that text, Emacs displays that string in the echo |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2652 area, or in the tooltip window. This feature is used in the mode line. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2653 It is available starting in Emacs 21. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
2654 |
6558 | 2655 @item local-map |
2656 @cindex keymap of character | |
2657 @kindex local-map @r{(text property)} | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2658 You can specify a different keymap for some of the text in a buffer by |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2659 means of the @code{local-map} property. The property's value for the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2660 character after point, if non-@code{nil}, is used for key lookup instead |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2661 of the buffer's local map. If the property value is a symbol, the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2662 symbol's function definition is used as the keymap. @xref{Active |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2663 Keymaps}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2664 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2665 @item syntax-table |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2666 The @code{syntax-table} property overrides what the syntax table says |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2667 about this particular character. @xref{Syntax Properties}. |
6558 | 2668 |
2669 @item read-only | |
2670 @cindex read-only character | |
2671 @kindex read-only @r{(text property)} | |
2672 If a character has the property @code{read-only}, then modifying that | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2673 character is not allowed. Any command that would do so gets an error, |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2674 @code{text-read-only}. |
6558 | 2675 |
2676 Insertion next to a read-only character is an error if inserting | |
2677 ordinary text there would inherit the @code{read-only} property due to | |
2678 stickiness. Thus, you can control permission to insert next to | |
2679 read-only text by controlling the stickiness. @xref{Sticky Properties}. | |
2680 | |
2681 Since changing properties counts as modifying the buffer, it is not | |
2682 possible to remove a @code{read-only} property unless you know the | |
2683 special trick: bind @code{inhibit-read-only} to a non-@code{nil} value | |
2684 and then remove the property. @xref{Read Only Buffers}. | |
2685 | |
2686 @item invisible | |
2687 @kindex invisible @r{(text property)} | |
12067 | 2688 A non-@code{nil} @code{invisible} property can make a character invisible |
2689 on the screen. @xref{Invisible Text}, for details. | |
6558 | 2690 |
6782
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
2691 @item intangible |
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
2692 @kindex intangible @r{(text property)} |
12067 | 2693 If a group of consecutive characters have equal and non-@code{nil} |
2694 @code{intangible} properties, then you cannot place point between them. | |
12098 | 2695 If you try to move point forward into the group, point actually moves to |
2696 the end of the group. If you try to move point backward into the group, | |
12067 | 2697 point actually moves to the start of the group. |
2698 | |
2699 When the variable @code{inhibit-point-motion-hooks} is non-@code{nil}, | |
2700 the @code{intangible} property is ignored. | |
6782
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
2701 |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2702 @item field |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2703 @kindex field @r{(text property)} |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2704 Consecutive characters with the same @code{field} property constitute a |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2705 @dfn{field}. Some motion functions including @code{forward-word} and |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2706 @code{beginning-of-line} stop moving at a field boundary. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2707 @xref{Fields}. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2708 |
6558 | 2709 @item modification-hooks |
2710 @cindex change hooks for a character | |
2711 @cindex hooks for changing a character | |
2712 @kindex modification-hooks @r{(text property)} | |
2713 If a character has the property @code{modification-hooks}, then its | |
2714 value should be a list of functions; modifying that character calls all | |
2715 of those functions. Each function receives two arguments: the beginning | |
2716 and end of the part of the buffer being modified. Note that if a | |
2717 particular modification hook function appears on several characters | |
2718 being modified by a single primitive, you can't predict how many times | |
2719 the function will be called. | |
2720 | |
2721 @item insert-in-front-hooks | |
2722 @itemx insert-behind-hooks | |
2723 @kindex insert-in-front-hooks @r{(text property)} | |
2724 @kindex insert-behind-hooks @r{(text property)} | |
16398
71e49abd5906
Clarify how insert-in-front-hooks and insert-behind-hooks are used.
Richard M. Stallman <rms@gnu.org>
parents:
15760
diff
changeset
|
2725 The operation of inserting text in a buffer also calls the functions |
71e49abd5906
Clarify how insert-in-front-hooks and insert-behind-hooks are used.
Richard M. Stallman <rms@gnu.org>
parents:
15760
diff
changeset
|
2726 listed in the @code{insert-in-front-hooks} property of the following |
71e49abd5906
Clarify how insert-in-front-hooks and insert-behind-hooks are used.
Richard M. Stallman <rms@gnu.org>
parents:
15760
diff
changeset
|
2727 character and in the @code{insert-behind-hooks} property of the |
71e49abd5906
Clarify how insert-in-front-hooks and insert-behind-hooks are used.
Richard M. Stallman <rms@gnu.org>
parents:
15760
diff
changeset
|
2728 preceding character. These functions receive two arguments, the |
71e49abd5906
Clarify how insert-in-front-hooks and insert-behind-hooks are used.
Richard M. Stallman <rms@gnu.org>
parents:
15760
diff
changeset
|
2729 beginning and end of the inserted text. The functions are called |
71e49abd5906
Clarify how insert-in-front-hooks and insert-behind-hooks are used.
Richard M. Stallman <rms@gnu.org>
parents:
15760
diff
changeset
|
2730 @emph{after} the actual insertion takes place. |
6558 | 2731 |
2732 See also @ref{Change Hooks}, for other hooks that are called | |
2733 when you change text in a buffer. | |
2734 | |
2735 @item point-entered | |
2736 @itemx point-left | |
2737 @cindex hooks for motion of point | |
2738 @kindex point-entered @r{(text property)} | |
2739 @kindex point-left @r{(text property)} | |
2740 The special properties @code{point-entered} and @code{point-left} | |
2741 record hook functions that report motion of point. Each time point | |
2742 moves, Emacs compares these two property values: | |
2743 | |
2744 @itemize @bullet | |
2745 @item | |
2746 the @code{point-left} property of the character after the old location, | |
2747 and | |
2748 @item | |
2749 the @code{point-entered} property of the character after the new | |
2750 location. | |
2751 @end itemize | |
2752 | |
2753 @noindent | |
2754 If these two values differ, each of them is called (if not @code{nil}) | |
2755 with two arguments: the old value of point, and the new one. | |
2756 | |
2757 The same comparison is made for the characters before the old and new | |
2758 locations. The result may be to execute two @code{point-left} functions | |
2759 (which may be the same function) and/or two @code{point-entered} | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2760 functions (which may be the same function). In any case, all the |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2761 @code{point-left} functions are called first, followed by all the |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2762 @code{point-entered} functions. |
6558 | 2763 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2764 It is possible using @code{char-after} to examine characters at various |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2765 positions without moving point to those positions. Only an actual |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2766 change in the value of point runs these hook functions. |
6558 | 2767 @end table |
2768 | |
2769 @defvar inhibit-point-motion-hooks | |
2770 When this variable is non-@code{nil}, @code{point-left} and | |
12067 | 2771 @code{point-entered} hooks are not run, and the @code{intangible} |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2772 property has no effect. Do not set this variable globally; bind it with |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2773 @code{let}. |
6558 | 2774 @end defvar |
2775 | |
12067 | 2776 @node Format Properties |
12098 | 2777 @subsection Formatted Text Properties |
12067 | 2778 |
2779 These text properties affect the behavior of the fill commands. They | |
12098 | 2780 are used for representing formatted text. @xref{Filling}, and |
2781 @ref{Margins}. | |
2782 | |
2783 @table @code | |
12067 | 2784 @item hard |
2785 If a newline character has this property, it is a ``hard'' newline. | |
2786 The fill commands do not alter hard newlines and do not move words | |
2787 across them. However, this property takes effect only if the variable | |
2788 @code{use-hard-newlines} is non-@code{nil}. | |
2789 | |
2790 @item right-margin | |
12098 | 2791 This property specifies an extra right margin for filling this part of the |
12067 | 2792 text. |
2793 | |
2794 @item left-margin | |
12098 | 2795 This property specifies an extra left margin for filling this part of the |
12067 | 2796 text. |
2797 | |
2798 @item justification | |
2799 This property specifies the style of justification for filling this part | |
2800 of the text. | |
2801 @end table | |
2802 | |
6558 | 2803 @node Sticky Properties |
2804 @subsection Stickiness of Text Properties | |
2805 @cindex sticky text properties | |
2806 @cindex inheritance of text properties | |
2807 | |
2808 Self-inserting characters normally take on the same properties as the | |
2809 preceding character. This is called @dfn{inheritance} of properties. | |
2810 | |
2811 In a Lisp program, you can do insertion with inheritance or without, | |
2812 depending on your choice of insertion primitive. The ordinary text | |
2813 insertion functions such as @code{insert} do not inherit any properties. | |
2814 They insert text with precisely the properties of the string being | |
2815 inserted, and no others. This is correct for programs that copy text | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2816 from one context to another---for example, into or out of the kill ring. |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2817 To insert with inheritance, use the special primitives described in this |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2818 section. Self-inserting characters inherit properties because they work |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2819 using these primitives. |
6558 | 2820 |
2821 When you do insertion with inheritance, @emph{which} properties are | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2822 inherited, and from where, depends on which properties are @dfn{sticky}. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2823 Insertion after a character inherits those of its properties that are |
6558 | 2824 @dfn{rear-sticky}. Insertion before a character inherits those of its |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2825 properties that are @dfn{front-sticky}. When both sides offer different |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2826 sticky values for the same property, the previous character's value |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2827 takes precedence. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2828 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2829 By default, a text property is rear-sticky but not front-sticky; thus, |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2830 the default is to inherit all the properties of the preceding character, |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2831 and nothing from the following character. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2832 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2833 You can control the stickiness of various text properties with two |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2834 specific text properties, @code{front-sticky} and @code{rear-nonsticky}, |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2835 and with the variable @code{text-property-default-nonsticky}. You can |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2836 use the variable to specify a different default for a given property. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2837 You can use those two text properties to make any specific properties |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2838 sticky or nonsticky in any particular part of the text. |
6558 | 2839 |
2840 If a character's @code{front-sticky} property is @code{t}, then all | |
2841 its properties are front-sticky. If the @code{front-sticky} property is | |
2842 a list, then the sticky properties of the character are those whose | |
2843 names are in the list. For example, if a character has a | |
2844 @code{front-sticky} property whose value is @code{(face read-only)}, | |
2845 then insertion before the character can inherit its @code{face} property | |
2846 and its @code{read-only} property, but no others. | |
2847 | |
27374
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
2848 The @code{rear-nonsticky} property works the opposite way. Most |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
2849 properties are rear-sticky by default, so the @code{rear-nonsticky} |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
2850 property says which properties are @emph{not} rear-sticky. If a |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
2851 character's @code{rear-nonsticky} property is @code{t}, then none of its |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
2852 properties are rear-sticky. If the @code{rear-nonsticky} property is a |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
2853 list, properties are rear-sticky @emph{unless} their names are in the |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
2854 list. |
6558 | 2855 |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2856 @defvar text-property-default-nonsticky |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2857 @tindex text-property-default-nonsticky |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2858 This variable holds an alist which defines the default rear-stickiness |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2859 of various text properties. Each element has the form |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2860 @code{(@var{property} . @var{nonstickiness})}, and it defines the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2861 stickiness of a particular text property, @var{property}. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2862 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2863 If @var{nonstickiness} is non-@code{nil}, this means that the property |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2864 @var{property} is rear-nonsticky by default. Since all properties are |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2865 front-nonsticky by default, this makes @var{property} nonsticky in both |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2866 directions by default. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2867 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2868 The text properties @code{front-sticky} and @code{rear-nonsticky}, when |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2869 used, take precedence over the default @var{nonstickiness} specifed in |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2870 @code{text-property-default-nonsticky}. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
2871 @end defvar |
6558 | 2872 |
2873 Here are the functions that insert text with inheritance of properties: | |
2874 | |
2875 @defun insert-and-inherit &rest strings | |
2876 Insert the strings @var{strings}, just like the function @code{insert}, | |
2877 but inherit any sticky properties from the adjoining text. | |
2878 @end defun | |
2879 | |
2880 @defun insert-before-markers-and-inherit &rest strings | |
2881 Insert the strings @var{strings}, just like the function | |
2882 @code{insert-before-markers}, but inherit any sticky properties from the | |
2883 adjoining text. | |
2884 @end defun | |
2885 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2886 @xref{Insertion}, for the ordinary insertion functions which do not |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2887 inherit. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2888 |
6558 | 2889 @node Saving Properties |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
2890 @subsection Saving Text Properties in Files |
6558 | 2891 @cindex text properties in files |
2892 @cindex saving text properties | |
2893 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2894 You can save text properties in files (along with the text itself), |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2895 and restore the same text properties when visiting or inserting the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2896 files, using these two hooks: |
6558 | 2897 |
12098 | 2898 @defvar write-region-annotate-functions |
6558 | 2899 This variable's value is a list of functions for @code{write-region} to |
2900 run to encode text properties in some fashion as annotations to the text | |
2901 being written in the file. @xref{Writing to Files}. | |
2902 | |
2903 Each function in the list is called with two arguments: the start and | |
2904 end of the region to be written. These functions should not alter the | |
2905 contents of the buffer. Instead, they should return lists indicating | |
2906 annotations to write in the file in addition to the text in the | |
2907 buffer. | |
2908 | |
2909 Each function should return a list of elements of the form | |
2910 @code{(@var{position} . @var{string})}, where @var{position} is an | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2911 integer specifying the relative position within the text to be written, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2912 and @var{string} is the annotation to add there. |
6558 | 2913 |
2914 Each list returned by one of these functions must be already sorted in | |
2915 increasing order by @var{position}. If there is more than one function, | |
2916 @code{write-region} merges the lists destructively into one sorted list. | |
2917 | |
2918 When @code{write-region} actually writes the text from the buffer to the | |
2919 file, it intermixes the specified annotations at the corresponding | |
2920 positions. All this takes place without modifying the buffer. | |
2921 @end defvar | |
2922 | |
2923 @defvar after-insert-file-functions | |
2924 This variable holds a list of functions for @code{insert-file-contents} | |
2925 to call after inserting a file's contents. These functions should scan | |
2926 the inserted text for annotations, and convert them to the text | |
2927 properties they stand for. | |
2928 | |
2929 Each function receives one argument, the length of the inserted text; | |
2930 point indicates the start of that text. The function should scan that | |
2931 text for annotations, delete them, and create the text properties that | |
2932 the annotations specify. The function should return the updated length | |
2933 of the inserted text, as it stands after those changes. The value | |
2934 returned by one function becomes the argument to the next function. | |
2935 | |
2936 These functions should always return with point at the beginning of | |
2937 the inserted text. | |
2938 | |
2939 The intended use of @code{after-insert-file-functions} is for converting | |
2940 some sort of textual annotations into actual text properties. But other | |
2941 uses may be possible. | |
2942 @end defvar | |
2943 | |
2944 We invite users to write Lisp programs to store and retrieve text | |
2945 properties in files, using these hooks, and thus to experiment with | |
2946 various data formats and find good ones. Eventually we hope users | |
2947 will produce good, general extensions we can install in Emacs. | |
2948 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2949 We suggest not trying to handle arbitrary Lisp objects as text property |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2950 names or values---because a program that general is probably difficult |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2951 to write, and slow. Instead, choose a set of possible data types that |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
2952 are reasonably flexible, and not too hard to encode. |
6558 | 2953 |
12098 | 2954 @xref{Format Conversion}, for a related feature. |
2955 | |
2956 @c ??? In next edition, merge this info Format Conversion. | |
2957 | |
15760
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2958 @node Lazy Properties |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2959 @subsection Lazy Computation of Text Properties |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2960 |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2961 Instead of computing text properties for all the text in the buffer, |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2962 you can arrange to compute the text properties for parts of the text |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2963 when and if something depends on them. |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2964 |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2965 The primitive that extracts text from the buffer along with its |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2966 properties is @code{buffer-substring}. Before examining the properties, |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2967 this function runs the abnormal hook @code{buffer-access-fontify-functions}. |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2968 |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2969 @defvar buffer-access-fontify-functions |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2970 This variable holds a list of functions for computing text properties. |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2971 Before @code{buffer-substring} copies the text and text properties for a |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2972 portion of the buffer, it calls all the functions in this list. Each of |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2973 the functions receives two arguments that specify the range of the |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2974 buffer being accessed. (The buffer itself is always the current |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2975 buffer.) |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2976 @end defvar |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2977 |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2978 The function @code{buffer-substring-no-properties} does not call these |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2979 functions, since it ignores text properties anyway. |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2980 |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2981 In order to prevent the hook functions from being called more than |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2982 once for the same part of the buffer, you can use the variable |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2983 @code{buffer-access-fontified-property}. |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2984 |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2985 @defvar buffer-access-fontified-property |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2986 If this value's variable is non-@code{nil}, it is a symbol which is used |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2987 as a text property name. A non-@code{nil} value for that text property |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2988 means, ``the other text properties for this character have already been |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2989 computed.'' |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2990 |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2991 If all the characters in the range specified for @code{buffer-substring} |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2992 have a non-@code{nil} value for this property, @code{buffer-substring} |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2993 does not call the @code{buffer-access-fontify-functions} functions. It |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2994 assumes these characters already have the right text properties, and |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2995 just copies the properties they already have. |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2996 |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2997 The normal way to use this feature is that the |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2998 @code{buffer-access-fontify-functions} functions add this property, as |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
2999 well as others, to the characters they operate on. That way, they avoid |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
3000 being called over and over for the same text. |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
3001 @end defvar |
0489cb739a5f
(Lazy Properties): New node.
Richard M. Stallman <rms@gnu.org>
parents:
13109
diff
changeset
|
3002 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3003 @node Clickable Text |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3004 @subsection Defining Clickable Text |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3005 @cindex clickable text |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3006 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3007 There are two ways to set up @dfn{clickable text} in a buffer. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3008 There are typically two parts of this: to make the text highlight |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3009 when the mouse is over it, and to make a mouse button do something |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3010 when you click it on that part of the text. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3011 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3012 Highlighting is done with the @code{mouse-face} text property. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3013 Here is an example of how Dired does it: |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3014 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3015 @smallexample |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3016 (condition-case nil |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3017 (if (dired-move-to-filename) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3018 (put-text-property (point) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3019 (save-excursion |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3020 (dired-move-to-end-of-filename) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3021 (point)) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3022 'mouse-face 'highlight)) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3023 (error nil)) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3024 @end smallexample |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3025 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3026 @noindent |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3027 The first two arguments to @code{put-text-property} specify the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3028 beginning and end of the text. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3029 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3030 The usual way to make the mouse do something when you click it |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3031 on this text is to define @code{mouse-2} in the major mode's |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3032 keymap. The job of checking whether the click was on clickable text |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3033 is done by the command definition. Here is how Dired does it: |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3034 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3035 @smallexample |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3036 (defun dired-mouse-find-file-other-window (event) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3037 "In dired, visit the file or directory name you click on." |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3038 (interactive "e") |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3039 (let (file) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3040 (save-excursion |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3041 (set-buffer (window-buffer (posn-window (event-end event)))) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3042 (save-excursion |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3043 (goto-char (posn-point (event-end event))) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3044 (setq file (dired-get-filename)))) |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3045 (select-window (posn-window (event-end event))) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3046 (find-file-other-window (file-name-sans-versions file t)))) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3047 @end smallexample |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3048 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3049 @noindent |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3050 The reason for the outer @code{save-excursion} construct is to avoid |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3051 changing the current buffer; the reason for the inner one is to avoid |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3052 permanently altering point in the buffer you click on. In this case, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3053 Dired uses the function @code{dired-get-filename} to determine which |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3054 file to visit, based on the position found in the event. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3055 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3056 Instead of defining a mouse command for the major mode, you can define |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3057 a key binding for the clickable text itself, using the @code{local-map} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3058 text property: |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3059 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3060 @example |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3061 (let ((map (make-sparse-keymap))) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3062 (define-key-binding map [mouse-2] 'operate-this-button) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3063 (put-text-property (point) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3064 (save-excursion |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3065 (dired-move-to-end-of-filename) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3066 (point)) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3067 'local-map map)) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3068 @end example |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3069 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3070 @noindent |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3071 This method makes it possible to define different commands for various |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3072 clickable pieces of text. Also, the major mode definition (or the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3073 global definition) remains available for the rest of the text in the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3074 buffer. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3075 |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3076 @node Fields |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3077 @subsection Defining and Using Fields |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3078 @cindex fields |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3079 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3080 A field is a range of consecutive characters in the buffer that are |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3081 identified by having the same value (comparing with @code{eq}) of the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3082 @code{field} property. This section describes special functions that |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3083 are available for operating on fields. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3084 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3085 You specify a field with a buffer position, @var{pos}. We think of |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3086 each field as containing a range of buffer positions, so the position |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3087 you specify stands for the field containing that position. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3088 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3089 When the characters before and after @var{pos} are part of the same |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3090 field, there is no doubt which field contains @var{pos}: the one those |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3091 characters both belong to. When @var{pos} is at a boundary between |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3092 fields, which field it belongs to depends on the stickiness of the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3093 @code{field} properties of the two surrounding characters (@pxref{Sticky |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3094 Properties}). The field whose property would be inherited by text |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3095 inserted at @var{pos} is the field that contains @var{pos}. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3096 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3097 There is an anomalous case where newly inserted text at @var{pos} |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3098 would not inherit the @code{field} property from either side. This |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3099 happens if the previous character's @code{field} property is not |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3100 rear-sticky, and the following character's @code{field} property is not |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3101 front-sticky. In this case, @var{pos} belongs to neither the preceding |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3102 field nor the following field; the field functions treat it as belonging |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3103 to an empty field whose beginning and end are both at @var{pos}. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3104 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3105 In all of these functions, if @var{pos} is omitted or @code{nil}, the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3106 value of point is used by default. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3107 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3108 @defun field-beginning &optional pos escape-from-edge |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3109 @tindex field-beginning |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3110 This function returns the beginning of the field specified by @var{pos}. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3111 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3112 If @var{pos} is at the end of a field, and @var{escape-from-edge} is |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3113 non-@code{nil}, then the return value is always the beginning of the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3114 field that @emph{ends} at @var{pos}, regardless of the stickiness of the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3115 @code{field} properties around @var{pos}. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3116 @end defun |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3117 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3118 @defun field-end &optional pos escape-from-edge |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3119 @tindex field-end |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3120 This function returns the end of the field specified by @var{pos}. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3121 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3122 If @var{pos} is at the beginning of a field, and @var{escape-from-edge} |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3123 is non-@code{nil}, then the return value is always the end of the field |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3124 that @emph{begins} at @var{pos}, regardless of the stickiness of the |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3125 @code{field} properties around @var{pos}. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3126 @end defun |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3127 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3128 @defun field-string &optional pos |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3129 @tindex field-string |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3130 This function returns the contents of the field specified by @var{pos}, |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3131 as a string. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3132 @end defun |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3133 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3134 @defun field-string-no-properties &optional pos |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3135 @tindex field-string-no-properties |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3136 This function returns the contents of the field specified by @var{pos}, |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3137 as a string, discarding text properties. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3138 @end defun |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3139 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3140 @defun delete-field &optional pos |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3141 @tindex delete-field |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3142 This function deletes the text of the field specified by @var{pos}. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3143 @end defun |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3144 |
27093
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3145 @deffn beginning-of-line-or-field &optional count |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3146 @tindex beginning-of-line-or-field |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3147 Like @code{beginning-of-line}, except that this function does not move |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3148 across a field boundary (@pxref{Fields}), unless it moves to another |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3149 line beyond the one that contains the field boundary. Therefore, if |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3150 @var{count} is zero, and point is initially at a field boundary, point |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3151 does not move. |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3152 @end deffn |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3153 |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3154 @deffn end-of-line-or-field &optional count |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3155 @tindex end-of-line-or-field |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3156 Like @code{end-of-line}, except that this function does not move |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3157 across a field boundary (@pxref{Fields}), unless it moves to another |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3158 line beyond the one that contains the field boundary. |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3159 @end deffn |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
26696
diff
changeset
|
3160 |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3161 @defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3162 @tindex constrain-to-field |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3163 This function ``constrains'' @var{new-pos} to the field that |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3164 @var{old-pos} belongs to---in other words, it returns the position |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3165 closest to @var{new-pos} that is in the same field as @var{old-pos}. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3166 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3167 If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3168 the value of point instead, and moves point to the resulting position. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3169 |
27374
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
3170 If @var{old-pos} is at the boundary of two fields, then the acceptable |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
3171 positions for @var{new-pos} depend on the value of the optional argument |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
3172 @var{escape-from-edge}. If @var{escape-from-edge} is @code{nil}, then |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
3173 @var{new-pos} is constrained to the field that has the same @code{field} |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
3174 text-property that new characters inserted at @var{old-pos} would get. |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
3175 (This depends on the stickiness of the @code{field} property for the |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
3176 characters before and after @var{old-pos}.) If @var{escape-from-edge} |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
3177 is non-@code{nil}, @var{new-pos} is constrained to the union of the two |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
3178 adjacent fields. |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3179 |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3180 If the optional argument @var{only-in-line} is non-@code{nil}, and |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3181 constraining @var{new-pos} in the usual way would move it to a different |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3182 line, @var{new-pos} is returned unconstrained. This used in commands |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3183 that move by line, such as @code{next-line} and |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3184 @code{beginning-of-line}, so that they respect field boundaries only in |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3185 the case where they can still move to the right line. |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3186 @end defun |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3187 |
6558 | 3188 @node Not Intervals |
3189 @subsection Why Text Properties are not Intervals | |
3190 @cindex intervals | |
3191 | |
3192 Some editors that support adding attributes to text in the buffer do | |
3193 so by letting the user specify ``intervals'' within the text, and adding | |
3194 the properties to the intervals. Those editors permit the user or the | |
3195 programmer to determine where individual intervals start and end. We | |
3196 deliberately provided a different sort of interface in Emacs Lisp to | |
3197 avoid certain paradoxical behavior associated with text modification. | |
3198 | |
3199 If the actual subdivision into intervals is meaningful, that means you | |
3200 can distinguish between a buffer that is just one interval with a | |
3201 certain property, and a buffer containing the same text subdivided into | |
3202 two intervals, both of which have that property. | |
3203 | |
3204 Suppose you take the buffer with just one interval and kill part of | |
3205 the text. The text remaining in the buffer is one interval, and the | |
3206 copy in the kill ring (and the undo list) becomes a separate interval. | |
3207 Then if you yank back the killed text, you get two intervals with the | |
3208 same properties. Thus, editing does not preserve the distinction | |
3209 between one interval and two. | |
3210 | |
3211 Suppose we ``fix'' this problem by coalescing the two intervals when | |
3212 the text is inserted. That works fine if the buffer originally was a | |
3213 single interval. But suppose instead that we have two adjacent | |
3214 intervals with the same properties, and we kill the text of one interval | |
3215 and yank it back. The same interval-coalescence feature that rescues | |
3216 the other case causes trouble in this one: after yanking, we have just | |
3217 one interval. One again, editing does not preserve the distinction | |
3218 between one interval and two. | |
3219 | |
3220 Insertion of text at the border between intervals also raises | |
3221 questions that have no satisfactory answer. | |
3222 | |
3223 However, it is easy to arrange for editing to behave consistently for | |
3224 questions of the form, ``What are the properties of this character?'' | |
3225 So we have decided these are the only questions that make sense; we have | |
3226 not implemented asking questions about where intervals start or end. | |
3227 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3228 In practice, you can usually use the text property search functions in |
6558 | 3229 place of explicit interval boundaries. You can think of them as finding |
3230 the boundaries of intervals, assuming that intervals are always | |
3231 coalesced whenever possible. @xref{Property Search}. | |
3232 | |
3233 Emacs also provides explicit intervals as a presentation feature; see | |
3234 @ref{Overlays}. | |
3235 | |
3236 @node Substitution | |
3237 @section Substituting for a Character Code | |
3238 | |
3239 The following functions replace characters within a specified region | |
3240 based on their character codes. | |
3241 | |
3242 @defun subst-char-in-region start end old-char new-char &optional noundo | |
3243 @cindex replace characters | |
3244 This function replaces all occurrences of the character @var{old-char} | |
3245 with the character @var{new-char} in the region of the current buffer | |
3246 defined by @var{start} and @var{end}. | |
3247 | |
3248 @cindex undo avoidance | |
12098 | 3249 If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does |
3250 not record the change for undo and does not mark the buffer as modified. | |
26696
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3251 This was useful for controlling the old selective display feature |
ef5e7bbe6f19
Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents:
25875
diff
changeset
|
3252 (@pxref{Selective Display}). |
6558 | 3253 |
3254 @code{subst-char-in-region} does not move point and returns | |
3255 @code{nil}. | |
3256 | |
3257 @example | |
3258 @group | |
3259 ---------- Buffer: foo ---------- | |
3260 This is the contents of the buffer before. | |
3261 ---------- Buffer: foo ---------- | |
3262 @end group | |
3263 | |
3264 @group | |
3265 (subst-char-in-region 1 20 ?i ?X) | |
3266 @result{} nil | |
3267 | |
3268 ---------- Buffer: foo ---------- | |
3269 ThXs Xs the contents of the buffer before. | |
3270 ---------- Buffer: foo ---------- | |
3271 @end group | |
3272 @end example | |
3273 @end defun | |
3274 | |
3275 @defun translate-region start end table | |
3276 This function applies a translation table to the characters in the | |
3277 buffer between positions @var{start} and @var{end}. | |
3278 | |
3279 The translation table @var{table} is a string; @code{(aref @var{table} | |
3280 @var{ochar})} gives the translated character corresponding to | |
3281 @var{ochar}. If the length of @var{table} is less than 256, any | |
3282 characters with codes larger than the length of @var{table} are not | |
3283 altered by the translation. | |
3284 | |
3285 The return value of @code{translate-region} is the number of | |
8427
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
3286 characters that were actually changed by the translation. This does |
bc548090f760
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7735
diff
changeset
|
3287 not count characters that were mapped into themselves in the |
6558 | 3288 translation table. |
3289 @end defun | |
3290 | |
3291 @node Registers | |
3292 @section Registers | |
3293 @cindex registers | |
3294 | |
3295 A register is a sort of variable used in Emacs editing that can hold a | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3296 variety of different kinds of values. Each register is named by a |
27374
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
3297 single character. All @sc{ascii} characters and their meta variants |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
3298 (but with the exception of @kbd{C-g}) can be used to name registers. |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
3299 Thus, there are 255 possible registers. A register is designated in |
0f5edee5242b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
3300 Emacs Lisp by the character that is its name. |
6558 | 3301 |
3302 @defvar register-alist | |
3303 This variable is an alist of elements of the form @code{(@var{name} . | |
3304 @var{contents})}. Normally, there is one element for each Emacs | |
3305 register that has been used. | |
3306 | |
3307 The object @var{name} is a character (an integer) identifying the | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3308 register. |
6558 | 3309 @end defvar |
3310 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3311 The @var{contents} of a register can have several possible types: |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3312 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3313 @table @asis |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3314 @item a number |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3315 A number stands for itself. If @code{insert-register} finds a number |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3316 in the register, it converts the number to decimal. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3317 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3318 @item a marker |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3319 A marker represents a buffer position to jump to. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3320 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3321 @item a string |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3322 A string is text saved in the register. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3323 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3324 @item a rectangle |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3325 A rectangle is represented by a list of strings. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3326 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3327 @item @code{(@var{window-configuration} @var{position})} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3328 This represents a window configuration to restore in one frame, and a |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3329 position to jump to in the current buffer. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3330 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3331 @item @code{(@var{frame-configuration} @var{position})} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3332 This represents a frame configuration to restore, and a position |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3333 to jump to in the current buffer. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3334 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3335 @item (file @var{filename}) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3336 This represents a file to visit; jumping to this value visits file |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3337 @var{filename}. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3338 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3339 @item (file-query @var{filename} @var{position}) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3340 This represents a file to visit and a position in it; jumping to this |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3341 value visits file @var{filename} and goes to buffer position |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3342 @var{position}. Restoring this type of position asks the user for |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3343 confirmation first. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3344 @end table |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3345 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3346 The functions in this section return unpredictable values unless |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3347 otherwise stated. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3348 |
6558 | 3349 @defun get-register reg |
3350 This function returns the contents of the register | |
3351 @var{reg}, or @code{nil} if it has no contents. | |
3352 @end defun | |
3353 | |
3354 @defun set-register reg value | |
3355 This function sets the contents of register @var{reg} to @var{value}. | |
3356 A register can be set to any value, but the other register functions | |
3357 expect only certain data types. The return value is @var{value}. | |
3358 @end defun | |
3359 | |
3360 @deffn Command view-register reg | |
3361 This command displays what is contained in register @var{reg}. | |
3362 @end deffn | |
3363 | |
3364 @ignore | |
3365 @deffn Command point-to-register reg | |
3366 This command stores both the current location of point and the current | |
3367 buffer in register @var{reg} as a marker. | |
3368 @end deffn | |
3369 | |
3370 @deffn Command jump-to-register reg | |
3371 @deffnx Command register-to-point reg | |
3372 @comment !!SourceFile register.el | |
3373 This command restores the status recorded in register @var{reg}. | |
3374 | |
3375 If @var{reg} contains a marker, it moves point to the position stored in | |
3376 the marker. Since both the buffer and the location within the buffer | |
3377 are stored by the @code{point-to-register} function, this command can | |
3378 switch you to another buffer. | |
3379 | |
3380 If @var{reg} contains a window configuration or a frame configuration. | |
3381 @code{jump-to-register} restores that configuration. | |
3382 @end deffn | |
3383 @end ignore | |
3384 | |
3385 @deffn Command insert-register reg &optional beforep | |
3386 This command inserts contents of register @var{reg} into the current | |
3387 buffer. | |
3388 | |
3389 Normally, this command puts point before the inserted text, and the | |
3390 mark after it. However, if the optional second argument @var{beforep} | |
3391 is non-@code{nil}, it puts the mark before and point after. | |
3392 You can pass a non-@code{nil} second argument @var{beforep} to this | |
3393 function interactively by supplying any prefix argument. | |
3394 | |
3395 If the register contains a rectangle, then the rectangle is inserted | |
3396 with its upper left corner at point. This means that text is inserted | |
3397 in the current line and underneath it on successive lines. | |
3398 | |
3399 If the register contains something other than saved text (a string) or | |
3400 a rectangle (a list), currently useless things happen. This may be | |
3401 changed in the future. | |
3402 @end deffn | |
3403 | |
3404 @ignore | |
3405 @deffn Command copy-to-register reg start end &optional delete-flag | |
3406 This command copies the region from @var{start} to @var{end} into | |
3407 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes | |
3408 the region from the buffer after copying it into the register. | |
3409 @end deffn | |
3410 | |
3411 @deffn Command prepend-to-register reg start end &optional delete-flag | |
3412 This command prepends the region from @var{start} to @var{end} into | |
3413 register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes | |
3414 the region from the buffer after copying it to the register. | |
3415 @end deffn | |
3416 | |
3417 @deffn Command append-to-register reg start end &optional delete-flag | |
3418 This command appends the region from @var{start} to @var{end} to the | |
3419 text already in register @var{reg}. If @var{delete-flag} is | |
3420 non-@code{nil}, it deletes the region from the buffer after copying it | |
3421 to the register. | |
3422 @end deffn | |
3423 | |
3424 @deffn Command copy-rectangle-to-register reg start end &optional delete-flag | |
3425 This command copies a rectangular region from @var{start} to @var{end} | |
3426 into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it | |
3427 deletes the region from the buffer after copying it to the register. | |
3428 @end deffn | |
3429 | |
3430 @deffn Command window-configuration-to-register reg | |
3431 This function stores the window configuration of the selected frame in | |
3432 register @var{reg}. | |
3433 @end deffn | |
3434 | |
3435 @deffn Command frame-configuration-to-register reg | |
3436 This function stores the current frame configuration in register | |
3437 @var{reg}. | |
3438 @end deffn | |
3439 @end ignore | |
3440 | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3441 @node Transposition |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3442 @section Transposition of Text |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3443 |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3444 This subroutine is used by the transposition commands. |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3445 |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3446 @defun transpose-regions start1 end1 start2 end2 &optional leave-markers |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3447 This function exchanges two nonoverlapping portions of the buffer. |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3448 Arguments @var{start1} and @var{end1} specify the bounds of one portion |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3449 and arguments @var{start2} and @var{end2} specify the bounds of the |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3450 other portion. |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3451 |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3452 Normally, @code{transpose-regions} relocates markers with the transposed |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3453 text; a marker previously positioned within one of the two transposed |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3454 portions moves along with that portion, thus remaining between the same |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3455 two characters in their new position. However, if @var{leave-markers} |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3456 is non-@code{nil}, @code{transpose-regions} does not do this---it leaves |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3457 all markers unrelocated. |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3458 @end defun |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3459 |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3460 @node Base 64 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3461 @section Base 64 Encoding |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3462 @cindex base 64 encoding |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3463 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3464 Base 64 code is used in email to encode a sequence of 8-bit bytes as a |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
3465 longer sequence of @sc{ascii} graphic characters. This section |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3466 describes the functions for converting to and from this code. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3467 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3468 @defun base64-encode-region beg end &optional no-line-break |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3469 @tindex base64-encode-region |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3470 This function converts the region from @var{beg} to @var{end} |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3471 into base 64 code. It returns the length of the encoded text. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3472 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3473 Normally, this function inserts newline characters into the encoded |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3474 text, to avoid overlong lines. However, if the optional argument |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3475 @var{no-line-break} is non-@code{nil}, these newlines are not added, so |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3476 the output is just one long line. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3477 @end defun |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3478 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3479 @defun base64-encode-string string &optional no-line-break |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3480 @tindex base64-encode-string |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3481 This function converts the string @var{string} into base 64 code. It |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3482 returns a string containing the encoded text. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3483 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3484 Normally, this function inserts newline characters into the encoded |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3485 text, to avoid overlong lines. However, if the optional argument |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3486 @var{no-line-break} is non-@code{nil}, these newlines are not added, so |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3487 the result string is just one long line. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3488 @end defun |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3489 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3490 @defun base64-decode-region beg end |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3491 @tindex base64-decode-region |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3492 This function converts the region from @var{beg} to @var{end} from base |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3493 64 code into the corresponding decoded text. It returns the length of |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3494 the decoded text. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3495 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3496 The decoding functions ignore newline characters in the encoded text. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3497 @end defun |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3498 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3499 @defun base64-decode-string string |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3500 @tindex base64-decode-string |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3501 This function converts the string @var{string} from base 64 code into |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3502 the corresponding decoded text. It returns a string containing the |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3503 decoded text. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3504 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3505 The decoding functions ignore newline characters in the encoded text. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3506 @end defun |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23147
diff
changeset
|
3507 |
6558 | 3508 @node Change Hooks |
3509 @section Change Hooks | |
3510 @cindex change hooks | |
3511 @cindex hooks for text changes | |
3512 | |
3513 These hook variables let you arrange to take notice of all changes in | |
3514 all buffers (or in a particular buffer, if you make them buffer-local). | |
3515 See also @ref{Special Properties}, for how to detect changes to specific | |
3516 parts of the text. | |
3517 | |
3518 The functions you use in these hooks should save and restore the match | |
3519 data if they do anything that uses regular expressions; otherwise, they | |
3520 will interfere in bizarre ways with the editing operations that call | |
3521 them. | |
3522 | |
6782
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3523 @defvar before-change-functions |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3524 This variable holds a list of functions to call before any buffer |
6782
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3525 modification. Each function gets two arguments, the beginning and end |
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3526 of the region that is about to change, represented as integers. The |
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3527 buffer that is about to change is always the current buffer. |
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3528 @end defvar |
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3529 |
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3530 @defvar after-change-functions |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3531 This variable holds a list of functions to call after any buffer |
6782
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3532 modification. Each function receives three arguments: the beginning and |
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3533 end of the region just changed, and the length of the text that existed |
19467
d76f57ca7aba
Explain after-change-functions and chars vs bytes.
Richard M. Stallman <rms@gnu.org>
parents:
18339
diff
changeset
|
3534 before the change. All three arguments are integers. The buffer that's |
d76f57ca7aba
Explain after-change-functions and chars vs bytes.
Richard M. Stallman <rms@gnu.org>
parents:
18339
diff
changeset
|
3535 about to change is always the current buffer. |
d76f57ca7aba
Explain after-change-functions and chars vs bytes.
Richard M. Stallman <rms@gnu.org>
parents:
18339
diff
changeset
|
3536 |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
3537 The length of the old text is the difference between the buffer positions |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
3538 before and after that text as it was before the change. As for the |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
3539 changed text, its length is simply the difference between the first two |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
3540 arguments. |
6782
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3541 @end defvar |
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3542 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
3543 @defmac combine-after-change-calls body... |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3544 The macro executes @var{body} normally, but arranges to call the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3545 after-change functions just once for a series of several changes---if |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3546 that seems safe. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3547 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3548 If a program makes several text changes in the same area of the buffer, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3549 using the macro @code{combine-after-change-calls} around that part of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3550 the program can make it run considerably faster when after-change hooks |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3551 are in use. When the after-change hooks are ultimately called, the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3552 arguments specify a portion of the buffer including all of the changes |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3553 made within the @code{combine-after-change-calls} body. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3554 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3555 @strong{Warning:} You must not alter the values of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3556 @code{after-change-functions} and @code{after-change-function} within |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3557 the body of a @code{combine-after-change-calls} form. |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3558 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3559 @strong{Note:} If the changes you combine occur in widely scattered |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3560 parts of the buffer, this will still work, but it is not advisable, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3561 because it may lead to inefficient behavior for some change hook |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3562 functions. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3563 @end defmac |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
19467
diff
changeset
|
3564 |
6558 | 3565 @defvar before-change-function |
12098 | 3566 This obsolete variable holds one function to call before any buffer |
3567 modification (or @code{nil} for no function). It is called just like | |
3568 the functions in @code{before-change-functions}. | |
6558 | 3569 @end defvar |
3570 | |
3571 @defvar after-change-function | |
12098 | 3572 This obsolete variable holds one function to call after any buffer modification |
6782
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3573 (or @code{nil} for no function). It is called just like the functions in |
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3574 @code{after-change-functions}. |
6558 | 3575 @end defvar |
3576 | |
6782
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3577 The four variables above are temporarily bound to @code{nil} during the |
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3578 time that any of these functions is running. This means that if one of |
6558 | 3579 these functions changes the buffer, that change won't run these |
6782
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3580 functions. If you do want a hook function to make changes that run |
5b07647ec8f7
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
3581 these functions, make it bind these variables back to their usual |
6558 | 3582 values. |
3583 | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3584 One inconvenient result of this protective feature is that you cannot |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3585 have a function in @code{after-change-functions} or |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3586 @code{before-change-functions} which changes the value of that variable. |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3587 But that's not a real limitation. If you want those functions to change |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3588 the list of functions to run, simply add one fixed function to the hook, |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3589 and code that function to look in another variable for other functions |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3590 to call. Here is an example: |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3591 |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3592 @example |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3593 (setq my-own-after-change-functions nil) |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3594 (defun indirect-after-change-function (beg end len) |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3595 (let ((list my-own-after-change-functions)) |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3596 (while list |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3597 (funcall (car list) beg end len) |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3598 (setq list (cdr list))))) |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3599 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3600 @group |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3601 (add-hooks 'after-change-functions |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3602 'indirect-after-change-function) |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
3603 @end group |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3604 @end example |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6782
diff
changeset
|
3605 |
6558 | 3606 @defvar first-change-hook |
3607 This variable is a normal hook that is run whenever a buffer is changed | |
3608 that was previously in the unmodified state. | |
3609 @end defvar | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
3610 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
3611 @defvar inhibit-modification-hooks |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
3612 @tindex inhibit-modification-hooks |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
3613 If this variable is non-@code{nil}, all of the change hooks are |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
3614 disabled; none of them run. This affects all the hook variables |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
3615 described above in this section, as well as the hooks attached to |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
3616 certain special text properties (@pxref{Special Properties}) and overlay |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
3617 properties (@pxref{Overlay Properties}). |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
3618 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
3619 This variable is available starting in Emacs 21. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25454
diff
changeset
|
3620 @end defvar |