@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000
-@c 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, Non-ASCII Characters, Markers, Top
* 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''.
+* Atomic Changes:: Installing several buffer changs ``atomically''.
* Change Hooks:: Supplying functions to be run when text is changed.
@end menu
@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
+this purpose, either at or before the beginning of the buffer, or beyond
the end, then the value is @code{nil}. The default for
@var{position} is point.
@end defun
@end example
@end defun
+@tindex current-word
+@defun current-word &optional strict really-word
+This function returns the symbol (or word) at or near point, as a string.
+The return value includes no text properties.
+
+The optional argument @var{really-word} is non-@code{nil}, it finds a
+word; otherwise, it finds a symbol (which includes word characters and
+both symbol constituent characters).
+
+If the optional argument @var{strict} is non-@code{nil}, then point
+must be in or next to the symbol or word---if no symbol or word is
+there, the function returns @code{nil}. Otherwise, a nearby symbol or
+word on the same line is acceptable.
+@end defun
+
@defun thing-at-point thing
Return the @var{thing} around or next to point, as a string.
the insertion point, the inserted text falls inside that overlay.
@end defun
-@defun insert-char character &optional count inherit
+@defun insert-char character count &optional inherit
This function inserts @var{count} instances of @var{character} into the
current buffer before point. The argument @var{count} should be a
number (@code{nil} means 1), and @var{character} must be a character.
---------- Buffer: bar ----------
@end group
@end example
+@end defun
+
+@defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
+This is like @code{insert-buffer-substring} except that it does not
+copy any text properties.
@end defun
@xref{Sticky Properties}, for other insertion functions that inherit
loop handles this function specially.
@end deffn
-@deffn Command newline &optional number-of-newlines
+@deffn Command newline &optional number-of-newlines
This command inserts newlines into the current buffer before point.
If @var{number-of-newlines} is supplied, that many newline characters
are inserted.
@end example
@end deffn
-@deffn Command delete-indentation &optional join-following-p
+@deffn Command delete-indentation &optional join-following-p
This function joins the line point is on to the previous line, deleting
any whitespace at the join and in some cases replacing it with one
space. If @var{join-following-p} is non-@code{nil},
@menu
* Kill Ring Concepts:: What text looks like in the kill ring.
* Kill Functions:: Functions that kill text.
+* Yanking:: How yanking is done.
* Yank Commands:: Commands that access the kill ring.
* Low-Level Kill Ring:: Functions and variables for kill ring access.
* Internals of Kill Ring:: Variables that hold kill-ring data.
@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
+@deffn Command kill-region start end &optional yank-handler
This function kills the text in the region defined by @var{start} and
@var{end}. The text is deleted but saved in the kill ring, along with
its text properties. The value is always @code{nil}.
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.
+
+If @var{yank-handler} is non-@code{nil}, this puts that value onto
+the string of killed text, as a @code{yank-handler} property.
+@xref{Yanking}.
@end deffn
@defopt kill-read-only-ok
Ring}.
@end deffn
+@node Yanking
+@subsection Yanking
+
+ Yanking means inserting text from the kill ring, but it does
+not insert the text blindly. Yank commands and some other commands
+use @code{insert-for-yank} to perform special processing on the
+text that they copy into the buffer.
+
+@defun insert-for-yank string
+This function normally works like @code{insert} except that it doesn't
+insert the text properties in the @code{yank-excluded-properties}
+list. However, if the first character of @var{string} has a
+non-@code{nil}@code{yank-handler} text property, that property
+can do various special processing on the text being inserted.
+@end defun
+
+@defun insert-buffer-substring-as-yank buf &optional start end
+This function resembles @code{insert-buffer-substring} except that it
+doesn't insert the text properties in the
+@code{yank-excluded-properties} list.
+@end defun
+
+ You can put a @code{yank-handler} text property on the text to
+control how it will be inserted if it is yanked. The
+@code{insert-for-yank} function looks for a @code{yank-handler}
+property on the first character in its @var{string} argument. The
+property value must be a list of one to four elements, with the
+following format (where elements after the first may be omitted):
+
+@example
+(@var{function} @var{param} @var{noexclude} @var{undo})
+@end example
+
+ Here is what the elements do:
+
+@table @var
+@item function
+When @var{function} is present and non-nil, it is called instead of
+@code{insert} to insert the string. @var{function} takes one
+argument---the string to insert.
+
+@item param
+If @var{param} is present and non-@code{nil}, it replaces @var{string}
+as the object passed to @var{function} (or @code{insert}); for
+example, if @var{function} is @code{yank-rectangle}, @var{param}
+should be a list of strings to insert as a rectangle.
+
+@item noexclude
+If @var{noexclude} is present and non-@code{nil}, the normal removal of the
+yank-excluded-properties is not performed; instead @var{function} is
+responsible for removing those properties. This may be necessary
+if @var{function} adjusts point before or after inserting the object.
+
+@item undo
+If @var{undo} is present and non-nil, it is a function that will be
+called by @code{yank-pop} to undo the insertion of the current object.
+It is called with two arguments, the start and end of the current
+region. @var{function} can set @code{yank-undo-function} to override
+the @var{undo} value.
+@end table
+
@node Yank Commands
@comment node-name, next, previous, up
@subsection Functions for Yanking
The return value is always @code{nil}.
@end deffn
+@defvar yank-undo-function
+If this variable is non-@code{nil}, the function @code{yank-pop} uses
+its value instead of @code{delete-region} to delete the text
+inserted by the previous @code{yank} or
+@code{yank-pop} command.
+
+The function @code{insert-for-yank} automatically sets this variable
+according to the @var{undo} element of the @code{yank-handler}
+text property, if there is one.
+@end defvar
+
@node Low-Level Kill Ring
@subsection Low-Level Kill Ring
the kill ring.
@end defun
-@defun kill-new string
+@defun kill-new string &optional yank-handler
This function puts the text @var{string} into the kill ring as a new
entry at the front of the ring. It discards the oldest entry if
appropriate. It also invokes the value of
@code{interprogram-cut-function} (see below).
+
+If @var{yank-handler} is non-@code{nil}, this puts that value onto
+the string of killed text, as a @code{yank-handler} property.
+@xref{Yanking}.
@end defun
-@defun kill-append string before-p
+@defun kill-append string before-p &optional yank-handler
This function appends the text @var{string} to the first entry in the
kill ring. Normally @var{string} goes at the end of the entry, but if
@var{before-p} is non-@code{nil}, it goes at the beginning. This
function also invokes the value of @code{interprogram-cut-function} (see
-below).
+below). This handles @var{yank-handler} just like @code{kill-new}.
@end defun
@defvar interprogram-paste-function
The variable @code{kill-ring} holds the kill ring contents, in the
form of a list of strings. The most recent kill is always at the front
-of the list.
+of the list.
The @code{kill-ring-yank-pointer} variable points to a link in the
kill ring list, whose @sc{car} is the text to yank next. We say it
Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
pointing to the second entry in the kill ring @code{("some text" "a
-different piece of text" "yet older text")}.
+different piece of text" "yet older text")}.
@example
@group
| --- --- --- --- --- ---
--> | | |------> | | |--> | | |--> nil
--- --- --- --- --- ---
- | | |
- | | |
- | | -->"yet older text"
+ | | |
+ | | |
+ | | -->"yet older text"
| |
- | --> "a different piece of text"
+ | --> "a different piece of text"
|
--> "some text"
@end group
@item (@var{beg} . @var{end})
This kind of element indicates how to delete text that was inserted.
-Upon insertion, the text occupied the range @var{beg}--@var{end} in the
+Upon insertion, the text occupied the range @var{beg}--@var{end} in the
buffer.
@item (@var{text} . @var{position})
Column number computations ignore the width of the window and the
amount of horizontal scrolling. Consequently, a column value can be
-arbitrarily high. The first (or leftmost) column is numbered 0.
+arbitrarily high. The first (or leftmost) column is numbered 0. They
+also ignore overlays and text properties, aside from invisibility.
@defun current-column
This function returns the horizontal position of point, measured in
These commands, primarily for interactive use, act based on the
indentation in the text.
-@deffn Command back-to-indentation
+@deffn Command back-to-indentation
@comment !!SourceFile simple.el
This command moves point to the first non-whitespace character in the
current line (which is the line in which point is located). It returns
@code{nil}.
@end deffn
-@deffn Command backward-to-indentation arg
+@deffn Command backward-to-indentation &optional arg
@comment !!SourceFile simple.el
This command moves point backward @var{arg} lines and then to the
first nonblank character on that line. It returns @code{nil}.
+If @var{arg} is omitted or @code{nil}, it defaults to 1.
@end deffn
-@deffn Command forward-to-indentation arg
+@deffn Command forward-to-indentation &optional arg
@comment !!SourceFile simple.el
This command moves point forward @var{arg} lines and then to the first
nonblank character on that line. It returns @code{nil}.
+If @var{arg} is omitted or @code{nil}, it defaults to 1.
@end deffn
@node Case Changes
@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.
-* 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.
+* 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
the @var{prop} property of that symbol.
@end defun
-@defun get-char-property pos prop &optional object
+@defun get-char-property position prop &optional object
This function is like @code{get-text-property}, except that it checks
overlays first and then text properties. @xref{Overlays}.
overlays.
@end defun
+@defun get-char-property-and-overlay position prop &optional object
+This is like @code{get-char-property}, but gives extra information
+about the overlay that the property value comes from.
+
+Its value is a cons cell whose @sc{car} is the property value, the
+same value @code{get-char-property} would return with the same
+arguments. Its @sc{cdr} is the overlay in which the property was
+found, or @code{nil}, if it was found as a text property or not found
+at all.
+
+If @var{position} is at the end of @var{object}, both the @sc{car} and
+the @sc{cdr} of the value are @code{nil}.
+@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-@code{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.}
properties specified by name.
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}).
+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}).
+Positions in a string start from 0, whereas positions in a buffer
+start from 1.
@defun put-text-property start end prop value &optional object
This function sets the @var{prop} property to @var{value} for the text
list.
@end defun
+@defun remove-list-of-text-properties start end list-of-properties &optional object
+Like @code{remove-list-properties} except that
+@var{list-of-properties} is a list property names only, not an
+alternating list of property values.
+@end defun
+
@defun set-text-properties start end props &optional object
This function completely replaces the text property list for the text
between @var{start} and @var{end} in the string or buffer @var{object}.
@var{pos}.
If @var{limit} is non-@code{nil}, then the scan ends at position
-@var{limit}. If there is no property change before that point,
+@var{limit}. If there is no property change before that point,
@code{next-property-change} returns @var{limit}.
The value is @code{nil} if the properties remain unchanged all the way
@var{pos}.
If @var{limit} is non-@code{nil}, then the scan ends at position
-@var{limit}. If there is no property change before that point,
+@var{limit}. If there is no property change before that point,
@code{next-single-property-change} returns @var{limit}.
The value is @code{nil} if the property remains unchanged all the way to
@var{limit} equals @var{pos}.
@end defun
-@defun next-char-property-change position &optional limit
+@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. 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.
+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 position &optional limit
+@defun previous-char-property-change pos &optional limit
This is like @code{next-char-property-change}, but scans back from
-@var{position} instead of forward.
+@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
@code{(:foreground @var{color-name})}, and likewise for the background.
@end itemize
-@xref{Font Lock Mode}, for information on how to update @code{face}
-properties automatically based on the contents of the text.
+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)}
@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.
+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
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. It is
-available starting in Emacs 21.
+This feature is used in the mode line and for other active text.
-@item local-map
+@item keymap
@cindex keymap of character
-@kindex local-map @r{(text property)}
-You can specify a different keymap for some of the text in a buffer by
-means of the @code{local-map} property. The property's value for the
-character after point, if non-@code{nil}, is used for key lookup instead
-of the buffer's local map. If the property value is a symbol, the
-symbol's function definition is used as the keymap. @xref{Active
+@kindex keymap @r{(text property)}
+The @code{keymap} property specifies an additional keymap for
+commands. The property's value for the character before point applies
+if it is non-@code{nil} and rear-sticky, and the property's value for
+the character after point applies if it is non-@code{nil} and
+front-sticky. (For mouse clicks, the position of the click is used
+instead of the position of point.) If the property value is a symbol,
+the symbol's function definition is used as the keymap.
+
+When this keymap applies, it is used for key lookup before the minor
+mode keymaps and before the buffer's local map. @xref{Active
Keymaps}.
-@item keymap
-@kindex keymap @r{(text property)}
-The @code{keymap} property is similar to @code{local-map} but overrides the
-buffer's local map (and the map specified by the @code{local-map}
-property) rather than replacing it.
+@item local-map
+@kindex local-map @r{(text property)}
+This property works like @code{keymap} except that it specifies a
+keymap to use @emph{instead of} the buffer's local map. 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
directions by default.
The text properties @code{front-sticky} and @code{rear-nonsticky}, when
-used, take precedence over the default @var{nonstickiness} specifed in
+used, take precedence over the default @var{nonstickiness} specified in
@code{text-property-default-nonsticky}.
@end defvar
We invite users to write Lisp programs to store and retrieve text
properties in files, using these hooks, and thus to experiment with
-various data formats and find good ones. Eventually we hope users
+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 text property
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
+@defun field-beginning &optional pos escape-from-edge limit
@tindex field-beginning
This function returns the beginning of the field specified by @var{pos}.
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
+@defun field-end &optional pos escape-from-edge limit
@tindex field-end
This function returns the end of the field specified by @var{pos}.
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
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.
+@code{inhibit-field-text-motion} to a non-@code{nil} value.
@end defun
@node Not Intervals
A register is a sort of variable used in Emacs editing that can hold a
variety of different kinds of values. Each register is named by a
-single character. All @sc{ascii} characters and their meta variants
+single character. All @acronym{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 the character that is its name.
@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 2045. This section describes the functions for
+a longer sequence of @acronym{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
@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
+the corresponding decoded text. It returns a unibyte 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 Atomic Changes
+@section Atomic Change Groups
+@cindex atomic changes
+
+ In data base terminology, an @dfn{atomic} change is an indivisible
+change---it can succeed entirely or it can fail entirely, but it
+cannot partly succeed. A Lisp program can make a series of changes to
+one or several buffers as an @dfn{atomic change group}, meaning that
+either the entire series of changes will be installed in their buffers
+or, in case of an error, none of them will be.
+
+ To do this for one buffer, the one already current, simply write a
+call to @code{atomic-change-group} around the code that makes the
+changes, like this:
+
+@example
+(atomic-change-group
+ (insert foo)
+ (delete-region x y))
+@end example
+
+@noindent
+If an error (or other nonlocal exit) occurs inside the body of
+@code{atomic-change-group}, it unmakes all the changes in that buffer
+that were during the execution of the body. This kind of change group
+has no effect on any other buffers--any such changes remain.
+
+ If you need something more sophisticated, such as to make changes in
+various buffers constitute one atomic group, you must directly call
+lower-level functions that @code{atomic-change-group} uses.
+
+@defun prepare-change-group &optional buffer
+This function sets up a change group for buffer @var{buffer}, which
+defaults to the current buffer. It returns a ``handle'' that
+represents the change group. You must use this handle to activate the
+change group and subsequently to finish it.
+@end defun
+
+ To use the change group, you must @dfn{activate} it. You must do
+this before making any changes in the text of @var{buffer}.
+
+@defun activate-change-group handle
+This function activates the change group that @var{handle} designates.
+@end defun
+
+ After you activate the change group, any changes you make in that
+buffer become part of it. Once you have made all the desired changes
+in the buffer, you must @dfn{finish} the change group. There are two
+ways to do this: you can either accept (and finalize) all the changes,
+or cancel them all.
+
+@defun accept-change-group handle
+This function accepts all the changes in the change group specified by
+@var{handle}, making them final.
+@end defun
+
+@defun cancel-change-group handle
+This function cancels and undoes all the changes in the change group
+specified by @var{handle}.
+@end defun
+
+ Your code should use @code{unwind-protect} to make sure the group is
+always finished. The call to @code{activate-change-group} should be
+inside the @code{unwind-protect}, in case the user types @kbd{C-g}
+just after it runs. (This is one reason why
+@code{prepare-change-group} and @code{activate-change-group} are
+separate functions, because normally you would call
+@code{prepare-change-group} before the start of that
+@code{unwind-protect}.) Once you finish the group, don't use the
+handle again---in particular, don't try to finish the same group
+twice.
+
+ To make a multibuffer change group, call @code{prepare-change-group}
+once for each buffer you want to cover, then use @code{nconc} to
+combine the returned values, like this:
+
+@example
+(nconc (prepare-change-group buffer-1)
+ (prepare-change-group buffer-2))
+@end example
+
+You can then activate the multibuffer change group with a single call
+to @code{activate-change-group}, and finish it with a single call to
+@code{accept-change-group} or @code{cancel-change-group}.
+
+ Nested use of several change groups for the same buffer works as you
+would expect. Non-nested use of change groups for the same buffer
+will get Emacs confused, so don't let it happen; the first change
+group you start for any given buffer should be the last one finished.
+
@node Change Hooks
@section Change Hooks
@cindex change hooks
arguments.
@end defvar
+ Output of messges into the @samp{*Messages*} buffer does not
+call these functions.
+
@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
@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
+@strong{Warning:} 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.
This variable is available starting in Emacs 21.
@end defvar
+
+@ignore
+ arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b
+@end ignore
HCoop / bpt / emacs.git / blobdiff