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