emacs / lispref / markers.texi

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/markers
@node Markers, Text, Positions, Top
@chapter Markers
@cindex markers

  A @dfn{marker} is a Lisp object used to specify a position in a buffer
relative to the surrounding text.  A marker changes its offset from the
beginning of the buffer automatically whenever text is inserted or
deleted, so that it stays with the two characters on either side of it.

@menu
* Overview of Markers::      The components of a marker, and how it relocates.
* Predicates on Markers::    Testing whether an object is a marker.
* Creating Markers::         Making empty markers or markers at certain places.
* Information from Markers:: Finding the marker's buffer or character position.
* Changing Markers::         Moving the marker to a new buffer or position.
* The Mark::                 How ``the mark'' is implemented with a marker.
* The Region::               How to access ``the region''.
@end menu

@node Overview of Markers
@section Overview of Markers

  A marker specifies a buffer and a position in that buffer.  The marker
can be used to represent a position in the functions that require one,
just as an integer could be used.  @xref{Positions}, for a complete
description of positions.

  A marker has two attributes: the marker position, and the marker
buffer.  The marker position is an integer that is equivalent (at a
given time) to the marker as a position in that buffer.  But the
marker's position value can change often during the life of the marker.
Insertion and deletion of text in the buffer relocate the marker.  The
idea is that a marker positioned between two characters remains between
those two characters despite insertion and deletion elsewhere in the
buffer.  Relocation changes the integer equivalent of the marker.

@cindex marker relocation
  Deleting text around a marker's position leaves the marker between the
characters immediately before and after the deleted text.  Inserting
text at the position of a marker normally leaves the marker in front of
the new text---unless it is inserted with @code{insert-before-markers}
(@pxref{Insertion}).

@cindex marker garbage collection
  Insertion and deletion in a buffer must check all the markers and
relocate them if necessary.  This slows processing in a buffer with a
large number of markers.  For this reason, it is a good idea to make a
marker point nowhere if you are sure you don't need it any more.
Unreferenced markers are garbage collected eventually, but until then
will continue to use time if they do point somewhere.

@cindex markers as numbers
  Because it is common to perform arithmetic operations on a marker
position, most of the arithmetic operations (including @code{+} and
@code{-}) accept markers as arguments.  In such cases, the marker
stands for its current position.

Here are examples of creating markers, setting markers, and moving point
to markers:

@example
@group
;; @r{Make a new marker that initially does not point anywhere:}
(setq m1 (make-marker))
     @result{} #<marker in no buffer>
@end group

@group
;; @r{Set @code{m1} to point between the 99th and 100th characters}
;;   @r{in the current buffer:}
(set-marker m1 100)
     @result{} #<marker at 100 in markers.texi>
@end group

@group
;; @r{Now insert one character at the beginning of the buffer:}
(goto-char (point-min))
     @result{} 1
(insert "Q")
     @result{} nil
@end group

@group
;; @r{@code{m1} is updated appropriately.}
m1
     @result{} #<marker at 101 in markers.texi>
@end group

@group
;; @r{Two markers that point to the same position}
;;   @r{are not @code{eq}, but they are @code{equal}.}
(setq m2 (copy-marker m1))
     @result{} #<marker at 101 in markers.texi>
(eq m1 m2)
     @result{} nil
(equal m1 m2)
     @result{} t
@end group

@group
;; @r{When you are finished using a marker, make it point nowhere.}
(set-marker m1 nil)
     @result{} #<marker in no buffer>
@end group
@end example

@node Predicates on Markers
@section Predicates on Markers

  You can test an object to see whether it is a marker, or whether it is
either an integer or a marker.  The latter test is useful in connection
with the arithmetic functions that work with both markers and integers.

@defun markerp object
This function returns @code{t} if @var{object} is a marker, @code{nil}
otherwise.  Note that integers are not markers, even though many
functions will accept either a marker or an integer.
@end defun

@defun integer-or-marker-p object
This function returns @code{t} if @var{object} is an integer or a marker,
@code{nil} otherwise.
@end defun

@defun number-or-marker-p object
This function returns @code{t} if @var{object} is a number (either kind)
or a marker, @code{nil} otherwise.
@end defun

@node Creating Markers
@section Functions That Create Markers

  When you create a new marker, you can make it point nowhere, or point
to the present position of point, or to the beginning or end of the
accessible portion of the buffer, or to the same place as another given
marker.

@defun make-marker
This functions returns a newly created marker that does not point
anywhere.

@example
@group
(make-marker)
     @result{} #<marker in no buffer>
@end group
@end example
@end defun

@defun point-marker
This function returns a new marker that points to the present position
of point in the current buffer.  @xref{Point}.  For an example, see
@code{copy-marker}, below.
@end defun

@defun point-min-marker
This function returns a new marker that points to the beginning of the
accessible portion of the buffer.  This will be the beginning of the
buffer unless narrowing is in effect.  @xref{Narrowing}.
@end defun

@defun point-max-marker
@cindex end of buffer marker
This function returns a new marker that points to the end of the
accessible portion of the buffer.  This will be the end of the buffer
unless narrowing is in effect.  @xref{Narrowing}.

Here are examples of this function and @code{point-min-marker}, shown in
a buffer containing a version of the source file for the text of this
chapter.

@example
@group
(point-min-marker)
     @result{} #<marker at 1 in markers.texi>
(point-max-marker)
     @result{} #<marker at 15573 in markers.texi>
@end group

@group
(narrow-to-region 100 200)
     @result{} nil
@end group
@group
(point-min-marker)
     @result{} #<marker at 100 in markers.texi>
@end group
@group
(point-max-marker)
     @result{} #<marker at 200 in markers.texi>
@end group
@end example
@end defun

@defun copy-marker marker-or-integer
If passed a marker as its argument, @code{copy-marker} returns a
new marker that points to the same place and the same buffer as does
@var{marker-or-integer}.  If passed an integer as its argument,
@code{copy-marker} returns a new marker that points to position
@var{marker-or-integer} in the current buffer.

If passed an integer argument less than 1, @code{copy-marker} returns a
new marker that points to the beginning of the current buffer.  If
passed an integer argument greater than the length of the buffer,
@code{copy-marker} returns a new marker that points to the end of the
buffer.

An error is signaled if @var{marker} is neither a marker nor an
integer.

@example
@group
(setq p (point-marker))
     @result{} #<marker at 2139 in markers.texi>
@end group

@group
(setq q (copy-marker p))
     @result{} #<marker at 2139 in markers.texi>
@end group

@group
(eq p q)
     @result{} nil
@end group

@group
(equal p q)
     @result{} t
@end group

@group
(copy-marker 0)
     @result{} #<marker at 1 in markers.texi>
@end group

@group
(copy-marker 20000)
     @result{} #<marker at 7572 in markers.texi>
@end group
@end example
@end defun

@node Information from Markers
@section Information from Markers

  This section describes the functions for accessing the components of a
marker object.

@defun marker-position marker
This function returns the position that @var{marker} points to, or
@code{nil} if it points nowhere.
@end defun

@defun marker-buffer marker
This function returns the buffer that @var{marker} points into, or
@code{nil} if it points nowhere.

@example
@group
(setq m (make-marker))
     @result{} #<marker in no buffer>
@end group
@group
(marker-position m)
     @result{} nil
@end group
@group
(marker-buffer m)
     @result{} nil
@end group

@group
(set-marker m 3770 (current-buffer))
     @result{} #<marker at 3770 in markers.texi>
@end group
@group
(marker-buffer m)
     @result{} #<buffer markers.texi>
@end group
@group
(marker-position m)
     @result{} 3770
@end group
@end example
@end defun

  Two distinct markers are considered @code{equal} (even though not
@code{eq}) to each other if they have the same position and buffer, or
if they both point nowhere.

@node Changing Markers
@section Changing Marker Positions

  This section describes how to change the position of an existing
marker.  When you do this, be sure you know whether the marker is used
outside of your program, and, if so, what effects will result from
moving it---otherwise, confusing things may happen in other parts of
Emacs.

@defun set-marker marker position &optional buffer
This function moves @var{marker} to @var{position}
in @var{buffer}.  If @var{buffer} is not provided, it defaults to
the current buffer.

If @var{position} is less than 1, @code{set-marker} moves @var{marker}
to the beginning of the buffer.  If @var{position} is greater than the
size of the buffer, @code{set-marker} moves marker to the end of the
buffer.  If @var{position} is @code{nil} or a marker that points
nowhere, then @var{marker} is set to point nowhere.

The value returned is @var{marker}.

@example
@group
(setq m (point-marker))
     @result{} #<marker at 4714 in markers.texi>
@end group
@group
(set-marker m 55)
     @result{} #<marker at 55 in markers.texi>
@end group
@group
(setq b (get-buffer "foo"))
     @result{} #<buffer foo>
@end group
@group
(set-marker m 0 b)
     @result{} #<marker at 1 in foo>
@end group
@end example
@end defun

@defun move-marker marker position &optional buffer
This is another name for @code{set-marker}.
@end defun

@node The Mark
@section The Mark
@cindex mark, the
@cindex mark ring

  One special marker in each buffer is designated @dfn{the mark}.  It
records a position for the user for the sake of commands such as
@kbd{C-w} and @kbd{C-x @key{TAB}}.  Lisp programs should set the mark
only to values that have a potential use to the user, and never for
their own internal purposes.  For example, the @code{replace-regexp}
command sets the mark to the value of point before doing any
replacements, because this enables the user to move back there
conveniently after the replace is finished.

  Many commands are designed so that when called interactively they
operate on the text between point and the mark.  If you are writing such
a command, don't examine the mark directly; instead, use
@code{interactive} with the @samp{r} specification.  This provides the
values of point and the mark as arguments to the command in an
interactive call, but permits other Lisp programs to specify arguments
explicitly.  @xref{Interactive Codes}.

  Each buffer has its own value of the mark that is independent of the
value of the mark in other buffers.  When a buffer is created, the mark
exists but does not point anywhere.  We consider this state as ``the
absence of a mark in that buffer.''

  Once the mark ``exists'' in a buffer, it normally never ceases to
exist.  However, it may become @dfn{inactive}, if Transient Mark mode is
enabled.  The variable @code{mark-active}, which is always local in all
buffers, indicates whether the mark is active: non-@code{nil} means yes.
A command can request deactivation of the mark upon return to the editor
command loop by setting @code{deactivate-mark} to a non-@code{nil} value
(but this causes deactivation only if Transient Mark mode is enabled).

  The main motivation for using Transient Mark mode is that this mode
also enables highlighting of the region when the mark is active.
@xref{Display}.

  In addition to the mark, each buffer has a @dfn{mark ring} which is a
list of markers containing previous values of the mark.  When editing
commands change the mark, they should normally save the old value of the
mark on the mark ring.  The variable @code{mark-ring-max} specifies the
maximum number of entries in the mark ring; once the list becomes this
long, adding a new element deletes the last element.

@defun mark &optional force
@cindex current buffer mark
This function returns the current buffer's mark position as an integer.

If the mark is inactive, @code{mark} normally signals an error.
However, if @var{force} is non-@code{nil}, then @code{mark} returns the
mark position anyway---or @code{nil}, if the mark is not yet set for
this buffer.
@end defun

@defun mark-marker
This function returns the current buffer's mark.  This is the very marker
that records the mark location inside Emacs, not a copy.  Therefore,
changing this marker's position will directly affect the position of the mark.
Don't do it unless that is the effect you want.

@example
@group
(setq m (mark-marker))
     @result{} #<marker at 3420 in markers.texi>
@end group
@group
(set-marker m 100)
     @result{} #<marker at 100 in markers.texi>
@end group
@group
(mark-marker)
     @result{} #<marker at 100 in markers.texi>
@end group
@end example

Like any marker, this marker can be set to point at any buffer you like.
We don't recommend that you make it point at any buffer other than the
one of which it is the mark.  If you do, it will yield perfectly
consistent, but rather odd, results.
@end defun

@ignore
@deffn Command set-mark-command jump
If @var{jump} is @code{nil}, this command sets the mark to the value
of point and pushes the previous value of the mark on the mark ring.  The
message @samp{Mark set} is also displayed in the echo area.

If @var{jump} is not @code{nil}, this command sets point to the value
of the mark, and sets the mark to the previous saved mark value, which
is popped off the mark ring.

This function is @emph{only} intended for interactive use.
@end deffn
@end ignore

@defun set-mark position
This function sets the mark to @var{position}, and activates the mark.
The old value of the mark is @emph{not} pushed onto the mark ring.

@strong{Please note:} Use this function only if you want the user to
see that the mark has moved, and you want the previous mark position to
be lost.  Normally, when a new mark is set, the old one should go on the
@code{mark-ring}.  For this reason, most applications should use
@code{push-mark} and @code{pop-mark}, not @code{set-mark}.

Novice Emacs Lisp programmers often try to use the mark for the wrong
purposes.  The mark saves a location for the user's convenience.  An
editing command should not alter the mark unless altering the mark is
part of the user-level functionality of the command.  (And, in that
case, this effect should be documented.)  To remember a location for
internal use in the Lisp program, store it in a Lisp variable.  For
example:

@example
@group
(let ((beg (point)))
  (forward-line 1)
  (delete-region beg (point))).
@end group
@end example
@end defun

@c for interactive use only
@ignore
@deffn Command exchange-point-and-mark
This function exchanges the positions of point and the mark.
It is intended for interactive use.
@end deffn
@end ignore

@defun push-mark &optional position nomsg activate
This function sets the current buffer's mark to @var{position}, and
pushes a copy of the previous mark onto @code{mark-ring}.  If
@var{position} is @code{nil}, then the value of point is used.
@code{push-mark} returns @code{nil}.

The function @code{push-mark} normally @emph{does not} activate the
mark.  To do that, specify @code{t} for the argument @var{activate}.

A @samp{Mark set} message is displayed unless @var{nomsg} is
non-@code{nil}.
@end defun

@defun pop-mark
This function pops off the top element of @code{mark-ring} and makes
that mark become the buffer's actual mark.  This does not move point in
the buffer, and it does nothing if @code{mark-ring} is empty.  It
deactivates the mark.

The return value is not meaningful.
@end defun

@defopt transient-mark-mode
@cindex Transient Mark mode
This variable if non-@code{nil} enables Transient Mark mode, in which
every buffer-modifying primitive sets @code{deactivate-mark}.  The
consequence of this is that commands that modify the buffer normally
make the mark inactive.
@end defopt

@defvar deactivate-mark
If an editor command sets this variable non-@code{nil}, then the editor
command loop deactivates the mark after the command returns, but only if
Transient Mark mode is enabled.
@end defvar

@defun deactivate-mark
This function deactivates the mark, but only if Transient Mark mode
is enabled.
@end defun

@defvar mark-active
The mark is active when this variable is non-@code{nil}.  This variable
is always local in each buffer.
@end defvar

@defvar activate-mark-hook
@defvarx deactivate-mark-hook
These normal hooks are run, respectively, when the mark becomes active
and when it becomes inactive.  The hook @code{activate-mark-hook} is also
run at the end of a command if the mark is active and the region may
have changed.
@end defvar

@defvar mark-ring
The value of this buffer-local variable is the list of saved former
marks of the current buffer, most recent first.

@example
@group
mark-ring
@result{} (#<marker at 11050 in markers.texi> 
    #<marker at 10832 in markers.texi>
    @dots{})
@end group
@end example
@end defvar

@defopt mark-ring-max
The value of this variable is the maximum size of @code{mark-ring}.  If
more marks than this are pushed onto the @code{mark-ring},
@code{push-mark} discards an old mark when it adds a new one.
@end defopt

@node The Region
@section The Region
@cindex region, the

  The text between point and the mark is known as @dfn{the region}.
Various functions operate on text delimited by point and the mark, but
only those functions specifically related to the region itself are
described here.

@defun region-beginning
This function returns the position of the beginning of the region (as
an integer).  This is the position of either point or the mark,
whichever is smaller.

If the mark does not point anywhere, an error is signaled.
@end defun

@defun region-end
This function returns the position of the end of the region (as an
integer).  This is the position of either point or the mark, whichever is
larger.

If the mark does not point anywhere, an error is signaled.
@end defun

  Few programs need to use the @code{region-beginning} and
@code{region-end} functions.  A command designed to operate on a region
should normally use @code{interactive} with the @samp{r} specification
to find the beginning and end of the region.  This lets other Lisp
programs specify the bounds explicitly as arguments.  (@xref{Interactive
Codes}.)
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.