Next: , Previous: Abbrev Files, Up: Abbrevs

36.5 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).

— 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.