A Scripter's Notes ❚
Emacs, scripting and anything text oriented.

Emacs Lisp: Advice Combinators

[Sat Jun 18, 2022]
— Kaushal Modi

My diagrammatic take on summarizing all the Emacs advice combinators.

<2022-06-18>
Improved the diagrams for :before-while, :before-until, :after-while and :after-until. Thanks @shom for the feedback.
Table of Contents

If you have read some of my earlier posts, you would know that I really enjoy using the Emacs Advice system 😃.

The “advice” feature lets you add to the existing definition of a function, by advising the function. This is a cleaner method than redefining the whole function, because it’s easier to debug and if you don’t need it, you can just remove the advice.

You can jump to the References section below if you need to look at the related sections in the Emacs Lisp Manual.

Overview on using advices #

I do not plan to write a tutorial on how to write advices in Emacs-Lisp, but here’s a 3-second primer:

To add an advice
(advice-add 'original-fn <combinator> #'advising-fn)
To remove an advice
(advice-remove 'original-fn #'advising-fn)

This article attempts to briefly describe different ways of advising a function, using 10 different combinators. If you have never used advices in your Emacs config, don’t worry. I am hopeful that the diagrams in this post and the examples linked for some of the combinators in the Summary section makes this concept a bit easier to assimilate.

Diagram Legend
  • Initial black circle: Original Fn input arguments
  • Yellow box: Original Fn
  • Gray box: Advising Fn
  • Black circle inside a white circle: Return values

1 :before #

Figure 1: :before advice

Figure 1: :before advice

2 :after #

Figure 2: :after advice

Figure 2: :after advice

3 :override #

Figure 3: :override advice

Figure 3: :override advice

4 :around #

Figure 4: :around advice

Figure 4: :around advice

5 :before-while #

Figure 5: :before-while advice

Figure 5: :before-while advice

6 :before-until #

Figure 6: :before-until advice

Figure 6: :before-until advice

7 :after-while #

Figure 7: :after-while advice

Figure 7: :after-while advice

8 :after-until #

Figure 8: :after-until advice

Figure 8: :after-until advice

9 :filter-args #

Figure 9: :filter-args advice

Figure 9: :filter-args advice

10 :filter-return #

Figure 10: :filter-return advice

Figure 10: :filter-return advice

Summary #

Here’s a concise summary of what each advice combinator does. For brevity, the advising function is called A and the original function is called O.

Once you click on any of the example posts, search for advice-add on that page to find the code example.

Table 1: Summary of what each advice combinator means
CombinatorDescriptionExample
:beforeA is called before O. O args and return values are not modified.
:afterA is called after O. O args and return values are not modified.
:overrideA is called in lieu of O. A gets the same args as O.Zero HTML Validation Errors!
:aroundA is called in lieu of O. A gets O fn + O args as args.Using Emacs advice to silence messages from functions
:before-whileA is called first. If it returns non-nil, O is called.
:before-untilA is called first. If it returns nil, O is called.Org: Show only Post subtree headings
:after-whileO is called first. If it returns non-nil, A is called.
:after-untilO is called first. If it returns nil, A is called.
:filter-argsA is called first. O is called next with return value from A as input.Narrowing the Author column in Magit
:filter-returnO is called first. A is called next with return value from O as input.Zero HTML Validation Errors!

If you have any feedback on how these diagrams can be made easier to understand, please let me know.

References #