GNU Info

Info Node: (elisp)Setting Variables

(elisp)Setting Variables


Next: Variable Scoping Prev: Accessing Variables Up: Variables
Enter node , (file) or (file)node

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