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