GNU Info
(elisp)Setting Variables
How to Alter a Variable Value
=============================
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 most-local
existing 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 sets SYMBOL's value to VALUE, then returns VALUE.
Since `set' is a function, the expression written for SYMBOL is
evaluated to obtain the symbol to set.
The most-local existing binding of the variable is the binding
that is set; shadowed bindings are not affected.
(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)
Logically speaking, `set' is a more fundamental primitive than
`setq'. Any use of `setq' can be trivially rewritten to use
`set'; `setq' could even be defined as a macro, given the
availability of `set'. However, `set' itself is rarely used;
beginners hardly need to know about it. It is useful only for
choosing at run time which variable to set. For example, the
command `set-variable', which reads a variable name from the user
and then sets the variable, needs to use `set'.
Common Lisp note: In Common Lisp, `set' always changes the
symbol's "special" or dynamic value, ignoring any lexical
bindings. In Emacs Lisp, all variables and all bindings are
dynamic, so `set' always affects the most local existing
binding.
One other function for setting a variable is designed to add an
element to a list if it is not already present in the list.
- Function: add-to-list symbol element
This function sets the variable SYMBOL by consing ELEMENT onto the
old value, if ELEMENT is not already a member of that value. It
returns the resulting list, whether updated or not. The value of
SYMBOL had better be a list already before the call.
The argument SYMBOL is not implicitly quoted; `add-to-list' is an
ordinary function, like `set' and unlike `setq'. Quote the
argument yourself if that is what you want.
Here's a scenario showing how to use `add-to-list':
(setq foo '(a b))
=> (a b)
(add-to-list 'foo 'c) ;; Add `c'.
=> (c a b)
(add-to-list 'foo 'b) ;; No effect.
=> (c a b)
foo ;; `foo' was changed.
=> (c a b)
An equivalent expression for `(add-to-list 'VAR VALUE)' is this:
(or (member VALUE VAR)
(setq VAR (cons VALUE VAR)))
automatically generated by info2www version 1.2.2.9