23. Abbrevs

An abbrev is a word which expands into some different text. Abbrevs are defined by the user to expand in specific ways. For example, you might define ‘foo’ as an abbrev expanding to ‘find outer otter’. With this abbrev defined, you would be able to get ‘find outer otter ’ into the buffer by typing f o o <SPC>.

Abbrevs expand only when Abbrev mode (a minor mode) is enabled. Disabling Abbrev mode does not cause abbrev definitions to be discarded, but they do not expand until Abbrev mode is enabled again. The command M-x abbrev-mode toggles Abbrev mode; with a numeric argument, it turns Abbrev mode on if the argument is positive, off otherwise. See section Minor Modes. abbrev-mode is also a variable; Abbrev mode is on when the variable is non-nil. The variable abbrev-mode automatically becomes local to the current buffer when it is set.

Abbrev definitions can be mode-specific—active only in one major mode. Abbrevs can also have global definitions that are active in all major modes. The same abbrev can have a global definition and various mode-specific definitions for different major modes. A mode-specific definition for the current major mode overrides a global definition.

You can define Abbrevs interactively during an editing session. You can also save lists of abbrev definitions in files and reload them in later sessions. Some users keep extensive lists of abbrevs that they load in every session.

A second kind of abbreviation facility is called the dynamic expansion. Dynamic abbrev expansion happens only when you give an explicit command and the result of the expansion depends only on the current contents of the buffer. See section Dynamic Abbrev Expansion.

23.1 Defining Abbrevs

C-x a g

Define an abbrev to expand into some text before point (add-global-abbrev).

C-x a l

Similar, but define an abbrev available only in the current major mode (add-mode-abbrev).

C-x a i g

Define a word in the buffer as an abbrev (inverse-add-global-abbrev).

C-x a i l

Define a word in the buffer as a mode-specific abbrev (inverse-add-mode-abbrev).

M-x kill-all-abbrevs

After this command, no abbrev definitions remain in effect.

The usual way to define an abbrev is to enter the text you want the abbrev to expand to, position point after it, and type C-x a g (add-global-abbrev). This reads the abbrev itself using the minibuffer, and then defines it as an abbrev for one or more words before point. Use a numeric argument to say how many words before point should be taken as the expansion. For example, to define the abbrev ‘foo’ as in the example above, insert the text ‘find outer otter’, then type
C-u 3 C-x a g f o o <RET>.

An argument of zero to C-x a g means to use the contents of the region as the expansion of the abbrev being defined.

The command C-x a l (add-mode-abbrev) is similar, but defines a mode-specific abbrev. Mode-specific abbrevs are active only in a particular major mode. C-x a l defines an abbrev for the major mode in effect at the time C-x a l is typed. The arguments work the same way they do for C-x a g.

If the text of an abbrev you want is already in the buffer instead of the expansion, use command C-x a i g (inverse-add-global-abbrev) instead of C-x a g, or use C-x a i l (inverse-add-mode-abbrev) instead of C-x a l. These commands are called “inverse” because they invert the meaning of the argument found in the buffer and the argument read using the minibuffer.

To change the definition of an abbrev, just add the new definition. You will be asked to confirm if the abbrev has a prior definition. To remove an abbrev definition, give a negative argument to C-x a g or C-x a l. You must choose the command to specify whether to kill a global definition or a mode-specific definition for the current mode, since those two definitions are independent for one abbrev.

M-x kill-all-abbrevs removes all existing abbrev definitions.

23.2 Controlling Abbrev Expansion

An abbrev expands whenever it is in a buffer just before point and you type a self-inserting punctuation character (<SPC>, comma, etc.). Most often an abbrev is used by inserting the abbrev followed by punctuation.

Abbrev expansion preserves case; thus, ‘foo’ expands into ‘find outer otter’, ‘Foo’ into ‘Find outer otter’, and ‘FOO’ into ‘FIND OUTER OTTER’ or ‘Find Outer Otter’ according to the variable abbrev-all-caps (a non-nil value chooses the first of the two expansions).

Two commands are available to control abbrev expansion:

M-'

Separate a prefix from a following abbrev to be expanded (abbrev-prefix-mark).

C-x a e

Expand the abbrev before point (expand-abbrev). This is effective even when Abbrev mode is not enabled.

M-x unexpand-abbrev

Undo last abbrev expansion.

M-x expand-region-abbrevs

Expand some or all abbrevs found in the region.

You may wish to expand an abbrev with a prefix attached. For example, if ‘cnst’ expands into ‘construction’, you may want to use it to enter ‘reconstruction’. It does not work to type recnst, because that is not necessarily a defined abbrev. Instead, you can use the command M-' (abbrev-prefix-mark) between the prefix ‘re’ and the abbrev ‘cnst’. First, insert ‘re’. Then type M-'; this inserts a minus sign in the buffer to indicate that it has done its work. Then insert the abbrev ‘cnst’. The buffer now contains ‘re-cnst’. Now insert a punctuation character to expand the abbrev ‘cnst’ into ‘construction’. The minus sign is deleted at this point by M-'. The resulting text is the desired ‘reconstruction’.

If you actually want the text of the abbrev in the buffer, rather than its expansion, insert the following punctuation with C-q. Thus, foo C-q - leaves ‘foo-’ in the buffer.

If you expand an abbrev by mistake, you can undo the expansion (replace the expansion by the original abbrev text) with M-x unexpand-abbrev. You can also use C-_ (undo) to undo the expansion; but that will first undo the insertion of the punctuation character.

M-x expand-region-abbrevs searches through the region for defined abbrevs, and offers to replace each one it finds with its expansion. This command is useful if you have typed text using abbrevs but forgot to turn on Abbrev mode first. It may also be useful together with a special set of abbrev definitions for making several global replacements at once. The command is effective even if Abbrev mode is not enabled.

23.3 Examining and Editing Abbrevs

M-x list-abbrevs

Print a list of all abbrev definitions.

M-x edit-abbrevs

Edit a list of abbrevs; you can add, alter, or remove definitions.

The output from M-x list-abbrevs looks like this:

(lisp-mode-abbrev-table)
"dk"           0    "define-key"
(global-abbrev-table)
"dfn"          0    "definition"

(Some blank lines of no semantic significance, and some other abbrev tables, have been omitted.)

A line containing a name in parentheses is the header for abbrevs in a particular abbrev table; global-abbrev-table contains all the global abbrevs, and the other abbrev tables that are named after major modes contain the mode-specific abbrevs.

Within each abbrev table, each non-blank line defines one abbrev. The word at the beginning is the abbrev. The number that appears is the number of times the abbrev has been expanded. Emacs keeps track of this to help you see which abbrevs you actually use, in case you want to eliminate those that you don’t use often. The string at the end of the line is the expansion.

M-x edit-abbrevs allows you to add, change or kill abbrev definitions by editing a list of them in an Emacs buffer. The list has the format described above. The buffer of abbrevs is called ‘*Abbrevs*’, and is in Edit-Abbrevs mode. This mode redefines the key C-c C-c to install the abbrev definitions as specified in the buffer. The edit-abbrevs-redefine command does this. Any abbrevs not described in the buffer are eliminated when this is done.

edit-abbrevs is actually the same as list-abbrevs, except that it selects the buffer ‘*Abbrevs*’ whereas list-abbrevs merely displays it in another window.

23.4 Saving Abbrevs

These commands allow you to keep abbrev definitions between editing sessions.

M-x write-abbrev-file

Write a file describing all defined abbrevs.

M-x read-abbrev-file

Read such an abbrev file and define abbrevs as specified there.

M-x quietly-read-abbrev-file

Similar, but do not display a message about what is going on.

M-x define-abbrevs

Define abbrevs from buffer.

M-x insert-abbrevs

Insert all abbrevs and their expansions into the buffer.

Use M-x write-abbrev-file to save abbrev definitions for use in a later session. The command reads a file name using the minibuffer and writes a description of all current abbrev definitions into the specified file. The text stored in the file looks like the output of M-x list-abbrevs.

M-x read-abbrev-file prompts for a file name using the minibuffer and reads the specified file, defining abbrevs according to its contents. M-x quietly-read-abbrev-file is the same but does not display a message in the echo area; it is actually useful primarily in the init file. See section The Init File. If you give an empty argument to either of these functions, the file name Emacs uses is the value of the variable abbrev-file-name, which is by default "~/.abbrev_defs".

Emacs offers to save abbrevs automatically if you have changed any of them, whenever it offers to save all files (for C-x s or C-x C-c). Set the variable save-abbrevs to nil to inhibit this feature.

The commands M-x insert-abbrevs and M-x define-abbrevs are similar to the previous commands but work on text in an Emacs buffer. M-x insert-abbrevs inserts text into the current buffer before point, describing all current abbrev definitions; M-x define-abbrevs parses the entire current buffer and defines abbrevs accordingly.

23.5 Dynamic Abbrev Expansion

The abbrev facility described above operates automatically as you insert text, but all abbrevs must be defined explicitly. By contrast, dynamic abbrevs allow the meanings of abbrevs to be determined automatically from the contents of the buffer, but dynamic abbrev expansion happens only when you request it explicitly.

M-/

Expand the word in the buffer before point as a dynamic abbrev, by searching in the buffer for words starting with that abbreviation (dabbrev-expand).

For example, if the buffer contains ‘does this follow ’ and you type f o M-/, the effect is to insert ‘follow’ because that is the last word in the buffer that starts with ‘fo’. A numeric argument to M-/ says to take the second, third, etc. distinct expansion found looking backward from point. Repeating M-/ searches for an alternative expansion by looking farther back. After the entire buffer before point has been considered, the buffer after point is searched.

Dynamic abbrev expansion is completely independent of Abbrev mode; the expansion of a word with M-/ is completely independent of whether it has a definition as an ordinary abbrev.

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.