[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/lispref/text.texi
From: |
Richard M. Stallman |
Subject: |
[Emacs-diffs] Changes to emacs/lispref/text.texi |
Date: |
Wed, 13 Aug 2003 13:28:31 -0400 |
Index: emacs/lispref/text.texi
diff -c emacs/lispref/text.texi:1.64 emacs/lispref/text.texi:1.65
*** emacs/lispref/text.texi:1.64 Mon Jul 14 11:51:54 2003
--- emacs/lispref/text.texi Wed Aug 13 13:28:31 2003
***************
*** 58,63 ****
--- 58,64 ----
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
***************
*** 398,403 ****
--- 399,409 ----
@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
text properties from the nearby text in addition to inserting it.
Whitespace inserted by indentation functions also inherits text
***************
*** 761,766 ****
--- 767,773 ----
@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.
***************
*** 805,811 ****
@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
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}.
--- 812,818 ----
@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 &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}.
***************
*** 818,823 ****
--- 825,834 ----
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 address@hidden, 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
***************
*** 842,847 ****
--- 853,919 ----
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
+ address@hidden@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 address@hidden, 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 address@hidden, 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
***************
*** 889,894 ****
--- 961,977 ----
The return value is always @code{nil}.
@end deffn
+ @defvar yank-undo-function
+ If this variable is address@hidden, 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
***************
*** 912,930 ****
the kill ring.
@end defun
! @defun kill-new string
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).
@end defun
! @defun kill-append string before-p
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 address@hidden, it goes at the beginning. This
function also invokes the value of @code{interprogram-cut-function} (see
! below).
@end defun
@defvar interprogram-paste-function
--- 995,1017 ----
the kill ring.
@end defun
! @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 address@hidden, 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 &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 address@hidden, it goes at the beginning. This
function also invokes the value of @code{interprogram-cut-function} (see
! below). This handles @var{yank-handler} just like @code{kill-new}.
@end defun
@defvar interprogram-paste-function
***************
*** 2435,2440 ****
--- 2522,2533 ----
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}.
***************
*** 3696,3701 ****
--- 3789,3884 ----
@var{noerror} is address@hidden, 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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] Changes to emacs/lispref/text.texi,
Richard M. Stallman <=