Abbrevs And Abbrev Expansion

An abbreviation or abbrev is a string of characters that may be expanded to a longer string. The user can insert the abbrev string and find it replaced automatically with the expansion of the abbrev. This saves typing.

The set of abbrevs currently in effect is recorded in an abbrev table. Each buffer has a local abbrev table, but normally all buffers in the same major mode share one abbrev table. There is also a global abbrev table. Normally both are used.

An abbrev table is represented as an obarray containing a symbol for each abbreviation. The symbol's name is the abbreviation. Its value is the expansion; its function definition is the hook function to do the expansion (if any); its property list cell contains the use count, the number of times the abbreviation has been expanded. Because these symbols are not interned in the usual obarray, they will never appear as the result of reading a Lisp expression; in fact, normally they are never used except by the code that handles abbrevs. Therefore, it is safe to use them in an extremely nonstandard way. See section Creating and Interning Symbols.

For the user-level commands for abbrevs, see section `Abbrev Mode' in The GNU Emacs Manual.

• Abbrev Mode: Setting up Emacs for abbreviation.
• Tables: Creating and working with abbrev tables.
• Defining Abbrevs: Specifying abbreviations and their expansions.
• Files: Saving abbrevs in files.
• Expansion: Controlling expansion; expansion subroutines.
• Standard Abbrev Tables: Abbrev tables used by various major modes.

Setting Up Abbrev Mode

Abbrev mode is a minor mode controlled by the value of the variable abbrev-mode.

Variable: abbrev-mode

A non-nil value of this variable turns on the automatic expansion of abbrevs when their abbreviations are inserted into a buffer. If the value is nil, abbrevs may be defined, but they are not expanded automatically.

This variable automatically becomes local when set in any fashion.

Variable: default-abbrev-mode

This is the value abbrev-mode for buffers that do not override it. This is the same as (default-value 'abbrev-mode).

Abbrev Tables

This section describes how to create and manipulate abbrev tables.

Function: make-abbrev-table

This function creates and returns a new, empty abbrev table--an obarray containing no symbols. It is a vector filled with zeros.

Function: clear-abbrev-table table

This function undefines all the abbrevs in abbrev table table, leaving it empty. The function returns nil.

Function: define-abbrev-table tabname definitions

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 usecount). The value is always nil.

Variable: 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.

Function: insert-abbrev-table-description name &optional human

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. The value is always nil.

If human is non-nil, the description is human-oriented. Otherwise the description is a Lisp expression--a call to define-abbrev-table which would define name exactly as it is currently defined.

Defining Abbrevs

These functions define an abbrev in a specified abbrev table. define-abbrev is the low-level basic function, while add-abbrev is used by commands that ask for information from the user.

Function: add-abbrev table type arg

This function adds an abbreviation to abbrev table table. The argument type is a string describing in English the kind of abbrev this will be (typically, "global" or "mode-specific"); this is used in prompting the user. The argument arg is the number of words in the expansion.

The return value is the symbol which internally represents the new abbrev, or nil if the user declines to confirm redefining an existing abbrev.

Function: define-abbrev table name expansion hook

This function defines an abbrev in table named name, to expand to expansion, and call hook. The return value is an uninterned symbol which represents the abbrev inside Emacs; its name is name.

The argument name should be a string. The argument expansion should be a string, or nil, to undefine the abbrev.

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.

The use count of the abbrev is initialized to zero.

User Option: 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 functioning of the functions in this section; it is examined by their callers.

Saving Abbrevs in Files

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 (see section How Programs Do Loading). However, the function quietly-read-abbrev-file is provided as a more convenient interface.

User-level facilities such as save-some-buffers can save abbrevs in a file automatically, under the control of variables described here.

User Option: abbrev-file-name

This is the default file name for reading and saving abbrevs.

Function: quietly-read-abbrev-file filename

This function reads abbrev definitions from a file named filename, previously written with write-abbrev-file. If filename is nil, the file specified in abbrev-file-name is used. save-abbrevs is set to t so that changes will be saved.

This function does not display any messages. It returns nil.

User Option: save-abbrevs

A non-nil value for save-abbrev means that Emacs should save abbrevs when files are saved. abbrev-file-name specifies the file to save the abbrevs in.

Variable: abbrevs-changed

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

Command: write-abbrev-file filename

Save all abbrev definitions, in all abbrev tables, in the file filename, in the form of a Lisp program which when loaded will define the same abbrevs. This function returns nil.

Looking Up and Expanding Abbreviations

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

Function: abbrev-symbol abbrev &optional table

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

User Option: 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.

Function: abbrev-expansion abbrev &optional table

This function returns the string that abbrev would expand into (as defined by the abbrev tables used for the current buffer). The optional argument table specifies the abbrev table to use; if it is specified, the abbrev is looked up in that table only.

Variable: abbrev-start-location

This is the buffer position for expand-abbrev to use as the start of the next abbrev to be expanded. (nil means 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.

Variable: 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.

Variable: last-abbrev

This is the abbrev-symbol of the last abbrev expanded. This information is left by expand-abbrev for the sake of the unexpand-abbrev command.

Variable: last-abbrev-location

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

Variable: last-abbrev-text

This is the exact expansion text of the last abbrev expanded, as results from case conversion. 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.

Variable: pre-abbrev-expand-hook

This is a normal hook whose functions are executed, in sequence, just before any expansion of an abbrev. See section Hooks. Since it is a normal hook, the hook functions receive no arguments. However, they can find the abbrev to be expanded by looking in the buffer before point.

The following sample code shows a simple use of pre-abbrev-expand-hook. If the user terminates an abbrev with a punctuation character, the hook function asks for confirmation. Thus, this hook allows the user to decide whether to expand the abbrev, and aborts expansion if it is not confirmed.

(add-hook 'pre-abbrev-expand-hook 'query-if-not-space)

;; This is the function invoked by pre-abbrev-expand-hook.

;; If the user terminated the abbrev with a space, the function does
;; nothing (that is, it returns so that the abbrev can expand).  If the
;; user entered some other character, this function asks whether
;; expansion should continue.

;; If the user enters the prompt with y, the function returns
;; nil (because of the not function), but that is
;; acceptable; the return value has no effect on expansion.

(defun query-if-not-space ()
  (if (/= ?\  (preceding-char))
      (if (not (y-or-n-p "Do you want to expand this abbrev? "))
          (error "Not expanding this abbrev"))))

Standard Abbrev Tables

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

Variable: 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.

Variable: local-abbrev-table

The value of this buffer-local variable is the (mode-specific) abbreviation table of the current buffer.

Variable: fundamental-mode-abbrev-table

This is the local abbrev table used in Fundamental mode. It is the local abbrev table in all buffers in Fundamental mode.

Variable: text-mode-abbrev-table

This is the local abbrev table used in Text mode.

Variable: c-mode-abbrev-table

This is the local abbrev table used in C mode.

Variable: lisp-mode-abbrev-table

This is the local abbrev table used in Lisp mode and Emacs Lisp mode.