;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: 4The Value Cell* =Text: 3THE VALUE CELL* 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 4(EVAL-0)Evaluation*. Each symbol has associated with it a 1value cell*, which refers to one Lisp object. This object is called the symbol's 1value*, 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 4(EVAL-1)Variables and Bindings*. We also say the the symbol 1is bound to* the object which is its value. The symbols 2nil* and 2t* 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 1void*, referring to 1no* Lisp object, in which case the symbol is said to be void or 1unbound*. 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. 3symeval* 1symbol* 3symbol-value* 1symbol* 2symeval* is the basic primitive for retrieving a symbol's value. 2(symeval 1symbol*)* returns 1symbol*'s current binding. This is the function called by 2eval* when it is given a symbol to evaluate. If the symbol is unbound, then 2symeval* signals an error. 2symbol-value* is the Common Lisp name for this function. 3set* 1symbol* 1value* 2set* is the primitive for assignment of symbols. The 1symbol*'s value is changed to 1value*; 1value* may be any Lisp object. 2set* returns 1value*. Example: 3(set (cond ((eq a b) 'c)* 3 (t 'd))* 3 'foo)* either sets 2c* to 2foo* or sets 2d* to 2foo*. 2(setf (symeval 1symbol*) 1value*)* is a more modern way to do this. 3boundp* 1symbol* 2t* if 1symbol*'s value cell is not void. 3makunbound* 1symbol* Makes 1symbol*'s value cell void. Example: 3(setq a 1)* 3a => 1* 3(makunbound 'a)* 3a => 2causes an error.** 2makunbound* returns its argument. 3value-cell-location* 1symbol* Returns a locative pointer to 1symbol*'s value cell. See the section on locatives (4(LOCATIVES-0)Locatives*). It is preferable to write 3(locf (symeval 1symbol*))* 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 (4(CLOSURES-0)Closures*). For historical compatibility, 2value-cell-location* of a quoted symbol is recognized specially by the compiler and treated like 2variable-location* (4(EVAL-1)Setting Variables*). However, such usage results in a compiler warning, and eventually this compatibility feature will be removed. =Node: 4The Function Cell* =Text: 3THE FUNCTION CELL* Every symbol also has associated with it a 1function cell*. The 1function* cell is similar to the 1value* cell; it refers to a Lisp object. When a function is referred to by name, that is, when a symbol is passed to 2apply* or appears as the car of a form to be evaluated, that symbol's function cell is used to find its 1definition*, the functional object which is to be applied. For example, when evaluating 2(+ 5 6)*, the evaluator looks in 2+*'s function cell to find the definition of 2+*, 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 2%bind* subprimitive; see 4(SUBPRIMITIVES-2)Special-Binding Subprimitive*.) The following functions are analogous to the value-cell-related functions in the previous section. 3fsymeval* 1symbol* 3symbol-function* 1symbol* Returns 1symbol*'s definition, the contents of its function cell. If the function cell is void, 2fsymeval* signals an error. 2symbol-function* is the Common Lisp name for this function. 3fset* 1symbol* 1definition* Stores 1definition*, which may be any Lisp object, into 1symbol*'s function cell. It returns 1definition*. 2(setf (fsymeval 1symbol*) 1definition*)* is a more modern way to do this. 3fboundp* 1symbol* 2nil* if 1symbol*'s function cell is void, i.e. if 1symbol* is undefined. Otherwise it returns 2t*. 3fmakunbound* 1symbol* Causes 1symbol* to be undefined, i.e. its function cell to be void. It returns 1symbol*. 3function-cell-location* 1symbol* Returns a locative pointer to 1symbol*'s function cell. See the section on locatives (4(LOCATIVES-0)Locatives*). It is preferable to write 3(locf (fsymeval 1symbol*))* 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 4(FUNCTIONS-0)Functions* for details. =Node: 4The Property List* =Text: 3THE PROPERTY LIST* Every symbol has an associated property list. See 4(MANLISTSTR-2)Property Lists* 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 (2expr*, 2fexpr*, 2macro*, 2array*, 2subr*, 2lsubr*, 2fsubr*, and in former times 2value* and 2pname*) exist in Zetalisp. 3plist* 1symbol* 3symbol-plist* Returns the list which represents the property list of 1symbol*. Note that this is not actually a property list; you cannot do 2get* on it. This value is like what would be the cdr of a property list. 2symbol-plist* is the Common Lisp name. 3setplist* 1symbol* 1list* Sets the list which represents the property list of 1symbol* to 1list*. 2setplist* 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 2eq*, since the shared list structure will cause unexpected effects on one symbol if 2putprop* or 2remprop* is done to the other. 2setplist* is equivalent to 3(setf (plist 1symbol*) 1list*) property-cell-location* 1symbol* Returns a locative pointer to the location of 1symbol*'s property-list cell. This locative pointer may be passed to 2get* or 2putprop* with the same results as if as 1symbol* itself had been passed. It is preferable to write 3(locf (plist 1symbol*))* rather than using this function. =Node: 4The Print Name* =Text: 3THE PRINT NAME* Every symbol has an associated string called the 1print-name*, or 1pname* for short. This string is used as the external representation of the symbol: if the string is typed in to 2read*, it is read as a reference to that symbol (if it is interned), and if the symbol is printed, 2print* types out the print-name. If a symbol is uninterned, 3#:* 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 1reader* 4(READPRINT-2)What The Reader Accepts*, 1printer* 4(READPRINT-1)What the Printer Produces*, and packages 4(PACKAGES-0)Packages*. 3symbol-name* 1symbol* 3get-pname* 1symbol* Returns the print-name of the symbol 1symbol*. Example: 3(symbol-name 'xyz) => "XYZ"* 2get-pname* is an older name for this function. =Node: 4The Package Cell* =Text: 3THE PACKAGE CELL* Every symbol has a 1package 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 2nil*. For information about packages in general, see the chapter on packages, 4(PACKAGES-0)Packages*. For information about package cells, see 4(PACKAGES-1)Home Packages of Symbols*. =Node: 4Creating Symbols* =Text: 3CREATING 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 2intern* 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 2intern* (see 4(PACKAGES-2)Packages and Interning*), 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, 2read* uses the already-existing symbol. If it does not, then 2intern* creates a new symbol and puts it into the table; 2read* uses that new symbol. A symbol that has been put into such a table is called an 1interned* 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 1packages*. For more information, turn to the chapter on packages (4(PACKAGES-0)Packages*). An 1uninterned* 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 3#:* when escaping is in use, unless 2*print-gensym** is 2nil*. This allows uninterned symbols to be distinguishable and to read back in as uninterned symbols. See 4(READPRINT-1)Options that Control Printing*. The following functions can be used to create uninterned symbols explicitly. 3make-symbol* 1pname* &optional 1permanent-p* Creates a new uninterned symbol, whose print-name is the string 1pname*. The value and function cells are void and the property list is empty. If 1permanent-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 1permanent-p* is 2nil* (the default), the symbol goes in the default area and the pname is not copied. 1permanent-p* is mostly for the use of 2intern* itself. Examples: 3(setq a (make-symbol "foo")) => foo* 3(symeval a) => ERROR!* Note that the symbol is 1not* interned; it is simply created and returned. 3copysymbol* 1symbol* 1copy-props* 3copy-symbol* 1symbol* 1copy-props* Returns a new uninterned symbol with the same print-name as 1symbol*. If 1copy-props* is non-2nil*, then the value and function-definition of the new symbol are the same as those of 1symbol*, and the property list of the new symbol is a copy of 1symbol*'s. If 1copy-props* is 2nil*, then the new symbol's function and value are void, and its property list is empty. 3gensym* &optional 1x* 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 2si:*gensym-prefix*) followed by the decimal representation of a number (the value of 2si:*gensym-counter*), e.g. 2g0001*. The number is increased by one every time 2gensym* is called. If the argument 1x* is present and is a fixnum, then 2si:*gensym-counter* is set to 1x*. If 1x* is a string or a symbol, then 2si:*gensym-prefix* is set to it, so it becomes the prefix for this and successive calls to 2gensym*. After handling the argument, 2gensym* creates a symbol as it would with no argument. Examples: 2if3 (gensym) => #:g0007** 2then3 (gensym 'foo) => #:foo0008** 3 (gensym 32.) => #:foo0032* 3 (gensym) => #:foo0033* Note that the number is in decimal and always has four digits. 3#:* is the prefix normally printed before uninterned symbols. 2gensym* 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''. 3gentemp* &optional 1(prefix* 1"t")* 1(a-package* 1package)* Creates and returns a new symbol whose name starts with 1prefix*, interned in 1a-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.