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. See Creating and Interning Symbols, for information about obarrays. Each abbreviation is represented by a symbol in the obarray. The symbol’s name is the abbreviation; its value is the expansion; its function definition is the hook function for performing the expansion (see Defining Abbrevs); and its property list cell contains various additional properties, including the use count and the number of times the abbreviation has been expanded (see Abbrev Properties).
Certain abbrevs, called system abbrevs, are defined by a major
mode instead of the user. A system abbrev is identified by its
non-nil :system property (see Abbrev Properties).
When abbrevs are saved to an abbrev file, system abbrevs are omitted.
See Saving Abbrevs in Files.
Because the symbols used for abbrevs 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 a nonstandard way.
If the minor mode Abbrev mode is enabled, the buffer-local variable
abbrev-mode is non-nil, and abbrevs are automatically
expanded in the buffer. For the user-level commands for abbrevs, see
Abbrev Mode in The GNU Emacs Manual.
This section describes how to create and manipulate abbrev tables.
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 (see Abbrev Table Properties).
This function returns a non-nil value if object is an
abbrev table.
This function undefines all the abbrevs in abbrev-table, leaving it empty.
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.
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.
The optional string docstring is the documentation string of the variable tabname. The property list props is applied to the abbrev table (see 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.)
This is a list of symbols whose values are abbrev tables.
define-abbrev-table adds the new abbrev table name to this list.
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.
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.
This function defines an abbrev named name, in
abbrev-table, to expand to expansion and call hook,
with properties props (see 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.
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 (see 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 (see Expanding
Abbrevs in The GNU Emacs Manual).
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.
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.
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. See Standard Abbrev Tables, for the
definitions of local-abbrev-table and text-mode-abbrev-table.
See Advising Emacs Lisp 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.
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.
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.
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.
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.
This is the local abbrev table used in Text mode.
This is the local abbrev table used in Lisp mode. It is the parent of the local abbrev table used in Emacs Lisp mode. See 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:
Set the property prop of abbrev to value val.
Return the property prop of abbrev, or nil if the
abbrev has no such property.
The following properties have special meanings:
:countThis property counts the number of times the abbrev has
been expanded. If not explicitly set, it is initialized to 0 by
define-abbrev.
:systemIf non-nil, this property marks the abbrev as a system abbrev.
Such abbrevs are not saved (see Saving Abbrevs in Files).
:enable-functionIf 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-fixedIf 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:
Set the property prop of abbrev table table to value val.
Return the property prop of abbrev table table, or nil
if table has no such property.
The following properties have special meaning:
:enable-functionThis 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-fixedThis is like the :case-fixed abbrev property except that it
applies to all abbrevs in the table.
:regexpIf 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.
:parentsThis property holds a list of tables from which to inherit other abbrevs.
:abbrev-table-modiffThis property holds a counter incremented each time a new abbrev is added to the table.