Function: define-abbrev

define-abbrev is a byte-compiled function defined in abbrev.el.gz.

Signature

(define-abbrev TABLE ABBREV EXPANSION &optional HOOK &rest PROPS)

Documentation

Define ABBREV in TABLE, to expand into EXPANSION and optionally call HOOK.

ABBREV must be a string, and should be lower-case. EXPANSION should usually be a string. To undefine an abbrev, define it with EXPANSION = nil. If HOOK is non-nil, it should be a function of no arguments; it is called after EXPANSION is inserted. If EXPANSION is not a string (and not nil), the abbrev is a
 special one, which does not expand in the usual way but only
 runs HOOK.

If HOOK is a non-nil symbol with a non-nil no-self-insert property, it can control whether the character that triggered abbrev expansion is inserted. If such a HOOK returns non-nil, the character is not inserted. If such a HOOK returns nil, then so does abbrev-insert
(and expand-abbrev), as if no abbrev expansion had taken place.

PROPS is a property list. The following properties are special:
- :count: the value for the abbrev's usage-count, which is incremented each
  time the abbrev is used (the default is zero).
- :system: if non-nil, says that this is a "system" abbreviation
  which should not be saved in the user's abbreviation file.
  Unless :system is force, a system abbreviation will not
  overwrite a non-system abbreviation of the same name.
- :case-fixed: non-nil means that abbreviations are looked up without
  case-folding, and the expansion is not capitalized/upcased.
- :enable-function: a function of no arguments which returns non-nil
  if the abbrev should be used for a particular call of expand-abbrev.

An obsolete but still supported calling form is:

(define-abbrev TABLE NAME EXPANSION &optional HOOK COUNT SYSTEM).

View in manual

Probably introduced at or before Emacs version 20.1.

Source Code

;; Defined in /usr/src/emacs/lisp/abbrev.el.gz
(defun define-abbrev (table abbrev expansion &optional hook &rest props)
  "Define ABBREV in TABLE, to expand into EXPANSION and optionally call HOOK.
ABBREV must be a string, and should be lower-case.
EXPANSION should usually be a string.
To undefine an abbrev, define it with EXPANSION = nil.
If HOOK is non-nil, it should be a function of no arguments;
it is called after EXPANSION is inserted.
If EXPANSION is not a string (and not nil), the abbrev is a
 special one, which does not expand in the usual way but only
 runs HOOK.

If HOOK is a non-nil symbol with a non-nil `no-self-insert' property,
it can control whether the character that triggered abbrev expansion
is inserted.  If such a HOOK returns non-nil, the character is not
inserted.  If such a HOOK returns nil, then so does `abbrev-insert'
\(and `expand-abbrev'), as if no abbrev expansion had taken place.

PROPS is a property list.  The following properties are special:
- `:count': the value for the abbrev's usage-count, which is incremented each
  time the abbrev is used (the default is zero).
- `:system': if non-nil, says that this is a \"system\" abbreviation
  which should not be saved in the user's abbreviation file.
  Unless `:system' is `force', a system abbreviation will not
  overwrite a non-system abbreviation of the same name.
- `:case-fixed': non-nil means that abbreviations are looked up without
  case-folding, and the expansion is not capitalized/upcased.
- `:enable-function': a function of no arguments which returns non-nil
  if the abbrev should be used for a particular call of `expand-abbrev'.

An obsolete but still supported calling form is:

\(define-abbrev TABLE NAME EXPANSION &optional HOOK COUNT SYSTEM)."
  (declare (indent defun))
  (when (and (consp props) (or (null (car props)) (numberp (car props))))
    ;; Old-style calling convention.
    (setq props `(:count ,(car props)
                  ,@(if (cadr props) (list :system (cadr props))))))
  (unless (plist-get props :count)
    (setq props (plist-put props :count 0)))
  (setq props (plist-put props :abbrev-table-modiff
                         (abbrev-table-get table :abbrev-table-modiff)))
  (let ((system-flag (plist-get props :system))
        (sym (obarray-put table abbrev)))
    ;; Don't override a prior user-defined abbrev with a system abbrev,
    ;; unless system-flag is `force'.
    (unless (and (not (memq system-flag '(nil force)))
                 (boundp sym) (symbol-value sym)
                 (not (abbrev-get sym :system)))
      (unless (or system-flag
                  (and (boundp sym)
                       ;; load-file-name
                       (equal (symbol-value sym) expansion)
                       (equal (symbol-function sym) hook)))
        (setq abbrevs-changed t))
      (set sym expansion)
      (fset sym hook)
      (setplist sym
                ;; Don't store the `force' value of `system-flag' into
                ;; the :system property.
                (if (eq 'force system-flag) (plist-put props :system t) props))
      (abbrev-table-put table :abbrev-table-modiff
                        (1+ (abbrev-table-get table :abbrev-table-modiff))))
    abbrev))