]> code.delx.au - gnu-emacs/blob - man/abbrevs.texi
*** empty log message ***
[gnu-emacs] / man / abbrevs.texi
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
4 @node Abbrevs, Picture, Building, Top
5 @chapter Abbrevs
6 @cindex abbrevs
7 @cindex expansion (of abbrevs)
8
9 A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert
10 it, into some different text. Abbrevs are defined by the user to expand
11 in specific ways. For example, you might define @samp{foo} as an abbrev
12 expanding to @samp{find outer otter}. Then you would be able to insert
13 @samp{find outer otter } into the buffer by typing @kbd{f o o
14 @key{SPC}}.
15
16 A second kind of abbreviation facility is called @dfn{dynamic abbrev
17 expansion}. You use dynamic abbrev expansion with an explicit command
18 to expand the letters in the buffer before point by looking for other
19 words in the buffer that start with those letters. @xref{Dynamic
20 Abbrevs}.
21
22 `Hippie' expansion generalizes abbreviation expansion.
23 @xref{Hippie Expand, `Hippie' Expansion, autotype, Features for
24 Automatic Typing}.
25
26 @menu
27 * Abbrev Concepts:: Fundamentals of defined abbrevs.
28 * Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
29 * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
30 * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
31 * Saving Abbrevs:: Saving the entire list of abbrevs for another session.
32 * Dynamic Abbrevs:: Abbreviations for words already in the buffer.
33 * Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling.
34 @end menu
35
36 @node Abbrev Concepts
37 @section Abbrev Concepts
38
39 An @dfn{abbrev} is a word which has been defined to @dfn{expand} into
40 a specified @dfn{expansion}. When you insert a word-separator character
41 following the abbrev, that expands the abbrev---replacing the abbrev
42 with its expansion. For example, if @samp{foo} is defined as an abbrev
43 expanding to @samp{find outer otter}, then you can insert @samp{find
44 outer otter.} into the buffer by typing @kbd{f o o .}.
45
46 @findex abbrev-mode
47 @vindex abbrev-mode
48 @cindex Abbrev mode
49 @cindex mode, Abbrev
50 Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
51 Disabling Abbrev mode does not cause abbrev definitions to be forgotten,
52 but they do not expand until Abbrev mode is enabled again. The command
53 @kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it
54 turns Abbrev mode on if the argument is positive, off otherwise.
55 @xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode is
56 on when the variable is non-@code{nil}. The variable @code{abbrev-mode}
57 automatically becomes local to the current buffer when it is set.
58
59 Abbrev definitions can be @dfn{mode-specific}---active only in one major
60 mode. Abbrevs can also have @dfn{global} definitions that are active in
61 all major modes. The same abbrev can have a global definition and various
62 mode-specific definitions for different major modes. A mode-specific
63 definition for the current major mode overrides a global definition.
64
65 Abbrevs can be defined interactively during the editing session. Lists
66 of abbrev definitions can also be saved in files and reloaded in later
67 sessions. Some users keep extensive lists of abbrevs that they load in
68 every session.
69
70 @node Defining Abbrevs
71 @section Defining Abbrevs
72
73 @table @kbd
74 @item C-x a g
75 Define an abbrev, using one or more words before point as its expansion
76 (@code{add-global-abbrev}).
77 @item C-x a l
78 Similar, but define an abbrev specific to the current major mode
79 (@code{add-mode-abbrev}).
80 @item C-x a i g
81 Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}).
82 @item C-x a i l
83 Define a word in the buffer as a mode-specific abbrev
84 (@code{inverse-add-mode-abbrev}).
85 @item M-x kill-all-abbrevs
86 This command discards all abbrev definitions currently in effect,
87 leaving a blank slate.
88 @end table
89
90 @kindex C-x a g
91 @findex add-global-abbrev
92 The usual way to define an abbrev is to enter the text you want the
93 abbrev to expand to, position point after it, and type @kbd{C-x a g}
94 (@code{add-global-abbrev}). This reads the abbrev itself using the
95 minibuffer, and then defines it as an abbrev for one or more words before
96 point. Use a numeric argument to say how many words before point should be
97 taken as the expansion. For example, to define the abbrev @samp{foo} as
98 mentioned above, insert the text @samp{find outer otter} and then type
99 @kbd{C-u 3 C-x a g f o o @key{RET}}.
100
101 An argument of zero to @kbd{C-x a g} means to use the contents of the
102 region as the expansion of the abbrev being defined.
103
104 @kindex C-x a l
105 @findex add-mode-abbrev
106 The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but
107 defines a mode-specific abbrev. Mode-specific abbrevs are active only in a
108 particular major mode. @kbd{C-x a l} defines an abbrev for the major mode
109 in effect at the time @kbd{C-x a l} is typed. The arguments work the same
110 as for @kbd{C-x a g}.
111
112 @kindex C-x a i g
113 @findex inverse-add-global-abbrev
114 @kindex C-x a i l
115 @findex inverse-add-mode-abbrev
116 If the text already in the buffer is the abbrev, rather than its
117 expansion, use command @kbd{C-x a i g}
118 (@code{inverse-add-global-abbrev}) instead of @kbd{C-x a g}, or use
119 @kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) instead of @kbd{C-x a
120 l}. These commands are called ``inverse'' because they invert the
121 meaning of the two text strings they use (one from the buffer and one
122 read with the minibuffer).
123
124 To change the definition of an abbrev, just define a new definition.
125 When the abbrev has a prior definition, the abbrev definition commands
126 ask for confirmation for replacing it.
127
128 To remove an abbrev definition, give a negative argument to the abbrev
129 definition command: @kbd{C-u - C-x a g} or @kbd{C-u - C-x a l}. The
130 former removes a global definition, while the latter removes a
131 mode-specific definition.
132
133 @findex kill-all-abbrevs
134 @kbd{M-x kill-all-abbrevs} removes all the abbrev definitions there
135 are, both global and local.
136
137 @node Expanding Abbrevs
138 @section Controlling Abbrev Expansion
139
140 An abbrev expands whenever it is present in the buffer just before
141 point and you type a self-inserting whitespace or punctuation character
142 (@key{SPC}, comma, etc.@:). More precisely, any character that is not a
143 word constituent expands an abbrev, and any word-constituent character
144 can be part of an abbrev. The most common way to use an abbrev is to
145 insert it and then insert a punctuation character to expand it.
146
147 @vindex abbrev-all-caps
148 Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find
149 outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into
150 @samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the
151 variable @code{abbrev-all-caps} (a non-@code{nil} value chooses the first
152 of the two expansions).
153
154 These commands are used to control abbrev expansion:
155
156 @table @kbd
157 @item M-'
158 Separate a prefix from a following abbrev to be expanded
159 (@code{abbrev-prefix-mark}).
160 @item C-x a e
161 @findex expand-abbrev
162 Expand the abbrev before point (@code{expand-abbrev}).
163 This is effective even when Abbrev mode is not enabled.
164 @item M-x expand-region-abbrevs
165 Expand some or all abbrevs found in the region.
166 @end table
167
168 @kindex M-'
169 @findex abbrev-prefix-mark
170 You may wish to expand an abbrev with a prefix attached; for example,
171 if @samp{cnst} expands into @samp{construction}, you might want to use
172 it to enter @samp{reconstruction}. It does not work to type
173 @kbd{recnst}, because that is not necessarily a defined abbrev. What
174 you can do is use the command @kbd{M-'} (@code{abbrev-prefix-mark}) in
175 between the prefix @samp{re} and the abbrev @samp{cnst}. First, insert
176 @samp{re}. Then type @kbd{M-'}; this inserts a hyphen in the buffer to
177 indicate that it has done its work. Then insert the abbrev @samp{cnst};
178 the buffer now contains @samp{re-cnst}. Now insert a non-word character
179 to expand the abbrev @samp{cnst} into @samp{construction}. This
180 expansion step also deletes the hyphen that indicated @kbd{M-'} had been
181 used. The result is the desired @samp{reconstruction}.
182
183 If you actually want the text of the abbrev in the buffer, rather than
184 its expansion, you can accomplish this by inserting the following
185 punctuation with @kbd{C-q}. Thus, @kbd{foo C-q ,} leaves @samp{foo,} in
186 the buffer.
187
188 @findex unexpand-abbrev
189 If you expand an abbrev by mistake, you can undo the expansion and
190 bring back the abbrev itself by typing @kbd{C-_} to undo (@pxref{Undo}).
191 This also undoes the insertion of the non-word character that expanded
192 the abbrev. If the result you want is the terminating non-word
193 character plus the unexpanded abbrev, you must reinsert the terminating
194 character, quoting it with @kbd{C-q}. You can also use the command
195 @kbd{M-x unexpand-abbrev} to cancel the last expansion without
196 deleting the terminating character.
197
198 @findex expand-region-abbrevs
199 @kbd{M-x expand-region-abbrevs} searches through the region for defined
200 abbrevs, and for each one found offers to replace it with its expansion.
201 This command is useful if you have typed in text using abbrevs but forgot
202 to turn on Abbrev mode first. It may also be useful together with a
203 special set of abbrev definitions for making several global replacements at
204 once. This command is effective even if Abbrev mode is not enabled.
205
206 Expanding an abbrev runs the hook @code{pre-abbrev-expand-hook}
207 (@pxref{Hooks}).
208
209 @need 1500
210 @node Editing Abbrevs
211 @section Examining and Editing Abbrevs
212
213 @table @kbd
214 @item M-x list-abbrevs
215 Display a list of all abbrev definitions. With numeric argument, list
216 only local abbrevs.
217 @item M-x edit-abbrevs
218 Edit a list of abbrevs; you can add, alter or remove definitions.
219 @end table
220
221 @findex list-abbrevs
222 The output from @kbd{M-x list-abbrevs} looks like this:
223
224 @example
225 (lisp-mode-abbrev-table)
226 "dk" 0 "define-key"
227 (global-abbrev-table)
228 "dfn" 0 "definition"
229 @end example
230
231 @noindent
232 (Some blank lines of no semantic significance, and some other abbrev
233 tables, have been omitted.)
234
235 A line containing a name in parentheses is the header for abbrevs in a
236 particular abbrev table; @code{global-abbrev-table} contains all the global
237 abbrevs, and the other abbrev tables that are named after major modes
238 contain the mode-specific abbrevs.
239
240 Within each abbrev table, each nonblank line defines one abbrev. The
241 word at the beginning of the line is the abbrev. The number that
242 follows is the number of times the abbrev has been expanded. Emacs
243 keeps track of this to help you see which abbrevs you actually use, so
244 that you can eliminate those that you don't use often. The string at
245 the end of the line is the expansion.
246
247 @findex edit-abbrevs
248 @kindex C-c C-c @r{(Edit Abbrevs)}
249 @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev
250 definitions by editing a list of them in an Emacs buffer. The list has
251 the same format described above. The buffer of abbrevs is called
252 @samp{*Abbrevs*}, and is in Edit-Abbrevs mode. Type @kbd{C-c C-c} in
253 this buffer to install the abbrev definitions as specified in the
254 buffer---and delete any abbrev definitions not listed.
255
256 The command @code{edit-abbrevs} is actually the same as
257 @code{list-abbrevs} except that it selects the buffer @samp{*Abbrevs*}
258 whereas @code{list-abbrevs} merely displays it in another window.
259
260 @node Saving Abbrevs
261 @section Saving Abbrevs
262
263 These commands allow you to keep abbrev definitions between editing
264 sessions.
265
266 @table @kbd
267 @item M-x write-abbrev-file @key{RET} @var{file} @key{RET}
268 Write a file @var{file} describing all defined abbrevs.
269 @item M-x read-abbrev-file @key{RET} @var{file} @key{RET}
270 Read the file @var{file} and define abbrevs as specified therein.
271 @item M-x quietly-read-abbrev-file @key{RET} @var{file} @key{RET}
272 Similar but do not display a message about what is going on.
273 @item M-x define-abbrevs
274 Define abbrevs from definitions in current buffer.
275 @item M-x insert-abbrevs
276 Insert all abbrevs and their expansions into current buffer.
277 @end table
278
279 @findex write-abbrev-file
280 @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and
281 then writes a description of all current abbrev definitions into that
282 file. This is used to save abbrev definitions for use in a later
283 session. The text stored in the file is a series of Lisp expressions
284 that, when executed, define the same abbrevs that you currently have.
285
286 @findex read-abbrev-file
287 @findex quietly-read-abbrev-file
288 @vindex abbrev-file-name
289 @kbd{M-x read-abbrev-file} reads a file name using the minibuffer and
290 then reads the file, defining abbrevs according to the contents of the
291 file. @kbd{M-x quietly-read-abbrev-file} is the same except that it
292 does not display a message in the echo area saying that it is doing its
293 work; it is actually useful primarily in the @file{.emacs} file. If an
294 empty argument is given to either of these functions, they use the file
295 name specified in the variable @code{abbrev-file-name}, which is by
296 default @code{"~/.abbrev_defs"}.
297
298 @vindex save-abbrevs
299 Emacs will offer to save abbrevs automatically if you have changed any of
300 them, whenever it offers to save all files (for @kbd{C-x s} or @kbd{C-x
301 C-c}). This feature can be inhibited by setting the variable
302 @code{save-abbrevs} to @code{nil}.
303
304 @findex insert-abbrevs
305 @findex define-abbrevs
306 The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are
307 similar to the previous commands but work on text in an Emacs buffer.
308 @kbd{M-x insert-abbrevs} inserts text into the current buffer before point,
309 describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses
310 the entire current buffer and defines abbrevs accordingly.@refill
311
312 @node Dynamic Abbrevs
313 @section Dynamic Abbrev Expansion
314
315 The abbrev facility described above operates automatically as you insert
316 text, but all abbrevs must be defined explicitly. By contrast,
317 @dfn{dynamic abbrevs} allow the meanings of abbrevs to be determined
318 automatically from the contents of the buffer, but dynamic abbrev expansion
319 happens only when you request it explicitly.
320
321 @kindex M-/
322 @kindex C-M-/
323 @findex dabbrev-expand
324 @findex dabbrev-completion
325 @table @kbd
326 @item M-/
327 Expand the word in the buffer before point as a @dfn{dynamic abbrev},
328 by searching in the buffer for words starting with that abbreviation
329 (@code{dabbrev-expand}).
330
331 @item C-M-/
332 Complete the word before point as a dynamic abbrev
333 (@code{dabbrev-completion}).
334 @end table
335
336 @vindex dabbrev-limit
337 For example, if the buffer contains @samp{does this follow } and you
338 type @kbd{f o M-/}, the effect is to insert @samp{follow} because that
339 is the last word in the buffer that starts with @samp{fo}. A numeric
340 argument to @kbd{M-/} says to take the second, third, etc.@: distinct
341 expansion found looking backward from point. Repeating @kbd{M-/}
342 searches for an alternative expansion by looking farther back. After
343 scanning all the text before point, it searches the text after point.
344 The variable @code{dabbrev-limit}, if non-@code{nil}, specifies how far
345 in the buffer to search for an expansion.
346
347 @vindex dabbrev-check-all-buffers
348 After scanning the current buffer, @kbd{M-/} normally searches other
349 buffers, unless you have set @code{dabbrev-check-all-buffers} to
350 @code{nil}.
351
352 @vindex dabbrev-ignored-buffer-regexps
353 A more fine control of the buffers that are scanned is possible by
354 customizing the variable @code{dabbrev-ignored-buffer-regexps}, which should
355 contain a list of regular expressions. Buffers matching a regular
356 expression from that list are not searched.
357
358 A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says to
359 search first for expansions after point, and second for expansions
360 before point. If you repeat the @kbd{M-/} to look for another
361 expansion, do not specify an argument. This tries all the expansions
362 after point and then the expansions before point.
363
364 After you have expanded a dynamic abbrev, you can copy additional
365 words that follow the expansion in its original context. Simply type
366 @kbd{@key{SPC} M-/} for each word you want to copy. The spacing and
367 punctuation between words is copied along with the words.
368
369 The command @kbd{C-M-/} (@code{dabbrev-completion}) performs
370 completion of a dynamic abbreviation. Instead of trying the possible
371 expansions one by one, it finds all of them, then inserts the text that
372 they have in common. If they have nothing in common, @kbd{C-M-/}
373 displays a list of completions, from which you can select a choice in
374 the usual manner. @xref{Completion}.
375
376 Dynamic abbrev expansion is completely independent of Abbrev mode; the
377 expansion of a word with @kbd{M-/} is completely independent of whether
378 it has a definition as an ordinary abbrev.
379
380 @node Dabbrev Customization
381 @section Customizing Dynamic Abbreviation
382
383 Normally, dynamic abbrev expansion ignores case when searching for
384 expansions. That is, the expansion need not agree in case with the word
385 you are expanding.
386
387 @vindex dabbrev-case-fold-search
388 This feature is controlled by the variable
389 @code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored in
390 this search; if @code{nil}, the word and the expansion must match in
391 case. If the value of @code{dabbrev-case-fold-search} is
392 @code{case-fold-search}, which is true by default, then the variable
393 @code{case-fold-search} controls whether to ignore case while searching
394 for expansions.
395
396 @vindex dabbrev-case-replace
397 Normally, dynamic abbrev expansion preserves the case pattern @emph{of
398 the abbrev you have typed}, by converting the expansion to that case
399 pattern.
400
401 @vindex dabbrev-case-fold-search
402 The variable @code{dabbrev-case-replace} controls whether to preserve
403 the case pattern of the abbrev. If it is @code{t}, the abbrev's case
404 pattern is preserved in most cases; if @code{nil}, the expansion is
405 always copied verbatim. If the value of @code{dabbrev-case-replace} is
406 @code{case-replace}, which is true by default, then the variable
407 @code{case-replace} controls whether to copy the expansion verbatim.
408
409 However, if the expansion contains a complex mixed case pattern, and
410 the abbrev matches this pattern as far as it goes, then the expansion is
411 always copied verbatim, regardless of those variables. Thus, for
412 example, if the buffer contains @code{variableWithSillyCasePattern}, and
413 you type @kbd{v a M-/}, it copies the expansion verbatim including its
414 case pattern.
415
416 @vindex dabbrev-abbrev-char-regexp
417 The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil},
418 controls which characters are considered part of a word, for dynamic expansion
419 purposes. The regular expression must match just one character, never
420 two or more. The same regular expression also determines which
421 characters are part of an expansion. The value @code{nil} has a special
422 meaning: abbreviations are made of word characters, but expansions are
423 made of word and symbol characters.
424
425 @vindex dabbrev-abbrev-skip-leading-regexp
426 In shell scripts and makefiles, a variable name is sometimes prefixed
427 with @samp{$} and sometimes not. Major modes for this kind of text can
428 customize dynamic abbreviation to handle optional prefixes by setting
429 the variable @code{dabbrev-abbrev-skip-leading-regexp}. Its value
430 should be a regular expression that matches the optional prefix that
431 dynamic abbreviation should ignore.