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 (see section Defining Abbrevs); 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 is a minor mode controlled by the value of the
variable abbrev-mode
.
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 buffer-local when set in any fashion.
abbrev-mode
for buffers that do not override it. This
is the same as (default-value 'abbrev-mode)
.
This section describes how to create and manipulate abbrev tables.
nil
.
(abbrevname expansion
hook usecount)
. The return value is
always nil
.
define-abbrev-table
adds the new abbrev table name to this list.
nil
. If human is non-nil
, the description is
human-oriented. Otherwise the description is a Lisp expression--a
call to define-abbrev-table
that would define
name exactly as it is currently defined.
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.
"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 that internally represents the
new abbrev, or nil
if the user declines to confirm
redefining an existing abbrev.
The argument 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.
The use count of the abbrev is initialized to zero.
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 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.
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
.
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.
nil
by defining or altering any abbrevs. This
serves as a flag for various Emacs commands to offer to save your
abbrevs.
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.
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.
abbrev-symbol
.
t
if it
did expansion, nil
otherwise.
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.
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.
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
.
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
.
abbrev-symbol
of the most recent abbrev expanded. This
information is left by expand-abbrev
for the sake of
the unexpand-abbrev
command (see section `Expanding
Abbrevs' in The GNU Emacs Manual).
expand-abbrev
for the sake of the
unexpand-abbrev
command.
nil
if the abbrev has already been
unexpanded. This contains information left by
expand-abbrev
for the sake of the
unexpand-abbrev
command.
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 bypre-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 answers the prompt with y, the function returns ;;nil
(because of thenot
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"))))
Here we list the variables that hold the abbrev tables for the preloaded major modes of Emacs.