# HG changeset patch # User Glenn Morris # Date 1189052512 0 # Node ID 1ddaa60edeb3d928c9902adb236334dec2c0c575 # Parent 0e98d539021160c6c3d4d487989c79de6170d1f6 Move here from ../../lispref diff -r 0e98d5390211 -r 1ddaa60edeb3 doc/lispref/markers.texi --- /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{} # +@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{} # +@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{} # +@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{} # +(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{} # +@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{} # +@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{} # +(point-max-marker) + @result{} # +@end group + +@group +(narrow-to-region 100 200) + @result{} nil +@end group +@group +(point-min-marker) + @result{} # +@end group +@group +(point-max-marker) + @result{} # +@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{} # +@end group + +@group +(copy-marker 20000) + @result{} # +@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{} # +@end group + +@group +(setq q (copy-marker p)) + @result{} # +@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{} # +@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{} # +@end group +@group +(marker-buffer m) + @result{} # +@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{} # +@end group +@group +(set-marker m 55) + @result{} # +@end group +@group +(setq b (get-buffer "foo")) + @result{} # +@end group +@group +(set-marker m 0 b) + @result{} # +@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{} # +@end group +@group +(set-marker m 100) + @result{} # +@end group +@group +(mark-marker) + @result{} # +@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{} (# + # + @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