/[emacs]/emacs/lispref/text.texi
ViewVC logotype

Diff of /emacs/lispref/text.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.64 by rms, Mon Jul 14 15:51:54 2003 UTC revision 1.65 by rms, Wed Aug 13 17:28:31 2003 UTC
# Line 58  the character after point. Line 58  the character after point.
58                         position stored in a register.                         position stored in a register.
59  * Base 64::          Conversion to or from base 64 encoding.  * Base 64::          Conversion to or from base 64 encoding.
60  * MD5 Checksum::     Compute the MD5 ``message digest''/``checksum''.  * MD5 Checksum::     Compute the MD5 ``message digest''/``checksum''.
61    * Atomic Changes::   Installing several buffer changs ``atomically''.
62  * Change Hooks::     Supplying functions to be run when text is changed.  * Change Hooks::     Supplying functions to be run when text is changed.
63  @end menu  @end menu
64    
# Line 398  We hold these truth@point{} Line 399  We hold these truth@point{}
399  @end example  @end example
400  @end defun  @end defun
401    
402    @defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
403    This is like @code{insert-buffer-substring} except that it does not
404    copy any text properties.
405    @end defun
406    
407    @xref{Sticky Properties}, for other insertion functions that inherit    @xref{Sticky Properties}, for other insertion functions that inherit
408  text properties from the nearby text in addition to inserting it.  text properties from the nearby text in addition to inserting it.
409  Whitespace inserted by indentation functions also inherits text  Whitespace inserted by indentation functions also inherits text
# Line 761  would be difficult to change the termino Line 767  would be difficult to change the termino
767  @menu  @menu
768  * Kill Ring Concepts::     What text looks like in the kill ring.  * Kill Ring Concepts::     What text looks like in the kill ring.
769  * Kill Functions::         Functions that kill text.  * Kill Functions::         Functions that kill text.
770    * Yanking::                How yanking is done.
771  * Yank Commands::          Commands that access the kill ring.  * Yank Commands::          Commands that access the kill ring.
772  * Low-Level Kill Ring::    Functions and variables for kill ring access.  * Low-Level Kill Ring::    Functions and variables for kill ring access.
773  * Internals of Kill Ring:: Variables that hold kill-ring data.  * Internals of Kill Ring:: Variables that hold kill-ring data.
# Line 805  adds it to the most recent element.  It Line 812  adds it to the most recent element.  It
812  @code{last-command}) whether the previous command was a kill command,  @code{last-command}) whether the previous command was a kill command,
813  and if so appends the killed text to the most recent entry.  and if so appends the killed text to the most recent entry.
814    
815  @deffn Command kill-region start end  @deffn Command kill-region start end &optional yank-handler
816  This function kills the text in the region defined by @var{start} and  This function kills the text in the region defined by @var{start} and
817  @var{end}.  The text is deleted but saved in the kill ring, along with  @var{end}.  The text is deleted but saved in the kill ring, along with
818  its text properties.  The value is always @code{nil}.  its text properties.  The value is always @code{nil}.
# Line 818  If the buffer or text is read-only, @cod Line 825  If the buffer or text is read-only, @cod
825  ring just the same, then signals an error without modifying the buffer.  ring just the same, then signals an error without modifying the buffer.
826  This is convenient because it lets the user use a series of kill  This is convenient because it lets the user use a series of kill
827  commands to copy text from a read-only buffer into the kill ring.  commands to copy text from a read-only buffer into the kill ring.
828    
829    If @var{yank-handler} is non-@code{nil}, this puts that value onto
830    the string of killed text, as a @code{yank-handler} property.
831    @xref{Yanking}.
832  @end deffn  @end deffn
833    
834  @defopt kill-read-only-ok  @defopt kill-read-only-ok
# Line 842  support Emacs 18.  For newer Emacs versi Line 853  support Emacs 18.  For newer Emacs versi
853  Ring}.  Ring}.
854  @end deffn  @end deffn
855    
856    @node Yanking
857    @subsection Yanking
858    
859      Yanking means inserting text from the kill ring, but it does
860    not insert the text blindly.  Yank commands and some other commands
861    use @code{insert-for-yank} to perform special processing on the
862    text that they copy into the buffer.
863    
864    @defun insert-for-yank string
865    This function normally works like @code{insert} except that it doesn't
866    insert the text properties in the @code{yank-excluded-properties}
867    list.  However, if the first character of @var{string} has a
868    non-@code{nil}@code{yank-handler} text property, that property
869    can do various special processing on the text being inserted.
870    @end defun
871    
872    @defun insert-buffer-substring-as-yank buf &optional start end
873    This function resembles @code{insert-buffer-substring} except that it
874    doesn't insert the text properties in the
875    @code{yank-excluded-properties} list.
876    @end defun
877    
878      You can put a @code{yank-handler} text property on the text to
879    control how it will be inserted if it is yanked.  The
880    @code{insert-for-yank} function looks for a @code{yank-handler}
881    property on the first character in its @var{string} argument.  The
882    property value must be a list of one to four elements, with the
883    following format (where elements after the first may be omitted):
884    
885    @example
886    (@var{function} @var{param} @var{noexclude} @var{undo})
887    @end example
888    
889      Here is what the elements do:
890    
891    @table @var
892    @item function
893    When @var{function} is present and non-nil, it is called instead of
894    @code{insert} to insert the string.  @var{function} takes one
895    argument---the string to insert.
896    
897    @item param
898    If @var{param} is present and non-@code{nil}, it replaces @var{string}
899    as the object passed to @var{function} (or @code{insert}); for
900    example, if @var{function} is @code{yank-rectangle}, @var{param}
901    should be a list of strings to insert as a rectangle.
902    
903    @item noexclude
904    If @var{noexclude} is present and non-@code{nil}, the normal removal of the
905    yank-excluded-properties is not performed; instead @var{function} is
906    responsible for removing those properties.  This may be necessary
907    if @var{function} adjusts point before or after inserting the object.
908    
909    @item undo
910    If @var{undo} is present and non-nil, it is a function that will be
911    called by @code{yank-pop} to undo the insertion of the current object.
912    It is called with two arguments, the start and end of the current
913    region.  @var{function} can set @code{yank-undo-function} to override
914    the @var{undo} value.
915    @end table
916    
917  @node Yank Commands  @node Yank Commands
918  @comment  node-name,  next,  previous,  up  @comment  node-name,  next,  previous,  up
919  @subsection Functions for Yanking  @subsection Functions for Yanking
# Line 889  oldest. Line 961  oldest.
961  The return value is always @code{nil}.  The return value is always @code{nil}.
962  @end deffn  @end deffn
963    
964    @defvar yank-undo-function
965    If this variable is non-@code{nil}, the function @code{yank-pop} uses
966    its value instead of @code{delete-region} to delete the text
967    inserted by the previous @code{yank} or
968    @code{yank-pop} command.
969    
970    The function @code{insert-for-yank} automatically sets this variable
971    according to the @var{undo} element of the @code{yank-handler}
972    text property, if there is one.
973    @end defvar
974    
975  @node Low-Level Kill Ring  @node Low-Level Kill Ring
976  @subsection Low-Level Kill Ring  @subsection Low-Level Kill Ring
977    
# Line 912  If @var{n} is zero, indicating a request Line 995  If @var{n} is zero, indicating a request
995  the kill ring.  the kill ring.
996  @end defun  @end defun
997    
998  @defun kill-new string  @defun kill-new string &optional yank-handler
999  This function puts the text @var{string} into the kill ring as a new  This function puts the text @var{string} into the kill ring as a new
1000  entry at the front of the ring.  It discards the oldest entry if  entry at the front of the ring.  It discards the oldest entry if
1001  appropriate.  It also invokes the value of  appropriate.  It also invokes the value of
1002  @code{interprogram-cut-function} (see below).  @code{interprogram-cut-function} (see below).
1003    
1004    If @var{yank-handler} is non-@code{nil}, this puts that value onto
1005    the string of killed text, as a @code{yank-handler} property.
1006    @xref{Yanking}.
1007  @end defun  @end defun
1008    
1009  @defun kill-append string before-p  @defun kill-append string before-p &optional yank-handler
1010  This function appends the text @var{string} to the first entry in the  This function appends the text @var{string} to the first entry in the
1011  kill ring.  Normally @var{string} goes at the end of the entry, but if  kill ring.  Normally @var{string} goes at the end of the entry, but if
1012  @var{before-p} is non-@code{nil}, it goes at the beginning.  This  @var{before-p} is non-@code{nil}, it goes at the beginning.  This
1013  function also invokes the value of @code{interprogram-cut-function} (see  function also invokes the value of @code{interprogram-cut-function} (see
1014  below).  below).  This handles @var{yank-handler} just like @code{kill-new}.
1015  @end defun  @end defun
1016    
1017  @defvar interprogram-paste-function  @defvar interprogram-paste-function
# Line 2435  To remove all text properties from certa Line 2522  To remove all text properties from certa
2522  list.  list.
2523  @end defun  @end defun
2524    
2525    @defun remove-list-of-text-properties start end list-of-properties &optional object
2526    Like @code{remove-list-properties} except that
2527    @var{list-of-properties} is a list property names only, not an
2528    alternating list of property values.
2529    @end defun
2530    
2531  @defun set-text-properties start end props &optional object  @defun set-text-properties start end props &optional object
2532  This function completely replaces the text property list for the text  This function completely replaces the text property list for the text
2533  between @var{start} and @var{end} in the string or buffer @var{object}.  between @var{start} and @var{end} in the string or buffer @var{object}.
# Line 3697  using the specified or chosen coding sys Line 3790  using the specified or chosen coding sys
3790  coding instead.  coding instead.
3791  @end defun  @end defun
3792    
3793    @node Atomic Changes
3794    @section Atomic Change Groups
3795    @cindex atomic changes
3796    
3797      In data base terminology, an @dfn{atomic} change is an indivisible
3798    change---it can succeed entirely or it can fail entirely, but it
3799    cannot partly succeed.  A Lisp program can make a series of changes to
3800    one or several buffers as an @dfn{atomic change group}, meaning that
3801    either the entire series of changes will be installed in their buffers
3802    or, in case of an error, none of them will be.
3803    
3804      To do this for one buffer, the one already current, simply write a
3805    call to @code{atomic-change-group} around the code that makes the
3806    changes, like this:
3807    
3808    @example
3809    (atomic-change-group
3810      (insert foo)
3811      (delete-region x y))
3812    @end example
3813    
3814    @noindent
3815    If an error (or other nonlocal exit) occurs inside the body of
3816    @code{atomic-change-group}, it unmakes all the changes in that buffer
3817    that were during the execution of the body.  This kind of change group
3818    has no effect on any other buffers--any such changes remain.
3819    
3820      If you need something more sophisticated, such as to make changes in
3821    various buffers constitute one atomic group, you must directly call
3822    lower-level functions that @code{atomic-change-group} uses.
3823    
3824    @defun prepare-change-group &optional buffer
3825    This function sets up a change group for buffer @var{buffer}, which
3826    defaults to the current buffer.  It returns a ``handle'' that
3827    represents the change group.  You must use this handle to activate the
3828    change group and subsequently to finish it.
3829    @end defun
3830    
3831      To use the change group, you must @dfn{activate} it.  You must do
3832    this before making any changes in the text of @var{buffer}.
3833    
3834    @defun activate-change-group handle
3835    This function activates the change group that @var{handle} designates.
3836    @end defun
3837    
3838      After you activate the change group, any changes you make in that
3839    buffer become part of it.  Once you have made all the desired changes
3840    in the buffer, you must @dfn{finish} the change group.  There are two
3841    ways to do this: you can either accept (and finalize) all the changes,
3842    or cancel them all.
3843    
3844    @defun accept-change-group handle
3845    This function accepts all the changes in the change group specified by
3846    @var{handle}, making them final.
3847    @end defun
3848    
3849    @defun cancel-change-group handle
3850    This function cancels and undoes all the changes in the change group
3851    specified by @var{handle}.
3852    @end defun
3853    
3854      Your code should use @code{unwind-protect} to make sure the group is
3855    always finished.  The call to @code{activate-change-group} should be
3856    inside the @code{unwind-protect}, in case the user types @kbd{C-g}
3857    just after it runs.  (This is one reason why
3858    @code{prepare-change-group} and @code{activate-change-group} are
3859    separate functions, because normally you would call
3860    @code{prepare-change-group} before the start of that
3861    @code{unwind-protect}.)  Once you finish the group, don't use the
3862    handle again---in particular, don't try to finish the same group
3863    twice.
3864    
3865      To make a multibuffer change group, call @code{prepare-change-group}
3866    once for each buffer you want to cover, then use @code{nconc} to
3867    combine the returned values, like this:
3868    
3869    @example
3870    (nconc (prepare-change-group buffer-1)
3871           (prepare-change-group buffer-2))
3872    @end example
3873    
3874    You can then activate the multibuffer change group with a single call
3875    to @code{activate-change-group}, and finish it with a single call to
3876    @code{accept-change-group} or @code{cancel-change-group}.
3877    
3878      Nested use of several change groups for the same buffer works as you
3879    would expect.  Non-nested use of change groups for the same buffer
3880    will get Emacs confused, so don't let it happen; the first change
3881    group you start for any given buffer should be the last one finished.
3882    
3883  @node Change Hooks  @node Change Hooks
3884  @section Change Hooks  @section Change Hooks
3885  @cindex change hooks  @cindex change hooks

Legend:
Removed from v.1.64  
changed lines
  Added in v.1.65

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26