@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999, 2001, 2002, 2003,
-@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1994, 1999, 2001-2015 Free Software Foundation,
+@c Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/abbrevs
-@node Abbrevs, Processes, Syntax Tables, Top
+@node Abbrevs
@chapter Abbrevs and Abbrev Expansion
@cindex abbrev
@c @cindex abbrev table Redundant with "abbrev".
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 (@pxref{Defining Abbrevs}); its property list cell
-typically contains the use count, the number of times the abbreviation
-has been expanded. Alternatively, the use count is on the
-@code{count} property and the system-abbrev flag is on the
-@code{system-type} property. Abbrevs with a non-@code{nil}
-@code{system-type} property are called ``system'' abbrevs. They are
-usually defined by modes or packages, instead of by the user, and are
-treated specially in certain respects.
-
-Because the symbols used for abbrevs are not interned in the usual
+ An abbrev table is represented as an obarray. @xref{Creating
+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 (@pxref{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 (@pxref{Abbrev Properties}).
+
+@cindex system abbrev
+ Certain abbrevs, called @dfn{system abbrevs}, are defined by a major
+mode instead of the user. A system abbrev is identified by its
+non-@code{nil} @code{:system} property (@pxref{Abbrev Properties}).
+When abbrevs are saved to an abbrev file, system abbrevs are omitted.
+@xref{Abbrev 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 an
-extremely nonstandard way. @xref{Creating Symbols}.
+that handles abbrevs. Therefore, it is safe to use them in a
+nonstandard way.
- For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
-Mode, emacs, The GNU Emacs Manual}.
+ If the minor mode Abbrev mode is enabled, the buffer-local variable
+@code{abbrev-mode} is non-@code{nil}, and abbrevs are automatically
+expanded in the buffer. For the user-level commands for abbrevs, see
+@ref{Abbrevs,, Abbrev Mode, emacs, The GNU Emacs Manual}.
@menu
-* Abbrev Mode:: Setting up Emacs for abbreviation.
* Tables: Abbrev Tables. Creating and working with abbrev tables.
* Defining Abbrevs:: Specifying abbreviations and their expansions.
* Files: Abbrev Files. Saving abbrevs in files.
* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
* Standard Abbrev Tables:: Abbrev tables used by various major modes.
+* Abbrev Properties:: How to read and set abbrev properties.
+ Which properties have which effect.
+* Abbrev Table Properties:: How to read and set abbrev table properties.
+ Which properties have which effect.
@end menu
-@node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs
-@comment node-name, next, previous, up
-@section Setting Up Abbrev Mode
-
- Abbrev mode is a minor mode controlled by the value of the variable
-@code{abbrev-mode}.
-
-@defvar abbrev-mode
-A non-@code{nil} value of this variable turns on the automatic expansion
-of abbrevs when their abbreviations are inserted into a buffer.
-If the value is @code{nil}, abbrevs may be defined, but they are not
-expanded automatically.
-
-This variable automatically becomes buffer-local when set in any fashion.
-@end defvar
-
-@defvar default-abbrev-mode
-This is the value of @code{abbrev-mode} for buffers that do not override it.
-This is the same as @code{(default-value 'abbrev-mode)}.
-@end defvar
-
-@node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs
+@node Abbrev Tables
@section Abbrev Tables
+@cindex abbrev tables
This section describes how to create and manipulate abbrev tables.
-@defun 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.
+@defun make-abbrev-table &optional props
+This function creates and returns a new, empty abbrev table---an
+obarray containing no symbols. It is a vector filled with zeros.
+@var{props} is a property list that is applied to the new table
+(@pxref{Abbrev Table Properties}).
+@end defun
+
+@defun abbrev-table-p object
+This function returns a non-@code{nil} value if @var{object} is an
+abbrev table.
@end defun
-@defun clear-abbrev-table table
-This function undefines all the abbrevs in abbrev table @var{table},
-leaving it empty. It always returns @code{nil}.
+@defun clear-abbrev-table abbrev-table
+This function undefines all the abbrevs in @var{abbrev-table}, leaving
+it empty.
+@c Don't see why this needs saying.
+@c It always returns @code{nil}.
@end defun
-@defun copy-abbrev-table table
-This function returns a copy of abbrev table @var{table}---a new
-abbrev table that contains the same abbrev definitions. The only
-difference between @var{table} and the returned copy is that this
-function sets the property lists of all copied abbrevs to 0.
+@defun copy-abbrev-table abbrev-table
+This function returns a copy of @var{abbrev-table}---a new abbrev
+table containing the same abbrev definitions. It does @emph{not} copy
+any property lists; only the names, values, and functions.
@end defun
-@defun define-abbrev-table tabname definitions
+@defun define-abbrev-table tabname definitions &optional docstring &rest props
This function defines @var{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 @var{definitions}, a list of
elements of the form @code{(@var{abbrevname} @var{expansion}
-@var{hook} @var{usecount} @var{system-flag})}. If an element of
-@var{definitions} has length less than five, omitted elements default
-to @code{nil}. A value of @code{nil} for @var{usecount} is equivalent
-to zero. The return value is always @code{nil}.
+[@var{hook}] [@var{props}...])}. These elements are passed as
+arguments to @code{define-abbrev}. @c The return value is always @code{nil}.
+
+The optional string @var{docstring} is the documentation string of the
+variable @var{tabname}. The property list @var{props} is applied to
+the abbrev table (@pxref{Abbrev Table Properties}).
If this function is called more than once for the same @var{tabname},
subsequent calls add the definitions in @var{definitions} to
-@var{tabname}, rather than overriding the entire original contents.
+@var{tabname}, rather than overwriting the entire original contents.
(A subsequent call only overrides abbrevs explicitly redefined or
undefined in @var{definitions}.)
@end defun
@defun insert-abbrev-table-description name &optional human
This function inserts before point a description of the abbrev table
named @var{name}. The argument @var{name} is a symbol whose value is an
-abbrev table. The return value is always @code{nil}.
+abbrev table. @c The return value is always @code{nil}.
If @var{human} is non-@code{nil}, the description is human-oriented.
System abbrevs are listed and identified as such. Otherwise the
to add these to @var{name} separately.)
@end defun
-@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs
-@comment node-name, next, previous, up
+@node Defining Abbrevs
@section Defining Abbrevs
+@cindex defining abbrevs
+
@code{define-abbrev} is the low-level basic function for defining an
-abbrev in a specified abbrev table. When major modes predefine standard
-abbrevs, they should call @code{define-abbrev} and specify @code{t} for
-@var{system-flag}. Be aware that any saved non-``system'' abbrevs are
-restored at startup, i.e. before some major modes are loaded. Major modes
-should therefore not assume that when they are first loaded their abbrev
-tables are empty.
-
-@defun define-abbrev table name expansion &optional hook count system-flag
-This function defines an abbrev named @var{name}, in @var{table}, to
-expand to @var{expansion} and call @var{hook}. The return value is
-@var{name}.
-
-The value of @var{count}, if specified, initializes the abbrev's
-usage-count. If @var{count} is not specified or @code{nil}, the use
-count is initialized to zero.
-
-The argument @var{name} should be a string. The argument
-@var{expansion} is normally the desired expansion (a string), or
-@code{nil} to undefine the abbrev. If it is anything but a string or
-@code{nil}, then the abbreviation ``expands'' solely by running
-@var{hook}.
+abbrev in an abbrev table.
+
+ When a major mode defines a system abbrev, it should call
+@code{define-abbrev} and specify @code{t} for the @code{: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.
+
+@defun define-abbrev abbrev-table name expansion &optional hook &rest props
+This function defines an abbrev named @var{name}, in
+@var{abbrev-table}, to expand to @var{expansion} and call @var{hook},
+with properties @var{props} (@pxref{Abbrev Properties}). The return
+value is @var{name}. The @code{:system} property in @var{props} is
+treated specially here: if it has the value @code{force}, then it will
+overwrite an existing definition even for a non-system abbrev of
+the same name.
+
+@var{name} should be a string. The argument @var{expansion} is
+normally the desired expansion (a string), or @code{nil} to undefine
+the abbrev. If it is anything but a string or @code{nil}, then the
+abbreviation expands solely by running @var{hook}.
The argument @var{hook} is a function or @code{nil}. If @var{hook} is
non-@code{nil}, then it is called with no arguments after the abbrev is
to insert the self-inserting input character that triggered the
expansion. If @var{hook} returns non-@code{nil} in this case, that
inhibits insertion of the character. By contrast, if @var{hook}
-returns @code{nil}, @code{expand-abbrev} also returns @code{nil}, as
-if expansion had not really occurred.
-
-If @var{system-flag} is non-@code{nil}, that marks the abbrev as a
-``system'' abbrev with the @code{system-type} property. Unless
-@var{system-flag} has the value @code{force}, a ``system'' abbrev will
-not overwrite an existing definition for a non-``system'' abbrev of the
-same name.
+returns @code{nil}, @code{expand-abbrev} (or @code{abbrev-insert})
+also returns @code{nil}, as if expansion had not really occurred.
-Normally the function @code{define-abbrev} sets the variable
+Normally, @code{define-abbrev} sets the variable
@code{abbrevs-changed} to @code{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 won't be saved
-anyway.
+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.
@end defun
@defopt only-global-abbrevs
callers.
@end defopt
-@node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs
+@node Abbrev Files
@section Saving Abbrevs in Files
+@cindex save 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 @code{load} (@pxref{How Programs Do Loading}). However, the
function @code{quietly-read-abbrev-file} is provided as a more
-convenient interface.
+convenient interface. Emacs automatically calls this function at
+startup.
User-level facilities such as @code{save-some-buffers} can save
abbrevs in a file automatically, under the control of variables
This function reads abbrev definitions from a file named @var{filename},
previously written with @code{write-abbrev-file}. If @var{filename} is
omitted or @code{nil}, the file specified in @code{abbrev-file-name} is
-used. @code{save-abbrevs} is set to @code{t} so that changes will be
-saved.
+used.
-This function does not display any messages. It returns @code{nil}.
+As the name implies, this function does not display any messages.
+@c It returns @code{nil}.
@end defun
@defopt save-abbrevs
A non-@code{nil} value for @code{save-abbrevs} means that Emacs should
-offer the user to save abbrevs when files are saved. If the value is
-@code{silently}, Emacs saves the abbrevs without asking the user.
-@code{abbrev-file-name} specifies the file to save the abbrevs in.
+offer to save abbrevs (if any have changed) when files are saved. If
+the value is @code{silently}, Emacs saves the abbrevs without asking
+the user. @code{abbrev-file-name} specifies the file to save the
+abbrevs in.
@end defopt
@defvar abbrevs-changed
This variable is set non-@code{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.
+abbrevs (except system abbrevs). This serves as a flag for various
+Emacs commands to offer to save your abbrevs.
@end defvar
@deffn Command write-abbrev-file &optional filename
-Save all abbrev definitions (except ``system'' abbrevs), for all abbrev
+Save all abbrev definitions (except system abbrevs), for all abbrev
tables listed in @code{abbrev-table-name-list}, in the file
@var{filename}, in the form of a Lisp program that when loaded will
define the same abbrevs. If @var{filename} is @code{nil} or omitted,
@code{abbrev-file-name} is used. This function returns @code{nil}.
@end deffn
-@node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs
-@comment node-name, next, previous, up
+@node Abbrev Expansion
@section Looking Up and Expanding Abbreviations
+@cindex looking up abbrevs
+@cindex expanding abbrevs
+@cindex abbrevs, looking up and expanding
Abbrevs are usually expanded by certain interactive commands,
including @code{self-insert-command}. This section describes the
@defun abbrev-symbol abbrev &optional table
This function returns the symbol representing the abbrev named
-@var{abbrev}. The value returned is @code{nil} if that abbrev is not
+@var{abbrev}. It returns @code{nil} if that abbrev is not
defined. The optional second argument @var{table} is the abbrev table
-to look it up in. If @var{table} is @code{nil}, this function tries
-first the current buffer's local abbrev table, and second the global
-abbrev table.
+in which to look it up. If @var{table} is @code{nil}, this function
+tries first the current buffer's local abbrev table, and second the
+global abbrev table.
@end defun
@defun abbrev-expansion abbrev &optional table
This function returns the string that @var{abbrev} would expand into (as
-defined by the abbrev tables used for the current buffer). If
-@var{abbrev} is not a valid abbrev, the function returns @code{nil}.
+defined by the abbrev tables used for the current buffer). It returns
+@code{nil} if @var{abbrev} is not a valid abbrev.
The optional argument @var{table} specifies the abbrev table to use,
as in @code{abbrev-symbol}.
@end defun
@deffn Command expand-abbrev
This command expands the abbrev before point, if any. If point does not
-follow an abbrev, this command does nothing. The command returns the
-abbrev symbol if it did expansion, @code{nil} otherwise.
-
-If the abbrev symbol has a hook function which is a symbol whose
-@code{no-self-insert} property is non-@code{nil}, and if the hook
-function returns @code{nil} as its value, then @code{expand-abbrev}
-returns @code{nil} even though expansion did occur.
+follow an abbrev, this command does nothing. To do the expansion, it
+calls the function that is the value of the @code{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 @code{nil} otherwise. If the abbrev symbol has a hook
+function that is a symbol whose @code{no-self-insert} property is
+non-@code{nil}, and if the hook function returns @code{nil} as its
+value, then the default expansion function returns @code{nil},
+even though expansion did occur.
@end deffn
+@defun abbrev-insert abbrev &optional name start end
+This function inserts the abbrev expansion of @code{abbrev}, replacing
+the text between @code{start} and @code{end}. If @code{start} is
+omitted, it defaults to point. @code{name}, if non-@code{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 @code{abbrev} if the abbrev was successfully
+inserted.
+@end defun
+
@deffn Command abbrev-prefix-mark &optional arg
This command marks the current location of point as the beginning of
an abbrev. The next call to @code{expand-abbrev} will use the text
@code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command.
@end defvar
-@c Emacs 19 feature
-@defvar pre-abbrev-expand-hook
-This is a normal hook whose functions are executed, in sequence, just
-before any expansion of an abbrev. @xref{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.
-Running the hook is the first thing that @code{expand-abbrev} does, and
-so a hook function can be used to change the current abbrev table before
-abbrev lookup happens. (Although you have to do this carefully. See
-the example below.)
+@defvar abbrev-expand-function
+The value of this variable is a function that @code{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.
@end defvar
The following sample code shows a simple use of
-@code{pre-abbrev-expand-hook}. It assumes that @code{foo-mode} is a
+@code{abbrev-expand-function}. It assumes that @code{foo-mode} is a
mode for editing certain files in which lines that start with @samp{#}
are comments. You want to use Text mode abbrevs for those lines. The
regular local abbrev table, @code{foo-mode-abbrev-table} is
-appropriate for all other lines. Then you can put the following code
-in your @file{.emacs} file. @xref{Standard Abbrev Tables}, for the
+appropriate for all other lines. @xref{Standard Abbrev Tables}, for the
definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.
+@xref{Advising Functions}, for details of @code{add-function}.
@smallexample
-(defun foo-mode-pre-abbrev-expand ()
- (when (save-excursion (forward-line 0) (eq (char-after) ?#))
- (let ((local-abbrev-table text-mode-abbrev-table)
- ;; Avoid infinite loop.
- (pre-abbrev-expand-hook nil))
- (expand-abbrev))
- ;; We have already called `expand-abbrev' in this hook.
- ;; Hence we want the "actual" call following this hook to be a no-op.
- (setq abbrev-start-location (point-max)
- abbrev-start-location-buffer (current-buffer))))
+(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-hook 'pre-abbrev-expand-hook
- 'foo-mode-pre-abbrev-expand
- nil t)))
+ #'(lambda ()
+ (add-function :around (local 'abbrev-expand-function)
+ #'foo-mode-abbrev-expand-function)))
@end smallexample
-Note that @code{foo-mode-pre-abbrev-expand} just returns @code{nil}
-without doing anything for lines not starting with @samp{#}. Hence
-abbrevs expand normally using @code{foo-mode-abbrev-table} as local
-abbrev table for such lines.
-
-@node Standard Abbrev Tables, , Abbrev Expansion, Abbrevs
-@comment node-name, next, previous, up
+@node Standard Abbrev Tables
@section Standard Abbrev Tables
+@cindex standard abbrev tables
Here we list the variables that hold the abbrev tables for the
preloaded major modes of Emacs.
@defvar local-abbrev-table
The value of this buffer-local variable is the (mode-specific)
-abbreviation table of the current buffer.
+abbreviation table of the current buffer. It can also be a list of
+such tables.
+@end defvar
+
+@defvar abbrev-minor-mode-table-alist
+The value of this variable is a list of elements of the form
+@code{(@var{mode} . @var{abbrev-table})} where @var{mode} is the name
+of a variable: if the variable is bound to a non-@code{nil} value,
+then the @var{abbrev-table} is active, otherwise it is ignored.
+@var{abbrev-table} can also be a list of abbrev tables.
@end defvar
@defvar fundamental-mode-abbrev-table
@end defvar
@defvar lisp-mode-abbrev-table
-This is the local abbrev table used in Lisp mode and Emacs Lisp 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. @xref{Abbrev Table
+Properties}.
@end defvar
-@ignore
- arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec
-@end ignore
+@node Abbrev Properties
+@section Abbrev Properties
+@cindex abbrev properties
+
+Abbrevs have properties, some of which influence the way they work.
+You can provide them as arguments to @code{define-abbrev}, and
+manipulate them with the following functions:
+
+@defun abbrev-put abbrev prop val
+Set the property @var{prop} of @var{abbrev} to value @var{val}.
+@end defun
+
+@defun abbrev-get abbrev prop
+Return the property @var{prop} of @var{abbrev}, or @code{nil} if the
+abbrev has no such property.
+@end defun
+
+The following properties have special meanings:
+
+@table @code
+@item :count
+This property counts the number of times the abbrev has
+been expanded. If not explicitly set, it is initialized to 0 by
+@code{define-abbrev}.
+
+@item :system
+If non-@code{nil}, this property marks the abbrev as a system abbrev.
+Such abbrevs are not saved (@pxref{Abbrev Files}).
+
+@item :enable-function
+If non-@code{nil}, this property should be a function of no
+arguments which returns @code{nil} if the abbrev should not be used
+and @code{t} otherwise.
+
+@item :case-fixed
+If non-@code{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.
+@end table
+
+@node Abbrev Table Properties
+@section Abbrev Table Properties
+@cindex abbrev table properties
+
+Like abbrevs, abbrev tables have properties, some of which influence
+the way they work. You can provide them as arguments to
+@code{define-abbrev-table}, and manipulate them with the functions:
+
+@defun abbrev-table-put table prop val
+Set the property @var{prop} of abbrev table @var{table} to value @var{val}.
+@end defun
+
+@defun abbrev-table-get table prop
+Return the property @var{prop} of abbrev table @var{table}, or @code{nil}
+if the abbrev has no such property.
+@end defun
+
+The following properties have special meaning:
+
+@table @code
+@item :enable-function
+This is like the @code{: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.
+
+@item :case-fixed
+This is like the @code{:case-fixed} abbrev property except that it
+applies to all abbrevs in the table.
+
+@item :regexp
+If non-@code{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 @code{nil}, the default is to use
+@code{backward-word} and @code{forward-word} to find the name. This
+property allows the use of abbrevs whose name contains characters of
+non-word syntax.
+
+@item :parents
+This property holds a list of tables from which to inherit
+other abbrevs.
+
+@item :abbrev-table-modiff
+This property holds a counter incremented each time a new abbrev is
+added to the table.
+
+@end table