|
0
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
|
|
|
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
|
|
|
261 @defun copy-marker marker-or-integer
|
|
|
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
|
|
|
274 An error is signaled if @var{marker} is neither a marker nor an
|
|
|
275 integer.
|
|
|
276
|
|
|
277 @example
|
|
|
278 @group
|
|
|
279 (setq p (point-marker))
|
|
|
280 @result{} #<marker at 2139 in markers.texi>
|
|
|
281 @end group
|
|
|
282
|
|
|
283 @group
|
|
|
284 (setq q (copy-marker p))
|
|
|
285 @result{} #<marker at 2139 in markers.texi>
|
|
|
286 @end group
|
|
|
287
|
|
|
288 @group
|
|
|
289 (eq p q)
|
|
|
290 @result{} nil
|
|
|
291 @end group
|
|
|
292
|
|
|
293 @group
|
|
|
294 (equal p q)
|
|
|
295 @result{} t
|
|
|
296 @end group
|
|
|
297
|
|
|
298 @group
|
|
|
299 (point)
|
|
|
300 @result{} 2139
|
|
|
301 @end group
|
|
|
302
|
|
|
303 @group
|
|
|
304 (set-marker p 3000)
|
|
|
305 @result{} #<marker at 3000 in markers.texi>
|
|
|
306 @end group
|
|
|
307
|
|
|
308 @group
|
|
|
309 (point)
|
|
|
310 @result{} 2139
|
|
|
311 @end group
|
|
|
312
|
|
|
313 @group
|
|
|
314 (setq p (point-marker t))
|
|
|
315 @result{} #<marker at 2139 in markers.texi>
|
|
|
316 @end group
|
|
|
317
|
|
|
318 @group
|
|
|
319 (set-marker p 3000)
|
|
|
320 @result{} #<marker at 3000 in markers.texi>
|
|
|
321 @end group
|
|
|
322
|
|
|
323 @group
|
|
|
324 (point)
|
|
|
325 @result{} 3000
|
|
|
326 @end group
|
|
|
327
|
|
|
328 @group
|
|
|
329 (copy-marker 0)
|
|
|
330 @result{} #<marker at 1 in markers.texi>
|
|
|
331 @end group
|
|
|
332
|
|
|
333 @group
|
|
|
334 (copy-marker 20000)
|
|
|
335 @result{} #<marker at 7572 in markers.texi>
|
|
|
336 @end group
|
|
|
337 @end example
|
|
|
338 @end defun
|
|
|
339
|
|
|
340 @node Information from Markers
|
|
|
341 @section Information from Markers
|
|
|
342
|
|
|
343 This section describes the functions for accessing the components of a
|
|
|
344 marker object.
|
|
|
345
|
|
|
346 @defun marker-position marker
|
|
|
347 This function returns the position that @var{marker} points to, or
|
|
|
348 @code{nil} if it points nowhere.
|
|
|
349 @end defun
|
|
|
350
|
|
|
351 @defun marker-buffer marker
|
|
|
352 This function returns the buffer that @var{marker} points into, or
|
|
|
353 @code{nil} if it points nowhere.
|
|
|
354
|
|
|
355 @example
|
|
|
356 @group
|
|
|
357 (setq m (make-marker))
|
|
|
358 @result{} #<marker in no buffer>
|
|
|
359 @end group
|
|
|
360 @group
|
|
|
361 (marker-position m)
|
|
|
362 @result{} nil
|
|
|
363 @end group
|
|
|
364 @group
|
|
|
365 (marker-buffer m)
|
|
|
366 @result{} nil
|
|
|
367 @end group
|
|
|
368
|
|
|
369 @group
|
|
|
370 (set-marker m 3770 (current-buffer))
|
|
|
371 @result{} #<marker at 3770 in markers.texi>
|
|
|
372 @end group
|
|
|
373 @group
|
|
|
374 (marker-buffer m)
|
|
|
375 @result{} #<buffer markers.texi>
|
|
|
376 @end group
|
|
|
377 @group
|
|
|
378 (marker-position m)
|
|
|
379 @result{} 3770
|
|
|
380 @end group
|
|
|
381 @end example
|
|
|
382 @end defun
|
|
|
383
|
|
|
384 Two distinct markers are considered @code{equal} (even though not
|
|
|
385 @code{eq}) to each other if they have the same position and buffer, or
|
|
|
386 if they both point nowhere.
|
|
|
387
|
|
|
388 @node Changing Markers
|
|
|
389 @section Changing Marker Positions
|
|
|
390
|
|
|
391 This section describes how to change the position of an existing
|
|
|
392 marker. When you do this, be sure you know whether the marker is used
|
|
|
393 outside of your program, and, if so, what effects will result from
|
|
|
394 moving it---otherwise, confusing things may happen in other parts of
|
|
|
395 Emacs.
|
|
|
396
|
|
|
397 @defun set-marker marker position &optional buffer
|
|
|
398 This function moves @var{marker} to @var{position}
|
|
|
399 in @var{buffer}. If @var{buffer} is not provided, it defaults to
|
|
|
400 the current buffer.
|
|
|
401
|
|
|
402 If @var{position} is less than 1, @code{set-marker} moves @var{marker}
|
|
|
403 to the beginning of the buffer. If @var{position} is greater than the
|
|
|
404 size of the buffer, @code{set-marker} moves marker to the end of the
|
|
|
405 buffer. If @var{position} is @code{nil} or a marker that points
|
|
|
406 nowhere, then @var{marker} is set to point nowhere.
|
|
|
407
|
|
|
408 The value returned is @var{marker}.
|
|
|
409
|
|
|
410 @example
|
|
|
411 @group
|
|
|
412 (setq m (point-marker))
|
|
|
413 @result{} #<marker at 4714 in markers.texi>
|
|
|
414 @end group
|
|
|
415 @group
|
|
|
416 (set-marker m 55)
|
|
|
417 @result{} #<marker at 55 in markers.texi>
|
|
|
418 @end group
|
|
|
419 @group
|
|
|
420 (setq b (get-buffer "foo"))
|
|
|
421 @result{} #<buffer foo>
|
|
|
422 @end group
|
|
|
423 @group
|
|
|
424 (set-marker m 0 b)
|
|
|
425 @result{} #<marker at 1 in foo>
|
|
|
426 @end group
|
|
|
427 @end example
|
|
|
428 @end defun
|
|
|
429
|
|
|
430 @defun move-marker marker position &optional buffer
|
|
|
431 This is another name for @code{set-marker}.
|
|
|
432 @end defun
|
|
|
433
|
|
|
434 @node The Mark
|
|
|
435 @section The Mark
|
|
|
436 @cindex mark, the
|
|
|
437 @cindex mark ring
|
|
|
438 @cindex global mark ring
|
|
|
439
|
|
|
440 One special marker in each buffer is designated @dfn{the mark}. It
|
|
|
441 records a position for the user for the sake of commands such as
|
|
|
442 @kbd{C-w} and @kbd{C-x @key{TAB}}. Lisp programs should set the mark
|
|
|
443 only to values that have a potential use to the user, and never for
|
|
|
444 their own internal purposes. For example, the @code{replace-regexp}
|
|
|
445 command sets the mark to the value of point before doing any
|
|
|
446 replacements, because this enables the user to move back there
|
|
|
447 conveniently after the replace is finished.
|
|
|
448
|
|
|
449 Once the mark ``exists'' in a buffer, it normally never ceases to
|
|
|
450 exist. However, it may become @dfn{inactive}, and usually does so
|
|
|
451 after each command (other than simple motion commands and some
|
|
|
452 commands that explicitly activate the mark). When the mark is active,
|
|
|
453 the region between point and the mark is called the @dfn{active region}
|
|
|
454 and is highlighted specially.
|
|
|
455
|
|
|
456 Many commands are designed so that when called interactively they
|
|
|
457 operate on the text between point and the mark. Such commands work
|
|
|
458 only when an active region exists, i.e. when the mark is active.
|
|
|
459 (The reason for this is to prevent you from accidentally deleting
|
|
|
460 or changing large chunks of your text.) If you are writing such
|
|
|
461 a command, don't examine the mark directly; instead, use
|
|
|
462 @code{interactive} with the @samp{r} specification. This provides the
|
|
|
463 values of point and the mark as arguments to the command in an
|
|
|
464 interactive call, but permits other Lisp programs to specify arguments
|
|
|
465 explicitly, and automatically signals an error if the command is called
|
|
|
466 interactively when no active region exists. @xref{Interactive Codes}.
|
|
|
467
|
|
|
468 Each buffer has its own value of the mark that is independent of the
|
|
|
469 value of the mark in other buffers. (When a buffer is created, the mark
|
|
|
470 exists but does not point anywhere. We consider this state as ``the
|
|
|
471 absence of a mark in that buffer.'') However, only one active region can
|
|
|
472 exist at a time. Activating the mark in one buffer automatically
|
|
|
473 deactivates an active mark in any other buffer. Note that the user can
|
|
|
474 explicitly activate a mark at any time by using the command
|
|
|
475 @code{activate-region} (normally bound to @kbd{M-C-z}) or by using the
|
|
|
476 command @code{exchange-point-and-mark} (normally bound to @kbd{C-x C-x}),
|
|
|
477 which has the side effect of activating the mark.
|
|
|
478
|
|
|
479 Some people do not like active regions, so they disable this behavior
|
|
|
480 by setting the variable @code{zmacs-regions} to @code{nil}. This makes
|
|
|
481 the mark always active (except when a buffer is just created and the
|
|
|
482 mark points nowhere), and turns off the highlighting of the region
|
|
|
483 between point and the mark. Commands that explicitly retrieve the value
|
|
|
484 of the mark should make sure that they behave correctly and consistently
|
|
|
485 irrespective of the setting of @code{zmacs-regions}; some primitives are
|
|
|
486 provided to ensure this behavior.
|
|
|
487
|
|
|
488 In addition to the mark, each buffer has a @dfn{mark ring} which is a
|
|
|
489 list of markers containing previous values of the mark. When editing
|
|
|
490 commands change the mark, they should normally save the old value of the
|
|
|
491 mark on the mark ring. The variable @code{mark-ring-max} specifies the
|
|
|
492 maximum number of entries in the mark ring; once the list becomes this
|
|
|
493 long, adding a new element deletes the last element.
|
|
|
494
|
|
|
495 @defun mark &optional force buffer
|
|
|
496 @cindex current buffer mark
|
|
|
497 This function returns @var{buffer}'s mark position as an integer.
|
|
|
498 @var{buffer} defaults to the current buffer if omitted.
|
|
|
499
|
|
|
500 If the mark is inactive, @code{mark} normally returns @code{nil}.
|
|
|
501 However, if @var{force} is non-@code{nil}, then @code{mark} returns the
|
|
|
502 mark position anyway---or @code{nil}, if the mark is not yet set for
|
|
|
503 the buffer.
|
|
|
504
|
|
|
505 (Remember that if @var{zmacs-regions} is @code{nil}, the mark is
|
|
|
506 always active as long as it exists, and the @var{force} argument
|
|
|
507 will have no effect.)
|
|
|
508
|
|
|
509 If you are using this in an editing command, you are most likely making
|
|
|
510 a mistake; see the documentation of @code{set-mark} below.
|
|
|
511 @end defun
|
|
|
512
|
|
|
513 @defun mark-marker inactive-p buffer
|
|
|
514 This function returns @var{buffer}'s mark. @var{buffer} defaults to the
|
|
|
515 current buffer if omitted. This is the very marker that records the
|
|
|
516 mark location inside XEmacs, not a copy. Therefore, changing this
|
|
|
517 marker's position will directly affect the position of the mark. Don't
|
|
|
518 do it unless that is the effect you want.
|
|
|
519
|
|
|
520 If the mark is inactive, @code{mark-marker} normally returns @code{nil}.
|
|
|
521 However, if @var{force} is non-@code{nil}, then @code{mark-marker}
|
|
|
522 returns the mark anyway.
|
|
|
523 @example
|
|
|
524 @group
|
|
|
525 (setq m (mark-marker))
|
|
|
526 @result{} #<marker at 3420 in markers.texi>
|
|
|
527 @end group
|
|
|
528 @group
|
|
|
529 (set-marker m 100)
|
|
|
530 @result{} #<marker at 100 in markers.texi>
|
|
|
531 @end group
|
|
|
532 @group
|
|
|
533 (mark-marker)
|
|
|
534 @result{} #<marker at 100 in markers.texi>
|
|
|
535 @end group
|
|
|
536 @end example
|
|
|
537
|
|
|
538 Like any marker, this marker can be set to point at any buffer you like.
|
|
|
539 We don't recommend that you make it point at any buffer other than the
|
|
|
540 one of which it is the mark. If you do, it will yield perfectly
|
|
|
541 consistent, but rather odd, results.
|
|
|
542 @end defun
|
|
|
543
|
|
|
544 @ignore
|
|
|
545 @deffn Command set-mark-command jump
|
|
|
546 If @var{jump} is @code{nil}, this command sets the mark to the value
|
|
|
547 of point and pushes the previous value of the mark on the mark ring. The
|
|
|
548 message @samp{Mark set} is also displayed in the echo area.
|
|
|
549
|
|
|
550 If @var{jump} is not @code{nil}, this command sets point to the value
|
|
|
551 of the mark, and sets the mark to the previous saved mark value, which
|
|
|
552 is popped off the mark ring.
|
|
|
553
|
|
|
554 This function is @emph{only} intended for interactive use.
|
|
|
555 @end deffn
|
|
|
556 @end ignore
|
|
|
557
|
|
|
558 @defun set-mark position &optional buffer
|
|
|
559 This function sets @code{buffer}'s mark to @var{position}, and activates
|
|
|
560 the mark. @var{buffer} defaults to the current buffer if omitted. The
|
|
|
561 old value of the mark is @emph{not} pushed onto the mark ring.
|
|
|
562
|
|
|
563 @strong{Please note:} Use this function only if you want the user to
|
|
|
564 see that the mark has moved, and you want the previous mark position to
|
|
|
565 be lost. Normally, when a new mark is set, the old one should go on the
|
|
|
566 @code{mark-ring}. For this reason, most applications should use
|
|
|
567 @code{push-mark} and @code{pop-mark}, not @code{set-mark}.
|
|
|
568
|
|
|
569 Novice XEmacs Lisp programmers often try to use the mark for the wrong
|
|
|
570 purposes. The mark saves a location for the user's convenience. An
|
|
|
571 editing command should not alter the mark unless altering the mark is
|
|
|
572 part of the user-level functionality of the command. (And, in that
|
|
|
573 case, this effect should be documented.) To remember a location for
|
|
|
574 internal use in the Lisp program, store it in a Lisp variable. For
|
|
|
575 example:
|
|
|
576
|
|
|
577 @example
|
|
|
578 @group
|
|
|
579 (let ((beg (point)))
|
|
|
580 (forward-line 1)
|
|
|
581 (delete-region beg (point))).
|
|
|
582 @end group
|
|
|
583 @end example
|
|
|
584 @end defun
|
|
|
585
|
|
|
586 @deffn Command exchange-point-and-mark &optional dont-activate-region
|
|
|
587 This function exchanges the positions of point and the mark.
|
|
|
588 It is intended for interactive use. The mark is also activated
|
|
|
589 unless @var{dont-activate-region} is non-@code{nil}.
|
|
|
590 @end deffn
|
|
|
591
|
|
|
592 @defun push-mark &optional position nomsg activate buffer
|
|
|
593 This function sets @var{buffer}'s mark to @var{position}, and pushes a
|
|
|
594 copy of the previous mark onto @code{mark-ring}. @var{buffer} defaults
|
|
|
595 to the current buffer if omitted. If @var{position} is @code{nil}, then
|
|
|
596 the value of point is used. @code{push-mark} returns @code{nil}.
|
|
|
597
|
|
|
598 If the last global mark pushed was not in @var{buffer}, also push
|
|
|
599 @var{position} on the global mark ring (see below).
|
|
|
600
|
|
|
601 The function @code{push-mark} normally @emph{does not} activate the
|
|
|
602 mark. To do that, specify @code{t} for the argument @var{activate}.
|
|
|
603
|
|
|
604 A @samp{Mark set} message is displayed unless @var{nomsg} is
|
|
|
605 non-@code{nil}.
|
|
|
606 @end defun
|
|
|
607
|
|
|
608 @defun pop-mark
|
|
|
609 This function pops off the top element of @code{mark-ring} and makes
|
|
|
610 that mark become the buffer's actual mark. This does not move point in
|
|
|
611 the buffer, and it does nothing if @code{mark-ring} is empty. It
|
|
|
612 deactivates the mark.
|
|
|
613
|
|
|
614 The return value is not meaningful.
|
|
|
615 @end defun
|
|
|
616
|
|
|
617 @defvar mark-ring
|
|
|
618 The value of this buffer-local variable is the list of saved former
|
|
|
619 marks of the current buffer, most recent first.
|
|
|
620
|
|
|
621 @example
|
|
|
622 @group
|
|
|
623 mark-ring
|
|
|
624 @result{} (#<marker at 11050 in markers.texi>
|
|
|
625 #<marker at 10832 in markers.texi>
|
|
|
626 @dots{})
|
|
|
627 @end group
|
|
|
628 @end example
|
|
|
629 @end defvar
|
|
|
630
|
|
|
631 @defopt mark-ring-max
|
|
|
632 The value of this variable is the maximum size of @code{mark-ring}. If
|
|
|
633 more marks than this are pushed onto the @code{mark-ring},
|
|
|
634 @code{push-mark} discards an old mark when it adds a new one.
|
|
|
635 @end defopt
|
|
|
636
|
|
|
637 In additional to a per-buffer mark ring, there is a @dfn{global mark
|
|
|
638 ring}. Marks are pushed onto the global mark ring the first time you
|
|
|
639 set a mark after switching buffers.
|
|
|
640
|
|
|
641 @defvar global-mark-ring
|
|
|
642 The value of this variable is the list of saved former global marks,
|
|
|
643 most recent first.
|
|
|
644 @end defvar
|
|
|
645
|
|
|
646 @defopt mark-ring-max
|
|
|
647 The value of this variable is the maximum size of
|
|
|
648 @code{global-mark-ring}. If more marks than this are pushed onto the
|
|
|
649 @code{global-mark-ring}, @code{push-mark} discards an old mark when it
|
|
|
650 adds a new one.
|
|
|
651 @end defopt
|
|
|
652
|
|
|
653 @deffn Command pop-global-mark
|
|
|
654 This function pops a mark off the global mark ring and jumps to that
|
|
|
655 location.
|
|
|
656 @end deffn
|
|
|
657
|
|
|
658 @node The Region
|
|
|
659 @section The Region
|
|
|
660 @cindex region, the
|
|
|
661
|
|
|
662 The text between point and the mark is known as @dfn{the region}.
|
|
|
663 Various functions operate on text delimited by point and the mark, but
|
|
|
664 only those functions specifically related to the region itself are
|
|
|
665 described here.
|
|
|
666
|
|
|
667 When @code{zmacs-regions} is non-@code{nil} (this is the default), the
|
|
|
668 concept of an @dfn{active region} exists. The region is active when the
|
|
|
669 corresponding mark is active. Note that only one active region at a
|
|
|
670 time can exist -- i.e. only one buffer's region is active at a time.
|
|
394
|
671 @xref{The Mark}, for more information about active regions.
|
|
0
|
672
|
|
|
673 @defopt zmacs-regions
|
|
|
674 If non-@code{nil} (the default), active regions are used. @xref{The Mark},
|
|
|
675 for a detailed explanation of what this means.
|
|
|
676 @end defopt
|
|
|
677
|
|
|
678 A number of functions are provided for explicitly determining the
|
|
|
679 bounds of the region and whether it is active. Few programs need to use
|
|
|
680 these functions, however. A command designed to operate on a region
|
|
|
681 should normally use @code{interactive} with the @samp{r} specification
|
|
|
682 to find the beginning and end of the region. This lets other Lisp
|
|
|
683 programs specify the bounds explicitly as arguments and automatically
|
|
|
684 respects the user's setting for @var{zmacs-regions}. (@xref{Interactive
|
|
|
685 Codes}.)
|
|
|
686
|
|
|
687 @defun region-beginning &optional buffer
|
|
|
688 This function returns the position of the beginning of @var{buffer}'s
|
|
|
689 region (as an integer). This is the position of either point or the
|
|
|
690 mark, whichever is smaller. @var{buffer} defaults to the current buffer
|
|
|
691 if omitted.
|
|
|
692
|
|
|
693 If the mark does not point anywhere, an error is signaled. Note that
|
|
|
694 this function ignores whether the region is active.
|
|
|
695 @end defun
|
|
|
696
|
|
|
697 @defun region-end &optional buffer
|
|
|
698 This function returns the position of the end of @var{buffer}'s region
|
|
|
699 (as an integer). This is the position of either point or the mark,
|
|
|
700 whichever is larger. @var{buffer} defaults to the current buffer if
|
|
|
701 omitted.
|
|
|
702
|
|
|
703 If the mark does not point anywhere, an error is signaled. Note that
|
|
|
704 this function ignores whether the region is active.
|
|
|
705 @end defun
|
|
|
706
|
|
|
707 @defun region-exists-p
|
|
|
708 This function is non-@code{nil} if the region exists. If active regions
|
|
|
709 are in use (i.e. @code{zmacs-regions} is true), this means that the
|
|
|
710 region is active. Otherwise, this means that the user has pushed a mark
|
|
|
711 in this buffer at some point in the past. If this function returns @code{nil},
|
|
|
712 a function that uses the @samp{r} interactive specification will cause
|
|
|
713 an error when called interactively.
|
|
|
714 @end defun
|
|
|
715
|
|
|
716 @defun region-active-p
|
|
|
717 If @code{zmacs-regions} is true, this is equivalent to
|
|
|
718 @code{region-exists-p}. Otherwise, this function always returns false.
|
|
|
719 This function is used by commands such as @code{fill-paragraph-or-region}
|
|
|
720 and @code{capitalize-region-or-word}, which operate either on the active
|
|
|
721 region or on something else (e.g. the word or paragraph at point).
|
|
|
722 @end defun
|
|
|
723
|
|
|
724 @defvar zmacs-region-stays
|
|
|
725 If a command sets this variable to true, the currently active region
|
|
|
726 will remain activated when the command finishes. (Normally the region is
|
|
|
727 deactivated when each command terminates.) If @var{zmacs-regions} is
|
|
|
728 false, however, this has no effect. Under normal circumstances, you do
|
|
|
729 not need to set this; use the interactive specification @samp{_}
|
|
|
730 instead, if you want the region to remain active.
|
|
|
731 @end defvar
|
|
|
732
|
|
|
733 @defun zmacs-activate-region
|
|
|
734 This function activates the region in the current buffer (this is
|
|
|
735 equivalent to activating the current buffer's mark). This will normally
|
|
|
736 also highlight the text in the active region and set
|
|
|
737 @var{zmacs-region-stays} to @code{t}. (If @var{zmacs-regions} is false,
|
|
|
738 however, this function has no effect.)
|
|
|
739 @end defun
|
|
|
740
|
|
|
741 @defun zmacs-deactivate-region
|
|
|
742 This function deactivates the region in the current buffer (this is
|
|
|
743 equivalent to deactivating the current buffer's mark). This will
|
|
|
744 normally also unhighlight the text in the active region and set
|
|
|
745 @var{zmacs-region-stays} to @code{nil}. (If @var{zmacs-regions} is
|
|
|
746 false, however, this function has no effect.)
|
|
|
747 @end defun
|
|
|
748
|
|
|
749 @defun zmacs-update-region
|
|
|
750 This function updates the active region, if it's currently active. (If
|
|
|
751 there is no active region, this function does nothing.) This has the
|
|
|
752 effect of updating the highlighting on the text in the region; but you
|
|
|
753 should never need to call this except under rather strange
|
|
|
754 circumstances. The command loop automatically calls it when
|
|
|
755 appropriate. Calling this function will call the hook
|
|
|
756 @code{zmacs-update-region-hook}, if the region is active.
|
|
|
757 @end defun
|
|
|
758
|
|
|
759 @defvar zmacs-activate-region-hook
|
|
|
760 This normal hook is called when a region becomes active. (Usually this
|
|
|
761 happens as a result of a command that activates the region, such as
|
|
|
762 @code{set-mark-command}, @code{activate-region}, or
|
|
|
763 @code{exchange-point-and-mark}.) Note that calling
|
|
|
764 @file{zmacs-activate-region} will call this hook, even if the region is
|
|
|
765 already active. If @var{zmacs-regions} is false, however, this hook
|
|
|
766 will never get called under any circumstances.
|
|
|
767 @end defvar
|
|
|
768
|
|
|
769 @defvar zmacs-deactivate-region-hook
|
|
|
770 This normal hook is called when an active region becomes inactive.
|
|
|
771 (Calling @file{zmacs-deactivate-region} when the region is inactive will
|
|
|
772 @emph{not} cause this hook to be called.) If @var{zmacs-regions} is
|
|
|
773 false, this hook will never get called.
|
|
|
774 @end defvar
|
|
|
775
|
|
|
776 @defvar zmacs-update-region-hook
|
|
|
777 This normal hook is called when an active region is "updated" by
|
|
|
778 @code{zmacs-update-region}. This normally gets called at the end
|
|
|
779 of each command that sets @var{zmacs-region-stays} to @code{t},
|
|
|
780 indicating that the region should remain activated. The motion
|
|
|
781 commands do this.
|
|
|
782 @end defvar
|
|
|
783
|
|
|
784
|
