Mercurial > emacs
annotate lispref/abbrevs.texi @ 27114:4efa5e54e9a9
(Qunspecified_fg, Qunspecified_bg): Remove.
(syms_of_xfaces): Remove their staticpro's.
(tty_color_name): Return Lisp strings for unspecified fore- and
back-ground colors.
(Finternal_set_lisp_face_attribute): Remove the special treatment
for Qunspecified_{f,b}g.
(realize_default_face): Replace Qunspecified_{f,b}g with a Lisp
string.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Mon, 03 Jan 2000 16:52:52 +0000 |
parents | 01d4feb7e1e4 |
children | d2e5f1b7d8e2 |
rev | line source |
---|---|
6552 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. | |
4 @c See the file elisp.texi for copying conditions. | |
5 @setfilename ../info/abbrevs | |
6 @node Abbrevs, Processes, Syntax Tables, Top | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
7 @chapter Abbrevs and Abbrev Expansion |
6552 | 8 @cindex abbrev |
9 @cindex abbrev table | |
10 | |
11 An abbreviation or @dfn{abbrev} is a string of characters that may be | |
12 expanded to a longer string. The user can insert the abbrev string and | |
13 find it replaced automatically with the expansion of the abbrev. This | |
14 saves typing. | |
15 | |
16 The set of abbrevs currently in effect is recorded in an @dfn{abbrev | |
17 table}. Each buffer has a local abbrev table, but normally all buffers | |
18 in the same major mode share one abbrev table. There is also a global | |
19 abbrev table. Normally both are used. | |
20 | |
21 An abbrev table is represented as an obarray containing a symbol for | |
7688 | 22 each abbreviation. The symbol's name is the abbreviation; its value is |
6552 | 23 the expansion; its function definition is the hook function to do the |
7688 | 24 expansion (@pxref{Defining Abbrevs}); its property list cell contains |
25 the use count, the number of times the abbreviation has been expanded. | |
26 Because these symbols are not interned in the usual obarray, they will | |
27 never appear as the result of reading a Lisp expression; in fact, | |
28 normally they are never used except by the code that handles abbrevs. | |
29 Therefore, it is safe to use them in an extremely nonstandard way. | |
30 @xref{Creating Symbols}. | |
6552 | 31 |
32 For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev | |
33 Mode, emacs, The GNU Emacs Manual}. | |
34 | |
35 @menu | |
36 * Abbrev Mode:: Setting up Emacs for abbreviation. | |
37 * Tables: Abbrev Tables. Creating and working with abbrev tables. | |
38 * Defining Abbrevs:: Specifying abbreviations and their expansions. | |
39 * Files: Abbrev Files. Saving abbrevs in files. | |
40 * Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. | |
41 * Standard Abbrev Tables:: Abbrev tables used by various major modes. | |
42 @end menu | |
43 | |
44 @node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs | |
45 @comment node-name, next, previous, up | |
46 @section Setting Up Abbrev Mode | |
47 | |
48 Abbrev mode is a minor mode controlled by the value of the variable | |
49 @code{abbrev-mode}. | |
50 | |
51 @defvar abbrev-mode | |
52 A non-@code{nil} value of this variable turns on the automatic expansion | |
53 of abbrevs when their abbreviations are inserted into a buffer. | |
54 If the value is @code{nil}, abbrevs may be defined, but they are not | |
55 expanded automatically. | |
56 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
57 This variable automatically becomes buffer-local when set in any fashion. |
6552 | 58 @end defvar |
59 | |
60 @defvar default-abbrev-mode | |
7688 | 61 This is the value of @code{abbrev-mode} for buffers that do not override it. |
6552 | 62 This is the same as @code{(default-value 'abbrev-mode)}. |
63 @end defvar | |
64 | |
65 @node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs | |
66 @section Abbrev Tables | |
67 | |
68 This section describes how to create and manipulate abbrev tables. | |
69 | |
70 @defun make-abbrev-table | |
71 This function creates and returns a new, empty abbrev table---an obarray | |
72 containing no symbols. It is a vector filled with zeros. | |
73 @end defun | |
74 | |
75 @defun clear-abbrev-table table | |
76 This function undefines all the abbrevs in abbrev table @var{table}, | |
26192 | 77 leaving it empty. The function returns @code{nil}. |
6552 | 78 @end defun |
79 | |
80 @defun define-abbrev-table tabname definitions | |
81 This function defines @var{tabname} (a symbol) as an abbrev table name, | |
82 i.e., as a variable whose value is an abbrev table. It defines abbrevs | |
83 in the table according to @var{definitions}, a list of elements of the | |
84 form @code{(@var{abbrevname} @var{expansion} @var{hook} | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
85 @var{usecount})}. The return value is always @code{nil}. |
6552 | 86 @end defun |
87 | |
88 @defvar abbrev-table-name-list | |
89 This is a list of symbols whose values are abbrev tables. | |
90 @code{define-abbrev-table} adds the new abbrev table name to this list. | |
91 @end defvar | |
92 | |
93 @defun insert-abbrev-table-description name &optional human | |
94 This function inserts before point a description of the abbrev table | |
95 named @var{name}. The argument @var{name} is a symbol whose value is an | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
96 abbrev table. The return value is always @code{nil}. |
6552 | 97 |
98 If @var{human} is non-@code{nil}, the description is human-oriented. | |
99 Otherwise the description is a Lisp expression---a call to | |
7688 | 100 @code{define-abbrev-table} that would define @var{name} exactly as it |
6552 | 101 is currently defined. |
102 @end defun | |
103 | |
104 @node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs | |
105 @comment node-name, next, previous, up | |
106 @section Defining Abbrevs | |
107 | |
108 These functions define an abbrev in a specified abbrev table. | |
109 @code{define-abbrev} is the low-level basic function, while | |
110 @code{add-abbrev} is used by commands that ask for information from the | |
111 user. | |
112 | |
113 @defun add-abbrev table type arg | |
7688 | 114 This function adds an abbreviation to abbrev table @var{table} based on |
115 information from the user. The argument @var{type} is a string | |
116 describing in English the kind of abbrev this will be (typically, | |
117 @code{"global"} or @code{"mode-specific"}); this is used in prompting | |
118 the user. The argument @var{arg} is the number of words in the | |
119 expansion. | |
6552 | 120 |
26192 | 121 |
7688 | 122 The return value is the symbol that internally represents the new |
6552 | 123 abbrev, or @code{nil} if the user declines to confirm redefining an |
124 existing abbrev. | |
125 @end defun | |
126 | |
26192 | 127 @defun define-abbrev table name expansion &optional hook count |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
128 This function defines an abbrev named @var{name}, in @var{table}, to |
26192 | 129 expand to @var{expansion} and call @var{hook}. The value of |
130 @var{count}, if specified, initializes the abbrev's usage-count. If | |
131 @var{count} is not specified or @code{nil}, the use count is initialized | |
132 to zero. The return value is a symbol that represents the abbrev inside | |
133 Emacs; its name is @var{name}. | |
6552 | 134 |
135 The argument @var{name} should be a string. The argument | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
136 @var{expansion} is normally the desired expansion (a string), or |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
137 @code{nil} to undefine the abbrev. If it is anything but a string or |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
138 @code{nil}, then the abbreviation ``expands'' solely by running |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
139 @var{hook}. |
6552 | 140 |
26192 | 141 |
6552 | 142 The argument @var{hook} is a function or @code{nil}. If @var{hook} is |
143 non-@code{nil}, then it is called with no arguments after the abbrev is | |
144 replaced with @var{expansion}; point is located at the end of | |
7688 | 145 @var{expansion} when @var{hook} is called. |
6552 | 146 @end defun |
147 | |
148 @defopt only-global-abbrevs | |
149 If this variable is non-@code{nil}, it means that the user plans to use | |
150 global abbrevs only. This tells the commands that define mode-specific | |
151 abbrevs to define global ones instead. This variable does not alter the | |
7688 | 152 behavior of the functions in this section; it is examined by their |
6552 | 153 callers. |
154 @end defopt | |
155 | |
156 @node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs | |
157 @section Saving Abbrevs in Files | |
158 | |
159 A file of saved abbrev definitions is actually a file of Lisp code. | |
160 The abbrevs are saved in the form of a Lisp program to define the same | |
161 abbrev tables with the same contents. Therefore, you can load the file | |
162 with @code{load} (@pxref{How Programs Do Loading}). However, the | |
163 function @code{quietly-read-abbrev-file} is provided as a more | |
164 convenient interface. | |
165 | |
166 User-level facilities such as @code{save-some-buffers} can save | |
167 abbrevs in a file automatically, under the control of variables | |
168 described here. | |
169 | |
170 @defopt abbrev-file-name | |
171 This is the default file name for reading and saving abbrevs. | |
172 @end defopt | |
173 | |
26192 | 174 @defun quietly-read-abbrev-file &optional filename |
6552 | 175 This function reads abbrev definitions from a file named @var{filename}, |
176 previously written with @code{write-abbrev-file}. If @var{filename} is | |
26192 | 177 omitted or @code{nil}, the file specified in @code{abbrev-file-name} is |
178 used. @code{save-abbrevs} is set to @code{t} so that changes will be | |
179 saved. | |
6552 | 180 |
181 This function does not display any messages. It returns @code{nil}. | |
182 @end defun | |
183 | |
184 @defopt save-abbrevs | |
185 A non-@code{nil} value for @code{save-abbrev} means that Emacs should | |
186 save abbrevs when files are saved. @code{abbrev-file-name} specifies | |
187 the file to save the abbrevs in. | |
188 @end defopt | |
189 | |
190 @defvar abbrevs-changed | |
191 This variable is set non-@code{nil} by defining or altering any | |
192 abbrevs. This serves as a flag for various Emacs commands to offer to | |
193 save your abbrevs. | |
194 @end defvar | |
195 | |
26192 | 196 @deffn Command write-abbrev-file &optional filename |
6552 | 197 Save all abbrev definitions, in all abbrev tables, in the file |
7688 | 198 @var{filename}, in the form of a Lisp program that when loaded will |
26192 | 199 define the same abbrevs. If @var{filename} is @code{nil} or omitted, |
200 @code{abbrev-file-name} is used. This function returns @code{nil}. | |
6552 | 201 @end deffn |
202 | |
203 @node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs | |
204 @comment node-name, next, previous, up | |
205 @section Looking Up and Expanding Abbreviations | |
206 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
207 Abbrevs are usually expanded by certain interactive commands, |
6552 | 208 including @code{self-insert-command}. This section describes the |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
209 subroutines used in writing such commands, as well as the variables they |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
210 use for communication. |
6552 | 211 |
212 @defun abbrev-symbol abbrev &optional table | |
213 This function returns the symbol representing the abbrev named | |
214 @var{abbrev}. The value returned is @code{nil} if that abbrev is not | |
215 defined. The optional second argument @var{table} is the abbrev table | |
216 to look it up in. If @var{table} is @code{nil}, this function tries | |
217 first the current buffer's local abbrev table, and second the global | |
218 abbrev table. | |
219 @end defun | |
220 | |
7688 | 221 @defun abbrev-expansion abbrev &optional table |
222 This function returns the string that @var{abbrev} would expand into (as | |
223 defined by the abbrev tables used for the current buffer). The optional | |
224 argument @var{table} specifies the abbrev table to use, as in | |
225 @code{abbrev-symbol}. | |
226 @end defun | |
227 | |
228 @deffn Command expand-abbrev | |
26192 | 229 This command expands the abbrev before point, if any. If point does not |
230 follow an abbrev, this command does nothing. The command returns the | |
231 abbrev symbol if it did expansion, @code{nil} otherwise. | |
7688 | 232 @end deffn |
233 | |
26192 | 234 |
7688 | 235 @deffn Command abbrev-prefix-mark &optional arg |
236 Mark current point as the beginning of an abbrev. The next call to | |
237 @code{expand-abbrev} will use the text from here to point (where it is | |
238 then) as the abbrev to expand, rather than using the previous word as | |
239 usual. | |
240 @end deffn | |
241 | |
6552 | 242 @defopt abbrev-all-caps |
243 When this is set non-@code{nil}, an abbrev entered entirely in upper | |
244 case is expanded using all upper case. Otherwise, an abbrev entered | |
245 entirely in upper case is expanded by capitalizing each word of the | |
246 expansion. | |
247 @end defopt | |
248 | |
249 @defvar abbrev-start-location | |
250 This is the buffer position for @code{expand-abbrev} to use as the start | |
251 of the next abbrev to be expanded. (@code{nil} means use the word | |
252 before point instead.) @code{abbrev-start-location} is set to | |
253 @code{nil} each time @code{expand-abbrev} is called. This variable is | |
254 also set by @code{abbrev-prefix-mark}. | |
255 @end defvar | |
256 | |
257 @defvar abbrev-start-location-buffer | |
258 The value of this variable is the buffer for which | |
259 @code{abbrev-start-location} has been set. Trying to expand an abbrev | |
260 in any other buffer clears @code{abbrev-start-location}. This variable | |
261 is set by @code{abbrev-prefix-mark}. | |
262 @end defvar | |
263 | |
264 @defvar last-abbrev | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
265 This is the @code{abbrev-symbol} of the most recent abbrev expanded. This |
6552 | 266 information is left by @code{expand-abbrev} for the sake of the |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
267 @code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
268 Abbrevs, emacs, The GNU Emacs Manual}). |
6552 | 269 @end defvar |
270 | |
271 @defvar last-abbrev-location | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
272 This is the location of the most recent abbrev expanded. This contains |
6552 | 273 information left by @code{expand-abbrev} for the sake of the |
274 @code{unexpand-abbrev} command. | |
275 @end defvar | |
276 | |
277 @defvar last-abbrev-text | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
278 This is the exact expansion text of the most recent abbrev expanded, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
279 after case conversion (if any). Its value is @code{nil} if the abbrev |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
280 has already been unexpanded. This contains information left by |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7688
diff
changeset
|
281 @code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command. |
6552 | 282 @end defvar |
283 | |
284 @c Emacs 19 feature | |
285 @defvar pre-abbrev-expand-hook | |
286 This is a normal hook whose functions are executed, in sequence, just | |
287 before any expansion of an abbrev. @xref{Hooks}. Since it is a normal | |
288 hook, the hook functions receive no arguments. However, they can find | |
289 the abbrev to be expanded by looking in the buffer before point. | |
26192 | 290 Running the hook is the first thing that @code{expand-abbrev} does, and |
291 so a hook function can be used to change the current abbrev table before | |
292 abbrev lookup happens. | |
6552 | 293 @end defvar |
294 | |
295 The following sample code shows a simple use of | |
296 @code{pre-abbrev-expand-hook}. If the user terminates an abbrev with a | |
297 punctuation character, the hook function asks for confirmation. Thus, | |
298 this hook allows the user to decide whether to expand the abbrev, and | |
299 aborts expansion if it is not confirmed. | |
300 | |
301 @smallexample | |
302 (add-hook 'pre-abbrev-expand-hook 'query-if-not-space) | |
303 | |
304 ;; @r{This is the function invoked by @code{pre-abbrev-expand-hook}.} | |
305 | |
306 ;; @r{If the user terminated the abbrev with a space, the function does} | |
307 ;; @r{nothing (that is, it returns so that the abbrev can expand). If the} | |
308 ;; @r{user entered some other character, this function asks whether} | |
309 ;; @r{expansion should continue.} | |
310 | |
7688 | 311 ;; @r{If the user answers the prompt with @kbd{y}, the function returns} |
6552 | 312 ;; @r{@code{nil} (because of the @code{not} function), but that is} |
313 ;; @r{acceptable; the return value has no effect on expansion.} | |
314 | |
315 (defun query-if-not-space () | |
316 (if (/= ?\ (preceding-char)) | |
317 (if (not (y-or-n-p "Do you want to expand this abbrev? ")) | |
318 (error "Not expanding this abbrev")))) | |
319 @end smallexample | |
320 | |
321 @node Standard Abbrev Tables, , Abbrev Expansion, Abbrevs | |
322 @comment node-name, next, previous, up | |
323 @section Standard Abbrev Tables | |
324 | |
325 Here we list the variables that hold the abbrev tables for the | |
326 preloaded major modes of Emacs. | |
327 | |
328 @defvar global-abbrev-table | |
329 This is the abbrev table for mode-independent abbrevs. The abbrevs | |
330 defined in it apply to all buffers. Each buffer may also have a local | |
331 abbrev table, whose abbrev definitions take precedence over those in the | |
332 global table. | |
333 @end defvar | |
334 | |
335 @defvar local-abbrev-table | |
336 The value of this buffer-local variable is the (mode-specific) | |
337 abbreviation table of the current buffer. | |
338 @end defvar | |
339 | |
340 @defvar fundamental-mode-abbrev-table | |
7688 | 341 This is the local abbrev table used in Fundamental mode; in other words, |
342 it is the local abbrev table in all buffers in Fundamental mode. | |
6552 | 343 @end defvar |
344 | |
345 @defvar text-mode-abbrev-table | |
346 This is the local abbrev table used in Text mode. | |
347 @end defvar | |
348 | |
349 @defvar lisp-mode-abbrev-table | |
350 This is the local abbrev table used in Lisp mode and Emacs Lisp mode. | |
351 @end defvar | |
26192 | 352 |