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 |
|
|
90 |
@defun char-before &optional position |
@defun char-before &optional position |
91 |
This function returns the character in the current buffer immediately |
This function returns the character in the current buffer immediately |
92 |
before position @var{position}. If @var{position} is out of range for |
before position @var{position}. If @var{position} is out of range for |
93 |
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 |
94 |
the end, then the value is @code{nil}. The default for |
the end, then the value is @code{nil}. The default for |
95 |
@var{position} is point. |
@var{position} is point. |
96 |
@end defun |
@end defun |
225 |
@end example |
@end example |
226 |
@end defun |
@end defun |
227 |
|
|
228 |
|
@tindex current-word |
229 |
|
@defun current-word &optional strict really-word |
230 |
|
This function returns the symbol (or word) at or near point, as a string. |
231 |
|
The return value includes no text properties. |
232 |
|
|
233 |
|
The optional argument @var{really-word} is non-@code{nil}, it finds a |
234 |
|
word; otherwise, it finds a symbol (which includes word characters and |
235 |
|
both symbol constituent characters). |
236 |
|
|
237 |
|
If the optional argument @var{strict} is non-@code{nil}, then point |
238 |
|
must be in or next to the symbol or word---if no symbol or word is |
239 |
|
there, the function returns @code{nil}. Otherwise, a nearby symbol or |
240 |
|
word on the same line is acceptable. |
241 |
|
@end defun |
242 |
|
|
243 |
@defun thing-at-point thing |
@defun thing-at-point thing |
244 |
Return the @var{thing} around or next to point, as a string. |
Return the @var{thing} around or next to point, as a string. |
245 |
|
|
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 |
2232 |
@code{nil}. |
@code{nil}. |
2233 |
@end deffn |
@end deffn |
2234 |
|
|
2235 |
@deffn Command backward-to-indentation arg |
@deffn Command backward-to-indentation &optional arg |
2236 |
@comment !!SourceFile simple.el |
@comment !!SourceFile simple.el |
2237 |
This command moves point backward @var{arg} lines and then to the |
This command moves point backward @var{arg} lines and then to the |
2238 |
first nonblank character on that line. It returns @code{nil}. |
first nonblank character on that line. It returns @code{nil}. |
2239 |
|
If @var{arg} is omitted or @code{nil}, it defaults to 1. |
2240 |
@end deffn |
@end deffn |
2241 |
|
|
2242 |
@deffn Command forward-to-indentation arg |
@deffn Command forward-to-indentation &optional arg |
2243 |
@comment !!SourceFile simple.el |
@comment !!SourceFile simple.el |
2244 |
This command moves point forward @var{arg} lines and then to the first |
This command moves point forward @var{arg} lines and then to the first |
2245 |
nonblank character on that line. It returns @code{nil}. |
nonblank character on that line. It returns @code{nil}. |
2246 |
|
If @var{arg} is omitted or @code{nil}, it defaults to 1. |
2247 |
@end deffn |
@end deffn |
2248 |
|
|
2249 |
@node Case Changes |
@node Case Changes |
2426 |
This variable holds an alist which maps property names to a list of |
This variable holds an alist which maps property names to a list of |
2427 |
alternative property names. If a character does not specify a direct |
alternative property names. If a character does not specify a direct |
2428 |
value for a property, the alternative property names are consulted in |
value for a property, the alternative property names are consulted in |
2429 |
order; the first non-nil value is used. This variable takes |
order; the first non-@code{nil} value is used. This variable takes |
2430 |
precedence over @code{default-text-properties}, and @code{category} |
precedence over @code{default-text-properties}, and @code{category} |
2431 |
properties take precedence over this variable. |
properties take precedence over this variable. |
2432 |
@end defvar |
@end defvar |
2524 |
list. |
list. |
2525 |
@end defun |
@end defun |
2526 |
|
|
2527 |
|
@defun remove-list-of-text-properties start end list-of-properties &optional object |
2528 |
|
Like @code{remove-list-properties} except that |
2529 |
|
@var{list-of-properties} is a list property names only, not an |
2530 |
|
alternating list of property values. |
2531 |
|
@end defun |
2532 |
|
|
2533 |
@defun set-text-properties start end props &optional object |
@defun set-text-properties start end props &optional object |
2534 |
This function completely replaces the text property list for the text |
This function completely replaces the text property list for the text |
2535 |
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}. |
2857 |
@cindex keymap of character |
@cindex keymap of character |
2858 |
@kindex keymap @r{(text property)} |
@kindex keymap @r{(text property)} |
2859 |
The @code{keymap} property specifies an additional keymap for |
The @code{keymap} property specifies an additional keymap for |
2860 |
commands. The property's value for the character after point, if |
commands. The property's value for the character before point applies |
2861 |
non-@code{nil}, is used for key lookup before the buffer's local map. |
if it is non-@code{nil} and rear-sticky, and the property's value for |
2862 |
(For mouse clicks, the @code{keymap} property of the character clicked |
the character after point applies if it is non-@code{nil} and |
2863 |
on is the one used.) If the property value is a symbol, the symbol's |
front-sticky. When the value applies, it is used for key lookup |
2864 |
function definition is used as the keymap. @xref{Active Keymaps}. |
before the buffer's local map. (For mouse clicks, the position of the |
2865 |
|
click is used instead of the position of point.) If the property |
2866 |
|
value is a symbol, the symbol's function definition is used as the |
2867 |
|
keymap. @xref{Active Keymaps}. |
2868 |
|
|
2869 |
@item local-map |
@item local-map |
2870 |
@kindex local-map @r{(text property)} |
@kindex local-map @r{(text property)} |
2871 |
This property specifies a keymap to use @emph{instead of} the buffer's |
This property works like @code{keymap} except that it specifies a |
2872 |
local map. If the property value is a symbol, the symbol's function |
keymap to use @emph{instead of} the buffer's local map. For most |
2873 |
definition is used as the keymap. For most purposes (perhaps all |
purposes (perhaps all purposes), the @code{keymap} is superior. |
|
purposes), the @code{keymap} is superior. |
|
2874 |
|
|
2875 |
@item syntax-table |
@item syntax-table |
2876 |
The @code{syntax-table} property overrides what the syntax table says |
The @code{syntax-table} property overrides what the syntax table says |
3408 |
|
|
3409 |
You can cause @code{constrain-to-field} to ignore all field boundaries |
You can cause @code{constrain-to-field} to ignore all field boundaries |
3410 |
(and so never constrain anything) by binding the variable |
(and so never constrain anything) by binding the variable |
3411 |
@code{inhibit-field-text-motion} to a non-nil value. |
@code{inhibit-field-text-motion} to a non-@code{nil} value. |
3412 |
@end defun |
@end defun |
3413 |
|
|
3414 |
@node Not Intervals |
@node Not Intervals |
3738 |
@defun base64-decode-string string |
@defun base64-decode-string string |
3739 |
@tindex base64-decode-string |
@tindex base64-decode-string |
3740 |
This function converts the string @var{string} from base 64 code into |
This function converts the string @var{string} from base 64 code into |
3741 |
the corresponding decoded text. It returns a string containing the |
the corresponding decoded text. It returns a unibyte string containing the |
3742 |
decoded text. |
decoded text. |
3743 |
|
|
3744 |
The decoding functions ignore newline characters in the encoded text. |
The decoding functions ignore newline characters in the encoded text. |
3792 |
coding instead. |
coding instead. |
3793 |
@end defun |
@end defun |
3794 |
|
|
3795 |
|
@node Atomic Changes |
3796 |
|
@section Atomic Change Groups |
3797 |
|
@cindex atomic changes |
3798 |
|
|
3799 |
|
In data base terminology, an @dfn{atomic} change is an indivisible |
3800 |
|
change---it can succeed entirely or it can fail entirely, but it |
3801 |
|
cannot partly succeed. A Lisp program can make a series of changes to |
3802 |
|
one or several buffers as an @dfn{atomic change group}, meaning that |
3803 |
|
either the entire series of changes will be installed in their buffers |
3804 |
|
or, in case of an error, none of them will be. |
3805 |
|
|
3806 |
|
To do this for one buffer, the one already current, simply write a |
3807 |
|
call to @code{atomic-change-group} around the code that makes the |
3808 |
|
changes, like this: |
3809 |
|
|
3810 |
|
@example |
3811 |
|
(atomic-change-group |
3812 |
|
(insert foo) |
3813 |
|
(delete-region x y)) |
3814 |
|
@end example |
3815 |
|
|
3816 |
|
@noindent |
3817 |
|
If an error (or other nonlocal exit) occurs inside the body of |
3818 |
|
@code{atomic-change-group}, it unmakes all the changes in that buffer |
3819 |
|
that were during the execution of the body. This kind of change group |
3820 |
|
has no effect on any other buffers--any such changes remain. |
3821 |
|
|
3822 |
|
If you need something more sophisticated, such as to make changes in |
3823 |
|
various buffers constitute one atomic group, you must directly call |
3824 |
|
lower-level functions that @code{atomic-change-group} uses. |
3825 |
|
|
3826 |
|
@defun prepare-change-group &optional buffer |
3827 |
|
This function sets up a change group for buffer @var{buffer}, which |
3828 |
|
defaults to the current buffer. It returns a ``handle'' that |
3829 |
|
represents the change group. You must use this handle to activate the |
3830 |
|
change group and subsequently to finish it. |
3831 |
|
@end defun |
3832 |
|
|
3833 |
|
To use the change group, you must @dfn{activate} it. You must do |
3834 |
|
this before making any changes in the text of @var{buffer}. |
3835 |
|
|
3836 |
|
@defun activate-change-group handle |
3837 |
|
This function activates the change group that @var{handle} designates. |
3838 |
|
@end defun |
3839 |
|
|
3840 |
|
After you activate the change group, any changes you make in that |
3841 |
|
buffer become part of it. Once you have made all the desired changes |
3842 |
|
in the buffer, you must @dfn{finish} the change group. There are two |
3843 |
|
ways to do this: you can either accept (and finalize) all the changes, |
3844 |
|
or cancel them all. |
3845 |
|
|
3846 |
|
@defun accept-change-group handle |
3847 |
|
This function accepts all the changes in the change group specified by |
3848 |
|
@var{handle}, making them final. |
3849 |
|
@end defun |
3850 |
|
|
3851 |
|
@defun cancel-change-group handle |
3852 |
|
This function cancels and undoes all the changes in the change group |
3853 |
|
specified by @var{handle}. |
3854 |
|
@end defun |
3855 |
|
|
3856 |
|
Your code should use @code{unwind-protect} to make sure the group is |
3857 |
|
always finished. The call to @code{activate-change-group} should be |
3858 |
|
inside the @code{unwind-protect}, in case the user types @kbd{C-g} |
3859 |
|
just after it runs. (This is one reason why |
3860 |
|
@code{prepare-change-group} and @code{activate-change-group} are |
3861 |
|
separate functions, because normally you would call |
3862 |
|
@code{prepare-change-group} before the start of that |
3863 |
|
@code{unwind-protect}.) Once you finish the group, don't use the |
3864 |
|
handle again---in particular, don't try to finish the same group |
3865 |
|
twice. |
3866 |
|
|
3867 |
|
To make a multibuffer change group, call @code{prepare-change-group} |
3868 |
|
once for each buffer you want to cover, then use @code{nconc} to |
3869 |
|
combine the returned values, like this: |
3870 |
|
|
3871 |
|
@example |
3872 |
|
(nconc (prepare-change-group buffer-1) |
3873 |
|
(prepare-change-group buffer-2)) |
3874 |
|
@end example |
3875 |
|
|
3876 |
|
You can then activate the multibuffer change group with a single call |
3877 |
|
to @code{activate-change-group}, and finish it with a single call to |
3878 |
|
@code{accept-change-group} or @code{cancel-change-group}. |
3879 |
|
|
3880 |
|
Nested use of several change groups for the same buffer works as you |
3881 |
|
would expect. Non-nested use of change groups for the same buffer |
3882 |
|
will get Emacs confused, so don't let it happen; the first change |
3883 |
|
group you start for any given buffer should be the last one finished. |
3884 |
|
|
3885 |
@node Change Hooks |
@node Change Hooks |
3886 |
@section Change Hooks |
@section Change Hooks |
3887 |
@cindex change hooks |
@cindex change hooks |
3917 |
arguments. |
arguments. |
3918 |
@end defvar |
@end defvar |
3919 |
|
|
3920 |
|
Output of messges into the @samp{*Messages*} buffer does not |
3921 |
|
call these functions. |
3922 |
|
|
3923 |
@defmac combine-after-change-calls body... |
@defmac combine-after-change-calls body... |
3924 |
The macro executes @var{body} normally, but arranges to call the |
The macro executes @var{body} normally, but arranges to call the |
3925 |
after-change functions just once for a series of several changes---if |
after-change functions just once for a series of several changes---if |
3936 |
@code{after-change-functions} within |
@code{after-change-functions} within |
3937 |
the body of a @code{combine-after-change-calls} form. |
the body of a @code{combine-after-change-calls} form. |
3938 |
|
|
3939 |
@strong{Note:} If the changes you combine occur in widely scattered |
@strong{Warning:} if the changes you combine occur in widely scattered |
3940 |
parts of the buffer, this will still work, but it is not advisable, |
parts of the buffer, this will still work, but it is not advisable, |
3941 |
because it may lead to inefficient behavior for some change hook |
because it may lead to inefficient behavior for some change hook |
3942 |
functions. |
functions. |
3986 |
|
|
3987 |
This variable is available starting in Emacs 21. |
This variable is available starting in Emacs 21. |
3988 |
@end defvar |
@end defvar |
3989 |
|
|
3990 |
|
@ignore |
3991 |
|
arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b |
3992 |
|
@end ignore |