2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2013 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 If passed an integer argument less than 1, @code{copy-marker} returns a
220 new marker that points to the beginning of the current buffer. If
221 passed an integer argument greater than the length of the buffer,
222 @code{copy-marker} returns a new marker that points to the end of the
228 @result{} #<marker at 1 in markers.texi>
233 @result{} #<marker at 24080 in markers.texi>
237 An error is signaled if @var{marker} is neither a marker nor an
241 Two distinct markers are considered @code{equal} (even though not
242 @code{eq}) to each other if they have the same position and buffer, or
243 if they both point nowhere.
247 (setq p (point-marker))
248 @result{} #<marker at 2139 in markers.texi>
252 (setq q (copy-marker p))
253 @result{} #<marker at 2139 in markers.texi>
267 @node Information from Markers
268 @section Information from Markers
270 This section describes the functions for accessing the components of a
273 @defun marker-position marker
274 This function returns the position that @var{marker} points to, or
275 @code{nil} if it points nowhere.
278 @defun marker-buffer marker
279 This function returns the buffer that @var{marker} points into, or
280 @code{nil} if it points nowhere.
282 @c FIXME: The `buffer' argument of `set-marker' already defaults to
283 @c the current buffer, why use `(current-buffer)' explicitly here?
286 (setq m (make-marker))
287 @result{} #<marker in no buffer>
299 (set-marker m 3770 (current-buffer))
300 @result{} #<marker at 3770 in markers.texi>
304 @result{} #<buffer markers.texi>
313 @node Marker Insertion Types
314 @section Marker Insertion Types
316 @cindex insertion type of a marker
317 When you insert text directly at the place where a marker points,
318 there are two possible ways to relocate that marker: it can point before
319 the inserted text, or point after it. You can specify which one a given
320 marker should do by setting its @dfn{insertion type}. Note that use of
321 @code{insert-before-markers} ignores markers' insertion types, always
322 relocating a marker to point after the inserted text.
324 @defun set-marker-insertion-type marker type
325 This function sets the insertion type of marker @var{marker} to
326 @var{type}. If @var{type} is @code{t}, @var{marker} will advance when
327 text is inserted at its position. If @var{type} is @code{nil},
328 @var{marker} does not advance when text is inserted there.
331 @defun marker-insertion-type marker
332 This function reports the current insertion type of @var{marker}.
335 Most functions that create markers, without an argument allowing to
336 specify the insertion type, create them with insertion type
337 @code{nil}. Also, the mark has, by default, insertion type
341 @section Moving Marker Positions
343 This section describes how to change the position of an existing
344 marker. When you do this, be sure you know whether the marker is used
345 outside of your program, and, if so, what effects will result from
346 moving it---otherwise, confusing things may happen in other parts of
349 @defun set-marker marker position &optional buffer
350 This function moves @var{marker} to @var{position}
351 in @var{buffer}. If @var{buffer} is not provided, it defaults to
354 If @var{position} is less than 1, @code{set-marker} moves @var{marker}
355 to the beginning of the buffer. If @var{position} is greater than the
356 size of the buffer (@pxref{Point}), @code{set-marker} moves marker to
357 the end of the buffer. If @var{position} is @code{nil} or a marker
358 that points nowhere, then @var{marker} is set to point nowhere.
360 The value returned is @var{marker}.
364 (setq m (point-marker))
365 @result{} #<marker at 4714 in markers.texi>
369 @result{} #<marker at 55 in markers.texi>
372 (setq b (get-buffer "foo"))
373 @result{} #<buffer foo>
377 @result{} #<marker at 1 in foo>
382 @defun move-marker marker position &optional buffer
383 This is another name for @code{set-marker}.
391 Each buffer has a special marker, which is designated @dfn{the
392 mark}. When a buffer is newly created, this marker exists but does
393 not point anywhere; this means that the mark ``doesn't exist'' in that
394 buffer yet. Subsequent commands can set the mark.
396 The mark specifies a position to bound a range of text for many
397 commands, such as @code{kill-region} and @code{indent-rigidly}. These
398 commands typically act on the text between point and the mark, which
399 is called the @dfn{region}. If you are writing a command that
400 operates on the region, don't examine the mark directly; instead, use
401 @code{interactive} with the @samp{r} specification. This provides the
402 values of point and the mark as arguments to the command in an
403 interactive call, but permits other Lisp programs to specify arguments
404 explicitly. @xref{Interactive Codes}.
406 Some commands set the mark as a side-effect. Commands should do
407 this only if it has a potential use to the user, and never for their
408 own internal purposes. For example, the @code{replace-regexp} command
409 sets the mark to the value of point before doing any replacements,
410 because this enables the user to move back there conveniently after
411 the replace is finished.
413 Once the mark ``exists'' in a buffer, it normally never ceases to
414 exist. However, it may become @dfn{inactive}, if Transient Mark mode
415 is enabled. The buffer-local variable @code{mark-active}, if
416 non-@code{nil}, means that the mark is active. A command can call the
417 function @code{deactivate-mark} to deactivate the mark directly, or it
418 can request deactivation of the mark upon return to the editor command
419 loop by setting the variable @code{deactivate-mark} to a
420 non-@code{nil} value.
422 If Transient Mark mode is enabled, certain editing commands that
423 normally apply to text near point, apply instead to the region when
424 the mark is active. This is the main motivation for using Transient
425 Mark mode. (Another is that this enables highlighting of the region
426 when the mark is active. @xref{Display}.)
429 In addition to the mark, each buffer has a @dfn{mark ring} which is a
430 list of markers containing previous values of the mark. When editing
431 commands change the mark, they should normally save the old value of the
432 mark on the mark ring. The variable @code{mark-ring-max} specifies the
433 maximum number of entries in the mark ring; once the list becomes this
434 long, adding a new element deletes the last element.
436 There is also a separate global mark ring, but that is used only in a
437 few particular user-level commands, and is not relevant to Lisp
438 programming. So we do not describe it here.
440 @defun mark &optional force
441 @cindex current buffer mark
442 This function returns the current buffer's mark position as an integer,
443 or @code{nil} if no mark has ever been set in this buffer.
445 If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is
446 @code{nil}, @code{mark} signals an error if the mark is inactive.
447 However, if @var{force} is non-@code{nil}, then @code{mark} disregards
448 inactivity of the mark, and returns the mark position (or @code{nil})
453 This function returns the marker that represents the current buffer's
454 mark. It is not a copy, it is the marker used internally. Therefore,
455 changing this marker's position will directly affect the buffer's
456 mark. Don't do that unless that is the effect you want.
460 (setq m (mark-marker))
461 @result{} #<marker at 3420 in markers.texi>
465 @result{} #<marker at 100 in markers.texi>
469 @result{} #<marker at 100 in markers.texi>
473 Like any marker, this marker can be set to point at any buffer you
474 like. If you make it point at any buffer other than the one of which
475 it is the mark, it will yield perfectly consistent, but rather odd,
476 results. We recommend that you not do it!
479 @defun set-mark position
480 This function sets the mark to @var{position}, and activates the mark.
481 The old value of the mark is @emph{not} pushed onto the mark ring.
483 @strong{Please note:} Use this function only if you want the user to
484 see that the mark has moved, and you want the previous mark position to
485 be lost. Normally, when a new mark is set, the old one should go on the
486 @code{mark-ring}. For this reason, most applications should use
487 @code{push-mark} and @code{pop-mark}, not @code{set-mark}.
489 Novice Emacs Lisp programmers often try to use the mark for the wrong
490 purposes. The mark saves a location for the user's convenience. An
491 editing command should not alter the mark unless altering the mark is
492 part of the user-level functionality of the command. (And, in that
493 case, this effect should be documented.) To remember a location for
494 internal use in the Lisp program, store it in a Lisp variable. For
501 (delete-region beg (point))).
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 @c Doesn't seem relevant.
511 @c @code{push-mark} returns @code{nil}.
513 The function @code{push-mark} normally @emph{does not} activate the
514 mark. To do that, specify @code{t} for the argument @var{activate}.
516 A @samp{Mark set} message is displayed unless @var{nomsg} is
521 This function pops off the top element of @code{mark-ring} and makes
522 that mark become the buffer's actual mark. This does not move point in
523 the buffer, and it does nothing if @code{mark-ring} is empty. It
524 deactivates the mark.
526 @c Seems even less relevant.
527 @c The return value is not meaningful.
530 @defopt transient-mark-mode
531 This variable, if non-@code{nil}, enables Transient Mark mode. In
532 Transient Mark mode, every buffer-modifying primitive sets
533 @code{deactivate-mark}. As a consequence, most commands that modify
534 the buffer also deactivate the mark.
536 When Transient Mark mode is enabled and the mark is active, many
537 commands that normally apply to the text near point instead apply to
538 the region. Such commands should use the function @code{use-region-p}
539 to test whether they should operate on the region. @xref{The Region}.
541 Lisp programs can set @code{transient-mark-mode} to non-@code{nil},
542 non-@code{t} values to enable Transient Mark mode temporarily. If the
543 value is @code{lambda}, Transient Mark mode is automatically turned
544 off after any action, such as buffer modification, that would normally
545 deactivate the mark. If the value is @w{@code{(only . @var{oldval})}},
546 then @code{transient-mark-mode} is set to the value @var{oldval} after
547 any subsequent command that moves point and is not shift-translated
548 (@pxref{Key Sequence Input, shift-translation}), or after any other
549 action that would normally deactivate the mark.
552 @defopt mark-even-if-inactive
553 If this is non-@code{nil}, Lisp programs and the Emacs user can use the
554 mark even when it is inactive. This option affects the behavior of
555 Transient Mark mode. When the option is non-@code{nil}, deactivation of
556 the mark turns off region highlighting, but commands that use the mark
557 behave as if the mark were still active.
560 @defvar deactivate-mark
561 If an editor command sets this variable non-@code{nil}, then the editor
562 command loop deactivates the mark after the command returns (if
563 Transient Mark mode is enabled). All the primitives that change the
564 buffer set @code{deactivate-mark}, to deactivate the mark when the
567 To write Lisp code that modifies the buffer without causing
568 deactivation of the mark at the end of the command, bind
569 @code{deactivate-mark} to @code{nil} around the code that does the
570 modification. For example:
573 (let (deactivate-mark)
578 @defun deactivate-mark &optional force
579 If Transient Mark mode is enabled or @var{force} is non-@code{nil},
580 this function deactivates the mark and runs the normal hook
581 @code{deactivate-mark-hook}. Otherwise, it does nothing.
585 The mark is active when this variable is non-@code{nil}. This
586 variable is always buffer-local in each buffer. Do @emph{not} use the
587 value of this variable to decide whether a command that normally
588 operates on text near point should operate on the region instead. Use
589 the function @code{use-region-p} for that (@pxref{The Region}).
592 @defvar activate-mark-hook
593 @defvarx deactivate-mark-hook
594 These normal hooks are run, respectively, when the mark becomes active
595 and when it becomes inactive. The hook @code{activate-mark-hook} is
596 also run at the end of the command loop if the mark is active and it
597 is possible that the region may have changed.
599 This piece of command_loop_1, run unless deactivating the mark:
600 if (current_buffer != prev_buffer || MODIFF != prev_modiff)
602 Lisp_Object hook = intern ("activate-mark-hook");
603 Frun_hooks (1, &hook);
608 @defun handle-shift-selection
609 This function implements the ``shift-selection'' behavior of
610 point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs
611 Manual}. It is called automatically by the Emacs command loop
612 whenever a command with a @samp{^} character in its @code{interactive}
613 spec is invoked, before the command itself is executed
614 (@pxref{Interactive Codes, ^}).
616 If @code{shift-select-mode} is non-@code{nil} and the current command
617 was invoked via shift translation (@pxref{Key Sequence Input,
618 shift-translation}), this function sets the mark and temporarily
619 activates the region, unless the region was already temporarily
620 activated in this way. Otherwise, if the region has been activated
621 temporarily, it deactivates the mark and restores the variable
622 @code{transient-mark-mode} to its earlier value.
626 The value of this buffer-local variable is the list of saved former
627 marks of the current buffer, most recent first.
632 @result{} (#<marker at 11050 in markers.texi>
633 #<marker at 10832 in markers.texi>
639 @defopt mark-ring-max
640 The value of this variable is the maximum size of @code{mark-ring}. If
641 more marks than this are pushed onto the @code{mark-ring},
642 @code{push-mark} discards an old mark when it adds a new one.
645 @c There is also global-mark-ring-max, but this chapter explicitly
646 @c does not talk about the global mark.
650 @cindex region (between point and mark)
652 The text between point and the mark is known as @dfn{the region}.
653 Various functions operate on text delimited by point and the mark, but
654 only those functions specifically related to the region itself are
657 The next two functions signal an error if the mark does not point
658 anywhere. If Transient Mark mode is enabled and
659 @code{mark-even-if-inactive} is @code{nil}, they also signal an error
660 if the mark is inactive.
662 @defun region-beginning
663 This function returns the position of the beginning of the region (as
664 an integer). This is the position of either point or the mark,
665 whichever is smaller.
669 This function returns the position of the end of the region (as an
670 integer). This is the position of either point or the mark, whichever is
674 @c FIXME: Mention it in tips.texi?
675 Instead of using @code{region-beginning} and @code{region-end}, a
676 command designed to operate on a region should normally use
677 @code{interactive} with the @samp{r} specification to find the
678 beginning and end of the region. This lets other Lisp programs
679 specify the bounds explicitly as arguments. @xref{Interactive Codes}.
682 This function returns @code{t} if Transient Mark mode is enabled, the
683 mark is active, and there is a valid region in the buffer. This
684 function is intended to be used by commands that operate on the
685 region, instead of on text near point, when the mark is active.
688 @vindex use-empty-active-region
689 A region is valid if it has a non-zero size, or if the user option
690 @code{use-empty-active-region} is non-@code{nil} (by default, it is
691 @code{nil}). The function @code{region-active-p} is similar to
692 @code{use-region-p}, but considers all regions as valid. In most
693 cases, you should not use @code{region-active-p}, since if the region
694 is empty it is often more appropriate to operate on point.