info/lispref.info-29

   1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
   2 lispref/lispref.texi.
   3
   4 INFO-DIR-SECTION XEmacs Editor
   5 START-INFO-DIR-ENTRY
   6 * Lispref: (lispref).           XEmacs Lisp Reference Manual.
   7 END-INFO-DIR-ENTRY
   8
   9    Edition History:
  10
  11    GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
  12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
  13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
  14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
  15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
  16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
  17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
  18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
  19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
  20
  21    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
  22 Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
  23 Copyright (C) 1995, 1996 Ben Wing.
  24
  25    Permission is granted to make and distribute verbatim copies of this
  26 manual provided the copyright notice and this permission notice are
  27 preserved on all copies.
  28
  29    Permission is granted to copy and distribute modified versions of
  30 this manual under the conditions for verbatim copying, provided that the
  31 entire resulting derived work is distributed under the terms of a
  32 permission notice identical to this one.
  33
  34    Permission is granted to copy and distribute translations of this
  35 manual into another language, under the above conditions for modified
  36 versions, except that this permission notice may be stated in a
  37 translation approved by the Foundation.
  38
  39    Permission is granted to copy and distribute modified versions of
  40 this manual under the conditions for verbatim copying, provided also
  41 that the section entitled "GNU General Public License" is included
  42 exactly as in the original, and provided that the entire resulting
  43 derived work is distributed under the terms of a permission notice
  44 identical to this one.
  45
  46    Permission is granted to copy and distribute translations of this
  47 manual into another language, under the above conditions for modified
  48 versions, except that the section entitled "GNU General Public License"
  49 may be included in a translation approved by the Free Software
  50 Foundation instead of in the original English.
  51
  52 \1f
  53 File: lispref.info,  Node: The Mark,  Next: The Region,  Prev: Changing Markers,  Up: Markers
  54
  55 The Mark
  56 ========
  57
  58    One special marker in each buffer is designated "the mark".  It
  59 records a position for the user for the sake of commands such as `C-w'
  60 and `C-x <TAB>'.  Lisp programs should set the mark only to values that
  61 have a potential use to the user, and never for their own internal
  62 purposes.  For example, the `replace-regexp' command sets the mark to
  63 the value of point before doing any replacements, because this enables
  64 the user to move back there conveniently after the replace is finished.
  65
  66    Once the mark "exists" in a buffer, it normally never ceases to
  67 exist.  However, it may become "inactive", and usually does so after
  68 each command (other than simple motion commands and some commands that
  69 explicitly activate the mark).  When the mark is active, the region
  70 between point and the mark is called the "active region" and is
  71 highlighted specially.
  72
  73    Many commands are designed so that when called interactively they
  74 operate on the text between point and the mark.  Such commands work
  75 only when an active region exists, i.e. when the mark is active.  (The
  76 reason for this is to prevent you from accidentally deleting or
  77 changing large chunks of your text.) If you are writing such a command,
  78 don't examine the mark directly; instead, use `interactive' with the
  79 `r' specification.  This provides the values of point and the mark as
  80 arguments to the command in an interactive call, but permits other Lisp
  81 programs to specify arguments explicitly, and automatically signals an
  82 error if the command is called interactively when no active region
  83 exists.  *Note Interactive Codes::.
  84
  85    Each buffer has its own value of the mark that is independent of the
  86 value of the mark in other buffers. (When a buffer is created, the mark
  87 exists but does not point anywhere.  We consider this state as "the
  88 absence of a mark in that buffer.") However, only one active region can
  89 exist at a time.  Activating the mark in one buffer automatically
  90 deactivates an active mark in any other buffer.  Note that the user can
  91 explicitly activate a mark at any time by using the command
  92 `activate-region' (normally bound to `M-C-z') or by using the command
  93 `exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
  94 side effect of activating the mark.
  95
  96    Some people do not like active regions, so they disable this behavior
  97 by setting the variable `zmacs-regions' to `nil'.  This makes the mark
  98 always active (except when a buffer is just created and the mark points
  99 nowhere), and turns off the highlighting of the region between point
 100 and the mark.  Commands that explicitly retrieve the value of the mark
 101 should make sure that they behave correctly and consistently
 102 irrespective of the setting of `zmacs-regions'; some primitives are
 103 provided to ensure this behavior.
 104
 105    In addition to the mark, each buffer has a "mark ring" which is a
 106 list of markers containing previous values of the mark.  When editing
 107 commands change the mark, they should normally save the old value of the
 108 mark on the mark ring.  The variable `mark-ring-max' specifies the
 109 maximum number of entries in the mark ring; once the list becomes this
 110 long, adding a new element deletes the last element.
 111
 112  - Function: mark &optional force buffer
 113      This function returns BUFFER's mark position as an integer.
 114      BUFFER defaults to the current buffer if omitted.
 115
 116      If the mark is inactive, `mark' normally returns `nil'.  However,
 117      if FORCE is non-`nil', then `mark' returns the mark position
 118      anyway--or `nil', if the mark is not yet set for the buffer.
 119
 120      (Remember that if ZMACS-REGIONS is `nil', the mark is always
 121      active as long as it exists, and the FORCE argument will have no
 122      effect.)
 123
 124      If you are using this in an editing command, you are most likely
 125      making a mistake; see the documentation of `set-mark' below.
 126
 127  - Function: mark-marker inactive-p buffer
 128      This function returns BUFFER's mark.  BUFFER defaults to the
 129      current buffer if omitted.  This is the very marker that records
 130      the mark location inside XEmacs, not a copy.  Therefore, changing
 131      this marker's position will directly affect the position of the
 132      mark.  Don't do it unless that is the effect you want.
 133
 134      If the mark is inactive, `mark-marker' normally returns `nil'.
 135      However, if FORCE is non-`nil', then `mark-marker' returns the
 136      mark anyway.
 137           (setq m (mark-marker))
 138                => #<marker at 3420 in markers.texi>
 139           (set-marker m 100)
 140                => #<marker at 100 in markers.texi>
 141           (mark-marker)
 142                => #<marker at 100 in markers.texi>
 143
 144      Like any marker, this marker can be set to point at any buffer you
 145      like.  We don't recommend that you make it point at any buffer
 146      other than the one of which it is the mark.  If you do, it will
 147      yield perfectly consistent, but rather odd, results.
 148
 149  - Function: set-mark position &optional buffer
 150      This function sets `buffer''s mark to POSITION, and activates the
 151      mark.  BUFFER defaults to the current buffer if omitted.  The old
 152      value of the mark is _not_ pushed onto the mark ring.
 153
 154      *Please note:* Use this function only if you want the user to see
 155      that the mark has moved, and you want the previous mark position to
 156      be lost.  Normally, when a new mark is set, the old one should go
 157      on the `mark-ring'.  For this reason, most applications should use
 158      `push-mark' and `pop-mark', not `set-mark'.
 159
 160      Novice XEmacs Lisp programmers often try to use the mark for the
 161      wrong purposes.  The mark saves a location for the user's
 162      convenience.  An editing command should not alter the mark unless
 163      altering the mark is part of the user-level functionality of the
 164      command.  (And, in that case, this effect should be documented.)
 165      To remember a location for internal use in the Lisp program, store
 166      it in a Lisp variable.  For example:
 167
 168           (let ((beg (point)))
 169             (forward-line 1)
 170             (delete-region beg (point))).
 171
 172  - Command: exchange-point-and-mark &optional dont-activate-region
 173      This function exchanges the positions of point and the mark.  It
 174      is intended for interactive use.  The mark is also activated
 175      unless DONT-ACTIVATE-REGION is non-`nil'.
 176
 177  - Function: push-mark &optional position nomsg activate buffer
 178      This function sets BUFFER's mark to POSITION, and pushes a copy of
 179      the previous mark onto `mark-ring'.  BUFFER defaults to the
 180      current buffer if omitted.  If POSITION is `nil', then the value
 181      of point is used.  `push-mark' returns `nil'.
 182
 183      If the last global mark pushed was not in BUFFER, also push
 184      POSITION on the global mark ring (see below).
 185
 186      The function `push-mark' normally _does not_ activate the mark.
 187      To do that, specify `t' for the argument ACTIVATE.
 188
 189      A `Mark set' message is displayed unless NOMSG is non-`nil'.
 190
 191  - Function: pop-mark
 192      This function pops off the top element of `mark-ring' and makes
 193      that mark become the buffer's actual mark.  This does not move
 194      point in the buffer, and it does nothing if `mark-ring' is empty.
 195      It deactivates the mark.
 196
 197      The return value is not meaningful.
 198
 199  - Variable: mark-ring
 200      The value of this buffer-local variable is the list of saved former
 201      marks of the current buffer, most recent first.
 202
 203           mark-ring
 204           => (#<marker at 11050 in markers.texi>
 205               #<marker at 10832 in markers.texi>
 206               ...)
 207
 208  - User Option: mark-ring-max
 209      The value of this variable is the maximum size of `mark-ring'.  If
 210      more marks than this are pushed onto the `mark-ring', `push-mark'
 211      discards an old mark when it adds a new one.
 212
 213    In additional to a per-buffer mark ring, there is a "global mark
 214 ring".  Marks are pushed onto the global mark ring the first time you
 215 set a mark after switching buffers.
 216
 217  - Variable: global-mark-ring
 218      The value of this variable is the list of saved former global
 219      marks, most recent first.
 220
 221  - User Option: mark-ring-max
 222      The value of this variable is the maximum size of
 223      `global-mark-ring'.  If more marks than this are pushed onto the
 224      `global-mark-ring', `push-mark' discards an old mark when it adds
 225      a new one.
 226
 227  - Command: pop-global-mark
 228      This function pops a mark off the global mark ring and jumps to
 229      that location.
 230
 231 \1f
 232 File: lispref.info,  Node: The Region,  Prev: The Mark,  Up: Markers
 233
 234 The Region
 235 ==========
 236
 237    The text between point and the mark is known as "the region".
 238 Various functions operate on text delimited by point and the mark, but
 239 only those functions specifically related to the region itself are
 240 described here.
 241
 242    When `zmacs-regions' is non-`nil' (this is the default), the concept
 243 of an "active region" exists.  The region is active when the
 244 corresponding mark is active.  Note that only one active region at a
 245 time can exist--i.e. only one buffer's region is active at a time.
 246 *Note The Mark::, for more information about active regions.
 247
 248  - User Option: zmacs-regions
 249      If non-`nil' (the default), active regions are used.  *Note The
 250      Mark::, for a detailed explanation of what this means.
 251
 252    A number of functions are provided for explicitly determining the
 253 bounds of the region and whether it is active.  Few programs need to use
 254 these functions, however.  A command designed to operate on a region
 255 should normally use `interactive' with the `r' specification to find
 256 the beginning and end of the region.  This lets other Lisp programs
 257 specify the bounds explicitly as arguments and automatically respects
 258 the user's setting for ZMACS-REGIONS.  (*Note Interactive Codes::.)
 259
 260  - Function: region-beginning &optional buffer
 261      This function returns the position of the beginning of BUFFER's
 262      region (as an integer).  This is the position of either point or
 263      the mark, whichever is smaller.  BUFFER defaults to the current
 264      buffer if omitted.
 265
 266      If the mark does not point anywhere, an error is signaled.  Note
 267      that this function ignores whether the region is active.
 268
 269  - Function: region-end &optional buffer
 270      This function returns the position of the end of BUFFER's region
 271      (as an integer).  This is the position of either point or the mark,
 272      whichever is larger.  BUFFER defaults to the current buffer if
 273      omitted.
 274
 275      If the mark does not point anywhere, an error is signaled.  Note
 276      that this function ignores whether the region is active.
 277
 278  - Function: region-exists-p
 279      This function is non-`nil' if the region exists.  If active regions
 280      are in use (i.e. `zmacs-regions' is true), this means that the
 281      region is active.  Otherwise, this means that the user has pushed
 282      a mark in this buffer at some point in the past.  If this function
 283      returns `nil', a function that uses the `r' interactive
 284      specification will cause an error when called interactively.
 285
 286  - Function: region-active-p
 287      If `zmacs-regions' is true, this is equivalent to
 288      `region-exists-p'.  Otherwise, this function always returns false.
 289      This function is used by commands such as
 290      `fill-paragraph-or-region' and `capitalize-region-or-word', which
 291      operate either on the active region or on something else (e.g. the
 292      word or paragraph at point).
 293
 294  - Variable: zmacs-region-stays
 295      If a command sets this variable to true, the currently active
 296      region will remain activated when the command finishes. (Normally
 297      the region is deactivated when each command terminates.) If
 298      ZMACS-REGIONS is false, however, this has no effect.  Under normal
 299      circumstances, you do not need to set this; use the interactive
 300      specification `_' instead, if you want the region to remain active.
 301
 302  - Function: zmacs-activate-region
 303      This function activates the region in the current buffer (this is
 304      equivalent to activating the current buffer's mark).  This will
 305      normally also highlight the text in the active region and set
 306      ZMACS-REGION-STAYS to `t'. (If ZMACS-REGIONS is false, however,
 307      this function has no effect.)
 308
 309  - Function: zmacs-deactivate-region
 310      This function deactivates the region in the current buffer (this is
 311      equivalent to deactivating the current buffer's mark).  This will
 312      normally also unhighlight the text in the active region and set
 313      ZMACS-REGION-STAYS to `nil'. (If ZMACS-REGIONS is false, however,
 314      this function has no effect.)
 315
 316  - Function: zmacs-update-region
 317      This function updates the active region, if it's currently active.
 318      (If there is no active region, this function does nothing.) This
 319      has the effect of updating the highlighting on the text in the
 320      region; but you should never need to call this except under rather
 321      strange circumstances.  The command loop automatically calls it
 322      when appropriate.  Calling this function will call the hook
 323      `zmacs-update-region-hook', if the region is active.
 324
 325  - Variable: zmacs-activate-region-hook
 326      This normal hook is called when a region becomes active. (Usually
 327      this happens as a result of a command that activates the region,
 328      such as `set-mark-command', `activate-region', or
 329      `exchange-point-and-mark'.) Note that calling
 330      `zmacs-activate-region' will call this hook, even if the region is
 331      already active.  If ZMACS-REGIONS is false, however, this hook
 332      will never get called under any circumstances.
 333
 334  - Variable: zmacs-deactivate-region-hook
 335      This normal hook is called when an active region becomes inactive.
 336      (Calling `zmacs-deactivate-region' when the region is inactive will
 337      _not_ cause this hook to be called.)  If ZMACS-REGIONS is false,
 338      this hook will never get called.
 339
 340  - Variable: zmacs-update-region-hook
 341      This normal hook is called when an active region is "updated" by
 342      `zmacs-update-region'.  This normally gets called at the end of
 343      each command that sets ZMACS-REGION-STAYS to `t', indicating that
 344      the region should remain activated.  The motion commands do this.
 345
 346 \1f
 347 File: lispref.info,  Node: Text,  Next: Searching and Matching,  Prev: Markers,  Up: Top
 348
 349 Text
 350 ****
 351
 352    This chapter describes the functions that deal with the text in a
 353 buffer.  Most examine, insert, or delete text in the current buffer,
 354 often in the vicinity of point.  Many are interactive.  All the
 355 functions that change the text provide for undoing the changes (*note
 356 Undo::).
 357
 358    Many text-related functions operate on a region of text defined by
 359 two buffer positions passed in arguments named START and END.  These
 360 arguments should be either markers (*note Markers::) or numeric
 361 character positions (*note Positions::).  The order of these arguments
 362 does not matter; it is all right for START to be the end of the region
 363 and END the beginning.  For example, `(delete-region 1 10)' and
 364 `(delete-region 10 1)' are equivalent.  An `args-out-of-range' error is
 365 signaled if either START or END is outside the accessible portion of
 366 the buffer.  In an interactive call, point and the mark are used for
 367 these arguments.
 368
 369    Throughout this chapter, "text" refers to the characters in the
 370 buffer, together with their properties (when relevant).
 371
 372 * Menu:
 373
 374 * Near Point::       Examining text in the vicinity of point.
 375 * Buffer Contents::  Examining text in a general fashion.
 376 * Comparing Text::   Comparing substrings of buffers.
 377 * Insertion::        Adding new text to a buffer.
 378 * Commands for Insertion::  User-level commands to insert text.
 379 * Deletion::         Removing text from a buffer.
 380 * User-Level Deletion::     User-level commands to delete text.
 381 * The Kill Ring::    Where removed text sometimes is saved for later use.
 382 * Undo::             Undoing changes to the text of a buffer.
 383 * Maintaining Undo:: How to enable and disable undo information.
 384                         How to control how much information is kept.
 385 * Filling::          Functions for explicit filling.
 386 * Margins::          How to specify margins for filling commands.
 387 * Auto Filling::     How auto-fill mode is implemented to break lines.
 388 * Sorting::          Functions for sorting parts of the buffer.
 389 * Columns::          Computing horizontal positions, and using them.
 390 * Indentation::      Functions to insert or adjust indentation.
 391 * Case Changes::     Case conversion of parts of the buffer.
 392 * Text Properties::  Assigning Lisp property lists to text characters.
 393 * Substitution::     Replacing a given character wherever it appears.
 394 * Registers::        How registers are implemented.  Accessing the text or
 395                        position stored in a register.
 396 * Transposition::    Swapping two portions of a buffer.
 397 * Change Hooks::     Supplying functions to be run when text is changed.
 398 * Transformations::  MD5 and base64 support.
 399
 400 \1f
 401 File: lispref.info,  Node: Near Point,  Next: Buffer Contents,  Up: Text
 402
 403 Examining Text Near Point
 404 =========================
 405
 406    Many functions are provided to look at the characters around point.
 407 Several simple functions are described here.  See also `looking-at' in
 408 *Note Regexp Search::.
 409
 410    Many of these functions take an optional BUFFER argument.  In all
 411 such cases, the current buffer will be used if this argument is
 412 omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions
 413 usually did not have these optional BUFFER arguments and always
 414 operated on the current buffer.)
 415
 416  - Function: char-after &optional position buffer
 417      This function returns the character in the buffer at (i.e.,
 418      immediately after) position POSITION.  If POSITION is out of range
 419      for this purpose, either before the beginning of the buffer, or at
 420      or beyond the end, then the value is `nil'.  The default for
 421      POSITION is point.  If optional argument BUFFER is `nil', the
 422      current buffer is assumed.
 423
 424      In the following example, assume that the first character in the
 425      buffer is `@':
 426
 427           (char-to-string (char-after 1))
 428                => "@"
 429
 430  - Function: char-before &optional position buffer
 431      This function returns the character in the current buffer
 432      immediately before position POSITION.  If POSITION is out of range
 433      for this purpose, either at or before the beginning of the buffer,
 434      or beyond the end, then the value is `nil'.  The default for
 435      POSITION is point.  If optional argument BUFFER is `nil', the
 436      current buffer is assumed.
 437
 438  - Function: following-char &optional buffer
 439      This function returns the character following point in the buffer.
 440      This is similar to `(char-after (point))'.  However, if point is at
 441      the end of the buffer, then the result of `following-char' is 0.
 442      If optional argument BUFFER is `nil', the current buffer is
 443      assumed.
 444
 445      Remember that point is always between characters, and the terminal
 446      cursor normally appears over the character following point.
 447      Therefore, the character returned by `following-char' is the
 448      character the cursor is over.
 449
 450      In this example, point is between the `a' and the `c'.
 451
 452           ---------- Buffer: foo ----------
 453           Gentlemen may cry ``Pea-!-ce! Peace!,''
 454           but there is no peace.
 455           ---------- Buffer: foo ----------
 456
 457           (char-to-string (preceding-char))
 458                => "a"
 459           (char-to-string (following-char))
 460                => "c"
 461
 462  - Function: preceding-char &optional buffer
 463      This function returns the character preceding point in the buffer.
 464      See above, under `following-char', for an example.  If point is at
 465      the beginning of the buffer, `preceding-char' returns 0.  If
 466      optional argument BUFFER is `nil', the current buffer is assumed.
 467
 468  - Function: bobp &optional buffer
 469      This function returns `t' if point is at the beginning of the
 470      buffer.  If narrowing is in effect, this means the beginning of the
 471      accessible portion of the text.  If optional argument BUFFER is
 472      `nil', the current buffer is assumed.  See also `point-min' in
 473      *Note Point::.
 474
 475  - Function: eobp &optional buffer
 476      This function returns `t' if point is at the end of the buffer.
 477      If narrowing is in effect, this means the end of accessible
 478      portion of the text.  If optional argument BUFFER is `nil', the
 479      current buffer is assumed.  See also `point-max' in *Note Point::.
 480
 481  - Function: bolp &optional buffer
 482      This function returns `t' if point is at the beginning of a line.
 483      If optional argument BUFFER is `nil', the current buffer is
 484      assumed.  *Note Text Lines::.  The beginning of the buffer (or its
 485      accessible portion) always counts as the beginning of a line.
 486
 487  - Function: eolp &optional buffer
 488      This function returns `t' if point is at the end of a line.  The
 489      end of the buffer is always considered the end of a line.  If
 490      optional argument BUFFER is `nil', the current buffer is assumed.
 491      The end of the buffer (or of its accessible portion) is always
 492      considered the end of a line.
 493
 494 \1f
 495 File: lispref.info,  Node: Buffer Contents,  Next: Comparing Text,  Prev: Near Point,  Up: Text
 496
 497 Examining Buffer Contents
 498 =========================
 499
 500    This section describes two functions that allow a Lisp program to
 501 convert any portion of the text in the buffer into a string.
 502
 503  - Function: buffer-substring start end &optional buffer
 504  - Function: buffer-string start end &optional buffer
 505      These functions are equivalent and return a string containing a
 506      copy of the text of the region defined by positions START and END
 507      in the buffer.  If the arguments are not positions in the
 508      accessible portion of the buffer, `buffer-substring' signals an
 509      `args-out-of-range' error.  If optional argument BUFFER is `nil',
 510      the current buffer is assumed.
 511
 512      If the region delineated by START and END contains duplicable
 513      extents, they will be remembered in the string.  *Note Duplicable
 514      Extents::.
 515
 516      It is not necessary for START to be less than END; the arguments
 517      can be given in either order.  But most often the smaller argument
 518      is written first.
 519
 520           ---------- Buffer: foo ----------
 521           This is the contents of buffer foo
 522
 523           ---------- Buffer: foo ----------
 524
 525           (buffer-substring 1 10)
 526           => "This is t"
 527           (buffer-substring (point-max) 10)
 528           => "he contents of buffer foo
 529           "
 530
 531 \1f
 532 File: lispref.info,  Node: Comparing Text,  Next: Insertion,  Prev: Buffer Contents,  Up: Text
 533
 534 Comparing Text
 535 ==============
 536
 537    This function lets you compare portions of the text in a buffer,
 538 without copying them into strings first.
 539
 540  - Function: compare-buffer-substrings buffer1 start1 end1 buffer2
 541           start2 end2
 542      This function lets you compare two substrings of the same buffer
 543      or two different buffers.  The first three arguments specify one
 544      substring, giving a buffer and two positions within the buffer.
 545      The last three arguments specify the other substring in the same
 546      way.  You can use `nil' for BUFFER1, BUFFER2, or both to stand for
 547      the current buffer.
 548
 549      The value is negative if the first substring is less, positive if
 550      the first is greater, and zero if they are equal.  The absolute
 551      value of the result is one plus the index of the first differing
 552      characters within the substrings.
 553
 554      This function ignores case when comparing characters if
 555      `case-fold-search' is non-`nil'.  It always ignores text
 556      properties.
 557
 558      Suppose the current buffer contains the text `foobarbar
 559      haha!rara!'; then in this example the two substrings are `rbar '
 560      and `rara!'.  The value is 2 because the first substring is greater
 561      at the second character.
 562
 563           (compare-buffer-substring nil 6 11 nil 16 21)
 564                => 2
 565
 566 \1f
 567 File: lispref.info,  Node: Insertion,  Next: Commands for Insertion,  Prev: Comparing Text,  Up: Text
 568
 569 Inserting Text
 570 ==============
 571
 572    "Insertion" means adding new text to a buffer.  The inserted text
 573 goes at point--between the character before point and the character
 574 after point.
 575
 576    Insertion relocates markers that point at positions after the
 577 insertion point, so that they stay with the surrounding text (*note
 578 Markers::).  When a marker points at the place of insertion, insertion
 579 normally doesn't relocate the marker, so that it points to the
 580 beginning of the inserted text; however, certain special functions such
 581 as `insert-before-markers' relocate such markers to point after the
 582 inserted text.
 583
 584    Some insertion functions leave point before the inserted text, while
 585 other functions leave it after.  We call the former insertion "after
 586 point" and the latter insertion "before point".
 587
 588    If a string with non-`nil' extent data is inserted, the remembered
 589 extents will also be inserted.  *Note Duplicable Extents::.
 590
 591    Insertion functions signal an error if the current buffer is
 592 read-only.
 593
 594    These functions copy text characters from strings and buffers along
 595 with their properties.  The inserted characters have exactly the same
 596 properties as the characters they were copied from.  By contrast,
 597 characters specified as separate arguments, not part of a string or
 598 buffer, inherit their text properties from the neighboring text.
 599
 600  - Function: insert &rest args
 601      This function inserts the strings and/or characters ARGS into the
 602      current buffer, at point, moving point forward.  In other words, it
 603      inserts the text before point.  An error is signaled unless all
 604      ARGS are either strings or characters.  The value is `nil'.
 605
 606  - Function: insert-before-markers &rest args
 607      This function inserts the strings and/or characters ARGS into the
 608      current buffer, at point, moving point forward.  An error is
 609      signaled unless all ARGS are either strings or characters.  The
 610      value is `nil'.
 611
 612      This function is unlike the other insertion functions in that it
 613      relocates markers initially pointing at the insertion point, to
 614      point after the inserted text.
 615
 616  - Function: insert-string string &optional buffer
 617      This function inserts STRING into BUFFER before point.  BUFFER
 618      defaults to the current buffer if omitted.  This function is
 619      chiefly useful if you want to insert a string in a buffer other
 620      than the current one (otherwise you could just use `insert').
 621
 622  - Function: insert-char character count &optional buffer
 623      This function inserts COUNT instances of CHARACTER into BUFFER
 624      before point.  COUNT must be a number, and CHARACTER must be a
 625      character.  The value is `nil'.  If optional argument BUFFER is
 626      `nil', the current buffer is assumed. (In FSF Emacs, the third
 627      argument is called INHERIT and refers to text properties.)
 628
 629  - Function: insert-buffer-substring from-buffer-or-name &optional
 630           start end
 631      This function inserts a portion of buffer FROM-BUFFER-OR-NAME
 632      (which must already exist) into the current buffer before point.
 633      The text inserted is the region from START and END.  (These
 634      arguments default to the beginning and end of the accessible
 635      portion of that buffer.)  This function returns `nil'.
 636
 637      In this example, the form is executed with buffer `bar' as the
 638      current buffer.  We assume that buffer `bar' is initially empty.
 639
 640           ---------- Buffer: foo ----------
 641           We hold these truths to be self-evident, that all
 642           ---------- Buffer: foo ----------
 643
 644           (insert-buffer-substring "foo" 1 20)
 645                => nil
 646
 647           ---------- Buffer: bar ----------
 648           We hold these truth-!-
 649           ---------- Buffer: bar ----------
 650
 651 \1f
 652 File: lispref.info,  Node: Commands for Insertion,  Next: Deletion,  Prev: Insertion,  Up: Text
 653
 654 User-Level Insertion Commands
 655 =============================
 656
 657    This section describes higher-level commands for inserting text,
 658 commands intended primarily for the user but useful also in Lisp
 659 programs.
 660
 661  - Command: insert-buffer from-buffer-or-name
 662      This command inserts the entire contents of FROM-BUFFER-OR-NAME
 663      (which must exist) into the current buffer after point.  It leaves
 664      the mark after the inserted text.  The value is `nil'.
 665
 666  - Command: self-insert-command count
 667      This command inserts the last character typed; it does so COUNT
 668      times, before point, and returns `nil'.  Most printing characters
 669      are bound to this command.  In routine use, `self-insert-command'
 670      is the most frequently called function in XEmacs, but programs
 671      rarely use it except to install it on a keymap.
 672
 673      In an interactive call, COUNT is the numeric prefix argument.
 674
 675      This command calls `auto-fill-function' whenever that is non-`nil'
 676      and the character inserted is a space or a newline (*note Auto
 677      Filling::).
 678
 679      This command performs abbrev expansion if Abbrev mode is enabled
 680      and the inserted character does not have word-constituent syntax.
 681      (*Note Abbrevs::, and *Note Syntax Class Table::.)
 682
 683      This is also responsible for calling `blink-paren-function' when
 684      the inserted character has close parenthesis syntax (*note
 685      Blinking::).
 686
 687  - Command: newline &optional number-of-newlines
 688      This command inserts newlines into the current buffer before point.
 689      If NUMBER-OF-NEWLINES is supplied, that many newline characters
 690      are inserted.
 691
 692      This function calls `auto-fill-function' if the current column
 693      number is greater than the value of `fill-column' and
 694      NUMBER-OF-NEWLINES is `nil'.  Typically what `auto-fill-function'
 695      does is insert a newline; thus, the overall result in this case is
 696      to insert two newlines at different places: one at point, and
 697      another earlier in the line.  `newline' does not auto-fill if
 698      NUMBER-OF-NEWLINES is non-`nil'.
 699
 700      This command indents to the left margin if that is not zero.
 701      *Note Margins::.
 702
 703      The value returned is `nil'.  In an interactive call, COUNT is the
 704      numeric prefix argument.
 705
 706  - Command: split-line
 707      This command splits the current line, moving the portion of the
 708      line after point down vertically so that it is on the next line
 709      directly below where it was before.  Whitespace is inserted as
 710      needed at the beginning of the lower line, using the `indent-to'
 711      function.  `split-line' returns the position of point.
 712
 713      Programs hardly ever use this function.
 714
 715  - Variable: overwrite-mode
 716      This variable controls whether overwrite mode is in effect: a
 717      non-`nil' value enables the mode.  It is automatically made
 718      buffer-local when set in any fashion.
 719
 720 \1f
 721 File: lispref.info,  Node: Deletion,  Next: User-Level Deletion,  Prev: Commands for Insertion,  Up: Text
 722
 723 Deleting Text
 724 =============
 725
 726    Deletion means removing part of the text in a buffer, without saving
 727 it in the kill ring (*note The Kill Ring::).  Deleted text can't be
 728 yanked, but can be reinserted using the undo mechanism (*note Undo::).
 729 Some deletion functions do save text in the kill ring in some special
 730 cases.
 731
 732    All of the deletion functions operate on the current buffer, and all
 733 return a value of `nil'.
 734
 735  - Function: erase-buffer &optional buffer
 736      This function deletes the entire text of BUFFER, leaving it empty.
 737      If the buffer is read-only, it signals a `buffer-read-only'
 738      error.  Otherwise, it deletes the text without asking for any
 739      confirmation.  It returns `nil'.  BUFFER defaults to the current
 740      buffer if omitted.
 741
 742      Normally, deleting a large amount of text from a buffer inhibits
 743      further auto-saving of that buffer "because it has shrunk".
 744      However, `erase-buffer' does not do this, the idea being that the
 745      future text is not really related to the former text, and its size
 746      should not be compared with that of the former text.
 747
 748  - Command: delete-region start end &optional buffer
 749      This command deletes the text in BUFFER in the region defined by
 750      START and END.  The value is `nil'.  If optional argument BUFFER
 751      is `nil', the current buffer is assumed.
 752
 753  - Command: delete-char count &optional killp
 754      This command deletes COUNT characters directly after point, or
 755      before point if COUNT is negative.  If KILLP is non-`nil', then it
 756      saves the deleted characters in the kill ring.
 757
 758      In an interactive call, COUNT is the numeric prefix argument, and
 759      KILLP is the unprocessed prefix argument.  Therefore, if a prefix
 760      argument is supplied, the text is saved in the kill ring.  If no
 761      prefix argument is supplied, then one character is deleted, but
 762      not saved in the kill ring.
 763
 764      The value returned is always `nil'.
 765
 766  - Command: delete-backward-char count &optional killp
 767      This command deletes COUNT characters directly before point, or
 768      after point if COUNT is negative.  If KILLP is non-`nil', then it
 769      saves the deleted characters in the kill ring.
 770
 771      In an interactive call, COUNT is the numeric prefix argument, and
 772      KILLP is the unprocessed prefix argument.  Therefore, if a prefix
 773      argument is supplied, the text is saved in the kill ring.  If no
 774      prefix argument is supplied, then one character is deleted, but
 775      not saved in the kill ring.
 776
 777      The value returned is always `nil'.
 778
 779  - Command: backward-delete-char-untabify count &optional killp
 780      This command deletes COUNT characters backward, changing tabs into
 781      spaces.  When the next character to be deleted is a tab, it is
 782      first replaced with the proper number of spaces to preserve
 783      alignment and then one of those spaces is deleted instead of the
 784      tab.  If KILLP is non-`nil', then the command saves the deleted
 785      characters in the kill ring.
 786
 787      Conversion of tabs to spaces happens only if COUNT is positive.
 788      If it is negative, exactly -COUNT characters after point are
 789      deleted.
 790
 791      In an interactive call, COUNT is the numeric prefix argument, and
 792      KILLP is the unprocessed prefix argument.  Therefore, if a prefix
 793      argument is supplied, the text is saved in the kill ring.  If no
 794      prefix argument is supplied, then one character is deleted, but
 795      not saved in the kill ring.
 796
 797      The value returned is always `nil'.
 798
 799 \1f
 800 File: lispref.info,  Node: User-Level Deletion,  Next: The Kill Ring,  Prev: Deletion,  Up: Text
 801
 802 User-Level Deletion Commands
 803 ============================
 804
 805    This section describes higher-level commands for deleting text,
 806 commands intended primarily for the user but useful also in Lisp
 807 programs.
 808
 809  - Command: delete-horizontal-space
 810      This function deletes all spaces and tabs around point.  It returns
 811      `nil'.
 812
 813      In the following examples, we call `delete-horizontal-space' four
 814      times, once on each line, with point between the second and third
 815      characters on the line each time.
 816
 817           ---------- Buffer: foo ----------
 818           I -!-thought
 819           I -!-     thought
 820           We-!- thought
 821           Yo-!-u thought
 822           ---------- Buffer: foo ----------
 823
 824           (delete-horizontal-space)   ; Four times.
 825                => nil
 826
 827           ---------- Buffer: foo ----------
 828           Ithought
 829           Ithought
 830           Wethought
 831           You thought
 832           ---------- Buffer: foo ----------
 833
 834  - Command: delete-indentation &optional join-following-p
 835      This function joins the line point is on to the previous line,
 836      deleting any whitespace at the join and in some cases replacing it
 837      with one space.  If JOIN-FOLLOWING-P is non-`nil',
 838      `delete-indentation' joins this line to the following line
 839      instead.  The value is `nil'.
 840
 841      If there is a fill prefix, and the second of the lines being joined
 842      starts with the prefix, then `delete-indentation' deletes the fill
 843      prefix before joining the lines.  *Note Margins::.
 844
 845      In the example below, point is located on the line starting
 846      `events', and it makes no difference if there are trailing spaces
 847      in the preceding line.
 848
 849           ---------- Buffer: foo ----------
 850           When in the course of human
 851           -!-    events, it becomes necessary
 852           ---------- Buffer: foo ----------
 853
 854           (delete-indentation)
 855                => nil
 856
 857           ---------- Buffer: foo ----------
 858           When in the course of human-!- events, it becomes necessary
 859           ---------- Buffer: foo ----------
 860
 861      After the lines are joined, the function `fixup-whitespace' is
 862      responsible for deciding whether to leave a space at the junction.
 863
 864  - Function: fixup-whitespace
 865      This function replaces all the white space surrounding point with
 866      either one space or no space, according to the context.  It
 867      returns `nil'.
 868
 869      At the beginning or end of a line, the appropriate amount of space
 870      is none.  Before a character with close parenthesis syntax, or
 871      after a character with open parenthesis or expression-prefix
 872      syntax, no space is also appropriate.  Otherwise, one space is
 873      appropriate.  *Note Syntax Class Table::.
 874
 875      In the example below, `fixup-whitespace' is called the first time
 876      with point before the word `spaces' in the first line.  For the
 877      second invocation, point is directly after the `('.
 878
 879           ---------- Buffer: foo ----------
 880           This has too many     -!-spaces
 881           This has too many spaces at the start of (-!-   this list)
 882           ---------- Buffer: foo ----------
 883
 884           (fixup-whitespace)
 885                => nil
 886           (fixup-whitespace)
 887                => nil
 888
 889           ---------- Buffer: foo ----------
 890           This has too many spaces
 891           This has too many spaces at the start of (this list)
 892           ---------- Buffer: foo ----------
 893
 894  - Command: just-one-space
 895      This command replaces any spaces and tabs around point with a
 896      single space.  It returns `nil'.
 897
 898  - Command: delete-blank-lines
 899      This function deletes blank lines surrounding point.  If point is
 900      on a blank line with one or more blank lines before or after it,
 901      then all but one of them are deleted.  If point is on an isolated
 902      blank line, then it is deleted.  If point is on a nonblank line,
 903      the command deletes all blank lines following it.
 904
 905      A blank line is defined as a line containing only tabs and spaces.
 906
 907      `delete-blank-lines' returns `nil'.
 908
 909 \1f
 910 File: lispref.info,  Node: The Kill Ring,  Next: Undo,  Prev: User-Level Deletion,  Up: Text
 911
 912 The Kill Ring
 913 =============
 914
 915    "Kill" functions delete text like the deletion functions, but save
 916 it so that the user can reinsert it by "yanking".  Most of these
 917 functions have `kill-' in their name.  By contrast, the functions whose
 918 names start with `delete-' normally do not save text for yanking
 919 (though they can still be undone); these are "deletion" functions.
 920
 921    Most of the kill commands are primarily for interactive use, and are
 922 not described here.  What we do describe are the functions provided for
 923 use in writing such commands.  You can use these functions to write
 924 commands for killing text.  When you need to delete text for internal
 925 purposes within a Lisp function, you should normally use deletion
 926 functions, so as not to disturb the kill ring contents.  *Note
 927 Deletion::.
 928
 929    Killed text is saved for later yanking in the "kill ring".  This is
 930 a list that holds a number of recent kills, not just the last text
 931 kill.  We call this a "ring" because yanking treats it as having
 932 elements in a cyclic order.  The list is kept in the variable
 933 `kill-ring', and can be operated on with the usual functions for lists;
 934 there are also specialized functions, described in this section, that
 935 treat it as a ring.
 936
 937    Some people think this use of the word "kill" is unfortunate, since
 938 it refers to operations that specifically _do not_ destroy the entities
 939 "killed".  This is in sharp contrast to ordinary life, in which death
 940 is permanent and "killed" entities do not come back to life.
 941 Therefore, other metaphors have been proposed.  For example, the term
 942 "cut ring" makes sense to people who, in pre-computer days, used
 943 scissors and paste to cut up and rearrange manuscripts.  However, it
 944 would be difficult to change the terminology now.
 945
 946 * Menu:
 947
 948 * Kill Ring Concepts::     What text looks like in the kill ring.
 949 * Kill Functions::         Functions that kill text.
 950 * Yank Commands::          Commands that access the kill ring.
 951 * Low-Level Kill Ring::    Functions and variables for kill ring access.
 952 * Internals of Kill Ring:: Variables that hold kill-ring data.
 953
 954 \1f
 955 File: lispref.info,  Node: Kill Ring Concepts,  Next: Kill Functions,  Up: The Kill Ring
 956
 957 Kill Ring Concepts
 958 ------------------
 959
 960    The kill ring records killed text as strings in a list, most recent
 961 first.  A short kill ring, for example, might look like this:
 962
 963      ("some text" "a different piece of text" "even older text")
 964
 965 When the list reaches `kill-ring-max' entries in length, adding a new
 966 entry automatically deletes the last entry.
 967
 968    When kill commands are interwoven with other commands, each kill
 969 command makes a new entry in the kill ring.  Multiple kill commands in
 970 succession build up a single entry in the kill ring, which would be
 971 yanked as a unit; the second and subsequent consecutive kill commands
 972 add text to the entry made by the first one.
 973
 974    For yanking, one entry in the kill ring is designated the "front" of
 975 the ring.  Some yank commands "rotate" the ring by designating a
 976 different element as the "front."  But this virtual rotation doesn't
 977 change the list itself--the most recent entry always comes first in the
 978 list.
 979
 980 \1f
 981 File: lispref.info,  Node: Kill Functions,  Next: Yank Commands,  Prev: Kill Ring Concepts,  Up: The Kill Ring
 982
 983 Functions for Killing
 984 ---------------------
 985
 986    `kill-region' is the usual subroutine for killing text.  Any command
 987 that calls this function is a "kill command" (and should probably have
 988 `kill' in its name).  `kill-region' puts the newly killed text in a new
 989 element at the beginning of the kill ring or adds it to the most recent
 990 element.  It uses the `last-command' variable to determine whether the
 991 previous command was a kill command, and if so appends the killed text
 992 to the most recent entry.
 993
 994  - Command: kill-region start end
 995      This function kills the text in the region defined by START and
 996      END.  The text is deleted but saved in the kill ring, along with
 997      its text properties.  The value is always `nil'.
 998
 999      In an interactive call, START and END are point and the mark.
1000
1001      If the buffer is read-only, `kill-region' modifies the kill ring
1002      just the same, then signals an error without modifying the buffer.
1003      This is convenient because it lets the user use all the kill
1004      commands to copy text into the kill ring from a read-only buffer.
1005
1006  - Command: copy-region-as-kill start end
1007      This command saves the region defined by START and END on the kill
1008      ring (including text properties), but does not delete the text
1009      from the buffer.  It returns `nil'.  It also indicates the extent
1010      of the text copied by moving the cursor momentarily, or by
1011      displaying a message in the echo area.
1012
1013      The command does not set `this-command' to `kill-region', so a
1014      subsequent kill command does not append to the same kill ring
1015      entry.
1016
1017      Don't call `copy-region-as-kill' in Lisp programs unless you aim to
1018      support Emacs 18.  For Emacs 19, it is better to use `kill-new' or
1019      `kill-append' instead.  *Note Low-Level Kill Ring::.
1020
1021 \1f
1022 File: lispref.info,  Node: Yank Commands,  Next: Low-Level Kill Ring,  Prev: Kill Functions,  Up: The Kill Ring
1023
1024 Functions for Yanking
1025 ---------------------
1026
1027    "Yanking" means reinserting an entry of previously killed text from
1028 the kill ring.  The text properties are copied too.
1029
1030  - Command: yank &optional arg
1031      This command inserts before point the text in the first entry in
1032      the kill ring.  It positions the mark at the beginning of that
1033      text, and point at the end.
1034
1035      If ARG is a list (which occurs interactively when the user types
1036      `C-u' with no digits), then `yank' inserts the text as described
1037      above, but puts point before the yanked text and puts the mark
1038      after it.
1039
1040      If ARG is a number, then `yank' inserts the ARGth most recently
1041      killed text--the ARGth element of the kill ring list.
1042
1043      `yank' does not alter the contents of the kill ring or rotate it.
1044      It returns `nil'.
1045
1046  - Command: yank-pop arg
1047      This command replaces the just-yanked entry from the kill ring
1048      with a different entry from the kill ring.
1049
1050      This is allowed only immediately after a `yank' or another
1051      `yank-pop'.  At such a time, the region contains text that was just
1052      inserted by yanking.  `yank-pop' deletes that text and inserts in
1053      its place a different piece of killed text.  It does not add the
1054      deleted text to the kill ring, since it is already in the kill
1055      ring somewhere.
1056
1057      If ARG is `nil', then the replacement text is the previous element
1058      of the kill ring.  If ARG is numeric, the replacement is the ARGth
1059      previous kill.  If ARG is negative, a more recent kill is the
1060      replacement.
1061
1062      The sequence of kills in the kill ring wraps around, so that after
1063      the oldest one comes the newest one, and before the newest one
1064      goes the oldest.
1065
1066      The value is always `nil'.
1067
1068 \1f
1069 File: lispref.info,  Node: Low-Level Kill Ring,  Next: Internals of Kill Ring,  Prev: Yank Commands,  Up: The Kill Ring
1070
1071 Low-Level Kill Ring
1072 -------------------
1073
1074    These functions and variables provide access to the kill ring at a
1075 lower level, but still convenient for use in Lisp programs.  They take
1076 care of interaction with X Window selections.  They do not exist in
1077 Emacs version 18.
1078
1079  - Function: current-kill n &optional do-not-move
1080      The function `current-kill' rotates the yanking pointer which
1081      designates the "front" of the kill ring by N places (from newer
1082      kills to older ones), and returns the text at that place in the
1083      ring.
1084
1085      If the optional second argument DO-NOT-MOVE is non-`nil', then
1086      `current-kill' doesn't alter the yanking pointer; it just returns
1087      the Nth kill, counting from the current yanking pointer.
1088
1089      If N is zero, indicating a request for the latest kill,
1090      `current-kill' calls the value of `interprogram-paste-function'
1091      (documented below) before consulting the kill ring.
1092
1093  - Function: kill-new string
1094      This function puts the text STRING into the kill ring as a new
1095      entry at the front of the ring.  It discards the oldest entry if
1096      appropriate.  It also invokes the value of
1097      `interprogram-cut-function' (see below).
1098
1099  - Function: kill-append string before-p
1100      This function appends the text STRING to the first entry in the
1101      kill ring.  Normally STRING goes at the end of the entry, but if
1102      BEFORE-P is non-`nil', it goes at the beginning.  This function
1103      also invokes the value of `interprogram-cut-function' (see below).
1104
1105  - Variable: interprogram-paste-function
1106      This variable provides a way of transferring killed text from other
1107      programs, when you are using a window system.  Its value should be
1108      `nil' or a function of no arguments.
1109
1110      If the value is a function, `current-kill' calls it to get the
1111      "most recent kill".  If the function returns a non-`nil' value,
1112      then that value is used as the "most recent kill".  If it returns
1113      `nil', then the first element of `kill-ring' is used.
1114
1115      The normal use of this hook is to get the X server's primary
1116      selection as the most recent kill, even if the selection belongs
1117      to another X client.  *Note X Selections::.
1118
1119  - Variable: interprogram-cut-function
1120      This variable provides a way of communicating killed text to other
1121      programs, when you are using a window system.  Its value should be
1122      `nil' or a function of one argument.
1123
1124      If the value is a function, `kill-new' and `kill-append' call it
1125      with the new first element of the kill ring as an argument.
1126
1127      The normal use of this hook is to set the X server's primary
1128      selection to the newly killed text.
1129