@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, 2008 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 various additional properties such as the use
-count, the number of times the abbreviation has been expanded, or
-whether the abbrev is a so-called ``system'' abbrev defined by a major
-mode rather than by the user (@pxref{Abbrev Properties}).
-
-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.
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 &rest 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
+@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 table
-Return non-@code{nil} is @var{table} is an abbrev table.
+@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 &optional docstring &rest props
abbrevs in the table according to @var{definitions}, a list of
elements of the form @code{(@var{abbrevname} @var{expansion}
[@var{hook}] [@var{props}...])}. These elements are passed as
-arguments to @code{define-abbrev}. The return value is always
-@code{nil}.
+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
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 a @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. 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 &rest props
-This function defines an abbrev named @var{name}, in @var{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.
-
-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.
+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
-@defvar abbrev-expand-functions
-This is a special hook run @emph{around} the @code{expand-abbrev}
-function. Functions on this hook are called with a single argument
-which is a function that performs the normal abbrev expansion.
-The hook function can hence do anything it wants before and after
-performing the expansion. It can also choose not to call its argument
-and thus override the default behavior, or it may even call it
-several times. The function should return the abbrev symbol if
-expansion took place.
+@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{abbrev-expand-functions}. 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-abbrev-expand-function (expand)
(funcall expand))))
(add-hook 'foo-mode-hook
- #'(lambda ()
- (add-hook 'abbrev-expand-functions
- 'foo-mode-abbrev-expand-function
- nil t)))
+ #'(lambda ()
+ (add-function :around (local 'abbrev-expand-function)
+ #'foo-mode-abbrev-expand-function)))
@end smallexample
-@node Standard Abbrev Tables, Abbrev Properties, 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.
@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
-@node Abbrev Properties, Abbrev Table Properties, Standard Abbrev Tables, Abbrevs
+@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 you can
-manipulate them with the functions:
+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 abbrev @var{abbrev} to value @var{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 abbrev @var{abbrev}, or @code{nil}
-if the abbrev has no such property.
+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 meaning:
+The following properties have special meanings:
@table @code
@item :count
@code{define-abbrev}.
@item :system
-If non-@code{nil}, this property marks the abbrev as a ``system''
-abbrev. Such abbrevs will not be saved to @var{abbrev-file-name}.
+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
modifies the capitalization of the expansion.
@end table
-@node Abbrev Table Properties, , Abbrev Properties, Abbrevs
+@node Abbrev Table Properties
@section Abbrev Table Properties
+@cindex abbrev table properties
-Like abbrevs, abble tables have properties, some of which influence
+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 you can manipulate them with the
-functions:
+@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}.
@table @code
@item :enable-function
This is like the @code{:enable-function} abbrev property except that
-it applies to all abbrevs in the table and is used even before trying
-to find the abbrev before point so it can dynamically modify the
+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
@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
+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}, @code{expand-function} defaults to
-@code{"\\<\\(\\w+\\)\\W"}. This property allows the use of abbrevs
-whose name contains characters of non-word syntax.
+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 the list of tables from which to inherit
+This property holds a list of tables from which to inherit
other abbrevs.
@item :abbrev-table-modiff
added to the table.
@end table
-
-
-@ignore
- arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec
-@end ignore