Mercurial > emacs
comparison lispref/markers.texi @ 6444:9cbdecc5a37d
Initial revision
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Sun, 20 Mar 1994 23:52:27 +0000 |
parents | |
children | a1c07008521d |
comparison
equal
deleted
inserted
replaced
6443:1d725a175387 | 6444:9cbdecc5a37d |
---|---|
1 @c -*-texinfo-*- | |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. | |
4 @c See the file elisp.texi for copying conditions. | |
5 @setfilename ../info/markers | |
6 @node Markers, Text, Positions, Top | |
7 @chapter Markers | |
8 @cindex markers | |
9 | |
10 A @dfn{marker} is a Lisp object used to specify a position in a buffer | |
11 relative to the surrounding text. A marker changes its offset from the | |
12 beginning of the buffer automatically whenever text is inserted or | |
13 deleted, so that it stays with the two characters on either side of it. | |
14 | |
15 @menu | |
16 * Overview of Markers:: The components of a marker, and how it relocates. | |
17 * Predicates on Markers:: Testing whether an object is a marker. | |
18 * Creating Markers:: Making empty markers or markers at certain places. | |
19 * Information from Markers:: Finding the marker's buffer or character position. | |
20 * Changing Markers:: Moving the marker to a new buffer or position. | |
21 * The Mark:: How ``the mark'' is implemented with a marker. | |
22 * The Region:: How to access ``the region''. | |
23 @end menu | |
24 | |
25 @node Overview of Markers | |
26 @section Overview of Markers | |
27 | |
28 A marker specifies a buffer and a position in that buffer. The marker | |
29 can be used to represent a position in the functions that require one, | |
30 just as an integer could be used. @xref{Positions}, for a complete | |
31 description of positions. | |
32 | |
33 A marker has two attributes: the marker position, and the marker | |
34 buffer. The marker position is an integer which is equivalent (at a | |
35 given time) to the marker as a position in that buffer. But the | |
36 marker's position value can change often during the life of the marker. | |
37 Insertion and deletion of text in the buffer relocate the marker. The | |
38 idea is that a marker positioned between two characters remains between | |
39 those two characters despite insertion and deletion elsewhere in the | |
40 buffer. Relocation changes the integer equivalent of the marker. | |
41 | |
42 @cindex marker relocation | |
43 Deleting text around a marker's position leaves the marker between the | |
44 characters immediately before and after the deleted text. Inserting | |
45 text at the position of a marker normally leaves the marker in front of | |
46 the new text---unless it is inserted with @code{insert-before-markers} | |
47 (@pxref{Insertion}). | |
48 | |
49 @cindex marker garbage collection | |
50 Insertion and deletion in a buffer must check all the markers and | |
51 relocate them if necessary. This slows processing in a buffer with a | |
52 large number of markers. For this reason, it is a good idea to make a | |
53 marker point nowhere if you are sure you don't need it any more. | |
54 Unreferenced markers are garbage collected eventually, but until then | |
55 will continue to use time if they do point somewhere. | |
56 | |
57 @cindex markers as numbers | |
58 Because it is common to perform arithmetic operations on a marker | |
59 position, most of the arithmetic operations (including @code{+} and | |
60 @code{-}) accept markers as arguments. In such cases, the marker | |
61 stands for its current position. | |
62 | |
63 Here are examples of creating markers, setting markers, and moving point | |
64 to markers: | |
65 | |
66 @example | |
67 @group | |
68 ;; @r{Make a new marker that initially does not point anywhere:} | |
69 (setq m1 (make-marker)) | |
70 @result{} #<marker in no buffer> | |
71 @end group | |
72 | |
73 @group | |
74 ;; @r{Set @code{m1} to point between the 99th and 100th characters} | |
75 ;; @r{in the current buffer:} | |
76 (set-marker m1 100) | |
77 @result{} #<marker at 100 in markers.texi> | |
78 @end group | |
79 | |
80 @group | |
81 ;; @r{Now insert one character at the beginning of the buffer:} | |
82 (goto-char (point-min)) | |
83 @result{} 1 | |
84 (insert "Q") | |
85 @result{} nil | |
86 @end group | |
87 | |
88 @group | |
89 ;; @r{@code{m1} is updated appropriately.} | |
90 m1 | |
91 @result{} #<marker at 101 in markers.texi> | |
92 @end group | |
93 | |
94 @group | |
95 ;; @r{Two markers that point to the same position} | |
96 ;; @r{are not @code{eq}, but they are @code{equal}.} | |
97 (setq m2 (copy-marker m1)) | |
98 @result{} #<marker at 101 in markers.texi> | |
99 (eq m1 m2) | |
100 @result{} nil | |
101 (equal m1 m2) | |
102 @result{} t | |
103 @end group | |
104 | |
105 @group | |
106 ;; @r{When you are finished using a marker, make it point nowhere.} | |
107 (set-marker m1 nil) | |
108 @result{} #<marker in no buffer> | |
109 @end group | |
110 @end example | |
111 | |
112 @node Predicates on Markers | |
113 @section Predicates on Markers | |
114 | |
115 You can test an object to see whether it is a marker, or whether it is | |
116 either an integer or a marker. The latter test is useful in connection | |
117 with the arithmetic functions that work with both markers and integers. | |
118 | |
119 @defun markerp object | |
120 This function returns @code{t} if @var{object} is a marker, @code{nil} | |
121 otherwise. Note that integers are not markers, even though many | |
122 functions will accept either a marker or an integer. | |
123 @end defun | |
124 | |
125 @defun integer-or-marker-p object | |
126 This function returns @code{t} if @var{object} is an integer or a marker, | |
127 @code{nil} otherwise. | |
128 @end defun | |
129 | |
130 @defun number-or-marker-p object | |
131 This function returns @code{t} if @var{object} is a number (either kind) | |
132 or a marker, @code{nil} otherwise. | |
133 @end defun | |
134 | |
135 @node Creating Markers | |
136 @section Functions That Create Markers | |
137 | |
138 When you create a new marker, you can make it point nowhere, or point | |
139 to the present position of point, or to the beginning or end of the | |
140 accessible portion of the buffer, or to the same place as another given | |
141 marker. | |
142 | |
143 @defun make-marker | |
144 This functions returns a newly allocated marker that does not point | |
145 anywhere. | |
146 | |
147 @example | |
148 @group | |
149 (make-marker) | |
150 @result{} #<marker in no buffer> | |
151 @end group | |
152 @end example | |
153 @end defun | |
154 | |
155 @defun point-marker | |
156 This function returns a new marker that points to the present position | |
157 of point in the current buffer. @xref{Point}. For an example, see | |
158 @code{copy-marker}, below. | |
159 @end defun | |
160 | |
161 @defun point-min-marker | |
162 This function returns a new marker that points to the beginning of the | |
163 accessible portion of the buffer. This will be the beginning of the | |
164 buffer unless narrowing is in effect. @xref{Narrowing}. | |
165 @end defun | |
166 | |
167 @defun point-max-marker | |
168 @cindex end of buffer marker | |
169 This function returns a new marker that points to the end of the | |
170 accessible portion of the buffer. This will be the end of the buffer | |
171 unless narrowing is in effect. @xref{Narrowing}. | |
172 | |
173 Here are examples of this function and @code{point-min-marker}, shown in | |
174 a buffer containing a version of the source file for the text of this | |
175 chapter. | |
176 | |
177 @example | |
178 @group | |
179 (point-min-marker) | |
180 @result{} #<marker at 1 in markers.texi> | |
181 (point-max-marker) | |
182 @result{} #<marker at 15573 in markers.texi> | |
183 @end group | |
184 | |
185 @group | |
186 (narrow-to-region 100 200) | |
187 @result{} nil | |
188 @end group | |
189 @group | |
190 (point-min-marker) | |
191 @result{} #<marker at 100 in markers.texi> | |
192 @end group | |
193 @group | |
194 (point-max-marker) | |
195 @result{} #<marker at 200 in markers.texi> | |
196 @end group | |
197 @end example | |
198 @end defun | |
199 | |
200 @defun copy-marker marker-or-integer | |
201 If passed a marker as its argument, @code{copy-marker} returns a | |
202 new marker that points to the same place and the same buffer as does | |
203 @var{marker-or-integer}. If passed an integer as its argument, | |
204 @code{copy-marker} returns a new marker that points to position | |
205 @var{marker-or-integer} in the current buffer. | |
206 | |
207 If passed an integer argument less than 1, @code{copy-marker} returns a | |
208 new marker that points to the beginning of the current buffer. If | |
209 passed an integer argument greater than the length of the buffer, | |
210 @code{copy-marker} returns a new marker that points to the end of the | |
211 buffer. | |
212 | |
213 An error is signaled if @var{marker} is neither a marker nor an | |
214 integer. | |
215 | |
216 @example | |
217 @group | |
218 (setq p (point-marker)) | |
219 @result{} #<marker at 2139 in markers.texi> | |
220 @end group | |
221 | |
222 @group | |
223 (setq q (copy-marker p)) | |
224 @result{} #<marker at 2139 in markers.texi> | |
225 @end group | |
226 | |
227 @group | |
228 (eq p q) | |
229 @result{} nil | |
230 @end group | |
231 | |
232 @group | |
233 (equal p q) | |
234 @result{} t | |
235 @end group | |
236 | |
237 @group | |
238 (copy-marker 0) | |
239 @result{} #<marker at 1 in markers.texi> | |
240 @end group | |
241 | |
242 @group | |
243 (copy-marker 20000) | |
244 @result{} #<marker at 7572 in markers.texi> | |
245 @end group | |
246 @end example | |
247 @end defun | |
248 | |
249 @node Information from Markers | |
250 @section Information from Markers | |
251 | |
252 This section describes the functions for accessing the components of a | |
253 marker object. | |
254 | |
255 @defun marker-position marker | |
256 This function returns the position that @var{marker} points to, or | |
257 @code{nil} if it points nowhere. | |
258 @end defun | |
259 | |
260 @defun marker-buffer marker | |
261 This function returns the buffer that @var{marker} points into, or | |
262 @code{nil} if it points nowhere. | |
263 | |
264 @example | |
265 @group | |
266 (setq m (make-marker)) | |
267 @result{} #<marker in no buffer> | |
268 @end group | |
269 @group | |
270 (marker-position m) | |
271 @result{} nil | |
272 @end group | |
273 @group | |
274 (marker-buffer m) | |
275 @result{} nil | |
276 @end group | |
277 | |
278 @group | |
279 (set-marker m 3770 (current-buffer)) | |
280 @result{} #<marker at 3770 in markers.texi> | |
281 @end group | |
282 @group | |
283 (marker-buffer m) | |
284 @result{} #<buffer markers.texi> | |
285 @end group | |
286 @group | |
287 (marker-position m) | |
288 @result{} 3770 | |
289 @end group | |
290 @end example | |
291 @end defun | |
292 | |
293 Two distinct markers are considered @code{equal} (even though not | |
294 @code{eq}) to each other if they have the same position and buffer, or | |
295 if they both point nowhere. | |
296 | |
297 @node Changing Markers | |
298 @section Changing Marker Positions | |
299 | |
300 This section describes how to change the position of an existing | |
301 marker. When you do this, be sure you know whether the marker is used | |
302 outside of your program, and, if so, what effects will result from | |
303 moving it---otherwise, confusing things may happen in other parts of | |
304 Emacs. | |
305 | |
306 @defun set-marker marker position &optional buffer | |
307 This function moves @var{marker} to @var{position} | |
308 in @var{buffer}. If @var{buffer} is not provided, it defaults to | |
309 the current buffer. | |
310 | |
311 If @var{position} is less than 1, @code{set-marker} moves @var{marker} | |
312 to the beginning of the buffer. If the value of @var{position} is | |
313 greater than the size of the buffer, @code{set-marker} moves marker to | |
314 the end of the buffer. If @var{position} is @code{nil} or a marker that | |
315 points nowhere, then @var{marker} is set to point nowhere. | |
316 | |
317 The value returned is @var{marker}. | |
318 | |
319 @example | |
320 @group | |
321 (setq m (point-marker)) | |
322 @result{} #<marker at 4714 in markers.texi> | |
323 @end group | |
324 @group | |
325 (set-marker m 55) | |
326 @result{} #<marker at 55 in markers.texi> | |
327 @end group | |
328 @group | |
329 (setq b (get-buffer "foo")) | |
330 @result{} #<buffer foo> | |
331 @end group | |
332 @group | |
333 (set-marker m 0 b) | |
334 @result{} #<marker at 1 in foo> | |
335 @end group | |
336 @end example | |
337 @end defun | |
338 | |
339 @defun move-marker marker position &optional buffer | |
340 This is another name for @code{set-marker}. | |
341 @end defun | |
342 | |
343 @node The Mark | |
344 @section The Mark | |
345 @cindex mark, the | |
346 @cindex mark ring | |
347 | |
348 One special marker in each buffer is designated @dfn{the mark}. It | |
349 records a position for the user for the sake of commands such as | |
350 @kbd{C-w} and @kbd{C-x @key{TAB}}. Lisp programs should set the mark | |
351 only to values that have a potential use to the user, and never for | |
352 their own internal purposes. For example, the @code{replace-regexp} | |
353 command sets the mark to the value of point before doing any | |
354 replacements, because this enables the user to move back there | |
355 conveniently after the replace is finished. | |
356 | |
357 Many commands are designed so that when called interactively they | |
358 operate on the text between point and the mark. If you are writing such | |
359 a command, don't examine the mark directly; instead, use | |
360 @code{interactive} with the @samp{r} specification. This provides the | |
361 values of point and the mark as arguments to the command in an | |
362 interactive call, but permits other Lisp programs to specify arguments | |
363 explicitly. @xref{Interactive Codes}. | |
364 | |
365 Each buffer has its own value of the mark that is independent of the | |
366 value of the mark in other buffers. When a buffer is created, the mark | |
367 exists but does not point anywhere. We consider this state as ``the | |
368 absence of a mark in that buffer''. | |
369 | |
370 Once the mark ``exists'' in a buffer, it normally never ceases to | |
371 exist. However, it may become @dfn{inactive}, if Transient Mark mode is | |
372 enabled. The variable @code{mark-active}, which is always local in all | |
373 buffers, indicates whether the mark is active: non-@code{nil} means | |
374 yes. A command can request deactivation of the mark upon return to the | |
375 editor command loop by setting @code{deactivate-mark} to a | |
376 non-@code{nil} value (but this deactivation only follows if Transient | |
377 Mark mode is enabled). | |
378 | |
379 The main motivation for using Transient Mark mode is that this mode | |
380 also enables highlighting of the region when the mark is active. | |
381 @xref{Display}. | |
382 | |
383 In addition to the mark, each buffer has a @dfn{mark ring} which is a | |
384 list of markers containing previous values of the mark. When editing | |
385 commands change the mark, they should normally save the old value of the | |
386 mark on the mark ring. The variable @code{mark-ring-max} specifies the | |
387 maximum number of entries in the mark ring; once the list becomes this | |
388 long, adding a new element deletes the last element. | |
389 | |
390 @defun mark &optional force | |
391 @cindex current buffer mark | |
392 This function returns the current buffer's mark position as an integer. | |
393 | |
394 If the mark is inactive, @code{mark} normally signals an error. | |
395 However, if @var{force} is non-@code{nil}, then @code{mark} returns the | |
396 mark position anyway---or @code{nil}, if the mark is not yet set for | |
397 this buffer. | |
398 @end defun | |
399 | |
400 @defun mark-marker | |
401 This function returns the current buffer's mark. This is the very marker | |
402 which records the mark location inside Emacs, not a copy. Therefore, | |
403 changing this marker's position will directly affect the position of the mark. | |
404 Don't do it unless that is the effect you want. | |
405 | |
406 @example | |
407 @group | |
408 (setq m (mark-marker)) | |
409 @result{} #<marker at 3420 in markers.texi> | |
410 @end group | |
411 @group | |
412 (set-marker m 100) | |
413 @result{} #<marker at 100 in markers.texi> | |
414 @end group | |
415 @group | |
416 (mark-marker) | |
417 @result{} #<marker at 100 in markers.texi> | |
418 @end group | |
419 @end example | |
420 | |
421 Like any marker, this marker can be set to point at any buffer you like. | |
422 We don't recommend that you make it point at any buffer other than the | |
423 one of which it is the mark. If you do, it will yield perfectly | |
424 consistent, but rather odd, results. | |
425 @end defun | |
426 | |
427 @ignore | |
428 @deffn Command set-mark-command jump | |
429 If @var{jump} is @code{nil}, this command sets the mark to the value | |
430 of point and pushes the previous value of the mark on the mark ring. The | |
431 message @samp{Mark set} is also displayed in the echo area. | |
432 | |
433 If @var{jump} is not @code{nil}, this command sets point to the value | |
434 of the mark, and sets the mark to the previous saved mark value, which | |
435 is popped off the mark ring. | |
436 | |
437 This function is @emph{only} intended for interactive use. | |
438 @end deffn | |
439 @end ignore | |
440 | |
441 @defun set-mark position | |
442 This function sets the mark to @var{position}, and activates the mark. | |
443 The old value of the mark is @emph{not} pushed onto the mark ring. | |
444 | |
445 @strong{Please note:} use this function only if you want the user to | |
446 see that the mark has moved, and you want the previous mark position to | |
447 be lost. Normally, when a new mark is set, the old one should go on the | |
448 @code{mark-ring}. For this reason, most applications should use | |
449 @code{push-mark} and @code{pop-mark}, not @code{set-mark}. | |
450 | |
451 Novice Emacs Lisp programmers often try to use the mark for the wrong | |
452 purposes. The mark saves a location for the user's convenience. An | |
453 editing command should not alter the mark unless altering the mark is | |
454 part of the user-level functionality of the command. (And, in that | |
455 case, this effect should be documented.) To remember a location for | |
456 internal use in the Lisp program, store it in a Lisp variable. For | |
457 example: | |
458 | |
459 @example | |
460 @group | |
461 (let ((beg (point))) | |
462 (forward-line 1) | |
463 (delete-region beg (point))). | |
464 @end group | |
465 @end example | |
466 @end defun | |
467 | |
468 @c for interactive use only | |
469 @ignore | |
470 @deffn Command exchange-point-and-mark | |
471 This function exchanges the positions of point and the mark. | |
472 It is intended for interactive use. | |
473 @end deffn | |
474 @end ignore | |
475 | |
476 @defun push-mark &optional position nomsg activate | |
477 This function sets the current buffer's mark to @var{position}, and | |
478 pushes a copy of the previous mark onto @code{mark-ring}. If | |
479 @var{position} is @code{nil}, then the value of point is used. | |
480 @code{push-mark} returns @code{nil}. | |
481 | |
482 The function @code{push-mark} normally @emph{does not} activate the | |
483 mark. To do that, specify @code{t} for the argument @var{activate}. | |
484 | |
485 A @samp{Mark set} message is displayed unless @var{nomsg} is | |
486 non-@code{nil}. | |
487 @end defun | |
488 | |
489 @defun pop-mark | |
490 This function pops off the top element of @code{mark-ring} and makes | |
491 that mark become the buffer's actual mark. This does not move point in | |
492 the buffer, and it does nothing if @code{mark-ring} is empty. It | |
493 deactivates the mark. | |
494 | |
495 The return value is not meaningful. | |
496 @end defun | |
497 | |
498 @defopt transient-mark-mode | |
499 @cindex Transient Mark mode | |
500 This variable enables Transient Mark mode, in which every | |
501 buffer-modifying primitive sets @code{deactivate-mark}. The consequence | |
502 of this is that commands that modify the buffer normally make the mark | |
503 inactive. | |
504 @end defopt | |
505 | |
506 @defvar deactivate-mark | |
507 If an editor command sets this variable non-@code{nil}, then the editor | |
508 command loop deactivates the mark after the command returns. | |
509 @end defvar | |
510 | |
511 @defvar mark-active | |
512 The mark is active when this variable is non-@code{nil}. This variable | |
513 is always local in each buffer. | |
514 @end defvar | |
515 | |
516 @defvar activate-mark-hook | |
517 @defvarx deactivate-mark-hook | |
518 These normal hooks are run, respectively, when the mark becomes active | |
519 and when it becomes inactive. The hook @code{activate-mark-hook} is also | |
520 run at the end of a command if the mark is active and the region may | |
521 have changed. | |
522 @end defvar | |
523 | |
524 @defvar mark-ring | |
525 The value of this buffer-local variable is the list of saved former | |
526 marks of the current buffer, most recent first. | |
527 | |
528 @example | |
529 @group | |
530 mark-ring | |
531 @result{} (#<marker at 11050 in markers.texi> | |
532 #<marker at 10832 in markers.texi> | |
533 @dots{}) | |
534 @end group | |
535 @end example | |
536 @end defvar | |
537 | |
538 @defopt mark-ring-max | |
539 The value of this variable is the maximum size of @code{mark-ring}. If | |
540 more marks than this are pushed onto the @code{mark-ring}, | |
541 @code{push-mark} discards an old mark when it adds a new one. | |
542 @end defopt | |
543 | |
544 @node The Region | |
545 @section The Region | |
546 @cindex region, the | |
547 | |
548 The text between point and the mark is known as @dfn{the region}. | |
549 Various functions operate on text delimited by point and the mark, but | |
550 only those functions specifically related to the region itself are | |
551 described here. | |
552 | |
553 @defun region-beginning | |
554 This function returns the position of the beginning of the region (as | |
555 an integer). This is the position of either point or the mark, | |
556 whichever is smaller. | |
557 | |
558 If the mark does not point anywhere, an error is signaled. | |
559 @end defun | |
560 | |
561 @defun region-end | |
562 This function returns the position of the end of the region (as an | |
563 integer). This is the position of either point or the mark, whichever is | |
564 larger. | |
565 | |
566 If the mark does not point anywhere, an error is signaled. | |
567 @end defun | |
568 | |
569 Few programs need to use the @code{region-beginning} and | |
570 @code{region-end} functions. A command designed to operate on a region | |
571 should normally use @code{interactive} with the @samp{r} specification | |
572 to find the beginning and end of the region. This lets other Lisp | |
573 programs specify the bounds explicitly as arguments. (@xref{Interactive | |
574 Codes}.) |