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