Mercurial > emacs
annotate doc/lispref/abbrevs.texi @ 85265:4fe6aac1d449
(ebrowse-tree-mode): Disable undo in the BROWSE buffer.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Sat, 13 Oct 2007 12:55:00 +0000 |
parents | 0ba80d073e27 |
children | beb909dfc54d |
rev | line source |
---|---|
84046 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999, 2001, 2002, 2003, | |
4 @c 2004, 2005, 2006, 2007 Free Software Foundation, Inc. | |
5 @c See the file elisp.texi for copying conditions. | |
84116
0ba80d073e27
(setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents:
84046
diff
changeset
|
6 @setfilename ../../info/abbrevs |
84046 | 7 @node Abbrevs, Processes, Syntax Tables, Top |
8 @chapter Abbrevs and Abbrev Expansion | |
9 @cindex abbrev | |
10 @c @cindex abbrev table Redundant with "abbrev". | |
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 | |
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. Abbrevs with a non-@code{nil} | |
30 @code{system-type} property are called ``system'' abbrevs. They are | |
31 usually defined by modes or packages, instead of by the user, and are | |
32 treated specially in certain respects. | |
33 | |
34 Because the symbols used for abbrevs are not interned in the usual | |
35 obarray, they will never appear as the result of reading a Lisp | |
36 expression; in fact, normally they are never used except by the code | |
37 that handles abbrevs. Therefore, it is safe to use them in an | |
38 extremely nonstandard way. @xref{Creating Symbols}. | |
39 | |
40 For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev | |
41 Mode, emacs, The GNU Emacs Manual}. | |
42 | |
43 @menu | |
44 * Abbrev Mode:: Setting up Emacs for abbreviation. | |
45 * Tables: Abbrev Tables. Creating and working with abbrev tables. | |
46 * Defining Abbrevs:: Specifying abbreviations and their expansions. | |
47 * Files: Abbrev Files. Saving abbrevs in files. | |
48 * Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. | |
49 * Standard Abbrev Tables:: Abbrev tables used by various major modes. | |
50 @end menu | |
51 | |
52 @node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs | |
53 @comment node-name, next, previous, up | |
54 @section Setting Up Abbrev Mode | |
55 | |
56 Abbrev mode is a minor mode controlled by the value of the variable | |
57 @code{abbrev-mode}. | |
58 | |
59 @defvar abbrev-mode | |
60 A non-@code{nil} value of this variable turns on the automatic expansion | |
61 of abbrevs when their abbreviations are inserted into a buffer. | |
62 If the value is @code{nil}, abbrevs may be defined, but they are not | |
63 expanded automatically. | |
64 | |
65 This variable automatically becomes buffer-local when set in any fashion. | |
66 @end defvar | |
67 | |
68 @defvar default-abbrev-mode | |
69 This is the value of @code{abbrev-mode} for buffers that do not override it. | |
70 This is the same as @code{(default-value 'abbrev-mode)}. | |
71 @end defvar | |
72 | |
73 @node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs | |
74 @section Abbrev Tables | |
75 | |
76 This section describes how to create and manipulate abbrev tables. | |
77 | |
78 @defun make-abbrev-table | |
79 This function creates and returns a new, empty abbrev table---an obarray | |
80 containing no symbols. It is a vector filled with zeros. | |
81 @end defun | |
82 | |
83 @defun clear-abbrev-table table | |
84 This function undefines all the abbrevs in abbrev table @var{table}, | |
85 leaving it empty. It always returns @code{nil}. | |
86 @end defun | |
87 | |
88 @defun copy-abbrev-table table | |
89 This function returns a copy of abbrev table @var{table}---a new | |
90 abbrev table that contains the same abbrev definitions. The only | |
91 difference between @var{table} and the returned copy is that this | |
92 function sets the property lists of all copied abbrevs to 0. | |
93 @end defun | |
94 | |
95 @defun define-abbrev-table tabname definitions | |
96 This function defines @var{tabname} (a symbol) as an abbrev table | |
97 name, i.e., as a variable whose value is an abbrev table. It defines | |
98 abbrevs in the table according to @var{definitions}, a list of | |
99 elements of the form @code{(@var{abbrevname} @var{expansion} | |
100 @var{hook} @var{usecount} @var{system-flag})}. If an element of | |
101 @var{definitions} has length less than five, omitted elements default | |
102 to @code{nil}. A value of @code{nil} for @var{usecount} is equivalent | |
103 to zero. The return value is always @code{nil}. | |
104 | |
105 If this function is called more than once for the same @var{tabname}, | |
106 subsequent calls add the definitions in @var{definitions} to | |
107 @var{tabname}, rather than overriding the entire original contents. | |
108 (A subsequent call only overrides abbrevs explicitly redefined or | |
109 undefined in @var{definitions}.) | |
110 @end defun | |
111 | |
112 @defvar abbrev-table-name-list | |
113 This is a list of symbols whose values are abbrev tables. | |
114 @code{define-abbrev-table} adds the new abbrev table name to this list. | |
115 @end defvar | |
116 | |
117 @defun insert-abbrev-table-description name &optional human | |
118 This function inserts before point a description of the abbrev table | |
119 named @var{name}. The argument @var{name} is a symbol whose value is an | |
120 abbrev table. The return value is always @code{nil}. | |
121 | |
122 If @var{human} is non-@code{nil}, the description is human-oriented. | |
123 System abbrevs are listed and identified as such. Otherwise the | |
124 description is a Lisp expression---a call to @code{define-abbrev-table} | |
125 that would define @var{name} as it is currently defined, but without | |
126 the system abbrevs. (The mode or package using @var{name} is supposed | |
127 to add these to @var{name} separately.) | |
128 @end defun | |
129 | |
130 @node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs | |
131 @comment node-name, next, previous, up | |
132 @section Defining Abbrevs | |
133 @code{define-abbrev} is the low-level basic function for defining an | |
134 abbrev in a specified abbrev table. When major modes predefine standard | |
135 abbrevs, they should call @code{define-abbrev} and specify @code{t} for | |
136 @var{system-flag}. Be aware that any saved non-``system'' abbrevs are | |
137 restored at startup, i.e. before some major modes are loaded. Major modes | |
138 should therefore not assume that when they are first loaded their abbrev | |
139 tables are empty. | |
140 | |
141 @defun define-abbrev table name expansion &optional hook count system-flag | |
142 This function defines an abbrev named @var{name}, in @var{table}, to | |
143 expand to @var{expansion} and call @var{hook}. The return value is | |
144 @var{name}. | |
145 | |
146 The value of @var{count}, if specified, initializes the abbrev's | |
147 usage-count. If @var{count} is not specified or @code{nil}, the use | |
148 count is initialized to zero. | |
149 | |
150 The argument @var{name} should be a string. The argument | |
151 @var{expansion} is normally the desired expansion (a string), or | |
152 @code{nil} to undefine the abbrev. If it is anything but a string or | |
153 @code{nil}, then the abbreviation ``expands'' solely by running | |
154 @var{hook}. | |
155 | |
156 The argument @var{hook} is a function or @code{nil}. If @var{hook} is | |
157 non-@code{nil}, then it is called with no arguments after the abbrev is | |
158 replaced with @var{expansion}; point is located at the end of | |
159 @var{expansion} when @var{hook} is called. | |
160 | |
161 @cindex @code{no-self-insert} property | |
162 If @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert} | |
163 property is non-@code{nil}, @var{hook} can explicitly control whether | |
164 to insert the self-inserting input character that triggered the | |
165 expansion. If @var{hook} returns non-@code{nil} in this case, that | |
166 inhibits insertion of the character. By contrast, if @var{hook} | |
167 returns @code{nil}, @code{expand-abbrev} also returns @code{nil}, as | |
168 if expansion had not really occurred. | |
169 | |
170 If @var{system-flag} is non-@code{nil}, that marks the abbrev as a | |
171 ``system'' abbrev with the @code{system-type} property. Unless | |
172 @var{system-flag} has the value @code{force}, a ``system'' abbrev will | |
173 not overwrite an existing definition for a non-``system'' abbrev of the | |
174 same name. | |
175 | |
176 Normally the function @code{define-abbrev} sets the variable | |
177 @code{abbrevs-changed} to @code{t}, if it actually changes the abbrev. | |
178 (This is so that some commands will offer to save the abbrevs.) It | |
179 does not do this for a ``system'' abbrev, since those won't be saved | |
180 anyway. | |
181 @end defun | |
182 | |
183 @defopt only-global-abbrevs | |
184 If this variable is non-@code{nil}, it means that the user plans to use | |
185 global abbrevs only. This tells the commands that define mode-specific | |
186 abbrevs to define global ones instead. This variable does not alter the | |
187 behavior of the functions in this section; it is examined by their | |
188 callers. | |
189 @end defopt | |
190 | |
191 @node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs | |
192 @section Saving Abbrevs in Files | |
193 | |
194 A file of saved abbrev definitions is actually a file of Lisp code. | |
195 The abbrevs are saved in the form of a Lisp program to define the same | |
196 abbrev tables with the same contents. Therefore, you can load the file | |
197 with @code{load} (@pxref{How Programs Do Loading}). However, the | |
198 function @code{quietly-read-abbrev-file} is provided as a more | |
199 convenient interface. | |
200 | |
201 User-level facilities such as @code{save-some-buffers} can save | |
202 abbrevs in a file automatically, under the control of variables | |
203 described here. | |
204 | |
205 @defopt abbrev-file-name | |
206 This is the default file name for reading and saving abbrevs. | |
207 @end defopt | |
208 | |
209 @defun quietly-read-abbrev-file &optional filename | |
210 This function reads abbrev definitions from a file named @var{filename}, | |
211 previously written with @code{write-abbrev-file}. If @var{filename} is | |
212 omitted or @code{nil}, the file specified in @code{abbrev-file-name} is | |
213 used. @code{save-abbrevs} is set to @code{t} so that changes will be | |
214 saved. | |
215 | |
216 This function does not display any messages. It returns @code{nil}. | |
217 @end defun | |
218 | |
219 @defopt save-abbrevs | |
220 A non-@code{nil} value for @code{save-abbrevs} means that Emacs should | |
221 offer the user to save abbrevs when files are saved. If the value is | |
222 @code{silently}, Emacs saves the abbrevs without asking the user. | |
223 @code{abbrev-file-name} specifies the file to save the abbrevs in. | |
224 @end defopt | |
225 | |
226 @defvar abbrevs-changed | |
227 This variable is set non-@code{nil} by defining or altering any | |
228 abbrevs (except ``system'' abbrevs). This serves as a flag for | |
229 various Emacs commands to offer to save your abbrevs. | |
230 @end defvar | |
231 | |
232 @deffn Command write-abbrev-file &optional filename | |
233 Save all abbrev definitions (except ``system'' abbrevs), for all abbrev | |
234 tables listed in @code{abbrev-table-name-list}, in the file | |
235 @var{filename}, in the form of a Lisp program that when loaded will | |
236 define the same abbrevs. If @var{filename} is @code{nil} or omitted, | |
237 @code{abbrev-file-name} is used. This function returns @code{nil}. | |
238 @end deffn | |
239 | |
240 @node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs | |
241 @comment node-name, next, previous, up | |
242 @section Looking Up and Expanding Abbreviations | |
243 | |
244 Abbrevs are usually expanded by certain interactive commands, | |
245 including @code{self-insert-command}. This section describes the | |
246 subroutines used in writing such commands, as well as the variables they | |
247 use for communication. | |
248 | |
249 @defun abbrev-symbol abbrev &optional table | |
250 This function returns the symbol representing the abbrev named | |
251 @var{abbrev}. The value returned is @code{nil} if that abbrev is not | |
252 defined. The optional second argument @var{table} is the abbrev table | |
253 to look it up in. If @var{table} is @code{nil}, this function tries | |
254 first the current buffer's local abbrev table, and second the global | |
255 abbrev table. | |
256 @end defun | |
257 | |
258 @defun abbrev-expansion abbrev &optional table | |
259 This function returns the string that @var{abbrev} would expand into (as | |
260 defined by the abbrev tables used for the current buffer). If | |
261 @var{abbrev} is not a valid abbrev, the function returns @code{nil}. | |
262 The optional argument @var{table} specifies the abbrev table to use, | |
263 as in @code{abbrev-symbol}. | |
264 @end defun | |
265 | |
266 @deffn Command expand-abbrev | |
267 This command expands the abbrev before point, if any. If point does not | |
268 follow an abbrev, this command does nothing. The command returns the | |
269 abbrev symbol if it did expansion, @code{nil} otherwise. | |
270 | |
271 If the abbrev symbol has a hook function which is a symbol whose | |
272 @code{no-self-insert} property is non-@code{nil}, and if the hook | |
273 function returns @code{nil} as its value, then @code{expand-abbrev} | |
274 returns @code{nil} even though expansion did occur. | |
275 @end deffn | |
276 | |
277 @deffn Command abbrev-prefix-mark &optional arg | |
278 This command marks the current location of point as the beginning of | |
279 an abbrev. The next call to @code{expand-abbrev} will use the text | |
280 from here to point (where it is then) as the abbrev to expand, rather | |
281 than using the previous word as usual. | |
282 | |
283 First, this command expands any abbrev before point, unless @var{arg} | |
284 is non-@code{nil}. (Interactively, @var{arg} is the prefix argument.) | |
285 Then it inserts a hyphen before point, to indicate the start of the | |
286 next abbrev to be expanded. The actual expansion removes the hyphen. | |
287 @end deffn | |
288 | |
289 @defopt abbrev-all-caps | |
290 When this is set non-@code{nil}, an abbrev entered entirely in upper | |
291 case is expanded using all upper case. Otherwise, an abbrev entered | |
292 entirely in upper case is expanded by capitalizing each word of the | |
293 expansion. | |
294 @end defopt | |
295 | |
296 @defvar abbrev-start-location | |
297 The value of this variable is a buffer position (an integer or a marker) | |
298 for @code{expand-abbrev} to use as the start of the next abbrev to be | |
299 expanded. The value can also be @code{nil}, which means to use the | |
300 word before point instead. @code{abbrev-start-location} is set to | |
301 @code{nil} each time @code{expand-abbrev} is called. This variable is | |
302 also set by @code{abbrev-prefix-mark}. | |
303 @end defvar | |
304 | |
305 @defvar abbrev-start-location-buffer | |
306 The value of this variable is the buffer for which | |
307 @code{abbrev-start-location} has been set. Trying to expand an abbrev | |
308 in any other buffer clears @code{abbrev-start-location}. This variable | |
309 is set by @code{abbrev-prefix-mark}. | |
310 @end defvar | |
311 | |
312 @defvar last-abbrev | |
313 This is the @code{abbrev-symbol} of the most recent abbrev expanded. This | |
314 information is left by @code{expand-abbrev} for the sake of the | |
315 @code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding | |
316 Abbrevs, emacs, The GNU Emacs Manual}). | |
317 @end defvar | |
318 | |
319 @defvar last-abbrev-location | |
320 This is the location of the most recent abbrev expanded. This contains | |
321 information left by @code{expand-abbrev} for the sake of the | |
322 @code{unexpand-abbrev} command. | |
323 @end defvar | |
324 | |
325 @defvar last-abbrev-text | |
326 This is the exact expansion text of the most recent abbrev expanded, | |
327 after case conversion (if any). Its value is @code{nil} if the abbrev | |
328 has already been unexpanded. This contains information left by | |
329 @code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command. | |
330 @end defvar | |
331 | |
332 @c Emacs 19 feature | |
333 @defvar pre-abbrev-expand-hook | |
334 This is a normal hook whose functions are executed, in sequence, just | |
335 before any expansion of an abbrev. @xref{Hooks}. Since it is a normal | |
336 hook, the hook functions receive no arguments. However, they can find | |
337 the abbrev to be expanded by looking in the buffer before point. | |
338 Running the hook is the first thing that @code{expand-abbrev} does, and | |
339 so a hook function can be used to change the current abbrev table before | |
340 abbrev lookup happens. (Although you have to do this carefully. See | |
341 the example below.) | |
342 @end defvar | |
343 | |
344 The following sample code shows a simple use of | |
345 @code{pre-abbrev-expand-hook}. It assumes that @code{foo-mode} is a | |
346 mode for editing certain files in which lines that start with @samp{#} | |
347 are comments. You want to use Text mode abbrevs for those lines. The | |
348 regular local abbrev table, @code{foo-mode-abbrev-table} is | |
349 appropriate for all other lines. Then you can put the following code | |
350 in your @file{.emacs} file. @xref{Standard Abbrev Tables}, for the | |
351 definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}. | |
352 | |
353 @smallexample | |
354 (defun foo-mode-pre-abbrev-expand () | |
355 (when (save-excursion (forward-line 0) (eq (char-after) ?#)) | |
356 (let ((local-abbrev-table text-mode-abbrev-table) | |
357 ;; Avoid infinite loop. | |
358 (pre-abbrev-expand-hook nil)) | |
359 (expand-abbrev)) | |
360 ;; We have already called `expand-abbrev' in this hook. | |
361 ;; Hence we want the "actual" call following this hook to be a no-op. | |
362 (setq abbrev-start-location (point-max) | |
363 abbrev-start-location-buffer (current-buffer)))) | |
364 | |
365 (add-hook 'foo-mode-hook | |
366 #'(lambda () | |
367 (add-hook 'pre-abbrev-expand-hook | |
368 'foo-mode-pre-abbrev-expand | |
369 nil t))) | |
370 @end smallexample | |
371 | |
372 Note that @code{foo-mode-pre-abbrev-expand} just returns @code{nil} | |
373 without doing anything for lines not starting with @samp{#}. Hence | |
374 abbrevs expand normally using @code{foo-mode-abbrev-table} as local | |
375 abbrev table for such lines. | |
376 | |
377 @node Standard Abbrev Tables, , Abbrev Expansion, Abbrevs | |
378 @comment node-name, next, previous, up | |
379 @section Standard Abbrev Tables | |
380 | |
381 Here we list the variables that hold the abbrev tables for the | |
382 preloaded major modes of Emacs. | |
383 | |
384 @defvar global-abbrev-table | |
385 This is the abbrev table for mode-independent abbrevs. The abbrevs | |
386 defined in it apply to all buffers. Each buffer may also have a local | |
387 abbrev table, whose abbrev definitions take precedence over those in the | |
388 global table. | |
389 @end defvar | |
390 | |
391 @defvar local-abbrev-table | |
392 The value of this buffer-local variable is the (mode-specific) | |
393 abbreviation table of the current buffer. | |
394 @end defvar | |
395 | |
396 @defvar fundamental-mode-abbrev-table | |
397 This is the local abbrev table used in Fundamental mode; in other words, | |
398 it is the local abbrev table in all buffers in Fundamental mode. | |
399 @end defvar | |
400 | |
401 @defvar text-mode-abbrev-table | |
402 This is the local abbrev table used in Text mode. | |
403 @end defvar | |
404 | |
405 @defvar lisp-mode-abbrev-table | |
406 This is the local abbrev table used in Lisp mode and Emacs Lisp mode. | |
407 @end defvar | |
408 | |
409 @ignore | |
410 arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec | |
411 @end ignore |