⟦3351e3a12⟧

TextFile

@setfilename ../info/markers
@node Markers, Text, Positions, Top
@chapter Markers

  A @dfn{marker} is a Lisp object used to specify a place in a buffer
relative to the surrounding text.  A marker changes its offset from the
beginning of the buffer automatically when text is inserted or deleted
so it stays with the surrounding characters.

  This is different from a position, which
specifies a static offset from the beginning of the buffer.
@xref{Positions}, for a complete description of positions.

  Markers have two attributes: a marker position, and a marker buffer.
At any given moment, the position is an offset from the beginning of the
buffer.  But the marker position is automatically updated by Emacs as
the buffer is changed.  The idea is that a marker positioned between two
characters in a buffer will remain between those two characters, despite
any changes made to the contents of the buffer.  Thus, a marker's offset
from the beginning of a buffer may change often during its life.

@cindex marker updating
  If the text around a marker is deleted, the marker is repositioned
between the characters before and after the deleted text.  If text is
inserted at the position of a marker, the marker remains in front of the
new text unless it is inserted with @code{insert-before-markers}
(@pxref{Insertion}).  When text is inserted or deleted somewhere before
the marker position (not next to the marker), the marker moves back and
forth with the two surrounding characters.

@cindex marker garbage collection
  When a buffer is modified, the positions of all the markers that
follow the modified region in that buffer must be updated to reflect
their current offsets from the beginning of the buffer.  This slows
processing in a buffer with a large number of markers.  For this reason,
unused markers should be made to point nowhere before they are
discarded.  Unreferenced markers will eventually be garbage collected,
but until then, they will continue to be updated.

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

Here are examples of making, setting and going to markers:

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

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

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

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

;; @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.texinfo>
(eq m1 m2)
     @result{} nil
(equal m1 m2)
     @result{} t

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

@menu
* Predicates on Markers::       
* Functions which Create Markers::      
* Information from Markers::    
* Changing Markers::    
* The Mark::    
* The Region::      
@end menu

@node Predicates on Markers, Functions which Create Markers, Markers, Markers
@section Predicates on Markers

  You can test an object to see whether it is of the type marker; or
whether it is either an integer or a marker.  The latter test is useful
for when you are using the arithmetric 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.  In particular, 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

@node Functions which Create Markers, Information from Markers, Predicates on Markers, Markers
@section Functions which Create Markers

  You can make markers that point nowhere initially, or point to the
present position of point, or point to the the beginning or end of the
accessible region of the buffer.  In addition, you can make a second
marker that points to the same place as a given marker.

@defun make-marker
  This functions returns a newly allocated marker which does not point
anywhere.

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

@defun point-marker
  This function returns a new marker which points to the present
position of the point in the current buffer.  (See the example for
@code{copy-marker}.)
@end defun

@defun point-min-marker
  This function returns a new marker that points to the beginning of the
accessible region of the buffer.  This will be the beginning of the
buffer unless a clipping restriction is in effect (i.e., unless you have
called the @code{narrow-to-region} function or @code{narrow-to-page}
function.)

@example
(point-min-marker)
     @result{} #<marker at 1 in markers.texinfo>
(point-max-marker)
     @result{} #<marker at 4703 in markers.texinfo>

(narrow-to-region 100 200)
     @result{} nil
(point-min-marker)
     @result{} #<marker at 100 in markers.texinfo>
(point-max-marker)
     @result{} #<marker at 200 in markers.texinfo>
@end example
@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 region of the buffer.  This will be the end of the
buffer unless a clipping restriction is in effect (i.e., unless you have
called the @code{narrow-to-region} function or @code{narrow-to-page}
function.)
@end defun

@defun copy-marker marker-or-integer
  If passed a marker as its argument, then @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, then
@code{copy-marker} returns a new marker that points to position
@var{marker-or-integer} in the current buffer.

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

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

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

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

(eq p q)
     @result{} nil

(equal p q)
     @result{} t

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

(copy-marker 10000)
     @result{} #<marker at 2324 in markers.texinfo>
@end example
@end defun

@node Information from Markers, Changing Markers, Functions which Create Markers, Markers
@section Information from Markers

  You can use information from markers to return to a position and a
buffer that you left earlier, even if you have modified the buffer.

@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} is in, or
@code{nil} if it points nowhere.

@example
(setq m (mark-marker))
     @result{} #<marker at 3770 in markers.texinfo>
(marker-buffer m)
     @result{} #<buffer markers.texinfo>
(marker-position m)
     @result{} 3770

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

  Two markers will be found @code{equal} (but not @code{eq}) to each
other if they have the same position and buffer, or if they both point
nowhere.

@node Changing Markers, The Mark, Information from Markers, Markers
@section Changing Markers

When you move the location of an existing marker object, be sure the
marker is not used outside of your program---otherwise, you may cause
unexpected consequences!

@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, then @code{set-marker} will move
marker to the beginning of the buffer.  If the value of @var{position}
is greater than the size of the buffer, then @code{set-marker} will move
marker to the end of the buffer.

  The value returned is @var{marker}.

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

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

@node The Mark, The Region, Changing Markers, Markers
@section The Mark

  A special marker in each buffer is designated the @dfn{mark}.  This
marker is for the user and should not normally be modified by Lisp
programs.  Lisp programs should set the mark only to values that have a
potential use to the user.  For example, the @code{replace-regexp}
command sets mark to the value of point before doing any replacements.
After the command completes, the user can go back to where the command
began by using @kbd{C-x C-x} (@code{exchange-point-and-mark}).

  As a rule, commands should not look at mark directly.  Instead, the
command's definition should use @code{interactive} with the @samp{r}
specification.  This will provide the values of point and mark, and
thereby the region between them.

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

  In addition to the mark, each buffer has a @dfn{mark ring} which is a
list of markers that are the previous values of the mark.  When editing
commands change the mark, normally the old value of the mark should be
saved on the mark ring.  The mark ring may contain no more than the
maximum number of entries specifed by the variable @var{mark-ring-max};
excess entries are discarded on a first-in-first-out basis.

@defun mark
@cindex current buffer mark
  This function returns the position of the current buffer's mark as an
integer.  @code{nil} is returned if the mark is not yet set for this
buffer.
@end defun

@defun mark-marker
  This function returns the current buffer's mark.  A buffer's mark is a
marker and obeys all the rules for markers.  This function does not
return a copy of the mark, but rather the mark itself.  Changing this
marker's position will directly affect region commands such as
@code{kill-region}.

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

  Changing a marker's buffer will yield perfectly consistent,
if rather odd, results.
@end defun

@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 mark on the mark ring.  The
message @samp{Mark set} is also displayed in the echo area.  By
repeating calls to @code{set-mark-command} with an argument, you can
therefore jump to previous marks.  This is very useful.

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

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

  Don't use this function!  That is to say, don't use this function unless
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}.  This is why 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.
Most editing commands should not alter the mark.
To remember a location for internal use in the Lisp program,
store it in a Lisp variable.  Example:

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

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

@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
mark-ring
@result{} (#<marker at 11050 in markers.texinfo> 
    #<marker at 10832 in markers.texinfo>
    @dots{} )
@end example
@end defvar

@defopt mark-ring-max
  The value of this global variable is the maximum size of
@code{mark-ring}.  If more marks than this are pushed onto the
@code{mark-ring}, then it starts discarding marks on a first-in,
first-out basis.
@end defopt

@defun push-mark &optional position nomsg
  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 point is used.

  A @samp{Mark set} message will be 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 change the
buffer's point and does nothing if @code{mark-ring} is empty.
@end defun

@node The Region,  , The Mark, Markers
@section The Region

  The text between point and mark is known as the @dfn{region}.
Various functions operate on text delimited by point and mark; only
those functions specifically related to the region itself are described
here.  See @code{buffer-substring} in @ref{Buffer Contents}.

  Note that few programs ever need to use the @code{region-beginning}
and @code{region-end} functions; and do not be tempted to use these
functions in commands to operate on a region.  Use @code{interactive}
with the @samp{r} specification instead.  (@xref{Interactive Codes}.)

@defun region-beginning
  This function returns the position of the beginning of the region.
This will be the position of either point or 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.  This
will be the position of either point or mark, whichever is larger.

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

DKUUG/EUUG Conference tapes

⟦3351e3a12⟧ TextFile

Derivation

TextFile
