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 |
|
|
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 |
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. |
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}. |
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 |
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 |
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 |
|
|
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 |
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}. |
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 |