Next: , Previous: Changing Markers, Up: Markers

42.6 The Mark

One special marker in each buffer is designated the mark. It records a position for the user for the sake of commands such as C-w and C-x <TAB>. Lisp programs should set the mark only to values that have a potential use to the user, and never for their own internal purposes. For example, the replace-regexp command sets the mark to the value of point before doing any replacements, because this enables the user to move back there conveniently after the replace is finished.

Once the mark “exists” in a buffer, it normally never ceases to exist. However, it may become inactive, and usually does so after each command (other than simple motion commands and some commands that explicitly activate the mark). When the mark is active, the region between point and the mark is called the active region and is highlighted specially.

Many commands are designed so that when called interactively they operate on the text between point and the mark. Such commands work only when an active region exists, i.e. when the mark is active. (The reason for this is to prevent you from accidentally deleting or changing large chunks of your text.) If you are writing such a command, don't examine the mark directly; instead, use interactive with the ‘r’ specification. This provides the values of point and the mark as arguments to the command in an interactive call, but permits other Lisp programs to specify arguments explicitly, and automatically signals an error if the command is called interactively when no active region exists. See Interactive Codes.

Each buffer has its own value of the mark that is independent of the value of the mark in other buffers. (When a buffer is created, the mark exists but does not point anywhere. We consider this state as “the absence of a mark in that buffer.”) However, only one active region can exist at a time. Activating the mark in one buffer automatically deactivates an active mark in any other buffer. Note that the user can explicitly activate a mark at any time by using the command activate-region (normally bound to M-C-z) or by using the command exchange-point-and-mark (normally bound to C-x C-x), which has the side effect of activating the mark.

Some people do not like active regions, so they disable this behavior by setting the variable zmacs-regions to nil. This makes the mark always active (except when a buffer is just created and the mark points nowhere), and turns off the highlighting of the region between point and the mark. Commands that explicitly retrieve the value of the mark should make sure that they behave correctly and consistently irrespective of the setting of zmacs-regions; some primitives are provided to ensure this behavior.

In addition to the mark, each buffer has a mark ring which is a list of markers containing previous values of the mark. When editing commands change the mark, they should normally save the old value of the mark on the mark ring. The variable mark-ring-max specifies the maximum number of entries in the mark ring; once the list becomes this long, adding a new element deletes the last element.

— Function: mark &optional force buffer

This function returns buffer's mark position as an integer. buffer defaults to the current buffer if omitted.

If the mark is inactive, mark normally returns nil. However, if force is non-nil, then mark returns the mark position anyway—or nil, if the mark is not yet set for the buffer.

(Remember that if zmacs-regions is nil, the mark is always active as long as it exists, and the force argument will have no effect.)

If you are using this in an editing command, you are most likely making a mistake; see the documentation of set-mark below.

— Function: mark-marker &optional force buffer

This function returns buffer's mark. buffer defaults to the current buffer if omitted. This is the very marker that records the mark location inside SXEmacs, not a copy. Therefore, changing this marker's position will directly affect the position of the mark. Don't do it unless that is the effect you want.

If the mark is inactive, mark-marker normally returns nil. However, if force is non-nil, then mark-marker returns the mark anyway. 

          (setq m (mark-marker))
               ⇒ #<marker at 3420 in markers.texi>
          (set-marker m 100)
               ⇒ #<marker at 100 in markers.texi>
          (mark-marker)
               ⇒ #<marker at 100 in markers.texi>

Like any marker, this marker can be set to point at any buffer you like. We don't recommend that you make it point at any buffer other than the one of which it is the mark. If you do, it will yield perfectly consistent, but rather odd, results.

— Function: set-mark position &optional buffer

This function sets buffer's mark to position, and activates the mark. buffer defaults to the current buffer if omitted. The old value of the mark is not pushed onto the mark ring.

Please note: Use this function only if you want the user to see that the mark has moved, and you want the previous mark position to be lost. Normally, when a new mark is set, the old one should go on the mark-ring. For this reason, most applications should use push-mark and pop-mark, not set-mark.

Novice SXEmacs Lisp programmers often try to use the mark for the wrong purposes. The mark saves a location for the user's convenience. An editing command should not alter the mark unless altering the mark is part of the user-level functionality of the command. (And, in that case, this effect should be documented.) To remember a location for internal use in the Lisp program, store it in a Lisp variable. For example: 

          (let ((start (point)))
            (forward-line 1)
            (delete-region start (point))).
— Command: exchange-point-and-mark &optional dont-activate-region

This function exchanges the positions of point and the mark. It is intended for interactive use. The mark is also activated unless dont-activate-region is non-nil.

— Function: push-mark &optional position nomsg activate buffer

This function sets buffer's mark to position, and pushes a copy of the previous mark onto mark-ring. buffer defaults to the current buffer if omitted. If position is nil, then the value of point is used. push-mark returns nil.

If the last global mark pushed was not in buffer, also push position on the global mark ring (see below).

The function push-mark normally does not activate the mark. To do that, specify t for the argument activate.

A ‘Mark set’ message is displayed unless nomsg is non-nil.

— Function: pop-mark

This function pops off the top element of mark-ring and makes that mark become the buffer's actual mark. This does not move point in the buffer, and it does nothing if mark-ring is empty. It deactivates the mark.

The return value is not meaningful.

— Variable: mark-ring

The value of this buffer-local variable is the list of saved former marks of the current buffer, most recent first. 

          mark-ring
          ⇒ (#<marker at 11050 in markers.texi>
              #<marker at 10832 in markers.texi>
              ...)
— User Option: mark-ring-max

The value of this variable is the maximum size of mark-ring. If more marks than this are pushed onto the mark-ring, push-mark discards an old mark when it adds a new one.

In additional to a per-buffer mark ring, there is a global mark ring. Marks are pushed onto the global mark ring the first time you set a mark after switching buffers.

— Variable: global-mark-ring

The value of this variable is the list of saved former global marks, most recent first.

— User Option: mark-ring-max

The value of this variable is the maximum size of global-mark-ring. If more marks than this are pushed onto the global-mark-ring, push-mark discards an old mark when it adds a new one.

— Command: pop-global-mark

This function pops a mark off the global mark ring and jumps to that location.