Emacs Lisp: Symbol

By Xah Lee. Date: . Last updated: .

What is Lisp Symbol

Lisp symbol is similar to Python/Java/JavaScript's identifiers (example: variable names and function names). But lisp symbol can be held unevaluated, and it can also store multiple values, including a Symbol Property List .

The Concept of Symbols in Lisp

One major way lisp differs from most programing languages (such as C, Java, Python, JavaScript) is that the language is said to be symbolic. Meaning, the identifiers (function names, variable names) , are “symbols”. This means, variable or function name isn't just values, can be just the symbol itself.

For example, in most languages, once you defined x=3, you cannot manipulate the variable “x” because it becomes 3 internally. In lisp, the x can be x itself.

In lisp, after (setq x 3) then x would evaluate to 3, but (quote x) evaluates to the symbol x itself.

For example, lets say you have a list of variable x = 4, y = 2, z = 3. you want to create new variables at run time, such that the new variable name are these variable with their value appended to the name, with new value that's old value plus 1.

(setq x 4)

;; create a new symbol,  whose name is old name with its value appended, set the value to plus 1 of original
(set
 (intern
  (concat
   (symbol-name 'x)
   (number-to-string (symbol-value 'x))))
 (1+ (symbol-value 'x)))

(symbol-value 'x4)
;; 5

In practice, having a language dealing with “symbols” directly means that transformation of expressions in source code is possible at run-time. (In lisp, this is the lisp macro feature, which is a limited form of term rewriting languages such as Wolfram Language .) Macros (ELISP Manual)

Quoting Symbol

Symbol's Cells

Each lisp symbol has the following “cells” to store things:

print name” cell
A string, the same as the symbol. Automatically set, cannot be changed.
value” cell
Store the symbol's value. When value cell is not void, the symbol is considered as a variable.
function” cell
Store function definition object, lisp macros, or other objects that can act as function.
property list” cell
Hold a list of name/value pairs. Used for storing meta info about the symbol, such as function state, font face spec (for syntax coloring), deprecation flag, etc.

A symbol's value cell or function cell may be empty. If so, it's said to be “void”. When you try to get a cell's value that's void, it's a lisp error. (a empty cell is not the same as having value of nil.)

Normally, you don't need to worry about any of these tech details. The only thing that's useful for most elisp code is property list.

Understanding Lisp Symbol is important when you do advanced lisp programing. For example: macros, create and call functions at run-time, nested functions, manipulate evaluation, implementing a language, or any sort of meta-programing. If you don't have a need, you should not exploit these facilities in your program. Keep your code simple.

Symbols (ELISP Manual)

Check If a Value is Symbol

symbolp
Return t if argument is a symbol.
(symbolp 3) ; nil
(symbolp 'x) ; t

Get Value of Symbol's Cells

Here's how to get various cell's values.

Here's a example of getting cell values, with symbol “sin” (sin is a builtin math function).

symbol-name
get symbol's name cell value
(symbol-name 'sin) ; "sin"
symbol-value
get symbol's value cell value
(symbol-value 'sin) ; void-variable error
;; because the value cell of the symbol sin is void
;; or, we just say that sin isn't a variable
symbol-function
get symbol's function cell value
(symbol-function 'sin) ;#<subr sin>
;; the value is a primitive function (written in C), and has print form of #<subr sin>
symbol-plist
get symbol's property list cell value
(symbol-plist 'sin) ; (side-effect-free t)

Set Symbol's Name Cell

Symbol's name cell is automatically set, as a string of the symbol name. Symbol name cell cannot be changed.

Set Symbol's Value Cell

The normal way to set a symbol's value cell is using setq.

;; set a symbol's value cell
(setq y "yes yes")

;; get it
(symbol-value 'y) ; "yes yes"

Setting Variables (ELISP Manual)

You can also check if a symbol's value cell is not empty, by boundp. (we think of it as checking if a variable is defined.)

(boundp 'h) ; nil

(setq h 4)

(boundp 'h) ; t

Set Symbol's Function Cell

The normal way to set a symbol's function cell is using defun or defmacro.

;; a function that returns 4
(defun z () 4)
;; Note: return value of defun is not defined

;; get a symbol's function cell value
(symbol-function 'z) ; (lambda nil 4)

Defining Functions (ELISP Manual)

Function Cells (ELISP Manual)

You can check if a symbol's function cell is not empty, by fboundp.

(fboundp 'f) ; nil

;; define a function that return 3
(defun f () 3)

;; now the fuction cell is filled
(fboundp 'f) ; t

Because a symbol can both hold a value and a function, a symbol can be both a variable and function. For example, the symbol buffer-file-name is both a variable and function. (you can try describe-function and describe-variable on it.)

Set Symbol's Property List Cell

Convert Symbol to String

;; convert a symbol to string
(symbol-name 'defun)

Convert String to Symbol

;; convert a string to symbol

;; if the symbol does not already exist in obarray, create it, put it in obarray
(intern "x")

;; if the symbol does not already exist in obarray, return nil
(intern-soft "x")

Lisp Symbol