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/markers.info
+ − 6 @node Markers, Text, Positions, Top
+ − 7 @chapter Markers
+ − 8 @cindex markers
+ − 9
+ − 10 A @dfn{marker} is a Lisp object used to specify a position in a buffer
+ − 11 relative to the surrounding text. A marker changes its offset from the
+ − 12 beginning of the buffer automatically whenever text is inserted or
+ − 13 deleted, so that it stays with the two characters on either side of it.
+ − 14
+ − 15 @menu
+ − 16 * Overview of Markers:: The components of a marker, and how it relocates.
+ − 17 * Predicates on Markers:: Testing whether an object is a marker.
+ − 18 * Creating Markers:: Making empty markers or markers at certain places.
+ − 19 * Information from Markers:: Finding the marker's buffer or character position.
+ − 20 * Changing Markers:: Moving the marker to a new buffer or position.
+ − 21 * The Mark:: How ``the mark'' is implemented with a marker.
+ − 22 * The Region:: How to access ``the region''.
+ − 23 @end menu
+ − 24
+ − 25 @node Overview of Markers
+ − 26 @section Overview of Markers
+ − 27
+ − 28 A marker specifies a buffer and a position in that buffer. The marker
+ − 29 can be used to represent a position in the functions that require one,
+ − 30 just as an integer could be used. @xref{Positions}, for a complete
+ − 31 description of positions.
+ − 32
+ − 33 A marker has two attributes: the marker position, and the marker
+ − 34 buffer. The marker position is an integer that is equivalent (at a
+ − 35 given time) to the marker as a position in that buffer. But the
+ − 36 marker's position value can change often during the life of the marker.
+ − 37 Insertion and deletion of text in the buffer relocate the marker. The
+ − 38 idea is that a marker positioned between two characters remains between
+ − 39 those two characters despite insertion and deletion elsewhere in the
+ − 40 buffer. Relocation changes the integer equivalent of the marker.
+ − 41
+ − 42 @cindex marker relocation
+ − 43 Deleting text around a marker's position leaves the marker between the
+ − 44 characters immediately before and after the deleted text. Inserting
+ − 45 text at the position of a marker normally leaves the marker in front of
+ − 46 the new text---unless it is inserted with @code{insert-before-markers}
+ − 47 (@pxref{Insertion}).
+ − 48
+ − 49 @cindex marker garbage collection
+ − 50 Insertion and deletion in a buffer must check all the markers and
+ − 51 relocate them if necessary. This slows processing in a buffer with a
+ − 52 large number of markers. For this reason, it is a good idea to make a
+ − 53 marker point nowhere if you are sure you don't need it any more.
+ − 54 Unreferenced markers are garbage collected eventually, but until then
+ − 55 will continue to use time if they do point somewhere.
+ − 56
+ − 57 @cindex markers as numbers
+ − 58 Because it is common to perform arithmetic operations on a marker
+ − 59 position, most of the arithmetic operations (including @code{+} and
+ − 60 @code{-}) accept markers as arguments. In such cases, the marker
+ − 61 stands for its current position.
+ − 62
+ − 63 @cindex markers vs. extents
+ − 64 Note that you can use extents to achieve the same functionality, and
+ − 65 more, as markers. (Markers were defined before extents, which is why
+ − 66 they both continue to exist.) A zero-length extent with the
+ − 67 @code{detachable} property removed is almost identical to a marker.
+ − 68 (@xref{Extent Endpoints}, for more information on zero-length extents.)
+ − 69
+ − 70 In particular:
+ − 71
+ − 72 @itemize @bullet
+ − 73 @item
+ − 74 In order to get marker-like behavior in a zero-length extent, the
+ − 75 @code{detachable} property must be removed (otherwise, the extent
+ − 76 will disappear when text near it is deleted) and exactly one
+ − 77 endpoint must be closed (if both endpoints are closed, the extent
+ − 78 will expand to contain text inserted where it is located).
+ − 79 @item
+ − 80 If a zero-length extent has the @code{end-open} property but not
+ − 81 the @code{start-open} property (this is the default), text inserted
+ − 82 at the extent's location causes the extent to move forward, just
+ − 83 like a marker.
+ − 84 @item
+ − 85 If a zero-length extent has the @code{start-open} property but not
+ − 86 the @code{end-open} property, text inserted at the extent's location
+ − 87 causes the extent to remain before the text, like what happens to
+ − 88 markers when @code{insert-before-markers} is used.
+ − 89 @item
+ − 90 Markers end up after or before inserted text depending on whether
+ − 91 @code{insert} or @code{insert-before-markers} was called. These
+ − 92 functions do not affect zero-length extents differently; instead,
+ − 93 the presence or absence of the @code{start-open} and @code{end-open}
+ − 94 extent properties determines this, as just described.
+ − 95 @item
+ − 96 Markers are automatically removed from a buffer when they are no
+ − 97 longer in use. Extents remain around until explicitly removed
+ − 98 from a buffer.
+ − 99 @item
+ − 100 Many functions are provided for listing the extents in a buffer or
+ − 101 in a region of a buffer. No such functions exist for markers.
+ − 102 @end itemize
+ − 103
+ − 104 Here are examples of creating markers, setting markers, and moving point
+ − 105 to markers:
+ − 106
+ − 107 @example
+ − 108 @group
+ − 109 ;; @r{Make a new marker that initially does not point anywhere:}
+ − 110 (setq m1 (make-marker))
+ − 111 @result{} #<marker in no buffer>
+ − 112 @end group
+ − 113
+ − 114 @group
+ − 115 ;; @r{Set @code{m1} to point between the 99th and 100th characters}
+ − 116 ;; @r{in the current buffer:}
+ − 117 (set-marker m1 100)
+ − 118 @result{} #<marker at 100 in markers.texi>
+ − 119 @end group
+ − 120
+ − 121 @group
+ − 122 ;; @r{Now insert one character at the beginning of the buffer:}
+ − 123 (goto-char (point-min))
+ − 124 @result{} 1
+ − 125 (insert "Q")
+ − 126 @result{} nil
+ − 127 @end group
+ − 128
+ − 129 @group
+ − 130 ;; @r{@code{m1} is updated appropriately.}
+ − 131 m1
+ − 132 @result{} #<marker at 101 in markers.texi>
+ − 133 @end group
+ − 134
+ − 135 @group
+ − 136 ;; @r{Two markers that point to the same position}
+ − 137 ;; @r{are not @code{eq}, but they are @code{equal}.}
+ − 138 (setq m2 (copy-marker m1))
+ − 139 @result{} #<marker at 101 in markers.texi>
+ − 140 (eq m1 m2)
+ − 141 @result{} nil
+ − 142 (equal m1 m2)
+ − 143 @result{} t
+ − 144 @end group
+ − 145
+ − 146 @group
+ − 147 ;; @r{When you are finished using a marker, make it point nowhere.}
+ − 148 (set-marker m1 nil)
+ − 149 @result{} #<marker in no buffer>
+ − 150 @end group
+ − 151 @end example
+ − 152
+ − 153 @node Predicates on Markers
+ − 154 @section Predicates on Markers
+ − 155
+ − 156 You can test an object to see whether it is a marker, or whether it is
+ − 157 either an integer or a marker or either an integer, a character, or a
+ − 158 marker. The latter tests are useful in connection with the arithmetic
+ − 159 functions that work with any of markers, integers, or characters.
+ − 160
+ − 161 @defun markerp object
+ − 162 This function returns @code{t} if @var{object} is a marker, @code{nil}
+ − 163 otherwise. Note that integers are not markers, even though many
+ − 164 functions will accept either a marker or an integer.
+ − 165 @end defun
+ − 166
+ − 167 @defun integer-or-marker-p object
+ − 168 This function returns @code{t} if @var{object} is an integer or a marker,
+ − 169 @code{nil} otherwise.
+ − 170 @end defun
+ − 171
+ − 172 @defun integer-char-or-marker-p object
+ − 173 This function returns @code{t} if @var{object} is an integer, a
+ − 174 character, or a marker, @code{nil} otherwise.
+ − 175 @end defun
+ − 176
+ − 177 @defun number-or-marker-p object
+ − 178 This function returns @code{t} if @var{object} is a number (either kind)
+ − 179 or a marker, @code{nil} otherwise.
+ − 180 @end defun
+ − 181
+ − 182 @defun number-char-or-marker-p object
+ − 183 This function returns @code{t} if @var{object} is a number (either
+ − 184 kind), a character, or a marker, @code{nil} otherwise.
+ − 185 @end defun
+ − 186
+ − 187 @node Creating Markers
+ − 188 @section Functions That Create Markers
+ − 189
+ − 190 When you create a new marker, you can make it point nowhere, or point
+ − 191 to the present position of point, or to the beginning or end of the
+ − 192 accessible portion of the buffer, or to the same place as another given
+ − 193 marker.
+ − 194
+ − 195 @defun make-marker
+ − 196 This functions returns a newly created marker that does not point
+ − 197 anywhere.
+ − 198
+ − 199 @example
+ − 200 @group
+ − 201 (make-marker)
+ − 202 @result{} #<marker in no buffer>
+ − 203 @end group
+ − 204 @end example
+ − 205 @end defun
+ − 206
+ − 207 @defun point-marker &optional dont-copy-p buffer
+ − 208 This function returns a marker that points to the present position of
+ − 209 point in @var{buffer}, which defaults to the current buffer.
+ − 210 @xref{Point}. For an example, see @code{copy-marker}, below.
+ − 211
+ − 212 Internally, a marker corresponding to point is always maintained.
+ − 213 Normally the marker returned by @code{point-marker} is a copy; you
+ − 214 may modify it with reckless abandon. However, if optional argument
+ − 215 @var{dont-copy-p} is non-@code{nil}, then the real point-marker is
+ − 216 returned; modifying the position of this marker will move point.
+ − 217 It is illegal to change the buffer of it, or make it point nowhere.
+ − 218 @end defun
+ − 219
+ − 220 @defun point-min-marker &optional buffer
+ − 221 This function returns a new marker that points to the beginning of the
+ − 222 accessible portion of @var{buffer}, which defaults to the current
+ − 223 buffer. This will be the beginning of the buffer unless narrowing is in
+ − 224 effect. @xref{Narrowing}.
+ − 225 @end defun
+ − 226
+ − 227 @defun point-max-marker &optional buffer
+ − 228 @cindex end of buffer marker
+ − 229 This function returns a new marker that points to the end of the
+ − 230 accessible portion of @var{buffer}, which defaults to the current
+ − 231 buffer. This will be the end of the buffer unless narrowing is in
+ − 232 effect. @xref{Narrowing}.
+ − 233
+ − 234 Here are examples of this function and @code{point-min-marker}, shown in
+ − 235 a buffer containing a version of the source file for the text of this
+ − 236 chapter.
+ − 237
+ − 238 @example
+ − 239 @group
+ − 240 (point-min-marker)
+ − 241 @result{} #<marker at 1 in markers.texi>
+ − 242 (point-max-marker)
+ − 243 @result{} #<marker at 15573 in markers.texi>
+ − 244 @end group
+ − 245
+ − 246 @group
+ − 247 (narrow-to-region 100 200)
+ − 248 @result{} nil
+ − 249 @end group
+ − 250 @group
+ − 251 (point-min-marker)
+ − 252 @result{} #<marker at 100 in markers.texi>
+ − 253 @end group
+ − 254 @group
+ − 255 (point-max-marker)
+ − 256 @result{} #<marker at 200 in markers.texi>
+ − 257 @end group
+ − 258 @end example
+ − 259 @end defun
+ − 260
444
+ − 261 @defun copy-marker marker-or-integer &optional marker-type
428
+ − 262 If passed a marker as its argument, @code{copy-marker} returns a
+ − 263 new marker that points to the same place and the same buffer as does
+ − 264 @var{marker-or-integer}. If passed an integer as its argument,
+ − 265 @code{copy-marker} returns a new marker that points to position
+ − 266 @var{marker-or-integer} in the current buffer.
+ − 267
+ − 268 If passed an integer argument less than 1, @code{copy-marker} returns a
+ − 269 new marker that points to the beginning of the current buffer. If
+ − 270 passed an integer argument greater than the length of the buffer,
+ − 271 @code{copy-marker} returns a new marker that points to the end of the
+ − 272 buffer.
+ − 273
444
+ − 274 An error is signaled if @var{marker-or-integer} is neither a marker nor
+ − 275 an integer.
+ − 276
+ − 277 Optional second argument @var{marker-type} specifies the insertion type
+ − 278 of the new marker; see @code{marker-insertion-type}.
428
+ − 279
+ − 280 @example
+ − 281 @group
+ − 282 (setq p (point-marker))
+ − 283 @result{} #<marker at 2139 in markers.texi>
+ − 284 @end group
+ − 285
+ − 286 @group
+ − 287 (setq q (copy-marker p))
+ − 288 @result{} #<marker at 2139 in markers.texi>
+ − 289 @end group
+ − 290
+ − 291 @group
+ − 292 (eq p q)
+ − 293 @result{} nil
+ − 294 @end group
+ − 295
+ − 296 @group
+ − 297 (equal p q)
+ − 298 @result{} t
+ − 299 @end group
+ − 300
+ − 301 @group
+ − 302 (point)
+ − 303 @result{} 2139
+ − 304 @end group
+ − 305
+ − 306 @group
+ − 307 (set-marker p 3000)
+ − 308 @result{} #<marker at 3000 in markers.texi>
+ − 309 @end group
+ − 310
+ − 311 @group
+ − 312 (point)
+ − 313 @result{} 2139
+ − 314 @end group
+ − 315
+ − 316 @group
+ − 317 (setq p (point-marker t))
+ − 318 @result{} #<marker at 2139 in markers.texi>
+ − 319 @end group
+ − 320
+ − 321 @group
+ − 322 (set-marker p 3000)
+ − 323 @result{} #<marker at 3000 in markers.texi>
+ − 324 @end group
+ − 325
+ − 326 @group
+ − 327 (point)
+ − 328 @result{} 3000
+ − 329 @end group
+ − 330
+ − 331 @group
+ − 332 (copy-marker 0)
+ − 333 @result{} #<marker at 1 in markers.texi>
+ − 334 @end group
+ − 335
+ − 336 @group
+ − 337 (copy-marker 20000)
+ − 338 @result{} #<marker at 7572 in markers.texi>
+ − 339 @end group
+ − 340 @end example
+ − 341 @end defun
+ − 342
+ − 343 @node Information from Markers
+ − 344 @section Information from Markers
+ − 345
+ − 346 This section describes the functions for accessing the components of a
+ − 347 marker object.
+ − 348
+ − 349 @defun marker-position marker
+ − 350 This function returns the position that @var{marker} points to, or
+ − 351 @code{nil} if it points nowhere.
+ − 352 @end defun
+ − 353
+ − 354 @defun marker-buffer marker
+ − 355 This function returns the buffer that @var{marker} points into, or
+ − 356 @code{nil} if it points nowhere.
+ − 357
+ − 358 @example
+ − 359 @group
+ − 360 (setq m (make-marker))
+ − 361 @result{} #<marker in no buffer>
+ − 362 @end group
+ − 363 @group
+ − 364 (marker-position m)
+ − 365 @result{} nil
+ − 366 @end group
+ − 367 @group
+ − 368 (marker-buffer m)
+ − 369 @result{} nil
+ − 370 @end group
+ − 371
+ − 372 @group
+ − 373 (set-marker m 3770 (current-buffer))
+ − 374 @result{} #<marker at 3770 in markers.texi>
+ − 375 @end group
+ − 376 @group
+ − 377 (marker-buffer m)
+ − 378 @result{} #<buffer markers.texi>
+ − 379 @end group
+ − 380 @group
+ − 381 (marker-position m)
+ − 382 @result{} 3770
+ − 383 @end group
+ − 384 @end example
+ − 385 @end defun
+ − 386
+ − 387 Two distinct markers are considered @code{equal} (even though not
+ − 388 @code{eq}) to each other if they have the same position and buffer, or
+ − 389 if they both point nowhere.
+ − 390
+ − 391 @node Changing Markers
+ − 392 @section Changing Marker Positions
+ − 393
+ − 394 This section describes how to change the position of an existing
+ − 395 marker. When you do this, be sure you know whether the marker is used
+ − 396 outside of your program, and, if so, what effects will result from
+ − 397 moving it---otherwise, confusing things may happen in other parts of
+ − 398 Emacs.
+ − 399
+ − 400 @defun set-marker marker position &optional buffer
+ − 401 This function moves @var{marker} to @var{position}
+ − 402 in @var{buffer}. If @var{buffer} is not provided, it defaults to
+ − 403 the current buffer.
+ − 404
444
+ − 405 @var{position} can be a marker, an integer or @code{nil}. If
+ − 406 @var{position} is an integer, @code{set-marker} moves @var{marker} to
+ − 407 point before the @var{position}th character in @var{buffer}. If
+ − 408 @var{position} is @code{nil}, @var{marker} is made to point nowhere.
+ − 409 Then it no longer slows down editing in any buffer. If @var{position}
+ − 410 is less than 1, @var{marker} is moved to the beginning of @var{buffer}.
+ − 411 If @var{position} is greater than the size of @var{buffer}, @var{marker}
+ − 412 is moved to the end of @var{buffer}.
428
+ − 413
+ − 414 The value returned is @var{marker}.
+ − 415
+ − 416 @example
+ − 417 @group
+ − 418 (setq m (point-marker))
+ − 419 @result{} #<marker at 4714 in markers.texi>
+ − 420 @end group
+ − 421 @group
+ − 422 (set-marker m 55)
+ − 423 @result{} #<marker at 55 in markers.texi>
+ − 424 @end group
+ − 425 @group
+ − 426 (setq b (get-buffer "foo"))
+ − 427 @result{} #<buffer foo>
+ − 428 @end group
+ − 429 @group
+ − 430 (set-marker m 0 b)
+ − 431 @result{} #<marker at 1 in foo>
+ − 432 @end group
+ − 433 @end example
+ − 434 @end defun
+ − 435
+ − 436 @defun move-marker marker position &optional buffer
+ − 437 This is another name for @code{set-marker}.
+ − 438 @end defun
+ − 439
+ − 440 @node The Mark
+ − 441 @section The Mark
+ − 442 @cindex mark, the
+ − 443 @cindex mark ring
+ − 444 @cindex global mark ring
+ − 445
+ − 446 One special marker in each buffer is designated @dfn{the mark}. It
+ − 447 records a position for the user for the sake of commands such as
+ − 448 @kbd{C-w} and @kbd{C-x @key{TAB}}. Lisp programs should set the mark
+ − 449 only to values that have a potential use to the user, and never for
+ − 450 their own internal purposes. For example, the @code{replace-regexp}
+ − 451 command sets the mark to the value of point before doing any
+ − 452 replacements, because this enables the user to move back there
+ − 453 conveniently after the replace is finished.
+ − 454
+ − 455 Once the mark ``exists'' in a buffer, it normally never ceases to
+ − 456 exist. However, it may become @dfn{inactive}, and usually does so
+ − 457 after each command (other than simple motion commands and some
+ − 458 commands that explicitly activate the mark). When the mark is active,
+ − 459 the region between point and the mark is called the @dfn{active region}
+ − 460 and is highlighted specially.
+ − 461
+ − 462 Many commands are designed so that when called interactively they
+ − 463 operate on the text between point and the mark. Such commands work
+ − 464 only when an active region exists, i.e. when the mark is active.
+ − 465 (The reason for this is to prevent you from accidentally deleting
+ − 466 or changing large chunks of your text.) If you are writing such
+ − 467 a command, don't examine the mark directly; instead, use
+ − 468 @code{interactive} with the @samp{r} specification. This provides the
+ − 469 values of point and the mark as arguments to the command in an
+ − 470 interactive call, but permits other Lisp programs to specify arguments
+ − 471 explicitly, and automatically signals an error if the command is called
+ − 472 interactively when no active region exists. @xref{Interactive Codes}.
+ − 473
+ − 474 Each buffer has its own value of the mark that is independent of the
+ − 475 value of the mark in other buffers. (When a buffer is created, the mark
+ − 476 exists but does not point anywhere. We consider this state as ``the
+ − 477 absence of a mark in that buffer.'') However, only one active region can
+ − 478 exist at a time. Activating the mark in one buffer automatically
+ − 479 deactivates an active mark in any other buffer. Note that the user can
+ − 480 explicitly activate a mark at any time by using the command
+ − 481 @code{activate-region} (normally bound to @kbd{M-C-z}) or by using the
+ − 482 command @code{exchange-point-and-mark} (normally bound to @kbd{C-x C-x}),
+ − 483 which has the side effect of activating the mark.
+ − 484
+ − 485 Some people do not like active regions, so they disable this behavior
+ − 486 by setting the variable @code{zmacs-regions} to @code{nil}. This makes
+ − 487 the mark always active (except when a buffer is just created and the
+ − 488 mark points nowhere), and turns off the highlighting of the region
+ − 489 between point and the mark. Commands that explicitly retrieve the value
+ − 490 of the mark should make sure that they behave correctly and consistently
+ − 491 irrespective of the setting of @code{zmacs-regions}; some primitives are
+ − 492 provided to ensure this behavior.
+ − 493
+ − 494 In addition to the mark, each buffer has a @dfn{mark ring} which is a
+ − 495 list of markers containing previous values of the mark. When editing
+ − 496 commands change the mark, they should normally save the old value of the
+ − 497 mark on the mark ring. The variable @code{mark-ring-max} specifies the
+ − 498 maximum number of entries in the mark ring; once the list becomes this
+ − 499 long, adding a new element deletes the last element.
+ − 500
+ − 501 @defun mark &optional force buffer
+ − 502 @cindex current buffer mark
+ − 503 This function returns @var{buffer}'s mark position as an integer.
+ − 504 @var{buffer} defaults to the current buffer if omitted.
+ − 505
+ − 506 If the mark is inactive, @code{mark} normally returns @code{nil}.
+ − 507 However, if @var{force} is non-@code{nil}, then @code{mark} returns the
+ − 508 mark position anyway---or @code{nil}, if the mark is not yet set for
+ − 509 the buffer.
+ − 510
1738
+ − 511 (Remember that if @code{zmacs-regions} is @code{nil}, the mark is
428
+ − 512 always active as long as it exists, and the @var{force} argument
+ − 513 will have no effect.)
+ − 514
+ − 515 If you are using this in an editing command, you are most likely making
+ − 516 a mistake; see the documentation of @code{set-mark} below.
+ − 517 @end defun
+ − 518
444
+ − 519 @defun mark-marker &optional force buffer
428
+ − 520 This function returns @var{buffer}'s mark. @var{buffer} defaults to the
+ − 521 current buffer if omitted. This is the very marker that records the
+ − 522 mark location inside XEmacs, not a copy. Therefore, changing this
+ − 523 marker's position will directly affect the position of the mark. Don't
+ − 524 do it unless that is the effect you want.
+ − 525
+ − 526 If the mark is inactive, @code{mark-marker} normally returns @code{nil}.
+ − 527 However, if @var{force} is non-@code{nil}, then @code{mark-marker}
+ − 528 returns the mark anyway.
+ − 529 @example
+ − 530 @group
+ − 531 (setq m (mark-marker))
+ − 532 @result{} #<marker at 3420 in markers.texi>
+ − 533 @end group
+ − 534 @group
+ − 535 (set-marker m 100)
+ − 536 @result{} #<marker at 100 in markers.texi>
+ − 537 @end group
+ − 538 @group
+ − 539 (mark-marker)
+ − 540 @result{} #<marker at 100 in markers.texi>
+ − 541 @end group
+ − 542 @end example
+ − 543
+ − 544 Like any marker, this marker can be set to point at any buffer you like.
+ − 545 We don't recommend that you make it point at any buffer other than the
+ − 546 one of which it is the mark. If you do, it will yield perfectly
+ − 547 consistent, but rather odd, results.
+ − 548 @end defun
+ − 549
+ − 550 @ignore
+ − 551 @deffn Command set-mark-command jump
+ − 552 If @var{jump} is @code{nil}, this command sets the mark to the value
+ − 553 of point and pushes the previous value of the mark on the mark ring. The
+ − 554 message @samp{Mark set} is also displayed in the echo area.
+ − 555
+ − 556 If @var{jump} is not @code{nil}, this command sets point to the value
+ − 557 of the mark, and sets the mark to the previous saved mark value, which
+ − 558 is popped off the mark ring.
+ − 559
+ − 560 This function is @emph{only} intended for interactive use.
+ − 561 @end deffn
+ − 562 @end ignore
+ − 563
+ − 564 @defun set-mark position &optional buffer
+ − 565 This function sets @code{buffer}'s mark to @var{position}, and activates
+ − 566 the mark. @var{buffer} defaults to the current buffer if omitted. The
+ − 567 old value of the mark is @emph{not} pushed onto the mark ring.
+ − 568
+ − 569 @strong{Please note:} Use this function only if you want the user to
+ − 570 see that the mark has moved, and you want the previous mark position to
+ − 571 be lost. Normally, when a new mark is set, the old one should go on the
+ − 572 @code{mark-ring}. For this reason, most applications should use
+ − 573 @code{push-mark} and @code{pop-mark}, not @code{set-mark}.
+ − 574
+ − 575 Novice XEmacs Lisp programmers often try to use the mark for the wrong
+ − 576 purposes. The mark saves a location for the user's convenience. An
+ − 577 editing command should not alter the mark unless altering the mark is
+ − 578 part of the user-level functionality of the command. (And, in that
+ − 579 case, this effect should be documented.) To remember a location for
+ − 580 internal use in the Lisp program, store it in a Lisp variable. For
+ − 581 example:
+ − 582
+ − 583 @example
+ − 584 @group
444
+ − 585 (let ((start (point)))
428
+ − 586 (forward-line 1)
444
+ − 587 (delete-region start (point))).
428
+ − 588 @end group
+ − 589 @end example
+ − 590 @end defun
+ − 591
+ − 592 @deffn Command exchange-point-and-mark &optional dont-activate-region
+ − 593 This function exchanges the positions of point and the mark.
+ − 594 It is intended for interactive use. The mark is also activated
+ − 595 unless @var{dont-activate-region} is non-@code{nil}.
+ − 596 @end deffn
+ − 597
+ − 598 @defun push-mark &optional position nomsg activate buffer
+ − 599 This function sets @var{buffer}'s mark to @var{position}, and pushes a
+ − 600 copy of the previous mark onto @code{mark-ring}. @var{buffer} defaults
+ − 601 to the current buffer if omitted. If @var{position} is @code{nil}, then
+ − 602 the value of point is used. @code{push-mark} returns @code{nil}.
+ − 603
+ − 604 If the last global mark pushed was not in @var{buffer}, also push
+ − 605 @var{position} on the global mark ring (see below).
+ − 606
+ − 607 The function @code{push-mark} normally @emph{does not} activate the
+ − 608 mark. To do that, specify @code{t} for the argument @var{activate}.
+ − 609
+ − 610 A @samp{Mark set} message is displayed unless @var{nomsg} is
+ − 611 non-@code{nil}.
+ − 612 @end defun
+ − 613
+ − 614 @defun pop-mark
+ − 615 This function pops off the top element of @code{mark-ring} and makes
+ − 616 that mark become the buffer's actual mark. This does not move point in
+ − 617 the buffer, and it does nothing if @code{mark-ring} is empty. It
+ − 618 deactivates the mark.
+ − 619
+ − 620 The return value is not meaningful.
+ − 621 @end defun
+ − 622
+ − 623 @defvar mark-ring
+ − 624 The value of this buffer-local variable is the list of saved former
+ − 625 marks of the current buffer, most recent first.
+ − 626
+ − 627 @example
+ − 628 @group
+ − 629 mark-ring
444
+ − 630 @result{} (#<marker at 11050 in markers.texi>
428
+ − 631 #<marker at 10832 in markers.texi>
+ − 632 @dots{})
+ − 633 @end group
+ − 634 @end example
+ − 635 @end defvar
+ − 636
+ − 637 @defopt mark-ring-max
+ − 638 The value of this variable is the maximum size of @code{mark-ring}. If
+ − 639 more marks than this are pushed onto the @code{mark-ring},
+ − 640 @code{push-mark} discards an old mark when it adds a new one.
+ − 641 @end defopt
+ − 642
+ − 643 In additional to a per-buffer mark ring, there is a @dfn{global mark
+ − 644 ring}. Marks are pushed onto the global mark ring the first time you
+ − 645 set a mark after switching buffers.
+ − 646
+ − 647 @defvar global-mark-ring
+ − 648 The value of this variable is the list of saved former global marks,
+ − 649 most recent first.
+ − 650 @end defvar
+ − 651
+ − 652 @defopt mark-ring-max
+ − 653 The value of this variable is the maximum size of
+ − 654 @code{global-mark-ring}. If more marks than this are pushed onto the
+ − 655 @code{global-mark-ring}, @code{push-mark} discards an old mark when it
+ − 656 adds a new one.
+ − 657 @end defopt
+ − 658
+ − 659 @deffn Command pop-global-mark
+ − 660 This function pops a mark off the global mark ring and jumps to that
+ − 661 location.
+ − 662 @end deffn
+ − 663
+ − 664 @node The Region
+ − 665 @section The Region
+ − 666 @cindex region, the
+ − 667
+ − 668 The text between point and the mark is known as @dfn{the region}.
+ − 669 Various functions operate on text delimited by point and the mark, but
+ − 670 only those functions specifically related to the region itself are
+ − 671 described here.
+ − 672
+ − 673 When @code{zmacs-regions} is non-@code{nil} (this is the default), the
+ − 674 concept of an @dfn{active region} exists. The region is active when the
+ − 675 corresponding mark is active. Note that only one active region at a
440
+ − 676 time can exist---i.e. only one buffer's region is active at a time.
428
+ − 677 @xref{The Mark}, for more information about active regions.
+ − 678
+ − 679 @defopt zmacs-regions
+ − 680 If non-@code{nil} (the default), active regions are used. @xref{The Mark},
+ − 681 for a detailed explanation of what this means.
+ − 682 @end defopt
+ − 683
+ − 684 A number of functions are provided for explicitly determining the
+ − 685 bounds of the region and whether it is active. Few programs need to use
+ − 686 these functions, however. A command designed to operate on a region
+ − 687 should normally use @code{interactive} with the @samp{r} specification
+ − 688 to find the beginning and end of the region. This lets other Lisp
+ − 689 programs specify the bounds explicitly as arguments and automatically
1738
+ − 690 respects the user's setting for @code{zmacs-regions}.
+ − 691 (@xref{Interactive Codes}.)
428
+ − 692
+ − 693 @defun region-beginning &optional buffer
+ − 694 This function returns the position of the beginning of @var{buffer}'s
+ − 695 region (as an integer). This is the position of either point or the
+ − 696 mark, whichever is smaller. @var{buffer} defaults to the current buffer
+ − 697 if omitted.
+ − 698
+ − 699 If the mark does not point anywhere, an error is signaled. Note that
+ − 700 this function ignores whether the region is active.
+ − 701 @end defun
+ − 702
+ − 703 @defun region-end &optional buffer
+ − 704 This function returns the position of the end of @var{buffer}'s region
+ − 705 (as an integer). This is the position of either point or the mark,
+ − 706 whichever is larger. @var{buffer} defaults to the current buffer if
+ − 707 omitted.
+ − 708
+ − 709 If the mark does not point anywhere, an error is signaled. Note that
+ − 710 this function ignores whether the region is active.
+ − 711 @end defun
+ − 712
+ − 713 @defun region-exists-p
+ − 714 This function is non-@code{nil} if the region exists. If active regions
+ − 715 are in use (i.e. @code{zmacs-regions} is true), this means that the
+ − 716 region is active. Otherwise, this means that the user has pushed a mark
+ − 717 in this buffer at some point in the past. If this function returns @code{nil},
+ − 718 a function that uses the @samp{r} interactive specification will cause
+ − 719 an error when called interactively.
+ − 720 @end defun
+ − 721
+ − 722 @defun region-active-p
+ − 723 If @code{zmacs-regions} is true, this is equivalent to
+ − 724 @code{region-exists-p}. Otherwise, this function always returns false.
+ − 725 This function is used by commands such as @code{fill-paragraph-or-region}
+ − 726 and @code{capitalize-region-or-word}, which operate either on the active
+ − 727 region or on something else (e.g. the word or paragraph at point).
+ − 728 @end defun
+ − 729
+ − 730 @defvar zmacs-region-stays
+ − 731 If a command sets this variable to true, the currently active region
+ − 732 will remain activated when the command finishes. (Normally the region is
1738
+ − 733 deactivated when each command terminates.) If @code{zmacs-regions} is
428
+ − 734 false, however, this has no effect. Under normal circumstances, you do
+ − 735 not need to set this; use the interactive specification @samp{_}
+ − 736 instead, if you want the region to remain active.
+ − 737 @end defvar
+ − 738
+ − 739 @defun zmacs-activate-region
+ − 740 This function activates the region in the current buffer (this is
+ − 741 equivalent to activating the current buffer's mark). This will normally
+ − 742 also highlight the text in the active region and set
1738
+ − 743 @code{zmacs-region-stays} to @code{t}. (If @code{zmacs-regions} is
+ − 744 false, however, this function has no effect.)
428
+ − 745 @end defun
+ − 746
+ − 747 @defun zmacs-deactivate-region
+ − 748 This function deactivates the region in the current buffer (this is
+ − 749 equivalent to deactivating the current buffer's mark). This will
+ − 750 normally also unhighlight the text in the active region and set
1738
+ − 751 @code{zmacs-region-stays} to @code{nil}. (If @code{zmacs-regions} is
428
+ − 752 false, however, this function has no effect.)
+ − 753 @end defun
+ − 754
+ − 755 @defun zmacs-update-region
+ − 756 This function updates the active region, if it's currently active. (If
+ − 757 there is no active region, this function does nothing.) This has the
+ − 758 effect of updating the highlighting on the text in the region; but you
+ − 759 should never need to call this except under rather strange
+ − 760 circumstances. The command loop automatically calls it when
+ − 761 appropriate. Calling this function will call the hook
+ − 762 @code{zmacs-update-region-hook}, if the region is active.
+ − 763 @end defun
+ − 764
+ − 765 @defvar zmacs-activate-region-hook
+ − 766 This normal hook is called when a region becomes active. (Usually this
+ − 767 happens as a result of a command that activates the region, such as
+ − 768 @code{set-mark-command}, @code{activate-region}, or
+ − 769 @code{exchange-point-and-mark}.) Note that calling
+ − 770 @file{zmacs-activate-region} will call this hook, even if the region is
1738
+ − 771 already active. If @code{zmacs-regions} is false, however, this hook
428
+ − 772 will never get called under any circumstances.
+ − 773 @end defvar
+ − 774
+ − 775 @defvar zmacs-deactivate-region-hook
+ − 776 This normal hook is called when an active region becomes inactive.
+ − 777 (Calling @file{zmacs-deactivate-region} when the region is inactive will
1738
+ − 778 @emph{not} cause this hook to be called.) If @code{zmacs-regions} is
428
+ − 779 false, this hook will never get called.
+ − 780 @end defvar
+ − 781
+ − 782 @defvar zmacs-update-region-hook
+ − 783 This normal hook is called when an active region is "updated" by
+ − 784 @code{zmacs-update-region}. This normally gets called at the end
1738
+ − 785 of each command that sets @code{zmacs-region-stays} to @code{t},
428
+ − 786 indicating that the region should remain activated. The motion
+ − 787 commands do this.
+ − 788 @end defvar
+ − 789
+ − 790
