Next: , Previous: Byte Compilation, Up: Top

17 Advising Emacs Lisp Functions

The advice feature lets you add to the existing definition of a function, by advising the function. This is a cleaner method for a library to customize functions defined within Emacs—cleaner than redefining the whole function.

Each function can have multiple pieces of advice, each of which can be separately defined and then enabled or disabled. All the enabled pieces of advice for any given function actually take effect when you activate advice for that function, or when you define or redefine the function. Note that enabling a piece of advice and activating advice for a function are not the same thing.

Advice is useful for altering the behavior of existing calls to an existing function. If you want the new behavior for new function calls or new key bindings, you should define a new function or command, and have it use the existing function as a subroutine.

Advising a function can cause confusion in debugging, since people who debug calls to the original function may not notice that it has been modified with advice. Therefore, if you have the possibility to change the code of that function to run a hook, please solve the problem that way. Advice should be reserved for the cases where you cannot get the function changed. In particular, Emacs's own source files should not put advice on functions in Emacs. There are currently a few exceptions to this convention, but we aim to correct them.

Unless you know what you are doing, do not advise a primitive (see What Is a Function). Some primitives are used by the advice mechanism; advising them could cause an infinite recursion. Also, many primitives are called directly from C code. Calls to the primitive from Lisp code will take note of the advice, but calls from C code will ignore the advice.