|
428
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
444
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
|
|
428
|
4 @c See the file lispref.texi for copying conditions.
|
|
|
5 @setfilename ../../info/markers.info
|
|
|
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 that 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 @cindex markers vs. extents
|
|
|
64 Note that you can use extents to achieve the same functionality, and
|
|
|
65 more, as markers. (Markers were defined before extents, which is why
|
|
|
66 they both continue to exist.) A zero-length extent with the
|
|
|
67 @code{detachable} property removed is almost identical to a marker.
|
|
|
68 (@xref{Extent Endpoints}, for more information on zero-length extents.)
|
|
|
69
|
|
|
70 In particular:
|
|
|
71
|
|
|
72 @itemize @bullet
|
|
|
73 @item
|
|
|
74 In order to get marker-like behavior in a zero-length extent, the
|
|
|
75 @code{detachable} property must be removed (otherwise, the extent
|
|
|
76 will disappear when text near it is deleted) and exactly one
|
|
|
77 endpoint must be closed (if both endpoints are closed, the extent
|
|
|
78 will expand to contain text inserted where it is located).
|
|
|
79 @item
|
|
|
80 If a zero-length extent has the @code{end-open} property but not
|
|
|
81 the @code{start-open} property (this is the default), text inserted
|
|
|
82 at the extent's location causes the extent to move forward, just
|
|
|
83 like a marker.
|
|
|
84 @item
|
|
|
85 If a zero-length extent has the @code{start-open} property but not
|
|
|
86 the @code{end-open} property, text inserted at the extent's location
|
|
|
87 causes the extent to remain before the text, like what happens to
|
|
|
88 markers when @code{insert-before-markers} is used.
|
|
|
89 @item
|
|
|
90 Markers end up after or before inserted text depending on whether
|
|
|
91 @code{insert} or @code{insert-before-markers} was called. These
|
|
|
92 functions do not affect zero-length extents differently; instead,
|
|
|
93 the presence or absence of the @code{start-open} and @code{end-open}
|
|
|
94 extent properties determines this, as just described.
|
|
|
95 @item
|
|
|
96 Markers are automatically removed from a buffer when they are no
|
|
|
97 longer in use. Extents remain around until explicitly removed
|
|
|
98 from a buffer.
|
|
|
99 @item
|
|
|
100 Many functions are provided for listing the extents in a buffer or
|
|
|
101 in a region of a buffer. No such functions exist for markers.
|
|
|
102 @end itemize
|
|
|
103
|
|
|
104 Here are examples of creating markers, setting markers, and moving point
|
|
|
105 to markers:
|
|
|
106
|
|
|
107 @example
|
|
|
108 @group
|
|
|
109 ;; @r{Make a new marker that initially does not point anywhere:}
|
|
|
110 (setq m1 (make-marker))
|
|
|
111 @result{} #<marker in no buffer>
|
|
|
112 @end group
|
|
|
113
|
|
|
114 @group
|
|
|
115 ;; @r{Set @code{m1} to point between the 99th and 100th characters}
|
|
|
116 ;; @r{in the current buffer:}
|
|
|
117 (set-marker m1 100)
|
|
|
118 @result{} #<marker at 100 in markers.texi>
|
|
|
119 @end group
|
|
|
120
|
|
|
121 @group
|
|
|
122 ;; @r{Now insert one character at the beginning of the buffer:}
|
|
|
123 (goto-char (point-min))
|
|
|
124 @result{} 1
|
|
|
125 (insert "Q")
|
|
|
126 @result{} nil
|
|
|
127 @end group
|
|
|
128
|
|
|
129 @group
|
|
|
130 ;; @r{@code{m1} is updated appropriately.}
|
|
|
131 m1
|
|
|
132 @result{} #<marker at 101 in markers.texi>
|
|
|
133 @end group
|
|
|
134
|
|
|
135 @group
|
|
|
136 ;; @r{Two markers that point to the same position}
|
|
|
137 ;; @r{are not @code{eq}, but they are @code{equal}.}
|
|
|
138 (setq m2 (copy-marker m1))
|
|
|
139 @result{} #<marker at 101 in markers.texi>
|
|
|
140 (eq m1 m2)
|
|
|
141 @result{} nil
|
|
|
142 (equal m1 m2)
|
|
|
143 @result{} t
|
|
|
144 @end group
|
|
|
145
|
|
|
146 @group
|
|
|
147 ;; @r{When you are finished using a marker, make it point nowhere.}
|
|
|
148 (set-marker m1 nil)
|
|
|
149 @result{} #<marker in no buffer>
|
|
|
150 @end group
|
|
|
151 @end example
|
|
|
152
|
|
|
153 @node Predicates on Markers
|
|
|
154 @section Predicates on Markers
|
|
|
155
|
|
|
156 You can test an object to see whether it is a marker, or whether it is
|
|
|
157 either an integer or a marker or either an integer, a character, or a
|
|
|
158 marker. The latter tests are useful in connection with the arithmetic
|
|
|
159 functions that work with any of markers, integers, or characters.
|
|
|
160
|
|
|
161 @defun markerp object
|
|
|
162 This function returns @code{t} if @var{object} is a marker, @code{nil}
|
|
|
163 otherwise. Note that integers are not markers, even though many
|
|
|
164 functions will accept either a marker or an integer.
|
|
|
165 @end defun
|
|
|
166
|
|
|
167 @defun integer-or-marker-p object
|
|
|
168 This function returns @code{t} if @var{object} is an integer or a marker,
|
|
|
169 @code{nil} otherwise.
|
|
|
170 @end defun
|
|
|
171
|
|
|
172 @defun integer-char-or-marker-p object
|
|
|
173 This function returns @code{t} if @var{object} is an integer, a
|
|
|
174 character, or a marker, @code{nil} otherwise.
|
|
|
175 @end defun
|
|
|
176
|
|
|
177 @defun number-or-marker-p object
|
|
|
178 This function returns @code{t} if @var{object} is a number (either kind)
|
|
|
179 or a marker, @code{nil} otherwise.
|
|
|
180 @end defun
|
|
|
181
|
|
|
182 @defun number-char-or-marker-p object
|
|
|
183 This function returns @code{t} if @var{object} is a number (either
|
|
|
184 kind), a character, or a marker, @code{nil} otherwise.
|
|
|
185 @end defun
|
|
|
186
|
|
|
187 @node Creating Markers
|
|
|
188 @section Functions That Create Markers
|
|
|
189
|
|
|
190 When you create a new marker, you can make it point nowhere, or point
|
|
|
191 to the present position of point, or to the beginning or end of the
|
|
|
192 accessible portion of the buffer, or to the same place as another given
|
|
|
193 marker.
|
|
|
194
|
|
|
195 @defun make-marker
|
|
|
196 This functions returns a newly created marker that does not point
|
|
|
197 anywhere.
|
|
|
198
|
|
|
199 @example
|
|
|
200 @group
|
|
|
201 (make-marker)
|
|
|
202 @result{} #<marker in no buffer>
|
|
|
203 @end group
|
|
|
204 @end example
|
|
|
205 @end defun
|
|
|
206
|
|
|
207 @defun point-marker &optional dont-copy-p buffer
|
|
|
208 This function returns a marker that points to the present position of
|
|
|
209 point in @var{buffer}, which defaults to the current buffer.
|
|
|
210 @xref{Point}. For an example, see @code{copy-marker}, below.
|
|
|
211
|
|
|
212 Internally, a marker corresponding to point is always maintained.
|
|
|
213 Normally the marker returned by @code{point-marker} is a copy; you
|
|
|
214 may modify it with reckless abandon. However, if optional argument
|
|
|
215 @var{dont-copy-p} is non-@code{nil}, then the real point-marker is
|
|
|
216 returned; modifying the position of this marker will move point.
|
|
|
217 It is illegal to change the buffer of it, or make it point nowhere.
|
|
|
218 @end defun
|
|
|
219
|
|
|
220 @defun point-min-marker &optional buffer
|
|
|
221 This function returns a new marker that points to the beginning of the
|
|
|
222 accessible portion of @var{buffer}, which defaults to the current
|
|
|
223 buffer. This will be the beginning of the buffer unless narrowing is in
|
|
|
224 effect. @xref{Narrowing}.
|
|
|
225 @end defun
|
|
|
226
|
|
|
227 @defun point-max-marker &optional buffer
|
|
|
228 @cindex end of buffer marker
|
|
|
229 This function returns a new marker that points to the end of the
|
|
|
230 accessible portion of @var{buffer}, which defaults to the current
|
|
|
231 buffer. This will be the end of the buffer unless narrowing is in
|
|
|
232 effect. @xref{Narrowing}.
|
|
|
233
|
|
|
234 Here are examples of this function and @code{point-min-marker}, shown in
|
|
|
235 a buffer containing a version of the source file for the text of this
|
|
|
236 chapter.
|
|
|
237
|
|
|
238 @example
|
|
|
239 @group
|
|
|
240 (point-min-marker)
|
|
|
241 @result{} #<marker at 1 in markers.texi>
|
|
|
242 (point-max-marker)
|
|
|
243 @result{} #<marker at 15573 in markers.texi>
|
|
|
244 @end group
|
|
|
245
|
|
|
246 @group
|
|
|
247 (narrow-to-region 100 200)
|
|
|
248 @result{} nil
|
|
|
249 @end group
|
|
|
250 @group
|
|
|
251 (point-min-marker)
|
|
|
252 @result{} #<marker at 100 in markers.texi>
|
|
|
253 @end group
|
|
|
254 @group
|
|
|
255 (point-max-marker)
|
|
|
256 @result{} #<marker at 200 in markers.texi>
|
|
|
257 @end group
|
|
|
258 @end example
|
|
|
259 @end defun
|
|
|
260
|
|
444
|
261 @defun copy-marker marker-or-integer &optional marker-type
|
|
428
|
262 If passed a marker as its argument, @code{copy-marker} returns a
|
|
|
263 new marker that points to the same place and the same buffer as does
|
|
|
264 @var{marker-or-integer}. If passed an integer as its argument,
|
|
|
265 @code{copy-marker} returns a new marker that points to position
|
|
|
266 @var{marker-or-integer} in the current buffer.
|
|
|
267
|
|
|
268 If passed an integer argument less than 1, @code{copy-marker} returns a
|
|
|
269 new marker that points to the beginning of the current buffer. If
|
|
|
270 passed an integer argument greater than the length of the buffer,
|
|
|
271 @code{copy-marker} returns a new marker that points to the end of the
|
|
|
272 buffer.
|
|
|
273
|
|
444
|
274 An error is signaled if @var{marker-or-integer} is neither a marker nor
|
|
|
275 an integer.
|
|
|
276
|
|
|
277 Optional second argument @var{marker-type} specifies the insertion type
|
|
|
278 of the new marker; see @code{marker-insertion-type}.
|
|
428
|
279
|
|
|
280 @example
|
|
|
281 @group
|
|
|
282 (setq p (point-marker))
|
|
|
283 @result{} #<marker at 2139 in markers.texi>
|
|
|
284 @end group
|
|
|
285
|
|
|
286 @group
|
|
|
287 (setq q (copy-marker p))
|
|
|
288 @result{} #<marker at 2139 in markers.texi>
|
|
|
289 @end group
|
|
|
290
|
|
|
291 @group
|
|
|
292 (eq p q)
|
|
|
293 @result{} nil
|
|
|
294 @end group
|
|
|
295
|
|
|
296 @group
|
|
|
297 (equal p q)
|
|
|
298 @result{} t
|
|
|
299 @end group
|
|
|
300
|
|
|
301 @group
|
|
|
302 (point)
|
|
|
303 @result{} 2139
|
|
|
304 @end group
|
|
|
305
|
|
|
306 @group
|
|
|
307 (set-marker p 3000)
|
|
|
308 @result{} #<marker at 3000 in markers.texi>
|
|
|
309 @end group
|
|
|
310
|
|
|
311 @group
|
|
|
312 (point)
|
|
|
313 @result{} 2139
|
|
|
314 @end group
|
|
|
315
|
|
|
316 @group
|
|
|
317 (setq p (point-marker t))
|
|
|
318 @result{} #<marker at 2139 in markers.texi>
|
|
|
319 @end group
|
|
|
320
|
|
|
321 @group
|
|
|
322 (set-marker p 3000)
|
|
|
323 @result{} #<marker at 3000 in markers.texi>
|
|
|
324 @end group
|
|
|
325
|
|
|
326 @group
|
|
|
327 (point)
|
|
|
328 @result{} 3000
|
|
|
329 @end group
|
|
|
330
|
|
|
331 @group
|
|
|
332 (copy-marker 0)
|
|
|
333 @result{} #<marker at 1 in markers.texi>
|
|
|
334 @end group
|
|
|
335
|
|
|
336 @group
|
|
|
337 (copy-marker 20000)
|
|
|
338 @result{} #<marker at 7572 in markers.texi>
|
|
|
339 @end group
|
|
|
340 @end example
|
|
|
341 @end defun
|
|
|
342
|
|
|
343 @node Information from Markers
|
|
|
344 @section Information from Markers
|
|
|
345
|
|
|
346 This section describes the functions for accessing the components of a
|
|
|
347 marker object.
|
|
|
348
|
|
|
349 @defun marker-position marker
|
|
|
350 This function returns the position that @var{marker} points to, or
|
|
|
351 @code{nil} if it points nowhere.
|
|
|
352 @end defun
|
|
|
353
|
|
|
354 @defun marker-buffer marker
|
|
|
355 This function returns the buffer that @var{marker} points into, or
|
|
|
356 @code{nil} if it points nowhere.
|
|
|
357
|
|
|
358 @example
|
|
|
359 @group
|
|
|
360 (setq m (make-marker))
|
|
|
361 @result{} #<marker in no buffer>
|
|
|
362 @end group
|
|
|
363 @group
|
|
|
364 (marker-position m)
|
|
|
365 @result{} nil
|
|
|
366 @end group
|
|
|
367 @group
|
|
|
368 (marker-buffer m)
|
|
|
369 @result{} nil
|
|
|
370 @end group
|
|
|
371
|
|
|
372 @group
|
|
|
373 (set-marker m 3770 (current-buffer))
|
|
|
374 @result{} #<marker at 3770 in markers.texi>
|
|
|
375 @end group
|
|
|
376 @group
|
|
|
377 (marker-buffer m)
|
|
|
378 @result{} #<buffer markers.texi>
|
|
|
379 @end group
|
|
|
380 @group
|
|
|
381 (marker-position m)
|
|
|
382 @result{} 3770
|
|
|
383 @end group
|
|
|
384 @end example
|
|
|
385 @end defun
|
|
|
386
|
|
|
387 Two distinct markers are considered @code{equal} (even though not
|
|
|
388 @code{eq}) to each other if they have the same position and buffer, or
|
|
|
389 if they both point nowhere.
|
|
|
390
|
|
|
391 @node Changing Markers
|
|
|
392 @section Changing Marker Positions
|
|
|
393
|
|
|
394 This section describes how to change the position of an existing
|
|
|
395 marker. When you do this, be sure you know whether the marker is used
|
|
|
396 outside of your program, and, if so, what effects will result from
|
|
|
397 moving it---otherwise, confusing things may happen in other parts of
|
|
|
398 Emacs.
|
|
|
399
|
|
|
400 @defun set-marker marker position &optional buffer
|
|
|
401 This function moves @var{marker} to @var{position}
|
|
|
402 in @var{buffer}. If @var{buffer} is not provided, it defaults to
|
|
|
403 the current buffer.
|
|
|
404
|
|
444
|
405 @var{position} can be a marker, an integer or @code{nil}. If
|
|
|
406 @var{position} is an integer, @code{set-marker} moves @var{marker} to
|
|
|
407 point before the @var{position}th character in @var{buffer}. If
|
|
|
408 @var{position} is @code{nil}, @var{marker} is made to point nowhere.
|
|
|
409 Then it no longer slows down editing in any buffer. If @var{position}
|
|
|
410 is less than 1, @var{marker} is moved to the beginning of @var{buffer}.
|
|
|
411 If @var{position} is greater than the size of @var{buffer}, @var{marker}
|
|
|
412 is moved to the end of @var{buffer}.
|
|
428
|
413
|
|
|
414 The value returned is @var{marker}.
|
|
|
415
|
|
|
416 @example
|
|
|
417 @group
|
|
|
418 (setq m (point-marker))
|
|
|
419 @result{} #<marker at 4714 in markers.texi>
|
|
|
420 @end group
|
|
|
421 @group
|
|
|
422 (set-marker m 55)
|
|
|
423 @result{} #<marker at 55 in markers.texi>
|
|
|
424 @end group
|
|
|
425 @group
|
|
|
426 (setq b (get-buffer "foo"))
|
|
|
427 @result{} #<buffer foo>
|
|
|
428 @end group
|
|
|
429 @group
|
|
|
430 (set-marker m 0 b)
|
|
|
431 @result{} #<marker at 1 in foo>
|
|
|
432 @end group
|
|
|
433 @end example
|
|
|
434 @end defun
|
|
|
435
|
|
|
436 @defun move-marker marker position &optional buffer
|
|
|
437 This is another name for @code{set-marker}.
|
|
|
438 @end defun
|
|
|
439
|
|
|
440 @node The Mark
|
|
|
441 @section The Mark
|
|
|
442 @cindex mark, the
|
|
|
443 @cindex mark ring
|
|
|
444 @cindex global mark ring
|
|
|
445
|
|
|
446 One special marker in each buffer is designated @dfn{the mark}. It
|
|
|
447 records a position for the user for the sake of commands such as
|
|
|
448 @kbd{C-w} and @kbd{C-x @key{TAB}}. Lisp programs should set the mark
|
|
|
449 only to values that have a potential use to the user, and never for
|
|
|
450 their own internal purposes. For example, the @code{replace-regexp}
|
|
|
451 command sets the mark to the value of point before doing any
|
|
|
452 replacements, because this enables the user to move back there
|
|
|
453 conveniently after the replace is finished.
|
|
|
454
|
|
|
455 Once the mark ``exists'' in a buffer, it normally never ceases to
|
|
|
456 exist. However, it may become @dfn{inactive}, and usually does so
|
|
|
457 after each command (other than simple motion commands and some
|
|
|
458 commands that explicitly activate the mark). When the mark is active,
|
|
|
459 the region between point and the mark is called the @dfn{active region}
|
|
|
460 and is highlighted specially.
|
|
|
461
|
|
|
462 Many commands are designed so that when called interactively they
|
|
|
463 operate on the text between point and the mark. Such commands work
|
|
|
464 only when an active region exists, i.e. when the mark is active.
|
|
|
465 (The reason for this is to prevent you from accidentally deleting
|
|
|
466 or changing large chunks of your text.) If you are writing such
|
|
|
467 a command, don't examine the mark directly; instead, use
|
|
|
468 @code{interactive} with the @samp{r} specification. This provides the
|
|
|
469 values of point and the mark as arguments to the command in an
|
|
|
470 interactive call, but permits other Lisp programs to specify arguments
|
|
|
471 explicitly, and automatically signals an error if the command is called
|
|
|
472 interactively when no active region exists. @xref{Interactive Codes}.
|
|
|
473
|
|
|
474 Each buffer has its own value of the mark that is independent of the
|
|
|
475 value of the mark in other buffers. (When a buffer is created, the mark
|
|
|
476 exists but does not point anywhere. We consider this state as ``the
|
|
|
477 absence of a mark in that buffer.'') However, only one active region can
|
|
|
478 exist at a time. Activating the mark in one buffer automatically
|
|
|
479 deactivates an active mark in any other buffer. Note that the user can
|
|
|
480 explicitly activate a mark at any time by using the command
|
|
|
481 @code{activate-region} (normally bound to @kbd{M-C-z}) or by using the
|
|
|
482 command @code{exchange-point-and-mark} (normally bound to @kbd{C-x C-x}),
|
|
|
483 which has the side effect of activating the mark.
|
|
|
484
|
|
|
485 Some people do not like active regions, so they disable this behavior
|
|
|
486 by setting the variable @code{zmacs-regions} to @code{nil}. This makes
|
|
|
487 the mark always active (except when a buffer is just created and the
|
|
|
488 mark points nowhere), and turns off the highlighting of the region
|
|
|
489 between point and the mark. Commands that explicitly retrieve the value
|
|
|
490 of the mark should make sure that they behave correctly and consistently
|
|
|
491 irrespective of the setting of @code{zmacs-regions}; some primitives are
|
|
|
492 provided to ensure this behavior.
|
|
|
493
|
|
|
494 In addition to the mark, each buffer has a @dfn{mark ring} which is a
|
|
|
495 list of markers containing previous values of the mark. When editing
|
|
|
496 commands change the mark, they should normally save the old value of the
|
|
|
497 mark on the mark ring. The variable @code{mark-ring-max} specifies the
|
|
|
498 maximum number of entries in the mark ring; once the list becomes this
|
|
|
499 long, adding a new element deletes the last element.
|
|
|
500
|
|
|
501 @defun mark &optional force buffer
|
|
|
502 @cindex current buffer mark
|
|
|
503 This function returns @var{buffer}'s mark position as an integer.
|
|
|
504 @var{buffer} defaults to the current buffer if omitted.
|
|
|
505
|
|
|
506 If the mark is inactive, @code{mark} normally returns @code{nil}.
|
|
|
507 However, if @var{force} is non-@code{nil}, then @code{mark} returns the
|
|
|
508 mark position anyway---or @code{nil}, if the mark is not yet set for
|
|
|
509 the buffer.
|
|
|
510
|
|
1738
|
511 (Remember that if @code{zmacs-regions} is @code{nil}, the mark is
|
|
428
|
512 always active as long as it exists, and the @var{force} argument
|
|
|
513 will have no effect.)
|
|
|
514
|
|
|
515 If you are using this in an editing command, you are most likely making
|
|
|
516 a mistake; see the documentation of @code{set-mark} below.
|
|
|
517 @end defun
|
|
|
518
|
|
444
|
519 @defun mark-marker &optional force buffer
|
|
428
|
520 This function returns @var{buffer}'s mark. @var{buffer} defaults to the
|
|
|
521 current buffer if omitted. This is the very marker that records the
|
|
|
522 mark location inside XEmacs, not a copy. Therefore, changing this
|
|
|
523 marker's position will directly affect the position of the mark. Don't
|
|
|
524 do it unless that is the effect you want.
|
|
|
525
|
|
|
526 If the mark is inactive, @code{mark-marker} normally returns @code{nil}.
|
|
|
527 However, if @var{force} is non-@code{nil}, then @code{mark-marker}
|
|
|
528 returns the mark anyway.
|
|
|
529 @example
|
|
|
530 @group
|
|
|
531 (setq m (mark-marker))
|
|
|
532 @result{} #<marker at 3420 in markers.texi>
|
|
|
533 @end group
|
|
|
534 @group
|
|
|
535 (set-marker m 100)
|
|
|
536 @result{} #<marker at 100 in markers.texi>
|
|
|
537 @end group
|
|
|
538 @group
|
|
|
539 (mark-marker)
|
|
|
540 @result{} #<marker at 100 in markers.texi>
|
|
|
541 @end group
|
|
|
542 @end example
|
|
|
543
|
|
|
544 Like any marker, this marker can be set to point at any buffer you like.
|
|
|
545 We don't recommend that you make it point at any buffer other than the
|
|
|
546 one of which it is the mark. If you do, it will yield perfectly
|
|
|
547 consistent, but rather odd, results.
|
|
|
548 @end defun
|
|
|
549
|
|
|
550 @ignore
|
|
|
551 @deffn Command set-mark-command jump
|
|
|
552 If @var{jump} is @code{nil}, this command sets the mark to the value
|
|
|
553 of point and pushes the previous value of the mark on the mark ring. The
|
|
|
554 message @samp{Mark set} is also displayed in the echo area.
|
|
|
555
|
|
|
556 If @var{jump} is not @code{nil}, this command sets point to the value
|
|
|
557 of the mark, and sets the mark to the previous saved mark value, which
|
|
|
558 is popped off the mark ring.
|
|
|
559
|
|
|
560 This function is @emph{only} intended for interactive use.
|
|
|
561 @end deffn
|
|
|
562 @end ignore
|
|
|
563
|
|
|
564 @defun set-mark position &optional buffer
|
|
|
565 This function sets @code{buffer}'s mark to @var{position}, and activates
|
|
|
566 the mark. @var{buffer} defaults to the current buffer if omitted. The
|
|
|
567 old value of the mark is @emph{not} pushed onto the mark ring.
|
|
|
568
|
|
|
569 @strong{Please note:} Use this function only if you want the user to
|
|
|
570 see that the mark has moved, and you want the previous mark position to
|
|
|
571 be lost. Normally, when a new mark is set, the old one should go on the
|
|
|
572 @code{mark-ring}. For this reason, most applications should use
|
|
|
573 @code{push-mark} and @code{pop-mark}, not @code{set-mark}.
|
|
|
574
|
|
|
575 Novice XEmacs Lisp programmers often try to use the mark for the wrong
|
|
|
576 purposes. The mark saves a location for the user's convenience. An
|
|
|
577 editing command should not alter the mark unless altering the mark is
|
|
|
578 part of the user-level functionality of the command. (And, in that
|
|
|
579 case, this effect should be documented.) To remember a location for
|
|
|
580 internal use in the Lisp program, store it in a Lisp variable. For
|
|
|
581 example:
|
|
|
582
|
|
|
583 @example
|
|
|
584 @group
|
|
444
|
585 (let ((start (point)))
|
|
428
|
586 (forward-line 1)
|
|
444
|
587 (delete-region start (point))).
|
|
428
|
588 @end group
|
|
|
589 @end example
|
|
|
590 @end defun
|
|
|
591
|
|
|
592 @deffn Command exchange-point-and-mark &optional dont-activate-region
|
|
|
593 This function exchanges the positions of point and the mark.
|
|
|
594 It is intended for interactive use. The mark is also activated
|
|
|
595 unless @var{dont-activate-region} is non-@code{nil}.
|
|
|
596 @end deffn
|
|
|
597
|
|
|
598 @defun push-mark &optional position nomsg activate buffer
|
|
|
599 This function sets @var{buffer}'s mark to @var{position}, and pushes a
|
|
|
600 copy of the previous mark onto @code{mark-ring}. @var{buffer} defaults
|
|
|
601 to the current buffer if omitted. If @var{position} is @code{nil}, then
|
|
|
602 the value of point is used. @code{push-mark} returns @code{nil}.
|
|
|
603
|
|
|
604 If the last global mark pushed was not in @var{buffer}, also push
|
|
|
605 @var{position} on the global mark ring (see below).
|
|
|
606
|
|
|
607 The function @code{push-mark} normally @emph{does not} activate the
|
|
|
608 mark. To do that, specify @code{t} for the argument @var{activate}.
|
|
|
609
|
|
|
610 A @samp{Mark set} message is displayed unless @var{nomsg} is
|
|
|
611 non-@code{nil}.
|
|
|
612 @end defun
|
|
|
613
|
|
|
614 @defun pop-mark
|
|
|
615 This function pops off the top element of @code{mark-ring} and makes
|
|
|
616 that mark become the buffer's actual mark. This does not move point in
|
|
|
617 the buffer, and it does nothing if @code{mark-ring} is empty. It
|
|
|
618 deactivates the mark.
|
|
|
619
|
|
|
620 The return value is not meaningful.
|
|
|
621 @end defun
|
|
|
622
|
|
|
623 @defvar mark-ring
|
|
|
624 The value of this buffer-local variable is the list of saved former
|
|
|
625 marks of the current buffer, most recent first.
|
|
|
626
|
|
|
627 @example
|
|
|
628 @group
|
|
|
629 mark-ring
|
|
444
|
630 @result{} (#<marker at 11050 in markers.texi>
|
|
428
|
631 #<marker at 10832 in markers.texi>
|
|
|
632 @dots{})
|
|
|
633 @end group
|
|
|
634 @end example
|
|
|
635 @end defvar
|
|
|
636
|
|
|
637 @defopt mark-ring-max
|
|
|
638 The value of this variable is the maximum size of @code{mark-ring}. If
|
|
|
639 more marks than this are pushed onto the @code{mark-ring},
|
|
|
640 @code{push-mark} discards an old mark when it adds a new one.
|
|
|
641 @end defopt
|
|
|
642
|
|
|
643 In additional to a per-buffer mark ring, there is a @dfn{global mark
|
|
|
644 ring}. Marks are pushed onto the global mark ring the first time you
|
|
|
645 set a mark after switching buffers.
|
|
|
646
|
|
|
647 @defvar global-mark-ring
|
|
|
648 The value of this variable is the list of saved former global marks,
|
|
|
649 most recent first.
|
|
|
650 @end defvar
|
|
|
651
|
|
|
652 @defopt mark-ring-max
|
|
|
653 The value of this variable is the maximum size of
|
|
|
654 @code{global-mark-ring}. If more marks than this are pushed onto the
|
|
|
655 @code{global-mark-ring}, @code{push-mark} discards an old mark when it
|
|
|
656 adds a new one.
|
|
|
657 @end defopt
|
|
|
658
|
|
|
659 @deffn Command pop-global-mark
|
|
|
660 This function pops a mark off the global mark ring and jumps to that
|
|
|
661 location.
|
|
|
662 @end deffn
|
|
|
663
|
|
|
664 @node The Region
|
|
|
665 @section The Region
|
|
|
666 @cindex region, the
|
|
|
667
|
|
|
668 The text between point and the mark is known as @dfn{the region}.
|
|
|
669 Various functions operate on text delimited by point and the mark, but
|
|
|
670 only those functions specifically related to the region itself are
|
|
|
671 described here.
|
|
|
672
|
|
|
673 When @code{zmacs-regions} is non-@code{nil} (this is the default), the
|
|
|
674 concept of an @dfn{active region} exists. The region is active when the
|
|
|
675 corresponding mark is active. Note that only one active region at a
|
|
440
|
676 time can exist---i.e. only one buffer's region is active at a time.
|
|
428
|
677 @xref{The Mark}, for more information about active regions.
|
|
|
678
|
|
|
679 @defopt zmacs-regions
|
|
|
680 If non-@code{nil} (the default), active regions are used. @xref{The Mark},
|
|
|
681 for a detailed explanation of what this means.
|
|
|
682 @end defopt
|
|
|
683
|
|
|
684 A number of functions are provided for explicitly determining the
|
|
|
685 bounds of the region and whether it is active. Few programs need to use
|
|
|
686 these functions, however. A command designed to operate on a region
|
|
|
687 should normally use @code{interactive} with the @samp{r} specification
|
|
|
688 to find the beginning and end of the region. This lets other Lisp
|
|
|
689 programs specify the bounds explicitly as arguments and automatically
|
|
1738
|
690 respects the user's setting for @code{zmacs-regions}.
|
|
|
691 (@xref{Interactive Codes}.)
|
|
428
|
692
|
|
|
693 @defun region-beginning &optional buffer
|
|
|
694 This function returns the position of the beginning of @var{buffer}'s
|
|
|
695 region (as an integer). This is the position of either point or the
|
|
|
696 mark, whichever is smaller. @var{buffer} defaults to the current buffer
|
|
|
697 if omitted.
|
|
|
698
|
|
|
699 If the mark does not point anywhere, an error is signaled. Note that
|
|
|
700 this function ignores whether the region is active.
|
|
|
701 @end defun
|
|
|
702
|
|
|
703 @defun region-end &optional buffer
|
|
|
704 This function returns the position of the end of @var{buffer}'s region
|
|
|
705 (as an integer). This is the position of either point or the mark,
|
|
|
706 whichever is larger. @var{buffer} defaults to the current buffer if
|
|
|
707 omitted.
|
|
|
708
|
|
|
709 If the mark does not point anywhere, an error is signaled. Note that
|
|
|
710 this function ignores whether the region is active.
|
|
|
711 @end defun
|
|
|
712
|
|
|
713 @defun region-exists-p
|
|
|
714 This function is non-@code{nil} if the region exists. If active regions
|
|
|
715 are in use (i.e. @code{zmacs-regions} is true), this means that the
|
|
|
716 region is active. Otherwise, this means that the user has pushed a mark
|
|
|
717 in this buffer at some point in the past. If this function returns @code{nil},
|
|
|
718 a function that uses the @samp{r} interactive specification will cause
|
|
|
719 an error when called interactively.
|
|
|
720 @end defun
|
|
|
721
|
|
|
722 @defun region-active-p
|
|
|
723 If @code{zmacs-regions} is true, this is equivalent to
|
|
|
724 @code{region-exists-p}. Otherwise, this function always returns false.
|
|
|
725 This function is used by commands such as @code{fill-paragraph-or-region}
|
|
|
726 and @code{capitalize-region-or-word}, which operate either on the active
|
|
|
727 region or on something else (e.g. the word or paragraph at point).
|
|
|
728 @end defun
|
|
|
729
|
|
|
730 @defvar zmacs-region-stays
|
|
|
731 If a command sets this variable to true, the currently active region
|
|
|
732 will remain activated when the command finishes. (Normally the region is
|
|
1738
|
733 deactivated when each command terminates.) If @code{zmacs-regions} is
|
|
428
|
734 false, however, this has no effect. Under normal circumstances, you do
|
|
|
735 not need to set this; use the interactive specification @samp{_}
|
|
|
736 instead, if you want the region to remain active.
|
|
|
737 @end defvar
|
|
|
738
|
|
|
739 @defun zmacs-activate-region
|
|
|
740 This function activates the region in the current buffer (this is
|
|
|
741 equivalent to activating the current buffer's mark). This will normally
|
|
|
742 also highlight the text in the active region and set
|
|
1738
|
743 @code{zmacs-region-stays} to @code{t}. (If @code{zmacs-regions} is
|
|
|
744 false, however, this function has no effect.)
|
|
428
|
745 @end defun
|
|
|
746
|
|
|
747 @defun zmacs-deactivate-region
|
|
|
748 This function deactivates the region in the current buffer (this is
|
|
|
749 equivalent to deactivating the current buffer's mark). This will
|
|
|
750 normally also unhighlight the text in the active region and set
|
|
1738
|
751 @code{zmacs-region-stays} to @code{nil}. (If @code{zmacs-regions} is
|
|
428
|
752 false, however, this function has no effect.)
|
|
|
753 @end defun
|
|
|
754
|
|
|
755 @defun zmacs-update-region
|
|
|
756 This function updates the active region, if it's currently active. (If
|
|
|
757 there is no active region, this function does nothing.) This has the
|
|
|
758 effect of updating the highlighting on the text in the region; but you
|
|
|
759 should never need to call this except under rather strange
|
|
|
760 circumstances. The command loop automatically calls it when
|
|
|
761 appropriate. Calling this function will call the hook
|
|
|
762 @code{zmacs-update-region-hook}, if the region is active.
|
|
|
763 @end defun
|
|
|
764
|
|
|
765 @defvar zmacs-activate-region-hook
|
|
|
766 This normal hook is called when a region becomes active. (Usually this
|
|
|
767 happens as a result of a command that activates the region, such as
|
|
|
768 @code{set-mark-command}, @code{activate-region}, or
|
|
|
769 @code{exchange-point-and-mark}.) Note that calling
|
|
|
770 @file{zmacs-activate-region} will call this hook, even if the region is
|
|
1738
|
771 already active. If @code{zmacs-regions} is false, however, this hook
|
|
428
|
772 will never get called under any circumstances.
|
|
|
773 @end defvar
|
|
|
774
|
|
|
775 @defvar zmacs-deactivate-region-hook
|
|
|
776 This normal hook is called when an active region becomes inactive.
|
|
|
777 (Calling @file{zmacs-deactivate-region} when the region is inactive will
|
|
1738
|
778 @emph{not} cause this hook to be called.) If @code{zmacs-regions} is
|
|
428
|
779 false, this hook will never get called.
|
|
|
780 @end defvar
|
|
|
781
|
|
|
782 @defvar zmacs-update-region-hook
|
|
|
783 This normal hook is called when an active region is "updated" by
|
|
|
784 @code{zmacs-update-region}. This normally gets called at the end
|
|
1738
|
785 of each command that sets @code{zmacs-region-stays} to @code{t},
|
|
428
|
786 indicating that the region should remain activated. The motion
|
|
|
787 commands do this.
|
|
|
788 @end defvar
|
|
|
789
|
|
|
790
|
