Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 38 Β· Macros

Variable Capture, gensym and Multiple Evaluation

Understand the two classic macro bugs in Common Lisp, variable capture and multiple evaluation, and fix them with gensym, once-only style bindings and careful package use.

Macros are powerful because they paste code into someone else's program. That is also the danger: the pasted code lives next to the caller's variables. Two bugs account for most broken macros, and both have simple, reliable cures.

Lisp code below is read-only because no Common Lisp runtime exists on this site. The JavaScript examples are labelled stand-ins: a tiny evaluator that models let, so you can watch capture happen and disappear.

Bug 1: variable capture

Here is a swap macro that uses a temporary variable:

LISP
(defmacro bad-swap (a b)
  `(let ((tmp ,a))
     (setf ,a ,b)
     (setf ,b tmp)))

(let ((x 1) (y 2))
  (bad-swap x y)
  (list x y))        ; => (2 1)   fine

It works until the caller's own variable is called tmp:

LISP
(let ((tmp 1) (other 2))
  (bad-swap tmp other)
  (list tmp other))  ; => (1 2)   nothing happened!

The expansion is (let ((tmp tmp)) (setf tmp other) (setf other tmp)). The macro's tmp captured the caller's tmp. The macro author and the macro user never agreed on the name, yet the code collides.

JS Stand-in: capture in a tiny evaluator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The cure: gensym

gensym creates a fresh, uninterned symbol that cannot be written by any other code, because it is a different object even if its printed name matches.

LISP
(defmacro swap (a b)
  (let ((tmp (gensym "TMP")))
    `(let ((,tmp ,a))
       (setf ,a ,b)
       (setf ,b ,tmp))))

The macro body runs at expansion time and creates the symbol; the template inserts it with a comma. Each expansion gets a new name (printed like #:TMP123). (gensym "TMP") uses the prefix only for readability in expansions. When a macro needs several temporaries, loop over names or use with-gensyms, a small utility macro found in the Alexandria library:

LISP
(defmacro with-gensyms ((&rest names) &body body)
  `(let ,(mapcar (lambda (n) `(,n (gensym ,(string n)))) names)
     ,@body))

Bug 2: multiple evaluation

A macro that pastes an argument into the expansion more than once evaluates it more than once:

LISP
(defmacro bad-square (x) `(* ,x ,x))

(let ((n 3))
  (bad-square (incf n)))   ; (* (incf n) (incf n)) => 4 * 5 = 20, not 16

The fix is to evaluate the argument once, into a gensym-named variable:

LISP
(defmacro square (x)
  (let ((v (gensym "V")))
    `(let ((,v ,x))
       (* ,v ,v))))

Note that this also fixes the order of evaluation: arguments to a macro should be evaluated in the order they were written, left to right, unless the macro documents otherwise.

JS Stand-in: gensym fixes both bugs

Press Run (or Ctrl + Enter) to see the console output here.

No output.

What about functions and special variables?

Capture can also affect function names and special operators: if your macro expands into a call to list and the user locally defines (flet ((list ...))), your code calls theirs. Common Lisp forbids redefining standard functions with flet or labels in conforming code, which protects list, car and friends. Your own helper functions in a package are not protected, so keep them in your package and refer to them with that package's symbols. The macro's expansion keeps those symbols, not strings, so the reader resolves them in your package, not the caller's.

For variables the user rarely controls, an alternative to gensym is a package-private name, but this only helps if nobody else works in that package, so gensym remains the safe default.

A checklist for every macro

  1. Does the expansion introduce any variable? Use gensym for it.
  2. Is any argument used more than once, or not at all? Bind it once to a gensym-named variable.
  3. Are arguments evaluated in the order the user wrote them?
  4. Are keyword/body arguments spliced with ,@?
  5. Did you test the macro with a variable named like one of your temporaries?
LISP
;; A reusable pattern: evaluate the arguments once, in order.
(defmacro my-max (a b)
  (let ((x (gensym)) (y (gensym)))
    `(let ((,x ,a) (,y ,b))
       (if (> ,x ,y) ,x ,y))))

Check your understanding

Quick check Β· 4 questions

of 4 answered You scored / 4 Β· perfect!

  1. 1. What does (gensym) return?

    An uninterned symbol is a distinct object, so it cannot clash with any symbol the caller wrote.
  2. 2. (bad-square (incf n)) where bad-square is (* ,x ,x) has which problem?

    The argument form appears twice in the expansion, so incf runs twice.
  3. 3. Variable capture happens when…

    The macro and its caller use the same name for different purposes in the same expansion.
  4. 4. Where should the call to gensym run?

    Create the name while expanding, then insert it with ,tmp everywhere it is needed so each expansion has its own.

Summary

  • Capture: a variable introduced by the macro collides with the caller's variables; fix it with gensym.
  • Multiple evaluation: an argument pasted more than once runs more than once; bind it once.
  • Create gensyms in the macro body and insert them with commas; use with-gensyms for several.
  • Test each macro with unlucky variable names and with arguments that have side effects.
  • The JavaScript evaluator is a stand-in that makes capture visible.

Next: Macro Patterns and Control Structures