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