-File: lispref.info, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring
-
-Internals of the Kill Ring
---------------------------
-
- The variable `kill-ring' holds the kill ring contents, in the form
-of a list of strings. The most recent kill is always at the front of
-the list.
-
- The `kill-ring-yank-pointer' variable points to a link in the kill
-ring list, whose CAR is the text to yank next. We say it identifies
-the "front" of the ring. Moving `kill-ring-yank-pointer' to a
-different link is called "rotating the kill ring". We call the kill
-ring a "ring" because the functions that move the yank pointer wrap
-around from the end of the list to the beginning, or vice-versa.
-Rotation of the kill ring is virtual; it does not change the value of
-`kill-ring'.
-
- Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
-whose values are normally lists. The word "pointer" in the name of the
-`kill-ring-yank-pointer' indicates that the variable's purpose is to
-identify one element of the list for use by the next yank command.
-
- The value of `kill-ring-yank-pointer' is always `eq' to one of the
-links in the kill ring list. The element it identifies is the CAR of
-that link. Kill commands, which change the kill ring, also set this
-variable to the value of `kill-ring'. The effect is to rotate the ring
-so that the newly killed text is at the front.
-
- Here is a diagram that shows the variable `kill-ring-yank-pointer'
-pointing to the second entry in the kill ring `("some text" "a
-different piece of text" "yet older text")'.
-
- kill-ring kill-ring-yank-pointer
- | |
- | ___ ___ ---> ___ ___ ___ ___
- --> |___|___|------> |___|___|--> |___|___|--> nil
- | | |
- | | |
- | | -->"yet older text"
- | |
- | --> "a different piece of text"
- |
- --> "some text"
-
-This state of affairs might occur after `C-y' (`yank') immediately
-followed by `M-y' (`yank-pop').
-
- - Variable: kill-ring
- This variable holds the list of killed text sequences, most
- recently killed first.
-
- - Variable: kill-ring-yank-pointer
- This variable's value indicates which element of the kill ring is
- at the "front" of the ring for yanking. More precisely, the value
- is a tail of the value of `kill-ring', and its CAR is the kill
- string that `C-y' should yank.
-
- - User Option: kill-ring-max
- The value of this variable is the maximum length to which the kill
- ring can grow, before elements are thrown away at the end. The
- default value for `kill-ring-max' is 30.
+File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
+
+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. *Note 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 XEmacs, 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 XEmacs 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.