Abbrevs and Abbrev Expansion
****************************

An abbreviation or abbrev is a string of characters that may be expanded to a longer string.  The user can insert the abbrev string and find it replaced automatically with the expansion of the abbrev.  This saves typing.

The set of abbrevs currently in effect is recorded in an abbrev table.  Each buffer has a local abbrev table, but normally all buffers 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 (see Defining Abbrevs); its property list cell typically contains the use count, the number of times the abbreviation has been expanded.  Alternatively, the use count is on the count property and the system-abbrev flag is on the system-type property.  Abbrevs with a non-nil system-type property are called ``system'' abbrevs.  They are usually defined by modes or packages, instead of by the user, and are treated specially in certain respects.

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.  See Creating Symbols.

For the user-level commands for abbrevs, see Abbrev Mode (The GNU Emacs Manual).

Setting Up Abbrev Mode
======================

Abbrev mode is a minor mode controlled by the value of the variable abbrev-mode.

 -- Variable: abbrev-mode
     A non-nil value of this variable turns on the automatic expansion of abbrevs when their abbreviations are inserted into a buffer. If the value is nil, abbrevs may be defined, but they are not expanded automatically.

     This variable automatically becomes buffer-local when set in any fashion.

 -- Variable: default-abbrev-mode
     This is the value of abbrev-mode for buffers that do not override it. This is the same as (default-value 'abbrev-mode).

Abbrev Tables
=============

This section describes how to create and manipulate abbrev tables.

 -- Function: make-abbrev-table
     This function creates and returns a new, empty abbrev table---an obarray containing no symbols.  It is a vector filled with zeros.

 -- Function: clear-abbrev-table table
     This function undefines all the abbrevs in abbrev table TABLE, leaving it empty.  It always returns nil.

 -- Function: copy-abbrev-table table
     This function returns a copy of abbrev table TABLE---a new abbrev table that contains the same abbrev definitions.  The only difference between TABLE and the returned copy is that this function sets the property lists of all copied abbrevs to 0.

 -- Function: define-abbrev-table tabname definitions
     This function defines TABNAME (a symbol) as an abbrev table name, i.e., as a variable whose value is an abbrev table.  It defines abbrevs in the table according to DEFINITIONS, a list of elements of the form (ABBREVNAME EXPANSION HOOK USECOUNT SYSTEM-FLAG).  If an element of DEFINITIONS has length less than five, omitted elements default to nil.  A value of nil for USECOUNT is equivalent to zero.  The return value is always nil.

     If this function is called more than once for the same TABNAME, subsequent calls add the definitions in DEFINITIONS to TABNAME, rather than overriding the entire original contents. (A subsequent call only overrides abbrevs explicitly redefined or undefined in DEFINITIONS.)

 -- Variable: abbrev-table-name-list
     This is a list of symbols whose values are abbrev tables. define-abbrev-table adds the new abbrev table name to this list.

 -- Function: insert-abbrev-table-description name &optional human
     This function inserts before point a description of the abbrev table named NAME.  The argument NAME is a symbol whose value is an abbrev table.  The return value is always nil.

     If HUMAN is non-nil, the description is human-oriented. System abbrevs are listed and identified as such.  Otherwise the description is a Lisp expression---a call to define-abbrev-table that would define NAME as it is currently defined, but without the system abbrevs.  (The mode or package using NAME is supposed to add these to NAME separately.)

Defining Abbrevs
================

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 define-abbrev and specify t for SYSTEM-FLAG.

 -- Function: define-abbrev table name expansion &optional hook count system-flag
     This function defines an abbrev named NAME, in TABLE, to expand to EXPANSION and call HOOK.  The return value is NAME.

     The value of COUNT, if specified, initializes the abbrev's usage-count.  If COUNT is not specified or nil, the use count is initialized to zero.

     The argument NAME should be a string.  The argument EXPANSION is normally the desired expansion (a string), or nil to undefine the abbrev.  If it is anything but a string or nil, then the abbreviation ``expands'' solely by running HOOK.

     The argument HOOK is a function or nil.  If HOOK is non-nil, then it is called with no arguments after the abbrev is replaced with EXPANSION; point is located at the end of EXPANSION when HOOK is called.

     If HOOK is a non-nil symbol whose no-self-insert property is non-nil, HOOK can explicitly control whether to insert the self-inserting input character that triggered the expansion.  If HOOK returns non-nil in this case, that inhibits insertion of the character.  By contrast, if HOOK returns nil, expand-abbrev also returns nil, as if expansion had not really occurred.

     If SYSTEM-FLAG is non-nil, that marks the abbrev as a ``system'' abbrev with the system-type property.

     Normally the function define-abbrev sets the variable abbrevs-changed to 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.

 -- User Option: only-global-abbrevs
     If this variable is non-nil, it means that the user plans to use global abbrevs only.  This tells the commands that define mode-specific abbrevs to define global ones instead.  This variable does not alter the behavior of the functions in this section; it is examined by their callers.

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 same abbrev tables with the same contents.  Therefore, you can load the file with load (see How Programs Do Loading).  However, the function quietly-read-abbrev-file is provided as a more convenient interface.

User-level facilities such as save-some-buffers can save abbrevs in a file automatically, under the control of variables described here.

 -- User Option: abbrev-file-name
     This is the default file name for reading and saving abbrevs.

 -- Function: quietly-read-abbrev-file &optional filename
     This function reads abbrev definitions from a file named FILENAME, previously written with write-abbrev-file.  If FILENAME is omitted or nil, the file specified in abbrev-file-name is used.  save-abbrevs is set to t so that changes will be saved.

     This function does not display any messages.  It returns nil.

 -- User Option: save-abbrevs
     A non-nil value for save-abbrevs means that Emacs should offer the user to save abbrevs when files are saved.  If the value is silently, Emacs saves the abbrevs without asking the user. abbrev-file-name specifies the file to save the abbrevs in.

 -- Variable: abbrevs-changed
     This variable is set non-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.

 -- Command: write-abbrev-file &optional filename
     Save all abbrev definitions (except ``system'' abbrevs), for all abbrev tables listed in abbrev-table-name-list, in the file FILENAME, in the form of a Lisp program that when loaded will define the same abbrevs.  If FILENAME is nil or omitted, abbrev-file-name is used.  This function returns nil.

Looking Up and Expanding Abbreviations
======================================

Abbrevs are usually expanded by certain interactive commands, including self-insert-command.  This section describes the subroutines used in writing such commands, as well as the variables they use for communication.

 -- Function: abbrev-symbol abbrev &optional table
     This function returns the symbol representing the abbrev named ABBREV.  The value returned is nil if that abbrev is not defined.  The optional second argument TABLE is the abbrev table to look it up in.  If TABLE is nil, this function tries first the current buffer's local abbrev table, and second the global abbrev table.

 -- Function: abbrev-expansion abbrev &optional table
     This function returns the string that ABBREV would expand into (as defined by the abbrev tables used for the current buffer).  If ABBREV is not a valid abbrev, the function returns nil. The optional argument TABLE specifies the abbrev table to use, as in abbrev-symbol.

 -- 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, nil otherwise.

     If the abbrev symbol has a hook function which is a symbol whose no-self-insert property is non-nil, and if the hook function returns nil as its value, then expand-abbrev returns nil even though expansion did occur.

 -- Command: abbrev-prefix-mark &optional arg
     This command marks the current location of point as the beginning of an abbrev.  The next call to expand-abbrev will use the text from here to point (where it is then) as the abbrev to expand, rather than using the previous word as usual.

     First, this command expands any abbrev before point, unless ARG is non-nil.  (Interactively, ARG is the prefix argument.) Then it inserts a hyphen before point, to indicate the start of the next abbrev to be expanded.  The actual expansion removes the hyphen.

 -- User Option: abbrev-all-caps
     When this is set non-nil, an abbrev entered entirely in upper case is expanded using all upper case.  Otherwise, an abbrev entered entirely in upper case is expanded by capitalizing each word of the expansion.

 -- Variable: abbrev-start-location
     The value of this variable is a buffer position (an integer or a marker) for expand-abbrev to use as the start of the next abbrev to be expanded.  The value can also be nil, which means to use the word before point instead.  abbrev-start-location is set to nil each time expand-abbrev is called.  This variable is also set by abbrev-prefix-mark.

 -- Variable: abbrev-start-location-buffer
     The value of this variable is the buffer for which abbrev-start-location has been set.  Trying to expand an abbrev in any other buffer clears abbrev-start-location.  This variable is set by abbrev-prefix-mark.

 -- Variable: last-abbrev
     This is the abbrev-symbol of the most recent abbrev expanded.  This information is left by expand-abbrev for the sake of the unexpand-abbrev command (see Expanding Abbrevs (The GNU Emacs Manual)).

 -- Variable: last-abbrev-location
     This is the location of the most recent abbrev expanded.  This contains information left by expand-abbrev for the sake of the unexpand-abbrev command.

 -- Variable: last-abbrev-text
     This is the exact expansion text of the most recent abbrev expanded, after case conversion (if any).  Its value is nil if the abbrev has already been unexpanded.  This contains information left by expand-abbrev for the sake of the unexpand-abbrev command.

 -- Variable: pre-abbrev-expand-hook
     This is a normal hook whose functions are executed, in sequence, just before any expansion of an abbrev.  See Hooks.  Since it is a normal hook, the hook functions receive no arguments.  However, they can find the abbrev to be expanded by looking in the buffer before point. Running the hook is the first thing that expand-abbrev does, and so a hook function can be used to change the current abbrev table before abbrev lookup happens.  (Although you have to do this carefully.  See the example below.)

The following sample code shows a simple use of pre-abbrev-expand-hook.  It assumes that foo-mode is a mode for editing certain files in which lines that start with # are comments.  You want to use Text mode abbrevs for those lines.  The regular local abbrev table, foo-mode-abbrev-table is appropriate for all other lines.  Then you can put the following code in your .emacs file.  See Standard Abbrev Tables, for the definitions of local-abbrev-table and text-mode-abbrev-table.

     (defun foo-mode-pre-abbrev-expand ()
       (when (save-excursion (forward-line 0) (eq (char-after) ?#))
         (let ((local-abbrev-table text-mode-abbrev-table)
     	  ;; Avoid infinite loop.
     	  (pre-abbrev-expand-hook nil))
           (expand-abbrev))
         ;; We have already called `expand-abbrev' in this hook.
         ;; Hence we want the "actual" call following this hook to be a no-op.
         (setq abbrev-start-location (point-max)
     	  abbrev-start-location-buffer (current-buffer))))

     (add-hook 'foo-mode-hook
     	  #'(lambda ()
     	      (add-hook 'pre-abbrev-expand-hook
     			'foo-mode-pre-abbrev-expand
     			nil t)))

Note that foo-mode-pre-abbrev-expand just returns nil without doing anything for lines not starting with #.  Hence abbrevs expand normally using foo-mode-abbrev-table as local abbrev table for such lines.

Standard Abbrev Tables
======================

Here we list the variables that hold the abbrev tables for the preloaded major modes of Emacs.

 -- Variable: global-abbrev-table
     This is the abbrev table for mode-independent abbrevs.  The abbrevs defined in it apply to all buffers.  Each buffer may also have a local abbrev table, whose abbrev definitions take precedence over those in the global table.

 -- Variable: local-abbrev-table
     The value of this buffer-local variable is the (mode-specific) abbreviation table of the current buffer.

 -- Variable: fundamental-mode-abbrev-table
     This is the local abbrev table used in Fundamental mode; in other words, it is the local abbrev table in all buffers in Fundamental mode.

 -- Variable: text-mode-abbrev-table
     This is the local abbrev table used in Text mode.

 -- Variable: lisp-mode-abbrev-table
     This is the local abbrev table used in Lisp mode and Emacs Lisp mode.