GNU emacs lisp: what does the with-wrapper-hook macro do? Could you provide a description and examples?

Question

I find the online help uninformative for this macro. Perhaps Stackoverflow can do better?

I am using emacs trunk (24.0.50.1) in case that makes a difference.

Thanks!

Answer 1

First you'll want to read in the manual on hooks, and possibly around advice which the documentation compares this macro to. The macro enables you to write code that can be wrapped around by some future code to change how it works.

(with-wrapper-hook hook-name ()
   your code here)

Then somebody else can add a function to hook-name that is something like this:

(defun my-hook (your-code)
   (let ((original-result (funcall your-code)))
      (modify original-result)))

The argument your-code stands for your code here above, encapsulated in a function object. The wrapper can call your original code with (funcall your-code), but it is not required to do so, in which case it completely overrides your code. The hook can even include several functions, each of which receives the next function as its first argument, so there can be a chain of wrappers, each modifying the results of the next one. It is also possible to define some additional arguments for each of these functions (that's what the empty parens above are for).

To find examples, you might want to grep around the source. One use is expand-abbrev:

(with-wrapper-hook abbrev-expand-functions () 
     ...)

The expand-abbrev function is used to, well, expand abbreviations, and it makes sense that you have a hook (abbrev-expand-functions) to customize how this is performed in different modes. This hook cannot be "normal", because it has to be able to modify the results, and it needs to be able to return some results to the calling code. (As explained in the documentation on hooks, a normal hook is called without arguments and its return value is ignored, so it is called only for its side effects on the buffer.)

The function on this hook can do its own abbrev expansion and ignore the wrapped code, or call the wrapped code and modify the results, or call the wrapped code many times with different inputs. An example of using that hook is mail-abbrev-expand-wrapper, which checks if you are typing a To: header in an email, and in that case expands your mail aliases instead of your standard abbreviations. The function modifies various pieces of the environment that affect abbrev expansion (the syntax table, the abbrev table) and then calls the wrapped function with (funcall expand) to do the actual work and returns its results directly.