@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/text
-@node Text, Searching and Matching, Markers, Top
+@node Text, Non-ASCII Characters, Markers, Top
@chapter Text
@cindex text
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
-(@pxref{Undo}).
+often operating at point or on text adjacent to point. Many are
+interactive. All the functions that change the text provide for undoing
+the changes (@pxref{Undo}).
Many text-related functions operate on a region of text defined by two
buffer positions passed in arguments named @var{start} and @var{end}.
@cindex buffer contents
Throughout this chapter, ``text'' refers to the characters in the
-buffer, together with their properties (when relevant).
+buffer, together with their properties (when relevant). Keep in mind
+that point is always between two characters, and the cursor appears on
+the character after point.
@menu
* Near Point:: Examining text in the vicinity of point.
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.
* Transposition:: Swapping two portions of a buffer.
* Registers:: How registers are implemented. Accessing the text or
position stored in a register.
+* Base 64:: Conversion to or from base 64 encoding.
+* MD5 Checksum:: Compute the MD5 ``message digest''/``checksum''.
* Change Hooks:: Supplying functions to be run when text is changed.
@end menu
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 &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 default for
+@var{position} is point.
+@end defun
+
@defun following-char
This function returns the character following point in the current
buffer. This is similar to @code{(char-after (point))}. However, if
@defun bolp
This function returns @code{t} if point is at the beginning of a line.
-@xref{Text Lines}. The beginning of the buffer (or its accessible
+@xref{Text Lines}. The beginning of the buffer (or of its accessible
portion) always counts as the beginning of a line.
@end defun
@defun buffer-substring-no-properties start end
This is like @code{buffer-substring}, except that it does not copy text
properties, just the characters themselves. @xref{Text Properties}.
-Here's an example of using this function to get a word to look up in an
-alist:
-
-@example
-(setq flammable
- (assoc (buffer-substring start end)
- '(("wood" . t) ("paper" . t)
- ("steel" . nil) ("asbestos" . nil))))
-@end example
-
-If this were written using @code{buffer-substring} instead, it would not
-work reliably; any text properties that happened to be in the word
-copied from the buffer would make the comparisons fail.
@end defun
@defun buffer-string
-This function returns the contents of the accessible portion of the
-current buffer as a string. This is the portion between
-@code{(point-min)} and @code{(point-max)} (@pxref{Narrowing}).
+This function returns the contents of the entire accessible portion of
+the current buffer as a string. It is equivalent to
+
+@example
+(buffer-substring (point-min) (point-max))
+@end example
@example
@group
@end example
@end defun
+@defun thing-at-point thing
+Return the @var{thing} around or next to point, as a string.
+
+The argument @var{thing} is a symbol which specifies a kind of syntactic
+entity. Possibilities include @code{symbol}, @code{list}, @code{sexp},
+@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
+@code{whitespace}, @code{line}, @code{page}, and others.
+
+@example
+---------- Buffer: foo ----------
+Gentlemen may cry ``Pea@point{}ce! Peace!,''
+but there is no peace.
+---------- Buffer: foo ----------
+
+(thing-at-point 'word)
+ @result{} "Peace"
+(thing-at-point 'line)
+ @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
+(thing-at-point 'whitespace)
+ @result{} nil
+@end example
+@end defun
+
@node Comparing Text
@section Comparing Text
@cindex comparing buffer text
at the second character.
@example
-(compare-buffer-substring nil 6 11 nil 16 21)
+(compare-buffer-substrings nil 6 11 nil 16 21)
@result{} 2
@end example
@end defun
@cindex insertion of text
@cindex text insertion
+@cindex insertion before point
+@cindex before point, insertion
@dfn{Insertion} means adding new text to a buffer. The inserted text
goes at point---between the character before point and the character
-after point.
+after point. Some insertion functions leave point before the inserted
+text, while other functions leave it after. We call the former
+insertion @dfn{after point} and the latter insertion @dfn{before point}.
Insertion relocates markers that point at positions after the
insertion point, so that they stay with the surrounding text
(@pxref{Markers}). When a marker points at the place of insertion,
-insertion normally doesn't relocate the marker, so that it points to the
-beginning of the inserted text; however, certain special functions such
-as @code{insert-before-markers} relocate such markers to point after the
-inserted text.
-
-@cindex insertion before point
-@cindex before point, insertion
- Some insertion functions leave point before the inserted text, while
-other functions leave it after. We call the former insertion @dfn{after
-point} and the latter insertion @dfn{before point}.
+insertion may or may not relocate the marker, depending on the marker's
+insertion type (@pxref{Marker Insertion Types}). Certain special
+functions such as @code{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.
+read-only or if they insert within read-only text.
These functions copy text characters from strings and buffers along
with their properties. The inserted characters have exactly the same
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
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.
+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.
@end defun
-@defun insert-char character count &optional inherit
+@defun insert-char character &optional count inherit
This function inserts @var{count} instances of @var{character} into the
-current buffer before point. The argument @var{count} must be a number,
-and @var{character} must be a character. The value is @code{nil}.
-@c It's unfortunate that count comes second. Not like make-string, etc.
+current buffer before point. The argument @var{count} should be a
+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
In an interactive call, @var{count} is the numeric prefix argument.
This command calls @code{auto-fill-function} whenever that is
-non-@code{nil} and the character inserted is a space or a newline
-(@pxref{Auto Filling}).
+non-@code{nil} and the character inserted is in the table
+@code{auto-fill-chars} (@pxref{Auto Filling}).
@c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
This command performs abbrev expansion if Abbrev mode is enabled and
This is also responsible for calling @code{blink-paren-function} when
the inserted character has close parenthesis syntax (@pxref{Blinking}).
+
+Do not try substituting your own definition of
+@code{self-insert-command} for the standard one. The editor command
+loop handles this function specially.
@end deffn
@deffn Command newline &optional number-of-newlines
@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
-confirmation. It returns @code{nil}.
+error; if some of the text in it is read-only, it signals a
+@code{text-read-only} error. Otherwise, it deletes the text without
+asking for any confirmation. It returns @code{nil}.
Normally, deleting a large amount of text from a buffer inhibits further
auto-saving of that buffer ``because it has shrunk''. However,
@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
-defined by @var{start} and @var{end}. The value is @code{nil}. If
-point was inside the deleted region, its value afterward is @var{start}.
+This command deletes the text between positions @var{start} and
+@var{end} in the current buffer, and returns @code{nil}. If point was
+inside the deleted region, its value afterward is @var{start}.
Otherwise, point relocates with the surrounding text, as markers do.
@end deffn
+@defun delete-and-extract-region start end
+@tindex delete-and-extract-region
+This function deletes the text between positions @var{start} and
+@var{end} in the current buffer, and returns a string containing the
+text just deleted.
+
+If point was inside the deleted region, its value afterward is
+@var{start}. Otherwise, point relocates with the surrounding text, as
+markers do.
+@end defun
+
@deffn Command delete-char count &optional killp
This command deletes @var{count} characters directly after point, or
before point if @var{count} is negative. If @var{killp} is
The value returned is always @code{nil}.
@end deffn
+@defopt 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;
+@code{hungry}, meaning delete all the whitespace characters before point
+with one command, and @code{nil}, meaning do nothing special for
+whitespace characters.
+@end defopt
+
@node User-Level Deletion
@section User-Level Deletion Commands
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
@section The Kill Ring
@cindex kill ring
- @dfn{Kill} functions delete text like the deletion functions, but save
+ @dfn{Kill functions} delete text like the deletion functions, but save
it so that the user can reinsert it by @dfn{yanking}. Most of these
functions have @samp{kill-} in their name. By contrast, the functions
whose names start with @samp{delete-} normally do not save text for
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
command that calls this function is a ``kill command'' (and should
probably have @samp{kill} in its name). @code{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 uses the @code{last-command}
-variable to determine whether the previous command was a kill command,
+adds it to the most recent element. It determines automatically (using
+@code{last-command}) whether the previous command was a kill command,
and if so appends the killed text to the most recent entry.
@deffn Command kill-region start end
the mark.
@c Emacs 19 feature
-If the buffer is read-only, @code{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.
+If the buffer or text is read-only, @code{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 a series of kill
+commands to copy text from a read-only buffer into the kill ring.
@end deffn
+@defopt kill-read-only-ok
+If this option is non-@code{nil}, @code{kill-region} does not signal an
+error if the buffer or text 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
subsequent kill command does not append to the same kill ring entry.
Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
-support Emacs 18. For Emacs 19, it is better to use @code{kill-new} or
-@code{kill-append} instead. @xref{Low-Level Kill Ring}.
+support Emacs 18. For newer Emacs versions, it is better to use
+@code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill
+Ring}.
@end deffn
@node Yank Commands
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
@subsection Low-Level Kill Ring
- These functions and variables provide access to the kill ring at a lower
-level, but still convenient for use in Lisp programs. They take care of
-interaction with X Window selections. They do not exist in Emacs
-version 18.
+ 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
+(@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},
then that value is used as the ``most recent kill''. If it returns
@code{nil}, then the first element of @code{kill-ring} is used.
-The normal use of this hook is to get the X server's primary selection
-as the most recent kill, even if the selection belongs to another X
-client. @xref{X Selections}.
+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. @xref{Window System Selections}.
@end defvar
@defvar interprogram-cut-function
If the value is a function, @code{kill-new} and @code{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 X server's primary selection
-to the newly killed text.
+The normal use of this hook is to set the window system's primary
+selection from the newly killed text. @xref{Window System Selections}.
@end defvar
@node Internals of Kill Ring
@example
@group
-kill-ring kill-ring-yank-pointer
- | |
- | ___ ___ ---> ___ ___ ___ ___
- --> |___|___|------> |___|___|--> |___|___|--> nil
+kill-ring ---- kill-ring-yank-pointer
+ | |
+ | v
+ | --- --- --- --- --- ---
+ --> | | |------> | | |--> | | |--> nil
+ --- --- --- --- --- ---
| | |
| | |
| | -->"yet older text"
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 commands 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 @code{buffer-disable-undo} is new as of Emacs versions
-19.
-@end defun
+preferred name is @code{buffer-disable-undo}.
+@end deffn
As editing continues, undo lists get longer and longer. To prevent
them from using up all available memory space, garbage collection trims
can be @code{left}, @code{right}, @code{full}, or @code{center}, to
request a specific style of justification. If it is @code{t}, that
means to use the current justification style for this part of the text
-(see @code{current-justification}, below).
+(see @code{current-justification}, below). Any other value is treated
+as @code{full}.
When you call the filling functions interactively, using a prefix
argument implies the value @code{full} for @var{justify}.
This command fills the paragraph at or after point. If
@var{justify} is non-@code{nil}, each line is justified as well.
It uses the ordinary paragraph motion commands to find paragraph
-boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}.
+boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
@end deffn
-@deffn Command fill-region start end &optional justify
+@deffn Command fill-region start end &optional justify nosqueeze to-eop
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
-@deffn Command fill-individual-paragraphs start end &optional justify mail-flag
+@deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
This command fills each paragraph in the region according to its
individual fill prefix. Thus, if the lines of a paragraph were indented
with spaces, the filled paragraph will remain indented in the same
The first two arguments, @var{start} and @var{end}, are the beginning
and end of the region to be filled. The third and fourth arguments,
-@var{justify} and @var{mail-flag}, are optional. If
+@var{justify} and @var{citation-regexp}, are optional. If
@var{justify} is non-@code{nil}, the paragraphs are justified as
-well as filled. If @var{mail-flag} is non-@code{nil}, it means the
+well as filled. If @var{citation-regexp} is non-@code{nil}, it means the
function is operating on a mail message and therefore should not fill
-the header lines.
+the header lines. If @var{citation-regexp} is a string, it is used as
+a regular expression; if it matches the beginning of a line, that line
+is treated as a citation marker.
Ordinarily, @code{fill-individual-paragraphs} regards each change in
indentation as starting a new paragraph. If
described above.
@end defopt
-@deffn Command fill-region-as-paragraph start end &optional justify
-This command considers a region of text as a 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 filling when
-@var{justify} is non-@code{nil}.
+@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
+filling when @var{justify} is non-@code{nil}.
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
+@deffn Command justify-current-line &optional how eop nosqueeze
This command inserts spaces between the words of the current line so
that the line ends exactly at @code{fill-column}. It returns
@code{nil}.
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
@end defopt
@defopt fill-column
-This buffer-local variable specifies the maximum width of filled
-lines. Its value should be an integer, which is a number of columns.
-All the filling, justification and centering commands are affected by
-this variable, including Auto Fill mode (@pxref{Auto Filling}).
+This buffer-local variable specifies the maximum width of filled lines.
+Its value should be an integer, which is a number of columns. All the
+filling, justification, and centering commands are affected by this
+variable, including Auto Fill mode (@pxref{Auto Filling}).
As a practical matter, if you are writing text for other people to
read, you should set @code{fill-column} to no more than 70. Otherwise
indentation if that doesn't match the left margin value.
@end deffn
-@defun delete-to-left-margin from to
-This function removes left margin indentation from the text
-between @var{from} and @var{to}. The amount of indentation
-to delete is determined by calling @code{current-left-margin}.
-In no case does this function delete non-whitespace.
+@defun delete-to-left-margin &optional from to
+This function removes left margin indentation from the text between
+@var{from} and @var{to}. The amount of indentation to delete is
+determined by calling @code{current-left-margin}. In no case does this
+function delete non-whitespace. If @var{from} and @var{to} are omitted,
+they default to the whole buffer.
@end defun
@defun indent-to-left-margin
@defvar left-margin
This variable specifies the base left margin column. In Fundamental
-mode, @key{LFD} indents to this column. This variable automatically
+mode, @kbd{C-j} indents to this column. This variable automatically
becomes buffer-local when set in any fashion.
@end defvar
+@defvar 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
+place where a break is being considered. If the function returns
+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.
+@c The optional argument first-line-regexp is not documented
+@c because it exists for internal purposes and might be eliminated
+@c in the future.
+@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
@defvar auto-fill-function
The value of this variable should be a function (of no arguments) to be
-called after self-inserting a space or a newline. It may be @code{nil},
-in which case nothing special is done in that case.
+called after self-inserting a character from the table
+@code{auto-fill-chars}. It may be @code{nil}, in which case nothing
+special is done in that case.
The value of @code{auto-fill-function} is @code{do-auto-fill} when
Auto-Fill mode is enabled. That is a function whose sole purpose is to
@defvar normal-auto-fill-function
This variable specifies the function to use for
@code{auto-fill-function}, if and when Auto Fill is turned on. Major
-modes can set this locally to alter how Auto Fill works.
+modes can set buffer-local values for this variable to alter how Auto
+Fill works.
+@end defvar
+
+@defvar auto-fill-chars
+A char table of characters which invoke @code{auto-fill-function} when
+self-inserted---space and newline in most language environments. They
+have an entry @code{t} in the table.
@end defvar
@node Sorting
The values returned by these functions are not meaningful.
@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
-This function is the general text-sorting routine that divides a buffer
-into records and sorts them. Most of the commands in this section use
-this function.
+This function is the general text-sorting routine that subdivides a
+buffer into records and then sorts them. Most of the commands in this
+section use this function.
To understand how @code{sort-subr} works, consider the whole accessible
portion of the buffer as being divided into disjoint pieces called
-@dfn{sort records}. The records may or may not be contiguous; they may
-not overlap. A portion of each sort record (perhaps all of it) is
+@dfn{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.
;; @r{Note that the first two lines of doc string}
;; @r{are effectively one line when viewed by a user.}
(defun sort-lines (reverse beg end)
- "Sort lines in region alphabetically.
+ "Sort lines in region alphabetically;\
+ argument means descending order.
Called from a program, there are three arguments:
@end group
@group
-REVERSE (non-nil means reverse order),
-and BEG and END (the region to sort)."
+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.
+@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
+
+Markers pointing into any sort records are left with no useful
+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}.
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 values. Since Emacs uses the @sc{ASCII}
-character set, the ordering in that set determines alphabetical order.
-@c version 19 change
+according to their numerical character codes in the Emacs character set.
The value of the @var{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 the
-next record. For example, the regular expression @samp{^.+$}, which
-matches lines with at least one character besides a newline, would make
-each such line into a sort record. @xref{Regular Expressions}, for a
-description of the syntax and meaning of regular expressions.
+done for this regular expression, and the text that matches it is taken
+as the next record. For example, the regular expression @samp{^.+$},
+which matches lines with at least one character besides a newline, would
+make each such line into a sort record. @xref{Regular Expressions}, for
+a description of the syntax and meaning of regular expressions.
The value of the @var{key-regexp} argument specifies what part of each
record is the sort key. The @var{key-regexp} could match the whole
Note that @code{sort-columns} uses the @code{sort} utility program,
and so cannot work properly on text containing tab characters. Use
-@kbd{M-x @code{untabify}} to convert tabs to spaces before sorting.
+@kbd{M-x untabify} to convert tabs to spaces before sorting.
@end deffn
@node Columns
characters from the beginning of the buffer) and a column position
(counting screen characters from the beginning of a line).
- A character counts 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 @code{ctl-arrow}, and tabs count as
-occupying a number of columns that depends on the value of
-@code{tab-width} and on the column where the tab begins. @xref{Usual Display}.
+ 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
+@code{ctl-arrow}, and tabs count as occupying a number of columns that
+depends on the value of @code{tab-width} and on the column where the tab
+begins. @xref{Usual Display}.
Column number computations ignore the width of the window and the
amount of horizontal scrolling. Consequently, a column value can be
@var{force}, since there is no way to split them.
The argument @var{force} also has an effect if the line isn't long
-enough to reach column @var{column}; in that case, it says to add
-whitespace at the end of the line to reach that column.
+enough to reach column @var{column}; if it is @code{t}, that means to
+add whitespace at the end of the line to reach that column.
If @var{column} is not an integer, an error is signaled.
This section describes the primitive functions used to count and
insert indentation. The functions in the following sections use these
-primitives.
+primitives. @xref{Width}, for related functions.
@defun current-indentation
@comment !!Type Primitive Function
@comment !!SourceFile indent.c
If this variable is non-@code{nil}, indentation functions can insert
tabs as well as spaces. Otherwise, they insert only spaces. Setting
-this variable automatically makes it local to the current buffer.
+this variable automatically makes it buffer-local in the current buffer.
@end defopt
@node Mode-Specific Indent
@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.
@end group
@end example
- In this example, point is between the @samp{m} and @samp{p} of
+ In this next example, point is between the @samp{m} and @samp{p} of
@samp{jumped}:
@example
@deffn Command indent-relative-maybe
@comment !!SourceFile indent.el
-This command indents the current line like the previous nonblank line.
-It calls @code{indent-relative} with @code{t} as the @var{unindented-ok}
-argument. The return value is unpredictable.
+This command indents the current line like the previous nonblank line,
+by calling @code{indent-relative} with @code{t} as the
+@var{unindented-ok} argument. The return value is unpredictable.
If the previous nonblank line has no indent points beyond the current
column, this command does nothing.
stop feature only in a few major modes, such as Text mode.
@deffn Command tab-to-tab-stop
-This command inserts spaces or tabs up to the next tab stop column
-defined by @code{tab-stop-list}. It searches the list for an element
-greater than the current column number, and uses that element as the
-column to indent to. It does nothing if no such element is found.
+This command inserts spaces or tabs before point, up to the next tab
+stop column defined by @code{tab-stop-list}. It searches the list for
+an element greater than the current column number, and uses that element
+as the column to indent to. It does nothing if no such element is
+found.
@end deffn
@defopt tab-stop-list
@node Case Changes
@comment node-name, next, previous, up
@section Case Changes
-@cindex case changes
+@cindex case conversion in buffers
The case change commands described here work on text in the current
-buffer. @xref{Character Case}, for case conversion commands that work
-on strings and characters. @xref{Case Table}, for how to customize
+buffer. @xref{Case Conversion}, for case conversion functions that work
+on strings and characters. @xref{Case Tables}, for how to customize
which characters are upper or lower case and how to convert them.
@deffn Command capitalize-region start end
@code{substring}, @code{insert}, and @code{buffer-substring}.
@menu
-* Examining Properties:: Looking at the properties of one character.
-* Changing Properties:: Setting the properties of a range of text.
-* Property Search:: Searching for where a property changes value.
-* Special Properties:: Particular properties with special meanings.
-* Format Properties:: Properties for representing formatting of text.
-* Sticky Properties:: How inserted text gets properties from
- neighboring text.
-* Saving Properties:: Saving text properties in files, and reading
- them back.
-* Lazy Properties:: Computing text properties in a lazy fashion
- only when text is examined.
-* Not Intervals:: Why text properties do not use
- Lisp-visible text intervals.
+* Examining Properties:: Looking at the properties of one character.
+* Changing Properties:: Setting the properties of a range of text.
+* Property Search:: Searching for where a property changes value.
+* Special Properties:: Particular properties with special meanings.
+* Format Properties:: Properties for representing formatting of text.
+* Sticky Properties:: How inserted text gets properties from
+ neighboring text.
+* Saving Properties:: Saving text properties in files, and reading
+ them back.
+* Lazy Properties:: Computing text properties in a lazy fashion
+ only when text is examined.
+* Clickable Text:: Using text properties to make regions of text
+ do something when you click on them.
+* Fields:: The @code{field} property defines
+ fields within the buffer.
+* Not Intervals:: Why text properties do not use
+ Lisp-visible text intervals.
@end menu
@node Examining Properties
overlays.
@end defun
+@defvar char-property-alias-alist
+This variable holds an alist which maps property names to a list of
+alternative property names. If a character does not specify a direct
+value for a property, the alternative property names are consulted in
+order; the first non-nil value is used. This variable takes
+precedence over @code{default-text-properties}, and @code{category}
+properties take precedence over this variable.
+@end defvar
+
@defun text-properties-at position &optional object
This function returns the entire property list of the character at
@var{position} in the string or buffer @var{object}. If @var{object} is
@defvar default-text-properties
This variable holds a property list giving default values for text
properties. Whenever a character does not specify a value for a
-property, neither directly nor through a category symbol, the value
-stored in this list is used instead. Here is an example:
+property, neither directly, through a category symbol, or through
+@code{char-property-alias-alist}, the value stored in this list is
+used instead. Here is an example:
@example
-(setq default-text-properties '(foo 69))
+(setq default-text-properties '(foo 69)
+ char-property-alias-alist nil)
;; @r{Make sure character 1 has no properties of its own.}
(set-text-properties 1 2 nil)
;; @r{What we get, when we ask, is the default value.}
@subsection Changing Text Properties
The primitives for changing properties apply to a specified range of
-text. The function @code{set-text-properties} (see end of section) sets
-the entire property list of the text in that range; more often, it is
-useful to add, change, or delete just certain properties specified by
-name.
+text in a buffer or string. The function @code{set-text-properties}
+(see end of section) sets the entire property list of the text in that
+range; more often, it is useful to add, change, or delete just certain
+properties specified by name.
- Since text properties are considered part of the buffer's contents, and
-can affect how the buffer looks on the screen, any change in the text
-properties is considered a buffer modification. Buffer text property
-changes are undoable (@pxref{Undo}).
+ Since text properties are considered part of the contents of the
+buffer (or string), and can affect how a buffer looks on the screen, any
+change in buffer text properties marks the buffer as modified. Buffer
+text property changes are undoable also (@pxref{Undo}).
@defun put-text-property start end prop value &optional object
This function sets the @var{prop} property to @var{value} for the text
@end defun
@defun add-text-properties start end props &optional object
-This function modifies the text properties for the text between
+This function adds or overrides text properties for the text between
@var{start} and @var{end} in the string or buffer @var{object}. If
@var{object} is @code{nil}, it defaults to the current buffer.
-The argument @var{props} specifies which properties to change. It
-should have the form of a property list (@pxref{Property Lists}): a list
-whose elements include the property names followed alternately by the
+The argument @var{props} specifies which properties to add. It should
+have the form of a property list (@pxref{Property Lists}): a list whose
+elements include the property names followed alternately by the
corresponding values.
The return value is @code{t} if the function actually changed some
The return value is @code{t} if the function actually changed some
property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
if no character in the specified text had any of those properties).
+
+To remove all text properties from certain text, use
+@code{set-text-properties} and specify @code{nil} for the new property
+list.
@end defun
@defun set-text-properties start end props &optional object
@end example
@end defun
-See also the function @code{buffer-substring-no-properties}
+ The easiest way to make a string with text properties
+is with @code{propertize}:
+
+@defun propertize string &rest properties
+@tindex propertize
+This function returns a copy of @var{string} which has the text
+properties @var{properties}. These properties apply to all the
+characters in the string that is returned. Here is an example that
+constructs a string with a @code{face} property and a @code{mouse-face}
+property:
+
+@smallexample
+(propertize "foo" 'face 'italic
+ 'mouse-face 'bold-italic)
+ @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
+@end smallexample
+
+To put different properties on various parts of a string, you can
+construct each part with @code{propertize} and then combine them with
+@code{concat}:
+
+@smallexample
+(concat
+ (propertize "foo" 'face 'italic
+ 'mouse-face 'bold-italic)
+ " and "
+ (propertize "bar" 'face 'italic
+ 'mouse-face 'bold-italic))
+ @result{} #("foo and bar"
+ 0 3 (face italic mouse-face bold-italic)
+ 3 8 nil
+ 8 11 (face italic mouse-face bold-italic))
+@end smallexample
+@end defun
+
+ See also the function @code{buffer-substring-no-properties}
(@pxref{Buffer Contents}) which copies text from the buffer
but does not copy its properties.
@node Property Search
-@subsection Property Search Functions
+@subsection Text Property Search Functions
-In typical use of text properties, most of the time several or many
+ In typical use of text properties, most of the time several or many
consecutive characters have the same value for a property. Rather than
writing your programs to examine characters one by one, it is much
faster to process chunks of text that have the same property value.
-Here are functions you can use to do this. They use @code{eq} for
+ Here are functions you can use to do this. They use @code{eq} for
comparing property values. In all cases, @var{object} defaults to the
current buffer.
-For high performance, it's very important to use the @var{limit}
+ For high performance, it's very important to use the @var{limit}
argument to these functions, especially the ones that search for a
single property---otherwise, they may spend a long time scanning to the
end of the buffer, if the property you are interested in does not change.
-Remember that a position is always between two characters; the position
-returned by these functions is between two characters with different
-properties.
+ These functions do not move point; instead, they return a position (or
+@code{nil}). Remember that a position is always between two characters;
+the position returned by these functions is between two characters with
+different properties.
@defun next-property-change pos &optional object limit
The function scans the text forward from position @var{pos} in the
@var{limit} equals @var{pos}.
@end defun
+@defun next-char-property-change pos &optional limit
+This is like @code{next-property-change} except that it considers
+overlay properties as well as text properties, and if no change is
+found before the end of the buffer, it returns the maximum buffer
+position rather than @code{nil} (in this sense, it resembles the
+corresponding overlay function @code{next-overlay-change}, rather than
+@code{next-property-change}). 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
+
+@defun previous-char-property-change pos &optional limit
+This is like @code{next-char-property-change}, but scans back from
+@var{pos} instead of forward, and returns the minimum buffer
+position if no change is found.
+@end defun
+
+@defun next-single-char-property-change pos prop &optional object limit
+@tindex next-single-char-property-change
+This is like @code{next-single-property-change} except that it
+considers overlay properties as well as text properties, and if no
+change is found before the end of the @var{object}, it returns the
+maximum valid position in @var{object} rather than @code{nil}. Unlike
+@code{next-char-property-change}, this function @emph{does} have an
+@var{object} operand; if @var{object} is not a buffer, only
+text-properties are considered.
+@end defun
+
+@defun previous-single-char-property-change pos prop &optional object limit
+@tindex previous-single-char-property-change
+This is like @code{next-single-char-property-change}, but scans back
+from @var{pos} instead of forward, and returns the minimum valid
+position in @var{object} if no change is found.
+@end defun
+
@defun text-property-any start end prop value &optional object
This function returns non-@code{nil} if at least one character between
@var{start} and @var{end} has a property @var{prop} whose value is
@defun text-property-not-all start end prop value &optional object
This function returns non-@code{nil} if at least one character between
-@var{start} and @var{end} has a property @var{prop} whose value differs
-from @var{value}. More precisely, it returns the position of the
-first such character. Otherwise, it returns @code{nil}.
+@var{start} and @var{end} does not have a property @var{prop} with value
+@var{value}. More precisely, it returns the position of the first such
+character. Otherwise, it returns @code{nil}.
The optional fifth argument, @var{object}, specifies the string or
buffer to scan. Positions are relative to @var{object}. The default
@subsection Properties with Special Meanings
Here is a table of text property names that have special built-in
-meanings. The following section lists a few more special property names
-that are used to control filling. All other names have no standard
-meaning, and you can use them as you like.
+meanings. The following sections list a few additional special property
+names that control filling and property inheritance. All other names
+have no standard meaning, and you can use them as you like.
@table @code
@cindex category of text character
@cindex face codes of text
@kindex face @r{(text property)}
You can use the property @code{face} to control the font and color of
-text. Its value is a face name or a list of face names. @xref{Faces},
-for more information. This feature may be temporary; in the future, we
-may replace it with other ways of specifying how to display text.
+text. @xref{Faces}, for more information.
+
+In the simplest case, the value is a face name. It can also be a list;
+then each element can be any of these possibilities;
+
+@itemize @bullet
+@item
+A face name (a symbol or string).
+
+@item
+Starting in Emacs 21, a property list of face attributes. This has the
+form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
+face attribute name and @var{value} is a meaningful value for that
+attribute. With this feature, you do not need to create a face each
+time you want to specify a particular attribute for certain text.
+@xref{Face Attributes}.
+
+@item
+A cons cell of the form @code{(foreground-color . @var{color-name})} or
+@code{(background-color . @var{color-name})}. These elements specify
+just the foreground color or just the background color.
+
+@code{(foreground-color . @var{color-name})} is equivalent to
+@code{(:foreground @var{color-name})}, and likewise for the background.
+@end itemize
+
+You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically
+update @code{face} properties based on the contents of the text.
+
+@item font-lock-face
+@kindex font-lock-face @r{(text property)}
+The @code{font-lock-face} property is the same in all respects as the
+@code{face} property, but its state of activation is controlled by
+@code{font-lock-mode}. This can be advantageous for special buffers
+which are not intended to be user-editable, or for static areas of
+text which are always fontified in the same way.
+@xref{Precalculated Fontification}.
+
+Strictly speaking, @code{font-lock-face} is not a built-in text
+property; rather, it is implemented in Font Lock mode using
+@code{char-property-alias-alist}. @xref{Examining Properties}.
+
+This property is new in Emacs 21.4.
@item mouse-face
@kindex mouse-face @r{(text property)}
that all text between the character and where the mouse is have the same
@code{mouse-face} property value.
-@item local-map
+@item fontified
+@kindex fontified @r{(text property)}
+This property, if non-@code{nil}, says that text in the buffer has
+had faces assigned automatically by a feature such as Font-Lock mode.
+@xref{Auto Faces}.
+
+@item display
+@kindex display @r{(text property)}
+This property activates various features that change the
+way text is displayed. For example, it can make text appear taller
+or shorter, higher or lower, wider or narrow, or replaced with an image.
+@xref{Display Property}.
+
+@item help-echo
+@kindex help-echo @r{(text property)}
+@cindex tooltip
+@anchor{Text help-echo}
+If text has a string as its @code{help-echo} property, then when you
+move the mouse onto that text, Emacs displays that string in the echo
+area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
+Manual}).
+
+If the value of the @code{help-echo} property is a function, that
+function is called with three arguments, @var{window}, @var{object} and
+@var{position} and should return a help string or @var{nil} for
+none. The first argument, @var{window} is the window in which
+the help was found. The second, @var{object}, is the buffer, overlay or
+string which had the @code{help-echo} property. The @var{position}
+argument is as follows:
+
+@itemize @bullet{}
+@item
+If @var{object} is a buffer, @var{pos} is the position in the buffer
+where the @code{help-echo} text property was found.
+@item
+If @var{object} is an overlay, that overlay has a @code{help-echo}
+property, and @var{pos} is the position in the overlay's buffer under
+the mouse.
+@item
+If @var{object} is a string (an overlay string or a string displayed
+with the @code{display} property), @var{pos} is the position in that
+string under the mouse.
+@end itemize
+
+If the value of the @code{help-echo} property is neither a function nor
+a string, it is evaluated to obtain a help string.
+
+You can alter the way help text is displayed by setting the variable
+@code{show-help-function} (@pxref{Help display}).
+
+This feature is used in the mode line and for other active text.
+
+@item keymap
@cindex keymap of character
+@kindex keymap @r{(text property)}
+The @code{keymap} property specifies an additional keymap for
+commands. The property's value for the character after point, if
+non-@code{nil}, is used for key lookup before the buffer's local map.
+(For mouse clicks, the @code{keymap} property of the character clicked
+on is the one used.) If the property value is a symbol, the symbol's
+function definition is used as the keymap. @xref{Active Keymaps}.
+
+@item local-map
@kindex local-map @r{(text property)}
-You can specify a different keymap for a portion of the text by means of
-a @code{local-map} property. The property's value for the character
-after point, if non-@code{nil}, replaces the buffer's local map.
-@xref{Active Keymaps}.
+This property specifies a keymap to use @emph{instead of} the buffer's
+local map. If the property value is a symbol, the symbol's function
+definition is used as the keymap. For most purposes (perhaps all
+purposes), the @code{keymap} is superior.
+
+@item syntax-table
+The @code{syntax-table} property overrides what the syntax table says
+about this particular character. @xref{Syntax Properties}.
@item read-only
@cindex read-only character
@kindex read-only @r{(text property)}
If a character has the property @code{read-only}, then modifying that
-character is not allowed. Any command that would do so gets an error.
+character is not allowed. Any command that would do so gets an error,
+@code{text-read-only}.
Insertion next to a read-only character is an error if inserting
ordinary text there would inherit the @code{read-only} property due to
When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
the @code{intangible} property is ignored.
+@item field
+@kindex field @r{(text property)}
+Consecutive characters with the same @code{field} property constitute a
+@dfn{field}. Some motion functions including @code{forward-word} and
+@code{beginning-of-line} stop moving at a field boundary.
+@xref{Fields}.
+
@item modification-hooks
@cindex change hooks for a character
@cindex hooks for changing a character
@code{point-left} functions are called first, followed by all the
@code{point-entered} functions.
-A primitive function may examine characters at various positions
-without moving point to those positions. Only an actual change in the
-value of point runs these hook functions.
+It is possible using @code{char-after} to examine characters at various
+positions without moving point to those positions. Only an actual
+change in the value of point runs these hook functions.
@end table
@defvar inhibit-point-motion-hooks
When this variable is non-@code{nil}, @code{point-left} and
@code{point-entered} hooks are not run, and the @code{intangible}
-property has no effect.
+property has no effect. Do not set this variable globally; bind it with
+@code{let}.
+@end defvar
+
+@defvar show-help-function
+@tindex show-help-function
+@anchor{Help display} If this variable is non-@code{nil}, it specifies a
+function called to display help strings. These may be @code{help-echo}
+properties, menu help strings (@pxref{Simple Menu Items},
+@pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
+Bar}). The specified function is called with one argument, the help
+string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs
+Manual}) provides an example.
@end defvar
@node Format Properties
using these primitives.
When you do insertion with inheritance, @emph{which} properties are
-inherited depends on two specific properties: @code{front-sticky} and
-@code{rear-nonsticky}.
-
- Insertion after a character inherits those of its properties that are
+inherited, and from where, depends on which properties are @dfn{sticky}.
+Insertion after a character inherits those of its properties that are
@dfn{rear-sticky}. Insertion before a character inherits those of its
-properties that are @dfn{front-sticky}. By default, a text property is
-rear-sticky but not front-sticky. Thus, the default is to inherit all
-the properties of the preceding character, and nothing from the
-following character. You can request different behavior by specifying
-the stickiness of certain properties.
+properties that are @dfn{front-sticky}. When both sides offer different
+sticky values for the same property, the previous character's value
+takes precedence.
+
+ By default, a text property is rear-sticky but not front-sticky; thus,
+the default is to inherit all the properties of the preceding character,
+and nothing from the following character.
+
+ You can control the stickiness of various text properties with two
+specific text properties, @code{front-sticky} and @code{rear-nonsticky},
+and with the variable @code{text-property-default-nonsticky}. You can
+use the variable to specify a different default for a given property.
+You can use those two text properties to make any specific properties
+sticky or nonsticky in any particular part of the text.
If a character's @code{front-sticky} property is @code{t}, then all
its properties are front-sticky. If the @code{front-sticky} property is
then insertion before the character can inherit its @code{face} property
and its @code{read-only} property, but no others.
- The @code{rear-nonsticky} works the opposite way. Every property is
-rear-sticky by default, so the @code{rear-nonsticky} property says which
-properties are @emph{not} rear-sticky. If a character's
-@code{rear-nonsticky} property is @code{t}, then none of its properties
-are rear-sticky. If the @code{rear-nonsticky} property is a list,
-properties are rear-sticky @emph{unless} their names are in the list.
+ The @code{rear-nonsticky} property works the opposite way. Most
+properties are rear-sticky by default, so the @code{rear-nonsticky}
+property says which properties are @emph{not} rear-sticky. If a
+character's @code{rear-nonsticky} property is @code{t}, then none of its
+properties are rear-sticky. If the @code{rear-nonsticky} property is a
+list, properties are rear-sticky @emph{unless} their names are in the
+list.
- When you insert text with inheritance, it inherits all the rear-sticky
-properties of the preceding character, and all the front-sticky
-properties of the following character. The previous character's
-properties take precedence when both sides offer different sticky values
-for the same property.
+@defvar text-property-default-nonsticky
+@tindex text-property-default-nonsticky
+This variable holds an alist which defines the default rear-stickiness
+of various text properties. Each element has the form
+@code{(@var{property} . @var{nonstickiness})}, and it defines the
+stickiness of a particular text property, @var{property}.
+
+If @var{nonstickiness} is non-@code{nil}, this means that the property
+@var{property} is rear-nonsticky by default. Since all properties are
+front-nonsticky by default, this makes @var{property} nonsticky in both
+directions by default.
+
+The text properties @code{front-sticky} and @code{rear-nonsticky}, when
+used, take precedence over the default @var{nonstickiness} specified in
+@code{text-property-default-nonsticky}.
+@end defvar
Here are the functions that insert text with inheritance of properties:
adjoining text.
@end defun
+ @xref{Insertion}, for the ordinary insertion functions which do not
+inherit.
+
@node Saving Properties
@subsection Saving Text Properties in Files
@cindex text properties in files
@cindex saving text properties
- You can save text properties in files, and restore text properties
-when inserting the files, using these two hooks:
+ You can save text properties in files (along with the text itself),
+and restore the same text properties when visiting or inserting the
+files, using these two hooks:
@defvar write-region-annotate-functions
This variable's value is a list of functions for @code{write-region} to
Each function should return a list of elements of the form
@code{(@var{position} . @var{string})}, where @var{position} is an
-integer specifying the relative position in the text to be written, and
-@var{string} is the annotation to add there.
+integer specifying the relative position within the text to be written,
+and @var{string} is the annotation to add there.
Each list returned by one of these functions must be already sorted in
increasing order by @var{position}. If there is more than one function,
various data formats and find good ones. Eventually we hope users
will produce good, general extensions we can install in Emacs.
-We suggest not trying to handle arbitrary Lisp objects as property
-names or property values---because a program that general is probably
-difficult to write, and slow. Instead, choose a set of possible data
-types that are reasonably flexible, and not too hard to encode.
+We suggest not trying to handle arbitrary Lisp objects as text property
+names or values---because a program that general is probably difficult
+to write, and slow. Instead, choose a set of possible data types that
+are reasonably flexible, and not too hard to encode.
@xref{Format Conversion}, for a related feature.
being called over and over for the same text.
@end defvar
+@node Clickable Text
+@subsection Defining Clickable Text
+@cindex clickable text
+
+ There are two ways to set up @dfn{clickable text} in a buffer.
+There are typically two parts of this: to make the text highlight
+when the mouse is over it, and to make a mouse button do something
+when you click it on that part of the text.
+
+ Highlighting is done with the @code{mouse-face} text property.
+Here is an example of how Dired does it:
+
+@smallexample
+(condition-case nil
+ (if (dired-move-to-filename)
+ (put-text-property (point)
+ (save-excursion
+ (dired-move-to-end-of-filename)
+ (point))
+ 'mouse-face 'highlight))
+ (error nil))
+@end smallexample
+
+@noindent
+The first two arguments to @code{put-text-property} specify the
+beginning and end of the text.
+
+ The usual way to make the mouse do something when you click it
+on this text is to define @code{mouse-2} in the major mode's
+keymap. The job of checking whether the click was on clickable text
+is done by the command definition. Here is how Dired does it:
+
+@smallexample
+(defun dired-mouse-find-file-other-window (event)
+ "In dired, visit the file or directory name you click on."
+ (interactive "e")
+ (let (file)
+ (save-excursion
+ (set-buffer (window-buffer (posn-window (event-end event))))
+ (save-excursion
+ (goto-char (posn-point (event-end event)))
+ (setq file (dired-get-filename))))
+ (select-window (posn-window (event-end event)))
+ (find-file-other-window (file-name-sans-versions file t))))
+@end smallexample
+
+@noindent
+The reason for the outer @code{save-excursion} construct is to avoid
+changing the current buffer; the reason for the inner one is to avoid
+permanently altering point in the buffer you click on. In this case,
+Dired uses the function @code{dired-get-filename} to determine which
+file to visit, based on the position found in the event.
+
+ Instead of defining a mouse command for the major mode, you can define
+a key binding for the clickable text itself, using the @code{keymap}
+text property:
+
+@example
+(let ((map (make-sparse-keymap)))
+ (define-key map [mouse-2] 'operate-this-button)
+ (put-text-property (point)
+ (save-excursion
+ (dired-move-to-end-of-filename)
+ (point))
+ 'keymap map))
+@end example
+
+@noindent
+This method makes it possible to define different commands for various
+clickable pieces of text. Also, the major mode definition (or the
+global definition) remains available for the rest of the text in the
+buffer.
+
+@node Fields
+@subsection Defining and Using Fields
+@cindex fields
+
+ A field is a range of consecutive characters in the buffer that are
+identified by having the same value (comparing with @code{eq}) of the
+@code{field} property (either a text-property or an overlay property).
+This section describes special functions that are available for
+operating on fields.
+
+ You specify a field with a buffer position, @var{pos}. We think of
+each field as containing a range of buffer positions, so the position
+you specify stands for the field containing that position.
+
+ When the characters before and after @var{pos} are part of the same
+field, there is no doubt which field contains @var{pos}: the one those
+characters both belong to. When @var{pos} is at a boundary between
+fields, which field it belongs to depends on the stickiness of the
+@code{field} properties of the two surrounding characters (@pxref{Sticky
+Properties}). The field whose property would be inherited by text
+inserted at @var{pos} is the field that contains @var{pos}.
+
+ There is an anomalous case where newly inserted text at @var{pos}
+would not inherit the @code{field} property from either side. This
+happens if the previous character's @code{field} property is not
+rear-sticky, and the following character's @code{field} property is not
+front-sticky. In this case, @var{pos} belongs to neither the preceding
+field nor the following field; the field functions treat it as belonging
+to an empty field whose beginning and end are both at @var{pos}.
+
+ In all of these functions, if @var{pos} is omitted or @code{nil}, the
+value of point is used by default.
+
+@defun field-beginning &optional pos escape-from-edge limit
+@tindex field-beginning
+This function returns the beginning of the field specified by @var{pos}.
+
+If @var{pos} is at the beginning of its field, and
+@var{escape-from-edge} is non-@code{nil}, then the return value is
+always the beginning of the preceding field that @emph{ends} at @var{pos},
+regardless of the stickiness of the @code{field} properties around
+@var{pos}.
+
+If @var{limit} is non-@code{nil}, it is a buffer position; if the
+beginning of the field is before @var{limit}, then @var{limit} will be
+returned instead.
+@end defun
+
+@defun field-end &optional pos escape-from-edge limit
+@tindex field-end
+This function returns the end of the field specified by @var{pos}.
+
+If @var{pos} is at the end of its field, and @var{escape-from-edge} is
+non-@code{nil}, then the return value is always the end of the following
+field that @emph{begins} at @var{pos}, regardless of the stickiness of
+the @code{field} properties around @var{pos}.
+
+If @var{limit} is non-@code{nil}, it is a buffer position; if the end
+of the field is after @var{limit}, then @var{limit} will be returned
+instead.
+@end defun
+
+@defun field-string &optional pos
+@tindex field-string
+This function returns the contents of the field specified by @var{pos},
+as a string.
+@end defun
+
+@defun field-string-no-properties &optional pos
+@tindex field-string-no-properties
+This function returns the contents of the field specified by @var{pos},
+as a string, discarding text properties.
+@end defun
+
+@defun delete-field &optional pos
+@tindex delete-field
+This function deletes the text of the field specified by @var{pos}.
+@end defun
+
+@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
+@tindex constrain-to-field
+This function ``constrains'' @var{new-pos} to the field that
+@var{old-pos} belongs to---in other words, it returns the position
+closest to @var{new-pos} that is in the same field as @var{old-pos}.
+
+If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
+the value of point instead, and moves point to the resulting position.
+
+If @var{old-pos} is at the boundary of two fields, then the acceptable
+positions for @var{new-pos} depend on the value of the optional argument
+@var{escape-from-edge}. If @var{escape-from-edge} is @code{nil}, then
+@var{new-pos} is constrained to the field that has the same @code{field}
+property (either a text-property or an overlay property) that new
+characters inserted at @var{old-pos} would get. (This depends on the
+stickiness of the @code{field} property for the characters before and
+after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
+@var{new-pos} is constrained to the union of the two adjacent fields.
+Additionally, if two fields are separated by another field with the
+special value @code{boundary}, then any point within this special field
+is also considered to be ``on the boundary.''
+
+If the optional argument @var{only-in-line} is non-@code{nil}, and
+constraining @var{new-pos} in the usual way would move it to a different
+line, @var{new-pos} is returned unconstrained. This used in commands
+that move by line, such as @code{next-line} and
+@code{beginning-of-line}, so that they respect field boundaries only in
+the case where they can still move to the right line.
+
+If the optional argument @var{inhibit-capture-property} is
+non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that
+name, then any field boundaries are ignored.
+
+You can cause @code{constrain-to-field} to ignore all field boundaries
+(and so never constrain anything) by binding the variable
+@code{inhibit-field-text-motion} to a non-nil value.
+@end defun
+
@node Not Intervals
@subsection Why Text Properties are not Intervals
@cindex intervals
So we have decided these are the only questions that make sense; we have
not implemented asking questions about where intervals start or end.
- In practice, you can usually use the property search functions in
+ In practice, you can usually use the text property search functions in
place of explicit interval boundaries. You can think of them as finding
the boundaries of intervals, assuming that intervals are always
coalesced whenever possible. @xref{Property Search}.
with the character @var{new-char} in the region of the current buffer
defined by @var{start} and @var{end}.
-@cindex Outline mode
@cindex undo avoidance
If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
not record the change for undo and does not mark the buffer as modified.
-This feature is used for controlling selective display (@pxref{Selective
-Display}).
+This was useful for controlling the old selective display feature
+(@pxref{Selective Display}).
@code{subst-char-in-region} does not move point and returns
@code{nil}.
@cindex registers
A register is a sort of variable used in Emacs editing that can hold a
-marker, a string, a rectangle, a window configuration (of one frame), or
-a frame configuration (of all frames). Each register is named by a
-single character. All characters, including control and meta characters
-(but with the exception of @kbd{C-g}), can be used to name registers.
+variety of different kinds of values. Each register is named by a
+single character. All @sc{ascii} characters and their meta variants
+(but with the exception of @kbd{C-g}) can be used to name registers.
Thus, there are 255 possible registers. A register is designated in
-Emacs Lisp by a character that is its name.
-
- The functions in this section return unpredictable values unless
-otherwise stated.
-@c Will change in version 19
+Emacs Lisp by the character that is its name.
@defvar register-alist
This variable is an alist of elements of the form @code{(@var{name} .
register that has been used.
The object @var{name} is a character (an integer) identifying the
-register. The object @var{contents} is a string, marker, or list
-representing the register contents. A string represents text stored in
-the register. A marker represents a position. A list represents a
-rectangle; its elements are strings, one per line of the rectangle.
+register.
@end defvar
+ The @var{contents} of a register can have several possible types:
+
+@table @asis
+@item a number
+A number stands for itself. If @code{insert-register} finds a number
+in the register, it converts the number to decimal.
+
+@item a marker
+A marker represents a buffer position to jump to.
+
+@item a string
+A string is text saved in the register.
+
+@item a rectangle
+A rectangle is represented by a list of strings.
+
+@item @code{(@var{window-configuration} @var{position})}
+This represents a window configuration to restore in one frame, and a
+position to jump to in the current buffer.
+
+@item @code{(@var{frame-configuration} @var{position})}
+This represents a frame configuration to restore, and a position
+to jump to in the current buffer.
+
+@item (file @var{filename})
+This represents a file to visit; jumping to this value visits file
+@var{filename}.
+
+@item (file-query @var{filename} @var{position})
+This represents a file to visit and a position in it; jumping to this
+value visits file @var{filename} and goes to buffer position
+@var{position}. Restoring this type of position asks the user for
+confirmation first.
+@end table
+
+ The functions in this section return unpredictable values unless
+otherwise stated.
+
@defun get-register reg
This function returns the contents of the register
@var{reg}, or @code{nil} if it has no contents.
all markers unrelocated.
@end defun
+@node Base 64
+@section Base 64 Encoding
+@cindex base 64 encoding
+
+ Base 64 code is used in email to encode a sequence of 8-bit bytes as
+a longer sequence of @sc{ascii} graphic characters. It is defined in
+Internet RFC@footnote{
+An RFC, an acronym for @dfn{Request for Comments}, is a numbered
+Internet informational document describing a standard. RFCs are
+usually written by technical experts acting on their own initiative,
+and are traditionally written in a pragmatic, experience-driven
+manner.
+}2045. This section describes the functions for
+converting to and from this code.
+
+@defun base64-encode-region beg end &optional no-line-break
+@tindex base64-encode-region
+This function converts the region from @var{beg} to @var{end} into base
+64 code. It returns the length of the encoded text. An error is
+signaled if a character in the region is multibyte, i.e.@: in a
+multibyte buffer the region must contain only characters from the
+charsets @code{ascii}, @code{eight-bit-control} and
+@code{eight-bit-graphic}.
+
+Normally, this function inserts newline characters into the encoded
+text, to avoid overlong lines. However, if the optional argument
+@var{no-line-break} is non-@code{nil}, these newlines are not added, so
+the output is just one long line.
+@end defun
+
+@defun base64-encode-string string &optional no-line-break
+@tindex base64-encode-string
+This function converts the string @var{string} into base 64 code. It
+returns a string containing the encoded text. As for
+@code{base64-encode-region}, an error is signaled if a character in the
+string is multibyte.
+
+Normally, this function inserts newline characters into the encoded
+text, to avoid overlong lines. However, if the optional argument
+@var{no-line-break} is non-@code{nil}, these newlines are not added, so
+the result string is just one long line.
+@end defun
+
+@defun base64-decode-region beg end
+@tindex base64-decode-region
+This function converts the region from @var{beg} to @var{end} from base
+64 code into the corresponding decoded text. It returns the length of
+the decoded text.
+
+The decoding functions ignore newline characters in the encoded text.
+@end defun
+
+@defun base64-decode-string string
+@tindex base64-decode-string
+This function converts the string @var{string} from base 64 code into
+the corresponding decoded text. It returns a string containing the
+decoded text.
+
+The decoding functions ignore newline characters in the encoded text.
+@end defun
+
+@node MD5 Checksum
+@section MD5 Checksum
+@cindex MD5 checksum
+@cindex message digest computation
+
+ MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit
+``fingerprints'' of a document or program. They are used to verify
+that you have an exact and unaltered copy of the data. The algorithm
+to calculate the MD5 message digest is defined in Internet
+RFC@footnote{
+For an explanation of what is an RFC, see the footnote in @ref{Base
+64}.
+}1321. This section describes the Emacs facilities for computing
+message digests.
+
+@defun md5 object &optional start end coding-system noerror
+This function returns the MD5 message digest of @var{object}, which
+should be a buffer or a string.
+
+The two optional arguments @var{start} and @var{end} are character
+positions specifying the portion of @var{object} to compute the
+message digest for. If they are @code{nil} or omitted, the digest is
+computed for the whole of @var{object}.
+
+The function @code{md5} does not compute the message digest directly
+from the internal Emacs representation of the text (@pxref{Text
+Representations}). Instead, it encodes the text using a coding
+system, and computes the message digest from the encoded text. The
+optional fourth argument @var{coding-system} specifies which coding
+system to use for encoding the text. It should be the same coding
+system that you used to read the text, or that you used or will use
+when saving or sending the text. @xref{Coding Systems}, for more
+information about coding systems.
+
+If @var{coding-system} is @code{nil} or omitted, the default depends
+on @var{object}. If @var{object} is a buffer, the default for
+@var{coding-system} is whatever coding system would be chosen by
+default for writing this text into a file. If @var{object} is a
+string, the user's most preferred coding system (@pxref{Recognize
+Coding, prefer-coding-system, the description of
+@code{prefer-coding-system}, emacs, GNU Emacs Manual}) is used.
+
+Normally, @code{md5} signals an error if the text can't be encoded
+using the specified or chosen coding system. However, if
+@var{noerror} is non-@code{nil}, it silently uses @code{raw-text}
+coding instead.
+@end defun
+
@node Change Hooks
@section Change Hooks
@cindex change hooks
them.
@defvar before-change-functions
-This variable holds a list of a functions to call before any buffer
+This variable holds a list of functions to call before any buffer
modification. Each function gets two arguments, the beginning and end
of the region that is about to change, represented as integers. The
buffer that is about to change is always the current buffer.
@end defvar
@defvar after-change-functions
-This variable holds a list of a functions to call after any buffer
+This variable holds a list of functions to call after any buffer
modification. Each function receives three arguments: the beginning and
end of the region just changed, and the length of the text that existed
-before the change. (To get the current length, subtract the region
-beginning from the region end.) All three arguments are integers. The
-buffer that's about to change is always the current buffer.
-@end defvar
+before the change. All three arguments are integers. The buffer that's
+about to change is always the current buffer.
-@defvar before-change-function
-This obsolete variable holds one function to call before any buffer
-modification (or @code{nil} for no function). It is called just like
-the functions in @code{before-change-functions}.
+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
-@defvar after-change-function
-This obsolete variable holds one function to call after any buffer modification
-(or @code{nil} for no function). It is called just like the functions in
-@code{after-change-functions}.
-@end defvar
+@defmac combine-after-change-calls body...
+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.
+
+If a program makes several text changes in the same area of the buffer,
+using the macro @code{combine-after-change-calls} around that part of
+the program can make it run considerably faster when after-change hooks
+are in use. When the after-change hooks are ultimately called, the
+arguments specify a portion of the buffer including all of the changes
+made within the @code{combine-after-change-calls} body.
+
+@strong{Warning:} You must not alter the values of
+@code{after-change-functions} within
+the body of a @code{combine-after-change-calls} form.
+
+@strong{Note:} If the changes you combine occur in widely scattered
+parts of the buffer, this will still work, but it is not advisable,
+because it may lead to inefficient behavior for some change hook
+functions.
+@end defmac
-The four variables above are temporarily bound to @code{nil} during the
+The two variables above are temporarily bound to @code{nil} during the
time that any of these functions is running. This means that if one of
these functions changes the buffer, that change won't run these
functions. If you do want a hook function to make changes that run
(while list
(funcall (car list) beg end len)
(setq list (cdr list)))))
+
+@group
(add-hooks 'after-change-functions
'indirect-after-change-function)
+@end group
@end example
@defvar first-change-hook
This variable is a normal hook that is run whenever a buffer is changed
that was previously in the unmodified state.
@end defvar
+
+@defvar inhibit-modification-hooks
+@tindex inhibit-modification-hooks
+If this variable is non-@code{nil}, all of the change hooks are
+disabled; none of them run. This affects all the hook variables
+described above in this section, as well as the hooks attached to
+certain special text properties (@pxref{Special Properties}) and overlay
+properties (@pxref{Overlay Properties}).
+
+This variable is available starting in Emacs 21.
+@end defvar
HCoop / bpt / emacs.git / blobdiff