My config is full of advice, and I keep hearing about the new shiny minimalist nadvice.el package.
I've searched the manuals, and I've read the source, but I'll openly admit: I still have no idea how to actually use it.
Can anyone here point me to a guide, or tell me how to get started porting my old-style advice over?
All information you need is included in C-h f add-function which
describes the underlying mechanism of advice-add.
The new advice system basically acts like replacing the current
definition of a function by the function described in the table in
C-h f add-function, depending on your choice of the WHERE
argument, only cleaner for the sake of tracking what behaviour has
been defined in what source file.
:around optionThe most general case is the :around option, so I give an example
for that. (It is probably better to use dedicated WHERE parameters
when possible, but you can replace every other by an equivalent
:around function).
Just as an example, lets say you want to debug some use of find-file
and want to print its argument list every time it is called. You
could write
(defun my-find-file-advice-print-arguments (old-function &rest arguments)
"Print the argument list every time the advised function is called."
(print arguments)
(apply old-function arguments))
(advice-add #'find-file :around #'my-find-file-advice-print-arguments)
With this new implementation, everything the advice needs is passed as
argument. ad-get-args becomes unnecessary, because the arguments are
passed to the advice function as normal function arguments (for
WHERE arguments for which it makes sense). ad-do-it becomes
unnecessary as :around advice gets as arguments the function and the
arguments, so (ad-do-it) is replaced by the form
(apply old-function arguments)
or when you have named the arguments
(funcall old-function first-arg second-arg)
which is cleaner as there are no magic forms involved. Modifying the
arguments simply happens by passing modified values to OLD-FUNCTION.
WHERE valuesThe docstring of add-function contains a table of all advice places (or "combinators"),
and what they are equivalent to, and explains the functionality in
terms of a lambda behaving equivalent to the advised function:
`:before' (lambda (&rest r) (apply FUNCTION r) (apply OLDFUN r))
`:after' (lambda (&rest r) (prog1 (apply OLDFUN r) (apply FUNCTION r)))
`:around' (lambda (&rest r) (apply FUNCTION OLDFUN r))
`:override' (lambda (&rest r) (apply FUNCTION r))
`:before-while' (lambda (&rest r) (and (apply FUNCTION r) (apply OLDFUN r)))
`:before-until' (lambda (&rest r) (or (apply FUNCTION r) (apply OLDFUN r)))
`:after-while' (lambda (&rest r) (and (apply OLDFUN r) (apply FUNCTION r)))
`:after-until' (lambda (&rest r) (or (apply OLDFUN r) (apply FUNCTION r)))
`:filter-args' (lambda (&rest r) (apply OLDFUN (funcall FUNCTION r)))
`:filter-return'(lambda (&rest r) (funcall FUNCTION (apply OLDFUN r)))
(cited from `C-h f add-function')
where FUNCTION is the advice function and OLDFUN the function where
the advice is added. Don't try to understand all of them at once, just
select a WHERE symbol that sounds fitting and try to understand that
one.
Or just use :around. As far as I can tell the only advantage of
using specialized WHEREs over :around for everything is that you
get a bit more information from looking up C-h f ADVISED-FUNCTION
prior to reading the docstring of the advice. Unless you plan to
publish the code containing the advice it probably doesn't matter.
I recommend using named functions as advice since it provides many advantages (some of them also apply to using named functions for hooks):
It shows up in C-h f find-file as
:around advice: `my-find-file-advice-print-arguments'
linking to the definition of the advice function, which as usual
contains a link to the file where it was defined . If the advice
had been defined as a lambda form directly in the advice-add
form the docstring would be shown inline (a mess for long
docstrings?) and nothing would indicate where it was defined.
You can remove the advice with
(advice-remove #'find-file #'my-find-file-advice-print-arguments)
You can update the definition of the advice without rerunning
advice-add or risking to keep the old version active (as running
advice-add with a changed lambda will be recognized as new
advice, not as an update to the old one).
Side remark The #'function notation is basically equivalent to
'function, except that it help the byte compiler identify symbols
as function names and thus to identify missing functions (e.g. due to
typos).
