Info Catalog elisp: Advising Named Functions elisp: Advising Functions elisp: Porting old advice

elisp: Advice combinators

 
 12.11.3 Ways to compose advice
 ------------------------------
 
 Here are the different possible values for the WHERE argument of
 ‘add-function’ and ‘advice-add’, specifying how the advice FUNCTION and
 the original function should be composed.
 
 ‘:before’
      Call FUNCTION before the old function.  Both functions receive the
      same arguments, and the return value of the composition is the
      return value of the old function.  More specifically, the
      composition of the two functions behaves like:
           (lambda (&rest r) (apply FUNCTION r) (apply OLDFUN r))
      ‘(add-function :before FUNVAR FUNCTION)’ is comparable for
      single-function hooks to ‘(add-hook 'HOOKVAR FUNCTION)’ for normal
      hooks.
 
 ‘:after’
      Call FUNCTION after the old function.  Both functions receive the
      same arguments, and the return value of the composition is the
      return value of the old function.  More specifically, the
      composition of the two functions behaves like:
           (lambda (&rest r) (prog1 (apply OLDFUN r) (apply FUNCTION r)))
      ‘(add-function :after FUNVAR FUNCTION)’ is comparable for
      single-function hooks to ‘(add-hook 'HOOKVAR FUNCTION 'append)’ for
      normal hooks.
 
 ‘:override’
      This completely replaces the old function with the new one.  The
      old function can of course be recovered if you later call
      ‘remove-function’.
 
 ‘:around’
      Call FUNCTION instead of the old function, but provide the old
      function as an extra argument to FUNCTION.  This is the most
      flexible composition.  For example, it lets you call the old
      function with different arguments, or many times, or within a
      let-binding, or you can sometimes delegate the work to the old
      function and sometimes override it completely.  More specifically,
      the composition of the two functions behaves like:
           (lambda (&rest r) (apply FUNCTION OLDFUN r))
 
 ‘:before-while’
      Call FUNCTION before the old function and don’t call the old
      function if FUNCTION returns ‘nil’.  Both functions receive the
      same arguments, and the return value of the composition is the
      return value of the old function.  More specifically, the
      composition of the two functions behaves like:
           (lambda (&rest r) (and (apply FUNCTION r) (apply OLDFUN r)))
      ‘(add-function :before-while FUNVAR FUNCTION)’ is comparable for
      single-function hooks to ‘(add-hook 'HOOKVAR FUNCTION)’ when
      HOOKVAR is run via ‘run-hook-with-args-until-failure’.
 
 ‘:before-until’
      Call FUNCTION before the old function and only call the old
      function if FUNCTION returns ‘nil’.  More specifically, the
      composition of the two functions behaves like:
           (lambda (&rest r) (or (apply FUNCTION r) (apply OLDFUN r)))
      ‘(add-function :before-until FUNVAR FUNCTION)’ is comparable for
      single-function hooks to ‘(add-hook 'HOOKVAR FUNCTION)’ when
      HOOKVAR is run via ‘run-hook-with-args-until-success’.
 
 ‘:after-while’
      Call FUNCTION after the old function and only if the old function
      returned non-‘nil’.  Both functions receive the same arguments, and
      the return value of the composition is the return value of
      FUNCTION.  More specifically, the composition of the two functions
      behaves like:
           (lambda (&rest r) (and (apply OLDFUN r) (apply FUNCTION r)))
      ‘(add-function :after-while FUNVAR FUNCTION)’ is comparable for
      single-function hooks to ‘(add-hook 'HOOKVAR FUNCTION 'append)’
      when HOOKVAR is run via ‘run-hook-with-args-until-failure’.
 
 ‘:after-until’
      Call FUNCTION after the old function and only if the old function
      returned ‘nil’.  More specifically, the composition of the two
      functions behaves like:
           (lambda (&rest r) (or  (apply OLDFUN r) (apply FUNCTION r)))
      ‘(add-function :after-until FUNVAR FUNCTION)’ is comparable for
      single-function hooks to ‘(add-hook 'HOOKVAR FUNCTION 'append)’
      when HOOKVAR is run via ‘run-hook-with-args-until-success’.
 
 ‘:filter-args’
      Call FUNCTION first and use the result (which should be a list) as
      the new arguments to pass to the old function.  More specifically,
      the composition of the two functions behaves like:
           (lambda (&rest r) (apply OLDFUN (funcall FUNCTION r)))
 
 ‘:filter-return’
      Call the old function first and pass the result to FUNCTION.  More
      specifically, the composition of the two functions behaves like:
           (lambda (&rest r) (funcall FUNCTION (apply OLDFUN r)))
 

Info Catalog elisp: Advising Named Functions elisp: Advising Functions elisp: Porting old advice