Each symbol has associated with it a value cell , which refers to one Lisp object. This object is called the symbol's binding or value , since it is what you get when you evaluate the symbol. The binding of symbols to values allows symbols to be used as the implementation of variables in programs. 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. The binding of a symbol can be changed either by lambda-binding or by assignment . The difference is that when a symbol is lambda-bound, its previous value is saved away, to be restored later, whereas assignment discards the previous value. The symbols nil and t are always bound to themselves; they may not be assigned nor lambda-bound. (The error of changing the value of t or nil is not yet detected, but it will be.) When closures are in use, the situation is a little more complicated. See the section on closures. When a Lisp function is compiled , most of its variables are compiled into local variables , which are not represented by means of symbols. However the compiler recognizes usage of the setq special form, and of the set and value-cell-location functions with a quoted argument, as referring to variables rather than symbols, and generates the appropriate code to access the corresponding local variable rather than the symbol.

defvar symbol &optional initial-value Special Form
defvar is the recommended way to declare the use of a global variable in a program. Placed at top level in a file, it serves to initialize the variable, declare it special for the sake of compilation, and record the location for the sake of the editor so that you can ask to see where the variable is defined. It also provides a good place to put a comment describing the meaning of the variable (whereas an ordinary declare offers the temptation to declare several variables at once and not have room to describe them all). If the variable has a value already, that value is not changed. If initial-value is omitted, the variable is left unbound. defvar should be used only at top level, never in function definitions, and only for global variables (used by more than one function). (defvar foo 'bar) is equivalent to

(declare (special foo))
(or (boundp 'foo)
    (setq foo 'bar))

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 .

setq Special Form
The special form (setq var1 form1 var2 form2...) is the "variable assignment statement" of Lisp. First form1 is evaluated and the result is assigned to var1 , using set , then form2 is evaluated and the result is assigned to var2 , and so forth. setq returns the last value assigned, i.e. the result of the evaluation of its last argument.

Example:
(setq x (+ 3 2 1) y (cons x nil))

x is set to 6 , y is set to (6) , and the setq returns (6) . Note that the first assignment was performed before the second form was evaluated, allowing that form to use the new value of x .

symeval sym
symeval is the basic primitive for retrieving a symbols'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.

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

makunbound sym
makunbound causes sym to become unbound.

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

makunbound returns its argument.

value-cell-location sym
value-cell-location returns a locative pointer to sym 's value cell. See the section on locatives. [Must explain about external vs internal value cell.]

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 applied 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 FEF containing a compiled program, 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 empty, and it can be lambda-bound or assigned. The following functions are analogous to the value-cell related functions in the previous section.

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

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

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

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

function-cell-location sym
function-cell-location returns a locative pointer to sym 's function cell. See the section on locatives.

The usual means of putting a function in a symbol's function cell (defining the symbol) is by means of the defun special form. Macros are put in a symbol's function cell by means of the macro special form. Substitutable functions can be put there with the defsubst special form. Anything else requires the deff special form.

defun Special Form
defun is used for defining functions. A defun form looks like:

(defun name type lambda-list
       body )

The type is only for Maclisp compatibility, and is optional and usually absent. The lambda-list is as described on this link and may contain "&-keywords".

Examples:
(defun addone (x)
       (1+ x))

(defun foo (a &optional (b 5) c &rest e &aux j)
	(setq j (+ a b))
	(cond ((not (null c))
	       (cons j e))
	      (t j)))

A list (named-lambda name lambda-list . body) is left in the function cell of name . For compatibility, the Maclisp type s expr , fexpr , and macro , and Maclisp lexprs (which have an atomic lambda-list) are recognized and the corresponding Lisp Machine flavor of defun is assumed.

defsubst Special Form
defsubst is used for defining substitutable functions. It is used just like defun

(defsubst name  lambda-list  . body )

and does almost the same thing. It defines a function which executes identically to the one which a similar call to defun would define. The difference comes when a function which calls this one is compiled. Then, the call will be open-coded by substituting the substitutable function's definition into the code being compiled. Substitutable functions are a sort of cross between ordinary functions and macros; they can be applied like functions, but act like macros for the compiler. The actual definition looks like (subst lambda-list . body) . For example, if we define

(defsubst square (x) (* x x))

(defun foo (a b) (square (+ a b)))

then if foo is used interpreted, square will work just as if it had been defined by defun . If foo is compiled, however, the squaring will be substituted into it and it will compile just like

(defun foo (a b) (* (+ a b) (+ a b)))

You will notice that the substitution performed is very simple and takes no care about the possibility of computing an argument twice when it really ought to be computed once.

macro Special Form
macro is used for defining macros. Its form is:

(macro name  (arg )
       body )

Examples:
(macro addone (x)
       (list '1+ (cadr x)))

(macro increment (x)
       (list 'setq (cadr x) (list '1+ (cadr x))))

In the function cell of name is placed a cons whose car is the symbol macro , and whose cdr is a lambda -expression of the form (lambda (arg) . body) . Much of the time it is more convenient and clear to use a macro-defining macro such as defmacro (see LINK:(defmacro-fun)) to define macros.

deff Special Form
deff is used for giving a function a definition which is not obtainable with the specific defining forms such as defun and macro . It looks like

(deff name  definition )

where definition is evaluated so you can get any object you want. For example,

(deff foo 'bar)

will make foo equivalent to bar , with an indirection so that if bar changes foo will likewise change;

(deff foo (function bar))

copies the definition of bar into foo with no indirection, so that further changes to bar will have no effect on foo .

fset-carefully symbol definition &optional force-flag
This is the same as (fset symbol definition) except that it makes some checks and saves the old definition. defun , macro , undefun , load , and the compiler call fset-carefully when they define functions. fset-carefully prints a message and asks the user if the current package (value of package ) is not allowed to redefine the symbol . Specifying force-flag non-nil suppresses this check. The previous definition, if any, of symbol is saved on the :previous-definition property. If it is a list, it is also saved on the :previous-expr-definition property. These properties are used by the undefun function (LINK:(undefun-fun)), which restores the previous definition, and the uncompile function (LINK:(uncompile-fun)), which restores the previous interpreted definition. If symbol is not a symbol, but a list (name prop) , then the definition is put on name 's prop property, the package error check is not done, and the old definition is not saved. This is used to implement the (defun (name prop) ...) feature.

undefun symbol
If symbol has a :previous-definition property, undefun interchanges it with symbol 's function definition. This undoes the effect of a defun , compile , etc.

arglist function &optional literal-flag
arglist is given a function, and returns its best guess at the nature of the function's lambda -list. If function is a symbol, arglist of its function definition is used. If the function is an actual lambda -expression, its cadr , the lambda-list, is returned. But if function is compiled, arglist attempts to reconstruct the lambda -list of the original definition, using whatever debugging information was saved by the compiler. Sometimes the actual names of the bound variables are not available, and arglist uses the symbol *unknown* for these. Also, sometimes the initialization of an optional parameter is too complicated for arglist to reconstruct; for these it returns the symbol *hairy* . Some functions' real argument lists are not what would be most descriptive to a user. A function may take a &rest argument for technical reasons even though there are standard meanings for the first element of that argument. For such cases, the definition of the function can specify a value to be returned when the user asks about the argument list, with a local-declare . Example:

(def foo		;So the definition of foo can be found
  (local-declare ((arglist x y &rest z))
    (defun foo (&rest rest-arg) .....)))

literal-flag allows the caller of arglist to say that declared arglists of this sort should not be used. arglist cannot be relied upon to return the exactly correct answer, since some of the information may have been lost. Programs interested in how many and what kind of arguments there are should use args-info instead. arglist is a reliable way of getting the names of the arguments, if that information is available, provided the literal-flag argument is t . This inhibits use of arglist declarations.

args-info function
args-info returns a fixnum called the "numeric argument descriptor" of the function , which describes the way the function takes arguments. The information in it is stored in various bits and byte fields in the fixnum, which are referenced by the symbolic names shown below. By the usual Lisp Machine convention, those starting with a single "%" are bit-masks (meant to be logand ed with the number), and those starting with "%%" are byte descriptors (meant to be used with ldb ). Here are the fields:

%arg-desc-quoted-rest
	If this bit is set, the function has a "rest" argument, and it is "quoted". Most special forms have this bit.
%arg-desc-evaled-rest
	If this bit is set, the function has a "rest" argument, and it is not "quoted".
%arg-desc-fef-quote-hair
	If this bit is set, there are some quoted arguments other than the "rest" argument (if any), and the pattern of quoting is too complicated to describe here. The ADL (Argument Description List) in the FEF should be consulted.
%arg-desc-interpreted
	This function is not a compiled-code object, and a numeric argument descriptor cannot be computed. Usually args-info will not return this bit, although %args-info will.
%arg-desc-fef-bind-hair
	There is argument initialization, or something else too complicated to describe here. The ADL (Argument Description List) in the FEF should be consulted.
%%arg-desc-min-args
	This is the minimum number of arguments which may be passed to this function, i.e., the number of "required" parameters.
%%arg-desc-max-args
	This is the maximum number of arguments which may be passed to this function, i.e., the sum of the number of "required" parameters and the number of "optional" paramaters. If there is a rest argument, this is not really the maximum number of arguments which may be passed; an arbitrarily-large number of arguments is permitted, subject to limitations on the maximum size of a stack frame.

Note that %arg-desc-quoted-rest and %arg-desc-evaled-rest cannot both be set.

%args-info function
This is an internal function of args-info ; it is like args-info but only works for compiled-code objects. It exists because it has to be in the microcode anyway, for apply .

Every symbol has associated with it a property list , which is a list used for associating "attributes" with symbols. A property list has an even number of elements. Each pair of elements constitutes a property ; the first of the pair is a symbol called the indicator , and the second is a Lisp object called the value or, more loosely, the property . The indicator serves as the name of the property, and the value as the value of the property. Here is an example of the property list of a symbol named b1 which is being used by a program which deals with blocks:

It is also possible to have a "disembodied" property list, which is not associated with any symbol. A disembodied property list is a cons. Its car may be used for any purpose. The property list resides in its cdr. The way to create a disembodied property list is with (ncons nil) . In all of the functions in this section, disembodied property lists may be used as well as symbols; for brevity, the text speaks only of symbols.

get sym indicator
get looks up sym 's indicator property. If it finds such a property, it returns the value; otherwise, it returns nil .

Example: If the property list of foo  is (baz 3) (get 'foo 'baz) => 3
(get 'foo 'zoo) => nil

getl sym indicator-list
getl is like get , except that the second argument is a list of indicators. getl searches down sym 's property list for any of the indicators in indicator-list , until it finds a property whose indicator is one of the elements of indicator-list . getl returns the portion of sym 's property list beginning with the first such property which it found. So the car of the returned list is an indicator, and the cadr is the property value. If none of the indicators on indicator-list are on the property list, getl returns nil .

Example:
If the property list of  foo were 
(bar (1 2 3) baz (3 2 1) color blue height six-two)
then 
(getl 'foo '(baz height))
  => (baz (3 2 1) color blue height six-two)

putprop sym x indicator
This gives sym an indicator -property of x . After this is done, (get sym indicator) will return x .

Example:
(putprop 'Nixon 'not 'crook)

If sym already has a property with the name indicator , then that property is removed first; this insures that getl will always find the property that was added most recently.

defprop Special Form
defprop is a form of putprop with unevaluated arguments, which is sometimes more convenient for typing.

Example:
(defprop foo bar next-to)

is the same as

(putprop 'foo 'bar 'next-to)

remprop sym indicator
This removes sym 's indicator property, by splicing it out of the property list. It returns that portion of sym 's property list of which the former indicator -property was the car .

Example:
If the property list of foo was 
(color blue height six-three near-to bar)
then 
(remprop 'foo 'height) => (six-three near-to bar)
and foo's property list would be 
(color blue near-to bar)

If sym has no indicator -property, then remprop has no side-effect and returns nil .

plist sym
This returns the property list of sym .

setplist sym property-list
This sets the property list of sym to property-list . setplist is to be used with caution, 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.

property-cell-location sym
This returns a locative pointer to the location of sym 's property-list cell. See the section on locatives.

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 print ed, print types out the print-name. For more information, see the section on the reader (see LINK:(reader)) and printer (see LINK:(printer)).

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.

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 LINK:(string-equal-fun)).

get-pname sym
This returns the print-name of the symbol sym .

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

print-name-cell-location sym
This returns a locative pointer to the location of sym 's print-name cell. See the section on locatives. Note that the contents of this cell is not actually the print name, but the symbol header, an object which may not be directly manipulated. Use get-pname , the microcode primitive which knows how to extract the pname from the symbol header.

Normally, one wants to refer to the same symbol every time the same print-name-like string is typed. So, when read sees such a character-string in the input to Lisp, it looks in a table called the obarray for some symbol with that print-name. If it finds such a symbol, then that is what it returns; otherwise, it creates a symbol with that print-name (using the make-symbol function, see below), enters that symbol on the obarray, and returns it. The sub-function of read which performs these functions is called intern , and when a symbol has been entered on the obarray it is said to be interned . A symbol can also be uninterned , indicating that it is not on the obarray and cannot be referred to simply by typing its print name. Such symbols can be used as objects within a data-structure, but can cause trouble during debugging because they cannot be "typed in" directly, yet they look just like interned symbols when "typed out". Actually there can be many obarrays; the Lisp Machine system includes a feature called the package system (see LINK:(package)) which keeps track of multiple packages or name spaces and their interrelationships, using separate obarrays for each package.

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, the property list will be empty, and the package will be nil . If permanent-p is specified, the symbol is going to be interned and kept around forever; in this case it and its pname will be put in the proper areas. If permanent-p is nil (the default), nothing special is done with areas.

Examples:
(setq a (make-symbol "foo")) => foo
(symeval a) => ERROR!

Note that the symbol is not interned; it is simply created and returned.

copysymbol sym copy-p
This returns a new uninterned symbol with the same print-name as sym . If copy-p is non-nil , then the initial 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-p is nil , then the new symbol will be unbound and undefined, and its property list will be nil .

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 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 40) => 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".