2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/markers.info
8 @node Markers, Text, Positions, Top
12 A @dfn{marker} is a Lisp object used to specify a position in a buffer
13 relative to the surrounding text. A marker changes its offset from the
14 beginning of the buffer automatically whenever text is inserted or
15 deleted, so that it stays with the two characters on either side of it.
18 * Overview of Markers:: The components of a marker, and how it relocates.
19 * Predicates on Markers:: Testing whether an object is a marker.
20 * Creating Markers:: Making empty markers or markers at certain places.
21 * Information from Markers:: Finding the marker's buffer or character position.
22 * Changing Markers:: Moving the marker to a new buffer or position.
23 * The Mark:: How ``the mark'' is implemented with a marker.
24 * The Region:: How to access ``the region''.
28 @node Overview of Markers
29 @section Overview of Markers
31 A marker specifies a buffer and a position in that buffer. The marker
32 can be used to represent a position in the functions that require one,
33 just as an integer could be used. @xref{Positions}, for a complete
34 description of positions.
36 A marker has two attributes: the marker position, and the marker
37 buffer. The marker position is an integer that is equivalent (at a
38 given time) to the marker as a position in that buffer. But the
39 marker's position value can change often during the life of the marker.
40 Insertion and deletion of text in the buffer relocate the marker. The
41 idea is that a marker positioned between two characters remains between
42 those two characters despite insertion and deletion elsewhere in the
43 buffer. Relocation changes the integer equivalent of the marker.
45 @cindex marker relocation
46 Deleting text around a marker's position leaves the marker between the
47 characters immediately before and after the deleted text. Inserting
48 text at the position of a marker normally leaves the marker in front of
49 the new text---unless it is inserted with @code{insert-before-markers}
52 @cindex marker garbage collection
53 Insertion and deletion in a buffer must check all the markers and
54 relocate them if necessary. This slows processing in a buffer with a
55 large number of markers. For this reason, it is a good idea to make a
56 marker point nowhere if you are sure you don't need it any more.
57 Unreferenced markers are garbage collected eventually, but until then
58 will continue to use time if they do point somewhere.
60 @cindex markers as numbers
61 Because it is common to perform arithmetic operations on a marker
62 position, most of the arithmetic operations (including @code{+} and
63 @code{-}) accept markers as arguments. In such cases, the marker
64 stands for its current position.
66 @cindex markers vs. extents
67 Note that you can use extents to achieve the same functionality, and
68 more, as markers. (Markers were defined before extents, which is why
69 they both continue to exist.) A zero-length extent with the
70 @code{detachable} property removed is almost identical to a marker.
71 (@xref{Extent Endpoints}, for more information on zero-length extents.)
77 In order to get marker-like behavior in a zero-length extent, the
78 @code{detachable} property must be removed (otherwise, the extent
79 will disappear when text near it is deleted) and exactly one
80 endpoint must be closed (if both endpoints are closed, the extent
81 will expand to contain text inserted where it is located).
83 If a zero-length extent has the @code{end-open} property but not
84 the @code{start-open} property (this is the default), text inserted
85 at the extent's location causes the extent to move forward, just
88 If a zero-length extent has the @code{start-open} property but not
89 the @code{end-open} property, text inserted at the extent's location
90 causes the extent to remain before the text, like what happens to
91 markers when @code{insert-before-markers} is used.
93 Markers end up after or before inserted text depending on whether
94 @code{insert} or @code{insert-before-markers} was called. These
95 functions do not affect zero-length extents differently; instead,
96 the presence or absence of the @code{start-open} and @code{end-open}
97 extent properties determines this, as just described.
99 Markers are automatically removed from a buffer when they are no
100 longer in use. Extents remain around until explicitly removed
103 Many functions are provided for listing the extents in a buffer or
104 in a region of a buffer. No such functions exist for markers.
107 Here are examples of creating markers, setting markers, and moving point
112 ;; @r{Make a new marker that initially does not point anywhere:}
113 (setq m1 (make-marker))
114 @result{} #<marker in no buffer>
118 ;; @r{Set @code{m1} to point between the 99th and 100th characters}
119 ;; @r{in the current buffer:}
121 @result{} #<marker at 100 in markers.texi>
125 ;; @r{Now insert one character at the beginning of the buffer:}
126 (goto-char (point-min))
133 ;; @r{@code{m1} is updated appropriately.}
135 @result{} #<marker at 101 in markers.texi>
139 ;; @r{Two markers that point to the same position}
140 ;; @r{are not @code{eq}, but they are @code{equal}.}
141 (setq m2 (copy-marker m1))
142 @result{} #<marker at 101 in markers.texi>
150 ;; @r{When you are finished using a marker, make it point nowhere.}
152 @result{} #<marker in no buffer>
157 @node Predicates on Markers
158 @section Predicates on Markers
160 You can test an object to see whether it is a marker, or whether it is
161 either an integer or a marker or either an integer, a character, or a
162 marker. The latter tests are useful in connection with the arithmetic
163 functions that work with any of markers, integers, or characters.
165 @defun markerp object
166 This function returns @code{t} if @var{object} is a marker, @code{nil}
167 otherwise. Note that integers are not markers, even though many
168 functions will accept either a marker or an integer.
171 @defun integer-or-marker-p object
172 This function returns @code{t} if @var{object} is an integer or a marker,
173 @code{nil} otherwise.
176 @defun integer-char-or-marker-p object
177 This function returns @code{t} if @var{object} is an integer, a
178 character, or a marker, @code{nil} otherwise.
181 @defun number-or-marker-p object
182 This function returns @code{t} if @var{object} is a number (either kind)
183 or a marker, @code{nil} otherwise.
186 @defun number-char-or-marker-p object
187 This function returns @code{t} if @var{object} is a number (either
188 kind), a character, or a marker, @code{nil} otherwise.
192 @node Creating Markers
193 @section Functions That Create Markers
195 When you create a new marker, you can make it point nowhere, or point
196 to the present position of point, or to the beginning or end of the
197 accessible portion of the buffer, or to the same place as another given
201 This functions returns a newly created marker that does not point
207 @result{} #<marker in no buffer>
212 @defun point-marker &optional dont-copy-p buffer
213 This function returns a marker that points to the present position of
214 point in @var{buffer}, which defaults to the current buffer.
215 @xref{Point}. For an example, see @code{copy-marker}, below.
217 Internally, a marker corresponding to point is always maintained.
218 Normally the marker returned by @code{point-marker} is a copy; you
219 may modify it with reckless abandon. However, if optional argument
220 @var{dont-copy-p} is non-@code{nil}, then the real point-marker is
221 returned; modifying the position of this marker will move point.
222 It is illegal to change the buffer of it, or make it point nowhere.
225 @defun point-min-marker &optional buffer
226 This function returns a new marker that points to the beginning of the
227 accessible portion of @var{buffer}, which defaults to the current
228 buffer. This will be the beginning of the buffer unless narrowing is in
229 effect. @xref{Narrowing}.
232 @defun point-max-marker &optional buffer
233 @cindex end of buffer marker
234 This function returns a new marker that points to the end of the
235 accessible portion of @var{buffer}, which defaults to the current
236 buffer. This will be the end of the buffer unless narrowing is in
237 effect. @xref{Narrowing}.
239 Here are examples of this function and @code{point-min-marker}, shown in
240 a buffer containing a version of the source file for the text of this
246 @result{} #<marker at 1 in markers.texi>
248 @result{} #<marker at 15573 in markers.texi>
252 (narrow-to-region 100 200)
257 @result{} #<marker at 100 in markers.texi>
261 @result{} #<marker at 200 in markers.texi>
266 @defun copy-marker marker-or-integer &optional marker-type
267 If passed a marker as its argument, @code{copy-marker} returns a
268 new marker that points to the same place and the same buffer as does
269 @var{marker-or-integer}. If passed an integer as its argument,
270 @code{copy-marker} returns a new marker that points to position
271 @var{marker-or-integer} in the current buffer.
273 If passed an integer argument less than 1, @code{copy-marker} returns a
274 new marker that points to the beginning of the current buffer. If
275 passed an integer argument greater than the length of the buffer,
276 @code{copy-marker} returns a new marker that points to the end of the
279 An error is signaled if @var{marker-or-integer} is neither a marker nor
282 Optional second argument @var{marker-type} specifies the insertion type
283 of the new marker; see @code{marker-insertion-type}.
287 (setq p (point-marker))
288 @result{} #<marker at 2139 in markers.texi>
292 (setq q (copy-marker p))
293 @result{} #<marker at 2139 in markers.texi>
313 @result{} #<marker at 3000 in markers.texi>
322 (setq p (point-marker t))
323 @result{} #<marker at 2139 in markers.texi>
328 @result{} #<marker at 3000 in markers.texi>
338 @result{} #<marker at 1 in markers.texi>
343 @result{} #<marker at 7572 in markers.texi>
349 @node Information from Markers
350 @section Information from Markers
352 This section describes the functions for accessing the components of a
355 @defun marker-position marker
356 This function returns the position that @var{marker} points to, or
357 @code{nil} if it points nowhere.
360 @defun marker-buffer marker
361 This function returns the buffer that @var{marker} points into, or
362 @code{nil} if it points nowhere.
366 (setq m (make-marker))
367 @result{} #<marker in no buffer>
379 (set-marker m 3770 (current-buffer))
380 @result{} #<marker at 3770 in markers.texi>
384 @result{} #<buffer markers.texi>
393 Two distinct markers are considered @code{equal} (even though not
394 @code{eq}) to each other if they have the same position and buffer, or
395 if they both point nowhere.
398 @node Changing Markers
399 @section Changing Marker Positions
401 This section describes how to change the position of an existing
402 marker. When you do this, be sure you know whether the marker is used
403 outside of your program, and, if so, what effects will result from
404 moving it---otherwise, confusing things may happen in other parts of
407 @defun set-marker marker position &optional buffer
408 This function moves @var{marker} to @var{position}
409 in @var{buffer}. If @var{buffer} is not provided, it defaults to
412 @var{position} can be a marker, an integer or @code{nil}. If
413 @var{position} is an integer, @code{set-marker} moves @var{marker} to
414 point before the @var{position}th character in @var{buffer}. If
415 @var{position} is @code{nil}, @var{marker} is made to point nowhere.
416 Then it no longer slows down editing in any buffer. If @var{position}
417 is less than 1, @var{marker} is moved to the beginning of @var{buffer}.
418 If @var{position} is greater than the size of @var{buffer}, @var{marker}
419 is moved to the end of @var{buffer}.
421 The value returned is @var{marker}.
425 (setq m (point-marker))
426 @result{} #<marker at 4714 in markers.texi>
430 @result{} #<marker at 55 in markers.texi>
433 (setq b (get-buffer "foo"))
434 @result{} #<buffer foo>
438 @result{} #<marker at 1 in foo>
443 @defun move-marker marker position &optional buffer
444 This is another name for @code{set-marker}.
452 @cindex global mark ring
454 One special marker in each buffer is designated @dfn{the mark}. It
455 records a position for the user for the sake of commands such as
456 @kbd{C-w} and @kbd{C-x @key{TAB}}. Lisp programs should set the mark
457 only to values that have a potential use to the user, and never for
458 their own internal purposes. For example, the @code{replace-regexp}
459 command sets the mark to the value of point before doing any
460 replacements, because this enables the user to move back there
461 conveniently after the replace is finished.
463 Once the mark ``exists'' in a buffer, it normally never ceases to
464 exist. However, it may become @dfn{inactive}, and usually does so
465 after each command (other than simple motion commands and some
466 commands that explicitly activate the mark). When the mark is active,
467 the region between point and the mark is called the @dfn{active region}
468 and is highlighted specially.
470 Many commands are designed so that when called interactively they
471 operate on the text between point and the mark. Such commands work
472 only when an active region exists, i.e. when the mark is active.
473 (The reason for this is to prevent you from accidentally deleting
474 or changing large chunks of your text.) If you are writing such
475 a command, don't examine the mark directly; instead, use
476 @code{interactive} with the @samp{r} specification. This provides the
477 values of point and the mark as arguments to the command in an
478 interactive call, but permits other Lisp programs to specify arguments
479 explicitly, and automatically signals an error if the command is called
480 interactively when no active region exists. @xref{Interactive Codes}.
482 Each buffer has its own value of the mark that is independent of the
483 value of the mark in other buffers. (When a buffer is created, the mark
484 exists but does not point anywhere. We consider this state as ``the
485 absence of a mark in that buffer.'') However, only one active region can
486 exist at a time. Activating the mark in one buffer automatically
487 deactivates an active mark in any other buffer. Note that the user can
488 explicitly activate a mark at any time by using the command
489 @code{activate-region} (normally bound to @kbd{M-C-z}) or by using the
490 command @code{exchange-point-and-mark} (normally bound to @kbd{C-x C-x}),
491 which has the side effect of activating the mark.
493 Some people do not like active regions, so they disable this behavior
494 by setting the variable @code{zmacs-regions} to @code{nil}. This makes
495 the mark always active (except when a buffer is just created and the
496 mark points nowhere), and turns off the highlighting of the region
497 between point and the mark. Commands that explicitly retrieve the value
498 of the mark should make sure that they behave correctly and consistently
499 irrespective of the setting of @code{zmacs-regions}; some primitives are
500 provided to ensure this behavior.
502 In addition to the mark, each buffer has a @dfn{mark ring} which is a
503 list of markers containing previous values of the mark. When editing
504 commands change the mark, they should normally save the old value of the
505 mark on the mark ring. The variable @code{mark-ring-max} specifies the
506 maximum number of entries in the mark ring; once the list becomes this
507 long, adding a new element deletes the last element.
509 @defun mark &optional force buffer
510 @cindex current buffer mark
511 This function returns @var{buffer}'s mark position as an integer.
512 @var{buffer} defaults to the current buffer if omitted.
514 If the mark is inactive, @code{mark} normally returns @code{nil}.
515 However, if @var{force} is non-@code{nil}, then @code{mark} returns the
516 mark position anyway---or @code{nil}, if the mark is not yet set for
519 (Remember that if @code{zmacs-regions} is @code{nil}, the mark is
520 always active as long as it exists, and the @var{force} argument
521 will have no effect.)
523 If you are using this in an editing command, you are most likely making
524 a mistake; see the documentation of @code{set-mark} below.
527 @defun mark-marker &optional force buffer
528 This function returns @var{buffer}'s mark. @var{buffer} defaults to the
529 current buffer if omitted. This is the very marker that records the
530 mark location inside SXEmacs, not a copy. Therefore, changing this
531 marker's position will directly affect the position of the mark. Don't
532 do it unless that is the effect you want.
534 If the mark is inactive, @code{mark-marker} normally returns @code{nil}.
535 However, if @var{force} is non-@code{nil}, then @code{mark-marker}
536 returns the mark anyway.
539 (setq m (mark-marker))
540 @result{} #<marker at 3420 in markers.texi>
544 @result{} #<marker at 100 in markers.texi>
548 @result{} #<marker at 100 in markers.texi>
552 Like any marker, this marker can be set to point at any buffer you like.
553 We don't recommend that you make it point at any buffer other than the
554 one of which it is the mark. If you do, it will yield perfectly
555 consistent, but rather odd, results.
559 @deffn Command set-mark-command jump
560 If @var{jump} is @code{nil}, this command sets the mark to the value
561 of point and pushes the previous value of the mark on the mark ring. The
562 message @samp{Mark set} is also displayed in the echo area.
564 If @var{jump} is not @code{nil}, this command sets point to the value
565 of the mark, and sets the mark to the previous saved mark value, which
566 is popped off the mark ring.
568 This function is @emph{only} intended for interactive use.
572 @defun set-mark position &optional buffer
573 This function sets @code{buffer}'s mark to @var{position}, and activates
574 the mark. @var{buffer} defaults to the current buffer if omitted. The
575 old value of the mark is @emph{not} pushed onto the mark ring.
577 @strong{Please note:} Use this function only if you want the user to
578 see that the mark has moved, and you want the previous mark position to
579 be lost. Normally, when a new mark is set, the old one should go on the
580 @code{mark-ring}. For this reason, most applications should use
581 @code{push-mark} and @code{pop-mark}, not @code{set-mark}.
583 Novice SXEmacs Lisp programmers often try to use the mark for the wrong
584 purposes. The mark saves a location for the user's convenience. An
585 editing command should not alter the mark unless altering the mark is
586 part of the user-level functionality of the command. (And, in that
587 case, this effect should be documented.) To remember a location for
588 internal use in the Lisp program, store it in a Lisp variable. For
593 (let ((start (point)))
595 (delete-region start (point))).
600 @deffn Command exchange-point-and-mark &optional dont-activate-region
601 This function exchanges the positions of point and the mark.
602 It is intended for interactive use. The mark is also activated
603 unless @var{dont-activate-region} is non-@code{nil}.
606 @defun push-mark &optional position nomsg activate buffer
607 This function sets @var{buffer}'s mark to @var{position}, and pushes a
608 copy of the previous mark onto @code{mark-ring}. @var{buffer} defaults
609 to the current buffer if omitted. If @var{position} is @code{nil}, then
610 the value of point is used. @code{push-mark} returns @code{nil}.
612 If the last global mark pushed was not in @var{buffer}, also push
613 @var{position} on the global mark ring (see below).
615 The function @code{push-mark} normally @emph{does not} activate the
616 mark. To do that, specify @code{t} for the argument @var{activate}.
618 A @samp{Mark set} message is displayed unless @var{nomsg} is
623 This function pops off the top element of @code{mark-ring} and makes
624 that mark become the buffer's actual mark. This does not move point in
625 the buffer, and it does nothing if @code{mark-ring} is empty. It
626 deactivates the mark.
628 The return value is not meaningful.
632 The value of this buffer-local variable is the list of saved former
633 marks of the current buffer, most recent first.
638 @result{} (#<marker at 11050 in markers.texi>
639 #<marker at 10832 in markers.texi>
645 @defopt mark-ring-max
646 The value of this variable is the maximum size of @code{mark-ring}. If
647 more marks than this are pushed onto the @code{mark-ring},
648 @code{push-mark} discards an old mark when it adds a new one.
651 In additional to a per-buffer mark ring, there is a @dfn{global mark
652 ring}. Marks are pushed onto the global mark ring the first time you
653 set a mark after switching buffers.
655 @defvar global-mark-ring
656 The value of this variable is the list of saved former global marks,
660 @defopt mark-ring-max
661 The value of this variable is the maximum size of
662 @code{global-mark-ring}. If more marks than this are pushed onto the
663 @code{global-mark-ring}, @code{push-mark} discards an old mark when it
667 @deffn Command pop-global-mark
668 This function pops a mark off the global mark ring and jumps to that
677 The text between point and the mark is known as @dfn{the region}.
678 Various functions operate on text delimited by point and the mark, but
679 only those functions specifically related to the region itself are
682 When @code{zmacs-regions} is non-@code{nil} (this is the default), the
683 concept of an @dfn{active region} exists. The region is active when the
684 corresponding mark is active. Note that only one active region at a
685 time can exist---i.e. only one buffer's region is active at a time.
686 @xref{The Mark}, for more information about active regions.
688 @defopt zmacs-regions
689 If non-@code{nil} (the default), active regions are used. @xref{The Mark},
690 for a detailed explanation of what this means.
693 A number of functions are provided for explicitly determining the
694 bounds of the region and whether it is active. Few programs need to use
695 these functions, however. A command designed to operate on a region
696 should normally use @code{interactive} with the @samp{r} specification
697 to find the beginning and end of the region. This lets other Lisp
698 programs specify the bounds explicitly as arguments and automatically
699 respects the user's setting for @code{zmacs-regions}.
700 (@xref{Interactive Codes}.)
702 @defun region-beginning &optional buffer
703 This function returns the position of the beginning of @var{buffer}'s
704 region (as an integer). This is the position of either point or the
705 mark, whichever is smaller. @var{buffer} defaults to the current buffer
708 If the mark does not point anywhere, an error is signaled. Note that
709 this function ignores whether the region is active.
712 @defun region-end &optional buffer
713 This function returns the position of the end of @var{buffer}'s region
714 (as an integer). This is the position of either point or the mark,
715 whichever is larger. @var{buffer} defaults to the current buffer if
718 If the mark does not point anywhere, an error is signaled. Note that
719 this function ignores whether the region is active.
722 @defun region-exists-p
723 This function is non-@code{nil} if the region exists. If active regions
724 are in use (i.e. @code{zmacs-regions} is true), this means that the
725 region is active. Otherwise, this means that the user has pushed a mark
726 in this buffer at some point in the past. If this function returns @code{nil},
727 a function that uses the @samp{r} interactive specification will cause
728 an error when called interactively.
731 @defun region-active-p
732 If @code{zmacs-regions} is true, this is equivalent to
733 @code{region-exists-p}. Otherwise, this function always returns false.
734 This function is used by commands such as @code{fill-paragraph-or-region}
735 and @code{capitalize-region-or-word}, which operate either on the active
736 region or on something else (e.g. the word or paragraph at point).
739 @defvar zmacs-region-stays
740 If a command sets this variable to true, the currently active region
741 will remain activated when the command finishes. (Normally the region is
742 deactivated when each command terminates.) If @code{zmacs-regions} is
743 false, however, this has no effect. Under normal circumstances, you do
744 not need to set this; use the interactive specification @samp{_}
745 instead, if you want the region to remain active.
748 @defun zmacs-activate-region
749 This function activates the region in the current buffer (this is
750 equivalent to activating the current buffer's mark). This will normally
751 also highlight the text in the active region and set
752 @code{zmacs-region-stays} to @code{t}. (If @code{zmacs-regions} is
753 false, however, this function has no effect.)
756 @defun zmacs-deactivate-region
757 This function deactivates the region in the current buffer (this is
758 equivalent to deactivating the current buffer's mark). This will
759 normally also unhighlight the text in the active region and set
760 @code{zmacs-region-stays} to @code{nil}. (If @code{zmacs-regions} is
761 false, however, this function has no effect.)
764 @defun zmacs-update-region
765 This function updates the active region, if it's currently active. (If
766 there is no active region, this function does nothing.) This has the
767 effect of updating the highlighting on the text in the region; but you
768 should never need to call this except under rather strange
769 circumstances. The command loop automatically calls it when
770 appropriate. Calling this function will call the hook
771 @code{zmacs-update-region-hook}, if the region is active.
774 @defvar zmacs-activate-region-hook
775 This normal hook is called when a region becomes active. (Usually this
776 happens as a result of a command that activates the region, such as
777 @code{set-mark-command}, @code{activate-region}, or
778 @code{exchange-point-and-mark}.) Note that calling
779 @file{zmacs-activate-region} will call this hook, even if the region is
780 already active. If @code{zmacs-regions} is false, however, this hook
781 will never get called under any circumstances.
784 @defvar zmacs-deactivate-region-hook
785 This normal hook is called when an active region becomes inactive.
786 (Calling @file{zmacs-deactivate-region} when the region is inactive will
787 @emph{not} cause this hook to be called.) If @code{zmacs-regions} is
788 false, this hook will never get called.
791 @defvar zmacs-update-region-hook
792 This normal hook is called when an active region is "updated" by
793 @code{zmacs-update-region}. This normally gets called at the end
794 of each command that sets @code{zmacs-region-stays} to @code{t},
795 indicating that the region should remain activated. The motion