2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1994, 1999, 2001-2012 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @node Abbrevs, Processes, Syntax Tables, Top
6 @chapter Abbrevs and Abbrev Expansion
8 @c @cindex abbrev table Redundant with "abbrev".
10 An abbreviation or @dfn{abbrev} is a string of characters that may be
11 expanded to a longer string. The user can insert the abbrev string and
12 find it replaced automatically with the expansion of the abbrev. This
15 The set of abbrevs currently in effect is recorded in an @dfn{abbrev
16 table}. Each buffer has a local abbrev table, but normally all buffers
17 in the same major mode share one abbrev table. There is also a global
18 abbrev table. Normally both are used.
20 An abbrev table is represented as an obarray. @xref{Creating
21 Symbols}, for information about obarrays. Each abbreviation is
22 represented by a symbol in the obarray. The symbol's name is the
23 abbreviation; its value is the expansion; its function definition is
24 the hook function for performing the expansion (@pxref{Defining
25 Abbrevs}); and its property list cell contains various additional
26 properties, including the use count and the number of times the
27 abbreviation has been expanded (@pxref{Abbrev Properties}).
30 Certain abbrevs, called @dfn{system abbrevs}, are defined by a major
31 mode instead of the user. A system abbrev is identified by its
32 non-@code{nil} @code{:system} property (@pxref{Abbrev Properties}).
33 When abbrevs are saved to an abbrev file, system abbrevs are omitted.
36 Because the symbols used for abbrevs are not interned in the usual
37 obarray, they will never appear as the result of reading a Lisp
38 expression; in fact, normally they are never used except by the code
39 that handles abbrevs. Therefore, it is safe to use them in a
42 If the minor mode Abbrev mode is enabled, the buffer-local variable
43 @code{abbrev-mode} is non-@code{nil}, and abbrevs are automatically
44 expanded in the buffer. For the user-level commands for abbrevs, see
45 @ref{Abbrevs,, Abbrev Mode, emacs, The GNU Emacs Manual}.
48 * Tables: Abbrev Tables. Creating and working with abbrev tables.
49 * Defining Abbrevs:: Specifying abbreviations and their expansions.
50 * Files: Abbrev Files. Saving abbrevs in files.
51 * Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
52 * Standard Abbrev Tables:: Abbrev tables used by various major modes.
53 * Abbrev Properties:: How to read and set abbrev properties.
54 Which properties have which effect.
55 * Abbrev Table Properties:: How to read and set abbrev table properties.
56 Which properties have which effect.
59 @node Abbrev Tables, Defining Abbrevs, Abbrevs, Abbrevs
60 @section Abbrev Tables
62 This section describes how to create and manipulate abbrev tables.
64 @defun make-abbrev-table &optional props
65 This function creates and returns a new, empty abbrev table---an
66 obarray containing no symbols. It is a vector filled with zeros.
67 @var{props} is a property list that is applied to the new table
68 (@pxref{Abbrev Table Properties}).
71 @defun abbrev-table-p object
72 This function returns a non-@code{nil} value if @var{object} is an
76 @defun clear-abbrev-table abbrev-table
77 This function undefines all the abbrevs in @var{abbrev-table}, leaving
79 @c Don't see why this needs saying.
80 @c It always returns @code{nil}.
83 @defun copy-abbrev-table abbrev-table
84 This function returns a copy of @var{abbrev-table}---a new abbrev
85 table containing the same abbrev definitions. It does @emph{not} copy
86 any property lists; only the names, values, and functions.
89 @defun define-abbrev-table tabname definitions &optional docstring &rest props
90 This function defines @var{tabname} (a symbol) as an abbrev table
91 name, i.e., as a variable whose value is an abbrev table. It defines
92 abbrevs in the table according to @var{definitions}, a list of
93 elements of the form @code{(@var{abbrevname} @var{expansion}
94 [@var{hook}] [@var{props}...])}. These elements are passed as
95 arguments to @code{define-abbrev}. @c The return value is always @code{nil}.
97 The optional string @var{docstring} is the documentation string of the
98 variable @var{tabname}. The property list @var{props} is applied to
99 the abbrev table (@pxref{Abbrev Table Properties}).
101 If this function is called more than once for the same @var{tabname},
102 subsequent calls add the definitions in @var{definitions} to
103 @var{tabname}, rather than overwriting the entire original contents.
104 (A subsequent call only overrides abbrevs explicitly redefined or
105 undefined in @var{definitions}.)
108 @defvar abbrev-table-name-list
109 This is a list of symbols whose values are abbrev tables.
110 @code{define-abbrev-table} adds the new abbrev table name to this list.
113 @defun insert-abbrev-table-description name &optional human
114 This function inserts before point a description of the abbrev table
115 named @var{name}. The argument @var{name} is a symbol whose value is an
116 abbrev table. @c The return value is always @code{nil}.
118 If @var{human} is non-@code{nil}, the description is human-oriented.
119 System abbrevs are listed and identified as such. Otherwise the
120 description is a Lisp expression---a call to @code{define-abbrev-table}
121 that would define @var{name} as it is currently defined, but without
122 the system abbrevs. (The mode or package using @var{name} is supposed
123 to add these to @var{name} separately.)
126 @node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs
127 @comment node-name, next, previous, up
128 @section Defining Abbrevs
130 @code{define-abbrev} is the low-level basic function for defining an
131 abbrev in an abbrev table.
133 When a major mode defines a system abbrev, it should call
134 @code{define-abbrev} and specify @code{t} for the @code{:system}
135 property. Be aware that any saved non-``system'' abbrevs are restored
136 at startup, i.e. before some major modes are loaded. Therefore, major
137 modes should not assume that their abbrev tables are empty when they
140 @defun define-abbrev abbrev-table name expansion &optional hook &rest props
141 This function defines an abbrev named @var{name}, in
142 @var{abbrev-table}, to expand to @var{expansion} and call @var{hook},
143 with properties @var{props} (@pxref{Abbrev Properties}). The return
144 value is @var{name}. The @code{:system} property in @var{props} is
145 treated specially here: if it has the value @code{force}, then it will
146 overwrite an existing definition even for a non-``system'' abbrev of
149 @var{name} should be a string. The argument @var{expansion} is
150 normally the desired expansion (a string), or @code{nil} to undefine
151 the abbrev. If it is anything but a string or @code{nil}, then the
152 abbreviation ``expands'' solely by running @var{hook}.
154 The argument @var{hook} is a function or @code{nil}. If @var{hook} is
155 non-@code{nil}, then it is called with no arguments after the abbrev is
156 replaced with @var{expansion}; point is located at the end of
157 @var{expansion} when @var{hook} is called.
159 @cindex @code{no-self-insert} property
160 If @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert}
161 property is non-@code{nil}, @var{hook} can explicitly control whether
162 to insert the self-inserting input character that triggered the
163 expansion. If @var{hook} returns non-@code{nil} in this case, that
164 inhibits insertion of the character. By contrast, if @var{hook}
165 returns @code{nil}, @code{expand-abbrev} (or @code{abbrev-insert})
166 also returns @code{nil}, as if expansion had not really occurred.
168 Normally, @code{define-abbrev} sets the variable
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 aren't saved anyway.
174 @defopt only-global-abbrevs
175 If this variable is non-@code{nil}, it means that the user plans to use
176 global abbrevs only. This tells the commands that define mode-specific
177 abbrevs to define global ones instead. This variable does not alter the
178 behavior of the functions in this section; it is examined by their
182 @node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs
183 @section Saving Abbrevs in Files
185 A file of saved abbrev definitions is actually a file of Lisp code.
186 The abbrevs are saved in the form of a Lisp program to define the same
187 abbrev tables with the same contents. Therefore, you can load the file
188 with @code{load} (@pxref{How Programs Do Loading}). However, the
189 function @code{quietly-read-abbrev-file} is provided as a more
190 convenient interface. Emacs automatically calls this function at
193 User-level facilities such as @code{save-some-buffers} can save
194 abbrevs in a file automatically, under the control of variables
197 @defopt abbrev-file-name
198 This is the default file name for reading and saving abbrevs.
201 @defun quietly-read-abbrev-file &optional filename
202 This function reads abbrev definitions from a file named @var{filename},
203 previously written with @code{write-abbrev-file}. If @var{filename} is
204 omitted or @code{nil}, the file specified in @code{abbrev-file-name} is
207 As the name implies, this function does not display any messages.
208 @c It returns @code{nil}.
212 A non-@code{nil} value for @code{save-abbrevs} means that Emacs should
213 offer to save abbrevs (if any have changed) when files are saved. If
214 the value is @code{silently}, Emacs saves the abbrevs without asking
215 the user. @code{abbrev-file-name} specifies the file to save the
219 @defvar abbrevs-changed
220 This variable is set non-@code{nil} by defining or altering any
221 abbrevs (except system abbrevs). This serves as a flag for various
222 Emacs commands to offer to save your abbrevs.
225 @deffn Command write-abbrev-file &optional filename
226 Save all abbrev definitions (except system abbrevs), for all abbrev
227 tables listed in @code{abbrev-table-name-list}, in the file
228 @var{filename}, in the form of a Lisp program that when loaded will
229 define the same abbrevs. If @var{filename} is @code{nil} or omitted,
230 @code{abbrev-file-name} is used. This function returns @code{nil}.
233 @node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs
234 @comment node-name, next, previous, up
235 @section Looking Up and Expanding Abbreviations
237 Abbrevs are usually expanded by certain interactive commands,
238 including @code{self-insert-command}. This section describes the
239 subroutines used in writing such commands, as well as the variables they
240 use for communication.
242 @defun abbrev-symbol abbrev &optional table
243 This function returns the symbol representing the abbrev named
244 @var{abbrev}. It returns @code{nil} if that abbrev is not
245 defined. The optional second argument @var{table} is the abbrev table
246 in which to look it up. If @var{table} is @code{nil}, this function
247 tries first the current buffer's local abbrev table, and second the
251 @defun abbrev-expansion abbrev &optional table
252 This function returns the string that @var{abbrev} would expand into (as
253 defined by the abbrev tables used for the current buffer). It returns
254 @code{nil} if @var{abbrev} is not a valid abbrev.
255 The optional argument @var{table} specifies the abbrev table to use,
256 as in @code{abbrev-symbol}.
259 @deffn Command expand-abbrev
260 This command expands the abbrev before point, if any. If point does not
261 follow an abbrev, this command does nothing. The command returns the
262 abbrev symbol if it did expansion, @code{nil} otherwise.
264 If the abbrev symbol has a hook function that is a symbol whose
265 @code{no-self-insert} property is non-@code{nil}, and if the hook
266 function returns @code{nil} as its value, then @code{expand-abbrev}
267 returns @code{nil} even though expansion did occur.
270 @defun abbrev-insert abbrev &optional name start end
271 This function inserts the abbrev expansion of @code{abbrev}, replacing
272 the text between @code{start} and @code{end}. If @code{start} is
273 omitted, it defaults to point. @code{name}, if non-@code{nil}, should
274 be the name by which this abbrev was found (a string); it is used to
275 figure out whether to adjust the capitalization of the expansion. The
276 function returns @code{abbrev} if the abbrev was successfully
280 @deffn Command abbrev-prefix-mark &optional arg
281 This command marks the current location of point as the beginning of
282 an abbrev. The next call to @code{expand-abbrev} will use the text
283 from here to point (where it is then) as the abbrev to expand, rather
284 than using the previous word as usual.
286 First, this command expands any abbrev before point, unless @var{arg}
287 is non-@code{nil}. (Interactively, @var{arg} is the prefix argument.)
288 Then it inserts a hyphen before point, to indicate the start of the
289 next abbrev to be expanded. The actual expansion removes the hyphen.
292 @defopt abbrev-all-caps
293 When this is set non-@code{nil}, an abbrev entered entirely in upper
294 case is expanded using all upper case. Otherwise, an abbrev entered
295 entirely in upper case is expanded by capitalizing each word of the
299 @defvar abbrev-start-location
300 The value of this variable is a buffer position (an integer or a marker)
301 for @code{expand-abbrev} to use as the start of the next abbrev to be
302 expanded. The value can also be @code{nil}, which means to use the
303 word before point instead. @code{abbrev-start-location} is set to
304 @code{nil} each time @code{expand-abbrev} is called. This variable is
305 also set by @code{abbrev-prefix-mark}.
308 @defvar abbrev-start-location-buffer
309 The value of this variable is the buffer for which
310 @code{abbrev-start-location} has been set. Trying to expand an abbrev
311 in any other buffer clears @code{abbrev-start-location}. This variable
312 is set by @code{abbrev-prefix-mark}.
316 This is the @code{abbrev-symbol} of the most recent abbrev expanded. This
317 information is left by @code{expand-abbrev} for the sake of the
318 @code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding
319 Abbrevs, emacs, The GNU Emacs Manual}).
322 @defvar last-abbrev-location
323 This is the location of the most recent abbrev expanded. This contains
324 information left by @code{expand-abbrev} for the sake of the
325 @code{unexpand-abbrev} command.
328 @defvar last-abbrev-text
329 This is the exact expansion text of the most recent abbrev expanded,
330 after case conversion (if any). Its value is @code{nil} if the abbrev
331 has already been unexpanded. This contains information left by
332 @code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command.
335 @defvar abbrev-expand-functions
336 This is a wrapper hook (@pxref{Running Hooks}) run around the
337 @code{expand-abbrev} function. Each function on this hook is called
338 with a single argument: a function that performs the normal abbrev
339 expansion. The hook function can hence do anything it wants before
340 and after performing the expansion. It can also choose not to call
341 its argument, thus overriding the default behavior; or it may even
342 call it several times. The function should return the abbrev symbol
343 if expansion took place.
346 The following sample code shows a simple use of
347 @code{abbrev-expand-functions}. It assumes that @code{foo-mode} is a
348 mode for editing certain files in which lines that start with @samp{#}
349 are comments. You want to use Text mode abbrevs for those lines. The
350 regular local abbrev table, @code{foo-mode-abbrev-table} is
351 appropriate for all other lines. @xref{Standard Abbrev Tables}, for the
352 definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.
355 (defun foo-mode-abbrev-expand-function (expand)
356 (if (not (save-excursion (forward-line 0) (eq (char-after) ?#)))
357 ;; Performs normal expansion.
359 ;; We're inside a comment: use the text-mode abbrevs.
360 (let ((local-abbrev-table text-mode-abbrev-table))
363 (add-hook 'foo-mode-hook
365 (add-hook 'abbrev-expand-functions
366 'foo-mode-abbrev-expand-function
370 @node Standard Abbrev Tables, Abbrev Properties, Abbrev Expansion, Abbrevs
371 @comment node-name, next, previous, up
372 @section Standard Abbrev Tables
374 Here we list the variables that hold the abbrev tables for the
375 preloaded major modes of Emacs.
377 @defvar global-abbrev-table
378 This is the abbrev table for mode-independent abbrevs. The abbrevs
379 defined in it apply to all buffers. Each buffer may also have a local
380 abbrev table, whose abbrev definitions take precedence over those in the
384 @defvar local-abbrev-table
385 The value of this buffer-local variable is the (mode-specific)
386 abbreviation table of the current buffer. It can also be a list of
390 @defvar abbrev-minor-mode-table-alist
391 The value of this variable is a list of elements of the form
392 @code{(@var{mode} . @var{abbrev-table})} where @var{mode} is the name
393 of a variable: if the variable is bound to a non-@code{nil} value,
394 then the @var{abbrev-table} is active, otherwise it is ignored.
395 @var{abbrev-table} can also be a list of abbrev tables.
398 @defvar fundamental-mode-abbrev-table
399 This is the local abbrev table used in Fundamental mode; in other words,
400 it is the local abbrev table in all buffers in Fundamental mode.
403 @defvar text-mode-abbrev-table
404 This is the local abbrev table used in Text mode.
407 @defvar lisp-mode-abbrev-table
408 This is the local abbrev table used in Lisp mode. It is the parent
409 of the local abbrev table used in Emacs Lisp mode. @xref{Abbrev Table
413 @node Abbrev Properties, Abbrev Table Properties, Standard Abbrev Tables, Abbrevs
414 @section Abbrev Properties
416 Abbrevs have properties, some of which influence the way they work.
417 You can provide them as arguments to @code{define-abbrev}, and
418 manipulate them with the following functions:
420 @defun abbrev-put abbrev prop val
421 Set the property @var{prop} of @var{abbrev} to value @var{val}.
424 @defun abbrev-get abbrev prop
425 Return the property @var{prop} of @var{abbrev}, or @code{nil} if the
426 abbrev has no such property.
429 The following properties have special meanings:
433 This property counts the number of times the abbrev has
434 been expanded. If not explicitly set, it is initialized to 0 by
435 @code{define-abbrev}.
438 If non-@code{nil}, this property marks the abbrev as a system abbrev.
439 Such abbrevs are not saved (@pxref{Abbrev Files}).
441 @item :enable-function
442 If non-@code{nil}, this property should be a function of no
443 arguments which returns @code{nil} if the abbrev should not be used
444 and @code{t} otherwise.
447 If non-@code{nil}, this property indicates that the case of the
448 abbrev's name is significant and should only match a text with the
449 same pattern of capitalization. It also disables the code that
450 modifies the capitalization of the expansion.
453 @node Abbrev Table Properties, , Abbrev Properties, Abbrevs
454 @section Abbrev Table Properties
456 Like abbrevs, abbrev tables have properties, some of which influence
457 the way they work. You can provide them as arguments to
458 @code{define-abbrev-table}, and manipulate them with the functions:
460 @defun abbrev-table-put table prop val
461 Set the property @var{prop} of abbrev table @var{table} to value @var{val}.
464 @defun abbrev-table-get table prop
465 Return the property @var{prop} of abbrev table @var{table}, or @code{nil}
466 if the abbrev has no such property.
469 The following properties have special meaning:
472 @item :enable-function
473 This is like the @code{:enable-function} abbrev property except that
474 it applies to all abbrevs in the table. It is used before even trying
475 to find the abbrev before point, so it can dynamically modify the
479 This is like the @code{:case-fixed} abbrev property except that it
480 applies to all abbrevs in the table.
483 If non-@code{nil}, this property is a regular expression that
484 indicates how to extract the name of the abbrev before point, before
485 looking it up in the table. When the regular expression matches
486 before point, the abbrev name is expected to be in submatch 1.
487 If this property is @code{nil}, the default is to use
488 @code{backward-word} and @code{forward-word} to find the name. This
489 property allows the use of abbrevs whose name contains characters of
493 This property holds a list of tables from which to inherit
496 @item :abbrev-table-modiff
497 This property holds a counter incremented each time a new abbrev is