GNU Info

(elisp)Abbrev Expansion

---

Next: Standard Abbrev Tables Prev: Abbrev Files Up: Abbrevs

---

Enter node , (file) or (file)node

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).  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
     Mark current 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.

 - 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
     This is the buffer position for `expand-abbrev' to use as the start
     of the next abbrev to be expanded.  (`nil' means 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 (*note Expanding Abbrevs:
     (emacs)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.  Note: 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.

   The following sample code shows a simple use of
`pre-abbrev-expand-hook'.  If the user terminates an abbrev with a
punctuation character, the hook function asks for confirmation.  Thus,
this hook allows the user to decide whether to expand the abbrev, and
aborts expansion if it is not confirmed.

     (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
     
     ;; This is the function invoked by `pre-abbrev-expand-hook'.
     
     ;; If the user terminated the abbrev with a space, the function does
     ;; nothing (that is, it returns so that the abbrev can expand).  If the
     ;; user entered some other character, this function asks whether
     ;; expansion should continue.
     
     ;; If the user answers the prompt with `y', the function returns
     ;; `nil' (because of the `not' function), but that is
     ;; acceptable; the return value has no effect on expansion.
     
     (defun query-if-not-space ()
       (if (/= ?\  (preceding-char))
           (if (not (y-or-n-p "Do you want to expand this abbrev? "))
               (error "Not expanding this abbrev"))))