In Zetalisp, variables are implemented using symbols. Symbols are used for many things in the language, such as naming functions, naming special forms, and being keywords; they are also useful to programs written in Lisp, as parts of data structures. But when a symbol is evaluated, its value as a variable is taken.

In Lisp, a variable is something that can remember one piece of data. The primary conceptual operations on a variable are to recover that piece of data and to change it. These might be called access and update. The concept of variables named by symbols, explained above, can be generalized to any storage location that can remember one piece of data, no matter how that location is named.

For each kind of generalized variable, there are typically three functions which implement the conceptual access, update and locate operations. For example, symeval accesses a symbol's value cell, set updates it, and value-cell-location returns the value cell's location. array-leader accesses the contents of an array leader element, store-array-leader updates it, and ap-leader returns the location of the leader element. car accesses the car of a cons, rplaca updates it, and car-location returns the location of the car.

Rather than thinking of this as two functions, which operate on a storage location somehow deduced from their arguments, we can shift our point of view and think of the access function as a name for the storage location. Thus (symeval 'foo) is a name for the value of foo, and (aref a 105) is a name for the 105th element of the array a. Rather than having to remember the update function associated with each access function, we adopt a uniform way of updating storage locations named in this way, using the setf special form. This is analogous to the way we use the setq special form to convert the name of a variable (which is also a form which accesses it) into a form that updates it. In fact, setf is an upward compatible generalization of setq. Similarly, the location of the generalized variable can be obtained using the locf construct.

In the description of evaluation on , we said that evaluation of a function form works by applying the function to the results of evaluating the argument subforms. What is a function, and what does it mean to apply it? In Zetalisp there are many kinds of functions, and applying them may do many different kinds of things. For full details, see . Here we explain the most basic kinds of functions and how they work. In particular, this section explains lambda lists and all their important features.

The simplest kind of user-defined function is the lambda-expression, which is a list that looks like: (lambda lambda-list body1 body2...) The first element of the lambda-expression is the symbol lambda; the second element is a list called the lambda list, and the rest of the elements are called the body. The lambda list, in its simplest form, is just a list of variables. Assuming that this simple form is being used, here is what happens when a lambda expression is applied to some arguments. First, the number of arguments and the number of variables in the lambda list must be the same, or else an error is signaled. Each variable is bound to the corresponding argument value. Then the forms of the body are evaluated sequentially. After this, the bindings are all undone, and the value of the last form in the body is returned.

This may sound something like the description of let, above. The most important difference is that the lambda-expression is not a form at all; if you try to evaluate a lambda-expression, you get an error because lambda is not a defined function. The lambda-expression is a function, not a form. A let form gets evaluated, and the values to which the variables are bound come from the evaluation of some subforms inside the let form; a lambda-expression gets applied, and the values are the arguments to which it is applied.

The variables in the lambda list are sometimes called parameters, by analogy with other languages. Some other terminologies would refer to these as formal parameters, and to arguments as actual parameters.

Lambda lists can have more complex structure than simply being a list of variables. There are additional features accessible by using certain keywords (which start with &) and/or lists as elements of the lambda list.

The principal weakness of simple lambda lists is that any function written with one must only take a certain, fixed number of arguments. As we know, many very useful functions, such as list, append, +, and so on, accept a varying number of arguments. Maclisp solved this problem by the use of lexprs and lsubrs, which were somewhat inelegant since the parameters had to be referred to by numbers instead of names (e.g. (arg 3)). (For compatibility reasons, Zetalisp supports lexprs, but they should not be used in new programs.) Simple lambda lists also require that arguments be matched with parameters by their position in the sequence. This makes calls hard to read when there are a great many arguments. Keyword parameters enable the use of other, more readable styles of call.

In general, a function in Zetalisp has zero or more positional parameters, followed if desired by a single rest parameter, followed by zero or more keyword parameters. The positional parameters may be required or optional, but all the optional parameters must follow all the required ones. The required/optional distinction does not apply to the rest parameter; all keyword parameters are optional.

The caller must provide enough arguments so that each of the required parameters gets bound, but he may provide extra arguments for some of the optional parameters. Also, if there is a rest parameter, he can provide as many extra arguments as he wants, and the rest parameter is bound to a list of all these extras. Optional parameters may have a default-form, which is a form to be evaluated to produce the default value for the parameter if no argument is supplied.

Positional parameters are matched with arguments by the position of the arguments in the argument list. Keyword parameters are matched with their arguments by matching the keyword name; the arguments need not appear in the same order as the parameters. If an optional positional argument is omitted, then no further arguments can be present. Keyword parameters allow the caller to decide independently for each one whether to specify it.

Here is the exact algorithm used to match up the arguments with the parameters:

Required positional parameters:	The first required positional parameter is bound to the first argument. apply continues to bind successive required positional parameters to the successive arguments. If, during this process, there are no arguments left but there are still some required parameters which have not been bound yet, it is an error (``too few arguments'').
Optional positional parameters:	After all required parameters are handled, apply continues with the optional positional parameters, if any. It binds each successive parameter to the next argument. If, during this process, there are no arguments left, each remaining optional parameter's default-form is evaluated, and the parameter is bound to it. This is done one parameter at a time; that is, first one default-form is evaluated, and then the parameter is bound to it, then the next default-form is evaluated, and so on. This allows the default for an argument to depend on the previous argument.
After the positional parameters:	Now, if there are no remaining parameters (rest or keyword), and there are no remaining arguments, we are finished. If there are no more parameters but there are still some arguments remaining, an error is signaled (``too many arguments''). If parameters remain, all the remaining arguments are used for both the rest parameter, if any, and the keyword parameters.
Rest parameter:	If there is a rest parameter, it is bound to a list of all the remaining arguments. If there are no remaining arguments, it is bound to nil.
Keyword parameters:	If there are keyword parameters, the same remaining arguments are used to bind them, as follows. The arguments for the keyword parameters are treated as a list of alternating keyword symbols and associated values. Each symbol is matched with eq against the allowed parameter keywords, which have by default the same names as the parameters but in the keyword package. (You can specify the keyword symbol explicitly in the lambda list if you must; see below.) Often the symbol arguments are constants in the program, and it is convenient for this usage that keywords all evaluate to themselves, but it is permissible for them to be computed by expressions. If any keyword parameter has not received a value when all the arguments have been processed, the default-form for the parameter is evaluated and the parameter is bound to its value. All keyword parameters are optional. There may be a keyword symbol among the arguments which does not match any keyword parameter name. By default this is an error, but the lambda list can specify that there should be no error using &allow-other-keys. Also, if one of the keyword symbols among the arguments is :allow-other-keys and the value that follows it is non-nil then there is no error. When there is no error, for either reason, the non-matching symbols and their associated values are simply ignored. The function can access these symbols and values through the rest parameter, if there is one. It is common for a function to check only for certain keywords, and pass its rest parameter to another function using apply; that function will check for the keywords that concern it.

The way you express which parameters are required, optional, rest and keyword is by means of specially recognized symbols, which are called &-keywords, in the lambda list. All such symbols' print names begin with the character `&'. A list of all such symbols is the value of the symbol lambda-list-keywords.

The keywords used here are &key, &optional and &rest. The way they are used is best explained by means of examples; the following are typical lambda lists, followed by descriptions of which parameters are positional, rest or keyword; and required or optional. (foo :a '(some elements) :b 69) (foo :a '(some elements)) This illustrates that the parameters can be matched in either order, or omitted. If a keyword is specified twice, the first value is used.

or

or

(a b c)	a, b, and c are all required and positional. The function must be passed three arguments.
(a b &optional c)	a and b are required, c is optional. All three are positional. The function may be passed either two or three arguments.
(&optional a b c)	a, b, and c are all optional and positional. The function may be passed zero, one, two or three arguments.
(&rest a)	a is a rest parameter. The function may be passed any number of arguments.
(a b &optional c d &rest e)	a and b are required positional, c and d are optional positional, and e is rest. The function may be passed two or more arguments.
(&key a b)	a and b are both keyword parameters. A typical call would look like (foo :b 69 :a '(some elements))
(x &optional y &rest z &key a b)	x is required positional, y is optional positional, z is rest, and a and b are keyword. One or more arguments are allowed. One or two arguments specify only the positional parameters. Arguments beyond the second specify both the rest parameter and the keyword parameters, so that (foo 1 2 :b '(a list)) specifies 1 for x, 2 for y, (:b (a list)) for z, and (a list) for b. It does not specify a.
(&rest z &key a b c &allow-other-keys)	z is rest, and a, b and c are keyword parameters. &allow-other-keys says that absolutely any keyword symbols may appear among the arguments; these symbols and the values that follow them have no effect on the keyword parameters, but do become part of the value of z.
(&rest z &key &allow-other-keys)	This is equivalent to (&rest z). So, for that matter, is the previous example, if the function does not use the values of a, b and c.

In all of the cases above, the default-form for each optional parameter is nil. To specify your own default forms, instead of putting a symbol as the element of a lambda list, put in a list whose first element is the symbol (the parameter itself) and whose second element is the default-form. Only optional parameters may have default forms; required parameters are never defaulted, and rest parameters always default to nil. For example:

(a &optional (b 3))

The default-form for b is 3. a is a required parameter, and so it doesn't have a default form.

(&optional (a 'foo) &rest d &key b (c (symeval a)))

a's default-form is 'foo, b's is nil, and c's is (symeval a). Note that if the function were called on no arguments, a would be bound to the symbol foo, and c would be bound to the value of the symbol foo; this illustrates the fact that each variable is bound immediately after its default-form is evaluated, and so later default-forms may take advantage of earlier parameters in the lambda list. b and d would be bound to nil.

Occasionally it is important to know whether a certain optional parameter was defaulted or not. Just by looking at the value one cannot distinguish between omitting it and passing the default value explicitly as an argument. The way to tell for sure is to put a third element into the list: the third element should be a variable (a symbol), and that variable is bound to nil if the parameter was not passed by the caller (and so was defaulted), or t if the parameter was passed. The new variable is called a ``supplied-p'' variable; it is bound to t if the parameter is supplied. For example:

(a &optional (b 3 c))

The default-form for b is 3, and the supplied-p variable for b is c. If the function is called with one argument, b is bound to 3 and c is bound to nil. If the function is called with two arguments, b is bound to the value that was passed by the caller (which might be 3), and c is bound to t.

It is possible to specify a keyword parameter's symbol independently of its parameter name. To do this, use two nested lists to specify the parameter. The outer list is the one which can contain the default-form and supplied-p variable, if the parameter is optional. The first element of this list, instead of a symbol, is again a list, whose elements are the keyword symbol and the parameter variable name. For example:

(&key ((:a a)) ((:b b) t))	This is equivalent to (&key a (b t)).
(&key ((:base base-value)))	This defines an argument which callers specify with the keyword :base, but which within the function is referred to as the variable base-value so as to avoid binding the value of base, which is a synonym for *print-base* and controls how numbers are printed.

It is also possible to include, in the lambda list, some other symbols, which are bound to the values of their default-forms upon entry to the function. These are not parameters, and they are never bound to arguments; they just get bound, as if they appeared in a let* form. (Whether you use aux-variables or bind the variables with let* is a stylistic decision.)

To include such symbols, put them after any parameters, preceeded by the &-keyword &aux. Examples:

(a &optional b &rest c &aux d (e 5) (f (cons a e)))

d, e, and f are bound, when the function is called, to nil, 5, and a cons of the first argument and 5. You could, equivalently, use (a &optional b &rest c) as the lamda list and write (let* (d (e 5) (f (cons a e))) ...) around the body of the function.

It is important to realize that the list of arguments to which a rest-parameter is bound is set up in whatever way is most efficiently implemented, rather than in the way that is most convenient for the function receiving the arguments. It is not guaranteed to be a ``real'' list. Sometimes the rest-args list is a stack list (see ) stored in the function-calling stack, and loses its validity when the function returns. If a rest-argument is to be returned or made part of permanent list-structure, it must first be copied (see copylist, ), as you must always assume that it is one of these special lists. The system does not detect the error of omitting to copy a rest-argument; you will simply find that you have a value which seems to change behind your back.

At other times the rest-args list may be an argument that was given to apply; therefore it is not safe to rplaca this list as you may modify permanent data structure. An attempt to rplacd a rest-args list is unsafe in this case, while in the first case it would cause an error, since lists in the stack are impossible to rplacd.

This section describes some functions and special forms. Some are parts of the evaluator, or closely related to it. Some have to do specifically with issues discussed above such as keyword arguments. Some are just fundamental Lisp forms that are very important.

Note: the Maclisp functions subrcall, lsubrcall, and arraycall are not needed on the Lisp Machine; funcall is just as efficient. arraycall is provided for compatibility; it ignores its first subform (the Maclisp array type) and is otherwise identical to aref. subrcall and lsubrcall are not provided.

Declarations provide auxiliary information on how to execute a function or expression properly. The most important declarations are special declarations, which control the scope of variable names. Some declarations do not affect execution at all and only provide information about a function, for the sake of arglist, for example.

Declarations may apply to an entire function or to any expression within it. Declarations can be made around any subexpression by writing a local-declare around the subexpression or by writing a declare at the front of the body of certain constructs. Declarations can be made on an entire function by writing a declare at the front of the function's body.

Here is a list of declarations that have system-defined meanings:

(special var1 var2 ...)	The variables var1, var2, etc. will be treated as special variables in the scope of the declaration.
(unspecial var1 var2 ...)	The variables var1, var2, etc. will be treated as lexical variables in the scope of the declaration, even if they are globally special.
(notinline fun1 fun2 ...)	The functions fun1, fun2 and so on will not be open coded or optimized by the compiler within the scope of the declaration.
(inline fun1 fun2 ...)	The functions fun1, fun2 and so on will be open coded or optimized by the compiler (to whatever extent it knows how) within the scope of the declaration. Merely issuing this declaration does not tell the compiler how to do any useful optimization or open coding of a function.
(ignore var1 var2 ...)	Says that the variables var1, var2, etc., which are bound in the construct in which this declaration is found, are going to be ignored. This is currently significant only in a function being compiled; the compiler issues a warning if the variables are used, and refrains from its usual warning if the variables are ignored.
(declaration decl1 decl2 ...)	Says that declarations decl1, decl2, etc. are going to be used, and prevents any warning about an unrecognized type of declaration. For example: (defun hack () (declare (declaration lose-method) (lose-method foo bar)) ... (lose foo) ...) might be useful if (lose foo) is a macro whose expander function does (getdecl 'foo 'lose-method) to see what to do. See for more information on getdecl and declarations. (proclaim '(declaration lose-method)) might also be advisable if you expect widespread use of lose-method declarations.

The next two are used by the compiler and generally should not be written by users.

(def name . definition)	name will be defined for the compiler in the scope of the declaration. The compiler uses this automatically to keep track of macros and open-codable functions (defsubsts) defined in the file being compiled. Note that the cddr of this item is a function.
(propname symbol value)	(getdecl symbol propname) will return value in the scope of the declaration. This is how the compiler keeps track of defdecls.

These declarations are significant only when they apply to an entire defun.

(arglist . arglist)	Records arglist as the argument list of the function, to be used instead of its lambda list if anyone asks what its arguments are. This is purely documentation.
(values . values) or (:return-list . values)	Records values as the return values list of the function, to be used if anyone asks what values it returns. This is purely documentation.
(sys:function-parent parent-function-spec)	Records parent-function-spec as the parent of this function. If, in the editor, you ask to see the source of this function, and the editor doesn't know where it is, the editor will show you the source code for the parent function instead. For example, the accessor functions generated by defstruct have no defuns of their own in the text of the source file. So defstruct generates them with sys:function-parent declarations giving the defstruct's name as the parent function spec. Visiting the accessor function with Meta-. sees the declaration and therefore visits the text of the defstruct.
(:self-flavor flavorname)	Instance variables of the flavor flavorname, in self, will be accessible in the function.

When one function ends by calling another function (possibly itself), as in (defun last (x) (cond ((atom x) x) ((atom (cdr x)) x) (t (last (cdr x))))) it is called tail recursion. In general, if X is a form, and Y is a sub-form of X, then if the value of Y is unconditionally returned as the value of X, with no intervening computation, then we say that X tail-recursively evaluates Y.

In a tail recursive situation, it is not strictly necessary to remember anything about the first call to last when the second one is activated. The stack frame for the first call can be discarded completely, allowing last to use a bounded amount of stack space independent of the length of its argument. A system which does this is called tail recursive.

The Lisp machine system works tail recursively if the variable tail-recursion-flag is non-nil. This is often faster, because it reduces the amount of time spent in refilling the hardware's pdl buffer. However, you forfeit a certain amount of useful debugging information: once the outer call to last has been removed from the stack, you can no longer see its frame in the debugger.

There are many things which a function can do that can make it dangerous to discard its stack frame. For example, it may have done a *catch; it may have bound special variables; it may have a &rest argument on the stack; it may have asked for the location of an argument or local variable. The system detects all of these conditions automatically and retains the stack frame to ensure proper execution. Some of these conditions occur in eval; as a result, interpreted code is never completely tail recursive.

The Lisp Machine includes a facility by which the evaluation of a form can produce more than one value. When a function needs to return more than one result to its caller, multiple values are a cleaner way of doing this than returning a list of the values or setq'ing special variables to the extra values. In most Lisp function calls, multiple values are not used. Special syntax is required both to produce multiple values and to receive them.

The primitive for producing multiple values is values, which takes any number of arguments and returns that many values. If the last form in the body of a function is a values with three arguments, then a call to that function returns three values. Many system functions produce multiple values, but they all do it via values.

return and its variants can also be used, within a block, do or prog special form, to return multiple values. They are explained on .

Here are the special forms for receiving multiple values.

When one form finished by tail recursively evaluating a subform (see ), all of the subform's multiple values are passed back by the outer form. For example, the value of a cond is the value of the last form in the selected clause. If the last form in that clause produces multiple values, so does the cond. This passing-back of multiple values of course has no effect unless eventually one of the special forms for receiving multiple values is reached.

If the outer form returns a value computed by a subform, but not in a tail recursive fashion (for example, if the value of the subform is examined first), multiple values or only single values may be returned at the discretion of the implementation; users should not depend on whatever way it happens to work, as it may change in the future or in other implementations. The reason we don't guarantee non-transmission of multiple values is because such a guarantee would not be very useful and the efficiency cost of enforcing it would be high. Even setq'ing a variable to the result of a form, then returning the value of that variable, might pass multiple values if an optimizing compiler realized that the setq'ing of the variable was unnecessary. Since extra returned values are generally ignored, it is not vital to eliminate them.

Note that use of a form as an argument to a function never receives multiple values from that form. That is, if the form (foo (bar)) is evaluated and the call to bar returns many values, foo is still called on only one argument (namely, the first value returned), rather than being called on all the values returned. We choose not to generate several separate arguments from the several values, because this would make the source code obscure; it would not be syntactically obvious that a single form does not correspond to a single argument. To pass all returned values to another function, use multiple-value-call, above.

For clarity, descriptions of the interaction of several common special forms with multiple values follow. This can all be deduced from the rule given above. Note well that when it says that multiple values are not returned, it really means that they may or may not be returned, and you should not write any programs that depend on which way it actually works.

The body of a defun or a lambda, and variations such as the body of a function, the body of a let, etc., pass back multiple values from the last form in the body.

eval, apply and funcall, pass back multiple values from the function called.

progn passes back multiple values from its last form. progv and progw do so also. prog1 and prog2, however, do not pass back multiple values.

Multiple values are passed back only from the last subform of an and or an or form, not from previous subforms since the return is conditional. Remember that multiple values are only passed back when the value of a subform is unconditionally returned from the containing form. For example, consider the form (or (foo) (bar)). If foo returns a non-nil first value, then only that value is returned as the value of the form. But if it returns nil (as its first value), then or returns whatever values the call to bar returns.

cond passes back multiple values from the last form in the selected clause, provided that that last form's value is returned unconditionally. This is true if the clause has two or more forms in it, and is always true for the last clause.

The variants of cond such as if, select, selectq, and dispatch pass back multiple values from the last form in the selected clause.

If a block form falls through the end, it returns all the values returned by the last expression in it. If return-from or return is used to exit a block form, then the values returned by the block form depend on the kind of return. If return is given two or more subforms, then block returns as many values as the return has subforms. However, if the return has only one subform, then the block returns all of the values returned by that one subform.

prog behaves like block if it is exited with return (or return-from). If control falls through the end of a prog, it returns the single value nil. do also behaves like block with respect to return, but if it is exited through the exit test, all the values of the last exit-form are returned.

unwind-protect passes back multiple values from its protected form. In a sense, this is an exception to the rule; but it is useful, and it makes sense to consider the execution of the unwind forms as a byproduct of unwinding the stack and not as part of sequential execution.

catch passes back multiple values from the last form in its body, if it exits normally. If a throw is done, multiple values are passed back from the value form in the throw.

Here is a description of the error conditions that the evaluator can signal. Some can be signaled by calls to compiled functions also. This is for use by those who are writing condition handlers (). The novice should skip this section.