"Fossies" - the Fresh Open Source Software Archive

Member "emacs-26.1/doc/emacs/abbrevs.texi" (23 Apr 2018, 21275 Bytes) of package /linux/misc/emacs-26.1.tar.xz:

Caution: As a special service "Fossies" has tried to format the requested Texinfo source page into HTML format but that may be not always succeeeded perfectly. Alternatively you can here view or download the uninterpreted Texinfo source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "abbrevs.texi": 25.3_vs_26.1.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Abbrevs

A defined abbrev is a word which expands, if you insert it, into some different text. Abbrevs are defined by the user to expand in specific ways. For example, you might define ‘foo’ as an abbrev expanding to ‘find outer otter’. Then you could insert ‘find outer otter ’ into the buffer by typing f o o <SPC>.

A second kind of abbreviation facility is called dynamic abbrev expansion. You use dynamic abbrev expansion with an explicit command to expand the letters in the buffer before point by looking for other words in the buffer that start with those letters. See section Dynamic Abbrev Expansion.

A third kind, hippie expansion, generalizes abbreviation expansion. See Hippie Expansion in Features for Automatic Typing.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Abbrev Concepts

An abbrev is a word that has been defined to expand into a specified expansion. When you insert a word-separator character following the abbrev, that expands the abbrev—replacing the abbrev with its expansion. For example, if ‘foo’ is defined as an abbrev expanding to ‘find outer otter’, then typing f o o . will insert ‘find outer otter.’.

Abbrevs expand only when Abbrev mode, a buffer-local 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 M-x abbrev-mode toggles Abbrev mode; with a numeric argument, it turns Abbrev mode on if the argument is positive, off otherwise. @xref{Minor Modes}.

Abbrevs can have mode-specific definitions, active only in one major mode. Abbrevs can also have global definitions that are active in all major modes. The same abbrev can have a global definition and various mode-specific definitions for different major modes. A mode-specific definition for the current major mode overrides a global definition.

You can define abbrevs interactively during the editing session, irrespective of whether Abbrev mode is enabled. You can also save lists of abbrev definitions in files, which you can then reload for use in later sessions.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Defining Abbrevs

C-x a g

Define an abbrev, using one or more words before point as its expansion (add-global-abbrev).

C-x a l

Similar, but define an abbrev specific to the current major mode (add-mode-abbrev).

C-x a i g

Define a word in the buffer as an abbrev (inverse-add-global-abbrev).

C-x a i l

Define a word in the buffer as a mode-specific abbrev (inverse-add-mode-abbrev).

M-x define-global-abbrev <RET> abbrev <RET> exp <RET>

Define abbrev as an abbrev expanding into exp.

M-x define-mode-abbrev <RET> abbrev <RET> exp <RET>

Define abbrev as a mode-specific abbrev expanding into exp.

M-x kill-all-abbrevs

Discard all abbrev definitions, leaving a blank slate.

The usual way to define an abbrev is to enter the text you want the abbrev to expand to, position point after it, and type C-x a g (add-global-abbrev). This reads the abbrev itself using the minibuffer, and then defines it as an abbrev for one or more words before point. Use a numeric argument to say how many words before point should be taken as the expansion. For example, to define the abbrev ‘foo’ as mentioned above, insert the text ‘find outer otter’ and then type C-u 3 C-x a g f o o <RET>.

An argument of zero to C-x a g means to use the contents of the region as the expansion of the abbrev being defined.

The command C-x a l (add-mode-abbrev) is similar, but defines a mode-specific abbrev for the current major mode. The arguments work the same as for C-x a g.

C-x a i g (inverse-add-global-abbrev) and C-x a i l (inverse-add-mode-abbrev) perform the opposite task: if the abbrev text is already in the buffer, you use these commands to define an abbrev by specifying the expansion in the minibuffer. These commands will expand the abbrev text used for the definition.

You can define an abbrev without inserting either the abbrev or its expansion in the buffer using the command define-global-abbrev. It reads two arguments—the abbrev, and its expansion. The command define-mode-abbrev does likewise for a mode-specific abbrev.

To change the definition of an abbrev, just make a new definition. When an abbrev has a prior definition, the abbrev definition commands ask for confirmation before replacing it.

To remove an abbrev definition, give a negative argument to the abbrev definition command: C-u - C-x a g or C-u - C-x a l. The former removes a global definition, while the latter removes a mode-specific definition. M-x kill-all-abbrevs removes all abbrev definitions, both global and local.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Controlling Abbrev Expansion

When Abbrev mode is enabled, an abbrev expands whenever it is present in the buffer just before point and you type a self-inserting whitespace or punctuation character (<SPC>, comma, etc.). More precisely, any character that is not a word constituent expands an abbrev, 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 a punctuation or whitespace character to expand it.

Abbrev expansion preserves case: ‘foo’ expands to ‘find outer otter’, and ‘Foo’ to ‘Find outer otter’. ‘FOO’ expands to ‘Find Outer Otter’ by default, but if you change the variable abbrev-all-caps to a non-nil value, it expands to ‘FIND OUTER OTTER’.

These commands are used to control abbrev expansion:


Separate a prefix from a following abbrev to be expanded (abbrev-prefix-mark).

C-x a e

Expand the abbrev before point (expand-abbrev). This is effective even when Abbrev mode is not enabled.

M-x unexpand-abbrev

Undo the expansion of the last expanded abbrev.

M-x expand-region-abbrevs

Expand some or all abbrevs found in the region.

You may wish to expand an abbrev and attach a prefix to the expansion; for example, if ‘cnst’ expands into ‘construction’, you might want to use it to enter ‘reconstruction’. It does not work to type recnst, because that is not necessarily a defined abbrev. What you can do is use the command M-' (abbrev-prefix-mark) in between the prefix ‘re’ and the abbrev ‘cnst’. First, insert ‘re’. Then type M-'; this inserts a hyphen in the buffer to indicate that it has done its work. Then insert the abbrev ‘cnst’; the buffer now contains ‘re-cnst’. Now insert a non-word character to expand the abbrev ‘cnst’ into ‘construction’. This expansion step also deletes the hyphen that indicated M-' had been used. The result is the desired ‘reconstruction’.

If you actually want the text of the abbrev in the buffer, rather than its expansion, you can accomplish this by inserting the following punctuation with C-q. Thus, foo C-q , leaves ‘foo,’ in the buffer, not expanding it.

If you expand an abbrev by mistake, you can undo the expansion by typing C-/ (undo). @xref{Undo}. This undoes the insertion of the abbrev expansion and brings back the abbrev text. If the result you want is the terminating non-word character plus the unexpanded abbrev, you must reinsert the terminating character, quoting it with C-q. You can also use the command M-x unexpand-abbrev to cancel the last expansion without deleting the terminating character.

M-x expand-region-abbrevs searches through the region for defined abbrevs, 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 forgot to turn on Abbrev mode first. It may also be useful together with a special set of abbrev definitions for making several global replacements at once. This command is effective even if Abbrev mode is not enabled.

The function expand-abbrev performs the expansion by calling the function that abbrev-expand-function specifies. By changing this function you can make arbitrary changes to the abbrev expansion. See Abbrev Expansion in The Emacs Lisp Reference Manual.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 Examining and Editing Abbrevs

M-x list-abbrevs

Display a list of all abbrev definitions. With a numeric argument, list only local abbrevs.

M-x edit-abbrevs

Edit a list of abbrevs; you can add, alter or remove definitions.

The output from M-x list-abbrevs looks like this:

various other tables…
"dk"          0    "define-key"
"dfn"         0    "definition"

(Some blank lines of no semantic significance, and some other abbrev tables, have been omitted.)

A line containing a name in parentheses is the header for abbrevs in a particular abbrev table; global-abbrev-table contains all the global abbrevs, and the other abbrev tables that are named after major modes contain the mode-specific abbrevs.

Within each abbrev table, each nonblank line defines one abbrev. The word at the beginning of the line is the abbrev. The number that follows is the number of times the abbrev has been expanded. Emacs keeps track of this to help you see which abbrevs you actually use, so that you can eliminate those that you don’t use often. The string at the end of the line is the expansion.

Some abbrevs are marked with ‘(sys)’. These system abbrevs (see Abbrevs in The Emacs Lisp Reference Manual) are pre-defined by various modes, and are not saved to your abbrev file. To disable a system abbrev, define an abbrev of the same name that expands to itself, and save it to your abbrev file.

M-x edit-abbrevs allows you to add, change or kill abbrev definitions by editing a list of them in an Emacs buffer. The list has the same format described above. The buffer of abbrevs is called ‘*Abbrevs*’, and is in Edit-Abbrevs mode. Type C-c C-c in this buffer to install the abbrev definitions as specified in the buffer—and delete any abbrev definitions not listed.

The command edit-abbrevs is actually the same as list-abbrevs except that it selects the buffer ‘*Abbrevs*’ whereas list-abbrevs merely displays it in another window.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 Saving Abbrevs

These commands allow you to keep abbrev definitions between editing sessions.

M-x write-abbrev-file <RET> file <RET>

Write a file file describing all defined abbrevs.

M-x read-abbrev-file <RET> file <RET>

Read the file file and define abbrevs as specified therein.

M-x define-abbrevs

Define abbrevs from definitions in current buffer.

M-x insert-abbrevs

Insert all abbrevs and their expansions into current buffer.

M-x write-abbrev-file reads a file name using the minibuffer and then writes a description of all current abbrev definitions into that file. This is used to save abbrev definitions for use in a later session. The text stored in the file is a series of Lisp expressions that, when executed, define the same abbrevs that you currently have.

M-x read-abbrev-file reads a file name using the minibuffer and then reads the file, defining abbrevs according to the contents of the file. The function quietly-read-abbrev-file is similar except that it does not display a message in the echo area; you cannot invoke it interactively, and it is used primarily in your init file (@pxref{Init File}). If either of these functions is called with nil as the argument, it uses the file given by the variable abbrev-file-name, which is ‘~/.emacs.d/abbrev_defs’ by default. This is your standard abbrev definition file, and Emacs loads abbrevs from it automatically when it starts up. (As an exception, Emacs does not load the abbrev file when it is started in batch mode. @xref{Initial Options}, for a description of batch mode.)

Emacs will offer to save abbrevs automatically if you have changed any of them, whenever it offers to save all files (for C-x s or C-x C-c). It saves them in the file specified by abbrev-file-name. This feature can be inhibited by setting the variable save-abbrevs to nil; setting it to silently will save the abbrevs automatically without asking.

The commands M-x insert-abbrevs and M-x define-abbrevs are similar to the previous commands but work on text in an Emacs buffer. M-x insert-abbrevs inserts text into the current buffer after point, describing all current abbrev definitions; M-x define-abbrevs parses the entire current buffer and defines abbrevs accordingly.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6 Dynamic Abbrev Expansion

The abbrev facility described above operates automatically as you insert text, but all abbrevs must be defined explicitly. By contrast, dynamic abbrevs allow the meanings of abbreviations to be determined automatically from the contents of the buffer, but dynamic abbrev expansion happens only when you request it explicitly.


Expand the word in the buffer before point as a dynamic abbrev, by searching for words starting with that abbreviation (dabbrev-expand).


Complete the word before point as a dynamic abbrev (dabbrev-completion).

For example, if the buffer contains ‘does this follow ’ and you type f o M-/, the effect is to insert ‘follow’ because that is the last word in the buffer that starts with ‘fo’. A numeric argument to M-/ says to take the second, third, etc. distinct expansion found looking backward from point. Repeating M-/ searches for an alternative expansion by looking farther back. After scanning all the text before point, it searches the text after point. The variable dabbrev-limit, if non-nil, specifies how far away in the buffer to search for an expansion.

After scanning the current buffer, M-/ normally searches other buffers. The variables dabbrev-check-all-buffers and dabbrev-check-other-buffers can be used to determine which other buffers, if any, are searched.

For finer control over which buffers to scan, customize the variables dabbrev-ignored-buffer-names and dabbrev-ignored-buffer-regexps. The value of the former is a list of buffer names to skip. The value of the latter is a list of regular expressions; if a buffer’s name matches any of these regular expressions, dynamic abbrev expansion skips that buffer.

A negative argument to M-/, as in C-u - M-/, says to search first for expansions after point, then other buffers, and consider expansions before point only as a last resort. If you repeat the M-/ to look for another expansion, do not specify an argument. Repeating M-/ cycles through all the expansions after point and then the expansions before point.

After you have expanded a dynamic abbrev, you can copy additional words that follow the expansion in its original context. Simply type <SPC> M-/ for each additional word you want to copy. The spacing and punctuation between words is copied along with the words.

You can control the way M-/ determines the word to expand and how to expand it, see Customizing Dynamic Abbreviation.

The command C-M-/ (dabbrev-completion) performs completion of a dynamic abbrev. Instead of trying the possible expansions one by one, it finds all of them, then inserts the text that they have in common. If they have nothing in common, C-M-/ displays a list of completions, from which you can select a choice in the usual manner. @xref{Completion}.

Dynamic abbrev expansion is completely independent of Abbrev mode; the expansion of a word with M-/ is completely independent of whether it has a definition as an ordinary abbrev.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7 Customizing Dynamic Abbreviation

Normally, dynamic abbrev expansion ignores case when searching for expansions. That is, the expansion need not agree in case with the word you are expanding.

This feature is controlled by the variable dabbrev-case-fold-search. If it is t, case is ignored in this search; if it is nil, the word and the expansion must match in case. If the value is case-fold-search (the default), then the variable case-fold-search controls whether to ignore case while searching for expansions (@pxref{Lax Search}).

Normally, dynamic abbrev expansion preserves the case pattern of the dynamic abbrev you are expanding, by converting the expansion to that case pattern.

The variable dabbrev-case-replace controls whether to preserve the case pattern of the dynamic abbrev. If it is t, the dynamic abbrev’s case pattern is preserved in most cases; if it is nil, the expansion is always copied verbatim. If the value is case-replace (the default), then the variable case-replace controls whether to copy the expansion verbatim (@pxref{Replacement and Lax Matches}).

However, if the expansion contains a complex mixed case pattern, and the dynamic abbrev matches this pattern as far as it goes, then the expansion is always copied verbatim, regardless of those variables. Thus, for example, if the buffer contains variableWithSillyCasePattern, and you type v a M-/, it copies the expansion verbatim including its case pattern.

The variable dabbrev-abbrev-char-regexp, if non-nil, controls which characters are considered part of a word, for dynamic expansion purposes. The regular expression must match just one character, never two or more. The same regular expression also determines which characters are part of an expansion. The (default) value nil has a special meaning: dynamic abbrevs (i.e. the word at point) are made of word characters, but their expansions are looked for as sequences of word and symbol characters. This is generally appropriate for expanding symbols in a program source and also for human-readable text in many languages, but may not be what you want in a text buffer that includes unusual punctuation characters; in that case, the value "\\sw" might produce better results.

In shell scripts and makefiles, a variable name is sometimes prefixed with ‘$’ and sometimes not. Major modes for this kind of text can customize dynamic abbrev expansion to handle optional prefixes by setting the variable dabbrev-abbrev-skip-leading-regexp. Its value should be a regular expression that matches the optional prefix that dynamic abbrev expression should ignore. The default is nil, which means no characters should be skipped.

[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on May 30, 2018 using texi2html.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

This document was generated on May 30, 2018 using texi2html.