6. "Symbols"

6.1 "The Value Cell"

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

Symbols are often used as special variables. Variables and how they work are described in (variable-section). The symbols nil and t are always bound to themselves; they may not be assigned, bound, or otherwise used as variables. Attempting to change the value of nil or t (usually) causes an error.

The functions described here work on symbols, not variables in general. This means that the functions below won't work if you try to use them on local variables.

Function: set 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)

will either set c to foo or set d to foo.

Function: symeval sym

symeval is the basic primitive for retrieving a symbol's value. (symeval sym) returns sym'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 causes an error.

Function: boundp sym

boundp returns t if sym is bound; otherwise, it returns nil.

Function: makunbound sym

makunbound causes sym to become unbound.

Example: (setq a 1) a => 1 (makunbound 'a) a => causes an error.

makunbound returns its argument.

Function: value-cell-location sym

value-cell-location returns a locative pointer to sym's value cell. See the section on locatives ((locative)). It is preferable to write

(locf (symeval sym))

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 ((closure)).

Note: the function value-cell-location works on symbols that get converted to local variables (see (variable-section)); the compiler knows about it specially when its argument is a quoted symbol which is the name of a local variable. It returns a pointer to the cell that holds the value of the local variable.

6.2 "The Function Cell"

Function: fsymeval sym

fsymeval returns sym's definition, the contents of its function cell. If the function cell is empty, fsymeval causes an error.

Function: fset sym definition

fset stores definition, which may be any Lisp object, into sym's function cell. It returns definition.

Function: fboundp sym

fboundp returns nil if sym's function cell is empty, i.e. sym is undefined. Otherwise it returns t.

Function: fmakunbound sym

fmakunbound causes sym to be undefined, i.e. its function cell to be empty. It returns sym.

Function: function-cell-location sym

function-cell-location returns a locative pointer to sym's function cell. See the section on locatives ((locative)). It is preferable to write

(locf (fsymeval sym))

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 (function-chapter) for details.

6.3 "The Property List"

Every symbol has an associated property list. See (plist) 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.

Function: plist sym

This returns the list which represents the property list of sym. Note that this is not the property list itself; you cannot do get on it.

Function: setplist sym list

This sets the list which represents the property list of sym 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.

Function: property-cell-location sym

This returns a locative pointer to the location of sym's property-list cell. This locative pointer is equally valid as sym itself, as a handle on sym's property list.

6.4 "The Print Name"

Function: get-pname sym

This returns the print-name of the symbol sym.

Example: (get-pname 'xyz) => "xyz"

Function: samepnamep sym1 sym2

This predicate returns t if the two symbols sym1 and sym2 have equal print-names; that is, if their printed representation is the same. Upper and lower case letters are normally considered the same. If either or both of the arguments is a string instead of a symbol, then that string is used in place of the print-name. samepnamep is useful for determining if two symbols would be the same except that they are in different packages (see (package)).

Examples: (samepnamep 'xyz (maknam '(x y z)) => t (samepnamep 'xyz (maknam '(w x y)) => nil (samepnamep 'xyz "xyz") => t

This is the same function as string-equal (see (string-equal-fun)). samepnamep is provided mainly so that you can write programs that will work in Maclisp as well as Zetalisp; in new programs, you should just use string-equal.

6.5 The Package Cell

Every symbol has a package cell which is used, for interned symbols, 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, (package). For information about package cells, see (symbol-package-cell-discussion).

6.6 Creating Symbols

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 of a symbol. When the reader sees such a p.r., it calls intern (see (intern-fun)), 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, and 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 someone (such as the reader) asks for a symbol with a given print-name that symbol is automatically created.

These tables are called packages. In Zetalisp, interned symbols are the province of the package system. Although interned symbols are the most commonly used, they will not be discussed further here. For more information, turn to the chapter on packages ((package)).

An uninterned symbol is a symbol used simply as a data object, with no special cataloging. An uninterned symbol prints the same as an interned symbol with the same print-name, but cannot be read back in.

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

Function: make-symbol pname &optional permanent-p

This creates a new uninterned symbol, whose print-name is the string pname. The value and function bindings will be unbound and the property list will be 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 will be 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.

Function: copysymbol sym copy-props

This returns a new uninterned symbol with the same print-name as sym. If copy-props is non-nil, then the value and function-definition of the new symbol will be the same as those of sym, and the property list of the new symbol will be a copy of sym's. If copy-props is nil, then the new symbol will be unbound and undefined, and its property list will be empty.

Function: gensym &optional x

gensym 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 character 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 the first character of the string or of the symbol's print-name. After handling the argument, gensym creates a symbol as it would with no argument.

Examples: if (gensym) => g0007 then (gensym 'foo) => f0008 (gensym 32.) => f0032 (gensym) => f0033

Note that the number is in decimal and always has four digits, and the prefix is always one character.

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