Mercurial > emacs

--- a/lispref/markers.texi	Thu Sep 06 04:12:51 2007 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,664 +0,0 @@
-@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