# HG changeset patch # User Glenn Morris # Date 1189051977 0 # Node ID aef42fbf0c93a14377b5f832b4523622b2ea9216 # Parent 545f172f9c74d2770867d79385fc773e00f570d1 Move to ../doc/lispref diff -r 545f172f9c74 -r aef42fbf0c93 lispref/markers.texi --- 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{} # -@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