Elisp: Lisp Symbol

By Xah Lee. Date: . Last updated: .

Lisp has symbols concept. Lisp's concept of “symbols” is somewhat like identifiers in other languages, except that:

The Concept of Symbols in Lisp

LISP differs from most programing languages such as C, Java, Ruby, Python, in that it deals with symbols, as opposed to just identifiers and values.

For example, in most languages, once you defined x=3, you cannot manipulate the variable “x” because it gets evaluated to 3 right away. If you want, you have to build a string "x" and manipulate this string, then use eval(lots string join here) to achieve the effect. (for example, you have a variable x, and it has integer 3 as value. you want to rename the variable so the new name is var_name + var_value.)

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

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.) (info "(elisp) Macros")

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.

[see Elisp: Property List]

[see Elisp: Symbol 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.

(info "(elisp) Symbols")

Quoting Symbol

A symbol, typically gets evaluated to its value. But you can stop this, by quote. e.g. (quote x). You can think of quote as “hold evaluation”.

quote has a shortcut syntax.

(quote x) is syntactically equivalent to 'x

(info "(elisp) Quoting")

When to Quote Symbol?

Some functions, automatically quote the argument for you, as a convenience.

For example, setq always automatically quotes its first argument. Because you basically always want the argument passed as a symbol. So, you write (setq x 3) instead of (set 'x 3).

The function set is almost the same as setq, except that set does not automatically quote the first argument. So, you write (set 'x 3). (info "(elisp) Setting Variables")

Some functions, require you to quote the argument yourself. Because sometimes you want a symbol's value passed, and sometimes the symbol itself.

For example, mapcar's arguments are not automatically quoted. You may or may not want to quote them, depending on your use.

Here's two examples of using mapcar, where in one example we want to quote the argument, and in the other example we do not want to quote the argument.

;; suppose we have many functions
(setq f '1+)
(setq f 'cos)
(setq f 'sqrt)
;; we use f as a wrapper because we are not sure which function we want until run time

;; here's our data
(setq mylist '(1 2 3))

;; normally, when using mapcar, we want first arg quoted
(mapcar '1+ mylist) ; (2 3 4)

;; here, we don't want first arg quoted
(mapcar f mylist) ; (1.0 1.4142135623730951 1.7320508075688772)

Check If a Value is Symbol

;; check if a variable eval to a lisp symbol

;; make symbol x1's value cell to be 123
(setq x1 123 )

(symbolp x1) ; nil
;; nil, because x1 is evaluated, and that value is 123, not a symbol

(symbolp 'x1) ; 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).

;; get symbol's name cell value
(symbol-name 'sin) ; "sin"
;; 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
;; 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>
;; get symbol's property list cell value
(symbol-plist 'sin) ; (side-effect-free t)

Here's another example with a user defined symbol.

;; get symbol cell values

;; this makes symbol x1's value cell to contain the number 3
(setq x1 3) ; 3

;; get symbol's name cell value
(symbol-name 'x1) ; "x1"

;; get symbol's value cell value
(symbol-value 'x1) ; 3

;; get symbol's function cell value
(symbol-function 'x1) ; nil
;; in emacs 24.3.1, this is a void-function error
;; in emacs 25.1, this returns nil
;; elisp manual 24 and 25.1  say it should be error

;; get symbol's property list cell value
(symbol-plist 'x1) ;nil

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"

(info "(elisp) Setting Variables")

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)

(info "(elisp) Defining Functions")

(info "(elisp) Function Cells")

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

Elisp: Symbol Property List

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")

If you have a question, put $5 at patreon and message me on xah discord.
Or support me by Buy Xah Emacs Tutorial

Emacs Tutorial

Emacs Init

Emacs Keys


ELisp Examples

ELisp Write Major Mode



Basic Functions

Writing Command

Writing Script

Lisp Data Structure

Lisp Symbol

Elisp Misc