@c This is part of the Emacs manual.@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, 2003,@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.@c See file emacs.texi for copying conditions.@node Abbrevs@chapter Abbrevs@cindex abbrevs@cindex expansion (of abbrevs) A defined @dfn{abbrev} is a word which @dfn{expands}, if you insertit, into some different text. Abbrevs are defined by the user to expandin specific ways. For example, you might define @samp{foo} as an abbrevexpanding to @samp{find outer otter}. Then you could insert@samp{find outer otter } into the buffer by typing @kbd{f o o@key{SPC}}. A second kind of abbreviation facility is called @dfn{dynamic abbrevexpansion}. You use dynamic abbrev expansion with an explicit commandto expand the letters in the buffer before point by looking for otherwords in the buffer that start with those letters. @xref{DynamicAbbrevs}. ``Hippie'' expansion generalizes abbreviation expansion.@xref{Hippie Expand, , Hippie Expansion, autotype, Features forAutomatic Typing}.@menu* Abbrev Concepts:: Fundamentals of defined abbrevs.* Defining Abbrevs:: Defining an abbrev, so it will expand when typed.* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.* Saving Abbrevs:: Saving the entire list of abbrevs for another session.* Dynamic Abbrevs:: Abbreviations for words already in the buffer.* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling.@end menu@node Abbrev Concepts@section Abbrev Concepts An @dfn{abbrev} is a word which has been defined to @dfn{expand} intoa specified @dfn{expansion}. When you insert a word-separator characterfollowing the abbrev, that expands the abbrev---replacing the abbrevwith its expansion. For example, if @samp{foo} is defined as an abbrevexpanding to @samp{find outer otter}, then you can insert @samp{findouter otter.} into the buffer by typing @kbd{f o o .}.@findex abbrev-mode@vindex abbrev-mode@cindex Abbrev mode@cindex mode, Abbrev Abbrevs expand only when Abbrev mode (a minor mode) is enabled.Disabling Abbrev mode does not cause abbrev definitions to be forgotten,but they do not expand until Abbrev mode is enabled again. The command@kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, itturns Abbrev mode on if the argument is positive, off otherwise.@xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode ison when the variable is non-@code{nil}. The variable @code{abbrev-mode}automatically becomes local to the current buffer when it is set. Abbrevs can have @dfn{mode-specific} definitions, active only in one majormode. Abbrevs can also have @dfn{global} definitions that are active inall major modes. The same abbrev can have a global definition and variousmode-specific definitions for different major modes. A mode-specificdefinition for the current major mode overrides a global definition. You can define abbrevs interactively during the editing session. Youcan also save lists of abbrev definitions in files for use in latersessions. Some users keep extensive lists of abbrevs that they loadin every session.@node Defining Abbrevs@section Defining Abbrevs@table @kbd@item C-x a gDefine an abbrev, using one or more words before point as its expansion(@code{add-global-abbrev}).@item C-x a lSimilar, but define an abbrev specific to the current major mode(@code{add-mode-abbrev}).@item C-x a i gDefine a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}).@item C-x a i lDefine a word in the buffer as a mode-specific abbrev(@code{inverse-add-mode-abbrev}).@item M-x define-global-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET}Define @var{abbrev} as an abbrev expanding into @var{exp}.@item M-x define-mode-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET}Define @var{abbrev} as a mode-specific abbrev expanding into @var{exp}.@item M-x kill-all-abbrevsDiscard all abbrev definitions, leaving a blank slate.@end table@kindex C-x a g@findex add-global-abbrev The usual way to define an abbrev is to enter the text you want theabbrev to expand to, position point after it, and type @kbd{C-x a g}(@code{add-global-abbrev}). This reads the abbrev itself using theminibuffer, and then defines it as an abbrev for one or more words beforepoint. Use a numeric argument to say how many words before point should betaken as the expansion. For example, to define the abbrev @samp{foo} asmentioned above, insert the text @samp{find outer otter} and then type@kbd{C-u 3 C-x a g f o o @key{RET}}. An argument of zero to @kbd{C-x a g} means to use the contents of theregion as the expansion of the abbrev being defined.@kindex C-x a l@findex add-mode-abbrev The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, butdefines a mode-specific abbrev. Mode-specific abbrevs are active only in aparticular major mode. @kbd{C-x a l} defines an abbrev for the major modein effect at the time @kbd{C-x a l} is typed. The arguments work the sameas for @kbd{C-x a g}.@kindex C-x a i g@findex inverse-add-global-abbrev@kindex C-x a i l@findex inverse-add-mode-abbrev If the abbrev text itself is already in the buffer, you can use thecommands @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and@kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) to define it as anabbrev by specify the expansion in the minibuffer. These commands arecalled ``inverse'' because they invert the meaning of the two textstrings they use (one from the buffer and one read with theminibuffer).@findex define-mode-abbrev@findex define-global-abbrev You can define an abbrev without inserting either the abbrev or itsexpansion in the buffer using the command @code{define-global-abbrev}.It reads two arguments---the abbrev, and its expansion. The command@code{define-mode-abbrev} does likewise for a mode-specific abbrev. To change the definition of an abbrev, just define a new definition.When the abbrev has a prior definition, the abbrev definition commandsask for confirmation before replacing it.@findex kill-all-abbrevs To remove an abbrev definition, give a negative argument to theabbrev definition command: @kbd{C-u - C-x a g} or @kbd{C-u - C-x a l}.The former removes a global definition, while the latter removes amode-specific definition. @kbd{M-x kill-all-abbrevs} removes allabbrev definitions, both global and local.@node Expanding Abbrevs@section Controlling Abbrev Expansion When Abbrev mode is enabled, an abbrev expands whenever it ispresent in the buffer just before point and you type a self-insertingwhitespace or punctuation character (@key{SPC}, comma, etc.@:). Moreprecisely, any character that is not a word constituent expands anabbrev, and any word-constituent character can be part of an abbrev.The most common way to use an abbrev is to insert it and then insert apunctuation or whitespace character to expand it.@vindex abbrev-all-caps Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{findouter otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into@samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to thevariable @code{abbrev-all-caps} (setting it non-@code{nil} specifies@samp{FIND OUTER OTTER}). These commands are used to control abbrev expansion:@table @kbd@item M-'Separate a prefix from a following abbrev to be expanded(@code{abbrev-prefix-mark}).@item C-x a e@findex expand-abbrevExpand the abbrev before point (@code{expand-abbrev}).This is effective even when Abbrev mode is not enabled.@item M-x expand-region-abbrevsExpand some or all abbrevs found in the region.@end table@kindex M-'@findex abbrev-prefix-mark You may wish to expand an abbrev and attach a prefix to the expansion;for example, if @samp{cnst} expands into @samp{construction}, you might wantto use it to enter @samp{reconstruction}. It does not work to type@kbd{recnst}, because that is not necessarily a defined abbrev. Whatyou can do is use the command @kbd{M-'} (@code{abbrev-prefix-mark}) inbetween the prefix @samp{re} and the abbrev @samp{cnst}. First, insert@samp{re}. Then type @kbd{M-'}; this inserts a hyphen in the buffer toindicate that it has done its work. Then insert the abbrev @samp{cnst};the buffer now contains @samp{re-cnst}. Now insert a non-word characterto expand the abbrev @samp{cnst} into @samp{construction}. Thisexpansion step also deletes the hyphen that indicated @kbd{M-'} had beenused. The result is the desired @samp{reconstruction}. If you actually want the text of the abbrev in the buffer, rather thanits expansion, you can accomplish this by inserting the followingpunctuation with @kbd{C-q}. Thus, @kbd{foo C-q ,} leaves @samp{foo,} inthe buffer, not expanding it.@findex unexpand-abbrev If you expand an abbrev by mistake, you can undo the expansion andbring back the abbrev itself by typing @kbd{C-_} to undo (@pxref{Undo}).This also undoes the insertion of the non-word character that expandedthe abbrev. If the result you want is the terminating non-wordcharacter plus the unexpanded abbrev, you must reinsert the terminatingcharacter, quoting it with @kbd{C-q}. You can also use the command@kbd{M-x unexpand-abbrev} to cancel the last expansion withoutdeleting the terminating character.@findex expand-region-abbrevs @kbd{M-x expand-region-abbrevs} searches through the region for definedabbrevs, and for each one found offers to replace it with its expansion.This command is useful if you have typed in text using abbrevs but forgotto turn on Abbrev mode first. It may also be useful together with aspecial set of abbrev definitions for making several global replacements atonce. This command is effective even if Abbrev mode is not enabled. Expanding any abbrev first runs the hook @code{pre-abbrev-expand-hook}(@pxref{Hooks}).@need 1500@node Editing Abbrevs@section Examining and Editing Abbrevs@table @kbd@item M-x list-abbrevsDisplay a list of all abbrev definitions. With a numeric argument, listonly local abbrevs.@item M-x edit-abbrevsEdit a list of abbrevs; you can add, alter or remove definitions.@end table@findex list-abbrevs The output from @kbd{M-x list-abbrevs} looks like this:@example@var{various other tables@dots{}}(lisp-mode-abbrev-table)"dk" 0 "define-key"(global-abbrev-table)"dfn" 0 "definition"@end example@noindent(Some blank lines of no semantic significance, and some other abbrevtables, have been omitted.) A line containing a name in parentheses is the header for abbrevs in aparticular abbrev table; @code{global-abbrev-table} contains all the globalabbrevs, and the other abbrev tables that are named after major modescontain the mode-specific abbrevs. Within each abbrev table, each nonblank line defines one abbrev. Theword at the beginning of the line is the abbrev. The number thatfollows is the number of times the abbrev has been expanded. Emacskeeps track of this to help you see which abbrevs you actually use, sothat you can eliminate those that you don't use often. The string atthe end of the line is the expansion. Some abbrevs are marked with @samp{(sys)}. These ``system'' abbrevs(@pxref{Abbrevs,,, elisp, The Emacs Lisp Reference Manual}) arepre-defined by various modes, and are not saved to your abbrev file.To disable a ``system'' abbrev, define an abbrev of the same name thatexpands to itself, and save it to your abbrev file.@findex edit-abbrevs@kindex C-c C-c @r{(Edit Abbrevs)} @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrevdefinitions by editing a list of them in an Emacs buffer. The list hasthe same format described above. The buffer of abbrevs is called@samp{*Abbrevs*}, and is in Edit-Abbrevs mode. Type @kbd{C-c C-c} inthis buffer to install the abbrev definitions as specified in thebuffer---and delete any abbrev definitions not listed. The command @code{edit-abbrevs} is actually the same as@code{list-abbrevs} except that it selects the buffer @samp{*Abbrevs*}whereas @code{list-abbrevs} merely displays it in another window.@node Saving Abbrevs@section Saving Abbrevs These commands allow you to keep abbrev definitions between editingsessions.@table @kbd@item M-x write-abbrev-file @key{RET} @var{file} @key{RET}Write a file @var{file} describing all defined abbrevs.@item M-x read-abbrev-file @key{RET} @var{file} @key{RET}Read the file @var{file} and define abbrevs as specified therein.@item M-x quietly-read-abbrev-file @key{RET} @var{file} @key{RET}Similar but do not display a message about what is going on.@item M-x define-abbrevsDefine abbrevs from definitions in current buffer.@item M-x insert-abbrevsInsert all abbrevs and their expansions into current buffer.@end table@findex write-abbrev-file @kbd{M-x write-abbrev-file} reads a file name using the minibuffer andthen writes a description of all current abbrev definitions into thatfile. This is used to save abbrev definitions for use in a latersession. The text stored in the file is a series of Lisp expressionsthat, when executed, define the same abbrevs that you currently have.@findex read-abbrev-file@findex quietly-read-abbrev-file@vindex abbrev-file-name @kbd{M-x read-abbrev-file} reads a file name using the minibufferand then reads the file, defining abbrevs according to the contents ofthe file. The function @code{quietly-read-abbrev-file} is similarexcept that it does not display a message in the echo area; you cannotinvoke it interactively, and it is used primarily in the @file{.emacs}file. If either of these functions is called with @code{nil} as theargument, it uses the file name specified in the variable@code{abbrev-file-name}, which is by default @code{"~/.abbrev_defs"}.That file is your standard abbrev definition file, and Emacs loadsabbrevs from it automatically when it starts up.@vindex save-abbrevs Emacs will offer to save abbrevs automatically if you have changedany of them, whenever it offers to save all files (for @kbd{C-x s} or@kbd{C-x C-c}). It saves them in the file specified by@code{abbrev-file-name}. This feature can be inhibited by setting thevariable @code{save-abbrevs} to @code{nil}.@findex insert-abbrevs@findex define-abbrevs The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} aresimilar to the previous commands but work on text in an Emacs buffer.@kbd{M-x insert-abbrevs} inserts text into the current buffer after point,describing all current abbrev definitions; @kbd{M-x define-abbrevs} parsesthe entire current buffer and defines abbrevs accordingly.@node Dynamic Abbrevs@section Dynamic Abbrev Expansion The abbrev facility described above operates automatically as youinsert text, but all abbrevs must be defined explicitly. By contrast,@dfn{dynamic abbrevs} allow the meanings of abbreviations to bedetermined automatically from the contents of the buffer, but dynamicabbrev expansion happens only when you request it explicitly.@kindex M-/@kindex C-M-/@findex dabbrev-expand@findex dabbrev-completion@table @kbd@item M-/Expand the word in the buffer before point as a @dfn{dynamic abbrev},by searching in the buffer for words starting with that abbreviation(@code{dabbrev-expand}).@item C-M-/Complete the word before point as a dynamic abbrev(@code{dabbrev-completion}).@end table@vindex dabbrev-limit For example, if the buffer contains @samp{does this follow } and youtype @kbd{f o M-/}, the effect is to insert @samp{follow} because thatis the last word in the buffer that starts with @samp{fo}. A numericargument to @kbd{M-/} says to take the second, third, etc.@: distinctexpansion found looking backward from point. Repeating @kbd{M-/}searches for an alternative expansion by looking farther back. Afterscanning all the text before point, it searches the text after point.The variable @code{dabbrev-limit}, if non-@code{nil}, specifies how faraway in the buffer to search for an expansion.@vindex dabbrev-check-all-buffers After scanning the current buffer, @kbd{M-/} normally searches otherbuffers, unless you have set @code{dabbrev-check-all-buffers} to@code{nil}.@vindex dabbrev-ignored-buffer-regexps For finer control over which buffers to scan, customize the variable@code{dabbrev-ignored-buffer-regexps}. Its value is a list of regularexpressions. If a buffer's name matches any of these regularexpressions, dynamic abbrev expansion skips that buffer. A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says tosearch first for expansions after point, then other buffers, andconsider expansions before point only as a last resort. If you repeatthe @kbd{M-/} to look for another expansion, do not specify anargument. Repeating @kbd{M-/} cycles through all the expansions afterpoint and then the expansions before point. After you have expanded a dynamic abbrev, you can copy additionalwords that follow the expansion in its original context. Simply type@kbd{@key{SPC} M-/} for each additional word you want to copy. Thespacing and punctuation between words is copied along with the words. The command @kbd{C-M-/} (@code{dabbrev-completion}) performscompletion of a dynamic abbrev. Instead of trying the possibleexpansions one by one, it finds all of them, then inserts the textthat they have in common. If they have nothing in common, @kbd{C-M-/}displays a list of completions, from which you can select a choice inthe usual manner. @xref{Completion}. Dynamic abbrev expansion is completely independent of Abbrev mode; theexpansion of a word with @kbd{M-/} is completely independent of whetherit has a definition as an ordinary abbrev.@node Dabbrev Customization@section Customizing Dynamic Abbreviation Normally, dynamic abbrev expansion ignores case when searching forexpansions. That is, the expansion need not agree in case with the wordyou are expanding.@vindex dabbrev-case-fold-search This feature is controlled by the variable@code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored inthis search; if it is @code{nil}, the word and the expansion must matchin case. If the value of @code{dabbrev-case-fold-search} is@code{case-fold-search}, which is true by default, then the variable@code{case-fold-search} controls whether to ignore case while searchingfor expansions.@vindex dabbrev-case-replace Normally, dynamic abbrev expansion preserves the case pattern@emph{of the dynamic abbrev you are expanding}, by converting theexpansion to that case pattern.@vindex dabbrev-case-fold-search The variable @code{dabbrev-case-replace} controls whether topreserve the case pattern of the dynamic abbrev. If it is @code{t},the dynamic abbrev's case pattern is preserved in most cases; if it is@code{nil}, the expansion is always copied verbatim. If the value of@code{dabbrev-case-replace} is @code{case-replace}, which is true bydefault, then the variable @code{case-replace} controls whether tocopy the expansion verbatim. However, if the expansion contains a complex mixed case pattern, andthe dynamic abbrev matches this pattern as far as it goes, then theexpansion is always copied verbatim, regardless of those variables.Thus, for example, if the buffer contains@code{variableWithSillyCasePattern}, and you type @kbd{v a M-/}, itcopies the expansion verbatim including its case pattern.@vindex dabbrev-abbrev-char-regexp The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil},controls which characters are considered part of a word, for dynamic expansionpurposes. The regular expression must match just one character, nevertwo or more. The same regular expression also determines whichcharacters are part of an expansion. The value @code{nil} has a specialmeaning: dynamic abbrevs are made of word characters, but expansions aremade of word and symbol characters.@vindex dabbrev-abbrev-skip-leading-regexp In shell scripts and makefiles, a variable name is sometimes prefixedwith @samp{$} and sometimes not. Major modes for this kind of text cancustomize dynamic abbrev expansion to handle optional prefixes by settingthe variable @code{dabbrev-abbrev-skip-leading-regexp}. Its valueshould be a regular expression that matches the optional prefix thatdynamic abbrev expression should ignore.@ignore arch-tag: 638e0079-9540-48ec-9166-414083e16445@end ignore