@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/markers
@node Markers, Text, Positions, Top
@chapter Markers
@cindex markers
@node Overview of Markers
@section Overview of Markers
- A marker specifies a buffer and a position in that buffer. The
-marker can be used to represent a position in the functions that
+ A marker specifies a buffer and a position in that buffer. A
+marker can be used to represent a position in functions that
require one, just as an integer could be used. In that case, the
marker's buffer is normally ignored. Of course, a marker used in this
way usually points to a position in the buffer that the function
A marker has three attributes: the marker position, the marker
buffer, and the insertion type. The marker position is an integer
that is equivalent (at a given time) to the marker as a position in
-that buffer. But the marker's position value can change often during
-the life of the marker. Insertion and deletion of text in the buffer
-relocate the marker. The idea is that a marker positioned between two
-characters remains between those two characters despite insertion and
-deletion elsewhere in the buffer. Relocation changes the integer
-equivalent of the marker.
+that buffer. But the marker's position value can change during
+the life of the marker, and often does. Insertion and deletion of
+text in the buffer relocate the marker. The idea is that a marker
+positioned between two characters remains between those two characters
+despite insertion and deletion elsewhere in the buffer. Relocation
+changes the integer equivalent of the marker.
@cindex marker relocation
Deleting text around a marker's position leaves the marker between the
relocate them if necessary. This slows processing in a buffer with a
large number of markers. For this reason, it is a good idea to make a
marker point nowhere if you are sure you don't need it any more.
-Unreferenced markers are garbage collected eventually, but until then
-will continue to use time if they do point somewhere.
+Markers that can no longer be accessed are eventually removed
+(@pxref{Garbage Collection}).
@cindex markers as numbers
Because it is common to perform arithmetic operations on a marker
-position, most of the arithmetic operations (including @code{+} and
+position, most of these operations (including @code{+} and
@code{-}) accept markers as arguments. In such cases, the marker
stands for its current position.
(point-min-marker)
@result{} #<marker at 1 in markers.texi>
(point-max-marker)
- @result{} #<marker at 15573 in markers.texi>
+ @result{} #<marker at 24080 in markers.texi>
@end group
@group
@end group
@group
-(copy-marker 20000)
- @result{} #<marker at 7572 in markers.texi>
+(copy-marker 90000)
+ @result{} #<marker at 24080 in markers.texi>
@end group
@end example
@cindex mark, the
@cindex mark ring
- One special marker in each buffer is designated @dfn{the mark}. It
-specifies a position to bound a range of text for commands such as
-@code{kill-region} and @code{indent-rigidly}. 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
-@code{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.
-
- Many commands are designed to operate on the text between point and
-the mark when called interactively. If you are writing such a
-command, don't examine the mark directly; instead, use
+ Each buffer has a special marker, which is designated @dfn{the
+mark}. When a buffer is newly created, this marker exists but does
+not point anywhere; this means that the mark ``doesn't exist'' in that
+buffer yet. Subsequent commands can set the mark.
+
+ The mark specifies a position to bound a range of text for many
+commands, such as @code{kill-region} and @code{indent-rigidly}. These
+commands typically act on the text between point and the mark, which
+is called the @dfn{region}. If you are writing a command that
+operates on the region, don't examine the mark directly; instead, use
@code{interactive} with the @samp{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. @xref{Interactive Codes}.
- Each buffer has a marker which represents the value of the mark in
-that buffer, independent of any other buffer. When a buffer is newly
-created, this marker exists but does not point anywhere. That means
-the mark ``doesn't exist'' in that buffer as yet.
+ Some commands set the mark as a side-effect. Commands should do
+this only if it has a potential use to the user, and never for their
+own internal purposes. For example, the @code{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 @dfn{inactive}, if Transient Mark mode is
-enabled. The variable @code{mark-active}, which is always buffer-local
-in all buffers, indicates whether the mark is active: non-@code{nil}
-means yes. A command can request deactivation of the mark upon return
-to the editor command loop by setting @code{deactivate-mark} to a
-non-@code{nil} value (but this causes deactivation only if Transient
-Mark mode is enabled).
-
- The main motivation for using Transient Mark mode is that this mode
-also enables highlighting of the region when the mark is active.
-@xref{Display}.
+exist. However, it may become @dfn{inactive}, if Transient Mark mode
+is enabled. The buffer-local variable @code{mark-active}, if
+non-@code{nil}, means that the mark is active. A command can call the
+function @code{deactivate-mark} to deactivate the mark directly, or it
+can request deactivation of the mark upon return to the editor command
+loop by setting the variable @code{deactivate-mark} to a
+non-@code{nil} value.
+
+ If Transient Mark mode is enabled, certain editing commands that
+normally apply to text near point, apply instead to the region when
+the mark is active. This is the main motivation for using Transient
+Mark mode. (Another is that this enables highlighting of the region
+when the mark is active. @xref{Display}.)
In addition to the mark, each buffer has a @dfn{mark ring} which is a
list of markers containing previous values of the mark. When editing
If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is
@code{nil}, @code{mark} signals an error if the mark is inactive.
However, if @var{force} is non-@code{nil}, then @code{mark} disregards
-inactivity of the mark, and returns the mark position anyway (or
-@code{nil}).
+inactivity of the mark, and returns the mark position (or @code{nil})
+anyway.
@end defun
@defun mark-marker
results. We recommend that you not do it!
@end defun
-@ignore
-@deffn Command set-mark-command jump
-If @var{jump} is @code{nil}, this command sets the mark to the value
-of point and pushes the previous value of the mark on the mark ring. The
-message @samp{Mark set} is also displayed in the echo area.
-
-If @var{jump} is not @code{nil}, this command sets point to the value
-of the mark, and sets the mark to the previous saved mark value, which
-is popped off the mark ring.
-
-This function is @emph{only} intended for interactive use.
-@end deffn
-@end ignore
-
@defun set-mark position
This function sets the mark to @var{position}, and activates the mark.
The old value of the mark is @emph{not} pushed onto the mark ring.
@end example
@end defun
-@c for interactive use only
-@ignore
-@deffn Command exchange-point-and-mark
-This function exchanges the positions of point and the mark.
-It is intended for interactive use.
-@end deffn
-@end ignore
-
@defun push-mark &optional position nomsg activate
This function sets the current buffer's mark to @var{position}, and
pushes a copy of the previous mark onto @code{mark-ring}. If
@var{position} is @code{nil}, then the value of point is used.
-@code{push-mark} returns @code{nil}.
+@c Doesn't seem relevant.
+@c @code{push-mark} returns @code{nil}.
The function @code{push-mark} normally @emph{does not} activate the
mark. To do that, specify @code{t} for the argument @var{activate}.
that mark become the buffer's actual mark. This does not move point in
the buffer, and it does nothing if @code{mark-ring} is empty. It
deactivates the mark.
-
-The return value is not meaningful.
+@c
+@c Seems even less relevant.
+@c The return value is not meaningful.
@end defun
@defopt transient-mark-mode
-@c @cindex Transient Mark mode Redundant
-This variable if non-@code{nil} enables Transient Mark mode, in which
-every buffer-modifying primitive sets @code{deactivate-mark}. The
-consequence of this is that commands that modify the buffer normally
-make the mark inactive.
-
-Lisp programs can set @code{transient-mark-mode} to @code{only} to
-enable Transient Mark mode for the following command only. During
-that following command, the value of @code{transient-mark-mode} is
-@code{identity}. If it is still @code{identity} at the end of the
-command, it changes to @code{nil}.
+This variable, if non-@code{nil}, enables Transient Mark mode. In
+Transient Mark mode, every buffer-modifying primitive sets
+@code{deactivate-mark}. As a consequence, most commands that modify
+the buffer also deactivate the mark.
+
+When Transient Mark mode is enabled and the mark is active, many
+commands that normally apply to the text near point instead apply to
+the region. Such commands should use the function @code{use-region-p}
+to test whether they should operate on the region. @xref{The Region}.
+
+Lisp programs can set @code{transient-mark-mode} to non-@code{nil},
+non-@code{t} values to enable Transient Mark mode temporarily. If the
+value is @code{lambda}, Transient Mark mode is automatically turned
+off after any action, such as buffer modification, that would normally
+deactivate the mark. If the value is @w{@code{(only . @var{oldval})}},
+then @code{transient-mark-mode} is set to the value @var{oldval} after
+any subsequent command that moves point and is not shift-translated
+(@pxref{Key Sequence Input, shift-translation}), or after any other
+action that would normally deactivate the mark.
@end defopt
@defopt mark-even-if-inactive
@end example
@end defvar
-@defun deactivate-mark
-This function deactivates the mark, if Transient Mark mode is enabled.
-Otherwise it does nothing.
+@defun deactivate-mark &optional force
+If Transient Mark mode is enabled or @var{force} is non-@code{nil},
+this function deactivates the mark and runs the normal hook
+@code{deactivate-mark-hook}. Otherwise, it does nothing.
@end defun
@defvar mark-active
-The mark is active when this variable is non-@code{nil}. This variable
-is always buffer-local in each buffer.
+The mark is active when this variable is non-@code{nil}. This
+variable is always buffer-local in each buffer. Do @emph{not} use the
+value of this variable to decide whether a command that normally
+operates on text near point should operate on the region instead. Use
+the function @code{use-region-p} for that (@pxref{The Region}).
@end defvar
@defvar activate-mark-hook
@defvarx deactivate-mark-hook
These normal hooks are run, respectively, when the mark becomes active
and when it becomes inactive. The hook @code{activate-mark-hook} is
-also run at the end of a command if the mark is active and it is
-possible that the region may have changed.
+also run at the end of the command loop if the mark is active and it
+is possible that the region may have changed.
+@ignore
+This piece of command_loop_1, run unless deactivating the mark:
+ if (current_buffer != prev_buffer || MODIFF != prev_modiff)
+ {
+ Lisp_Object hook = intern ("activate-mark-hook");
+ Frun_hooks (1, &hook);
+ }
+@end ignore
@end defvar
+@defun handle-shift-selection
+This function implements the ``shift-selection'' behavior of
+point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs
+Manual}. It is called automatically by the Emacs command loop
+whenever a command with a @samp{^} character in its @code{interactive}
+spec is invoked, before the command itself is executed
+(@pxref{Interactive Codes, ^}).
+
+If @code{shift-select-mode} is non-@code{nil} and the current command
+was invoked via shift translation (@pxref{Key Sequence Input,
+shift-translation}), this function sets the mark and temporarily
+activates the region, unless the region was already temporarily
+activated in this way. Otherwise, if the region has been activated
+temporarily, it deactivates the mark and restores the variable
+@code{transient-mark-mode} to its earlier value.
+@end defun
+
@defvar mark-ring
The value of this buffer-local variable is the list of saved former
marks of the current buffer, most recent first.
@code{push-mark} discards an old mark when it adds a new one.
@end defopt
+@c There is also global-mark-ring-max, but this chapter explicitly
+@c does not talk about the global mark.
+
@node The Region
@section The Region
@cindex region (between point and mark)
larger.
@end defun
- Few programs need to use the @code{region-beginning} and
-@code{region-end} functions. A command designed to operate on a region
-should normally use @code{interactive} with the @samp{r} specification
-to find the beginning and end of the region. This lets other Lisp
-programs specify the bounds explicitly as arguments. (@xref{Interactive
-Codes}.)
+ Instead of using @code{region-beginning} and @code{region-end}, a
+command designed to operate on a region should normally use
+@code{interactive} with the @samp{r} specification to find the
+beginning and end of the region. This lets other Lisp programs
+specify the bounds explicitly as arguments. @xref{Interactive Codes}.
+
+@defun use-region-p
+This function returns @code{t} if Transient Mark mode is enabled, the
+mark is active, and there is a valid region in the buffer. This
+function is intended to be used by commands that operate on the
+region, instead of on text near point, when the mark is active.
+
+A region is valid if it has a non-zero size, or if the user option
+@code{use-empty-active-region} is non-@code{nil} (by default, it is
+@code{nil}). The function @code{region-active-p} is similar to
+@code{use-region-p}, but considers all regions as valid. In most
+cases, you should not use @code{region-active-p}, since if the region
+is empty it is often more appropriate to operate on point.
+@end defun
-@ignore
- arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299
-@end ignore
HCoop / bpt / emacs.git / blobdiff