Mercurial > emacs
annotate doc/lispref/markers.texi @ 106508:8c836ea59444
* net/tramp.el (tramp-handle-insert-directory): Suppress error messages.
author | Michael Albinus <michael.albinus@gmx.de> |
---|---|
date | Wed, 09 Dec 2009 10:23:00 +0000 |
parents | 8f9899f50e02 |
children | 1d1d5d9bd884 |
rev | line source |
---|---|
84086 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, | |
100974 | 4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. |
84086 | 5 @c See the file elisp.texi for copying conditions. |
84116
0ba80d073e27
(setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents:
84086
diff
changeset
|
6 @setfilename ../../info/markers |
84086 | 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. | |
21 * Marker Insertion Types:: Two ways a marker can relocate when you | |
22 insert where it points. | |
23 * Moving Markers:: Moving the marker to a new buffer or position. | |
24 * The Mark:: How "the mark" is implemented with a marker. | |
25 * The Region:: How to access "the region". | |
26 @end menu | |
27 | |
28 @node Overview of Markers | |
29 @section Overview of Markers | |
30 | |
31 A marker specifies a buffer and a position in that buffer. The | |
32 marker can be used to represent a position in the functions that | |
33 require one, just as an integer could be used. In that case, the | |
34 marker's buffer is normally ignored. Of course, a marker used in this | |
35 way usually points to a position in the buffer that the function | |
36 operates on, but that is entirely the programmer's responsibility. | |
37 @xref{Positions}, for a complete description of positions. | |
38 | |
39 A marker has three attributes: the marker position, the marker | |
40 buffer, and the insertion type. The marker position is an integer | |
41 that is equivalent (at a given time) to the marker as a position in | |
42 that buffer. But the marker's position value can change often during | |
43 the life of the marker. Insertion and deletion of text in the buffer | |
44 relocate the marker. The idea is that a marker positioned between two | |
45 characters remains between those two characters despite insertion and | |
46 deletion elsewhere in the buffer. Relocation changes the integer | |
47 equivalent of the marker. | |
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 | |
52 text at the position of a marker normally leaves the marker either in | |
53 front of or after the new text, depending on the marker's @dfn{insertion | |
54 type} (@pxref{Marker Insertion Types})---unless the insertion is done | |
55 with @code{insert-before-markers} (@pxref{Insertion}). | |
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 | |
139 This function returns @code{t} if @var{object} is a number (either | |
140 integer or floating point) or a marker, @code{nil} otherwise. | |
141 @end defun | |
142 | |
143 @node Creating Markers | |
144 @section Functions that Create Markers | |
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 | |
151 The next four functions all return markers with insertion type | |
152 @code{nil}. @xref{Marker Insertion Types}. | |
153 | |
154 @defun make-marker | |
155 This function returns a newly created marker that does not point | |
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 This function returns a new marker that points to the end of the | |
180 accessible portion of the buffer. This will be the end of the buffer | |
181 unless narrowing is in effect. @xref{Narrowing}. | |
182 | |
183 Here are examples of this function and @code{point-min-marker}, shown in | |
184 a buffer containing a version of the source file for the text of this | |
185 chapter. | |
186 | |
187 @example | |
188 @group | |
189 (point-min-marker) | |
190 @result{} #<marker at 1 in markers.texi> | |
191 (point-max-marker) | |
192 @result{} #<marker at 15573 in markers.texi> | |
193 @end group | |
194 | |
195 @group | |
196 (narrow-to-region 100 200) | |
197 @result{} nil | |
198 @end group | |
199 @group | |
200 (point-min-marker) | |
201 @result{} #<marker at 100 in markers.texi> | |
202 @end group | |
203 @group | |
204 (point-max-marker) | |
205 @result{} #<marker at 200 in markers.texi> | |
206 @end group | |
207 @end example | |
208 @end defun | |
209 | |
210 @defun copy-marker marker-or-integer &optional insertion-type | |
211 If passed a marker as its argument, @code{copy-marker} returns a | |
212 new marker that points to the same place and the same buffer as does | |
213 @var{marker-or-integer}. If passed an integer as its argument, | |
214 @code{copy-marker} returns a new marker that points to position | |
215 @var{marker-or-integer} in the current buffer. | |
216 | |
217 The new marker's insertion type is specified by the argument | |
218 @var{insertion-type}. @xref{Marker Insertion Types}. | |
219 | |
220 If passed an integer argument less than 1, @code{copy-marker} returns a | |
221 new marker that points to the beginning of the current buffer. If | |
222 passed an integer argument greater than the length of the buffer, | |
223 @code{copy-marker} returns a new marker that points to the end of the | |
224 buffer. | |
225 | |
226 @example | |
227 @group | |
228 (copy-marker 0) | |
229 @result{} #<marker at 1 in markers.texi> | |
230 @end group | |
231 | |
232 @group | |
233 (copy-marker 20000) | |
234 @result{} #<marker at 7572 in markers.texi> | |
235 @end group | |
236 @end example | |
237 | |
238 An error is signaled if @var{marker} is neither a marker nor an | |
239 integer. | |
240 @end defun | |
241 | |
242 Two distinct markers are considered @code{equal} (even though not | |
243 @code{eq}) to each other if they have the same position and buffer, or | |
244 if they both point nowhere. | |
245 | |
246 @example | |
247 @group | |
248 (setq p (point-marker)) | |
249 @result{} #<marker at 2139 in markers.texi> | |
250 @end group | |
251 | |
252 @group | |
253 (setq q (copy-marker p)) | |
254 @result{} #<marker at 2139 in markers.texi> | |
255 @end group | |
256 | |
257 @group | |
258 (eq p q) | |
259 @result{} nil | |
260 @end group | |
261 | |
262 @group | |
263 (equal p q) | |
264 @result{} t | |
265 @end group | |
266 @end example | |
267 | |
268 @node Information from Markers | |
269 @section Information from Markers | |
270 | |
271 This section describes the functions for accessing the components of a | |
272 marker object. | |
273 | |
274 @defun marker-position marker | |
275 This function returns the position that @var{marker} points to, or | |
276 @code{nil} if it points nowhere. | |
277 @end defun | |
278 | |
279 @defun marker-buffer marker | |
280 This function returns the buffer that @var{marker} points into, or | |
281 @code{nil} if it points nowhere. | |
282 | |
283 @example | |
284 @group | |
285 (setq m (make-marker)) | |
286 @result{} #<marker in no buffer> | |
287 @end group | |
288 @group | |
289 (marker-position m) | |
290 @result{} nil | |
291 @end group | |
292 @group | |
293 (marker-buffer m) | |
294 @result{} nil | |
295 @end group | |
296 | |
297 @group | |
298 (set-marker m 3770 (current-buffer)) | |
299 @result{} #<marker at 3770 in markers.texi> | |
300 @end group | |
301 @group | |
302 (marker-buffer m) | |
303 @result{} #<buffer markers.texi> | |
304 @end group | |
305 @group | |
306 (marker-position m) | |
307 @result{} 3770 | |
308 @end group | |
309 @end example | |
310 @end defun | |
311 | |
312 @defun buffer-has-markers-at position | |
313 This function returns @code{t} if one or more markers | |
314 point at position @var{position} in the current buffer. | |
315 @end defun | |
316 | |
317 @node Marker Insertion Types | |
318 @section Marker Insertion Types | |
319 | |
320 @cindex insertion type of a marker | |
321 When you insert text directly at the place where a marker points, | |
322 there are two possible ways to relocate that marker: it can point before | |
323 the inserted text, or point after it. You can specify which one a given | |
324 marker should do by setting its @dfn{insertion type}. Note that use of | |
325 @code{insert-before-markers} ignores markers' insertion types, always | |
326 relocating a marker to point after the inserted text. | |
327 | |
328 @defun set-marker-insertion-type marker type | |
329 This function sets the insertion type of marker @var{marker} to | |
330 @var{type}. If @var{type} is @code{t}, @var{marker} will advance when | |
331 text is inserted at its position. If @var{type} is @code{nil}, | |
332 @var{marker} does not advance when text is inserted there. | |
333 @end defun | |
334 | |
335 @defun marker-insertion-type marker | |
336 This function reports the current insertion type of @var{marker}. | |
337 @end defun | |
338 | |
339 Most functions that create markers, without an argument allowing to | |
340 specify the insertion type, create them with insertion type | |
341 @code{nil}. Also, the mark has, by default, insertion type | |
342 @code{nil}. | |
343 | |
344 @node Moving Markers | |
345 @section Moving Marker Positions | |
346 | |
347 This section describes how to change the position of an existing | |
348 marker. When you do this, be sure you know whether the marker is used | |
349 outside of your program, and, if so, what effects will result from | |
350 moving it---otherwise, confusing things may happen in other parts of | |
351 Emacs. | |
352 | |
353 @defun set-marker marker position &optional buffer | |
354 This function moves @var{marker} to @var{position} | |
355 in @var{buffer}. If @var{buffer} is not provided, it defaults to | |
356 the current buffer. | |
357 | |
358 If @var{position} is less than 1, @code{set-marker} moves @var{marker} | |
359 to the beginning of the buffer. If @var{position} is greater than the | |
360 size of the buffer, @code{set-marker} moves marker to the end of the | |
361 buffer. If @var{position} is @code{nil} or a marker that points | |
362 nowhere, then @var{marker} is set to point nowhere. | |
363 | |
364 The value returned is @var{marker}. | |
365 | |
366 @example | |
367 @group | |
368 (setq m (point-marker)) | |
369 @result{} #<marker at 4714 in markers.texi> | |
370 @end group | |
371 @group | |
372 (set-marker m 55) | |
373 @result{} #<marker at 55 in markers.texi> | |
374 @end group | |
375 @group | |
376 (setq b (get-buffer "foo")) | |
377 @result{} #<buffer foo> | |
378 @end group | |
379 @group | |
380 (set-marker m 0 b) | |
381 @result{} #<marker at 1 in foo> | |
382 @end group | |
383 @end example | |
384 @end defun | |
385 | |
386 @defun move-marker marker position &optional buffer | |
387 This is another name for @code{set-marker}. | |
388 @end defun | |
389 | |
390 @node The Mark | |
391 @section The Mark | |
392 @cindex mark, the | |
393 @cindex mark ring | |
394 | |
102855
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
395 Each buffer has a special marker, which is designated @dfn{the |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
396 mark}. When a buffer is newly created, this marker exists but does |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
397 not point anywhere; this means that the mark ``doesn't exist'' in that |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
398 buffer yet. Subsequent commands can set the mark. |
84086 | 399 |
102855
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
400 The mark specifies a position to bound a range of text for many |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
401 commands, such as @code{kill-region} and @code{indent-rigidly}. These |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
402 commands typically act on the text between point and the mark, which |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
403 is called the @dfn{region}. If you are writing a command that |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
404 operates on the region, don't examine the mark directly; instead, use |
84086 | 405 @code{interactive} with the @samp{r} specification. This provides the |
406 values of point and the mark as arguments to the command in an | |
407 interactive call, but permits other Lisp programs to specify arguments | |
408 explicitly. @xref{Interactive Codes}. | |
409 | |
102855
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
410 Some commands set the mark as a side-effect. Commands should do |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
411 this only if it has a potential use to the user, and never for their |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
412 own internal purposes. For example, the @code{replace-regexp} command |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
413 sets the mark to the value of point before doing any replacements, |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
414 because this enables the user to move back there conveniently after |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
415 the replace is finished. |
84086 | 416 |
417 Once the mark ``exists'' in a buffer, it normally never ceases to | |
102855
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
418 exist. However, it may become @dfn{inactive}, if Transient Mark mode |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
419 is enabled. The buffer-local variable @code{mark-active}, if |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
420 non-@code{nil}, means that the mark is active. A command can call the |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
421 function @code{deactivate-mark} to deactivate the mark directly, or it |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
422 can request deactivation of the mark upon return to the editor command |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
423 loop by setting the variable @code{deactivate-mark} to a |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
424 non-@code{nil} value. |
84086 | 425 |
102855
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
426 If Transient Mode is enabled, certain editing commands that normally |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
427 apply to text near point, apply instead to the region when the mark is |
98784
ae2c057fb447
(The Mark): Document use-region-p.
Eli Zaretskii <eliz@gnu.org>
parents:
98762
diff
changeset
|
428 active. This is the main motivation for using Transient Mark mode. |
102855
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
429 (Another is that this enables highlighting of the region when the mark |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
430 is active. @xref{Display}.) |
84086 | 431 |
432 In addition to the mark, each buffer has a @dfn{mark ring} which is a | |
433 list of markers containing previous values of the mark. When editing | |
434 commands change the mark, they should normally save the old value of the | |
435 mark on the mark ring. The variable @code{mark-ring-max} specifies the | |
436 maximum number of entries in the mark ring; once the list becomes this | |
437 long, adding a new element deletes the last element. | |
438 | |
439 There is also a separate global mark ring, but that is used only in a | |
440 few particular user-level commands, and is not relevant to Lisp | |
441 programming. So we do not describe it here. | |
442 | |
443 @defun mark &optional force | |
444 @cindex current buffer mark | |
445 This function returns the current buffer's mark position as an integer, | |
446 or @code{nil} if no mark has ever been set in this buffer. | |
447 | |
448 If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is | |
449 @code{nil}, @code{mark} signals an error if the mark is inactive. | |
450 However, if @var{force} is non-@code{nil}, then @code{mark} disregards | |
102855
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
451 inactivity of the mark, and returns the mark position (or @code{nil}) |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
452 anyway. |
84086 | 453 @end defun |
454 | |
455 @defun mark-marker | |
456 This function returns the marker that represents the current buffer's | |
457 mark. It is not a copy, it is the marker used internally. Therefore, | |
458 changing this marker's position will directly affect the buffer's | |
459 mark. Don't do that unless that is the effect you want. | |
460 | |
461 @example | |
462 @group | |
463 (setq m (mark-marker)) | |
464 @result{} #<marker at 3420 in markers.texi> | |
465 @end group | |
466 @group | |
467 (set-marker m 100) | |
468 @result{} #<marker at 100 in markers.texi> | |
469 @end group | |
470 @group | |
471 (mark-marker) | |
472 @result{} #<marker at 100 in markers.texi> | |
473 @end group | |
474 @end example | |
475 | |
476 Like any marker, this marker can be set to point at any buffer you | |
477 like. If you make it point at any buffer other than the one of which | |
478 it is the mark, it will yield perfectly consistent, but rather odd, | |
479 results. We recommend that you not do it! | |
480 @end defun | |
481 | |
482 @defun set-mark position | |
483 This function sets the mark to @var{position}, and activates the mark. | |
484 The old value of the mark is @emph{not} pushed onto the mark ring. | |
485 | |
486 @strong{Please note:} Use this function only if you want the user to | |
487 see that the mark has moved, and you want the previous mark position to | |
488 be lost. Normally, when a new mark is set, the old one should go on the | |
489 @code{mark-ring}. For this reason, most applications should use | |
490 @code{push-mark} and @code{pop-mark}, not @code{set-mark}. | |
491 | |
492 Novice Emacs Lisp programmers often try to use the mark for the wrong | |
493 purposes. The mark saves a location for the user's convenience. An | |
494 editing command should not alter the mark unless altering the mark is | |
495 part of the user-level functionality of the command. (And, in that | |
496 case, this effect should be documented.) To remember a location for | |
497 internal use in the Lisp program, store it in a Lisp variable. For | |
498 example: | |
499 | |
500 @example | |
501 @group | |
502 (let ((beg (point))) | |
503 (forward-line 1) | |
504 (delete-region beg (point))). | |
505 @end group | |
506 @end example | |
507 @end defun | |
508 | |
509 @defun push-mark &optional position nomsg activate | |
510 This function sets the current buffer's mark to @var{position}, and | |
511 pushes a copy of the previous mark onto @code{mark-ring}. If | |
512 @var{position} is @code{nil}, then the value of point is used. | |
513 @code{push-mark} returns @code{nil}. | |
514 | |
515 The function @code{push-mark} normally @emph{does not} activate the | |
516 mark. To do that, specify @code{t} for the argument @var{activate}. | |
517 | |
518 A @samp{Mark set} message is displayed unless @var{nomsg} is | |
519 non-@code{nil}. | |
520 @end defun | |
521 | |
522 @defun pop-mark | |
523 This function pops off the top element of @code{mark-ring} and makes | |
524 that mark become the buffer's actual mark. This does not move point in | |
525 the buffer, and it does nothing if @code{mark-ring} is empty. It | |
526 deactivates the mark. | |
527 | |
528 The return value is not meaningful. | |
529 @end defun | |
530 | |
531 @defopt transient-mark-mode | |
102855
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
532 This variable, if non-@code{nil}, enables Transient Mark mode. In |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
533 Transient Mark mode, every buffer-modifying primitive sets |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
534 @code{deactivate-mark}. As a consequence, most commands that modify |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
535 the buffer also deactivate the mark. |
84086 | 536 |
102855
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
537 When Transient Mark mode is enabled and the mark is active, many |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
538 commands that normally apply to the text near point instead apply to |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
539 the region. Such commands should use the function @code{use-region-p} |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
540 to test whether they should operate on the region. @xref{The Region}. |
98784
ae2c057fb447
(The Mark): Document use-region-p.
Eli Zaretskii <eliz@gnu.org>
parents:
98762
diff
changeset
|
541 |
98752
1d0213f6230f
(The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
542 Lisp programs can set @code{transient-mark-mode} to non-@code{nil}, |
1d0213f6230f
(The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
543 non-@code{t} values to enable Transient Mark mode temporarily. If the |
98762
ef39b163f82b
(The Mark): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents:
98752
diff
changeset
|
544 value is @code{lambda}, Transient Mark mode is automatically turned |
98752
1d0213f6230f
(The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
545 off after any action, such as buffer modification, that would normally |
1d0213f6230f
(The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
546 deactivate the mark. If the value is @w{@code{(only . @var{oldval})}}, |
1d0213f6230f
(The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
547 then @code{transient-mark-mode} is set to the value @var{oldval} after |
1d0213f6230f
(The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
548 any subsequent command that moves point and is not shift-translated |
1d0213f6230f
(The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
549 (@pxref{Key Sequence Input, shift-translation}), or after any other |
1d0213f6230f
(The Mark): Document the `lambda' and `(only . OLD)' values of
Eli Zaretskii <eliz@gnu.org>
parents:
87649
diff
changeset
|
550 action that would normally deactivate the mark. |
84086 | 551 @end defopt |
552 | |
553 @defopt mark-even-if-inactive | |
554 If this is non-@code{nil}, Lisp programs and the Emacs user can use the | |
555 mark even when it is inactive. This option affects the behavior of | |
556 Transient Mark mode. When the option is non-@code{nil}, deactivation of | |
557 the mark turns off region highlighting, but commands that use the mark | |
558 behave as if the mark were still active. | |
559 @end defopt | |
560 | |
561 @defvar deactivate-mark | |
562 If an editor command sets this variable non-@code{nil}, then the editor | |
563 command loop deactivates the mark after the command returns (if | |
564 Transient Mark mode is enabled). All the primitives that change the | |
565 buffer set @code{deactivate-mark}, to deactivate the mark when the | |
566 command is finished. | |
567 | |
568 To write Lisp code that modifies the buffer without causing | |
569 deactivation of the mark at the end of the command, bind | |
570 @code{deactivate-mark} to @code{nil} around the code that does the | |
571 modification. For example: | |
572 | |
573 @example | |
574 (let (deactivate-mark) | |
575 (insert " ")) | |
576 @end example | |
577 @end defvar | |
578 | |
103894
60606ee8aee7
* markers.texi (The Mark): Document optional arg to deactivate-mark.
Chong Yidong <cyd@stupidchicken.com>
parents:
102855
diff
changeset
|
579 @defun deactivate-mark &optional force |
103895
8f9899f50e02
Clarify last change.
Chong Yidong <cyd@stupidchicken.com>
parents:
103894
diff
changeset
|
580 If Transient Mark mode is enabled or @var{force} is non-@code{nil}, |
8f9899f50e02
Clarify last change.
Chong Yidong <cyd@stupidchicken.com>
parents:
103894
diff
changeset
|
581 this function deactivates the mark and runs the normal hook |
8f9899f50e02
Clarify last change.
Chong Yidong <cyd@stupidchicken.com>
parents:
103894
diff
changeset
|
582 @code{deactivate-mark-hook}. Otherwise, it does nothing. |
84086 | 583 @end defun |
584 | |
585 @defvar mark-active | |
98784
ae2c057fb447
(The Mark): Document use-region-p.
Eli Zaretskii <eliz@gnu.org>
parents:
98762
diff
changeset
|
586 The mark is active when this variable is non-@code{nil}. This |
ae2c057fb447
(The Mark): Document use-region-p.
Eli Zaretskii <eliz@gnu.org>
parents:
98762
diff
changeset
|
587 variable is always buffer-local in each buffer. Do @emph{not} use the |
ae2c057fb447
(The Mark): Document use-region-p.
Eli Zaretskii <eliz@gnu.org>
parents:
98762
diff
changeset
|
588 value of this variable to decide whether a command that normally |
ae2c057fb447
(The Mark): Document use-region-p.
Eli Zaretskii <eliz@gnu.org>
parents:
98762
diff
changeset
|
589 operates on text near point should operate on the region instead. Use |
102855
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
590 the function @code{use-region-p} for that (@pxref{The Region}). |
84086 | 591 @end defvar |
592 | |
593 @defvar activate-mark-hook | |
594 @defvarx deactivate-mark-hook | |
595 These normal hooks are run, respectively, when the mark becomes active | |
596 and when it becomes inactive. The hook @code{activate-mark-hook} is | |
597 also run at the end of a command if the mark is active and it is | |
598 possible that the region may have changed. | |
599 @end defvar | |
600 | |
102855
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
601 @defun handle-shift-selection |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
602 This function implements the ``shift-selection'' behavior of |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
603 point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
604 Manual}. It is called automatically by the Emacs command loop |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
605 whenever a command with a @samp{^} character in its @code{interactive} |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
606 spec is invoked, before the command itself is executed |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
607 (@pxref{Interactive Codes, ^}). |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
608 |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
609 If @code{shift-select-mode} is non-@code{nil} and the current command |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
610 was invoked via shift translation (@pxref{Key Sequence Input, |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
611 shift-translation}), this function sets the mark and temporarily |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
612 activates the region, unless the region was already temporarily |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
613 activated in this way. Otherwise, if the region has been activated |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
614 temporarily, it deactivates the mark and restores the variable |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
615 @code{transient-mark-mode} to its earlier value. |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
616 @end defun |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
617 |
84086 | 618 @defvar mark-ring |
619 The value of this buffer-local variable is the list of saved former | |
620 marks of the current buffer, most recent first. | |
621 | |
622 @example | |
623 @group | |
624 mark-ring | |
625 @result{} (#<marker at 11050 in markers.texi> | |
626 #<marker at 10832 in markers.texi> | |
627 @dots{}) | |
628 @end group | |
629 @end example | |
630 @end defvar | |
631 | |
632 @defopt mark-ring-max | |
633 The value of this variable is the maximum size of @code{mark-ring}. If | |
634 more marks than this are pushed onto the @code{mark-ring}, | |
635 @code{push-mark} discards an old mark when it adds a new one. | |
636 @end defopt | |
637 | |
638 @node The Region | |
639 @section The Region | |
640 @cindex region (between point and mark) | |
641 | |
642 The text between point and the mark is known as @dfn{the region}. | |
643 Various functions operate on text delimited by point and the mark, but | |
644 only those functions specifically related to the region itself are | |
645 described here. | |
646 | |
647 The next two functions signal an error if the mark does not point | |
648 anywhere. If Transient Mark mode is enabled and | |
649 @code{mark-even-if-inactive} is @code{nil}, they also signal an error | |
650 if the mark is inactive. | |
651 | |
652 @defun region-beginning | |
653 This function returns the position of the beginning of the region (as | |
654 an integer). This is the position of either point or the mark, | |
655 whichever is smaller. | |
656 @end defun | |
657 | |
658 @defun region-end | |
659 This function returns the position of the end of the region (as an | |
660 integer). This is the position of either point or the mark, whichever is | |
661 larger. | |
662 @end defun | |
663 | |
664 Few programs need to use the @code{region-beginning} and | |
665 @code{region-end} functions. A command designed to operate on a region | |
666 should normally use @code{interactive} with the @samp{r} specification | |
667 to find the beginning and end of the region. This lets other Lisp | |
668 programs specify the bounds explicitly as arguments. (@xref{Interactive | |
669 Codes}.) | |
670 | |
102855
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
671 @defun use-region-p |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
672 This function returns @code{t} if Transient Mark mode is enabled, the |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
673 mark is active, and there's a valid region in the buffer. Commands |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
674 that operate on the region (instead of on text near point) when |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
675 there's an active mark should use this to test whether to do that. |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
676 @end defun |
17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
Chong Yidong <cyd@stupidchicken.com>
parents:
102739
diff
changeset
|
677 |
84086 | 678 @ignore |
679 arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299 | |
680 @end ignore |