⟦d27a2362a⟧

TextFile

@setfilename ../info/positions
@node Positions, Markers, Windows, Top
@chapter Positions

  A @dfn{position} is a number denoting the offset of a character from
the beginning of a buffer.  The position of the first character in a
buffer is @code{1}.  Positions are always between two characters (or
before the first character in the buffer, or after the last character of
the buffer).  The character referred to as @emph{at} or @emph{after} a
position is always the one immediately following the position.

  Markers are another way to represent positions; they relocate
automatically when text is inserted or deleted so they stay with the
surrounding characters.  @xref{Markers}.

@menu
* Point::                       Special position
* Motion::                      Changing point
* Excursions::                  Temporary motion and buffer changes
* Clipping Restrictions::       Restricting point to a region
@end menu

@node Point, Motion, Positions, Positions
@section Point

@cindex self-insert at point
  @dfn{Point} is a special buffer position used by many editing
commands, including the self-inserting typed characters and text
insertion functions.  Other commands move point through the text, so
that you can edit at different places in it.

  Like other positions, point is always between two characters (or before
the first character in the buffer, or after the last character of the
buffer).  Many terminals display the cursor over the character that
immediately follows point; on such terminals, point is between the
character on which the cursor sits and the preceding character.

@cindex point in restriction
  Each buffer has a value of point, which is independent of the value of
point in other buffers.  The value of point is always between @code{1}
and the buffer size plus one (@pxref{Buffer Contents}).  If there is a
clipping restriction in effect (@pxref{Clipping Restrictions}), then 
point is always constrained to fall between the restriction boundaries.

  Each window also has a value of point, which is independent of the
value of point in other windows on the same buffer.  This is why point
can be in different places in each window that shows a given buffer.
When a buffer appears in only one window, the buffer's point and the
window's point normally have the same value, so the distinction is
rarely important.  @xref{Window Point}, for more details.

@defun point
@cindex current buffer position
  This function returns the position of point in the current buffer,
as an integer.

@example
(point)
     @result{} 175
@end example
@end defun

@defun bobp
  This function returns @code{t} if the point is at the beginning of the
buffer.  If a clipping restriction is in effect, this means the beginning
of the visible text.  Also, see @code{point-min} in @ref{Buffer Contents}.
@end defun

@defun eobp
  This function returns @code{t} if point is at the end of the buffer.
If a clipping restriction is in effect, this means the end of visible
text.  Also, see @code{point-max} in @xref{Buffer Contents}.
@end defun

@defun bolp
  This function returns @code{t} if the point is at the beginning of a line.
@end defun

@defun eolp
  This function returns @code{t} if the point is at the end of a line.
The end of the buffer is always considered the end of a line.
@end defun

  Many functions are provided to look at the characters around point.
Three simple functions are described here.  Also,
@pxref{Searching and Matching}.

@defun char-after position
  This function returns the character in the current buffer at position
@var{position}.  If @var{position} does not specify a character in the
buffer, then it returns @code{nil}.

  (Remember that point is always between characters or before the first
character in a buffer; therefore, on many terminals, the character
returned by @code{char-after} is the character the cursor is over.)

  In the example, the first character in the buffer is @kbd{@@}.
@example
(char-to-string (char-after 1))
     @result{} "@@"
@end example
@end defun

@defun following-char
  This function returns the character following point in the current
buffer.  This is similar to @code{(char-after (point))}.  However, point
is the last position of the buffer, then the result of
@code{following-char} is @code{0}.

  In this example, the point is between the @kbd{a} and the @kbd{c}.

@example
Gentlemen may cry ``Pe@point{}ace! Peace!,'' but there is no peace.

(char-to-string (preceding-char))
     @result{} "a"
(char-to-string (following-char))
     @result{} "c"
@end example
@end defun

@defun preceding-char
   This function returns the character preceding point in the
current buffer.  See @code{following-char} for an example.  If point is the
first position of the buffer, then the result of @code{preceding-char}
is @code{0}.
@end defun

@node Motion, Excursions, Point, Positions
@section Motion

  Motion functions change the value of point, either relative to the
current value of point, relative to the beginning or end of the buffer,
or relative to the edges of the selected window.

@menu
* Character Motion::
* Lines::	
* Goal Column::	
* List Motion::	
* Skipping Characters::	
@end menu

@node Character Motion, Lines, Motion, Motion
@subsection Motion by Characters

@deffn Command goto-char position
  This function sets point in the current buffer to that position in the
current buffer.  If @var{position} is less than 1, then point is set to
the beginning of the buffer.  If it is greater than the length of the
buffer, then point is set to the end of the buffer.

  If a clipping restriction is in effect, then the position is still
measured from the beginning of the buffer, but any position specified
outside of the clipped region will result in point being placed at
either the beginning or the end of the clipped region.

  When called interactively, @var{position} is the numeric prefix argument,
if provided; otherwise it is read from the minibuffer.

@code{goto-char} returns @var{position}.
@end deffn

@deffn Command forward-char &optional count
@cindex beginning-of-buffer error
@cindex end-of-buffer error
  This function moves point forward, towards the end of the buffer,
@var{count} characters (or backward, towards the beginning of the
buffer, if @var{count} is negative).  If the function attempts to move
point past the beginning or end of the buffer (or the limits of the
accessible region when a restriction is in effect), an error is
signaled, with error code @code{beginning-of-buffer} or
@code{end-of-buffer}.

  When called interactively, @var{count} is the numeric prefix argument.
@end deffn

@deffn Command backward-char &optional count
  This function moves point backward, towards the beginning of the
buffer, @var{count} characters (or forward, towards the end of the
buffer, if @var{count} is negative).  If the function attempts to move
point past the beginning or end of the buffer (or the limits of the
accessible region when a restriction is in effect), an error is
signaled, with error code @code{beginning-of-buffer} or
@code{end-of-buffer}.

  When called interactively, @var{count} is the numeric prefix argument.
@end deffn

@deffn Command forward-word count
  This function moves point forward @var{count} words (or backward if
@var{count} is negative).  Normally it returns @code{t}.  If point
encounters the beginning or end of the buffer or the limits of the
accessible region when a restriction is in effect, point is left there
and @code{nil} is returned.

  When called interactively, @var{count} is set to the numeric prefix
argument.
@end deffn

@deffn Command backward-word count
  This function is the exact analog to @code{forward-word}, save that it
moves backward until encountering the front of a word.

  When called interactively, @var{count} is set to the numeric prefix
argument.

  In programs, it is faster to call @code{forward-word} with negative
argument, as that is all that this function does anyway.
@end deffn

@deffn Command beginning-of-buffer &optional n
  This function moves point to the beginning of the buffer (or the
limits of the accessible region when a restriction is in effect),
leaving the mark at the previous position.  If @var{n} is
non-@code{nil}, then it puts point @var{n} tenths of the way from the
beginning of the buffer.

  When called interactively, @var{n} is the numeric prefix argument,
if provided; otherwise @var{n} defaults to @code{nil}.

  Don't use this in Lisp programs!  @code{(goto-char (point-min))} is
faster and does not set the mark.
@end deffn

@deffn Command end-of-buffer &optional n
  This function moves point to the end of the buffer (or the limits of
the accessible region when a restriction is in effect), leaving the mark
at the previous position.  If @var{n} is non-@code{nil}, then it puts
the point @var{n} tenths of the way from the end.

  When called interactively, @var{n} is the numeric prefix argument,
if provided; otherwise @var{n} defaults to @code{nil}.

  Don't use this in Lisp programs!  @code{(goto-char (point-max))} is
faster and does not set the mark.
@end deffn

@node Lines, Goal Column, Character Motion, Motion
@subsection Lines
@cindex lines

  Also see @code{bolp} and @code{eolp} in @ref{Point}.

@deffn Command goto-line line
  This function sets point to the front of the @var{line}'th line,
counting from line 1 at beginning of buffer.  If @var{line} is less than 1,
then point is set to the top of the buffer.  If it is greater than the
number of lines in the buffer, then point is set to the @emph{end of
the last line} of the buffer.

  If a clipping restriction is in effect, then the line is still
measured from the beginning of the buffer, but any line specified
outside of the clipped region will result in point being placed at
either the beginning or end of the clipped region.

  The return value is the difference between @var{line} and the line
number of the line to which point actually was able move, ignoring any
clipping restriction.

  When called interactively, @var{line} is the numeric prefix argument if
one has been provided.  Otherwise @var{line} is prompted for.
@end deffn

@deffn Command beginning-of-line &optional count
  This function moves point to the beginning of the current line.  With
an argument @var{count} not @code{nil} or 1, it moves forward, towards
the end of the buffer, (@var{count} - 1) lines first.  If it reaches the
end of the buffer (or end of the accessible region if a restriction is
in effect), it positions point at the beginning of the last line.  No
error is signaled.
@end deffn

@deffn Command end-of-line &optional count
  This function moves point to the end of the current line.  With an
argument @var{count} not @code{nil} or 1, it moves forward, towards the
end of the buffer, (@var{count} - 1) lines first.  If it reaches the end
of the buffer (or end of the accessible region if a restriction is in
effect), it positions point at the end of the last line.  No error is
signaled.
@end deffn

@deffn Command forward-line &optional count
@cindex beginning of line
  This function moves point to the first column of a line,
@var{count} lines forward, towards the
end of the buffer, from the present position.  If @var{count} is
negative, it moves that many lines up.

  If there are not that @var{count} available to mover over in the
buffer (or the the accessible region if a restriction is in effect),
then the function moves point to the beginning (or end) of the buffer
(or end of the accessible region if a restriction is in effect).

  @code{forward-line} returns the difference between @var{count} and the
number of lines actually moved.  If you attempt to move down five lines
from thebeginning of a buffer that has only three lines, point will
positioned at the end of the last line, and a value of 2 will be
returned.

  When called interactively, @var{count} will be the numeric
prefix argument.
@end deffn

@defun vertical-motion count
  This function moves point to the start of the line @var{count}
screen lines down.  If @var{count} is negative, it moves up.

  If Emacs is continuing a long line of text onto a second or third line
on the diplay, rather than truncating it, this function will move point
according to the number of lines of the display, not the number of lines
that are terminated by newlines characters.

  Because continuation depends on the width of the display and whether
truncation is set, this function may work different in different windows.

  If truncation is set, @code{vertical-motion} is essentially the same
as @code{forward-line}.

  The @code{vertical-motion} function returns the number of lines moved.
It may be closer to zero than @var{count} if the beginning or end of the
buffer was reached.
@end defun

@deffn Command move-to-window-line count
  This function repositions point relative to the text currently
displayed in the selected window.  Point is moved to the beginning of
the line @var{count} lines from the top of the window.  If @var{count}
is negative, point moves either to the beginning of the line
@w{@minus{}@var{count}} lines from the bottom or else to the last line
of the buffer if that point is beyond the end of buffer.

  If @var{count} is @code{nil}, then point moves to the beginning of
the line in the middle of the window.  If the absolute value of @var{count}
is greater than the size of the window, then the window scrolls and
that line goes to the middle of the window.

  When called interactively, @var{count} gets the value of the processed prefix
argument.

  The result of the function call is the window line number, with the
top line in the window numbered 0.
@end deffn

@defun count-lines start end
@cindex lines in region
  This function returns the number of lines between the positions @var{start}
and @var{end} (which are character offsets from the beginning of the
buffer) in the current buffer.  If @var{start} and @var{end} are the same,
then it returns 0.  Otherwise it returns at least 1, even if @var{start}
and @var{end} are on the same line.

@example
@findex window-start @r{example}
@findex current-column @r{example}
(defun current-line ()
  "Return the vertical position of point in the selected window.  
Top line is 0.  Counts each text line only once, even if it wraps."
  (+ (count-lines (window-start) (point))
     (if (= (current-column) 0) 1 0)
     -1))
@end example
@end defun

@ignore
@c ================
The @code{previous-line} and @code{next-line} commands are functions
that should not be used in programs.  They are for users and are
mentioned here only for completeness.

@deffn Command previous-line count
@cindex goal column
  This function moves point up @var{count} lines (down if @var{count}
is negative).  In moving, it attempts to keep point in the ``goal column''
(normally the same column that it was at the beginning of the move).

  If there is no character in the target line exactly under the current
column, point is positioned after the character in that line which
spans this column, or at the end of the line if it is not long enough.

  If it attempts to move beyond the top or bottom of the buffer (or clipped
region), then point is positioned in the goal column in the top or
bottom line.  No error is signaled.

  When called interactively, @var{count} will be the numeric
prefix argument.

  The command @code{set-goal-column} can be used to create a semipermanent
goal column to which this command always moves.  Then it does not try to
move vertically.

  If you are thinking of using this in a Lisp program, consider using
@code{forward-line} with a negative argument instead.  It is usually easier
to use and more reliable (no dependence on goal column, etc.).
@end deffn

@deffn Command next-line count
  This function moves point down @var{count} lines (up if @var{count}
is negative).  In moving, it attempts to keep point in the ``goal column''
(normally the same column that it was at the beginning of the move).

  If there is no character in the target line exactly under the current
column, point is positioned after the character in that line which
spans this column, or at the end of the line if it is not long enough.

  If it attempts to move beyond the top or bottom of the buffer (or clipped
region), then point is positioned in the goal column in the top or
bottom line.  No error is signaled.

  In the case where the @var{count} is 1, and point is on the last
line of the buffer (or clipped region), a new empty line is inserted at the
end of the buffer (or clipped region) and point moved there.

  When called interactively, @var{count} will be the numeric
prefix argument.

  The command @code{set-goal-column} can be used to create a semipermanent
goal column to which this command always moves.  Then it does not try to
move vertically.

  If you are thinking of using this in a Lisp program, consider using
@code{forward-line} instead.  It is usually easier
to use and more reliable (no dependence on goal column, etc.).
@end deffn

@c ================
@end ignore

@node Goal Column, List Motion, Lines, Motion
@comment  node-name,  next,  previous,  up
@subsection Goal Column
@cindex goal column

  A goal column is useful if you want to edit a region of text, such as
a table, in which you want to move point to a certain column on each
line.  The goal column affects the commands @code{next-line} and
@code{previous-line}.

@defvar goal-column
  This global variable determines the goal column for vertical motion
commands.  If it is an integer, than all vertical motion commands have
this as their goal.  If it is @code{nil}, then the commands set their
own goal columns.  Any other value is invalid.
@end defvar

@defvar temporary-goal-column
  This global variable determines the temporary goal column for vertical
motions commands.  It is overridden by @code{goal-column} if that is
non-@code{nil}, and it is set to 9999 if @code{track-eol} is
non-@code{nil}.  It is set each time a vertical motion command is
invoked, unless the previous command was also a vertical motion command.
@end defvar

@defvar track-eol
@cindex vertical motion column
  This global variable controls how the vertical motion commands
(@code{next-line} and @code{previous-line}) operate when starting at the
end of a line.  If @code{track-eol} is non-@code{nil}, then vertical
motion starting at the end of a line will keep to the ends of lines.
This means moving to the end of each line moved onto.
@end defvar

@deffn Command set-goal-column unset
  This command sets the permanent goal column for vertical movement.  If
@var{unset} is @code{nil}, then the goal column is set to the current
column of point.  All future vertical motion commands will have that
column as their goal, untill the setting is canceled.

  If @var{unset} is non-@code{nil}, then the permanent goal column is
cleared, and vertical motion commands resume their normal operation.

  This function is for interactive use; and when called interactively,
@var{unset} is the unprocessed prefix argument.
@end deffn

@node List Motion, Skipping Characters, Goal Column, Motion
@comment  node-name,  next,  previous,  up
@subsection Moving over Lists and Other Balanced Expressions 
@cindex sexps
@cindex Lisp expressions
@cindex list moving

  Here are several functions concerned with Lisp expressions.
@xref{Lists and Sexps,,Editing Programs, emacs, GNU Emacs User Manual}
Also @pxref{Streams}, for descriptions of related functions; and
@pxref{Syntax Tables}, which control how these function move across
text.

@deffn Command forward-list arg
Move forward across @var{arg} balanced groups of parentheses.
@end deffn

@deffn Command backward-list arg
Move backward across @var{arg} balanced groups of parentheses.
@end deffn

@deffn Command up-list arg
@cindex parenthesis depth
Move forward out of @var{arg} levels of parentheses.
A negative argument means move backward but still to a less deep spot.
@end deffn

@deffn Command down-list arg
Move forward down @var{arg} levels of parentheses.
A negative argument means move backward but still go down a level.
@end deffn

@deffn Command forward-sexp arg
Move forward across @var{arg} balanced expressions.
@end deffn

@deffn Command backward-sexp arg
Move backward across @var{arg} balanced expressions.
@end deffn

@node Skipping Characters,  , List Motion, Motion
@comment  node-name,  next,  previous,  up
@subsection Skipping Characters
@cindex skipping characters

  The following two functions move point over a specified set of
characters, such as whitespace characters.

@defun skip-chars-forward character-set &optional limit
  This function moves the point in the current buffer forward, skipping
over a given set of characters.   Emacs first examines the character following
the point.  If it is matched by @var{character-set}, then point is advanced and
the next character is examined.  This continues until a character is found
that is not matched.

  @var{character-set} is like the inside of a @samp{[...]} in a regular
expression except that @samp{]} is never special and @samp{\} quotes
@samp{^}, @samp{-} or @samp{\}.  Thus, @samp{"a-zA-Z"} skips over all
letters, stopping before the first nonletter, and @samp{"^a-zA-Z}" skips
nonletters stopping before the first letter.

  If @var{limit} is supplied (it must be a number or a marker), it will be
the maximum position in the buffer that point can be skipped to.  
Point will stop at or before @var{limit}.

  In the example,  point is located directly before the @samp{T}.  After
evaluating the form, it is located at the end of that line (between the
@samp{t} of @samp{hat} and the newline).  This regexp skipped all
letters and spaces, but not newlines.

@example
---------- Buffer: foo ----------
I read "@point{}The cat in the hat
comes back" twice.
---------- Buffer: foo ----------

(skip-chars-forward "a-zA-Z ")
     @result{} nil

---------- Buffer: foo ----------
I read "The cat in the hat@point{}
comes back" twice.
---------- Buffer: foo ----------

@end example
@end defun

@defun skip-chars-backward character-set &optional limit
  This function moves the point backwards, skipping all characters in
@var{character-set}.  It is the exact analog of @code{skip-chars-forward}.
@end defun



@node Excursions, Clipping Restrictions, Motion, Positions
@section Excursions

  Sometimes you need to move point temporarily to another position
within the current buffer or to another buffer entirely.  An
@dfn{excursion} is such a temporary movement.  The @code{save-excursion}
function is used to keep track of the current buffer and its values of
point and mark, so they can be restored after the completion of the
excursion.

  The forms for saving and restoring the configuration of windows are
described elsewhere (@pxref{Window Configurations}).

@defspec save-excursion forms@dots{}
@cindex mark excursion
@cindex point excursion
@cindex current buffer excursion

  The @code{save-excursion} special form saves the values of point and
mark of the current buffer, records the identity of the buffer,
evaluates @var{forms}, and then restores the buffer with the saved
values of point and mark.  The buffer and its values of point and mark
are restored even in case of an abnormal exit (via throw or error).

  The @code{save-excursion} special form is used more than 500 times in
the Lisp sources.  It is the standard way to restore the current buffer
and the values of point and mark after you have changed the position of
point in the current buffer or changed the buffer.  

  The values of point and mark for other buffers are not saved by
@code{save-excursion}, so any changes made to point and mark in the
other buffers will remain after @code{save-excursion} exits.

@cindex window excursions
  @code{save-excursion} does not restore window-buffer correspondences
destroyed by functions such as @code{switch-to-buffer}.  One way to restore the
selected window is to use @code{save-window-excursion} inside
@code{save-excursion} (@pxref{Window Configurations}).

  The value returned by @code{save-excursion} is the result of the last
evaluated form, or @code{nil} if no @var{forms} are given.

@example
(save-excursion
  @var{forms})
@equiv{}      
(let ((old-buf (current-buffer))
      (old-pnt (point))
      (old-mark (marker-position (mark))))
  (unwind-protect
      (progn @var{forms})
    (set-buffer old-buf)
    (goto-char old-pnt)
    (set-marker (mark) old-mark)
    ))
@end example
@end defspec

@node Clipping Restrictions,  , Excursions, Positions
@section Clipping Restrictions

  @dfn{Narrowing} is the act of limiting the text addressable by Emacs
editing commands to a limited range of characters in a buffer.  This is
@cindex restrictions
also known as setting a @dfn{clipping restriction}.  A clipping restriction
is denoted by two buffer positions which are the beginning and end of the
restriction.  For most editing commands these positions replace the values
of the beginning and end of the buffer.  However, some commands use the true
beginning and end of the buffer but signal an error if an attempt is made to
modify text outside the clipping restriction.  @code{Undo} is an example of
this (@pxref{Undo}).

  While a clipping restriction is in effect, no text outside the region
is displayed.  No buffer motion functions set the value of point outside
the current clipping restriction.  Functions that return buffer
positions are not affected by clipping restrictions.  The position
returned is always relative to the true beginning of the buffer.

  Buffer saving commands are unaffected by narrowing; the entire buffer
is saved regardless of the current clipping restriction.

@deffn Command narrow-to-region start end
  This function sets the current clipping restriction to start at
@var{start} and end at @var{end}.  Both should be character positions.

  When called interactively, @var{start} and @var{end} are set to the
current region (@code{region-beginning} and @code{region-end}).
@end deffn

@deffn Command narrow-to-page move-count
  This function sets the clipping restriction to include just the current
page.  An optional first argument @var{move-count} non-@code{nil} means to
move forward or backward that many pages, then narrow.

  When called interactively, @var{move-count} is set to the processed prefix
argument.
@end deffn

@deffn Command widen
@cindex remove clipping restriction
  This function removes the clipping restrictions from the current buffer.
@end deffn

@defspec save-restriction forms@dots{}
  This special form saves the current clipping restriction, evaluates
@var{forms} and restores the clipping restriction.  The clipping restriction
is restored even in the event of abnormal exit (throw or error).  Point and
mark are @emph{not} restored; use @code{save-excursion} for that.
This is the standard way to arrange that the clipping restriction be
automatically restored if you need to temporarily change it.

  The @code{save-restriction} special form stores the values of the
beginning and end of the restriction as distances from the beginning and
of the buffer.  It records the amount of invisible text.  This is the
right thing to do if you want to do further narrowing.

  However, @code{save-restriction} can be confused if, within the body,
you widen and then make changes outside the area of the saved
restrictions.  Instead, if you want to widen a restriction and change
text, you may want to use the @code{point-min-marker} and
@code{point-min-marker} functions to return markers to the beginning and
end of the clipped region.  Even after text has been added or removed,
the markers will continue to point to the beginning and end of the
region.  In addition, you could use the @code{unwind-protect} function
as a safeguard in the event of an abnormal exit.

  Note that if you use both @code{save-restriction} and
@code{save-excursion}, @code{save-excursion} should come first.
Otherwise, the old form would be restored with the temporary restriction
in effect, and that action might move point as a side effect.

  The value returned by @code{save-restriction} is that returned by the
last evaluated form, or @code{nil} if no forms were given.

@example
---------- Buffer: foo ----------
This is the contents of foo
This is the contents of foo
This is the contents of foo
---------- Buffer: foo ----------

(save-excursion
  (save-restriction
    (narrow-to-region 1 80)
    (goto-char (point-min))
    (replace-string "foo" "bar")))

---------- Buffer: foo ----------
This is the contents of bar
This is the contents of bar
This is the contents of foo
---------- Buffer: foo ----------
@end example

@end defspec
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦d27a2362a⟧ TextFile

Derivation

TextFile
