2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/markers
6 @node Markers, Text, Positions, Top
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.
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 * Marker Insertion Types:: Two ways a marker can relocate when you
21 insert where it points.
22 * Moving 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''.
27 @node Overview of Markers
28 @section Overview of Markers
30 A marker specifies a buffer and a position in that buffer. The marker
31 can be used to represent a position in the functions that require one,
32 just as an integer could be used. @xref{Positions}, for a complete
33 description of positions.
35 A marker has two attributes: the marker position, and the marker
36 buffer. The marker position is an integer that is equivalent (at a
37 given time) to the marker as a position in that buffer. But the
38 marker's position value can change often during the life of the marker.
39 Insertion and deletion of text in the buffer relocate the marker. The
40 idea is that a marker positioned between two characters remains between
41 those two characters despite insertion and deletion elsewhere in the
42 buffer. Relocation changes the integer equivalent of the marker.
44 @cindex marker relocation
45 Deleting text around a marker's position leaves the marker between the
46 characters immediately before and after the deleted text. Inserting
47 text at the position of a marker normally leaves the marker either in
48 front of or after the new text, depending on the marker's @dfn{insertion
49 type} (@pxref{Marker Insertion Types})---unless the insertion is done
50 with @code{insert-before-markers} (@pxref{Insertion}).
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 Here are examples of creating markers, setting markers, and moving point
71 ;; @r{Make a new marker that initially does not point anywhere:}
72 (setq m1 (make-marker))
73 @result{} #<marker in no buffer>
77 ;; @r{Set @code{m1} to point between the 99th and 100th characters}
78 ;; @r{in the current buffer:}
80 @result{} #<marker at 100 in markers.texi>
84 ;; @r{Now insert one character at the beginning of the buffer:}
85 (goto-char (point-min))
92 ;; @r{@code{m1} is updated appropriately.}
94 @result{} #<marker at 101 in markers.texi>
98 ;; @r{Two markers that point to the same position}
99 ;; @r{are not @code{eq}, but they are @code{equal}.}
100 (setq m2 (copy-marker m1))
101 @result{} #<marker at 101 in markers.texi>
109 ;; @r{When you are finished using a marker, make it point nowhere.}
111 @result{} #<marker in no buffer>
115 @node Predicates on Markers
116 @section Predicates on Markers
118 You can test an object to see whether it is a marker, or whether it is
119 either an integer or a marker. The latter test is useful in connection
120 with the arithmetic functions that work with both markers and integers.
122 @defun markerp object
123 This function returns @code{t} if @var{object} is a marker, @code{nil}
124 otherwise. Note that integers are not markers, even though many
125 functions will accept either a marker or an integer.
128 @defun integer-or-marker-p object
129 This function returns @code{t} if @var{object} is an integer or a marker,
130 @code{nil} otherwise.
133 @defun number-or-marker-p object
134 This function returns @code{t} if @var{object} is a number (either kind)
135 or a marker, @code{nil} otherwise.
138 @node Creating Markers
139 @section Functions That Create Markers
141 When you create a new marker, you can make it point nowhere, or point
142 to the present position of point, or to the beginning or end of the
143 accessible portion of the buffer, or to the same place as another given
147 This functions returns a newly created marker that does not point
153 @result{} #<marker in no buffer>
159 This function returns a new marker that points to the present position
160 of point in the current buffer. @xref{Point}. For an example, see
161 @code{copy-marker}, below.
164 @defun point-min-marker
165 This function returns a new marker that points to the beginning of the
166 accessible portion of the buffer. This will be the beginning of the
167 buffer unless narrowing is in effect. @xref{Narrowing}.
170 @defun point-max-marker
171 @cindex end of buffer marker
172 This function returns a new marker that points to the end of the
173 accessible portion of the buffer. This will be the end of the buffer
174 unless narrowing is in effect. @xref{Narrowing}.
176 Here are examples of this function and @code{point-min-marker}, shown in
177 a buffer containing a version of the source file for the text of this
183 @result{} #<marker at 1 in markers.texi>
185 @result{} #<marker at 15573 in markers.texi>
189 (narrow-to-region 100 200)
194 @result{} #<marker at 100 in markers.texi>
198 @result{} #<marker at 200 in markers.texi>
203 @defun copy-marker marker-or-integer insertion-type
204 If passed a marker as its argument, @code{copy-marker} returns a
205 new marker that points to the same place and the same buffer as does
206 @var{marker-or-integer}. If passed an integer as its argument,
207 @code{copy-marker} returns a new marker that points to position
208 @var{marker-or-integer} in the current buffer.
210 The new marker's insertion type is specified by the argument
211 @var{insertion-type}. @xref{Marker Insertion Types}.
213 If passed an integer argument less than 1, @code{copy-marker} returns a
214 new marker that points to the beginning of the current buffer. If
215 passed an integer argument greater than the length of the buffer,
216 @code{copy-marker} returns a new marker that points to the end of the
219 An error is signaled if @var{marker} is neither a marker nor an
224 (setq p (point-marker))
225 @result{} #<marker at 2139 in markers.texi>
229 (setq q (copy-marker p))
230 @result{} #<marker at 2139 in markers.texi>
245 @result{} #<marker at 1 in markers.texi>
250 @result{} #<marker at 7572 in markers.texi>
255 @node Information from Markers
256 @section Information from Markers
258 This section describes the functions for accessing the components of a
261 @defun marker-position marker
262 This function returns the position that @var{marker} points to, or
263 @code{nil} if it points nowhere.
266 @defun marker-buffer marker
267 This function returns the buffer that @var{marker} points into, or
268 @code{nil} if it points nowhere.
272 (setq m (make-marker))
273 @result{} #<marker in no buffer>
285 (set-marker m 3770 (current-buffer))
286 @result{} #<marker at 3770 in markers.texi>
290 @result{} #<buffer markers.texi>
299 Two distinct markers are considered @code{equal} (even though not
300 @code{eq}) to each other if they have the same position and buffer, or
301 if they both point nowhere.
303 @node Marker Insertion Types
304 @section Marker Insertion Types
306 @cindex insertion type of a marker
307 When you insert text directly at the place where a marker points,
308 there are two possible ways to relocate that marker: it can point before
309 the inserted text, or point after it. You can specify which one a given
310 marker should do by setting its @dfn{insertion type}. Note that use of
311 @code{insert-before-markers} ignores markers' insertion types, always
312 relocating a marker to point after the inserted text.
314 @tindex set-marker-insertion-type
315 @defun set-marker-insertion-type marker type
316 This function sets the insertion type of marker @var{marker} to
317 @var{type}. If @var{type} is @code{t}, @var{marker} will advances when
318 text is inserted at it. If @var{type} is @code{nil}, @var{marker} does
319 not advance when text is inserted there.
322 @tindex marker-insertion-type
323 @defun marker-insertion-type marker
324 This function reports the current insertion type of @var{marker}.
328 @section Moving Marker Positions
330 This section describes how to change the position of an existing
331 marker. When you do this, be sure you know whether the marker is used
332 outside of your program, and, if so, what effects will result from
333 moving it---otherwise, confusing things may happen in other parts of
336 @defun set-marker marker position &optional buffer
337 This function moves @var{marker} to @var{position}
338 in @var{buffer}. If @var{buffer} is not provided, it defaults to
341 If @var{position} is less than 1, @code{set-marker} moves @var{marker}
342 to the beginning of the buffer. If @var{position} is greater than the
343 size of the buffer, @code{set-marker} moves marker to the end of the
344 buffer. If @var{position} is @code{nil} or a marker that points
345 nowhere, then @var{marker} is set to point nowhere.
347 The value returned is @var{marker}.
351 (setq m (point-marker))
352 @result{} #<marker at 4714 in markers.texi>
356 @result{} #<marker at 55 in markers.texi>
359 (setq b (get-buffer "foo"))
360 @result{} #<buffer foo>
364 @result{} #<marker at 1 in foo>
369 @defun move-marker marker position &optional buffer
370 This is another name for @code{set-marker}.
378 One special marker in each buffer is designated @dfn{the mark}. It
379 records a position for the user for the sake of commands such as
380 @kbd{C-w} and @kbd{C-x @key{TAB}}. Lisp programs should set the mark
381 only to values that have a potential use to the user, and never for
382 their own internal purposes. For example, the @code{replace-regexp}
383 command sets the mark to the value of point before doing any
384 replacements, because this enables the user to move back there
385 conveniently after the replace is finished.
387 Many commands are designed so that when called interactively they
388 operate on the text between point and the mark. If you are writing such
389 a command, don't examine the mark directly; instead, use
390 @code{interactive} with the @samp{r} specification. This provides the
391 values of point and the mark as arguments to the command in an
392 interactive call, but permits other Lisp programs to specify arguments
393 explicitly. @xref{Interactive Codes}.
395 Each buffer has its own value of the mark that is independent of the
396 value of the mark in other buffers. When a buffer is created, the mark
397 exists but does not point anywhere. We consider this state as ``the
398 absence of a mark in that buffer.''
400 Once the mark ``exists'' in a buffer, it normally never ceases to
401 exist. However, it may become @dfn{inactive}, if Transient Mark mode is
402 enabled. The variable @code{mark-active}, which is always buffer-local
403 in all buffers, indicates whether the mark is active: non-@code{nil}
404 means yes. A command can request deactivation of the mark upon return
405 to the editor command loop by setting @code{deactivate-mark} to a
406 non-@code{nil} value (but this causes deactivation only if Transient
407 Mark mode is enabled).
409 The main motivation for using Transient Mark mode is that this mode
410 also enables highlighting of the region when the mark is active.
413 In addition to the mark, each buffer has a @dfn{mark ring} which is a
414 list of markers containing previous values of the mark. When editing
415 commands change the mark, they should normally save the old value of the
416 mark on the mark ring. The variable @code{mark-ring-max} specifies the
417 maximum number of entries in the mark ring; once the list becomes this
418 long, adding a new element deletes the last element.
420 @defun mark &optional force
421 @cindex current buffer mark
422 This function returns the current buffer's mark position as an integer.
424 If the mark is inactive, @code{mark} normally signals an error.
425 However, if @var{force} is non-@code{nil}, then @code{mark} returns the
426 mark position anyway---or @code{nil}, if the mark is not yet set for
431 This function returns the current buffer's mark. This is the very marker
432 that records the mark location inside Emacs, not a copy. Therefore,
433 changing this marker's position will directly affect the position of the mark.
434 Don't do it unless that is the effect you want.
438 (setq m (mark-marker))
439 @result{} #<marker at 3420 in markers.texi>
443 @result{} #<marker at 100 in markers.texi>
447 @result{} #<marker at 100 in markers.texi>
451 Like any marker, this marker can be set to point at any buffer you like.
452 We don't recommend that you make it point at any buffer other than the
453 one of which it is the mark. If you do, it will yield perfectly
454 consistent, but rather odd, results.
458 @deffn Command set-mark-command jump
459 If @var{jump} is @code{nil}, this command sets the mark to the value
460 of point and pushes the previous value of the mark on the mark ring. The
461 message @samp{Mark set} is also displayed in the echo area.
463 If @var{jump} is not @code{nil}, this command sets point to the value
464 of the mark, and sets the mark to the previous saved mark value, which
465 is popped off the mark ring.
467 This function is @emph{only} intended for interactive use.
471 @defun set-mark position
472 This function sets the mark to @var{position}, and activates the mark.
473 The old value of the mark is @emph{not} pushed onto the mark ring.
475 @strong{Please note:} Use this function only if you want the user to
476 see that the mark has moved, and you want the previous mark position to
477 be lost. Normally, when a new mark is set, the old one should go on the
478 @code{mark-ring}. For this reason, most applications should use
479 @code{push-mark} and @code{pop-mark}, not @code{set-mark}.
481 Novice Emacs Lisp programmers often try to use the mark for the wrong
482 purposes. The mark saves a location for the user's convenience. An
483 editing command should not alter the mark unless altering the mark is
484 part of the user-level functionality of the command. (And, in that
485 case, this effect should be documented.) To remember a location for
486 internal use in the Lisp program, store it in a Lisp variable. For
493 (delete-region beg (point))).
498 @c for interactive use only
500 @deffn Command exchange-point-and-mark
501 This function exchanges the positions of point and the mark.
502 It is intended for interactive use.
506 @defun push-mark &optional position nomsg activate
507 This function sets the current buffer's mark to @var{position}, and
508 pushes a copy of the previous mark onto @code{mark-ring}. If
509 @var{position} is @code{nil}, then the value of point is used.
510 @code{push-mark} returns @code{nil}.
512 The function @code{push-mark} normally @emph{does not} activate the
513 mark. To do that, specify @code{t} for the argument @var{activate}.
515 A @samp{Mark set} message is displayed unless @var{nomsg} is
520 This function pops off the top element of @code{mark-ring} and makes
521 that mark become the buffer's actual mark. This does not move point in
522 the buffer, and it does nothing if @code{mark-ring} is empty. It
523 deactivates the mark.
525 The return value is not meaningful.
528 @defopt transient-mark-mode
529 @cindex Transient Mark mode
530 This variable if non-@code{nil} enables Transient Mark mode, in which
531 every buffer-modifying primitive sets @code{deactivate-mark}. The
532 consequence of this is that commands that modify the buffer normally
533 make the mark inactive.
536 @defopt mark-even-if-inactive
537 If this is non-@code{nil}, Lisp programs and the Emacs user can use the
538 mark even when it is inactive. This option affects the behavior of
539 Transient Mark mode. When the option is non-@code{nil}, deactivation of
540 the mark turns off region highlighting, but commands that use the mark
541 behave as if the mark were still active.
544 @defvar deactivate-mark
545 If an editor command sets this variable non-@code{nil}, then the editor
546 command loop deactivates the mark after the command returns (if
547 Transient Mark mode is enabled). All the primitives that change the
548 buffer set @code{deactivate-mark}, to deactivate the mark when the
552 @defun deactivate-mark
553 This function deactivates the mark, if Transient Mark mode is enabled.
554 Otherwise it does nothing.
558 The mark is active when this variable is non-@code{nil}. This variable
559 is always buffer-local in each buffer.
562 @defvar activate-mark-hook
563 @defvarx deactivate-mark-hook
564 These normal hooks are run, respectively, when the mark becomes active
565 and when it becomes inactive. The hook @code{activate-mark-hook} is
566 also run at the end of a command if the mark is active and it is
567 possible that the region may have changed.
571 The value of this buffer-local variable is the list of saved former
572 marks of the current buffer, most recent first.
577 @result{} (#<marker at 11050 in markers.texi>
578 #<marker at 10832 in markers.texi>
584 @defopt mark-ring-max
585 The value of this variable is the maximum size of @code{mark-ring}. If
586 more marks than this are pushed onto the @code{mark-ring},
587 @code{push-mark} discards an old mark when it adds a new one.
594 The text between point and the mark is known as @dfn{the region}.
595 Various functions operate on text delimited by point and the mark, but
596 only those functions specifically related to the region itself are
599 @defun region-beginning
600 This function returns the position of the beginning of the region (as
601 an integer). This is the position of either point or the mark,
602 whichever is smaller.
604 If the mark does not point anywhere, an error is signaled.
608 This function returns the position of the end of the region (as an
609 integer). This is the position of either point or the mark, whichever is
612 If the mark does not point anywhere, an error is signaled.
615 Few programs need to use the @code{region-beginning} and
616 @code{region-end} functions. A command designed to operate on a region
617 should normally use @code{interactive} with the @samp{r} specification
618 to find the beginning and end of the region. This lets other Lisp
619 programs specify the bounds explicitly as arguments. (@xref{Interactive