Writing GNU Emacs Extensions

Macro Functions

Although limited-save-excursion works when we require its arguments to be quoted, it's cumbersome for the caller, and it doesn't really qualify as a substitute for save-excursion (since save-excursion doesn't have that restriction).

It is possible to write a special kind of function, called a macro function,^[31] that behaves as though its arguments are quoted. That is, when a macro function is invoked, its arguments are not evaluated before the function gets control. Instead, the macro function produces some value, typically a rearrangement of its arguments, and then that is evaluated.

Here's a simple example. Suppose we wanted a function called incr that could increment the value of a numeric variable. We'd like to be able to write:

(setq x 17)
(incr x)
x ⇒ 18

But if incr were an ordinary function, then it would be invoked with the argument 17, not x, and could not therefore affect x. So incr must be a macro function. Its output must be an expression that, when evaluated, adds one to the value of the variable named in its argument.

Macro functions are defined with defmacro (whose syntax resembles defun). The way to write incr is:

(defmacro incr (var)
  "Add one to the named variable."
  (list 'setq var (list '+ var 1)))

The body of a macro function produces an expansion of its input. The expansion then gets evaluated. The expansion of (incr x) is:

(setq x (+ x 1))

When that expression is evaluated, x is incremented.

You can debug macro functions using the function macroexpand ...