Function: advice-add

advice-add is a byte-compiled function defined in nadvice.el.gz.

Signature

(advice-add SYMBOL HOW FUNCTION &optional PROPS)

Documentation

Like add-function but for the function named SYMBOL.

Contrary to add-function, this will properly handle the cases where SYMBOL is defined as a macro, alias, command, ... HOW can be one of:
 :around (lambda (&rest r) (apply FUNCTION OLDFUN r))
 :before (lambda (&rest r) (apply FUNCTION r) (apply OLDFUN r))
 :after (lambda (&rest r) (prog1 (apply OLDFUN r) (apply FUNCTION r)))
 :override (lambda (&rest r) (apply FUNCTION r))
 :after-until (lambda (&rest r) (or (apply OLDFUN r) (apply FUNCTION r)))
 :after-while (lambda (&rest r) (and (apply OLDFUN r) (apply FUNCTION r)))
 :before-until (lambda (&rest r) (or (apply FUNCTION r) (apply OLDFUN r)))
 :before-while (lambda (&rest r) (and (apply FUNCTION r) (apply OLDFUN r)))
 :filter-args (lambda (&rest r) (apply OLDFUN (funcall FUNCTION r)))
 :filter-return (lambda (&rest r) (funcall FUNCTION (apply OLDFUN r)))

View in manual

Probably introduced at or before Emacs version 24.4.

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/nadvice.el.gz
;;;###autoload
(defun advice-add (symbol how function &optional props)
  "Like `add-function' but for the function named SYMBOL.
Contrary to `add-function', this will properly handle the cases where SYMBOL
is defined as a macro, alias, command, ...
HOW can be one of:
<<>>"
  ;; TODO:
  ;; - record the advice location, to display in describe-function.
  (let* ((f (symbol-function symbol))
	 (nf (advice--normalize symbol f)))
    (unless (eq f nf) (fset symbol nf))
    (add-function how (cond
                       ((eq (car-safe nf) 'macro) (cdr nf))
                       ;; Reasons to delay installation of the advice:
                       ;; - If the function is not yet defined, installing
                       ;;   the advice would affect `fboundp'ness.
                       ;; - the symbol-function slot of an autoloaded
                       ;;   function is not itself a function value.
                       ;; - `autoload' does nothing if the function is
                       ;;   not an autoload or undefined.
                       ((or (not nf) (autoloadp nf))
                        (get symbol 'advice--pending))
                       (t (symbol-function symbol)))
                  function props)
    ;; FIXME: We could use a defmethod on `function-documentation' instead,
    ;; except when (autoloadp nf)!
    (put symbol 'function-documentation `(advice--make-docstring ',symbol))
    (add-function :around (get symbol 'defalias-fset-function)
                  #'advice--defalias-fset))
  nil)