Function: add-function

add-function is a macro defined in nadvice.el.gz.

Signature

(add-function HOW PLACE FUNCTION &optional PROPS)

Documentation

Add a piece of advice on the function stored at PLACE.

FUNCTION describes the code to add. HOW describes how to add it. HOW can be explained by showing the resulting new function, as the result of combining FUNCTION and the previous value of PLACE, which we call OLDFUN here:
 :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)))
If FUNCTION was already added, do nothing. PROPS is an alist of additional properties, among which the following have a special meaning:
- name: a string or symbol. It can be used to refer to this piece of advice.
- depth: a number indicating a preference w.r.t ordering.
  The default depth is 0. By convention, a depth of 100 means that
  the advice should be innermost (i.e. at the end of the list),
  whereas a depth of -100 means that the advice should be outermost.

If PLACE is a symbol, its default-value will be affected. Use (local 'SYMBOL) if you want to apply FUNCTION to SYMBOL buffer-locally. Use (var VAR) if you want to apply FUNCTION to the (lexical) VAR. If you are trying to modify an existing named function rather than a function value, you probably want to use advice-add instead (see Info node (elisp) Advising Named Functions).

If one of FUNCTION or OLDFUN is interactive, then the resulting function is also interactive. There are 3 cases:
- FUNCTION is not interactive: the interactive spec of OLDFUN is used.
- The interactive spec of FUNCTION is itself a function: it should take one
  argument (the interactive spec of OLDFUN, which it can pass to
  advice-eval-interactive-spec) and return the list of arguments to use.
- Else, use the interactive spec of FUNCTION and ignore the one of OLDFUN.

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
(defmacro add-function (how place function &optional props)
  ;; TODO:
  ;; - maybe let `how' specify some kind of predicate and use it
  ;;   to implement things like mode-local or cl-defmethod.
  ;;   Of course, that only makes sense if the predicates of all advices can
  ;;   be combined and made more efficient.
  ;; :before is like a normal add-hook on a normal hook.
  ;; :before-while is like add-hook on run-hook-with-args-until-failure.
  ;; :before-until is like add-hook on run-hook-with-args-until-success.
  ;; Same with :after-* but for (add-hook ... 'append).
  "Add a piece of advice on the function stored at PLACE.
FUNCTION describes the code to add.  HOW describes how to add it.
HOW can be explained by showing the resulting new function, as the
result of combining FUNCTION and the previous value of PLACE, which we
call OLDFUN here:
<<>>
If FUNCTION was already added, do nothing.
PROPS is an alist of additional properties, among which the following have
a special meaning:
- `name': a string or symbol.  It can be used to refer to this piece of advice.
- `depth': a number indicating a preference w.r.t ordering.
  The default depth is 0.  By convention, a depth of 100 means that
  the advice  should be innermost (i.e. at the end of the list),
  whereas a depth of -100 means that the advice should be outermost.

If PLACE is a symbol, its `default-value' will be affected.
Use (local \\='SYMBOL) if you want to apply FUNCTION to SYMBOL buffer-locally.
Use (var VAR) if you want to apply FUNCTION to the (lexical) VAR.
If you are trying to modify an existing named function rather
than a function value, you probably want to use `advice-add'
instead (see Info node `(elisp) Advising Named Functions').

If one of FUNCTION or OLDFUN is interactive, then the resulting function
is also interactive.  There are 3 cases:
- FUNCTION is not interactive: the interactive spec of OLDFUN is used.
- The interactive spec of FUNCTION is itself a function: it should take one
  argument (the interactive spec of OLDFUN, which it can pass to
  `advice-eval-interactive-spec') and return the list of arguments to use.
- Else, use the interactive spec of FUNCTION and ignore the one of OLDFUN."
  (declare
   ;;(indent 2)
   (debug (form [&or symbolp ("local" form) ("var" sexp) gv-place]
                form &optional form)))
  `(advice--add-function ,how (gv-ref ,(advice--normalize-place place))
                         ,function ,props))