Mercurial > emacs
annotate lispref/markers.texi @ 73548:227bb8f9276e
* makefile.w32-in: revert last change.
author | Chong Yidong <cyd@stupidchicken.com> |
---|---|
date | Mon, 30 Oct 2006 14:15:57 +0000 |
parents | 17479ca5deda |
children | 6d19c76d81c5 8a8e69664178 |
rev | line source |
---|---|
6444 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
64889
e836425ee789
Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
64452
diff
changeset
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, |
68648
067115a6e738
Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
68284
diff
changeset
|
4 @c 2004, 2005, 2006 Free Software Foundation, Inc. |
6444 | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/markers | |
7 @node Markers, Text, Positions, Top | |
8 @chapter Markers | |
9 @cindex markers | |
10 | |
11 A @dfn{marker} is a Lisp object used to specify a position in a buffer | |
12 relative to the surrounding text. A marker changes its offset from the | |
13 beginning of the buffer automatically whenever text is inserted or | |
14 deleted, so that it stays with the two characters on either side of it. | |
15 | |
16 @menu | |
17 * Overview of Markers:: The components of a marker, and how it relocates. | |
18 * Predicates on Markers:: Testing whether an object is a marker. | |
19 * Creating Markers:: Making empty markers or markers at certain places. | |
20 * Information from Markers:: Finding the marker's buffer or character position. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
21 * Marker Insertion Types:: Two ways a marker can relocate when you |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
22 insert where it points. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
23 * Moving Markers:: Moving the marker to a new buffer or position. |
71958
17479ca5deda
Use real doublequote in menus.
Richard M. Stallman <rms@gnu.org>
parents:
71703
diff
changeset
|
24 * The Mark:: How "the mark" is implemented with a marker. |
17479ca5deda
Use real doublequote in menus.
Richard M. Stallman <rms@gnu.org>
parents:
71703
diff
changeset
|
25 * The Region:: How to access "the region". |
6444 | 26 @end menu |
27 | |
28 @node Overview of Markers | |
29 @section Overview of Markers | |
30 | |
53104
b0b3d8b864b8
(Overview of Markers): Mention that, if a marker is used a a position,
Luc Teirlinck <teirllm@auburn.edu>
parents:
53036
diff
changeset
|
31 A marker specifies a buffer and a position in that buffer. The |
b0b3d8b864b8
(Overview of Markers): Mention that, if a marker is used a a position,
Luc Teirlinck <teirllm@auburn.edu>
parents:
53036
diff
changeset
|
32 marker can be used to represent a position in the functions that |
b0b3d8b864b8
(Overview of Markers): Mention that, if a marker is used a a position,
Luc Teirlinck <teirllm@auburn.edu>
parents:
53036
diff
changeset
|
33 require one, just as an integer could be used. In that case, the |
b0b3d8b864b8
(Overview of Markers): Mention that, if a marker is used a a position,
Luc Teirlinck <teirllm@auburn.edu>
parents:
53036
diff
changeset
|
34 marker's buffer is normally ignored. Of course, a marker used in this |
b0b3d8b864b8
(Overview of Markers): Mention that, if a marker is used a a position,
Luc Teirlinck <teirllm@auburn.edu>
parents:
53036
diff
changeset
|
35 way usually points to a position in the buffer that the function |
b0b3d8b864b8
(Overview of Markers): Mention that, if a marker is used a a position,
Luc Teirlinck <teirllm@auburn.edu>
parents:
53036
diff
changeset
|
36 operates on, but that is entirely the programmer's responsibility. |
b0b3d8b864b8
(Overview of Markers): Mention that, if a marker is used a a position,
Luc Teirlinck <teirllm@auburn.edu>
parents:
53036
diff
changeset
|
37 @xref{Positions}, for a complete description of positions. |
6444 | 38 |
68284
a0f252483758
(Overview of Markers): Count insertion type as one of a marker's attributes.
Richard M. Stallman <rms@gnu.org>
parents:
68044
diff
changeset
|
39 A marker has three attributes: the marker position, the marker |
a0f252483758
(Overview of Markers): Count insertion type as one of a marker's attributes.
Richard M. Stallman <rms@gnu.org>
parents:
68044
diff
changeset
|
40 buffer, and the insertion type. The marker position is an integer |
a0f252483758
(Overview of Markers): Count insertion type as one of a marker's attributes.
Richard M. Stallman <rms@gnu.org>
parents:
68044
diff
changeset
|
41 that is equivalent (at a given time) to the marker as a position in |
a0f252483758
(Overview of Markers): Count insertion type as one of a marker's attributes.
Richard M. Stallman <rms@gnu.org>
parents:
68044
diff
changeset
|
42 that buffer. But the marker's position value can change often during |
a0f252483758
(Overview of Markers): Count insertion type as one of a marker's attributes.
Richard M. Stallman <rms@gnu.org>
parents:
68044
diff
changeset
|
43 the life of the marker. Insertion and deletion of text in the buffer |
a0f252483758
(Overview of Markers): Count insertion type as one of a marker's attributes.
Richard M. Stallman <rms@gnu.org>
parents:
68044
diff
changeset
|
44 relocate the marker. The idea is that a marker positioned between two |
a0f252483758
(Overview of Markers): Count insertion type as one of a marker's attributes.
Richard M. Stallman <rms@gnu.org>
parents:
68044
diff
changeset
|
45 characters remains between those two characters despite insertion and |
a0f252483758
(Overview of Markers): Count insertion type as one of a marker's attributes.
Richard M. Stallman <rms@gnu.org>
parents:
68044
diff
changeset
|
46 deletion elsewhere in the buffer. Relocation changes the integer |
a0f252483758
(Overview of Markers): Count insertion type as one of a marker's attributes.
Richard M. Stallman <rms@gnu.org>
parents:
68044
diff
changeset
|
47 equivalent of the marker. |
6444 | 48 |
49 @cindex marker relocation | |
50 Deleting text around a marker's position leaves the marker between the | |
51 characters immediately before and after the deleted text. Inserting | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
52 text at the position of a marker normally leaves the marker either in |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
53 front of or after the new text, depending on the marker's @dfn{insertion |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
54 type} (@pxref{Marker Insertion Types})---unless the insertion is done |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
55 with @code{insert-before-markers} (@pxref{Insertion}). |
6444 | 56 |
57 @cindex marker garbage collection | |
58 Insertion and deletion in a buffer must check all the markers and | |
59 relocate them if necessary. This slows processing in a buffer with a | |
60 large number of markers. For this reason, it is a good idea to make a | |
61 marker point nowhere if you are sure you don't need it any more. | |
62 Unreferenced markers are garbage collected eventually, but until then | |
63 will continue to use time if they do point somewhere. | |
64 | |
65 @cindex markers as numbers | |
66 Because it is common to perform arithmetic operations on a marker | |
67 position, most of the arithmetic operations (including @code{+} and | |
68 @code{-}) accept markers as arguments. In such cases, the marker | |
69 stands for its current position. | |
70 | |
71 Here are examples of creating markers, setting markers, and moving point | |
72 to markers: | |
73 | |
74 @example | |
75 @group | |
76 ;; @r{Make a new marker that initially does not point anywhere:} | |
77 (setq m1 (make-marker)) | |
78 @result{} #<marker in no buffer> | |
79 @end group | |
80 | |
81 @group | |
82 ;; @r{Set @code{m1} to point between the 99th and 100th characters} | |
83 ;; @r{in the current buffer:} | |
84 (set-marker m1 100) | |
85 @result{} #<marker at 100 in markers.texi> | |
86 @end group | |
87 | |
88 @group | |
89 ;; @r{Now insert one character at the beginning of the buffer:} | |
90 (goto-char (point-min)) | |
91 @result{} 1 | |
92 (insert "Q") | |
93 @result{} nil | |
94 @end group | |
95 | |
96 @group | |
97 ;; @r{@code{m1} is updated appropriately.} | |
98 m1 | |
99 @result{} #<marker at 101 in markers.texi> | |
100 @end group | |
101 | |
102 @group | |
103 ;; @r{Two markers that point to the same position} | |
104 ;; @r{are not @code{eq}, but they are @code{equal}.} | |
105 (setq m2 (copy-marker m1)) | |
106 @result{} #<marker at 101 in markers.texi> | |
107 (eq m1 m2) | |
108 @result{} nil | |
109 (equal m1 m2) | |
110 @result{} t | |
111 @end group | |
112 | |
113 @group | |
114 ;; @r{When you are finished using a marker, make it point nowhere.} | |
115 (set-marker m1 nil) | |
116 @result{} #<marker in no buffer> | |
117 @end group | |
118 @end example | |
119 | |
120 @node Predicates on Markers | |
121 @section Predicates on Markers | |
122 | |
123 You can test an object to see whether it is a marker, or whether it is | |
124 either an integer or a marker. The latter test is useful in connection | |
125 with the arithmetic functions that work with both markers and integers. | |
126 | |
127 @defun markerp object | |
128 This function returns @code{t} if @var{object} is a marker, @code{nil} | |
129 otherwise. Note that integers are not markers, even though many | |
130 functions will accept either a marker or an integer. | |
131 @end defun | |
132 | |
133 @defun integer-or-marker-p object | |
134 This function returns @code{t} if @var{object} is an integer or a marker, | |
135 @code{nil} otherwise. | |
136 @end defun | |
137 | |
138 @defun number-or-marker-p object | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
139 This function returns @code{t} if @var{object} is a number (either |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
140 integer or floating point) or a marker, @code{nil} otherwise. |
6444 | 141 @end defun |
142 | |
143 @node Creating Markers | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
144 @section Functions that Create Markers |
6444 | 145 |
146 When you create a new marker, you can make it point nowhere, or point | |
147 to the present position of point, or to the beginning or end of the | |
148 accessible portion of the buffer, or to the same place as another given | |
149 marker. | |
150 | |
53036
8383c6d510e2
(Creating Markers): Specify insertion type of created markers. Add
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
151 The next four functions all return markers with insertion type |
8383c6d510e2
(Creating Markers): Specify insertion type of created markers. Add
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
152 @code{nil}. @xref{Marker Insertion Types}. |
8383c6d510e2
(Creating Markers): Specify insertion type of created markers. Add
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
153 |
6444 | 154 @defun make-marker |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
155 This function returns a newly created marker that does not point |
6444 | 156 anywhere. |
157 | |
158 @example | |
159 @group | |
160 (make-marker) | |
161 @result{} #<marker in no buffer> | |
162 @end group | |
163 @end example | |
164 @end defun | |
165 | |
166 @defun point-marker | |
167 This function returns a new marker that points to the present position | |
168 of point in the current buffer. @xref{Point}. For an example, see | |
169 @code{copy-marker}, below. | |
170 @end defun | |
171 | |
172 @defun point-min-marker | |
173 This function returns a new marker that points to the beginning of the | |
174 accessible portion of the buffer. This will be the beginning of the | |
175 buffer unless narrowing is in effect. @xref{Narrowing}. | |
176 @end defun | |
177 | |
178 @defun point-max-marker | |
179 @cindex end of buffer marker | |
180 This function returns a new marker that points to the end of the | |
181 accessible portion of the buffer. This will be the end of the buffer | |
182 unless narrowing is in effect. @xref{Narrowing}. | |
183 | |
184 Here are examples of this function and @code{point-min-marker}, shown in | |
185 a buffer containing a version of the source file for the text of this | |
186 chapter. | |
187 | |
188 @example | |
189 @group | |
190 (point-min-marker) | |
191 @result{} #<marker at 1 in markers.texi> | |
192 (point-max-marker) | |
193 @result{} #<marker at 15573 in markers.texi> | |
194 @end group | |
195 | |
196 @group | |
197 (narrow-to-region 100 200) | |
198 @result{} nil | |
199 @end group | |
200 @group | |
201 (point-min-marker) | |
202 @result{} #<marker at 100 in markers.texi> | |
203 @end group | |
204 @group | |
205 (point-max-marker) | |
206 @result{} #<marker at 200 in markers.texi> | |
207 @end group | |
208 @end example | |
209 @end defun | |
210 | |
53036
8383c6d510e2
(Creating Markers): Specify insertion type of created markers. Add
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
211 @defun copy-marker marker-or-integer &optional insertion-type |
6444 | 212 If passed a marker as its argument, @code{copy-marker} returns a |
213 new marker that points to the same place and the same buffer as does | |
214 @var{marker-or-integer}. If passed an integer as its argument, | |
215 @code{copy-marker} returns a new marker that points to position | |
216 @var{marker-or-integer} in the current buffer. | |
217 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
218 The new marker's insertion type is specified by the argument |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
219 @var{insertion-type}. @xref{Marker Insertion Types}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
220 |
6444 | 221 If passed an integer argument less than 1, @code{copy-marker} returns a |
222 new marker that points to the beginning of the current buffer. If | |
223 passed an integer argument greater than the length of the buffer, | |
224 @code{copy-marker} returns a new marker that points to the end of the | |
225 buffer. | |
226 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
227 @example |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
228 @group |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
229 (copy-marker 0) |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
230 @result{} #<marker at 1 in markers.texi> |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
231 @end group |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
232 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
233 @group |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
234 (copy-marker 20000) |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
235 @result{} #<marker at 7572 in markers.texi> |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
236 @end group |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
237 @end example |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
238 |
6444 | 239 An error is signaled if @var{marker} is neither a marker nor an |
240 integer. | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
241 @end defun |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
242 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
243 Two distinct markers are considered @code{equal} (even though not |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
244 @code{eq}) to each other if they have the same position and buffer, or |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
245 if they both point nowhere. |
6444 | 246 |
247 @example | |
248 @group | |
249 (setq p (point-marker)) | |
250 @result{} #<marker at 2139 in markers.texi> | |
251 @end group | |
252 | |
253 @group | |
254 (setq q (copy-marker p)) | |
255 @result{} #<marker at 2139 in markers.texi> | |
256 @end group | |
257 | |
258 @group | |
259 (eq p q) | |
260 @result{} nil | |
261 @end group | |
262 | |
263 @group | |
264 (equal p q) | |
265 @result{} t | |
266 @end group | |
267 @end example | |
268 | |
269 @node Information from Markers | |
270 @section Information from Markers | |
271 | |
272 This section describes the functions for accessing the components of a | |
273 marker object. | |
274 | |
275 @defun marker-position marker | |
276 This function returns the position that @var{marker} points to, or | |
277 @code{nil} if it points nowhere. | |
278 @end defun | |
279 | |
280 @defun marker-buffer marker | |
281 This function returns the buffer that @var{marker} points into, or | |
282 @code{nil} if it points nowhere. | |
283 | |
284 @example | |
285 @group | |
286 (setq m (make-marker)) | |
287 @result{} #<marker in no buffer> | |
288 @end group | |
289 @group | |
290 (marker-position m) | |
291 @result{} nil | |
292 @end group | |
293 @group | |
294 (marker-buffer m) | |
295 @result{} nil | |
296 @end group | |
297 | |
298 @group | |
299 (set-marker m 3770 (current-buffer)) | |
300 @result{} #<marker at 3770 in markers.texi> | |
301 @end group | |
302 @group | |
303 (marker-buffer m) | |
304 @result{} #<buffer markers.texi> | |
305 @end group | |
306 @group | |
307 (marker-position m) | |
308 @result{} 3770 | |
309 @end group | |
310 @end example | |
311 @end defun | |
312 | |
26181 | 313 @defun buffer-has-markers-at position |
314 This function returns @code{t} if one or more markers | |
315 point at position @var{position} in the current buffer. | |
316 @end defun | |
317 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
318 @node Marker Insertion Types |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
319 @section Marker Insertion Types |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
320 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
321 @cindex insertion type of a marker |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
322 When you insert text directly at the place where a marker points, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
323 there are two possible ways to relocate that marker: it can point before |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
324 the inserted text, or point after it. You can specify which one a given |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
325 marker should do by setting its @dfn{insertion type}. Note that use of |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
326 @code{insert-before-markers} ignores markers' insertion types, always |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
327 relocating a marker to point after the inserted text. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
328 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
329 @defun set-marker-insertion-type marker type |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
330 This function sets the insertion type of marker @var{marker} to |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
331 @var{type}. If @var{type} is @code{t}, @var{marker} will advance when |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
332 text is inserted at its position. If @var{type} is @code{nil}, |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
333 @var{marker} does not advance when text is inserted there. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
334 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
335 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
336 @defun marker-insertion-type marker |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
337 This function reports the current insertion type of @var{marker}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
338 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
339 |
54211
f8a2c975db26
(Marker Insertion Types): Minor change.
Luc Teirlinck <teirllm@auburn.edu>
parents:
54063
diff
changeset
|
340 Most functions that create markers, without an argument allowing to |
f8a2c975db26
(Marker Insertion Types): Minor change.
Luc Teirlinck <teirllm@auburn.edu>
parents:
54063
diff
changeset
|
341 specify the insertion type, create them with insertion type |
f8a2c975db26
(Marker Insertion Types): Minor change.
Luc Teirlinck <teirllm@auburn.edu>
parents:
54063
diff
changeset
|
342 @code{nil}. Also, the mark has, by default, insertion type |
f8a2c975db26
(Marker Insertion Types): Minor change.
Luc Teirlinck <teirllm@auburn.edu>
parents:
54063
diff
changeset
|
343 @code{nil}. |
54063
3e2d6f6c8e51
(Marker Insertion Types): Minor change.
Luc Teirlinck <teirllm@auburn.edu>
parents:
53104
diff
changeset
|
344 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
345 @node Moving Markers |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
346 @section Moving Marker Positions |
6444 | 347 |
348 This section describes how to change the position of an existing | |
349 marker. When you do this, be sure you know whether the marker is used | |
350 outside of your program, and, if so, what effects will result from | |
351 moving it---otherwise, confusing things may happen in other parts of | |
352 Emacs. | |
353 | |
354 @defun set-marker marker position &optional buffer | |
355 This function moves @var{marker} to @var{position} | |
356 in @var{buffer}. If @var{buffer} is not provided, it defaults to | |
357 the current buffer. | |
358 | |
359 If @var{position} is less than 1, @code{set-marker} moves @var{marker} | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
360 to the beginning of the buffer. If @var{position} is greater than the |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
361 size of the buffer, @code{set-marker} moves marker to the end of the |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
362 buffer. If @var{position} is @code{nil} or a marker that points |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
363 nowhere, then @var{marker} is set to point nowhere. |
6444 | 364 |
365 The value returned is @var{marker}. | |
366 | |
367 @example | |
368 @group | |
369 (setq m (point-marker)) | |
370 @result{} #<marker at 4714 in markers.texi> | |
371 @end group | |
372 @group | |
373 (set-marker m 55) | |
374 @result{} #<marker at 55 in markers.texi> | |
375 @end group | |
376 @group | |
377 (setq b (get-buffer "foo")) | |
378 @result{} #<buffer foo> | |
379 @end group | |
380 @group | |
381 (set-marker m 0 b) | |
382 @result{} #<marker at 1 in foo> | |
383 @end group | |
384 @end example | |
385 @end defun | |
386 | |
387 @defun move-marker marker position &optional buffer | |
388 This is another name for @code{set-marker}. | |
389 @end defun | |
390 | |
391 @node The Mark | |
392 @section The Mark | |
393 @cindex mark, the | |
394 @cindex mark ring | |
395 | |
396 One special marker in each buffer is designated @dfn{the mark}. It | |
60268 | 397 specifies a position to bound a range of text for commands such as |
398 @code{kill-region} and @code{indent-rigidly}. Lisp programs should | |
399 set the mark only to values that have a potential use to the user, and | |
400 never for their own internal purposes. For example, the | |
401 @code{replace-regexp} command sets the mark to the value of point | |
402 before doing any replacements, because this enables the user to move | |
403 back there conveniently after the replace is finished. | |
6444 | 404 |
60268 | 405 Many commands are designed to operate on the text between point and |
406 the mark when called interactively. If you are writing such a | |
407 command, don't examine the mark directly; instead, use | |
6444 | 408 @code{interactive} with the @samp{r} specification. This provides the |
409 values of point and the mark as arguments to the command in an | |
410 interactive call, but permits other Lisp programs to specify arguments | |
411 explicitly. @xref{Interactive Codes}. | |
412 | |
413 Each buffer has its own value of the mark that is independent of the | |
414 value of the mark in other buffers. When a buffer is created, the mark | |
415 exists but does not point anywhere. We consider this state as ``the | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
416 absence of a mark in that buffer.'' |
6444 | 417 |
418 Once the mark ``exists'' in a buffer, it normally never ceases to | |
419 exist. However, it may become @dfn{inactive}, if Transient Mark mode is | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
420 enabled. The variable @code{mark-active}, which is always buffer-local |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
421 in all buffers, indicates whether the mark is active: non-@code{nil} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
422 means yes. A command can request deactivation of the mark upon return |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
423 to the editor command loop by setting @code{deactivate-mark} to a |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
424 non-@code{nil} value (but this causes deactivation only if Transient |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
425 Mark mode is enabled). |
6444 | 426 |
427 The main motivation for using Transient Mark mode is that this mode | |
428 also enables highlighting of the region when the mark is active. | |
429 @xref{Display}. | |
430 | |
431 In addition to the mark, each buffer has a @dfn{mark ring} which is a | |
432 list of markers containing previous values of the mark. When editing | |
433 commands change the mark, they should normally save the old value of the | |
434 mark on the mark ring. The variable @code{mark-ring-max} specifies the | |
435 maximum number of entries in the mark ring; once the list becomes this | |
436 long, adding a new element deletes the last element. | |
437 | |
26181 | 438 There is also a separate global mark ring, but that is used only in a |
439 few particular user-level commands, and is not relevant to Lisp | |
440 programming. So we do not describe it here. | |
441 | |
6444 | 442 @defun mark &optional force |
443 @cindex current buffer mark | |
68044
39029da4541b
(The Mark): Fix in `mark'.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
444 This function returns the current buffer's mark position as an integer, |
39029da4541b
(The Mark): Fix in `mark'.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
445 or @code{nil} if no mark has ever been set in this buffer. |
6444 | 446 |
68044
39029da4541b
(The Mark): Fix in `mark'.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
447 If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is |
39029da4541b
(The Mark): Fix in `mark'.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
448 @code{nil}, @code{mark} signals an error if the mark is inactive. |
39029da4541b
(The Mark): Fix in `mark'.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
449 However, if @var{force} is non-@code{nil}, then @code{mark} disregards |
39029da4541b
(The Mark): Fix in `mark'.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
450 inactivity of the mark, and returns the mark position anyway (or |
39029da4541b
(The Mark): Fix in `mark'.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
451 @code{nil}). |
6444 | 452 @end defun |
453 | |
454 @defun mark-marker | |
455 This function returns the current buffer's mark. This is the very marker | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
456 that records the mark location inside Emacs, not a copy. Therefore, |
6444 | 457 changing this marker's position will directly affect the position of the mark. |
458 Don't do it unless that is the effect you want. | |
459 | |
460 @example | |
461 @group | |
462 (setq m (mark-marker)) | |
463 @result{} #<marker at 3420 in markers.texi> | |
464 @end group | |
465 @group | |
466 (set-marker m 100) | |
467 @result{} #<marker at 100 in markers.texi> | |
468 @end group | |
469 @group | |
470 (mark-marker) | |
471 @result{} #<marker at 100 in markers.texi> | |
472 @end group | |
473 @end example | |
474 | |
475 Like any marker, this marker can be set to point at any buffer you like. | |
476 We don't recommend that you make it point at any buffer other than the | |
477 one of which it is the mark. If you do, it will yield perfectly | |
478 consistent, but rather odd, results. | |
479 @end defun | |
480 | |
481 @ignore | |
482 @deffn Command set-mark-command jump | |
483 If @var{jump} is @code{nil}, this command sets the mark to the value | |
484 of point and pushes the previous value of the mark on the mark ring. The | |
485 message @samp{Mark set} is also displayed in the echo area. | |
486 | |
487 If @var{jump} is not @code{nil}, this command sets point to the value | |
488 of the mark, and sets the mark to the previous saved mark value, which | |
489 is popped off the mark ring. | |
490 | |
491 This function is @emph{only} intended for interactive use. | |
492 @end deffn | |
493 @end ignore | |
494 | |
495 @defun set-mark position | |
496 This function sets the mark to @var{position}, and activates the mark. | |
497 The old value of the mark is @emph{not} pushed onto the mark ring. | |
498 | |
7734 | 499 @strong{Please note:} Use this function only if you want the user to |
6444 | 500 see that the mark has moved, and you want the previous mark position to |
501 be lost. Normally, when a new mark is set, the old one should go on the | |
502 @code{mark-ring}. For this reason, most applications should use | |
503 @code{push-mark} and @code{pop-mark}, not @code{set-mark}. | |
504 | |
505 Novice Emacs Lisp programmers often try to use the mark for the wrong | |
506 purposes. The mark saves a location for the user's convenience. An | |
507 editing command should not alter the mark unless altering the mark is | |
508 part of the user-level functionality of the command. (And, in that | |
509 case, this effect should be documented.) To remember a location for | |
510 internal use in the Lisp program, store it in a Lisp variable. For | |
511 example: | |
512 | |
513 @example | |
514 @group | |
515 (let ((beg (point))) | |
516 (forward-line 1) | |
517 (delete-region beg (point))). | |
518 @end group | |
519 @end example | |
520 @end defun | |
521 | |
522 @c for interactive use only | |
523 @ignore | |
524 @deffn Command exchange-point-and-mark | |
525 This function exchanges the positions of point and the mark. | |
526 It is intended for interactive use. | |
527 @end deffn | |
528 @end ignore | |
529 | |
530 @defun push-mark &optional position nomsg activate | |
531 This function sets the current buffer's mark to @var{position}, and | |
532 pushes a copy of the previous mark onto @code{mark-ring}. If | |
533 @var{position} is @code{nil}, then the value of point is used. | |
534 @code{push-mark} returns @code{nil}. | |
535 | |
536 The function @code{push-mark} normally @emph{does not} activate the | |
537 mark. To do that, specify @code{t} for the argument @var{activate}. | |
538 | |
539 A @samp{Mark set} message is displayed unless @var{nomsg} is | |
540 non-@code{nil}. | |
541 @end defun | |
542 | |
543 @defun pop-mark | |
544 This function pops off the top element of @code{mark-ring} and makes | |
545 that mark become the buffer's actual mark. This does not move point in | |
546 the buffer, and it does nothing if @code{mark-ring} is empty. It | |
547 deactivates the mark. | |
548 | |
549 The return value is not meaningful. | |
550 @end defun | |
551 | |
552 @defopt transient-mark-mode | |
553 @cindex Transient Mark mode | |
12098 | 554 This variable if non-@code{nil} enables Transient Mark mode, in which |
555 every buffer-modifying primitive sets @code{deactivate-mark}. The | |
556 consequence of this is that commands that modify the buffer normally | |
557 make the mark inactive. | |
60959
06ac4b1ff2ab
(The Mark): Document temporary Transient Mark mode.
Richard M. Stallman <rms@gnu.org>
parents:
60268
diff
changeset
|
558 |
06ac4b1ff2ab
(The Mark): Document temporary Transient Mark mode.
Richard M. Stallman <rms@gnu.org>
parents:
60268
diff
changeset
|
559 Lisp programs can set @code{transient-mark-mode} to @code{only} to |
06ac4b1ff2ab
(The Mark): Document temporary Transient Mark mode.
Richard M. Stallman <rms@gnu.org>
parents:
60268
diff
changeset
|
560 enable Transient Mark mode for the following command only. During |
63682
701e28d85125
(The Mark): Texinfo usage fix.
Juanma Barranquero <lekktu@gmail.com>
parents:
60959
diff
changeset
|
561 that following command, the value of @code{transient-mark-mode} is |
60959
06ac4b1ff2ab
(The Mark): Document temporary Transient Mark mode.
Richard M. Stallman <rms@gnu.org>
parents:
60268
diff
changeset
|
562 @code{identity}. If it is still @code{identity} at the end of the |
63682
701e28d85125
(The Mark): Texinfo usage fix.
Juanma Barranquero <lekktu@gmail.com>
parents:
60959
diff
changeset
|
563 command, it changes to @code{nil}. |
6444 | 564 @end defopt |
565 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
566 @defopt mark-even-if-inactive |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
567 If this is non-@code{nil}, Lisp programs and the Emacs user can use the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
568 mark even when it is inactive. This option affects the behavior of |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
569 Transient Mark mode. When the option is non-@code{nil}, deactivation of |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
570 the mark turns off region highlighting, but commands that use the mark |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
571 behave as if the mark were still active. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
572 @end defopt |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
573 |
6444 | 574 @defvar deactivate-mark |
575 If an editor command sets this variable non-@code{nil}, then the editor | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
576 command loop deactivates the mark after the command returns (if |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
577 Transient Mark mode is enabled). All the primitives that change the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
578 buffer set @code{deactivate-mark}, to deactivate the mark when the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
579 command is finished. |
46339
469cf4d8b62b
Document binding `deactivate-mark' around something that modifies the
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
580 |
469cf4d8b62b
Document binding `deactivate-mark' around something that modifies the
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
581 To write Lisp code that modifies the buffer without causing |
469cf4d8b62b
Document binding `deactivate-mark' around something that modifies the
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
582 deactivation of the mark at the end of the command, bind |
469cf4d8b62b
Document binding `deactivate-mark' around something that modifies the
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
583 @code{deactivate-mark} to @code{nil} around the code that does the |
469cf4d8b62b
Document binding `deactivate-mark' around something that modifies the
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
584 modification. For example: |
469cf4d8b62b
Document binding `deactivate-mark' around something that modifies the
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
585 |
469cf4d8b62b
Document binding `deactivate-mark' around something that modifies the
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
586 @example |
469cf4d8b62b
Document binding `deactivate-mark' around something that modifies the
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
587 (let (deactivate-mark) |
469cf4d8b62b
Document binding `deactivate-mark' around something that modifies the
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
588 (insert " ")) |
469cf4d8b62b
Document binding `deactivate-mark' around something that modifies the
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
589 @end example |
6444 | 590 @end defvar |
591 | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
592 @defun deactivate-mark |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
593 This function deactivates the mark, if Transient Mark mode is enabled. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
594 Otherwise it does nothing. |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
595 @end defun |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
596 |
6444 | 597 @defvar mark-active |
598 The mark is active when this variable is non-@code{nil}. This variable | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
599 is always buffer-local in each buffer. |
6444 | 600 @end defvar |
601 | |
602 @defvar activate-mark-hook | |
603 @defvarx deactivate-mark-hook | |
604 These normal hooks are run, respectively, when the mark becomes active | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
605 and when it becomes inactive. The hook @code{activate-mark-hook} is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
606 also run at the end of a command if the mark is active and it is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
607 possible that the region may have changed. |
6444 | 608 @end defvar |
609 | |
610 @defvar mark-ring | |
611 The value of this buffer-local variable is the list of saved former | |
612 marks of the current buffer, most recent first. | |
613 | |
614 @example | |
615 @group | |
616 mark-ring | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
46339
diff
changeset
|
617 @result{} (#<marker at 11050 in markers.texi> |
6444 | 618 #<marker at 10832 in markers.texi> |
619 @dots{}) | |
620 @end group | |
621 @end example | |
622 @end defvar | |
623 | |
624 @defopt mark-ring-max | |
625 The value of this variable is the maximum size of @code{mark-ring}. If | |
626 more marks than this are pushed onto the @code{mark-ring}, | |
627 @code{push-mark} discards an old mark when it adds a new one. | |
628 @end defopt | |
629 | |
630 @node The Region | |
631 @section The Region | |
632 @cindex region, the | |
633 | |
634 The text between point and the mark is known as @dfn{the region}. | |
635 Various functions operate on text delimited by point and the mark, but | |
636 only those functions specifically related to the region itself are | |
637 described here. | |
638 | |
53036
8383c6d510e2
(Creating Markers): Specify insertion type of created markers. Add
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
639 The next two functions signal an error if the mark does not point |
8383c6d510e2
(Creating Markers): Specify insertion type of created markers. Add
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
640 anywhere. If Transient Mark mode is enabled and |
8383c6d510e2
(Creating Markers): Specify insertion type of created markers. Add
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
641 @code{mark-even-if-inactive} is @code{nil}, they also signal an error |
8383c6d510e2
(Creating Markers): Specify insertion type of created markers. Add
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
642 if the mark is inactive. |
8383c6d510e2
(Creating Markers): Specify insertion type of created markers. Add
Luc Teirlinck <teirllm@auburn.edu>
parents:
52401
diff
changeset
|
643 |
6444 | 644 @defun region-beginning |
645 This function returns the position of the beginning of the region (as | |
646 an integer). This is the position of either point or the mark, | |
647 whichever is smaller. | |
648 @end defun | |
649 | |
650 @defun region-end | |
651 This function returns the position of the end of the region (as an | |
652 integer). This is the position of either point or the mark, whichever is | |
653 larger. | |
654 @end defun | |
655 | |
656 Few programs need to use the @code{region-beginning} and | |
657 @code{region-end} functions. A command designed to operate on a region | |
658 should normally use @code{interactive} with the @samp{r} specification | |
659 to find the beginning and end of the region. This lets other Lisp | |
660 programs specify the bounds explicitly as arguments. (@xref{Interactive | |
661 Codes}.) | |
52401 | 662 |
663 @ignore | |
664 arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299 | |
665 @end ignore |