The docs made me no wiser:

This function returns the value stored in symbol's value cell. This is where the variable's current (dynamic) value is stored. If the variable has no local binding, this is simply its global value. If the variable is void, a void-variable error is signaled.

What is the point of symbol-value? Where and when do I need to use it?

  • 3
    Thank you for trying to find the answer by asking Emacs. That is the right approach: ask Emacs first, and then ask here about whatever is still not clear, letting us know in your question what you have already tried. Kudos!
    – Drew
    Mar 10 '15 at 19:35

You need it when, in Elisp code, you want to get the value of a symbol, that is, its value when considered as a variable.

Keep in mind that an Elisp symbol has several characteristics/features:

  • It has a name (which function symbol-name gives)
  • It might have a value, when considered as a variable (which symbol-value gives)
  • It might name a function, when considered as a function (which symbol-function gives)
  • It has a property list (which symbol-plist gives)

Think of a symbol as an object, with various attributes.

  • 1
    Note also that (as the documentation indicates) symbol-value always returns the dynamic binding for the symbol. You cannot obtain lexical values this way.
    – phils
    Mar 10 '15 at 20:21
  • 2
    Also see C-h i g (elisp) Symbol Components RET for documentation on these various symbol cells/components.
    – phils
    Mar 10 '15 at 20:26
  • @phils: Hm, I wonder: (setq lexical-binding t) (let ((v 42)) (message "lex: %S, val: %S" lexical-binding (symbol-value 'v))). But yes, that is what it says at (elisp) Lexical Binding: "functions like symbol-value, boundp', and set' only retrieve or modify a variable's dynamic binding (i.e., the contents of its symbol's value cell)". However, nothing is said about it at Symbol Components.
    – Drew
    Mar 11 '15 at 0:06

(Doh, @Drew already put some of the following up. Anyway, here's some additional detail.)

As the manual page on symbol components explains, there are four components (cells) to each symbol: its print name cell, its value cell, its function definition, and its property list. Either the value cell or the function cell may be void, and the property list may be nil.

As the manual also points out:

Because each symbol has separate value and function cells, variables names and function names do not conflict.

That's why you can have, for example:

(setq test "kittens")
(defun test ()
  (message "puppies"))
(symbol-value 'test)    ; => "kittens"
(symbol-function 'test) ; => (lambda nil (message "puppies"))
  • 1
    Ah, that it is value as opposed to function made it much easier to understand. Thanks. Mar 10 '15 at 19:45

Here's a bit of historical reference (I haven't been born yet when the described events took place, so maybe someone more knowledgeable will correct me. All this is from reading old articles and some books).

Having dispensed with the disclaimer, it seems like back in the days of Fortran vs Lisp "symbolic" was a kind of a buzzword as "object oriented" is today. I.e. programs were typically seen as just huge mathematical formulae where numbers will eventually be plugged and the placeholders for numbers were immaterial. All symbolic information contained in a program would vanish as soon as that program was either run, compiled or interpreted. The novelty of Lisp was that it allowed symbols to persist in a program even after it is run, compiled or interpreted. This inspired such terminology as "symbolic algebra" (as in manipulation on algebraic formulae as done on paper / blackboard rather than by direct calculation). In order to support this (and other symbolic things) symbols were to be equipped with a name and some properties. From a non-symbolic point of view, one might say that "symbols are just named pointers", and while this isn't true, if anything they are more of pointers to structs, but for practical purposes, symbols are designators of the left hand side of a variable-value pair. This also makes it possible to see symbol-value function as pointer dereferencing in non-symbolic languages.

Modern Lisps vary in that how much values can be associated with one symbol (suppose you had a non-symbolic language with multiple memory stacks / heaps, you could imagine a situation where the same pointer has meaning when interpreted in the context of different stacks / heaps). So, Lisp2 languages (Emacs Lisp being one such language) have separate storage for functions and variables, this is why there's also a symbol-function, which "dereferences a pointer pointing to a function storage". Scheme doesn't have this special storage and Clojure AFAIK, doesn't have neither that nor symbol-plist.


Small demo:

(setq v1 10)
(setq v2 'v1)
(symbol-value v2)

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.