13.1 Symbol Components

Each symbol has four components (or “cells”), each of which references another object:

Print name

The print name cell holds a string that names the symbol for reading and printing. See symbol-name in Creating Symbols.

Value

The value cell holds the current value of the symbol as a variable. When a symbol is used as a form, the value of the form is the contents of the symbol’s value cell. See symbol-value in Accessing Variables.

Function

The function cell holds the function definition of the symbol. When a symbol is used as a function, its function definition is used in its place. This cell is also used to make a symbol stand for a keymap or a keyboard macro, for editor command execution. Because each symbol has separate value and function cells, variables and function names do not conflict. See symbol-function in Function Cells.

Property list

The property list cell holds the property list of the symbol. See symbol-plist in Symbol Properties.

The print name cell always holds a string, and cannot be changed. The other three cells can be set individually to any specified Lisp object.

The print name cell holds the string that is the name of the symbol. Since symbols are represented textually by their names, it is important not to have two symbols with the same name. The Lisp reader ensures this: every time it reads a symbol, it looks for an existing symbol with the specified name before it creates a new one. (In SXEmacs Lisp, this lookup uses a hashing algorithm and an obarray; see Creating Symbols.)

In normal usage, the function cell usually contains a function or macro, as that is what the Lisp interpreter expects to see there (see Evaluation). Keyboard macros (see Keyboard Macros), keymaps (see Keymaps) and autoload objects (see Autoloading) are also sometimes stored in the function cell of symbols. We often refer to “the function foo” when we really mean the function stored in the function cell of the symbol foo. We make the distinction only when necessary.

The property list cell normally should hold a correctly formatted property list (see Property Lists), as a number of functions expect to see a property list there.

The function cell or the value cell may be void, which means that the cell does not reference any object. (This is not the same thing as holding the symbol void, nor the same as holding the symbol nil.) Examining a cell that is void results in an error, such as ‘Symbol's value as variable is void’.

The four functions symbol-name, symbol-value, symbol-plist, and symbol-function return the contents of the four cells of a symbol. Here as an example we show the contents of the four cells of the symbol buffer-file-name:

(symbol-name 'buffer-file-name)
     ⇒ "buffer-file-name"
(symbol-value 'buffer-file-name)
     ⇒ "/gnu/elisp/symbols.texi"
(symbol-plist 'buffer-file-name)
     ⇒ (variable-documentation 29529)
(symbol-function 'buffer-file-name)
     ⇒ #<subr buffer-file-name>

Because this symbol is the variable which holds the name of the file being visited in the current buffer, the value cell contents we see are the name of the source file of this chapter of the XEmacs Lisp Reference Manual. The property list cell contains the list (variable-documentation 29529) which tells the documentation functions where to find the documentation string for the variable buffer-file-name in the DOC file. (29529 is the offset from the beginning of the DOC file to where that documentation string begins.) The function cell contains the function for returning the name of the file. buffer-file-name names a primitive function, which has no read syntax and prints in hash notation (see Primitive Function Type). A symbol naming a function written in Lisp would have a lambda expression (or a byte-code object) in this cell.