2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
5 @c See the file elisp.texi for copying conditions.
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. A
31 marker can be used to represent a position in functions that
32 require one, just as an integer could be used. In that case, the
33 marker's buffer is normally ignored. Of course, a marker used in this
34 way usually points to a position in the buffer that the function
35 operates on, but that is entirely the programmer's responsibility.
36 @xref{Positions}, for a complete description of positions.
38 A marker has three attributes: the marker position, the marker
39 buffer, and the insertion type. The marker position is an integer
40 that is equivalent (at a given time) to the marker as a position in
41 that buffer. But the marker's position value can change during
42 the life of the marker, and often does. Insertion and deletion of
43 text in the buffer relocate the marker. The idea is that a marker
44 positioned between two characters remains between those two characters
45 despite insertion and deletion elsewhere in the buffer. Relocation
46 changes the integer equivalent of the marker.
48 @cindex marker relocation
49 Deleting text around a marker's position leaves the marker between the
50 characters immediately before and after the deleted text. Inserting
51 text at the position of a marker normally leaves the marker either in
52 front of or after the new text, depending on the marker's @dfn{insertion
53 type} (@pxref{Marker Insertion Types})---unless the insertion is done
54 with @code{insert-before-markers} (@pxref{Insertion}).
56 @cindex marker garbage collection
57 Insertion and deletion in a buffer must check all the markers and
58 relocate them if necessary. This slows processing in a buffer with a
59 large number of markers. For this reason, it is a good idea to make a
60 marker point nowhere if you are sure you don't need it any more.
61 Markers that can no longer be accessed are eventually removed
62 (@pxref{Garbage Collection}).
64 @cindex markers as numbers
65 Because it is common to perform arithmetic operations on a marker
66 position, most of these operations (including @code{+} and
67 @code{-}) accept markers as arguments. In such cases, the marker
68 stands for its current position.
70 Here are examples of creating markers, setting markers, and moving point
75 ;; @r{Make a new marker that initially does not point anywhere:}
76 (setq m1 (make-marker))
77 @result{} #<marker in no buffer>
81 ;; @r{Set @code{m1} to point between the 99th and 100th characters}
82 ;; @r{in the current buffer:}
84 @result{} #<marker at 100 in markers.texi>
88 ;; @r{Now insert one character at the beginning of the buffer:}
89 (goto-char (point-min))
96 ;; @r{@code{m1} is updated appropriately.}
98 @result{} #<marker at 101 in markers.texi>
102 ;; @r{Two markers that point to the same position}
103 ;; @r{are not @code{eq}, but they are @code{equal}.}
104 (setq m2 (copy-marker m1))
105 @result{} #<marker at 101 in markers.texi>
113 ;; @r{When you are finished using a marker, make it point nowhere.}
115 @result{} #<marker in no buffer>
119 @node Predicates on Markers
120 @section Predicates on Markers
122 You can test an object to see whether it is a marker, or whether it is
123 either an integer or a marker. The latter test is useful in connection
124 with the arithmetic functions that work with both markers and integers.
126 @defun markerp object
127 This function returns @code{t} if @var{object} is a marker, @code{nil}
128 otherwise. Note that integers are not markers, even though many
129 functions will accept either a marker or an integer.
132 @defun integer-or-marker-p object
133 This function returns @code{t} if @var{object} is an integer or a marker,
134 @code{nil} otherwise.
137 @defun number-or-marker-p object
138 This function returns @code{t} if @var{object} is a number (either
139 integer or floating point) or a marker, @code{nil} otherwise.
142 @node Creating Markers
143 @section Functions that Create Markers
145 When you create a new marker, you can make it point nowhere, or point
146 to the present position of point, or to the beginning or end of the
147 accessible portion of the buffer, or to the same place as another given
150 The next four functions all return markers with insertion type
151 @code{nil}. @xref{Marker Insertion Types}.
154 This function returns a newly created marker that does not point
160 @result{} #<marker in no buffer>
166 This function returns a new marker that points to the present position
167 of point in the current buffer. @xref{Point}. For an example, see
168 @code{copy-marker}, below.
171 @defun point-min-marker
172 This function returns a new marker that points to the beginning of the
173 accessible portion of the buffer. This will be the beginning of the
174 buffer unless narrowing is in effect. @xref{Narrowing}.
177 @defun point-max-marker
178 This function returns a new marker that points to the end of the
179 accessible portion of the buffer. This will be the end of the buffer
180 unless narrowing is in effect. @xref{Narrowing}.
182 Here are examples of this function and @code{point-min-marker}, shown in
183 a buffer containing a version of the source file for the text of this
189 @result{} #<marker at 1 in markers.texi>
191 @result{} #<marker at 24080 in markers.texi>
195 (narrow-to-region 100 200)
200 @result{} #<marker at 100 in markers.texi>
204 @result{} #<marker at 200 in markers.texi>
209 @defun copy-marker &optional marker-or-integer insertion-type
210 If passed a marker as its argument, @code{copy-marker} returns a
211 new marker that points to the same place and the same buffer as does
212 @var{marker-or-integer}. If passed an integer as its argument,
213 @code{copy-marker} returns a new marker that points to position
214 @var{marker-or-integer} in the current buffer.
216 The new marker's insertion type is specified by the argument
217 @var{insertion-type}. @xref{Marker Insertion Types}.
219 @c This behavior used to be documented until 2013/08.
221 If passed an integer argument less than 1, @code{copy-marker} returns a
222 new marker that points to the beginning of the current buffer. If
223 passed an integer argument greater than the length of the buffer,
224 @code{copy-marker} returns a new marker that points to the end of the
231 @result{} #<marker at 1 in markers.texi>
236 @result{} #<marker at 24080 in markers.texi>
240 An error is signaled if @var{marker} is neither a marker nor an
244 Two distinct markers are considered @code{equal} (even though not
245 @code{eq}) to each other if they have the same position and buffer, or
246 if they both point nowhere.
250 (setq p (point-marker))
251 @result{} #<marker at 2139 in markers.texi>
255 (setq q (copy-marker p))
256 @result{} #<marker at 2139 in markers.texi>
270 @node Information from Markers
271 @section Information from Markers
273 This section describes the functions for accessing the components of a
276 @defun marker-position marker
277 This function returns the position that @var{marker} points to, or
278 @code{nil} if it points nowhere.
281 @defun marker-buffer marker
282 This function returns the buffer that @var{marker} points into, or
283 @code{nil} if it points nowhere.
285 @c FIXME: The `buffer' argument of `set-marker' already defaults to
286 @c the current buffer, why use `(current-buffer)' explicitly here?
289 (setq m (make-marker))
290 @result{} #<marker in no buffer>
302 (set-marker m 3770 (current-buffer))
303 @result{} #<marker at 3770 in markers.texi>
307 @result{} #<buffer markers.texi>
316 @node Marker Insertion Types
317 @section Marker Insertion Types
319 @cindex insertion type of a marker
320 When you insert text directly at the place where a marker points,
321 there are two possible ways to relocate that marker: it can point before
322 the inserted text, or point after it. You can specify which one a given
323 marker should do by setting its @dfn{insertion type}. Note that use of
324 @code{insert-before-markers} ignores markers' insertion types, always
325 relocating a marker to point after the inserted text.
327 @defun set-marker-insertion-type marker type
328 This function sets the insertion type of marker @var{marker} to
329 @var{type}. If @var{type} is @code{t}, @var{marker} will advance when
330 text is inserted at its position. If @var{type} is @code{nil},
331 @var{marker} does not advance when text is inserted there.
334 @defun marker-insertion-type marker
335 This function reports the current insertion type of @var{marker}.
338 Most functions that create markers, without an argument allowing to
339 specify the insertion type, create them with insertion type
340 @code{nil}. Also, the mark has, by default, insertion type
344 @section Moving Marker Positions
346 This section describes how to change the position of an existing
347 marker. When you do this, be sure you know how the marker is used
348 outside of your program. For example, moving a marker to an unrelated
349 new position can cause undo to later adjust the marker incorrectly.
350 Often when you wish to relocate a marker to an unrelated position, it
351 is preferable to make a new marker and set the prior one to point
354 @defun set-marker marker position &optional buffer
355 This function moves @var{marker} to @var{position}
356 in @var{buffer}. If @var{buffer} is not provided, it defaults to
359 @c This behavior used to be documented until 2013/08.
361 If @var{position} is less than 1, @code{set-marker} moves @var{marker}
362 to the beginning of the buffer. If @var{position} is greater than the
363 size of the buffer (@pxref{Point}), @code{set-marker} moves marker to
364 the end of the buffer.
366 If @var{position} is @code{nil} or a marker that points nowhere, then
367 @var{marker} is set to point nowhere.
369 The value returned is @var{marker}.
373 (setq m (point-marker))
374 @result{} #<marker at 4714 in markers.texi>
378 @result{} #<marker at 55 in markers.texi>
381 (setq b (get-buffer "foo"))
382 @result{} #<buffer foo>
386 @result{} #<marker at 1 in foo>
391 @defun move-marker marker position &optional buffer
392 This is another name for @code{set-marker}.
400 Each buffer has a special marker, which is designated @dfn{the
401 mark}. When a buffer is newly created, this marker exists but does
402 not point anywhere; this means that the mark ``doesn't exist'' in that
403 buffer yet. Subsequent commands can set the mark.
405 The mark specifies a position to bound a range of text for many
406 commands, such as @code{kill-region} and @code{indent-rigidly}. These
407 commands typically act on the text between point and the mark, which
408 is called the @dfn{region}. If you are writing a command that
409 operates on the region, don't examine the mark directly; instead, use
410 @code{interactive} with the @samp{r} specification. This provides the
411 values of point and the mark as arguments to the command in an
412 interactive call, but permits other Lisp programs to specify arguments
413 explicitly. @xref{Interactive Codes}.
415 Some commands set the mark as a side-effect. Commands should do
416 this only if it has a potential use to the user, and never for their
417 own internal purposes. For example, the @code{replace-regexp} command
418 sets the mark to the value of point before doing any replacements,
419 because this enables the user to move back there conveniently after
420 the replace is finished.
422 Once the mark ``exists'' in a buffer, it normally never ceases to
423 exist. However, it may become @dfn{inactive}, if Transient Mark mode
424 is enabled. The buffer-local variable @code{mark-active}, if
425 non-@code{nil}, means that the mark is active. A command can call the
426 function @code{deactivate-mark} to deactivate the mark directly, or it
427 can request deactivation of the mark upon return to the editor command
428 loop by setting the variable @code{deactivate-mark} to a
429 non-@code{nil} value.
431 If Transient Mark mode is enabled, certain editing commands that
432 normally apply to text near point, apply instead to the region when
433 the mark is active. This is the main motivation for using Transient
434 Mark mode. (Another is that this enables highlighting of the region
435 when the mark is active. @xref{Display}.)
438 In addition to the mark, each buffer has a @dfn{mark ring} which is a
439 list of markers containing previous values of the mark. When editing
440 commands change the mark, they should normally save the old value of the
441 mark on the mark ring. The variable @code{mark-ring-max} specifies the
442 maximum number of entries in the mark ring; once the list becomes this
443 long, adding a new element deletes the last element.
445 There is also a separate global mark ring, but that is used only in a
446 few particular user-level commands, and is not relevant to Lisp
447 programming. So we do not describe it here.
449 @defun mark &optional force
450 @cindex current buffer mark
451 This function returns the current buffer's mark position as an integer,
452 or @code{nil} if no mark has ever been set in this buffer.
454 If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is
455 @code{nil}, @code{mark} signals an error if the mark is inactive.
456 However, if @var{force} is non-@code{nil}, then @code{mark} disregards
457 inactivity of the mark, and returns the mark position (or @code{nil})
462 This function returns the marker that represents the current buffer's
463 mark. It is not a copy, it is the marker used internally. Therefore,
464 changing this marker's position will directly affect the buffer's
465 mark. Don't do that unless that is the effect you want.
469 (setq m (mark-marker))
470 @result{} #<marker at 3420 in markers.texi>
474 @result{} #<marker at 100 in markers.texi>
478 @result{} #<marker at 100 in markers.texi>
482 Like any marker, this marker can be set to point at any buffer you
483 like. If you make it point at any buffer other than the one of which
484 it is the mark, it will yield perfectly consistent, but rather odd,
485 results. We recommend that you not do it!
488 @defun set-mark position
489 This function sets the mark to @var{position}, and activates the mark.
490 The old value of the mark is @emph{not} pushed onto the mark ring.
492 @strong{Please note:} Use this function only if you want the user to
493 see that the mark has moved, and you want the previous mark position to
494 be lost. Normally, when a new mark is set, the old one should go on the
495 @code{mark-ring}. For this reason, most applications should use
496 @code{push-mark} and @code{pop-mark}, not @code{set-mark}.
498 Novice Emacs Lisp programmers often try to use the mark for the wrong
499 purposes. The mark saves a location for the user's convenience. An
500 editing command should not alter the mark unless altering the mark is
501 part of the user-level functionality of the command. (And, in that
502 case, this effect should be documented.) To remember a location for
503 internal use in the Lisp program, store it in a Lisp variable. For
510 (delete-region beg (point))).
515 @defun push-mark &optional position nomsg activate
516 This function sets the current buffer's mark to @var{position}, and
517 pushes a copy of the previous mark onto @code{mark-ring}. If
518 @var{position} is @code{nil}, then the value of point is used.
519 @c Doesn't seem relevant.
520 @c @code{push-mark} returns @code{nil}.
522 The function @code{push-mark} normally @emph{does not} activate the
523 mark. To do that, specify @code{t} for the argument @var{activate}.
525 A @samp{Mark set} message is displayed unless @var{nomsg} is
530 This function pops off the top element of @code{mark-ring} and makes
531 that mark become the buffer's actual mark. This does not move point in
532 the buffer, and it does nothing if @code{mark-ring} is empty. It
533 deactivates the mark.
535 @c Seems even less relevant.
536 @c The return value is not meaningful.
539 @defopt transient-mark-mode
540 This variable, if non-@code{nil}, enables Transient Mark mode. In
541 Transient Mark mode, every buffer-modifying primitive sets
542 @code{deactivate-mark}. As a consequence, most commands that modify
543 the buffer also deactivate the mark.
545 When Transient Mark mode is enabled and the mark is active, many
546 commands that normally apply to the text near point instead apply to
547 the region. Such commands should use the function @code{use-region-p}
548 to test whether they should operate on the region. @xref{The Region}.
550 Lisp programs can set @code{transient-mark-mode} to non-@code{nil},
551 non-@code{t} values to enable Transient Mark mode temporarily. If the
552 value is @code{lambda}, Transient Mark mode is automatically turned
553 off after any action, such as buffer modification, that would normally
554 deactivate the mark. If the value is @w{@code{(only . @var{oldval})}},
555 then @code{transient-mark-mode} is set to the value @var{oldval} after
556 any subsequent command that moves point and is not shift-translated
557 (@pxref{Key Sequence Input, shift-translation}), or after any other
558 action that would normally deactivate the mark.
561 @defopt mark-even-if-inactive
562 If this is non-@code{nil}, Lisp programs and the Emacs user can use the
563 mark even when it is inactive. This option affects the behavior of
564 Transient Mark mode. When the option is non-@code{nil}, deactivation of
565 the mark turns off region highlighting, but commands that use the mark
566 behave as if the mark were still active.
569 @defvar deactivate-mark
570 If an editor command sets this variable non-@code{nil}, then the editor
571 command loop deactivates the mark after the command returns (if
572 Transient Mark mode is enabled). All the primitives that change the
573 buffer set @code{deactivate-mark}, to deactivate the mark when the
576 To write Lisp code that modifies the buffer without causing
577 deactivation of the mark at the end of the command, bind
578 @code{deactivate-mark} to @code{nil} around the code that does the
579 modification. For example:
582 (let (deactivate-mark)
587 @defun deactivate-mark &optional force
588 If Transient Mark mode is enabled or @var{force} is non-@code{nil},
589 this function deactivates the mark and runs the normal hook
590 @code{deactivate-mark-hook}. Otherwise, it does nothing.
594 The mark is active when this variable is non-@code{nil}. This
595 variable is always buffer-local in each buffer. Do @emph{not} use the
596 value of this variable to decide whether a command that normally
597 operates on text near point should operate on the region instead. Use
598 the function @code{use-region-p} for that (@pxref{The Region}).
601 @defvar activate-mark-hook
602 @defvarx deactivate-mark-hook
603 These normal hooks are run, respectively, when the mark becomes active
604 and when it becomes inactive. The hook @code{activate-mark-hook} is
605 also run at the end of the command loop if the mark is active and it
606 is possible that the region may have changed.
608 This piece of command_loop_1, run unless deactivating the mark:
609 if (current_buffer != prev_buffer || MODIFF != prev_modiff)
611 Lisp_Object hook = intern ("activate-mark-hook");
612 Frun_hooks (1, &hook);
617 @defun handle-shift-selection
618 This function implements the ``shift-selection'' behavior of
619 point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs
620 Manual}. It is called automatically by the Emacs command loop
621 whenever a command with a @samp{^} character in its @code{interactive}
622 spec is invoked, before the command itself is executed
623 (@pxref{Interactive Codes, ^}).
625 If @code{shift-select-mode} is non-@code{nil} and the current command
626 was invoked via shift translation (@pxref{Key Sequence Input,
627 shift-translation}), this function sets the mark and temporarily
628 activates the region, unless the region was already temporarily
629 activated in this way. Otherwise, if the region has been activated
630 temporarily, it deactivates the mark and restores the variable
631 @code{transient-mark-mode} to its earlier value.
635 The value of this buffer-local variable is the list of saved former
636 marks of the current buffer, most recent first.
641 @result{} (#<marker at 11050 in markers.texi>
642 #<marker at 10832 in markers.texi>
648 @defopt mark-ring-max
649 The value of this variable is the maximum size of @code{mark-ring}. If
650 more marks than this are pushed onto the @code{mark-ring},
651 @code{push-mark} discards an old mark when it adds a new one.
654 @c There is also global-mark-ring-max, but this chapter explicitly
655 @c does not talk about the global mark.
659 @c The index entry must be just ``region'' to make it the first hit
660 @c when the user types ``i region RET'', because otherwise the Info
661 @c reader will present substring matches in alphabetical order,
662 @c putting this one near the end, with something utterly unrelated as
666 The text between point and the mark is known as @dfn{the region}.
667 Various functions operate on text delimited by point and the mark, but
668 only those functions specifically related to the region itself are
671 The next two functions signal an error if the mark does not point
672 anywhere. If Transient Mark mode is enabled and
673 @code{mark-even-if-inactive} is @code{nil}, they also signal an error
674 if the mark is inactive.
676 @defun region-beginning
677 This function returns the position of the beginning of the region (as
678 an integer). This is the position of either point or the mark,
679 whichever is smaller.
683 This function returns the position of the end of the region (as an
684 integer). This is the position of either point or the mark, whichever is
688 @c FIXME: Mention it in tips.texi?
689 Instead of using @code{region-beginning} and @code{region-end}, a
690 command designed to operate on a region should normally use
691 @code{interactive} with the @samp{r} specification to find the
692 beginning and end of the region. This lets other Lisp programs
693 specify the bounds explicitly as arguments. @xref{Interactive Codes}.
696 This function returns @code{t} if Transient Mark mode is enabled, the
697 mark is active, and there is a valid region in the buffer. This
698 function is intended to be used by commands that operate on the
699 region, instead of on text near point, when the mark is active.
702 @vindex use-empty-active-region
703 A region is valid if it has a non-zero size, or if the user option
704 @code{use-empty-active-region} is non-@code{nil} (by default, it is
705 @code{nil}). The function @code{region-active-p} is similar to
706 @code{use-region-p}, but considers all regions as valid. In most
707 cases, you should not use @code{region-active-p}, since if the region
708 is empty it is often more appropriate to operate on point.