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