diff doc/lispref/markers.texi @ 84086:1ddaa60edeb3

Move here from ../../lispref

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/lispref/markers.texi	Thu Sep 06 04:21:52 2007 +0000
@@ -0,0 +1,664 @@
+@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  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
+
+  A @dfn{marker} is a Lisp object used to specify a position in a buffer
+relative to the surrounding text.  A marker changes its offset from the
+beginning of the buffer automatically whenever text is inserted or
+deleted, so that it stays with the two characters on either side of it.
+
+@menu
+* Overview of Markers::      The components of a marker, and how it relocates.
+* Predicates on Markers::    Testing whether an object is a marker.
+* Creating Markers::         Making empty markers or markers at certain places.
+* Information from Markers:: Finding the marker's buffer or character position.
+* Marker Insertion Types::   Two ways a marker can relocate when you
+                               insert where it points.
+* Moving Markers::           Moving the marker to a new buffer or position.
+* The Mark::                 How "the mark" is implemented with a marker.
+* The Region::               How to access "the region".
+@end menu
+
+@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
+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
+operates on, but that is entirely the programmer's responsibility.
+@xref{Positions}, for a complete description of positions.
+
+  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.
+
+@cindex marker relocation
+  Deleting text around a marker's position leaves the marker between the
+characters immediately before and after the deleted text.  Inserting
+text at the position of a marker normally leaves the marker either in
+front of or after the new text, depending on the marker's @dfn{insertion
+type} (@pxref{Marker Insertion Types})---unless the insertion is done
+with @code{insert-before-markers} (@pxref{Insertion}).
+
+@cindex marker garbage collection
+  Insertion and deletion in a buffer must check all the markers and
+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.
+
+@cindex markers as numbers
+  Because it is common to perform arithmetic operations on a marker
+position, most of the arithmetic operations (including @code{+} and
+@code{-}) accept markers as arguments.  In such cases, the marker
+stands for its current position.
+
+Here are examples of creating markers, setting markers, and moving point
+to markers:
+
+@example
+@group
+;; @r{Make a new marker that initially does not point anywhere:}
+(setq m1 (make-marker))
+     @result{} #<marker in no buffer>
+@end group
+
+@group
+;; @r{Set @code{m1} to point between the 99th and 100th characters}
+;;   @r{in the current buffer:}
+(set-marker m1 100)
+     @result{} #<marker at 100 in markers.texi>
+@end group
+
+@group
+;; @r{Now insert one character at the beginning of the buffer:}
+(goto-char (point-min))
+     @result{} 1
+(insert "Q")
+     @result{} nil
+@end group
+
+@group
+;; @r{@code{m1} is updated appropriately.}
+m1
+     @result{} #<marker at 101 in markers.texi>
+@end group
+
+@group
+;; @r{Two markers that point to the same position}
+;;   @r{are not @code{eq}, but they are @code{equal}.}
+(setq m2 (copy-marker m1))
+     @result{} #<marker at 101 in markers.texi>
+(eq m1 m2)
+     @result{} nil
+(equal m1 m2)
+     @result{} t
+@end group
+
+@group
+;; @r{When you are finished using a marker, make it point nowhere.}
+(set-marker m1 nil)
+     @result{} #<marker in no buffer>
+@end group
+@end example
+
+@node Predicates on Markers
+@section Predicates on Markers
+
+  You can test an object to see whether it is a marker, or whether it is
+either an integer or a marker.  The latter test is useful in connection
+with the arithmetic functions that work with both markers and integers.
+
+@defun markerp object
+This function returns @code{t} if @var{object} is a marker, @code{nil}
+otherwise.  Note that integers are not markers, even though many
+functions will accept either a marker or an integer.
+@end defun
+
+@defun integer-or-marker-p object
+This function returns @code{t} if @var{object} is an integer or a marker,
+@code{nil} otherwise.
+@end defun
+
+@defun number-or-marker-p object
+This function returns @code{t} if @var{object} is a number (either
+integer or floating point) or a marker, @code{nil} otherwise.
+@end defun
+
+@node Creating Markers
+@section Functions that Create Markers
+
+  When you create a new marker, you can make it point nowhere, or point
+to the present position of point, or to the beginning or end of the
+accessible portion of the buffer, or to the same place as another given
+marker.
+
+The next four functions all return markers with insertion type
+@code{nil}.  @xref{Marker Insertion Types}.
+
+@defun make-marker
+This function returns a newly created marker that does not point
+anywhere.
+
+@example
+@group
+(make-marker)
+     @result{} #<marker in no buffer>
+@end group
+@end example
+@end defun
+
+@defun point-marker
+This function returns a new marker that points to the present position
+of point in the current buffer.  @xref{Point}.  For an example, see
+@code{copy-marker}, below.
+@end defun
+
+@defun point-min-marker
+This function returns a new marker that points to the beginning of the
+accessible portion of the buffer.  This will be the beginning of the
+buffer unless narrowing is in effect.  @xref{Narrowing}.
+@end defun
+
+@defun point-max-marker
+This function returns a new marker that points to the end of the
+accessible portion of the buffer.  This will be the end of the buffer
+unless narrowing is in effect.  @xref{Narrowing}.
+
+Here are examples of this function and @code{point-min-marker}, shown in
+a buffer containing a version of the source file for the text of this
+chapter.
+
+@example
+@group
+(point-min-marker)
+     @result{} #<marker at 1 in markers.texi>
+(point-max-marker)
+     @result{} #<marker at 15573 in markers.texi>
+@end group
+
+@group
+(narrow-to-region 100 200)
+     @result{} nil
+@end group
+@group
+(point-min-marker)
+     @result{} #<marker at 100 in markers.texi>
+@end group
+@group
+(point-max-marker)
+     @result{} #<marker at 200 in markers.texi>
+@end group
+@end example
+@end defun
+
+@defun copy-marker marker-or-integer &optional insertion-type
+If passed a marker as its argument, @code{copy-marker} returns a
+new marker that points to the same place and the same buffer as does
+@var{marker-or-integer}.  If passed an integer as its argument,
+@code{copy-marker} returns a new marker that points to position
+@var{marker-or-integer} in the current buffer.
+
+The new marker's insertion type is specified by the argument
+@var{insertion-type}.  @xref{Marker Insertion Types}.
+
+If passed an integer argument less than 1, @code{copy-marker} returns a
+new marker that points to the beginning of the current buffer.  If
+passed an integer argument greater than the length of the buffer,
+@code{copy-marker} returns a new marker that points to the end of the
+buffer.
+
+@example
+@group
+(copy-marker 0)
+     @result{} #<marker at 1 in markers.texi>
+@end group
+
+@group
+(copy-marker 20000)
+     @result{} #<marker at 7572 in markers.texi>
+@end group
+@end example
+
+An error is signaled if @var{marker} is neither a marker nor an
+integer.
+@end defun
+
+  Two distinct markers are considered @code{equal} (even though not
+@code{eq}) to each other if they have the same position and buffer, or
+if they both point nowhere.
+
+@example
+@group
+(setq p (point-marker))
+     @result{} #<marker at 2139 in markers.texi>
+@end group
+
+@group
+(setq q (copy-marker p))
+     @result{} #<marker at 2139 in markers.texi>
+@end group
+
+@group
+(eq p q)
+     @result{} nil
+@end group
+
+@group
+(equal p q)
+     @result{} t
+@end group
+@end example
+
+@node Information from Markers
+@section Information from Markers
+
+  This section describes the functions for accessing the components of a
+marker object.
+
+@defun marker-position marker
+This function returns the position that @var{marker} points to, or
+@code{nil} if it points nowhere.
+@end defun
+
+@defun marker-buffer marker
+This function returns the buffer that @var{marker} points into, or
+@code{nil} if it points nowhere.
+
+@example
+@group
+(setq m (make-marker))
+     @result{} #<marker in no buffer>
+@end group
+@group
+(marker-position m)
+     @result{} nil
+@end group
+@group
+(marker-buffer m)
+     @result{} nil
+@end group
+
+@group
+(set-marker m 3770 (current-buffer))
+     @result{} #<marker at 3770 in markers.texi>
+@end group
+@group
+(marker-buffer m)
+     @result{} #<buffer markers.texi>
+@end group
+@group
+(marker-position m)
+     @result{} 3770
+@end group
+@end example
+@end defun
+
+@defun buffer-has-markers-at position
+This function returns @code{t} if one or more markers
+point at position @var{position} in the current buffer.
+@end defun
+
+@node Marker Insertion Types
+@section Marker Insertion Types
+
+@cindex insertion type of a marker
+  When you insert text directly at the place where a marker points,
+there are two possible ways to relocate that marker: it can point before
+the inserted text, or point after it.  You can specify which one a given
+marker should do by setting its @dfn{insertion type}.  Note that use of
+@code{insert-before-markers} ignores markers' insertion types, always
+relocating a marker to point after the inserted text.
+
+@defun set-marker-insertion-type marker type
+This function sets the insertion type of marker @var{marker} to
+@var{type}.  If @var{type} is @code{t}, @var{marker} will advance when
+text is inserted at its position.  If @var{type} is @code{nil},
+@var{marker} does not advance when text is inserted there.
+@end defun
+
+@defun marker-insertion-type marker
+This function reports the current insertion type of @var{marker}.
+@end defun
+
+Most functions that create markers, without an argument allowing to
+specify the insertion type, create them with insertion type
+@code{nil}.  Also, the mark has, by default, insertion type
+@code{nil}.
+
+@node Moving Markers
+@section Moving Marker Positions
+
+  This section describes how to change the position of an existing
+marker.  When you do this, be sure you know whether the marker is used
+outside of your program, and, if so, what effects will result from
+moving it---otherwise, confusing things may happen in other parts of
+Emacs.
+
+@defun set-marker marker position &optional buffer
+This function moves @var{marker} to @var{position}
+in @var{buffer}.  If @var{buffer} is not provided, it defaults to
+the current buffer.
+
+If @var{position} is less than 1, @code{set-marker} moves @var{marker}
+to the beginning of the buffer.  If @var{position} is greater than the
+size of the buffer, @code{set-marker} moves marker to the end of the
+buffer.  If @var{position} is @code{nil} or a marker that points
+nowhere, then @var{marker} is set to point nowhere.
+
+The value returned is @var{marker}.
+
+@example
+@group
+(setq m (point-marker))
+     @result{} #<marker at 4714 in markers.texi>
+@end group
+@group
+(set-marker m 55)
+     @result{} #<marker at 55 in markers.texi>
+@end group
+@group
+(setq b (get-buffer "foo"))
+     @result{} #<buffer foo>
+@end group
+@group
+(set-marker m 0 b)
+     @result{} #<marker at 1 in foo>
+@end group
+@end example
+@end defun
+
+@defun move-marker marker position &optional buffer
+This is another name for @code{set-marker}.
+@end defun
+
+@node The Mark
+@section The Mark
+@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
+@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.
+
+  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}.
+
+  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
+commands change the mark, they should normally save the old value of the
+mark on the mark ring.  The variable @code{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.
+
+  There is also a separate global mark ring, but that is used only in a
+few particular user-level commands, and is not relevant to Lisp
+programming.  So we do not describe it here.
+
+@defun mark &optional force
+@cindex current buffer mark
+This function returns the current buffer's mark position as an integer,
+or @code{nil} if no mark has ever been set in this buffer.
+
+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}).
+@end defun
+
+@defun mark-marker
+This function returns the marker that represents the current buffer's
+mark.  It is not a copy, it is the marker used internally.  Therefore,
+changing this marker's position will directly affect the buffer's
+mark.  Don't do that unless that is the effect you want.
+
+@example
+@group
+(setq m (mark-marker))
+     @result{} #<marker at 3420 in markers.texi>
+@end group
+@group
+(set-marker m 100)
+     @result{} #<marker at 100 in markers.texi>
+@end group
+@group
+(mark-marker)
+     @result{} #<marker at 100 in markers.texi>
+@end group
+@end example
+
+Like any marker, this marker can be set to point at any buffer you
+like.  If you make it point at any buffer other than the one of which
+it is the mark, it will yield perfectly consistent, but rather odd,
+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.
+
+@strong{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
+@code{mark-ring}.  For this reason, most applications should use
+@code{push-mark} and @code{pop-mark}, not @code{set-mark}.
+
+Novice Emacs 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:
+
+@example
+@group
+(let ((beg (point)))
+  (forward-line 1)
+  (delete-region beg (point))).
+@end group
+@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}.
+
+The function @code{push-mark} normally @emph{does not} activate the
+mark.  To do that, specify @code{t} for the argument @var{activate}.
+
+A @samp{Mark set} message is displayed unless @var{nomsg} is
+non-@code{nil}.
+@end defun
+
+@defun pop-mark
+This function pops off the top element of @code{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 @code{mark-ring} is empty.  It
+deactivates the mark.
+
+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}.
+@end defopt
+
+@defopt mark-even-if-inactive
+If this is non-@code{nil}, Lisp programs and the Emacs user can use the
+mark even when it is inactive.  This option affects the behavior of
+Transient Mark mode.  When the option is non-@code{nil}, deactivation of
+the mark turns off region highlighting, but commands that use the mark
+behave as if the mark were still active.
+@end defopt
+
+@defvar deactivate-mark
+If an editor command sets this variable non-@code{nil}, then the editor
+command loop deactivates the mark after the command returns (if
+Transient Mark mode is enabled).  All the primitives that change the
+buffer set @code{deactivate-mark}, to deactivate the mark when the
+command is finished.
+
+To write Lisp code that modifies the buffer without causing
+deactivation of the mark at the end of the command, bind
+@code{deactivate-mark} to @code{nil} around the code that does the
+modification.  For example:
+
+@example
+(let (deactivate-mark)
+  (insert " "))
+@end example
+@end defvar
+
+@defun deactivate-mark
+This function deactivates the mark, if Transient Mark mode is enabled.
+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.
+@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.
+@end defvar
+
+@defvar mark-ring
+The value of this buffer-local variable is the list of saved former
+marks of the current buffer, most recent first.
+
+@example
+@group
+mark-ring
+@result{} (#<marker at 11050 in markers.texi>
+    #<marker at 10832 in markers.texi>
+    @dots{})
+@end group
+@end example
+@end defvar
+
+@defopt mark-ring-max
+The value of this variable is the maximum size of @code{mark-ring}.  If
+more marks than this are pushed onto the @code{mark-ring},
+@code{push-mark} discards an old mark when it adds a new one.
+@end defopt
+
+@node The Region
+@section The Region
+@cindex region (between point and mark)
+
+  The text between point and the mark is known as @dfn{the region}.
+Various functions operate on text delimited by point and the mark, but
+only those functions specifically related to the region itself are
+described here.
+
+The next two functions signal an error if the mark does not point
+anywhere.  If Transient Mark mode is enabled and
+@code{mark-even-if-inactive} is @code{nil}, they also signal an error
+if the mark is inactive.
+
+@defun region-beginning
+This function returns the position of the beginning of the region (as
+an integer).  This is the position of either point or the mark,
+whichever is smaller.
+@end defun
+
+@defun region-end
+This function returns the position of the end of the region (as an
+integer).  This is the position of either point or the mark, whichever is
+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}.)
+
+@ignore
+   arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299
+@end ignore