This chapter discusses the symbol as a Lisp data type. The Lisp system uses symbols as variables and function names, but these applications of symbols are discussed in chapter .

Each symbol has associated with it a value cell, which refers to one Lisp object. This object is called the symbol's value, since it is what you get when you evaluate the symbol as a dynamic variable in a program. Variables and how they work are described in . We also say the the symbol is bound to the object which is its value. The symbols nil and t are always bound to themselves; they may not be assigned, bound, or otherwise used as variables. The same is true of symbols in the keyword package.

The value cell can also be void, referring to no Lisp object, in which case the symbol is said to be void or unbound. This is the initial state of a symbol when it is created. An attempt to evaluate a void symbol causes an error.

Lexical variable bindings are not stored in symbol value cells. The functions in this section have no interaction with lexical bindings.

symbol symbol symeval is the basic primitive for retrieving a symbol's value. (symeval symbol) returns symbol's current binding. This is the function called by eval when it is given a symbol to evaluate. If the symbol is unbound, then symeval signals an error. symbol-value is the Common Lisp name for this function. symbol value set is the primitive for assignment of symbols. The symbol's value is changed to value; value may be any Lisp object. set returns value. Example: (set (cond ((eq a b) 'c) (t 'd)) 'foo) either sets c to foo or sets d to foo. (setf (symeval symbol) value) is a more modern way to do this. symbol t if symbol's value cell is not void. symbol Makes symbol's value cell void. Example: (setq a 1) a => 1 (makunbound 'a) a => causes an error. makunbound returns its argument. symbol Returns a locative pointer to symbol's value cell. See the section on locatives (). It is preferable to write (locf (symeval symbol)) which is equivalent, instead of calling this function explicitly. This is actually the internal value cell; there can also be an external value cell. For details, see the section on closures (). For historical compatibility, value-cell-location of a quoted symbol is recognized specially by the compiler and treated like variable-location (). However, such usage results in a compiler warning, and eventually this compatibility feature will be removed.

Every symbol also has associated with it a function cell. The function cell is similar to the value cell; it refers to a Lisp object. When a function is referred to by name, that is, when a symbol is passed to apply or appears as the car of a form to be evaluated, that symbol's function cell is used to find its definition, the functional object which is to be applied. For example, when evaluating (+ 5 6), the evaluator looks in +'s function cell to find the definition of +, in this case a compiled function object, to apply to 5 and 6.

Maclisp does not have function cells; instead, it looks for special properties on the property list. This is one of the major incompatibilities between the two dialects.

Like the value cell, a function cell can be void, and it can be bound or assigned. (However, to bind a function cell you must use the %bind subprimitive; see .) The following functions are analogous to the value-cell-related functions in the previous section.

symbol symbol Returns symbol's definition, the contents of its function cell. If the function cell is void, fsymeval signals an error. symbol-function is the Common Lisp name for this function. symbol definition Stores definition, which may be any Lisp object, into symbol's function cell. It returns definition. (setf (fsymeval symbol) definition) is a more modern way to do this. symbol nil if symbol's function cell is void, i.e. if symbol is undefined. Otherwise it returns t. symbol Causes symbol to be undefined, i.e. its function cell to be void. It returns symbol. symbol Returns a locative pointer to symbol's function cell. See the section on locatives (). It is preferable to write (locf (fsymeval symbol)) rather than calling this function explicitly.

Since functions are the basic building block of Lisp programs, the system provides a variety of facilities for dealing with functions. Refer to chapter for details.

Every symbol has an associated property list. See for documentation of property lists. When a symbol is created, its property list is initially empty.

The Lisp language itself does not use a symbol's property list for anything. (This was not true in older Lisp implementations, where the print-name, value-cell, and function-cell of a symbol were kept on its property list.) However, various system programs use the property list to associate information with the symbol. For instance, the editor uses the property list of a symbol which is the name of a function to remember where it has the source code for that function, and the compiler uses the property list of a symbol which is the name of a special form to remember how to compile that special form.

Because of the existence of print-name, value, function, and package cells, none of the Maclisp system property names (expr, fexpr, macro, array, subr, lsubr, fsubr, and in former times value and pname) exist in Zetalisp.

symbol Returns the list which represents the property list of symbol. Note that this is not actually a property list; you cannot do get on it. This value is like what would be the cdr of a property list. symbol-plist is the Common Lisp name. symbol list Sets the list which represents the property list of symbol to list. setplist is to be used with caution (or not at all), since property lists sometimes contain internal system properties, which are used by many useful system functions. Also it is inadvisable to have the property lists of two different symbols be eq, since the shared list structure will cause unexpected effects on one symbol if putprop or remprop is done to the other. setplist is equivalent to (setf (plist symbol) list) symbol Returns a locative pointer to the location of symbol's property-list cell. This locative pointer may be passed to get or putprop with the same results as if as symbol itself had been passed. It is preferable to write (locf (plist symbol)) rather than using this function.

Every symbol has an associated string called the print-name, or pname for short. This string is used as the external representation of the symbol: if the string is typed in to read, it is read as a reference to that symbol (if it is interned), and if the symbol is printed, print types out the print-name.

If a symbol is uninterned, #: is normally printed as a prefix before the symbol's print-name. If the symbol is interned, a package prefix may be printed, depending on the current package and how it relates to the symbol's home package.

For more information, see the sections on the reader (see ), printer (see ), and packages (see ).

symbol symbol Returns the print-name of the symbol symbol. Example: (symbol-name 'xyz) => "XYZ" get-pname is an older name for this function.

Every symbol has a package cell which, for interned symbols, is used to point to the package which the symbol belongs to. For an uninterned symbol, the package cell contains nil. For information about packages in general, see the chapter on packages, . For information about package cells, see .

The functions in this section are primitives for creating symbols. However, before discussing them, it is important to point out that most symbols are created by a higher-level mechanism, namely the reader and the intern function. Nearly all symbols in Lisp are created by virtue of the reader's having seen a sequence of input characters that looked like the printed representation (p.r.) of a symbol. When the reader sees such a p.r., it calls intern (see ), which looks up the sequence of characters in a big table and sees whether any symbol with this print-name already exists. If it does, read uses the already-existing symbol. If it does not, then intern creates a new symbol and puts it into the table; read uses that new symbol.

A symbol that has been put into such a table is called an interned symbol. Interned symbols are normally created automatically; the first time that someone (such as the reader) asks for a symbol with a given print-name, that symbol is automatically created.

These tables are called packages. For more information, turn to the chapter on packages ().

An uninterned symbol is a symbol that has not been recorded or looked up in a package. It is used simply as a data object, with no special cataloging. An uninterned symbol prints with a prefix #: when escaping is in use, unless *print-gensym* is nil. This allows uninterned symbols to be distinguishable and to read back in as uninterned symbols. See .

The following functions can be used to create uninterned symbols explicitly.

pname &optional permanent-p Creates a new uninterned symbol, whose print-name is the string pname. The value and function cells are void and the property list is empty. If permanent-p is specified, it is assumed that the symbol is going to be interned and probably kept around forever; in this case it and its pname are put in the proper areas. If permanent-p is nil (the default), the symbol goes in the default area and the pname is not copied. permanent-p is mostly for the use of intern itself. Examples: (setq a (make-symbol "foo")) => foo (symeval a) => ERROR! Note that the symbol is not interned; it is simply created and returned. symbol copy-props symbol copy-props Returns a new uninterned symbol with the same print-name as symbol. If copy-props is non-nil, then the value and function-definition of the new symbol are the same as those of symbol, and the property list of the new symbol is a copy of symbol's. If copy-props is nil, then the new symbol's function and value are void, and its property list is empty. &optional x Invents a print-name and creates a new symbol with that print-name. It returns the new, uninterned symbol. The invented print-name is a prefix (the value of si:*gensym-prefix) followed by the decimal representation of a number (the value of si:*gensym-counter), e.g. g0001. The number is increased by one every time gensym is called. If the argument x is present and is a fixnum, then si:*gensym-counter is set to x. If x is a string or a symbol, then si:*gensym-prefix is set to it, so it becomes the prefix for this and successive calls to gensym. After handling the argument, gensym creates a symbol as it would with no argument. Examples: if (gensym) => #:g0007 then (gensym 'foo) => #:foo0008 (gensym 32.) => #:foo0032 (gensym) => #:foo0033 Note that the number is in decimal and always has four digits. #: is the prefix normally printed before uninterned symbols. gensym is usually used to create a symbol which should not normally be seen by the user, and whose print-name is unimportant, except to allow easy distinction by eye between two such symbols. The optional argument is rarely supplied. The name comes from `generate symbol', and the symbols produced by it are often called ``gensyms''. &optional (prefix "t") (a-package package) Creates and returns a new symbol whose name starts with prefix, interned in a-package, and distinct from any symbol already present there. This is done by trying names one by one until a name not already in use is found, which may be very slow.