— Function: run-hooks &rest hookvars

This function takes one or more normal hook variable names as arguments, and runs each hook in turn. Each argument should be a symbol that is a normal hook variable. These arguments are processed in the order specified.

If a hook variable has a non-nil value, that value should be a list of functions. run-hooks calls all the functions, one by one, with no arguments.

The hook variable's value can also be a single function—either a lambda expression or a symbol with a function definition—which run-hooks calls. But this usage is obsolete.

If the hook variable is buffer-local, the buffer-local variable will be used instead of the global variable. However, if the buffer-local variable contains the element t, the global hook variable will be run as well.

— Function: run-hook-with-args hook &rest args

This function runs an abnormal hook by calling all the hook functions in hook, passing each one the arguments args.

— Function: run-hook-with-args-until-failure hook &rest args

This function runs an abnormal hook by calling each hook function in turn, stopping if one of them “fails” by returning nil. Each hook function is passed the arguments args. If this function stops because one of the hook functions fails, it returns nil; otherwise it returns a non-nil value.

— Function: run-hook-with-args-until-success hook &rest args

This function runs an abnormal hook by calling each hook function, stopping if one of them “succeeds” by returning a non-nil value. Each hook function is passed the arguments args. If this function stops because one of the hook functions returns a non-nil value, it returns that value; otherwise it returns nil.

— Macro: with-wrapper-hook hook args &rest body

This macro runs the abnormal hook hook as a series of nested “wrapper functions” around the body forms. The effect is similar to nested around advices (see Around-Advice).

Each hook function should accept an argument list consisting of a function fun, followed by the additional arguments listed in args. The first hook function is passed a function fun that, if it is called with arguments args, performs body (i.e., the default operation). The fun passed to each successive hook function is constructed from all the preceding hook functions (and body); if this fun is called with arguments args, it does what the with-wrapper-hook call would if the preceding hook functions were the only ones in hook.

Each hook function may call its fun argument as many times as it wishes, including never. In that case, such a hook function acts to replace the default definition altogether, and any preceding hook functions. Of course, a subsequent hook function may do the same thing.

Each hook function definition is used to construct the fun passed to the next hook function in hook, if any. The last or “outermost” fun is called once to produce the overall effect.

When might you want to use a wrapper hook? The function filter-buffer-substring illustrates a common case. There is a basic functionality, performed by body—in this case, to extract a buffer-substring. Then any number of hook functions can act in sequence to modify that string, before returning the final result. A wrapper-hook also allows for a hook function to completely replace the default definition (by not calling fun).

— Function: run-hook-wrapped hook wrap-function &rest args

This function is similar to run-hook-with-args-until-success. Like that function, it runs the functions on the abnormal hook hook, stopping at the first one that returns non-nil. Instead of calling the hook functions directly, though, it actually calls wrap-function with arguments fun and args.