This chapter describes the functions that deal with the text in a buffer. Most examine, insert, or delete text in the current buffer, often in the vicinity of point. Many are interactive. All the functions that change the text provide for undoing the changes (see section Undo).
Many text-related functions operate on a region of text defined
by two buffer positions passed in arguments named start
and end. These arguments should be either markers (see
section Markers) or numeric
character positions (see section Positions). The order of these
arguments does not matter; it is all right for start to
be the end of the region and end the beginning. For
example, (delete-region 1 10) and (delete-region
10 1) are equivalent. An args-out-of-range
error is signaled if either start or end is
outside the accessible portion of the buffer. In an interactive
call, point and the mark are used for these arguments.
Throughout this chapter, "text" refers to the characters in the buffer, together with their properties (when relevant).
Many functions are provided to look at the characters around
point. Several simple functions are described here. See also
looking-at in section Regular Expression Searching.
nil. The
default for position is point. In the following example, assume that the first character in the buffer is `@':
(char-to-string (char-after 1))
=> "@"
nil. The default for
position is point.
(char-after (point)). However, if point is at the end
of the buffer, then following-char returns 0. Remember that point is always between characters, and the
terminal cursor normally appears over the character following
point. Therefore, the character returned by
following-char is the character the cursor is
over.
In this example, point is between the `a' and the `c'.
---------- Buffer: foo ----------
Gentlemen may cry ``Pea-!-ce! Peace!,''
but there is no peace.
---------- Buffer: foo ----------
(char-to-string (preceding-char))
=> "a"
(char-to-string (following-char))
=> "c"
following-char, for an example. If point is at the
beginning of the buffer, preceding-char returns
0.
t if point is at the beginning of the buffer. If
narrowing is in effect, this means the beginning of the accessible
portion of the text. See also point-min in section Point.
t if point is at the end of the buffer. If narrowing
is in effect, this means the end of accessible portion of the text.
See also point-max in See section Point.
t if point is at the beginning of a line. See section
Motion by Text Lines. The beginning
of the buffer (or of its accessible portion) always counts as the
beginning of a line.
t if point is at the end of a line. The end of the
buffer (or of its accessible portion) is always considered the end
of a line.
This section describes two functions that allow a Lisp program to convert any portion of the text in the buffer into a string.
buffer-substring signals an
args-out-of-range error. It is not necessary for start to be less than end; the arguments can be given in either order. But most often the smaller argument is written first.
If the text being copied has any text properties, these are copied into the string along with the characters they belong to. See section Text Properties. However, overlays (see section Overlays) in the buffer and their properties are ignored, not copied.
---------- Buffer: foo ---------- This is the contents of buffer foo ---------- Buffer: foo ---------- (buffer-substring 1 10) => "This is t" (buffer-substring (point-max) 10) => "he contents of buffer foo "
buffer-substring, except that it does not copy text
properties, just the characters themselves. See section Text Properties.
(buffer-substring (point-min) (point-max))
---------- Buffer: foo ----------
This is the contents of buffer foo
---------- Buffer: foo ----------
(buffer-string)
=> "This is the contents of buffer foo
"
The argument thing is a symbol which specifies a kind
of syntactic entity. Possibilities include symbol,
list, sexp, defun,
filename, url, word,
sentence, whitespace, line,
page, and others.
---------- Buffer: foo ----------
Gentlemen may cry ``Pea-!-ce! Peace!,''
but there is no peace.
---------- Buffer: foo ----------
(thing-at-point 'word)
=> "Peace"
(thing-at-point 'line)
=> "Gentlemen may cry ``Peace! Peace!,''\n"
(thing-at-point 'whitespace)
=> nil
This function lets you compare portions of the text in a buffer, without copying them into strings first.
nil for buffer1, buffer2, or
both to stand for the current buffer. The value is negative if the first substring is less, positive if the first is greater, and zero if they are equal. The absolute value of the result is one plus the index of the first differing characters within the substrings.
This function ignores case when comparing characters if
case-fold-search is non-nil. It always
ignores text properties.
Suppose the current buffer contains the text `foobarbar haha!rara!'; then in this example the two substrings are `rbar ' and `rara!'. The value is 2 because the first substring is greater at the second character.
(compare-buffer-substring nil 6 11 nil 16 21)
=> 2
Insertion means adding new text to a buffer. The inserted text goes at point--between the character before point and the character after point. Some insertion functions leave point before the inserted text, while other functions leave it after. We call the former insertion after point and the latter insertion before point.
Insertion relocates markers that point at positions after the
insertion point, so that they stay with the surrounding text (see
section Markers). When a marker
points at the place of insertion, insertion may or may not relocate
the marker, depending on the marker's insertion type (see section
Marker Insertion Types). Certain
special functions such as insert-before-markers
relocate all such markers to point after the inserted text,
regardless of the markers' insertion type.
Insertion functions signal an error if the current buffer is read-only.
These functions copy text characters from strings and buffers along with their properties. The inserted characters have exactly the same properties as the characters they were copied from. By contrast, characters specified as separate arguments, not part of a string or buffer, inherit their text properties from the neighboring text.
The insertion functions convert text from unibyte to multibyte in order to insert in a multibyte buffer, and vice versa--if the text comes from a string or from a buffer. However, they do not convert unibyte character codes 128 through 255 to multibyte characters, not even if the current buffer is a multibyte buffer. See section Converting Text Representations.
nil.
nil. This function is unlike the other insertion functions in that it relocates markers initially pointing at the insertion point, to point after the inserted text. If an overlay begins the insertion point, the inserted text falls outside the overlay; if a nonempty overlay ends at the insertion point, the inserted text falls inside that overlay.
nil means 1), and character must be
a character. The value is nil. This function does not convert unibyte character codes 128 through 255 to multibyte characters, not even if the current buffer is a multibyte buffer. See section Converting Text Representations.
If inherit is non-nil, then the inserted
characters inherit sticky text properties from the two characters
before and after the insertion point. See section Stickiness of Text Properties.
nil.
In this 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 ----------
See section Stickiness of Text Properties, for other insertion functions that inherit text properties from the nearby text in addition to inserting it. Whitespace inserted by indentation functions also inherits text properties.
This section describes higher-level commands for inserting text, commands intended primarily for the user but useful also in Lisp programs.
nil.
nil.
Most printing characters are bound to this command. In routine use,
self-insert-command is the most frequently called
function in Emacs, but programs rarely use it except to install it
on a keymap. In an interactive call, count is the numeric prefix argument.
This command calls auto-fill-function whenever that
is non-nil and the character inserted is a space or a
newline (see section Auto
Filling).
This command performs abbrev expansion if Abbrev mode is enabled and the inserted character does not have word-constituent syntax. (See section Abbrevs And Abbrev Expansion, and section Table of Syntax Classes.)
This is also responsible for calling
blink-paren-function when the inserted character has
close parenthesis syntax (see section Blinking Parentheses).
This function calls
auto-fill-function if the current column number is
greater than the value of fill-column and
number-of-newlines is nil. Typically what
auto-fill-function does is insert a newline; thus, the
overall result in this case is to insert two newlines at different
places: one at point, and another earlier in the line.
newline does not auto-fill if
number-of-newlines is non-nil.
This command indents to the left margin if that is not zero. See section Margins for Filling.
The value returned is nil. In an interactive call,
count is the numeric prefix argument.
indent-to function.
split-line returns the position of point. Programs hardly ever use this function.
overwrite-mode-textual,
overwrite-mode-binary, or nil.
overwrite-mode-textual specifies textual overwrite
mode (treats newlines and tabs specially), and
overwrite-mode-binary specifies binary overwrite mode
(treats newlines and tabs like any other characters).
Deletion means removing part of the text in a buffer, without saving it in the kill ring (see section The Kill Ring). Deleted text can't be yanked, but can be reinserted using the undo mechanism (see section Undo). Some deletion functions do save text in the kill ring in some special cases.
All of the deletion functions operate on the current buffer, and
all return a value of nil.
buffer-read-only error.
Otherwise, it deletes the text without asking for any confirmation.
It returns nil. Normally, deleting a large amount of text from a buffer inhibits
further auto-saving of that buffer "because it has shrunk".
However, erase-buffer does not do this, the idea being
that the future text is not really related to the former text, and
its size should not be compared with that of the former text.
nil.
If point was inside the deleted region, its value afterward is
start. Otherwise, point relocates with the surrounding
text, as markers do.
nil, then it saves the deleted characters in the
kill ring. In an interactive call, count is the numeric prefix argument, and killp is the unprocessed prefix argument. Therefore, if a prefix argument is supplied, the text is saved in the kill ring. If no prefix argument is supplied, then one character is deleted, but not saved in the kill ring.
The value returned is always nil.
nil, then it saves the deleted characters in the
kill ring. In an interactive call, count is the numeric prefix argument, and killp is the unprocessed prefix argument. Therefore, if a prefix argument is supplied, the text is saved in the kill ring. If no prefix argument is supplied, then one character is deleted, but not saved in the kill ring.
The value returned is always nil.
nil, then the command saves the deleted characters
in the kill ring. Conversion of tabs to spaces happens only if count is positive. If it is negative, exactly -count characters after point are deleted.
In an interactive call, count is the numeric prefix argument, and killp is the unprocessed prefix argument. Therefore, if a prefix argument is supplied, the text is saved in the kill ring. If no prefix argument is supplied, then one character is deleted, but not saved in the kill ring.
The value returned is always nil.
backward-delete-char-untabify should deal with
whitespace. Possible values include untabify, the
default, meaning convert a tab to many spaces and delete one;
hungry, meaning delete all the whitespace characters
before point with one command, and nil, meaning do
nothing special for whitespace characters.
This section describes higher-level commands for deleting text, commands intended primarily for the user but useful also in Lisp programs.
nil. In the following examples, we call
delete-horizontal-space four times, once on each line,
with point between the second and third characters on the line each
time.
---------- Buffer: foo ----------
I -!-thought
I -!- thought
We-!- thought
Yo-!-u thought
---------- Buffer: foo ----------
(delete-horizontal-space) ; Four times.
=> nil
---------- Buffer: foo ----------
Ithought
Ithought
Wethought
You thought
---------- Buffer: foo ----------
nil,
delete-indentation joins this line to the following
line instead. The function returns nil. If there is a fill prefix, and the second of the lines being
joined starts with the prefix, then delete-indentation
deletes the fill prefix before joining the lines. See section Margins for Filling.
In the example below, point is located on the line starting `events', and it makes no difference if there are trailing spaces in the preceding line.
---------- 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 ----------
After the lines are joined, the function
fixup-whitespace is responsible for deciding whether
to leave a space at the junction.
nil. At the beginning or end of a line, the appropriate amount of space is none. Before a character with close parenthesis syntax, or after a character with open parenthesis or expression-prefix syntax, no space is also appropriate. Otherwise, one space is appropriate. See section Table of Syntax Classes.
In the example below, fixup-whitespace is called
the first time with point before the word `spaces' in
the first line. For the second invocation, point is directly after
the `('.
---------- Buffer: foo ----------
This has too many -!-spaces
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
This has too many spaces at the start of (this list)
---------- Buffer: foo ----------
nil.
A blank line is defined as a line containing only tabs and spaces.
delete-blank-lines returns nil.
Kill functions delete text like the deletion functions, but save it so that the user can reinsert it by yanking. Most of these functions have `kill-' in their name. By contrast, the functions whose names start with `delete-' normally do not save text for yanking (though they can still be undone); these are "deletion" functions.
Most of the kill commands are primarily for interactive use, and are not described here. What we do describe are the functions provided for use in writing such commands. You can use these functions to write commands for killing text. When you need to delete text for internal purposes within a Lisp function, you should normally use deletion functions, so as not to disturb the kill ring contents. See section Deleting Text.
Killed text is saved for later yanking in the kill
ring. This is a list that holds a number of recent kills, not
just the last text kill. We call this a "ring" because yanking
treats it as having elements in a cyclic order. The list is kept in
the variable kill-ring, and can be operated on with
the usual functions for lists; there are also specialized
functions, described in this section, that treat it as a ring.
Some people think this use of the word "kill" is unfortunate, since it refers to operations that specifically do not destroy the entities "killed". This is in sharp contrast to ordinary life, in which death is permanent and "killed" entities do not come back to life. Therefore, other metaphors have been proposed. For example, the term "cut ring" makes sense to people who, in pre-computer days, used scissors and paste to cut up and rearrange manuscripts. However, it would be difficult to change the terminology now.
The kill ring records killed text as strings in a list, most recent first. A short kill ring, for example, might look like this:
("some text" "a different piece of text" "even older text")
When the list reaches kill-ring-max entries in
length, adding a new entry automatically deletes the last
entry.
When kill commands are interwoven with other commands, each kill command makes a new entry in the kill ring. Multiple kill commands in succession build up a single kill-ring entry, which would be yanked as a unit; the second and subsequent consecutive kill commands add text to the entry made by the first one.
For yanking, one entry in the kill ring is designated the "front" of the ring. Some yank commands "rotate" the ring by designating a different element as the "front." But this virtual rotation doesn't change the list itself--the most recent entry always comes first in the list.
kill-region is the usual subroutine for killing
text. Any command that calls this function is a "kill command" (and
should probably have `kill' in its name).
kill-region puts the newly killed text in a new
element at the beginning of the kill ring or adds it to the most
recent element. It determines automatically (using
last-command) whether the previous command was a kill
command, and if so appends the killed text to the most recent
entry.
nil. In an interactive call, start and end are point and the mark.
If the buffer is read-only, kill-region modifies
the kill ring just the same, then signals an error without
modifying the buffer. This is convenient because it lets the user
use all the kill commands to copy text into the kill ring from a
read-only buffer.
nil, kill-region does not get an
error if the buffer is read-only. Instead, it simply returns,
updating the kill ring but not changing the buffer.
nil. It also indicates the
extent of the text copied by moving the cursor momentarily, or by
displaying a message in the echo area. The command does not set this-command to
kill-region, so a subsequent kill command does not
append to the same kill ring entry.
Don't call copy-region-as-kill in Lisp programs
unless you aim to support Emacs 18. For newer Emacs versions, it is
better to use kill-new or kill-append
instead. See section Low-Level Kill
Ring.
Yanking means reinserting an entry of previously killed text from the kill ring. The text properties are copied too.
If arg is a list (which occurs interactively when the
user types C-u with no digits), then yank
inserts the text as described above, but puts point before the
yanked text and puts the mark after it.
If arg is a number, then yank inserts
the argth most recently killed text--the
argth element of the kill ring list.
yank does not alter the contents of the kill ring
or rotate it. It returns nil.
This is allowed only immediately after a yank or
another yank-pop. At such a time, the region contains
text that was just inserted by yanking. yank-pop
deletes that text and inserts in its place a different piece of
killed text. It does not add the deleted text to the kill ring,
since it is already in the kill ring somewhere.
If arg is nil, then the replacement text
is the previous element of the kill ring. If arg is
numeric, the replacement is the argth previous kill. If
arg is negative, a more recent kill is the
replacement.
The sequence of kills in the kill ring wraps around, so that after the oldest one comes the newest one, and before the newest one goes the oldest.
The return value is always nil.
These functions and variables provide access to the kill ring at a lower level, but still convenient for use in Lisp programs, because they take care of interaction with window system selections (see section Window System Selections).
current-kill rotates the yanking pointer, which
designates the "front" of the kill ring, by n places
(from newer kills to older ones), and returns the text at that
place in the ring. If the optional second argument do-not-move is
non-nil, then current-kill doesn't alter
the yanking pointer; it just returns the nth kill,
counting from the current yanking pointer.
If n is zero, indicating a request for the latest
kill, current-kill calls the value of
interprogram-paste-function (documented below) before
consulting the kill ring.
interprogram-cut-function (see
below).
nil, it goes at the
beginning. This function also invokes the value of
interprogram-cut-function (see below).
nil or a
function of no arguments. If the value is a function, current-kill calls it
to get the "most recent kill". If the function returns a
non-nil value, then that value is used as the "most
recent kill". If it returns nil, then the first
element of kill-ring is used.
The normal use of this hook is to get the window system's primary selection as the most recent kill, even if the selection belongs to another application. See section Window System Selections.
nil or a
function of one argument. If the value is a function, kill-new and
kill-append call it with the new first element of the
kill ring as an argument.
The normal use of this hook is to set the window system's primary selection from the newly killed text. See section Window System Selections.
The variable kill-ring holds the kill ring
contents, in the form of a list of strings. The most recent kill is
always at the front of the list.
The kill-ring-yank-pointer variable points to a
link in the kill ring list, whose CAR is the text to yank next. We
say it identifies the "front" of the ring. Moving
kill-ring-yank-pointer to a different link is called
rotating the kill ring. We call the kill ring a "ring"
because the functions that move the yank pointer wrap around from
the end of the list to the beginning, or vice-versa. Rotation of
the kill ring is virtual; it does not change the value of
kill-ring.
Both kill-ring and
kill-ring-yank-pointer are Lisp variables whose values
are normally lists. The word "pointer" in the name of the
kill-ring-yank-pointer indicates that the variable's
purpose is to identify one element of the list for use by the next
yank command.
The value of kill-ring-yank-pointer is always
eq to one of the links in the kill ring list. The
element it identifies is the CAR of that link. Kill commands, which
change the kill ring, also set this variable to the value of
kill-ring. The effect is to rotate the ring so that
the newly killed text is at the front.
Here is a diagram that shows the variable
kill-ring-yank-pointer pointing to the second entry in
the kill ring ("some text" "a different piece of text" "yet
older text").
kill-ring ---- kill-ring-yank-pointer
| |
| v
| --- --- --- --- --- ---
--> | | |------> | | |--> | | |--> nil
--- --- --- --- --- ---
| | |
| | |
| | -->"yet older text"
| |
| --> "a different piece of text"
|
--> "some text"
This state of affairs might occur after C-y
(yank) immediately followed by M-y
(yank-pop).
kill-ring, and its CAR is the kill string that
C-y should yank.
kill-ring-max is 30.
Most buffers have an undo list, which records all
changes made to the buffer's text so that they can be undone. (The
buffers that don't have one are usually special-purpose buffers for
which Emacs assumes that undoing is not useful.) All the primitives
that modify the text in the buffer automatically add elements to
the front of the undo list, which is in the variable
buffer-undo-list.
t
disables the recording of undo information.
Here are the kinds of elements an undo list can have:
position(beg . end)(text . position)(abs
position).
(t high . low)primitive-undo uses those values to determine whether
to mark the buffer as unmodified once again; it does so only if the
file's modification time matches those numbers.
(nil property value beg
. end)(put-text-property beg end property value)
(marker . adjustment)nilnil. The editor command loop automatically creates an undo boundary before each key sequence is executed. Thus, each undo normally undoes the effects of one command. Self-inserting input characters are an exception. The command loop makes a boundary for the first such character; the next 19 consecutive self-inserting input characters do not make boundaries, and then the 20th does, and so on as long as self-inserting characters continue.
All buffer modifications add a boundary whenever the previous undoable change was made in some other buffer. This is to ensure that each command makes a boundary in each buffer where it makes changes.
Calling this function explicitly is useful for splitting the
effects of a command into more than one unit. For example,
query-replace calls undo-boundary after
each replacement, so that the user can undo individual replacements
one by one.
primitive-undo adds elements to the buffer's undo
list when it changes the buffer. Undo commands avoid confusion by
saving the undo list value at the beginning of a sequence of undo
operations. Then the undo operations use and update the saved
value. The new elements added by undoing are not part of this saved
value, so they don't interfere with continuing to undo.
This section describes how to enable and disable undo information for a given buffer. It also explains how the undo list is truncated automatically so it doesn't get too big.
Recording of undo information in a newly created buffer is
normally enabled to start with; but if the buffer name starts with
a space, the undo recording is initially disabled. You can
explicitly enable or disable undo recording with the following two
functions, or by setting buffer-undo-list
yourself.
nil. In an interactive call, buffer-or-name is the current buffer. You cannot specify any other buffer.
This function returns nil.
The name buffer-flush-undo is not considered
obsolete, but the preferred name is
buffer-disable-undo.
As editing continues, undo lists get longer and longer. To
prevent them from using up all available memory space, garbage
collection trims them back to size limits you can set. (For this
purpose, the "size" of an undo list measures the cons cells that
make up the list, plus the strings of deleted text.) Two variables
control the range of acceptable sizes: undo-limit and
undo-strong-limit.
Filling means adjusting the lengths of lines (by moving
the line breaks) so that they are nearly (but no greater than) a
specified maximum width. Additionally, lines can be
justified, which means inserting spaces to make the left
and/or right margins line up precisely. The width is controlled by
the variable fill-column. For ease of reading, lines
should be no longer than 70 or so columns.
You can use Auto Fill mode (see section Auto Filling) to fill text automatically as you insert it, but changes to existing text may leave it improperly filled. Then you must fill the text explicitly.
Most of the commands in this section return values that are not
meaningful. All the functions that do filling take note of the
current left margin, current right margin, and current
justification style (see section Margins for Filling). If the current
justification style is none, the filling functions
don't actually do anything.
Several of the filling functions have an argument
justify. If it is non-nil, that requests
some kind of justification. It can be left,
right, full, or center, to
request a specific style of justification. If it is t,
that means to use the current justification style for this part of
the text (see current-justification, below). Any other
value is treated as full.
When you call the filling functions interactively, using a
prefix argument implies the value full for
justify.
nil, each line is
justified as well. It uses the ordinary paragraph motion commands
to find paragraph boundaries. See section `Paragraphs' in The
Emacs Manual.
nil. If nosqueeze is non-nil, that means to
leave whitespace other than line breaks untouched. If
to-eop is non-nil, that means to keep
filling to the end of the paragraph--or the next hard newline, if
use-hard-newlines is enabled (see below).
The variable paragraph-separate controls how to
distinguish paragraphs. See section Standard Regular Expressions Used in
Editing.
The first two arguments, start and end,
are the beginning and end of the region to be filled. The third and
fourth arguments, justify and mail-flag, are
optional. If justify is non-nil, the
paragraphs are justified as well as filled. If mail-flag
is non-nil, it means the function is operating on a
mail message and therefore should not fill the header lines.
Ordinarily, fill-individual-paragraphs regards each
change in indentation as starting a new paragraph. If
fill-individual-varying-indent is
non-nil, then only separator lines separate
paragraphs. That mode can handle indented paragraphs with
additional indentation on the first line.
fill-individual-paragraphs as described
above.
nil. In an interactive call, any prefix argument requests justification.
If nosqueeze is non-nil, that means to
leave whitespace other than line breaks untouched. If
squeeze-after is non-nil, it specifies a
position in the region, and means don't canonicalize spaces before
that position.
In Adaptive Fill mode, this command calls
fill-context-prefix to choose a fill prefix by
default. See section Adaptive Fill
Mode.
fill-column. It returns nil. The argument how, if non-nil specifies
explicitly the style of justification. It can be left,
right, full, center, or
none. If it is t, that means to do follow
specified justification style (see
current-justification, below). nil means
to do full justification.
If eop is non-nil, that means do
left-justification if current-justification specifies
full justification. This is used for the last line of a paragraph;
even if the paragraph as a whole is fully justified, the last line
should not be.
If nosqueeze is non-nil, that means do
not change interior whitespace.
left, right, full,
center, or none. The default value is
left.
nil, a period followed by just one space does not
count as the end of a sentence, and the filling functions avoid
breaking the line at such a place.
nil, fill-paragraph calls
this function to do the work. If the function returns a
non-nil value, fill-paragraph assumes the
job is done, and immediately returns that value. The usual use of this feature is to fill comments in programming language modes. If the function needs to fill a paragraph in the usual way, it can do so as follows:
(let ((fill-paragraph-function nil)) (fill-paragraph arg))
nil, the filling functions do not delete newlines
that have the hard text property. These "hard
newlines" act as paragraph separators.
The fill prefix follows the left margin whitespace, if any.
As a practical matter, if you are writing text for other people
to read, you should set fill-column to no more than
70. Otherwise the line will be too long for people to read
comfortably, and this can make the text seem clumsy.
fill-column in buffers that
do not override it. This is the same as (default-value
'fill-column). The default value for default-fill-column is
70.
left-margin property on the text from from
to to to the value margin. If Auto Fill mode
is enabled, this command also refills the region to fit the new
margin.
right-margin property on the text from from
to to to the value margin. If Auto Fill mode
is enabled, this command also refills the region to fit the new
margin.
left-margin property of
the character at the start of the current line (or zero if none),
and the value of the variable left-margin.
fill-column variable,
minus the value of the right-margin property of the
character after point.
current-left-margin. If the argument n is
non-nil, move-to-left-margin moves
forward n-1 lines first. If force is non-nil, that says to fix
the line's indentation if that doesn't match the left margin
value.
current-left-margin. In no case does this
function delete non-whitespace.
indent-line-function, used in Fundamental mode, Text
mode, etc. Its effect is to adjust the indentation at the beginning
of the current line to the value specified by the variable
left-margin. This may involve either inserting or
deleting whitespace.
nil,
then the line won't be broken there.
Adaptive Fill mode chooses a fill prefix automatically from the text in each paragraph being filled.
nil. It is
t by default.
comment-start-skip, then it is
used--otherwise, spaces amounting to the same width are used
instead. However, the fill prefix is never taken from a one-line paragraph if it would act as a paragraph starter on subsequent lines.
adaptive-fill-regexp does not match, with point after
the left margin of a line, and it should return the appropriate
fill prefix based on that line. If it returns nil,
that means it sees no fill prefix in that line.
Auto Fill mode is a minor mode that fills lines automatically as text is inserted. This section describes the hook used by Auto Fill mode. For a description of functions that you can call explicitly to fill and justify existing text, see section Filling.
Auto Fill mode also enables the functions that change the margins and justification style to refill portions of the text. See section Margins for Filling.
nil, in
which case nothing special is done in that case. The value of auto-fill-function is
do-auto-fill when Auto-Fill mode is enabled. That is a
function whose sole purpose is to implement the usual strategy for
breaking a line.
In older Emacs versions, this variable was named
auto-fill-hook, but since it is not called with the standard convention for hooks, it was renamed toauto-fill-functionin version 19.
auto-fill-function, if and when
Auto Fill is turned on. Major modes can set buffer-local values for
this variable to alter how Auto Fill works.
The sorting functions described in this section all rearrange
text in a buffer. This is in contrast to the function
sort, which rearranges the order of the elements of a
list (see section Functions that
Rearrange Lists). The values returned by these functions are
not meaningful.
To understand how sort-subr works, consider the
whole accessible portion of the buffer as being divided into
disjoint pieces called sort records. The records may or
may not be contiguous, but they must not overlap. A portion of each
sort record (perhaps all of it) is designated as the sort key.
Sorting rearranges the records in order by their sort keys.
Usually, the records are rearranged in order of ascending sort
key. If the first argument to the sort-subr function,
reverse, is non-nil, the sort records are
rearranged in order of descending sort key.
The next four arguments to sort-subr are functions
that are called to move point across a sort record. They are called
many times from within sort-subr.
sort-subr is called. Therefore, you should usually
move point to the beginning of the buffer before calling
sort-subr. This function can indicate there are no
more sort records by leaving point at the end of the buffer.
nil
value to be used as the sort key, or return nil to
indicate that the sort key is in the buffer starting at point. In
the latter case, endkeyfun is called to find the end of
the sort key.
nil and this
argument is omitted (or nil), then the sort key
extends to the end of the record. There is no need for
endkeyfun if startkeyfun returns a
non-nil value.
As an example of sort-subr, here is the complete
function definition for sort-lines:
;; Note that the first two lines of doc string
;; are effectively one line when viewed by a user.
(defun sort-lines (reverse beg end)
"Sort lines in region alphabetically;\
argument means descending order.
Called from a program, there are three arguments:
REVERSE (non-nil means reverse order),\
BEG and END (region to sort).
The variable `sort-fold-case' determines\
whether alphabetic case affects
the sort order.
(interactive "P\nr")
(save-excursion
(save-restriction
(narrow-to-region beg end)
(goto-char (point-min))
(sort-subr reverse 'forward-line 'end-of-line))))
Here forward-line moves point to the start of the
next record, and end-of-line moves point to the end of
record. We do not pass the arguments startkeyfun and
endkeyfun, because the entire record is used as the sort
key.
The sort-paragraphs function is very much the same,
except that its sort-subr call looks like this:
(sort-subr reverse
(function
(lambda ()
(while (and (not (eobp))
(looking-at paragraph-separate))
(forward-line 1))))
'forward-paragraph)
Markers pointing into any sort records are left with no useful
position after sort-subr returns.
nil, sort-subr and the other buffer
sorting functions ignore case when comparing strings.
Alphabetical sorting means that two sort keys are compared by comparing the first characters of each, the second characters of each, and so on. If a mismatch is found, it means that the sort keys are unequal; the sort key whose character is less at the point of first mismatch is the lesser sort key. The individual characters are compared according to their numerical character codes in the Emacs character set.
The value of the record-regexp argument specifies how to divide the buffer into sort records. At the end of each record, a search is done for this regular expression, and the text that matches it is taken as the next record. For example, the regular expression `^.+$', which matches lines with at least one character besides a newline, would make each such line into a sort record. See section Regular Expressions, for a description of the syntax and meaning of regular expressions.
The value of the key-regexp argument specifies what part of each record is the sort key. The key-regexp could match the whole record, or only a part. In the latter case, the rest of the record has no effect on the sorted order of records, but it is carried along when the record moves to its new position.
The key-regexp argument can refer to the text matched by a subexpression of record-regexp, or it can be a regular expression on its own.
If key-regexp is:
sort-regexp-fields searches for a match for
the regular expression within the record. If such a match is found,
it is the sort key. If there is no match for key-regexp
within a record then that record is ignored, which means its
position in the buffer is not changed. (The other records may move
around it.)
For example, if you plan to sort all the lines in the region by the first word on each line starting with the letter `f', you should set record-regexp to `^.*$' and set key-regexp to `\<f\w*\>'. The resulting expression looks like this:
(sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
(region-beginning)
(region-end))
If you call sort-regexp-fields interactively, it
prompts for record-regexp and key-regexp in
the minibuffer.
nil, the
sort is in reverse order.
nil, the
sort is in reverse order.
nil, the
sort is in reverse order.
If reverse is non-nil, the sort is in
reverse order.
One unusual thing about this command is that the entire line containing position beg, and the entire line containing position end, are included in the region sorted.
Note that sort-columns uses the sort
utility program, and so cannot work properly on text containing tab
characters. Use M-x untabify to convert tabs to spaces
before sorting.
The column functions convert between a character position (counting characters from the beginning of the buffer) and a column position (counting screen characters from the beginning of a line).
These functions count each character according to the number of
columns it occupies on the screen. This means control characters
count as occupying 2 or 4 columns, depending upon the value of
ctl-arrow, and tabs count as occupying a number of
columns that depends on the value of tab-width and on
the column where the tab begins. See section Usual Display Conventions.
Column number computations ignore the width of the window and the amount of horizontal scrolling. Consequently, a column value can be arbitrarily high. The first (or leftmost) column is numbered 0.
For an example of using current-column, see the
description of count-lines in section Motion by Text Lines.
If column column is beyond the end of the line, point moves to the end of the line. If column is negative, point moves to the beginning of the line.
If it is impossible to move to column column because
that is in the middle of a multicolumn character such as a tab,
point moves to the end of that character. However, if
force is non-nil, and column is
in the middle of a tab, then move-to-column converts
the tab into spaces so that it can move precisely to column
column. Other multicolumn characters can cause anomalies
despite force, since there is no way to split them.
The argument force also has an effect if the line isn't long enough to reach column column; in that case, it says to add whitespace at the end of the line to reach that column.
If column is not an integer, an error is signaled.
The return value is the column number actually moved to.
The indentation functions are used to examine, move to, and change whitespace that is at the beginning of a line. Some of the functions can also change whitespace elsewhere on a line. Columns and indentation count from zero at the left margin.
This section describes the primitive functions used to count and insert indentation. The functions in the following sections use these primitives. See section Width, for related functions.
nil, then at
least that many spaces are inserted even if this requires going
beyond column. Otherwise the function does nothing if
point is already beyond column. The value is the column
at which the inserted indentation ends. The inserted whitespace characters inherit text properties from the surrounding text (usually, from the preceding text only). See section Stickiness of Text Properties.