12.8 Setting Variable Values

The usual way to change the value of a variable is with the special form setq. When you need to compute the choice of variable at run time, use the function set.

Special Form: setq [symbol form]… ¶

This special form is the most common method of changing a variable’s value. Each symbol is given a new value, which is the result of evaluating the corresponding form. The current binding of the symbol is changed.

setq does not evaluate symbol; it sets the symbol that you write. We say that this argument is automatically quoted. The ‘q’ in setq stands for “quoted”.

The value of the setq form is the value of the last form.

(setq x (1+ 2))
     ⇒ 3

x                   ; x now has a global value.
     ⇒ 3

(let ((x 5))
  (setq x 6)        ; The local binding of x is set.
  x)
     ⇒ 6

x                   ; The global value is unchanged.
     ⇒ 3

Note that the first form is evaluated, then the first symbol is set, then the second form is evaluated, then the second symbol is set, and so on:

(setq x 10          ; Notice that x is set before
      y (1+ x))     ;   the value of y is computed.
     ⇒ 11

Function: set symbol value ¶

This function puts value in the value cell of symbol. Since it is a function rather than a special form, the expression written for symbol is evaluated to obtain the symbol to set. The return value is value.

When dynamic variable binding is in effect (the default), set has the same effect as setq, apart from the fact that set evaluates its symbol argument whereas setq does not. But when a variable is lexically bound, set affects its dynamic value, whereas setq affects its current (lexical) value. See Scoping Rules for Variable Bindings.

(set one 1)
error→ Symbol's value as variable is void: one

(set 'one 1)
     ⇒ 1

(set 'two 'one)
     ⇒ one

(set two 2)         ; two evaluates to symbol one.
     ⇒ 2

one                 ; So it is one that was set.
     ⇒ 2
(let ((one 1))      ; This binding of one is set,
  (set 'one 3)      ;   not the global value.
  one)
     ⇒ 3

one
     ⇒ 2

If symbol is not actually a symbol, a wrong-type-argument error is signaled.

(set '(x y) 'z)
error→ Wrong type argument: symbolp, (x y)

Macro: setopt [symbol form]… ¶

This is like setq (see above), but meant for user options. This macro uses the Customize machinery to set the variable(s) (see Defining Customization Variables). In particular, setopt will run the setter function associated with the variable. For instance, if you have:

(defcustom my-var 1
  "My var."
  :type 'number
  :set (lambda (var val)
         (set-default var val)
         (message "We set %s to %s" var val)))

then the following, in addition to setting my-var to ‘2’, will also issue a message:

(setopt my-var 2)

setopt also checks whether the value is valid for the user option. For instance, using setopt to set a user option defined with a number type to a string will signal an error.

Unlike defcustom and related customization commands, such as customize-variable, setopt is meant for non-interactive use, in particular in the user init file. For that reason, it doesn’t record the standard, saved, and user-set values, and doesn’t mark the variable as candidate for saving in the custom file.

The setopt macro can be used on regular, non-user option variables, but is much less efficient than setq. The main use case for this macro is setting user options in the user’s init file.