|
DataMuseum.dkPresents historical artifacts from the history of: DKUUG/EUUG Conference tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about DKUUG/EUUG Conference tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - downloadIndex: T l
Length: 51359 (0xc89f)
Types: TextFile
Names: »lispref-14«
└─⟦a05ed705a⟧ Bits:30007078 DKUUG GNU 2/12/89
└─⟦c06c473ab⟧ »./UNRELEASED/lispref.tar.Z«
└─⟦1b57a2ffe⟧
└─⟦this⟧ »lispref-14«
Info file: lispref, -*-Text-*-
produced by texinfo-format-buffer
from file: lispref.texinfo
This file documents GNU Emacs Lisp.
This is Edition 0.1 Beta of the GNU Emacs Lisp Reference Manual, for
Emacs Version 18, with some references to Emacs Version 19.
Please read this document for review purposes.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1989 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Foundation.
▶1f◀
File: lispref Node: Motion, Prev: Point, Up: Positions, Next: Excursions
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::
▶1f◀
File: lispref Node: Character Motion, Prev: Motion, Up: Motion, Next: Lines
Motion by Characters
--------------------
* Command: goto-char POSITION
This function sets point in the current buffer to that position
in the current buffer. If 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, POSITION is the numeric prefix
argument, if provided; otherwise it is read from the minibuffer.
`goto-char' returns POSITION.
* Command: forward-char &optional COUNT
This function moves point forward, towards the end of the buffer,
COUNT characters (or backward, towards the beginning of the buffer,
if 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 `beginning-of-buffer' or `end-of-buffer'.
When called interactively, COUNT is the numeric prefix argument.
* Command: backward-char &optional COUNT
This function moves point backward, towards the beginning of the
buffer, COUNT characters (or forward, towards the end of the
buffer, if 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 `beginning-of-buffer' or `end-of-buffer'.
When called interactively, COUNT is the numeric prefix argument.
* Command: forward-word COUNT
This function moves point forward COUNT words (or backward if
COUNT is negative). Normally it returns `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
`nil' is returned.
When called interactively, COUNT is set to the numeric prefix
argument.
* Command: backward-word COUNT
This function is the exact analog to `forward-word', save that it
moves backward until encountering the front of a word.
When called interactively, COUNT is set to the numeric prefix
argument.
In programs, it is faster to call `forward-word' with negative
argument, as that is all that this function does anyway.
* 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 N is non-`nil', then
it puts point N tenths of the way from the beginning of the buffer.
When called interactively, N is the numeric prefix argument, if
provided; otherwise N defaults to `nil'.
Don't use this in Lisp programs! `(goto-char (point-min))' is
faster and does not set the mark.
* 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 N is non-`nil', then it puts
the point N tenths of the way from the end.
When called interactively, N is the numeric prefix argument, if
provided; otherwise N defaults to `nil'.
Don't use this in Lisp programs! `(goto-char (point-max))' is
faster and does not set the mark.
▶1f◀
File: lispref Node: Lines, Prev: Character Motion, Up: Motion, Next: Goal Column
Lines
-----
Also see `bolp' and `eolp' in *Note Point::.
* Command: goto-line LINE
This function sets point to the front of the LINE'th line,
counting from line 1 at beginning of buffer. If 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
*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 LINE and the line
number of the line to which point actually was able move, ignoring
any clipping restriction.
When called interactively, LINE is the numeric prefix argument if
one has been provided. Otherwise LINE is prompted for.
* Command: beginning-of-line &optional COUNT
This function moves point to the beginning of the current line.
With an argument COUNT not `nil' or 1, it moves forward, towards
the end of the buffer, (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.
* Command: end-of-line &optional COUNT
This function moves point to the end of the current line. With
an argument COUNT not `nil' or 1, it moves forward, towards the end
of the buffer, (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.
* Command: forward-line &optional COUNT
This function moves point to the first column of a line, COUNT
lines forward, towards the end of the buffer, from the present
position. If COUNT is negative, it moves that many lines up.
If there are not that 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).
`forward-line' returns the difference between 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, COUNT will be the numeric prefix
argument.
* Function: vertical-motion COUNT
This function moves point to the start of the line COUNT screen
lines down. If 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, `vertical-motion' is essentially the same
as `forward-line'.
The `vertical-motion' function returns the number of lines moved.
It may be closer to zero than COUNT if the beginning or end of the
buffer was reached.
* 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 COUNT lines from the top of the window. If COUNT is
negative, point moves either to the beginning of the line -COUNT
lines from the bottom or else to the last line of the buffer if
that point is beyond the end of buffer.
If COUNT is `nil', then point moves to the beginning of the line
in the middle of the window. If the absolute value of 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, 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.
* Function: count-lines START END
This function returns the number of lines between the positions
START and END (which are character offsets from the beginning of
the buffer) in the current buffer. If START and END are the same,
then it returns 0. Otherwise it returns at least 1, even if START
and END are on the same line.
(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))
▶1f◀
File: lispref Node: Goal Column, Prev: Lines, Up: Motion, Next: List Motion
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 `next-line' and
`previous-line'.
* Variable: 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 `nil', then the
commands set their own goal columns. Any other value is invalid.
* Variable: temporary-goal-column
This global variable determines the temporary goal column for
vertical motions commands. It is overridden by `goal-column' if
that is non-`nil', and it is set to 9999 if `track-eol' is
non-`nil'. It is set each time a vertical motion command is
invoked, unless the previous command was also a vertical motion
command.
* Variable: track-eol
This global variable controls how the vertical motion commands
(`next-line' and `previous-line') operate when starting at the end
of a line. If `track-eol' is non-`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.
* Command: set-goal-column UNSET
This command sets the permanent goal column for vertical
movement. If UNSET is `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 UNSET is non-`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, UNSET is the unprocessed prefix argument.
▶1f◀
File: lispref Node: List Motion, Prev: Goal Column, Up: Motion, Next: Skipping Characters
Moving over Lists and Other Balanced Expressions
-------------------------------------------------
Here are several functions concerned with Lisp expressions. *Note
Editing Programs: (emacs)Lists and SexpsAlso *Note Streams::, for
descriptions of related functions; and *Note Syntax Tables::, which
control how these function move across text.
* Command: forward-list ARG
Move forward across ARG balanced groups of parentheses.
* Command: backward-list ARG
Move backward across ARG balanced groups of parentheses.
* Command: up-list ARG
Move forward out of ARG levels of parentheses. A negative argument
means move backward but still to a less deep spot.
* Command: down-list ARG
Move forward down ARG levels of parentheses. A negative argument
means move backward but still go down a level.
* Command: forward-sexp ARG
Move forward across ARG balanced expressions.
* Command: backward-sexp ARG
Move backward across ARG balanced expressions.
▶1f◀
File: lispref Node: Skipping Characters, Prev: List Motion, Up: Motion
Skipping Characters
-------------------
The following two functions move point over a specified set of
characters, such as whitespace characters.
* Function: 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 CHARACTER-SET,
then point is advanced and the next character is examined. This
continues until a character is found that is not matched.
CHARACTER-SET is like the inside of a `[...]' in a regular
expression except that `]' is never special and `\' quotes `^', `-'
or `\'. Thus, `"a-zA-Z"' skips over all letters, stopping before
the first nonletter, and `"^a-zA-Z'" skips nonletters stopping
before the first letter.
If 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 LIMIT.
In the example, point is located directly before the `T'. After
evaluating the form, it is located at the end of that line (between
the `t' of `hat' and the newline). This regexp skipped all letters
and spaces, but not newlines.
---------- Buffer: foo ----------
I read "-!-The cat in the hat
comes back" twice.
---------- Buffer: foo ----------
(skip-chars-forward "a-zA-Z ")
=> nil
---------- Buffer: foo ----------
I read "The cat in the hat-!-
comes back" twice.
---------- Buffer: foo ----------
* Function: skip-chars-backward CHARACTER-SET &optional LIMIT
This function moves the point backwards, skipping all characters
in CHARACTER-SET. It is the exact analog of `skip-chars-forward'.
▶1f◀
File: lispref Node: Excursions, Prev: Motion, Up: Positions, Next: Clipping Restrictions
Excursions
==========
Sometimes you need to move point temporarily to another position
within the current buffer or to another buffer entirely. An "excursion"
is such a temporary movement. The `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 (*Note Window Configurations::).
* Special form: save-excursion FORMS...
The `save-excursion' special form saves the values of point and
mark of the current buffer, records the identity of the buffer,
evaluates 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 `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
`save-excursion', so any changes made to point and mark in the
other buffers will remain after `save-excursion' exits.
`save-excursion' does not restore window-buffer correspondences
destroyed by functions such as `switch-to-buffer'. One way to
restore the selected window is to use `save-window-excursion'
inside `save-excursion' (*Note Window Configurations::).
The value returned by `save-excursion' is the result of the last
evaluated form, or `nil' if no FORMS are given.
(save-excursion
FORMS)
==
(let ((old-buf (current-buffer))
(old-pnt (point))
(old-mark (marker-position (mark))))
(unwind-protect
(progn FORMS)
(set-buffer old-buf)
(goto-char old-pnt)
(set-marker (mark) old-mark)
))
▶1f◀
File: lispref Node: Clipping Restrictions, Prev: Excursions, Up: Positions
Clipping Restrictions
=====================
"Narrowing" is the act of limiting the text addressable by Emacs
editing commands to a limited range of characters in a buffer. This is
also known as setting a "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. `Undo'
is an example of this (*Note 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.
* Command: narrow-to-region START END
This function sets the current clipping restriction to start at
START and end at END. Both should be character positions.
When called interactively, START and END are set to the current
region (`region-beginning' and `region-end').
* Command: narrow-to-page MOVE-COUNT
This function sets the clipping restriction to include just the
current page. An optional first argument MOVE-COUNT non-`nil'
means to move forward or backward that many pages, then narrow.
When called interactively, MOVE-COUNT is set to the processed
prefix argument.
* Command: widen
This function removes the clipping restrictions from the current
buffer.
* Special form: save-restriction FORMS...
This special form saves the current clipping restriction,
evaluates 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 *not* restored; use
`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 `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, `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 `point-min-marker' and
`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 `unwind-protect'
function as a safeguard in the event of an abnormal exit.
Note that if you use both `save-restriction' and
`save-excursion', `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 `save-restriction' is that returned by the
last evaluated form, or `nil' if no forms were given.
---------- 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 ----------
▶1f◀
File: lispref Node: Markers, Prev: Positions, Up: Top, Next: Text
Markers
*******
A "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. *Note 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.
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 `insert-before-markers' (*Note
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.
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.
Because it is quite common to perform arithmetic operations on a
marker position, most of the arithmetic operations (such as, `+' and
`-') 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:
;; Make a new marker that, initially does not point anywhere:
(setq m1 (make-marker))
=> #<marker in no buffer>
;; Set `m1' to point between the 100th and 101st characters.
;; in the current buffer:
(set-marker m1 100)
=> #<marker at 100 in markers.texinfo>
;; Now insert one character at the beginning of the buffer:
(goto-char (point-min))
=> 1
(insert "Q")
=> nil
;; `m1' is updated appropriately.
m1
=> #<marker at 101 in markers.texinfo>
;; Two markers that point to the same position
;; are not `eq', but they are `equal'.
(setq m2 (copy-marker m1))
=> #<marker at 101 in markers.texinfo>
(eq m1 m2)
=> nil
(equal m1 m2)
=> t
;; When you are finished using a marker, make it point nowhere.
(set-marker m1 nil)
=> #<marker in no buffer>
* Menu:
* Predicates on Markers::
* Functions which Create Markers::
* Information from Markers::
* Changing Markers::
* The Mark::
* The Region::
▶1f◀
File: lispref Node: Predicates on Markers, Prev: Markers, Up: Markers, Next: Functions which Create Markers
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.
* Function: markerp OBJECT
This function returns `t' if OBJECT is a marker, `nil' otherwise.
In particular, integers are not markers, even though many functions
will accept either a marker or an integer.
* Function: integer-or-marker-p OBJECT
This function returns `t' if OBJECT is an integer or a marker,
`nil' otherwise.
▶1f◀
File: lispref Node: Functions which Create Markers, Prev: Predicates on Markers, Up: Markers, Next: Information from Markers
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.
* Function: make-marker
This functions returns a newly allocated marker which does not
point anywhere.
(make-marker)
=> #<marker in no buffer>
* Function: 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
`copy-marker'.)
* Function: 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 `narrow-to-region' function or
`narrow-to-page' function.)
(point-min-marker)
=> #<marker at 1 in markers.texinfo>
(point-max-marker)
=> #<marker at 4703 in markers.texinfo>
(narrow-to-region 100 200)
=> nil
(point-min-marker)
=> #<marker at 100 in markers.texinfo>
(point-max-marker)
=> #<marker at 200 in markers.texinfo>
* Function: point-max-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 `narrow-to-region' function or `narrow-to-page'
function.)
* Function: copy-marker MARKER-OR-INTEGER
If passed a marker as its argument, then `copy-marker' returns a
new marker that points to the same place and the same buffer as
does MARKER-OR-INTEGER. If passed an integer as its argument, then
`copy-marker' returns a new marker that points to position
MARKER-OR-INTEGER in the current buffer.
If passed an argument that is an integer whose value is less than
1, then `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
`copy-marker' returns a new marker that points to the end of the
buffer.
It is an error if MARKER is neither a marker nor an integer.
(setq p (point-marker))
=> #<marker at 2139 in markers.texinfo>
(setq q (copy-marker p))
=> #<marker at 2139 in markers.texinfo>
(eq p q)
=> nil
(equal p q)
=> t
(copy-marker 0)
=> #<marker at 1 in markers.texinfo>
(copy-marker 10000)
=> #<marker at 2324 in markers.texinfo>
▶1f◀
File: lispref Node: Information from Markers, Prev: Functions which Create Markers, Up: Markers, Next: Changing Markers
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.
* Function: marker-position MARKER
This function returns the position that MARKER points to, or
`nil' if it points nowhere.
* Function: marker-buffer MARKER
This function returns the buffer that MARKER is in, or `nil' if
it points nowhere.
(setq m (mark-marker))
=> #<marker at 3770 in markers.texinfo>
(marker-buffer m)
=> #<buffer markers.texinfo>
(marker-position m)
=> 3770
(setq m (make-marker))
=> #<marker in no buffer>
(marker-position m)
=> nil
(marker-buffer m)
=> nil
Two markers will be found `equal' (but not `eq') to each other if they
have the same position and buffer, or if they both point nowhere.
▶1f◀
File: lispref Node: Changing Markers, Prev: Information from Markers, Up: Markers, Next: The Mark
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!
* Function: set-marker MARKER POSITION &optional BUFFER
This function moves MARKER to POSITION in BUFFER. If BUFFER is
not provided, it defaults to the current buffer.
If POSITION is less than 1, then `set-marker' will move marker to
the beginning of the buffer. If the value of POSITION is greater
than the size of the buffer, then `set-marker' will move marker to
the end of the buffer.
The value returned is MARKER.
(setq m (point-marker))
=> #<marker at 4714 in markers.texinfo>
(set-marker m 55)
=> #<marker at 55 in markers.texinfo>
(setq b (get-buffer "foo"))
=> #<buffer foo>
(set-marker m 0 b)
=> #<marker at 1 in foo>
* Function: move-marker MARKER POSITION &optional BUFFER
This is another name for `set-marker'.
▶1f◀
File: lispref Node: The Mark, Prev: Changing Markers, Up: Markers, Next: The Region
The Mark
========
A special marker in each buffer is designated the "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 `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 `C-x
C-x' (`exchange-point-and-mark').
As a rule, commands should not look at mark directly. Instead, the
command's definition should use `interactive' with the `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 "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 MARK-RING-MAX; excess
entries are discarded on a first-in-first-out basis.
* Function: mark
This function returns the position of the current buffer's mark
as an integer. `nil' is returned if the mark is not yet set for
this buffer.
* Function: 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 `kill-region'.
(setq m (mark-marker))
=> #<marker at 3420 in markers.texinfo>
(set-marker m 100)
=> #<marker at 100 in markers.texinfo>
(mark-marker)
=> #<marker at 100 in markers.texinfo>
Changing a marker's buffer will yield perfectly consistent, if
rather odd, results.
* Command: set-mark-command JUMP
If JUMP is `nil' this command sets the mark to the value of point
and pushes the previous value of mark on the mark ring. The
message `Mark set' is also displayed in the echo area. By
repeating calls to `set-mark-command' with an argument, you can
therefore jump to previous marks. This is very useful.
This function is intended for interactive use, *only*.
* Function: set-mark POSITION
This function sets the mark to POSITION. The old value of the
mark is *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
`mark-ring'. This is why most applications should use `push-mark'
and `pop-mark', not `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:
(let ((beg (point)))
(forward-line 1)
(delete-region beg (point))).
* Variable: mark-ring
The value of this buffer-local variable is the list of saved
former marks of the current buffer, most recent first.
mark-ring
=> (#<marker at 11050 in markers.texinfo>
#<marker at 10832 in markers.texinfo>
... )
* User Option: mark-ring-max
The value of this global variable is the maximum size of
`mark-ring'. If more marks than this are pushed onto the
`mark-ring', then it starts discarding marks on a first-in,
first-out basis.
* Function: push-mark &optional POSITION NOMSG
This function sets the current buffer's mark to POSITION, and
pushes a copy of the previous mark onto `mark-ring'. If POSITION
is `nil', then the point is used.
A `Mark set' message will be displayed unless NOMSG is non-`nil'.
* Function: pop-mark
This function pops off the top element of `mark-ring' and makes
that mark become the buffer's actual mark. This does not change
the buffer's point and does nothing if `mark-ring' is empty.
▶1f◀
File: lispref Node: The Region, Prev: The Mark, Up: Markers
The Region
==========
The text between point and mark is known as the "region". Various
functions operate on text delimited by point and mark; only those
functions specifically related to the region itself are described here.
See `buffer-substring' in *Note Buffer Contents::.
Note that few programs ever need to use the `region-beginning' and
`region-end' functions; and do not be tempted to use these functions in
commands to operate on a region. Use `interactive' with the `r'
specification instead. (*Note Interactive Codes::.)
* Function: 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.
* Function: 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.
▶1f◀
File: lispref Node: Text, Prev: Markers, Up: Top, Next: Searching and Matching
Text
****
This chapter is about those functions that deal with the text of a
buffer. Most of these functions insert or delete text in whichever
buffer is current. Most of them are interactive functions and perform
their changes either directly in front of or directly following point.
Some text-related functions put text into the "kill ring", others do
not; but all the changes they make can be undone so long as the buffer
has undo enabled (*Note Undo::.)
Many text-related functions operate on a region of text defined by two
locations in the buffer, named START and END. These arguments should be
either markers or or numeric character positions that count from the
beginning of the buffer.
Since text-related functions always operate on the text between the
two locations, START and END, the order in which the locations are given
is not important. For example, `(delete-region 1 10)' and
`(delete-region 10 1)' perform identically. It is an
`args-out-of-range' error if either location does not indicate an
existing position in the buffer.
Throughout this chapter, `text' refers to the characters in the
buffer.
* Menu:
* Insertion::
* Deletion::
* The Kill Ring::
* Undo::
* Auto Filling::
* Filling::
* Sorting::
* Indentation::
* Indent Tabs::
* Columns::
* Case Changes::
* Underlining::
* Registers::
▶1f◀
File: lispref Node: Insertion, Prev: Text, Up: Text, Next: Deletion
Insertion
=========
Insertion takes place at point; normally markers which pointed at point
before the insertion end up pointing before the inserted text. Point
may end up either before or after inserted text, depending on the
function used.
* Function: insert &rest ARGS
This function inserts any number of strings or characters into
the current buffer, at point, moving point forward. It is an error
unless all ARGS are either strings or characters.
Any markers pointing after point are relocated. Any markers
pointing at point or before are unchanged.
* Function: insert-before-markers &rest ARGS
This function inserts any number of strings or characters into
the current buffer, at point, moving point forward. It is an error
unless all ARGS are either strings or characters.
Unlike `insert', any markers whose position equals point are
relocated to come after the newly inserted text.
* Function: insert-char CHARACTER COUNT
This function inserts COUNT instances of CHARACTER into the
current buffer before the point. COUNT must be a number, and
CHARACTER must be a character.
* Command: copy-to-buffer TO-BUFFER START END
This function copies text from the current buffer to TO-BUFFER.
TO-BUFFER is first erased (with no questions asked), and then the
text in the region defined by START and END is inserted into that
buffer.
When called interactively, TO-BUFFER is prompted for in the
minibuffer, and START and END are bound to the value of the point
and mark (i.e., to the values of the beginning and end of the
region).
* Function: insert-buffer-substring FROM-BUFFER-OR-NAME START END
This function inserts a substring of FROM-BUFFER-OR-NAME (which
must exist) into the current buffer before the point. The string
is those characters in the region defined by START and END.
In the example, the form is executed with buffer `bar' as the
current buffer. We assume that buffer `bar' is initially empty.
---------- Buffer: foo ----------
We hold these truths to be self-evident, that all
---------- Buffer: foo ----------
(insert-buffer-substring "foo" 1 20)
=> nil
---------- Buffer: bar ----------
We hold these truth
---------- Buffer: bar ----------
* Function: insert-buffer FROM-BUFFER-OR-NAME
This function inserts the entire contents of FROM-BUFFER-OR-NAME
(which must exist) into the current buffer after the point. It
leaves the mark after the inserted text.
* Command: quoted-insert COUNT
This function reads the next input character verbatim and
inserts it. It is primarily useful for inserting control
characters. You may also type up to 3 octal digits, to insert a
character with that code.
COUNT is the number of these characters to insert. It is an
error if COUNT is not a number, or if the current buffer is
read-only.
Programs rarely want to use this function, but might want to put
it on a keymap.
This function is primarily for interactive use.
* Command: self-insert-command COUNT
This function inserts the last character typed COUNT times. This
is the function that most printing characters are bound to.
Programs rarely want to use this, but might want to put it on a
keymap.
This function calls `auto-fill-hook'. (In version 19,
`auto-fill-function' has been renamed `auto-fill-function' since it
is not called by the `run-hooks' function.)
In everyday use, `self-insert-command' is the most frequently
called function in Emacs!
▶1f◀
File: lispref Node: Commands for Insertion
Commands for Insertion
----------------------
* Command: newline &optional NUMBER-OF-NEWLINES
This function inserts newlines into the current buffer before the
point. If NUMBER-OF-NEWLINES is supplied (and is a number), that
many newline characters are inserted.
In Auto Fill mode, `newline' can break the preceding line if
COUNT is not supplied.
When called interactively, COUNT is the processed prefix
argument.
* Command: split-line
This function splits the current line, moving the portion of the
line after point down vertically, so that it is on the next line
directly below where it was before. Whitespace is inserted at the
beginning of the lower line as needed by the `indent-to' function
with a combination of tabs and spaces. `split-line' returns the
position of point.
In the example, point is located between the `t' and the `h' when
`(split-line)' is called. The second line in the result contains
one tab and one space before the `h'. Point is still located at
the end of the first line, directly after the `t'.
---------- Buffer: foo ----------
This is t-!-he line before
---------- Buffer: foo ----------
(split-line)
=> 4433
---------- Buffer: foo ----------
This is t-!-
he line before
---------- Buffer: foo ----------
Programs hardly ever use this function.
* Command: open-line COUNT
This function inserts COUNT newlines into the current buffer
after point, leaving point where it was.
When called interactively, COUNT is the processed prefix
argument. Programs hardly ever use this function.
* Command: overwrite-mode ARGUMENT
This function turns overwrite mode on and off. If ARGUMENT is a
positive number (greater than zero), then it is turned on,
otherwise it is turned off. In overwrite mode, typed-in printable
characters replace existing text character for character, and do
not push the existing text to the right.
This function only effects the self-insertion command.
When called interactively, ARGUMENT is set to the processed
prefix argument.
▶1f◀
File: lispref Node: Deletion, Prev: Insertion, Up: Text, Next: The Kill Ring
Deletion
========
All of the deletion functions operate on the current buffer, and they
all return a value of `nil'. None of them put their deleted text into
the kill ring unless otherwise noted.
In general, functions that have ``delete'' in their names do not put
text into the kill ring, while corresponding functions with ``kill'' in
their names do (compare: `delete-region' and `kill-region'). From
programs, you will usually want to use a ``delete'' function as opposed
to a ``kill'' function, since the kill ring is for the user.
* Function: erase-buffer
This function deletes the entire text of the current buffer. If
the buffer is read-only, it signals a `buffer-read-only' error.
Otherwise it does not complain, even if erasing a buffer visiting a
modified file. It does not kill the buffer.
* Command: delete-region START END
This function deletes the text in the current buffer in the
region defined by START and END.
* Command: delete-horizontal-space
This function deletes all spaces and tabs around point.
In the examples, point is between the second and third characters
on each of the lines when the function is called.
---------- Buffer: foo ----------
I -!-thought
I -!- thought
We-!- thought
Yo-!-u thought
---------- Buffer: foo ----------
(delete-horizontal-space)
=> nil
---------- Buffer: foo ----------
Ithought
Ithought
Wethought
You thought
---------- Buffer: foo ----------
* Command: delete-indentation &optional JOIN-FOLLOWING-P
This function joins the line point is on to the previous line and
deletes all the whitespace at the join, save for one space. If
JOIN-FOLLOWING-P is non-`nil', `delete-indentation' joins this line
to following line instead.
In the example below, point is located on the line starting
`events', and it makes no difference if there are trailing spaces.
---------- Buffer: foo ----------
When in the course of human
-!- events, it becomes necessary
---------- Buffer: foo ----------
(delete-indentation)
=> nil
---------- Buffer: foo ----------
When in the course of human-!- events, it becomes necessary
---------- Buffer: foo ----------
* Function: fixup-whitespace
This function replaces white space between the objects on either
side of point with either one space or no space as appropriate.
The function leaves one space if point is in the middle of a line
that has printing characters somewhere before and after it (except
in a few cases described below). When point is at the beginning or
end of a line, this function leaves no spaces.
`fixup-whitespace' does not leave any space when point is located
directly after a character whose syntax class is ``open
parenthesis'' `(', directly before a character whose syntax class
is ``close parenthesis'' `)', or directly before a character whose
syntax class is ``Expression Prefix Operator'' `''.
In the example, point starts out at the beginning of the second
line, when `fixup-whitespace' is called the first time. It is
located directly after the `(' for the second invocation.
---------- Buffer: foo ----------
This has too many spaces
-!- at the front of this line
This has too many spaces at the start of (-!- this list)
---------- Buffer: foo ----------
(fixup-whitespace)
=> nil
(fixup-whitespace)
=> nil
---------- Buffer: foo ----------
This has too many spaces
at the front of this line
This has too many spaces at the start of (this list)
---------- Buffer: foo ----------
* Command: just-one-space
Delete all spaces and tabs around point, leaving one space.
* Command: delete-blank-lines
This function deletes blank lines surrounding point. If point is
on a blank line with one or more blank lines before or after it,
then all but one of them are deleted. If point is on an isolated
blank line, then it is deleted. If point is on a nonblank line, it
deletes all blank lines following it.
A blank line is defined as any line consisting of a newline and
nothing else except tabs and spaces.
`delete-blank-lines' returns `nil'.
* Command: delete-char COUNT &optional KILLP
This function deletes COUNT characters directly after point
(before, if COUNT is negative).
If KILLP is non-`nil', then it saves the deleted characters in
the kill ring.
When called interactively, COUNT is the processed prefix
argument, and KILLP is set to `t' if COUNT is greater than 1.
* Command: delete-backward-char COUNT &optional KILLP
This function deletes COUNT characters directly before point
(after, if COUNT is negative).
If KILLP is non-`nil', then it saves the deleted characters in
the kill ring.
When called interactively, COUNT is the processed prefix
argument, and KILLP is set to `t' if COUNT is greater than 1.
* Command: backward-delete-char-untabify COUNT &optional KILLP
This function deletes COUNT characters backward, changing tabs
into spaces. When changing tabs into spaces, a sufficient number
of spaces are inserted into the buffer to keep point in the same
column. These spaces are then deleted by `delete-backward-char'.
If COUNT is negative, then tabs are not changed to spaces, and
the characters are deleted by calling `delete-backward-char' with
COUNT.
If KILLP is non-`nil', then it saves the deleted characters in
the kill ring.
When called interactively, COUNT is the processed prefix
argument, and KILLP is set to `t' if COUNT is greater than 1.
▶1f◀