Extending Emacs with Advice
January 14, 2009 at 04:30 PM | categories: emacs | View Comments
The greatest single thing about Emacs is it's extensibility. If you think Emacs is missing something, or don't like how something works, you can change it. But that's true of any open-source software. The difference with Emacs is how easy it is to make that change.
There are several different strategies to extend Emacs. I'll list a few of them in order of hardest to easiest (and arguably from worst to best):
- Write your own major or minor mode from scratch.
- Edit someone else's mode (and hopefully submit a patch.)
- Write an Advice function.
- Write a Mode Hook.
Where Advice fits in
(Don't worry, I get into the meat of it in the next section. For the impatient, skip down.)
Mode hooks are almost always the easiest and best way to extend a particular mode, but they are also limited in scope. The author of the mode created these hooks specifically to allow you to extend his mode, and are therefore the best maintainable way to extend a mode (the author is unlikely to remove those hooks in future versions). However, if the author didn't anticipate certain functionality and there is no appropriate hook provided, you'll have to come up with a different solution.
At this point, obviously, you could just write your own mode -- but what a pain that would be if you already have something that's close to what you want. So why not just edit that particular mode to suit your needs (perhaps creating that missing mode hook yourself?) This approach is probably the best one especially if the feature you want is something other people would benefit from. You can submit your changes as a patch to the original author and (if he accepts them) your changes go into the next release.
But what if for some reason your changes are not acceptable to the author? You can still use your changes on your local machine, but every time a new version of the original mode comes out you'll have to merge your changes back into that new version. At this point you've successfully "forked" the project, but that's usually a bad thing in the long run.
One other option exists to Emacs developers: advice. Advice allows you to wrap existing functions with your own functions. This allows some types of behavior to be modified without even having to change the original file at all. You can keep your changes completely separated in your own customized files. This gives you the benefit of inheriting new versions of the mode by simply downloading the new version and putting it in your load path. In most cases your advice function will continue to work on the new version and you didn't have to merge any changes at all. If significant changes have been made you may need to modify your advice function, or create a new one, but you still won't need to merge any changes.
Continue reading and I'll give you a real-world example of how I've used advice, but I want to first re-iterate the proper use cases of advice:
- If you can use the mode hooks provided by the author, use them instead.
- If there is a bug in the original mode, just fix it in the original code and submit a patch.
- If there is a new feature you want, add it to the original mode and submit a patch. Talk to the author, work with him, and it will most likely end up in the next release.
- If you are an Emacs developer, working on Emacs itself, or one of the modes shipped with Emacs, never use advice. It's the least maintainable method of extending Emacs with the exception of a pure fork, and since you're working on Emacs itself, it's not a fork.
- If your patch is not accepted, or you know that what you want is fringe enough or hackish enough to not warrant submitting a patch, only then should you use advice or fork the project.
Using Advice
Alright, onward to the example I promised. I really liked the tip over at Minor Emacs Wizardry on combining EasyPG with Org mode -- it's an awesome way to keep a lot of things in an organized and encrypted way -- I use it all the time now.
My main machine is running Ubuntu and it's default GnuPG agent is Seahorse. It's actually a pretty nice manager for encryption (SSH and PGP) and is completely integrated with the Gnome desktop. The one problem I have with it is that I use Multi-TTY Emacs and when I'm using a terminal on a remote connection and I try and open an encrypted file, Seahorse pops up on the desktop instead of prompting me for the passphrase on my remote connection. In the past I've had to fire up VNC to my desktop just so that I could enter the password; damn inconvenient.
I could setup something like keychain, it's a real nice GPG agent that works equally well on the desktop as on the console. I've used it in the past and liked it. Seahorse requires no setup though, it comes with Ubuntu by default, and like I said, I really quite like it.
So, when I'm on my remote connection and Seahorse doesn't have my password cached, I'd like to be able to bypass the GPG agent entirely and just enter my password. EasyPG doesn't appear to have this functionality so I added it with advice:
(defadvice epg--start (around advice-epg-disable-agent disable) "Make epg--start not able to find a gpg-agent" (let ((agent (getenv "GPG_AGENT_INFO"))) (setenv "GPG_AGENT_INFO" nil) ad-do-it (setenv "GPG_AGENT_INFO" agent)))
That little bit of code wraps the main EasyPG function that will ask for a password. It temporarily removes the environment variable that EasyPG looks for to connect to the GPG agent, and therefore EasyPG asks the user for the password as if there were no agent running.
Let's analyze the different parts of that advice function:
- All advice starts with a "defadvice" definition.
- "epg--start" is the name of the original function I'm wrapping.
- "around" is indicating that I'm specifying code to run both before and after the function I'm wrapping (other options would include "before" and "after")
- The word "disable" means that the advice is initially turned off (you could say "activate" to have it immediately turned on, read the manual for more options here)
- Starting with the "let" function is the body of my custom function
- The "ad-do-it" line in the middle is the point in the function where the original function gets executed. (This would not be used in a "before" or "after" style function.)
One more important thing to understand about advising a function is that you aren't creating a new function with a new name. You are adding data to the existing function definition. Wherever the original function gets called, your advice will be called along with it. However, advice does offer the convenience of turning on or off your changes. For the above example I added two user commands to turn on and off the GPG agent (bound to M-x epg-disable-agent and M-x epg-enable-agent):
(defun epg-disable-agent () "Make EasyPG bypass any gpg-agent" (interactive) (ad-enable-advice 'epg--start 'around 'advice-epg-disable-agent) (ad-activate 'epg--start) (message "EasyPG gpg-agent bypassed")) (defun epg-enable-agent () "Make EasyPG use a gpg-agent after having been disabled with epg-disable-agent" (interactive) (ad-disable-advice 'epg--start 'around 'advice-epg-disable-agent) (ad-activate 'epg--start) (message "EasyPG gpg-agent re-enabled"))
These functions use the (ad-enable-advice) and (ad-disable-advice) functions respectively. Whenever advice is switched on or off, a call to (ad-activate) must also be made on the function to update it.
The manual goes into more depth about how to advice functions. Hopefully you got something useful out of this, I sure learned a lot in writing it.