This section describes how to create and manipulate abbrev tables.

make-abbrev-table

This function creates and returns a new, empty abbrev table—an obarray containing no symbols. props is a property list that is applied to the new table (Abbrev Table Properties).

abbrev-table-p

This function returns a non-nil value if object is an abbrev table.

clear-abbrev-table

This function undefines all the abbrevs in abbrev-table, leaving it empty.

copy-abbrev-table

This function returns a copy of abbrev-table—a new abbrev table containing the same abbrev definitions. It does not copy any property lists; only the names, values, and functions.

define-abbrev-table

This function defines tabname (a symbol) as an abbrev table name, i.e., as a variable whose value is an abbrev table. It defines abbrevs in the table according to definitions, a list of elements of the form (ABBREVNAME EXPANSION [HOOK] [PROPS...]). These elements are passed as arguments to define-abbrev. @c The return value is always nil. The optional string docstring is the documentation string of the variable tabname. The property list props is applied to the abbrev table (Abbrev Table Properties). If this function is called more than once for the same tabname, subsequent calls add the definitions in definitions to tabname, rather than overwriting the entire original contents. (A subsequent call only overrides abbrevs explicitly redefined or undefined in definitions.)

abbrev-table-name-list

This is a list of symbols whose values are abbrev tables. define-abbrev-table adds the new abbrev table name to this list.

insert-abbrev-table-description

This function inserts before point a description of the abbrev table named name. The argument name is a symbol whose value is an abbrev table. @c The return value is always nil. If human is non-nil, the description is human-oriented. System abbrevs are listed and identified as such. Otherwise the description is a Lisp expression—a call to define-abbrev-table that would define name as it is currently defined, but without the system abbrevs. (The mode or package using name is supposed to add these to name separately.)

define-abbrev is the low-level basic function for defining an abbrev in an abbrev table. When a major mode defines a system abbrev, it should call define-abbrev and specify t for the :system property. Be aware that any saved non-system abbrevs are restored at startup, i.e., before some major modes are loaded. Therefore, major modes should not assume that their abbrev tables are empty when they are first loaded.

define-abbrev

This function defines an abbrev named name, in abbrev-table, to expand to expansion and call hook, with properties props (Abbrev Properties). The return value is name. The :system property in props is treated specially here: if it has the value force, then it will overwrite an existing definition even for a non-system abbrev of the same name. name should be a string. The argument expansion is normally the desired expansion (a string), or nil to undefine the abbrev. If it is anything but a string or nil, then the abbreviation expands solely by running hook. The argument hook is a function or nil. If hook is non-nil, then it is called with no arguments after the abbrev is replaced with expansion; point is located at the end of expansion when hook is called. If hook is a non-nil symbol whose no-self-insert property is non-nil, hook can explicitly control whether to insert the self-inserting input character that triggered the expansion. If hook returns non-nil in this case, that inhibits insertion of the character. By contrast, if hook returns nil, expand-abbrev (or abbrev-insert) also returns nil, as if expansion had not really occurred. Normally, define-abbrev sets the variable abbrevs-changed to t, if it actually changes the abbrev. This is so that some commands will offer to save the abbrevs. It does not do this for a system abbrev, since those aren't saved anyway.

only-global-abbrevs

If this variable is non-nil, it means that the user plans to use global abbrevs only. This tells the commands that define mode-specific abbrevs to define global ones instead. This variable does not alter the behavior of the functions in this section; it is examined by their callers.

A file of saved abbrev definitions is actually a file of Lisp code. The abbrevs are saved in the form of a Lisp program to define the same abbrev tables with the same contents. Therefore, you can load the file with load (How Programs Do Loading). However, the function quietly-read-abbrev-file is provided as a more convenient interface. Emacs automatically calls this function at startup. User-level facilities such as save-some-buffers can save abbrevs in a file automatically, under the control of variables described here.

abbrev-file-name

This is the default file name for reading and saving abbrevs. By default, Emacs will look for ~/.emacs.d/abbrev_defs, and, if not found, for ~/.abbrev_defs; if neither file exists, Emacs will create ~/.emacs.d/abbrev_defs.

quietly-read-abbrev-file

This function reads abbrev definitions from a file named filename, previously written with write-abbrev-file. If filename is omitted or nil, the file specified in abbrev-file-name is used. As the name implies, this function does not display any messages.

save-abbrevs

A non-nil value for save-abbrevs means that Emacs should offer to save abbrevs (if any have changed) when files are saved. If the value is silently, Emacs saves the abbrevs without asking the user. abbrev-file-name specifies the file to save the abbrevs in. The default value is t.

abbrevs-changed

This variable is set non-nil by defining or altering any abbrevs (except system abbrevs). This serves as a flag for various Emacs commands to offer to save your abbrevs.

Command write-abbrev-file

Save all abbrev definitions (except system abbrevs), for all abbrev tables listed in abbrev-table-name-list, in the file filename, in the form of a Lisp program that when loaded will define the same abbrevs. Tables that do not have any abbrevs to save are omitted. If filename is nil or omitted, abbrev-file-name is used. This function returns nil.

Abbrevs are usually expanded by certain interactive commands, including self-insert-command. This section describes the subroutines used in writing such commands, as well as the variables they use for communication.

abbrev-symbol

This function returns the symbol representing the abbrev named abbrev. It returns nil if that abbrev is not defined. The optional second argument table is the abbrev table in which to look it up. If table is nil, this function tries first the current buffer's local abbrev table, and second the global abbrev table.

abbrev-expansion

This function returns the string that abbrev would expand into (as defined by the abbrev tables used for the current buffer). It returns nil if abbrev is not a valid abbrev. The optional argument table specifies the abbrev table to use, as in abbrev-symbol.

Command expand-abbrev

This command expands the abbrev before point, if any. If point does not follow an abbrev, this command does nothing. To do the expansion, it calls the function that is the value of the abbrev-expand-function variable, with no arguments, and returns whatever that function does. The default expansion function returns the abbrev symbol if it did expansion, and nil otherwise. If the abbrev symbol has a hook function that is a symbol whose no-self-insert property is non-nil, and if the hook function returns nil as its value, then the default expansion function returns nil, even though expansion did occur.

abbrev-insert

This function inserts the abbrev expansion of abbrev, replacing the text between start and end. If start is omitted, it defaults to point. name, if non-nil, should be the name by which this abbrev was found (a string); it is used to figure out whether to adjust the capitalization of the expansion. The function returns abbrev if the abbrev was successfully inserted, otherwise it returns nil.

Command abbrev-prefix-mark

This command marks the current location of point as the beginning of an abbrev. The next call to expand-abbrev will use the text from here to point (where it is then) as the abbrev to expand, rather than using the previous word as usual. First, this command expands any abbrev before point, unless arg is non-nil. (Interactively, arg is the prefix argument.) Then it inserts a hyphen before point, to indicate the start of the next abbrev to be expanded. The actual expansion removes the hyphen.

abbrev-all-caps

When this is set non-nil, an abbrev entered entirely in upper case is expanded using all upper case. Otherwise, an abbrev entered entirely in upper case is expanded by capitalizing each word of the expansion.

abbrev-start-location

The value of this variable is a buffer position (an integer or a marker) for expand-abbrev to use as the start of the next abbrev to be expanded. The value can also be nil, which means to use the word before point instead. abbrev-start-location is set to nil each time expand-abbrev is called. This variable is also set by abbrev-prefix-mark.

abbrev-start-location-buffer

The value of this variable is the buffer for which abbrev-start-location has been set. Trying to expand an abbrev in any other buffer clears abbrev-start-location. This variable is set by abbrev-prefix-mark.

last-abbrev

This is the abbrev-symbol of the most recent abbrev expanded. This information is left by expand-abbrev for the sake of the unexpand-abbrev command (Expanding Abbrevs).

last-abbrev-location

This is the location of the most recent abbrev expanded. This contains information left by expand-abbrev for the sake of the unexpand-abbrev command.

last-abbrev-text

This is the exact expansion text of the most recent abbrev expanded, after case conversion (if any). Its value is nil if the abbrev has already been unexpanded. This contains information left by expand-abbrev for the sake of the unexpand-abbrev command.

abbrev-expand-function

The value of this variable is a function that expand-abbrev will call with no arguments to do the expansion. The function can do anything it wants before and after performing the expansion. It should return the abbrev symbol if expansion took place.

The following sample code shows a simple use of abbrev-expand-function. It assumes that foo-mode is a mode for editing certain files in which lines that start with # are comments. You want to use Text mode abbrevs for those lines. The regular local abbrev table, foo-mode-abbrev-table is appropriate for all other lines. Standard Abbrev Tables, for the definitions of local-abbrev-table and text-mode-abbrev-table. Advising Functions, for details of add-function.

(defun foo-mode-abbrev-expand-function (expand)
  (if (not (save-excursion (forward-line 0) (eq (char-after) ?#)))
      ;; Performs normal expansion.
      (funcall expand)
    ;; We're inside a comment: use the text-mode abbrevs.
    (let ((local-abbrev-table text-mode-abbrev-table))
      (funcall expand))))

(add-hook 'foo-mode-hook
          (lambda ()
            (add-function :around (local 'abbrev-expand-function)
                          #'foo-mode-abbrev-expand-function)))

Here we list the variables that hold the abbrev tables for the preloaded major modes of Emacs.

global-abbrev-table

This is the abbrev table for mode-independent abbrevs. The abbrevs defined in it apply to all buffers. Each buffer may also have a local abbrev table, whose abbrev definitions take precedence over those in the global table.

local-abbrev-table

The value of this buffer-local variable is the (mode-specific) abbreviation table of the current buffer. It can also be a list of such tables.

abbrev-minor-mode-table-alist

The value of this variable is a list of elements of the form (MODE . ABBREV-TABLE) where mode is the name of a variable: if the variable is bound to a non-nil value, then the abbrev-table is active, otherwise it is ignored. abbrev-table can also be a list of abbrev tables.

fundamental-mode-abbrev-table

This is the local abbrev table used in Fundamental mode; in other words, it is the local abbrev table in all buffers in Fundamental mode.

text-mode-abbrev-table

This is the local abbrev table used in Text mode.

lisp-mode-abbrev-table

This is the local abbrev table used in Lisp mode. It is the parent of the local abbrev table used in Emacs Lisp mode. Abbrev Table Properties.

Abbrevs have properties, some of which influence the way they work. You can provide them as arguments to define-abbrev, and manipulate them with the following functions:

abbrev-put

Set the property prop of abbrev to value val.

abbrev-get

Return the property prop of abbrev, or nil if the abbrev has no such property.

The following properties have special meanings:

:count

This property counts the number of times the abbrev has been expanded. If not explicitly set, it is initialized to 0 by define-abbrev.

:system

If non-nil, this property marks the abbrev as a system abbrev. Such abbrevs are not saved (Abbrev Files).

:enable-function

If non-nil, this property should be a function of no arguments which returns nil if the abbrev should not be used and t otherwise.

:case-fixed

If non-nil, this property indicates that the case of the abbrev's name is significant and should only match a text with the same pattern of capitalization. It also disables the code that modifies the capitalization of the expansion.

Like abbrevs, abbrev tables have properties, some of which influence the way they work. You can provide them as arguments to define-abbrev-table, and manipulate them with the functions:

abbrev-table-put

Set the property prop of abbrev table table to value val.

abbrev-table-get

Return the property prop of abbrev table table, or nil if table has no such property.

The following properties have special meaning:

:enable-function

This is like the :enable-function abbrev property except that it applies to all abbrevs in the table. It is used before even trying to find the abbrev before point, so it can dynamically modify the abbrev table.

:case-fixed

This is like the :case-fixed abbrev property except that it applies to all abbrevs in the table.

:regexp

If non-nil, this property is a regular expression that indicates how to extract the name of the abbrev before point, before looking it up in the table. When the regular expression matches before point, the abbrev name is expected to be in submatch 1. If this property is nil, the default is to use backward-word and forward-word to find the name. This property allows the use of abbrevs whose name contains characters of non-word syntax.

:parents

This property holds a list of tables from which to inherit other abbrevs.

:abbrev-table-modiff

This property holds a counter incremented each time a new abbrev is added to the table.