@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 See the file elisp.texi for copying conditions.@setfilename ../../info/abbrevs@node Abbrevs, Processes, Syntax Tables, Top@chapter Abbrevs and Abbrev Expansion@cindex abbrev@c @cindex abbrev table Redundant with "abbrev". 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 valueis the expansion; its function definition is the hook function to dothe expansion (@pxref{Defining Abbrevs}); its property list celltypically contains various additional properties such as the usecount, the number of times the abbreviation has been expanded, orwhether the abbrev is a so-called ``system'' abbrev defined by a majormode rather than by the user (@pxref{Abbrev Properties}).Because the symbols used for abbrevs are not interned in the usualobarray, they will never appear as the result of reading a Lispexpression; in fact, normally they are never used except by the codethat handles abbrevs. Therefore, it is safe to use them in anextremely 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.* 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-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-table &rest propsThis function creates and returns a new, empty abbrev table---an obarraycontaining 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 tableReturn non-@code{nil} is @var{table} is an abbrev table.@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 copy-abbrev-table tableThis function returns a copy of abbrev table @var{table}---a newabbrev table that contains the same abbrev definitions. The onlydifference between @var{table} and the returned copy is that thisfunction sets the property lists of all copied abbrevs to 0.@end defun@defun define-abbrev-table tabname definitions &optional docstring &rest propsThis function defines @var{tabname} (a symbol) as an abbrev tablename, i.e., as a variable whose value is an abbrev table. It definesabbrevs in the table according to @var{definitions}, a list ofelements of the form @code{(@var{abbrevname} @var{expansion}[@var{hook}] [@var{props}...])}. These elements are passed asarguments to @code{define-abbrev}. The return value is always@code{nil}.The optional string @var{docstring} is the documentation string of thevariable @var{tabname}. The property list @var{props} is applied tothe 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.(A subsequent call only overrides abbrevs explicitly redefined orundefined in @var{definitions}.)@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.System abbrevs are listed and identified as such. Otherwise thedescription is a Lisp expression---a call to @code{define-abbrev-table}that would define @var{name} as it is currently defined, but withoutthe system abbrevs. (The mode or package using @var{name} is supposedto add these to @var{name} separately.)@end defun@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs@comment node-name, next, previous, up@section Defining Abbrevs @code{define-abbrev} is the low-level basic function for defining anabbrev in a specified abbrev table. When major modes predefine standardabbrevs, they should call @code{define-abbrev} and specify a @code{t} forthe @code{:system} property.Be aware that any saved non-``system'' abbrevs are restored at startup, i.e. before some major modes are loaded. Major modesshould therefore not assume that when they are first loaded their abbrevtables are empty.@defun define-abbrev table name expansion &optional hook &rest propsThis function defines an abbrev named @var{name}, in @var{table}, toexpand 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 existingdefinition 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}.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.@cindex @code{no-self-insert} propertyIf @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert}property is non-@code{nil}, @var{hook} can explicitly control whetherto insert the self-inserting input character that triggered theexpansion. If @var{hook} returns non-@code{nil} in this case, thatinhibits insertion of the character. By contrast, if @var{hook}returns @code{nil}, @code{expand-abbrev} also returns @code{nil}, asif expansion had not really occurred.Normally the function @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.) Itdoes not do this for a ``system'' abbrev, since those won't be savedanyway.@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-abbrevs} means that Emacs shouldoffer 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.@end defopt@defvar abbrevs-changedThis variable is set non-@code{nil} by defining or altering anyabbrevs (except ``system'' abbrevs). This serves as a flag forvarious Emacs commands to offer to save your abbrevs.@end defvar@deffn Command write-abbrev-file &optional filenameSave all abbrev definitions (except ``system'' abbrevs), for all abbrevtables listed in @code{abbrev-table-name-list}, 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). If@var{abbrev} is not a valid abbrev, the function returns @code{nil}.The optional argument @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 argThis command marks the current location of point as the beginning ofan abbrev. The next call to @code{expand-abbrev} will use the textfrom here to point (where it is then) as the abbrev to expand, ratherthan using the previous word as usual.First, this command expands any abbrev before point, unless @var{arg}is non-@code{nil}. (Interactively, @var{arg} is the prefix argument.)Then it inserts a hyphen before point, to indicate the start of thenext abbrev to be expanded. The actual expansion removes the hyphen.@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-locationThe value of this variable is a buffer position (an integer or a marker)for @code{expand-abbrev} to use as the start of the next abbrev to beexpanded. The value can also be @code{nil}, which means to use theword before 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@defvar abbrev-expand-functionsThis is a special hook run @emph{around} the @code{expand-abbrev}function. Functions on this hook are called with a single argumentwhich is a function that performs the normal abbrev expansion.The hook function can hence do anything it wants before and afterperforming the expansion. It can also choose not to call its argumentand thus override the default behavior, or it may even call itseveral times. The function should return the abbrev symbol ifexpansion took place.@end defvar The following sample code shows a simple use of@code{abbrev-expand-functions}. It assumes that @code{foo-mode} is amode for editing certain files in which lines that start with @samp{#}are comments. You want to use Text mode abbrevs for those lines. Theregular local abbrev table, @code{foo-mode-abbrev-table} isappropriate for all other lines. Then you can put the following codein your @file{.emacs} file. @xref{Standard Abbrev Tables}, for thedefinitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.@smallexample(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 'abbrev-expand-functions 'foo-mode-abbrev-expand-function nil t)))@end smallexample@node Standard Abbrev Tables, Abbrev Properties, 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. It can also be a list ofsuch tables.@end defvar@defvar abbrev-minor-mode-table-alistThe value of this variable is a list of elements of the form@code{(@var{mode} . @var{abbrev-table})} where @var{mode} is the nameof 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-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@node Abbrev Properties, Abbrev Table Properties, Standard Abbrev Tables, Abbrevs@section Abbrev PropertiesAbbrevs have properties, some of which influence the way they work.You can provide them as arguments to @code{define-abbrev} and you canmanipulate them with the functions:@defun abbrev-put abbrev prop valSet the property @var{prop} of abbrev @var{abbrev} to value @var{val}.@end defun@defun abbrev-get abbrev propReturn the property @var{prop} of abbrev @var{abbrev}, or @code{nil}if the abbrev has no such property.@end defunThe following properties have special meaning:@table @code@item :countThis property counts the number of times the abbrev hasbeen expanded. If not explicitly set, it is initialized to 0 by@code{define-abbrev}.@item :systemIf non-@code{nil}, this property marks the abbrev as a ``system''abbrev. Such abbrevs will not be saved to @var{abbrev-file-name}.@item :enable-functionIf non-@code{nil}, this property should be a function of noarguments which returns @code{nil} if the abbrev should not be usedand @code{t} otherwise.@item :case-fixedIf non-@code{nil}, this property indicates that the case of theabbrev's name is significant and should only match a text with thesame pattern of capitalization. It also disables the code thatmodifies the capitalization of the expansion.@end table@node Abbrev Table Properties, , Abbrev Properties, Abbrevs@section Abbrev Table PropertiesLike abbrevs, abble tables have properties, some of which influencethe way they work. You can provide them as arguments to@code{define-abbrev-table} and you can manipulate them with thefunctions:@defun abbrev-table-put table prop valSet the property @var{prop} of abbrev table @var{table} to value @var{val}.@end defun@defun abbrev-table-get table propReturn the property @var{prop} of abbrev table @var{table}, or @code{nil}if the abbrev has no such property.@end defunThe following properties have special meaning:@table @code@item :enable-functionThis is like the @code{:enable-function} abbrev property except thatit applies to all abbrevs in the table and is used even before tryingto find the abbrev before point so it can dynamically modify theabbrev table.@item :case-fixedThis is like the @code{:case-fixed} abbrev property except that itapplies to all abbrevs in the table.@item :regexpIf non-@code{nil}, this property is a regular expression thatindicates how to extract the name of the abbrev before point beforelooking it up in the table. When the regular expression matchesbefore 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 abbrevswhose name contains characters of non-word syntax.@item :parentsThis property holds the list of tables from which to inheritother abbrevs.@item :abbrev-table-modiffThis property holds a counter incremented each time a new abbrev isadded to the table.@end table@ignore arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec@end ignore