Next: 适配使用旧版 defadvice 的代码, Previous: 为命名函数添加建议, Up: 为 Emacs Lisp 函数添加建议   [Contents][Index]

13.12.3 建议的组合方式 ¶

以下是 add-function 和 advice-add 中参数 where 可使用的各种取值，用于指定建议函数与原函数的组合方式。

:before

在原函数执行之前调用 function。两个函数接收相同的参数，组合后的函数返回值为原函数的返回值。更具体地说，这两个函数的组合行为等价于：

(lambda (&rest r) (apply function r) (apply oldfun r))

对于「单函数钩子」场景，(add-function :before funvar function)的效果类似于普通钩子中 (add-hook 'hookvar function) 的效果。

:after

在原函数执行之后调用 function。两个函数接收相同的参数，组合后的函数返回值为原函数的返回值。更具体地说，这两个函数的组合行为等价于：

(lambda (&rest r) (prog1 (apply oldfun r) (apply function r)))

对于「单函数钩子」场景，(add-function :after funvar function)的效果类似于普通钩子中 (add-hook 'hookvar function 'append) 的效果。

: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

调用 function 以替代原函数执行，但会将原函数作为额外参数传入 function。这是灵活性最高的组合方式：例如，你可以让原函数接收不同的参数、多次调用原函数、在 let 绑定环境中调用原函数，也可以选择有时将任务委托给原函数执行，有时则完全覆盖原函数的逻辑。更具体地说，这两个函数的组合行为等价于：

(lambda (&rest r) (apply function oldfun r))

:before-while

在原函数执行前调用 function；若 function 返回 nil，则不再调用原函数。两个函数接收相同的参数，组合后的函数返回值为原函数的返回值（若原函数未执行，则返回 nil）。更具体地说，这两个函数的组合行为等价于：

(lambda (&rest r) (and (apply function r) (apply oldfun r)))

对于单函数钩子场景，(add-function :before-while funvar function) 的效果，等同于当 hookvar 通过 run-hook-with-args-until-failure 执行时，调用 (add-hook 'hookvar function) 的效果。

:before-until

在原函数之前调用 function，并且只有当 function 返回 nil 时，才调用原函数。更具体地说，这两个函数的组合行为等价于：

(lambda (&rest r) (or (apply function r) (apply oldfun r)))

对于单函数钩子，(add-function :before-until funvar function)等价于在 hookvar 通过 run-hook-with-args-until-success 运行时，使用 (add-hook 'hookvar function) 的效果。

:after-while

在原函数之后调用 function，并且只有当原函数返回非 nil 时才调用。两个函数接收相同的参数，组合后的返回值是 function 的返回值。更具体地说，这两个函数的组合行为等价于：

(lambda (&rest r) (and (apply oldfun r) (apply function r)))

对于单函数钩子，(add-function :after-while funvar function)等价于在 hookvar 通过 run-hook-with-args-until-failure 运行时，使用 (add-hook 'hookvar function 'append) 的效果。

:after-until

在原函数之后调用 function，并且只有当原函数返回 nil 时才调用。更具体地说，这两个函数的组合行为等价于：

(lambda (&rest r) (or  (apply oldfun r) (apply function r)))

(add-function :after-until funvar function)对于单函数钩子场景，其效果等同于：当 hookvar 通过run-hook-with-args-until-success 执行时，调用(add-hook 'hookvar function 'append) 的效果。

:filter-args

先调用 function，并将其返回结果（需为列表类型）作为新参数传递给原函数。更具体地说，这两个函数的组合行为等价于：

(lambda (&rest r) (apply oldfun (funcall function r)))

:filter-return

先调用原函数，再将其返回结果传递给 function。更具体地说，这两个函数的组合行为等价于：

(lambda (&rest r) (funcall function (apply oldfun r)))