@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions.@setfilename ../info/abbrevs@node Abbrevs, Processes, Syntax Tables, Top@chapter Abbrevs and Abbrev Expansion@cindex abbrev@cindex abbrev table An abbreviation or @dfn{abbrev} is a string of characters that may beexpanded to a longer string. The user can insert the abbrev string andfind it replaced automatically with the expansion of the abbrev. Thissaves typing. The set of abbrevs currently in effect is recorded in an @dfn{abbrevtable}. Each buffer has a local abbrev table, but normally all buffersin the same major mode share one abbrev table. There is also a globalabbrev table. Normally both are used. An abbrev table is represented as an obarray containing a symbol foreach abbreviation. The symbol's name is the abbreviation; its value isthe expansion; its function definition is the hook function to do theexpansion (@pxref{Defining Abbrevs}); its property list cell containsthe use count, the number of times the abbreviation has been expanded.Because these symbols are not interned in the usual obarray, they willnever 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}. For the user-level commands for abbrevs, see @ref{Abbrevs,, AbbrevMode, 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.@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-modeA non-@code{nil} value of this variable turns on the automatic expansionof abbrevs when their abbreviations are inserted into a buffer.If the value is @code{nil}, abbrevs may be defined, but they are notexpanded automatically.This variable automatically becomes buffer-local when set in any fashion.@end defvar@defvar default-abbrev-modeThis 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@section Abbrev Tables This section describes how to create and manipulate abbrev tables.@defun make-abbrev-tableThis function creates and returns a new, empty abbrev table---an obarraycontaining no symbols. It is a vector filled with zeros.@end defun@defun clear-abbrev-table tableThis function undefines all the abbrevs in abbrev table @var{table},leaving it empty. It always returns @code{nil}.@end defun@defun define-abbrev-table tabname definitionsThis function defines @var{tabname} (a symbol) as an abbrev table name,i.e., as a variable whose value is an abbrev table. It defines abbrevsin the table according to @var{definitions}, a list of elements of theform @code{(@var{abbrevname} @var{expansion} @var{hook}@var{usecount})}. The return value is always @code{nil}.@end defun@defvar abbrev-table-name-listThis is a list of symbols whose values are abbrev tables.@code{define-abbrev-table} adds the new abbrev table name to this list.@end defvar@defun insert-abbrev-table-description name &optional humanThis function inserts before point a description of the abbrev tablenamed @var{name}. The argument @var{name} is a symbol whose value is anabbrev table. The return value is always @code{nil}.If @var{human} is non-@code{nil}, the description is human-oriented.Otherwise the description is a Lisp expression---a call to@code{define-abbrev-table} that would define @var{name} exactly as itis currently defined.@end defun@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs@comment node-name, next, previous, up@section Defining Abbrevs These functions define an abbrev in a specified abbrev table.@code{define-abbrev} is the low-level basic function, while@code{add-abbrev} is used by commands that ask for information from theuser.@defun add-abbrev table type argThis function adds an abbreviation to abbrev table @var{table} based oninformation from the user. The argument @var{type} is a stringdescribing in English the kind of abbrev this will be (typically,@code{"global"} or @code{"mode-specific"}); this is used in promptingthe user. The argument @var{arg} is the number of words in theexpansion.The return value is the symbol that internally represents the newabbrev, or @code{nil} if the user declines to confirm redefining anexisting abbrev.@end defun@defun define-abbrev table name expansion &optional hook countThis function defines an abbrev named @var{name}, in @var{table}, toexpand to @var{expansion} and call @var{hook}. 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 initializedto zero. The return value is a symbol that represents the abbrev insideEmacs; its name is @var{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}.The argument @var{hook} is a function or @code{nil}. If @var{hook} isnon-@code{nil}, then it is called with no arguments after the abbrev isreplaced with @var{expansion}; point is located at the end of@var{expansion} when @var{hook} is called.If @var{hook} is a non-nil symbol whose @code{no-self-insert} propertyis non-@code{nil}, @var{hook} can explicitly control whether to insertthe self-inserting input character that triggered the expansion. If@var{hook} returns non-@code{nil} in this case, that inhibits insertionof the character. By contrast, if @var{hook} returns @code{nil},@code{expand-abbrev} also returns @code{nil}, as if expansion had notreally occurred.@end defun@defopt only-global-abbrevsIf this variable is non-@code{nil}, it means that the user plans to useglobal abbrevs only. This tells the commands that define mode-specificabbrevs to define global ones instead. This variable does not alter thebehavior of the functions in this section; it is examined by theircallers.@end defopt@node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs@section 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 sameabbrev tables with the same contents. Therefore, you can load the filewith @code{load} (@pxref{How Programs Do Loading}). However, thefunction @code{quietly-read-abbrev-file} is provided as a moreconvenient interface. User-level facilities such as @code{save-some-buffers} can saveabbrevs in a file automatically, under the control of variablesdescribed here.@defopt abbrev-file-nameThis is the default file name for reading and saving abbrevs.@end defopt@defun quietly-read-abbrev-file &optional filenameThis function reads abbrev definitions from a file named @var{filename},previously written with @code{write-abbrev-file}. If @var{filename} isomitted or @code{nil}, the file specified in @code{abbrev-file-name} isused. @code{save-abbrevs} is set to @code{t} so that changes will besaved.This function does not display any messages. It returns @code{nil}.@end defun@defopt save-abbrevsA non-@code{nil} value for @code{save-abbrev} means that Emacs shouldsave abbrevs when files are saved. @code{abbrev-file-name} specifiesthe file to save the abbrevs in.@end defopt@defvar abbrevs-changedThis variable is set non-@code{nil} by defining or altering any abbrevs. This serves as a flag for various Emacs commands to offer tosave your abbrevs.@end defvar@deffn Command write-abbrev-file &optional filenameSave all abbrev definitions, in all abbrev tables, in the file@var{filename}, in the form of a Lisp program that when loaded willdefine 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@section Looking Up and Expanding Abbreviations Abbrevs are usually expanded by certain interactive commands,including @code{self-insert-command}. This section describes thesubroutines used in writing such commands, as well as the variables theyuse for communication.@defun abbrev-symbol abbrev &optional tableThis function returns the symbol representing the abbrev named@var{abbrev}. The value returned is @code{nil} if that abbrev is notdefined. The optional second argument @var{table} is the abbrev tableto look it up in. If @var{table} is @code{nil}, this function triesfirst the current buffer's local abbrev table, and second the globalabbrev table.@end defun@defun abbrev-expansion abbrev &optional tableThis function returns the string that @var{abbrev} would expand into (asdefined by the abbrev tables used for the current buffer). The optionalargument @var{table} specifies the abbrev table to use, as in@code{abbrev-symbol}.@end defun@deffn Command expand-abbrevThis command expands the abbrev before point, if any. If point does notfollow an abbrev, this command does nothing. The command returns theabbrev 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 hookfunction returns @code{nil} as its value, then @code{expand-abbrev}returns @code{nil} even though expansion did occur.@end deffn@deffn Command abbrev-prefix-mark &optional argMark current point as the beginning of an abbrev. The next call to@code{expand-abbrev} will use the text from here to point (where it isthen) as the abbrev to expand, rather than using the previous word asusual.@end deffn@defopt abbrev-all-capsWhen this is set non-@code{nil}, an abbrev entered entirely in uppercase is expanded using all upper case. Otherwise, an abbrev enteredentirely in upper case is expanded by capitalizing each word of theexpansion.@end defopt@defvar abbrev-start-locationThis is the buffer position for @code{expand-abbrev} to use as the startof the next abbrev to be expanded. (@code{nil} means use the wordbefore point instead.) @code{abbrev-start-location} is set to@code{nil} each time @code{expand-abbrev} is called. This variable isalso set by @code{abbrev-prefix-mark}.@end defvar@defvar abbrev-start-location-bufferThe value of this variable is the buffer for which@code{abbrev-start-location} has been set. Trying to expand an abbrevin any other buffer clears @code{abbrev-start-location}. This variableis set by @code{abbrev-prefix-mark}.@end defvar@defvar last-abbrevThis is the @code{abbrev-symbol} of the most recent abbrev expanded. Thisinformation is left by @code{expand-abbrev} for the sake of the@code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, ExpandingAbbrevs, emacs, The GNU Emacs Manual}).@end defvar@defvar last-abbrev-locationThis is the location of the most recent abbrev expanded. This containsinformation left by @code{expand-abbrev} for the sake of the@code{unexpand-abbrev} command.@end defvar@defvar last-abbrev-textThis is the exact expansion text of the most recent abbrev expanded,after case conversion (if any). Its value is @code{nil} if the abbrevhas already been unexpanded. This contains information left by@code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command.@end defvar@c Emacs 19 feature@defvar pre-abbrev-expand-hookThis is a normal hook whose functions are executed, in sequence, justbefore any expansion of an abbrev. @xref{Hooks}. Since it is a normalhook, the hook functions receive no arguments. However, they can findthe abbrev to be expanded by looking in the buffer before point.Running the hook is the first thing that @code{expand-abbrev} does, andso a hook function can be used to change the current abbrev table beforeabbrev lookup happens.@end defvar The following sample code shows a simple use of@code{pre-abbrev-expand-hook}. If the user terminates an abbrev with apunctuation character, the hook function asks for confirmation. Thus,this hook allows the user to decide whether to expand the abbrev, andaborts expansion if it is not confirmed.@smallexample(add-hook 'pre-abbrev-expand-hook 'query-if-not-space);; @r{This is the function invoked by @code{pre-abbrev-expand-hook}.};; @r{If the user terminated the abbrev with a space, the function does};; @r{nothing (that is, it returns so that the abbrev can expand). If the};; @r{user entered some other character, this function asks whether};; @r{expansion should continue.};; @r{If the user answers the prompt with @kbd{y}, the function returns};; @r{@code{nil} (because of the @code{not} function), but that is};; @r{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"))))@end smallexample@node Standard Abbrev Tables, , Abbrev Expansion, Abbrevs@comment node-name, next, previous, up@section Standard Abbrev Tables Here we list the variables that hold the abbrev tables for thepreloaded major modes of Emacs.@defvar global-abbrev-tableThis is the abbrev table for mode-independent abbrevs. The abbrevsdefined in it apply to all buffers. Each buffer may also have a localabbrev table, whose abbrev definitions take precedence over those in theglobal table.@end defvar@defvar local-abbrev-tableThe value of this buffer-local variable is the (mode-specific)abbreviation table of the current buffer.@end defvar@defvar fundamental-mode-abbrev-tableThis is the local abbrev table used in Fundamental mode; in other words,it is the local abbrev table in all buffers in Fundamental mode.@end defvar@defvar text-mode-abbrev-tableThis is the local abbrev table used in Text mode.@end defvar@defvar lisp-mode-abbrev-tableThis is the local abbrev table used in Lisp mode and Emacs Lisp mode.@end defvar