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 in front of
48 the new text---unless it is inserted with @code{insert-before-markers}
51 @cindex marker garbage collection
52 Insertion and deletion in a buffer must check all the markers and
53 relocate them if necessary. This slows processing in a buffer with a
54 large number of markers. For this reason, it is a good idea to make a
55 marker point nowhere if you are sure you don't need it any more.
56 Unreferenced markers are garbage collected eventually, but until then
57 will continue to use time if they do point somewhere.
59 @cindex markers as numbers
60 Because it is common to perform arithmetic operations on a marker
61 position, most of the arithmetic operations (including @code{+} and
62 @code{-}) accept markers as arguments. In such cases, the marker
63 stands for its current position.
65 Here are examples of creating markers, setting markers, and moving point
70 ;; @r{Make a new marker that initially does not point anywhere:}
71 (setq m1 (make-marker))
72 @result{} #<marker in no buffer>
76 ;; @r{Set @code{m1} to point between the 99th and 100th characters}
77 ;; @r{in the current buffer:}
79 @result{} #<marker at 100 in markers.texi>
83 ;; @r{Now insert one character at the beginning of the buffer:}
84 (goto-char (point-min))
91 ;; @r{@code{m1} is updated appropriately.}
93 @result{} #<marker at 101 in markers.texi>
97 ;; @r{Two markers that point to the same position}
98 ;; @r{are not @code{eq}, but they are @code{equal}.}
99 (setq m2 (copy-marker m1))
100 @result{} #<marker at 101 in markers.texi>
108 ;; @r{When you are finished using a marker, make it point nowhere.}
110 @result{} #<marker in no buffer>
114 @node Predicates on Markers
115 @section Predicates on Markers
117 You can test an object to see whether it is a marker, or whether it is
118 either an integer or a marker. The latter test is useful in connection
119 with the arithmetic functions that work with both markers and integers.
121 @defun markerp object
122 This function returns @code{t} if @var{object} is a marker, @code{nil}
123 otherwise. Note that integers are not markers, even though many
124 functions will accept either a marker or an integer.
127 @defun integer-or-marker-p object
128 This function returns @code{t} if @var{object} is an integer or a marker,
129 @code{nil} otherwise.
132 @defun number-or-marker-p object
133 This function returns @code{t} if @var{object} is a number (either kind)
134 or a marker, @code{nil} otherwise.
137 @node Creating Markers
138 @section Functions That Create Markers
140 When you create a new marker, you can make it point nowhere, or point
141 to the present position of point, or to the beginning or end of the
142 accessible portion of the buffer, or to the same place as another given
146 This functions returns a newly created marker that does not point
152 @result{} #<marker in no buffer>
158 This function returns a new marker that points to the present position
159 of point in the current buffer. @xref{Point}. For an example, see
160 @code{copy-marker}, below.
163 @defun point-min-marker
164 This function returns a new marker that points to the beginning of the
165 accessible portion of the buffer. This will be the beginning of the
166 buffer unless narrowing is in effect. @xref{Narrowing}.
169 @defun point-max-marker
170 @cindex end of buffer marker
171 This function returns a new marker that points to the end of the
172 accessible portion of the buffer. This will be the end of the buffer
173 unless narrowing is in effect. @xref{Narrowing}.
175 Here are examples of this function and @code{point-min-marker}, shown in
176 a buffer containing a version of the source file for the text of this
182 @result{} #<marker at 1 in markers.texi>
184 @result{} #<marker at 15573 in markers.texi>
188 (narrow-to-region 100 200)
193 @result{} #<marker at 100 in markers.texi>
197 @result{} #<marker at 200 in markers.texi>
202 @defun copy-marker marker-or-integer insertion-type
203 If passed a marker as its argument, @code{copy-marker} returns a
204 new marker that points to the same place and the same buffer as does
205 @var{marker-or-integer}. If passed an integer as its argument,
206 @code{copy-marker} returns a new marker that points to position
207 @var{marker-or-integer} in the current buffer.
209 The new marker's insertion type is specified by the argument
210 @var{insertion-type}. @xref{Marker Insertion Types}.
212 If passed an integer argument less than 1, @code{copy-marker} returns a
213 new marker that points to the beginning of the current buffer. If
214 passed an integer argument greater than the length of the buffer,
215 @code{copy-marker} returns a new marker that points to the end of the
218 An error is signaled if @var{marker} is neither a marker nor an
223 (setq p (point-marker))
224 @result{} #<marker at 2139 in markers.texi>
228 (setq q (copy-marker p))
229 @result{} #<marker at 2139 in markers.texi>
244 @result{} #<marker at 1 in markers.texi>
249 @result{} #<marker at 7572 in markers.texi>
254 @node Information from Markers
255 @section Information from Markers
257 This section describes the functions for accessing the components of a
260 @defun marker-position marker
261 This function returns the position that @var{marker} points to, or
262 @code{nil} if it points nowhere.
265 @defun marker-buffer marker
266 This function returns the buffer that @var{marker} points into, or
267 @code{nil} if it points nowhere.
271 (setq m (make-marker))
272 @result{} #<marker in no buffer>
284 (set-marker m 3770 (current-buffer))
285 @result{} #<marker at 3770 in markers.texi>
289 @result{} #<buffer markers.texi>
298 Two distinct markers are considered @code{equal} (even though not
299 @code{eq}) to each other if they have the same position and buffer, or
300 if they both point nowhere.
302 @node Marker Insertion Types
303 @section Marker Insertion Types
305 @cindex insertion type of a marker
306 When you insert text directly at the place where a marker points,
307 there are two possible ways to relocate that marker: it can point before
308 the inserted text, or point after it. You can specify which one a given
309 marker should do by setting its @dfn{insertion type}.
311 @tindex set-marker-insertion-type
312 @defun set-marker-insertion-type marker type
313 This function sets the insertion type of marker @var{marker} to
314 @var{type}. If @var{type} is @code{t}, @var{marker} will advances when
315 text is inserted at it. If @var{type} is @code{nil}, @var{marker} does
316 not advance when text is inserted there.
319 @tindex marker-insertion-type
320 @defun marker-insertion-type marker
321 This function reports the current insertion type of @var{marker}.
325 @section Moving Marker Positions
327 This section describes how to change the position of an existing
328 marker. When you do this, be sure you know whether the marker is used
329 outside of your program, and, if so, what effects will result from
330 moving it---otherwise, confusing things may happen in other parts of
333 @defun set-marker marker position &optional buffer
334 This function moves @var{marker} to @var{position}
335 in @var{buffer}. If @var{buffer} is not provided, it defaults to
338 If @var{position} is less than 1, @code{set-marker} moves @var{marker}
339 to the beginning of the buffer. If @var{position} is greater than the
340 size of the buffer, @code{set-marker} moves marker to the end of the
341 buffer. If @var{position} is @code{nil} or a marker that points
342 nowhere, then @var{marker} is set to point nowhere.
344 The value returned is @var{marker}.
348 (setq m (point-marker))
349 @result{} #<marker at 4714 in markers.texi>
353 @result{} #<marker at 55 in markers.texi>
356 (setq b (get-buffer "foo"))
357 @result{} #<buffer foo>
361 @result{} #<marker at 1 in foo>
366 @defun move-marker marker position &optional buffer
367 This is another name for @code{set-marker}.
375 One special marker in each buffer is designated @dfn{the mark}. It
376 records a position for the user for the sake of commands such as
377 @kbd{C-w} and @kbd{C-x @key{TAB}}. Lisp programs should set the mark
378 only to values that have a potential use to the user, and never for
379 their own internal purposes. For example, the @code{replace-regexp}
380 command sets the mark to the value of point before doing any
381 replacements, because this enables the user to move back there
382 conveniently after the replace is finished.
384 Many commands are designed so that when called interactively they
385 operate on the text between point and the mark. If you are writing such
386 a command, don't examine the mark directly; instead, use
387 @code{interactive} with the @samp{r} specification. This provides the
388 values of point and the mark as arguments to the command in an
389 interactive call, but permits other Lisp programs to specify arguments
390 explicitly. @xref{Interactive Codes}.
392 Each buffer has its own value of the mark that is independent of the
393 value of the mark in other buffers. When a buffer is created, the mark
394 exists but does not point anywhere. We consider this state as ``the
395 absence of a mark in that buffer.''
397 Once the mark ``exists'' in a buffer, it normally never ceases to
398 exist. However, it may become @dfn{inactive}, if Transient Mark mode is
399 enabled. The variable @code{mark-active}, which is always local in all
400 buffers, indicates whether the mark is active: non-@code{nil} means yes.
401 A command can request deactivation of the mark upon return to the editor
402 command loop by setting @code{deactivate-mark} to a non-@code{nil} value
403 (but this causes deactivation only if Transient Mark mode is enabled).
405 The main motivation for using Transient Mark mode is that this mode
406 also enables highlighting of the region when the mark is active.
409 In addition to the mark, each buffer has a @dfn{mark ring} which is a
410 list of markers containing previous values of the mark. When editing
411 commands change the mark, they should normally save the old value of the
412 mark on the mark ring. The variable @code{mark-ring-max} specifies the
413 maximum number of entries in the mark ring; once the list becomes this
414 long, adding a new element deletes the last element.
416 @defun mark &optional force
417 @cindex current buffer mark
418 This function returns the current buffer's mark position as an integer.
420 If the mark is inactive, @code{mark} normally signals an error.
421 However, if @var{force} is non-@code{nil}, then @code{mark} returns the
422 mark position anyway---or @code{nil}, if the mark is not yet set for
427 This function returns the current buffer's mark. This is the very marker
428 that records the mark location inside Emacs, not a copy. Therefore,
429 changing this marker's position will directly affect the position of the mark.
430 Don't do it unless that is the effect you want.
434 (setq m (mark-marker))
435 @result{} #<marker at 3420 in markers.texi>
439 @result{} #<marker at 100 in markers.texi>
443 @result{} #<marker at 100 in markers.texi>
447 Like any marker, this marker can be set to point at any buffer you like.
448 We don't recommend that you make it point at any buffer other than the
449 one of which it is the mark. If you do, it will yield perfectly
450 consistent, but rather odd, results.
454 @deffn Command set-mark-command jump
455 If @var{jump} is @code{nil}, this command sets the mark to the value
456 of point and pushes the previous value of the mark on the mark ring. The
457 message @samp{Mark set} is also displayed in the echo area.
459 If @var{jump} is not @code{nil}, this command sets point to the value
460 of the mark, and sets the mark to the previous saved mark value, which
461 is popped off the mark ring.
463 This function is @emph{only} intended for interactive use.
467 @defun set-mark position
468 This function sets the mark to @var{position}, and activates the mark.
469 The old value of the mark is @emph{not} pushed onto the mark ring.
471 @strong{Please note:} Use this function only if you want the user to
472 see that the mark has moved, and you want the previous mark position to
473 be lost. Normally, when a new mark is set, the old one should go on the
474 @code{mark-ring}. For this reason, most applications should use
475 @code{push-mark} and @code{pop-mark}, not @code{set-mark}.
477 Novice Emacs Lisp programmers often try to use the mark for the wrong
478 purposes. The mark saves a location for the user's convenience. An
479 editing command should not alter the mark unless altering the mark is
480 part of the user-level functionality of the command. (And, in that
481 case, this effect should be documented.) To remember a location for
482 internal use in the Lisp program, store it in a Lisp variable. For
489 (delete-region beg (point))).
494 @c for interactive use only
496 @deffn Command exchange-point-and-mark
497 This function exchanges the positions of point and the mark.
498 It is intended for interactive use.
502 @defun push-mark &optional position nomsg activate
503 This function sets the current buffer's mark to @var{position}, and
504 pushes a copy of the previous mark onto @code{mark-ring}. If
505 @var{position} is @code{nil}, then the value of point is used.
506 @code{push-mark} returns @code{nil}.
508 The function @code{push-mark} normally @emph{does not} activate the
509 mark. To do that, specify @code{t} for the argument @var{activate}.
511 A @samp{Mark set} message is displayed unless @var{nomsg} is
516 This function pops off the top element of @code{mark-ring} and makes
517 that mark become the buffer's actual mark. This does not move point in
518 the buffer, and it does nothing if @code{mark-ring} is empty. It
519 deactivates the mark.
521 The return value is not meaningful.
524 @defopt transient-mark-mode
525 @cindex Transient Mark mode
526 This variable if non-@code{nil} enables Transient Mark mode, in which
527 every buffer-modifying primitive sets @code{deactivate-mark}. The
528 consequence of this is that commands that modify the buffer normally
529 make the mark inactive.
532 @defvar deactivate-mark
533 If an editor command sets this variable non-@code{nil}, then the editor
534 command loop deactivates the mark after the command returns, but only if
535 Transient Mark mode is enabled.
538 @defun deactivate-mark
539 This function deactivates the mark, but only if Transient Mark mode
544 The mark is active when this variable is non-@code{nil}. This variable
545 is always local in each buffer.
548 @defvar activate-mark-hook
549 @defvarx deactivate-mark-hook
550 These normal hooks are run, respectively, when the mark becomes active
551 and when it becomes inactive. The hook @code{activate-mark-hook} is
552 also run at the end of a command if the mark is active and it is
553 possible that the region may have changed.
557 The value of this buffer-local variable is the list of saved former
558 marks of the current buffer, most recent first.
563 @result{} (#<marker at 11050 in markers.texi>
564 #<marker at 10832 in markers.texi>
570 @defopt mark-ring-max
571 The value of this variable is the maximum size of @code{mark-ring}. If
572 more marks than this are pushed onto the @code{mark-ring},
573 @code{push-mark} discards an old mark when it adds a new one.
580 The text between point and the mark is known as @dfn{the region}.
581 Various functions operate on text delimited by point and the mark, but
582 only those functions specifically related to the region itself are
585 @defun region-beginning
586 This function returns the position of the beginning of the region (as
587 an integer). This is the position of either point or the mark,
588 whichever is smaller.
590 If the mark does not point anywhere, an error is signaled.
594 This function returns the position of the end of the region (as an
595 integer). This is the position of either point or the mark, whichever is
598 If the mark does not point anywhere, an error is signaled.
601 Few programs need to use the @code{region-beginning} and
602 @code{region-end} functions. A command designed to operate on a region
603 should normally use @code{interactive} with the @samp{r} specification
604 to find the beginning and end of the region. This lets other Lisp
605 programs specify the bounds explicitly as arguments. (@xref{Interactive