How to control how much information is kept.
* Filling:: Functions for explicit filling.
* Margins:: How to specify margins for filling commands.
+* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context.
* Auto Filling:: How auto-fill mode is implemented to break lines.
* Sorting:: Functions for sorting parts of the buffer.
* Columns:: Computing horizontal positions, and using them.
Several simple functions are described here. See also @code{looking-at}
in @ref{Regexp Search}.
-@defun char-after position
+@defun char-after &optional position
This function returns the character in the current buffer at (i.e.,
immediately after) position @var{position}. If @var{position} is out of
range for this purpose, either before the beginning of the buffer, or at
-or beyond the end, then the value is @code{nil}.
+or beyond the end, then the value is @code{nil}. The default for
+@var{position} is point.
In the following example, assume that the first character in the
buffer is @samp{@@}:
@end example
@end defun
-@defun char-before position
+@defun char-before &optional position
This function returns the character in the current buffer immediately
before position @var{position}. If @var{position} is out of range for
this purpose, either before the beginning of the buffer, or at or beyond
-the end, then the value is @code{nil}.
+the end, then the value is @code{nil}. The default for
+@var{position} is point.
@end defun
@defun following-char
@defun buffer-string
This function returns the contents of the entire accessible portion of
-the current buffer as a string. This is the portion between
-@code{(point-min)} and @code{(point-max)} (@pxref{Narrowing}).
+the current buffer as a string. It is equivalent to
+
+@example
+(buffer-substring (point-min) (point-max))
+@end example
@example
@group
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. @xref{Converting
+Representations}.
+
@defun insert &rest args
This function inserts the strings and/or characters @var{args} into the
current buffer, at point, moving point forward. In other words, it
number (@code{nil} means 1), and @var{character} must be a character.
The value is @code{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. @xref{Converting Representations}.
+
If @var{inherit} is non-@code{nil}, then the inserted characters inherit
sticky text properties from the two characters before and after the
insertion point. @xref{Sticky Properties}.
@end deffn
@defvar overwrite-mode
-This variable controls whether overwrite mode is in effect: a
-non-@code{nil} value enables the mode. It is automatically made
-buffer-local when set in any fashion.
+This variable controls whether overwrite mode is in effect. The value
+should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
+or @code{nil}. @code{overwrite-mode-textual} specifies textual
+overwrite mode (treats newlines and tabs specially), and
+@code{overwrite-mode-binary} specifies binary overwrite mode (treats
+newlines and tabs like any other characters).
@end defvar
@node Deletion
All of the deletion functions operate on the current buffer, and all
return a value of @code{nil}.
-@defun erase-buffer
+@deffn Command erase-buffer
This function deletes the entire text of the current buffer, leaving it
empty. If the buffer is read-only, it signals a @code{buffer-read-only}
error. Otherwise, it deletes the text without asking for any
@code{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.
-@end defun
+@end deffn
@deffn Command delete-region start end
This command deletes the text in the current buffer in the region
The value returned is always @code{nil}.
@end deffn
-@tindex backward-delete-char-untabify-method
@defopt backward-delete-char-untabify-method
+@tindex backward-delete-char-untabify-method
This option specifies how @code{backward-delete-char-untabify} should
deal with whitespace. Possible values include @code{untabify}, the
default, meaning convert a tab to many spaces and delete one;
any whitespace at the join and in some cases replacing it with one
space. If @var{join-following-p} is non-@code{nil},
@code{delete-indentation} joins this line to the following line
-instead. The value is @code{nil}.
+instead. The function returns @code{nil}.
If there is a fill prefix, and the second of the lines being joined
starts with the prefix, then @code{delete-indentation} deletes the
@end deffn
@defun fixup-whitespace
-This function replaces all the white space surrounding point with either
+This function replaces all the whitespace surrounding point with either
one space or no space, according to the context. It returns @code{nil}.
At the beginning or end of a line, the appropriate amount of space is
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 entry in the kill ring, which would be
-yanked as a unit; the second and subsequent consecutive kill commands
-add text to the entry made by the first one.
+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
text into the kill ring from a read-only buffer.
@end deffn
+@defopt kill-read-only-ok
+If this option is non-@code{nil}, @code{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.
+@end defopt
+
@deffn Command copy-region-as-kill start end
This command saves the region defined by @var{start} and @var{end} on
the kill ring (including text properties), but does not delete the text
oldest one comes the newest one, and before the newest one goes the
oldest.
-The value is always @code{nil}.
+The return value is always @code{nil}.
@end deffn
@node Low-Level Kill Ring
(@pxref{Window System Selections}).
@defun current-kill n &optional do-not-move
-The function @code{current-kill} rotates the yanking pointer which
-designates the ``front'' of the kill ring by @var{n} places (from newer
+The function @code{current-kill} rotates the yanking pointer, which
+designates the ``front'' of the kill ring, by @var{n} places (from newer
kills to older ones), and returns the text at that place in the ring.
If the optional second argument @var{do-not-move} is non-@code{nil},
Here are the kinds of elements an undo list can have:
@table @code
-@item @var{integer}
-This kind of element records a previous value of point. Ordinary cursor
-motion does not get any sort of undo record, but deletion operations use
-these entries to record where point was before the command.
+@item @var{position}
+This kind of element records a previous value of point; undoing this
+element moves point to @var{position}. Ordinary cursor motion does not
+make any sort of undo record, but deletion operations use these entries
+to record where point was before the command.
@item (@var{beg} . @var{end})
This kind of element indicates how to delete text that was inserted.
@var{adjustment} character positions. Undoing this element moves
@var{marker} @minus{} @var{adjustment} characters.
-@item @var{position}
-This element indicates where point was at an earlier time. Undoing this
-element sets point to @var{position}. Deletion normally creates an
-element of this kind as well as a reinsertion element.
-
@item nil
This element is a boundary. The elements between two boundaries are
called a @dfn{change group}; normally, each change group corresponds to
self-inserting characters continue.
All buffer modifications add a boundary whenever the previous undoable
-change was made in some other buffer. This way, a command that modifies
-several buffers makes a boundary in each buffer it changes.
+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, @code{query-replace}
You cannot specify any other buffer.
@end deffn
-@defun buffer-disable-undo &optional buffer
-@defunx buffer-flush-undo &optional buffer
+@deffn Command buffer-disable-undo &optional buffer
+@deffnx Command buffer-flush-undo &optional buffer
@cindex disable undo
This function discards the undo list of @var{buffer}, and disables
further recording of undo information. As a result, it is no longer
the undo list of @var{buffer} is already disabled, this function
has no effect.
-This function returns @code{nil}. It cannot be called interactively.
+This function returns @code{nil}.
The name @code{buffer-flush-undo} is not considered obsolete, but the
preferred name is @code{buffer-disable-undo}.
-@end defun
+@end deffn
As editing continues, undo lists get longer and longer. To prevent
them from using up all available memory space, garbage collection trims
boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}.
@end deffn
-@deffn Command fill-region start end &optional justify
+@deffn Command fill-region start end &optional justify nosqueeze
This command fills each of the paragraphs in the region from @var{start}
to @var{end}. It justifies as well if @var{justify} is
non-@code{nil}.
+If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
+other than line breaks untouched. If @var{to-eop} is non-@code{nil},
+that means to keep filling to the end of the paragraph---or the next hard
+newline, if @code{use-hard-newlines} is enabled (see below).
+
The variable @code{paragraph-separate} controls how to distinguish
paragraphs. @xref{Standard Regexps}.
@end deffn
described above.
@end defopt
-@deffn Command fill-region-as-paragraph start end &optional justify
+@deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
This command considers a region of text as a single paragraph and fills
it. If the region was made up of many paragraphs, the blank lines
between paragraphs are removed. This function justifies as well as
In an interactive call, any prefix argument requests justification.
-In Adaptive Fill mode, which is enabled by default, calling the function
-@code{fill-region-as-paragraph} on an indented paragraph when there is
-no fill prefix uses the indentation of the second line of the paragraph
-as the fill prefix.
+If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
+other than line breaks untouched. If @var{squeeze-after} is
+non-@code{nil}, it specifies a position in the region, and means don't
+canonicalize spaces before that position.
+
+In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
+choose a fill prefix by default. @xref{Adaptive Fill}.
@end deffn
@deffn Command justify-current-line how eop nosqueeze
the text around point.
@end defun
+@defopt sentence-end-double-space
+If this variable is non-@code{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.
+@end defopt
+
@defvar fill-paragraph-function
This variable provides a way for major modes to override the filling of
paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
@section Margins for Filling
@defopt fill-prefix
-This variable specifies a string of text that appears at the beginning
+This buffer-local variable specifies a string of text that appears at
+the beginning
of normal text lines and should be disregarded when filling them. Any
line that fails to start with the fill prefix is considered the start of
a paragraph; so is any line that starts with the fill prefix followed by
becomes buffer-local when set in any fashion.
@end defvar
-@tindex fill-nobreak-predicate
@defvar fill-nobreak-predicate
+@tindex fill-nobreak-predicate
This variable gives major modes a way to specify not to break a line at
certain places. Its value should be a function. This function is
called during filling, with no arguments and with point located at the
non-@code{nil}, then the line won't be broken there.
@end defvar
+@node Adaptive Fill
+@section Adaptive Fill Mode
+@cindex Adaptive Fill mode
+
+ Adaptive Fill mode chooses a fill prefix automatically from the text
+in each paragraph being filled.
+
+@defopt adaptive-fill-mode
+Adaptive Fill mode is enabled when this variable is non-@code{nil}.
+It is @code{t} by default.
+@end defopt
+
+@defun fill-context-prefix from to
+This function implements the heart of Adaptive Fill mode; it chooses a
+fill prefix based on the text between @var{from} and @var{to}. It does
+this by looking at the first two lines of the paragraph, based on the
+variables described below.
+@end defun
+
+@defopt adaptive-fill-regexp
+This variable holds a regular expression to control Adaptive Fill mode.
+Adaptive Fill mode matches this regular expression against the text
+starting after the left margin whitespace (if any) on a line; the
+characters it matches are that line's candidate for the fill prefix.
+@end defopt
+
+@defopt adaptive-fill-first-line-regexp
+In a one-line paragraph, if the candidate fill prefix matches this
+regular expression, or if it matches @code{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.
+@end defopt
+
+@defopt adaptive-fill-function
+You can specify more complex ways of choosing a fill prefix
+automatically by setting this variable to a function. The function is
+called when @code{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 @code{nil}, that means it sees
+no fill prefix in that line.
+@end defopt
+
@node Auto Filling
@comment node-name, next, previous, up
@section Auto Filling
@end group
@group
(interactive "P\nr")
- (save-restriction
- (narrow-to-region beg end)
- (goto-char (point-min))
- (sort-subr reverse 'forward-line 'end-of-line)))
+ (save-excursion
+ (save-restriction
+ (narrow-to-region beg end)
+ (goto-char (point-min))
+ (sort-subr reverse 'forward-line 'end-of-line))))
@end group
@end example
@example
@group
(sort-subr reverse
- (function
- (lambda () (skip-chars-forward "\n \t\f")))
+ (function
+ (lambda ()
+ (while (and (not (eobp))
+ (looking-at paragraph-separate))
+ (forward-line 1))))
'forward-paragraph)
@end group
@end example
position after @code{sort-subr} returns.
@end defun
+@defopt sort-fold-case
+If this variable is non-@code{nil}, @code{sort-subr} and the other
+buffer sorting functions ignore case when comparing strings.
+@end defopt
+
@deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
This command sorts the region between @var{start} and @var{end}
alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
@deffn Command indent-for-tab-command
This command calls the function in @code{indent-line-function} to indent
-the current line; except that if that function is
-@code{indent-to-left-margin}, it calls @code{insert-tab} instead. (That
+the current line; however, if that function is
+@code{indent-to-left-margin}, @code{insert-tab} is called instead. (That
is a trivial command that inserts a tab character.)
@end deffn
@deffn Command reindent-then-newline-and-indent
@comment !!SourceFile simple.el
This command reindents the current line, inserts a newline at point,
-and then reindents the new line (the one following the newline just
+and then indents the new line (the one following the newline just
inserted).
This command does indentation on both lines according to the current
@defvar indent-region-function
The value of this variable is a function that can be used by
-@code{indent-region} as a short cut. You should design the function so
+@code{indent-region} as a short cut. It should take two arguments, the
+start and end of the region. You should design the function so
that it will produce the same results as indenting the lines of the
region one by one, but presumably faster.
@var{limit} equals @var{pos}.
@end defun
-@tindex next-char-property-change
@defun next-char-property-change position &optional limit
+@tindex next-char-property-change
This is like @code{next-property-change} except that it considers
overlay properties as well as text properties. There is no @var{object}
operand because this function operates only on the current buffer. It
returns the next address at which either kind of property changes.
@end defun
-@tindex previous-char-property-change
@defun previous-char-property-change position &optional limit
+@tindex previous-char-property-change
This is like @code{next-char-property-change}, but scans back from
@var{position} instead of forward.
@end defun
before the change. All three arguments are integers. The buffer that's
about to change is always the current buffer.
-The length of the old text is measured in bytes; it is the difference
-between the buffer positions before and after that text, before the
-change. As for the changed text, its length in bytes is simply the
-difference between the first two arguments. If you want the length
-in @emph{characters} of the text before the change, you should use
-a @code{before-change-functions} function that calls @code{chars-in-region}
-(@pxref{Chars and Bytes}).
+The length of the old text is the difference between the buffer positions
+before and after that text as it was before the change. As for the
+changed text, its length is simply the difference between the first two
+arguments.
@end defvar
-@tindex combine-after-change-calls
@defmac combine-after-change-calls body...
+@tindex combine-after-change-calls
The macro executes @var{body} normally, but arranges to call the
after-change functions just once for a series of several changes---if
that seems safe.