Emacs Lisp: Advice Combinators

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Fri, 17 Jun 2022 21:30:00 -0400

My diagrammatic take on summarizing all the Emacs advice combinators.

Table of Contents

Overview on using advices
1 :before
2 :after
3 :override
4 :around
5 :before-while
6 :before-until
7 :after-while
8 :after-until
9 :filter-args
10 :filter-return
Summary
References

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

2 `:after` #

Figure 2: :after advice

3 `:override` #

Figure 3: :override advice

4 `:around` #

Figure 4: :around advice

5 `:before-while` #

Figure 5: :before-while advice

6 `:before-until` #

Figure 6: :before-until advice

7 `:after-while` #

Figure 7: :after-while advice

8 `:after-until` #

Figure 8: :after-until advice

9 `:filter-args` #

Figure 9: :filter-args advice

10 `:filter-return` #

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

Combinator	Description	Example
`:before`	A is called before O. O args and return values are not modified.
`:after`	A is called after O. O args and return values are not modified.
`:override`	A is called in lieu of O. A gets the same args as O.	Zero HTML Validation Errors!
`:around`	A is called in lieu of O. A gets O fn + O args as args.	Using Emacs advice to silence messages from functions
`:before-while`	A is called first. If it returns non-nil, O is called.
`:before-until`	A is called first. If it returns nil, O is called.	Org: Show only Post subtree headings
`:after-while`	O is called first. If it returns non-nil, A is called.
`:after-until`	O is called first. If it returns nil, A is called.
`:filter-args`	A is called first. O is called next with return value from A as input.	Narrowing the Author column in Magit
`:filter-return`	O 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 #

Elisp Info: Advising Functions
- Elisp Info: Advice Combinators

Org Contribution Flow-chart

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Tue, 06 Mar 2018 00:23:00 -0500

A handy flow-chart if you are confused about when commits happen to Org bugfix branch vs main branch, what ends up in the GNU Elpa version, and so on.

I have often seen questions and confusion about why certain fixes or features added to Org mode did not show up in its update on GNU Elpa.

Below flow chart is an attempt to answer all such questions, and also my first attempt at creating one using PlantUML (legacy syntax) See the legacy vs new (beta) PlantUML syntax for activity diagrams. When I tried the new (beta) syntax, it did not allow using the “labels”.. see the as bugfix, as main syntax in the flowchart source code. .

Figure 1: Flow of a commit in Org mode repo from bugfix branch to main branch to Emacs repo

PlantUML source code

(*) --> "My Org commit"
--> "Discuss on Org mailing list"
if "Bug fix commit?" then
-->[yes] "Commit to Org **bugfix**" as bugfix
else
->[no] if "**bugfix** compatible doc fix commit?" then
-->[yes] bugfix
else
->[no] "Commit to Org **main**" as main
endif
endif
bugfix --> "Merge to Org **main**"
--> main
bugfix --> "Wait till next Monday"
--> "Push to GNU Elpa" as push
bugfix --> "Short maturity time"
--> "Cut a minor release" as minor_release
minor_release --> ===RELEASE===
minor_release --> main
main --> "**Long maturity time**"
--> "Cut a major release" as major_release
major_release --> ===RELEASE===
major_release --> "Merge to Org **bugfix**"
--> bugfix
===RELEASE=== --> push
===RELEASE=== --> "Squash and commit to Emacs release or main branch"
--> (*)
push --> (*)

Few notes on PlantUML syntax

Syntax	Output
`-->`	Vertical arrow
`->`	Horizontal arrow
`(*) -->`	Start point
`--> (*)`	End point

plantuml on A Scripter's Notes

Emacs Lisp: Advice Combinators

Overview on using advices #

1 :before #

2 :after #

3 :override #

4 :around #

5 :before-while #

6 :before-until #

7 :after-while #

8 :after-until #

9 :filter-args #

10 :filter-return #