16.4 When a Variable is “Void”

If you have never given a symbol any value as a global variable, we say that that symbol’s global value is void. In other words, the symbol’s value cell does not have any Lisp object in it. If you try to evaluate the symbol, you get a void-variable error rather than a value.

Note that a value of nil is not the same as void. The symbol nil is a Lisp object and can be the value of a variable just as any other object can be; but it is a value. A void variable does not have any value.

After you have given a variable a value, you can make it void once more using makunbound.

Function: makunbound symbol

This function makes the current binding of symbol void. Subsequent attempts to use this symbol’s value as a variable will signal the error void-variable, unless or until you set it again.

makunbound returns symbol.

(makunbound 'x)      ; Make the global value
                     ;   of x void.
     ⇒ x

x
error→ Symbol's value as variable is void: x

If symbol is locally bound, makunbound affects the most local existing binding. This is the only way a symbol can have a void local binding, since all the constructs that create local bindings create them with values. In this case, the voidness lasts at most as long as the binding does; when the binding is removed due to exit from the construct that made it, the previous or global binding is reexposed as usual, and the variable is no longer void unless the newly reexposed binding was void all along.

(setq x 1)               ; Put a value in the global binding.
     ⇒ 1
(let ((x 2))             ; Locally bind it.
  (makunbound 'x)        ; Void the local binding.
  x)
error→ Symbol's value as variable is void: x

x                        ; The global binding is unchanged.
     ⇒ 1

(let ((x 2))             ; Locally bind it.
  (let ((x 3))           ; And again.
    (makunbound 'x)      ; Void the innermost-local binding.
    x))                  ; And refer: it’s void.
error→ Symbol's value as variable is void: x

(let ((x 2))
  (let ((x 3))
    (makunbound 'x))     ; Void inner binding, then remove it.
  x)                     ; Now outer let binding is visible.
     ⇒ 2

A variable that has been made void with makunbound is indistinguishable from one that has never received a value and has always been void.

You can use the function boundp to test whether a variable is currently void.

Function: boundp variable

boundp returns t if variable (a symbol) is not void; more precisely, if its current binding is not void. It returns nil otherwise.

(boundp 'abracadabra)          ; Starts out void.
     ⇒ nil

(let ((abracadabra 5))         ; Locally bind it.
  (boundp 'abracadabra))
     ⇒ t

(boundp 'abracadabra)          ; Still globally void.
     ⇒ nil

(setq abracadabra 5)           ; Make it globally nonvoid.
     ⇒ 5

(boundp 'abracadabra)
     ⇒ t