;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: Some Functions and Special Forms =Text: 3SOME FUNCTIONS AND SPECIAL FORMS* 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. 3eval* 1form* &optional 1nohook* 2(eval 1form*)* evaluates 1form*, and returns the result. Example: 3(defvar x 43)* 3(defvar foo 'bar)* 3(eval (list 'cons x 'foo))* 3 => (43 . bar)* The dynamic bindings available at the time 2eval* is called are visible for dynamic variables within the expression 1x*. No lexical bindings are available for the evaluation of 1x*. It is unusual to call 2eval* explicitly, since usually evaluation is done implicitly. If you are writing a simple Lisp program and explicitly calling 2eval*, you are probably doing something wrong. 2eval* is primarily useful in programs which deal with Lisp itself, rather than programs about knowledge, mathematics or games. Also, if you are only interested in getting at the dynamic value of a symbol (that is, the contents of the symbol's value cell), then you should use the primitive function 2symeval* (see 4(SYMBOLS-1)The Value Cell*). If the argument 1nohook* is non-2nil*, execution of the evalhook is inhibited for 1form*, but not for evaluation of the subforms of 1form*. See 2evalhook*. 2evalhook* is also the way to evaluate in a specified lexical environment if you happen to have got your hands on one. Note: in Maclisp, the second argument to 2eval* is a ``binding context pointer''. There is no such thing in Zetalisp; closures are used instead (see 4(CLOSURES-0)Closures*). 3si:eval1* 1form* &optional 1nohook* Within the definition of a special form, evaluates 1form* in the 1current* lexical environment. 3funcall* 1f* &rest 1args* 2(funcall 1f* 1a1* 1a2* ... 1an*)* applies the function 1f* to the arguments 1a1*, 1a2*, ..., 1an*. 1f* may not be a special form nor a macro; this would not be meaningful. Example: 3(cons 1 2) => (1 . 2)* 3(setq cons 'plus)* 3(funcall cons 1 2) => 3* This shows that the use of the symbol 2cons* as the name of a function and the use of that symbol as the name of a variable do not interact. The 2cons* form invokes the function named 2cons*. The 2funcall* form evaluates the variable and gets the symbol 2plus*, which is the name of a different function. Note: the Maclisp functions 2subrcall*, 2lsubrcall*, and 2arraycall* are not needed on the Lisp Machine; 2funcall* is just as efficient. 2arraycall* is provided for compatibility; it ignores its first subform (the Maclisp array type) and is otherwise identical to 2aref*. 2subrcall* and 2lsubrcall* are not provided. 3apply* 1f* &rest 1args* 3lexpr-funcall* 1f* &rest 1args* 2apply* is like 2funcall* except that the last of 1args* is really a list of arguments to give to 1f* rather than a single argument. 2lexpr-funcall* is a synonym for 2apply*; formerly, 2apply* was limited to the two argument case. 2(apply 1f* 1arglist*)* applies the function 1f* to the list of arguments 1arglist*. 1arglist* should be a list; 1f* can be any function. Examples: 3(setq fred '+) (apply fred '(1 2)) => 3* 3(setq fred '-) (apply fred '(1 2)) => -1* 3(apply 'cons '((+ 2 3) 4)) =>* 3 ((+ 2 3) . 4) 1not* (5 . 4)* Of course, 1arglist* may be 2nil*. If there is more than one element of 1args*, then all but the last of them are individual arguments to pass to 1f*, while the last one is a list of arguments as above. Examples: 3(apply 'plus 1 1 1 '(1 1 1)) => 6* 3(defun report-error (&rest args)* 3 (apply 'format *error-output* args))* 2apply* can also be used with a single argument. Then this argument is a list of a function and some arguments to pass it. Example: 3(apply '(car (a))) => a* 3 2;Not the same as (eval '(car (a)))** Note: in Maclisp, 2apply* takes two or three arguments, and the third argument, when passed, is interpreted as a ``binding context pointer''. So the second argument always provides all the args to pass to the function. There are no binding context pointers in Zetalisp; true lexical scoping exists and is interfaced in other ways. 3call-arguments-limit* 1Constant* Has as its value the limit on the number of arguments that can be dealt with in a function call. There is no promise that this many is forbidden, but it is a promise that any smaller number is acceptable. Note that if 2apply* is used with exactly two arguments, the first one being a function that takes a rest argument, there is no limit except the size of memory on the number of elements in the second argument to 2apply*. 3call* 1function* &rest 1argument-specifications* Offers a very general way of controlling what arguments you pass to a function. You can provide either individual arguments as in 2funcall* or lists of arguments as in 2apply*, in any order. In addition, you can make some of the arguments 1optional*. If the function is not prepared to accept all the arguments you specify, no error occurs if the excess arguments are optional ones. Instead, the excess arguments are simply not passed to the function. The 1argument-specs* are alternating keywords (or lists of keywords) and values. Each keyword or list of keywords says what to do with the value that follows. If a value happens to require no keywords, provide 2()* as a list of keywords for it. Two keywords are presently defined: 2:optional* and 2:spread*. 2:spread* says that the following value is a list of arguments. Otherwise it is a single argument. 2:optional* says that all the following arguments are optional. It is not necessary to specify 2:optional* with all the following 1argument-specs*, because it is sticky. Example: 3(call #'foo () x :spread y '(:optional :spread) z () w)* The arguments passed to 2foo* are the value of 2x*, the elements of the value of 2y*, the elements of the value of 2z*, and the value of 2w*. The function 2foo* must be prepared to accept all the arguments which come from 2x* and 2y*, but if it does not want the rest, they are ignored. 3quote* 1object* 1Special Form* 2(quote 1object*)* simply returns 1object*. 2quote* is used to include constants in a form. It is useful specifically because 1object* is not evaluated; the 2quote* is how you make a form that returns an arbitrary Lisp object. Examples: 3(quote x) => x* 3(setq x (quote (some list))) x => (some list)* Since 2quote* is so useful but somewhat cumbersome to type, the reader normally converts any form preceded by a single quote (2'*) character into a 2quote* form. For example, 3(setq x '(some list))* is converted by 3read* into 3(setq x (quote (some list))) function* 1f* 1Special Form* 2function* has two distinct, though related, meanings. If 1f* is a symbol or any other function spec (see 4(FUNCTIONS-1)Function Specs*), 2(function 1f*)* refers to the function definition of 1f*. For example, in 2(mapcar (function car) x)*, the function definition of 2car* is passed as the first argument to 2mapcar*. 2function* used this way is like 2fdefinition* except that its argument is unevaluated, and so 3(function fred) 2is like* (fdefinition 'fred)* 1f* can also be an explicit function, or lambda-expression, a list such as 2(lambda (x) (* x x))* such as could be the function definition of a symbol. Then 2(function 1f*)* represents that function, suitably interfaced to execute in the lexical environment where it appears. To explain: 3(let (a)* 3 (mapcar (lambda (x) (push x a)) l))* attempts to call the function 2lambda* and evaluate 2(x)* for its first argument. That is no way to refer to the function expressed by 2(lambda (x) (push x a))*. 3(let (a)* 3 (mapcar (quote (lambda (x) (push x a))) l))* passes to 2mapcar* the list 2(lambda (x) (push x a))*. This list does not in any way record the lexical environment where the 2quote* form appeared, so it is impossible to make this environment, with its binding of 2a*, available for the execution of 2(push x a)*. Therefore, the reference to 2a* does not work properly. 3(let (a)* 3 (mapcar (function (lambda (x) (push x a))) l))* passes 2mapcar* a specially designed closure made from the function represented by 2(lambda* 2(x) (push x a))*. When 2mapcar* calls this closure, the lexical environment of the 2function* form is put again into effect, and the 2a* in 2(push x a)* refers properly to the binding made by this 2let*. In addition, the compiler knows that the argument to 2function* should be compiled. The argument of 2quote* cannot be compiled since it may be intended for other uses. To ease typing, the reader converts 2#'1thing** into 2(function 1thing*)*. So 2#'* is similar to 2'* except that it produces a 2function* form instead of a 2quote* form. The last example could be written as 3(let (a)* 3 (mapcar #'(lambda (x) (push x a)) l))* Another way of explaining 2function* is that it causes 1f* to be treated the same way as it would as the car of a form. Evaluating the form 2(1f* 1arg1* 1arg2*...)* uses the function definition of 1f* if it is a symbol, and otherwise expects 1f* to be a list which is a lambda-expression. Note that the car of a form may not be a non-symbol function spec, as that would be difficult to make sense of. Instead, write 3(funcall (function 1spec*) 1args*...)* You should be careful about whether you use 2#'* or 2'*. Suppose you have a program with a variable 2x* whose value is assumed to contain a function that gets called on some arguments. If you want that variable to be the 2test* function, there are two things you could say: 3(setq x 'test)* or 3(setq x #'test)* The former causes the value of 2x* to be the symbol 2test*, whereas the latter causes the value of 2x* to be the function object found in the function cell of 2test*. When the time comes to call the function (the program does 2(funcall x ...)*), either expression works because calling a symbol as a function uses its function definition instead. Using 2'test* is insignificantly slower, because the function call has to indirect through the symbol, but it allows the function to be redefined, traced (see 4(DEBUGGING-5)Tracing Function Execution*), or advised (see 4(DEBUGGING-5)Advising a Function*). Use of 2#'* picks up the function definition out of the symbol 2test* when the 2setq* is done and does not see any later changes to it. 2#'* should be used only if you wish specifically to prevent redefinition of the function from affecting this closure. 3false* Takes no arguments and returns 2nil*. 3true* Takes no arguments and returns 2t*. 3ignore* &rest 1ignore* Takes any number of arguments and returns 2nil*. This is often useful as a ``dummy'' function; if you are calling a function that takes a function as an argument, and you want to pass one that doesn't do anything and won't mind being called with any argument pattern, use this. 3comment* 1Special Form* 2comment* ignores its form and returns the symbol 2comment*. It is most useful for commenting out function definitions that are not needed or correct but worth preserving in the source. The 2#|...|#* syntactic construct is an alternative method. For comments within code about the code, it is better to use semicolons. Example: 3(comment* 3;; This is brain-damaged. Can someone figure out* 3;; how to do this right?* 3(defun foo (x)* 3 ...)* 3) ;End comment* 2;; prevents this definition of foo from being used.* =Node: Declarations =Text: 3DECLARATIONS* Declarations provide auxiliary information on how to execute a function or expression properly. The most important declarations are 2special* 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 2arglist*, 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 2local-declare* around the subexpression or by writing a 2declare* at the front of the body of certain constructs. Declarations can be made on an entire function by writing a 2declare* at the front of the function's body. 3local-declare* 1(declaration...)* 1body...* 1Special Form* A 2local-declare* form looks like 3(local-declare (1decl1* 1decl2* ...)* 3 1form1** 3 1form2** 3 ...)* Each 1decl* is in effect for the forms in the body of the 2local-declare* form. 3declare* 1declaration...* 1Special Form* The special form 2declare* is used for writing local declarations within the construct they apply to. A 1declare* inside a function definition, just after the argument list, is equivalent to putting a 2local-declare* around the function definition. More specifically, 3(defun foo (a b)* 3 (declare (special a b))* 3 (bar))* is equivalent to 3(local-declare ((special a b))* 3(defun foo (a b)* 3 (bar)))* Note that 3(defun foo (a b)* 3 (local-declare ((special a b))* 3 (bar)))* does not do the job, because the declaration is not in effect for the binding of the arguments of 2foo*. 2declare* is preferable to 2local-declare* in this sort of situation, because it allows the 2defun*s themselves to be the top-level lists in the file. While 2local-declare* might appear to have an advantage in that one 2local-declare* may go around several 2defun*s, it tends to cause trouble to use 2local-declare* in that fashion. 2declare* has a similar meaning at the front of the body of a 2progn*, 2prog*, 2let*, 2prog**, 2let**, or internal 2lambda*. For example, 3(prog (x)* 3 (declare (special x))* 3 ...)* is equivalent to 3(local-declare ((special x))* 3 (prog (x)* 3 ...))* At top level in the file, 2(declare 1forms*...)* is equivalent to 2(eval-when (compile) 1forms*...)*. This use of 2declare* is nearly obsolete, and should be avoided. In Common Lisp, 2proclaim* (below) is used for such purposes, with a different calling convention. Elsewhere, 2declare*'s are ignored. Here is a list of declarations that have system-defined meanings: 2(special 1var1 var2 ...*)* The variables 1var1*, 1var2*, etc. will be treated as special variables in the scope of the declaration. 2(unspecial 1var1 var2 ...*)* The variables 1var1*, 1var2*, etc. will be treated as lexical variables in the scope of the declaration, even if they are globally special. 2(notinline 1fun1* 1fun2 ...*)* The functions 1fun1*, 1fun2* and so on will not be open coded or optimized by the compiler within the scope of the declaration. 2(inline 1fun1* 1fun2 ...*)* The functions 1fun1*, 1fun2* 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. 2(ignore 1var1* 1var2 ...*)* Says that the variables 1var1*, 1var2*, 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. 2(declaration 1decl1* 1decl2 ...*)* Says that declarations 1decl1*, 1decl2*, etc. are going to be used, and prevents any warning about an unrecognized type of declaration. For example: 3(defun hack ()* 3 (declare (declaration lose-method)* 3 (lose-method foo bar))* 3 1...* (lose foo) 1...*)* might be useful if 2(lose foo)* is a macro whose expander function does 2(getdecl 'foo* 2'lose-method)* to see what to do. See 4(COMPILER-1)Compile-Time Properties of Symbols* for more information on 2getdecl* and declarations. 3(proclaim '(declaration lose-method))* might also be advisable if you expect widespread use of 2lose-method* declarations. The next two are used by the compiler and generally should not be written by users. 2(def 1name* . 1definition*)* 1name* 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 (2defsubst*s) defined in the file being compiled. Note that the cddr of this item is a function. 2(1propname* 1symbol* 1value*)* 2(getdecl 1symbol* 1propname*)* will return 1value* in the scope of the declaration. This is how the compiler keeps track of 2defdecl*s. These declarations are significant only when they apply to an entire 2defun*. 2(arglist . 1arglist*)* Records 1arglist* 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. 2(values . 1values*) or (:return-list . 1values*)* Records 1values* as the return values list of the function, to be used if anyone asks what values it returns. This is purely documentation. 2(sys:function-parent 1parent-function-spec*)* Records 1parent-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 2defstruct* have no defuns of their own in the text of the source file. So 2defstruct* generates them with 2sys:function-parent* declarations giving the 2defstruct*'s name as the parent function spec. Visiting the accessor function with 2Meta-.* sees the declaration and therefore visits the text of the 2defstruct*. 2(:self-flavor 1flavorname*)* Instance variables of the flavor 1flavorname*, in 2self*, will be accessible in the function. 3locally* &body 1body* 1Macro* Executes the 1body*, recognizing declarations at the front of it. 2locally* is synonymous with 2progn* except that in Common Lisp a 2declare* is allowed at the beginning of a 2locally* and not at the beginning of a 2progn*. 2locally* does differ from 2progn* in one context: at top level in a file being compiled, 2progn* causes each of its elements (including declarations, therefore) to be treated as if at top level. 2locally* does not receive this treatment. The 2locally* form is simply evaluated when the QFASL file is loaded. 3proclaim* &rest 1declarations* Each of 1declarations* is put into effect globally. Currently only 2special* and 2unspecial* declarations mean anything in this way. 2proclaim*'s arguments are evaluated, and the values are expected to be declarations such as you could write in a 2declare*. Thus, you would say 2(proclaim '(special x))* to make a special declaration globally. Top-level 2special* declarations are not the recommended way to make a variable special. Use 2defvar*, 2defconstant* or 2defparameter*, so that you can give the variable documentation. Proclaiming the variable special should be done only when the variable is used in a file other than the one which defines it, to enable the file to be compiled without having to load the defining file first. 2proclaim* is fairly new. Until recently, top-level 2declare* was the preferred way to make global special declarations when 2defvar*, etc., could not be used. Such top-level 2declare*'s are still quite common. In them, the declaration would not be quoted; for example, 2(declare (special* 2x))*. 3special* 1variables...* 1Special Form* Equivalent to 2(proclaim (special 1variables*...))*, this declares each of the 1variables* to be globally special. This function is obsolete. 3unspecial* 1variables...* 1Special Form* Removes any global special declarations of the 1variables*. This function is obsolete. 3the* 1type-specifier* 1value-form* 1Macro* Is a Common Lisp construct effectively the same as 1value-form*. It declares that the value of 1value-form* is an object which of type 1type-specifier*. This is to assist compilers in generating better code for conventional machine architectures. The Lisp Machine does not make use of type declarations so this is the same as writing just 1value-form*. 1type-specifier* is not evaluated. If you want the type of an object to be checked at run time, with an error if it is not what it is supposed to be, use 2check-type* (4(DEBUGGING-2)Convenience Functions for Signaling*). =Node: Tail Recursion =Text: 3TAIL RECURSION* When one function ends by calling another function (possibly itself), as in 3(defun last (x)* 3 (cond ((atom x) x)* 3 ((atom (cdr x)) x)* 3 (t (last (cdr x)))))* it is called 1tail recursion*. In general, if 1X* is a form, and 1Y* is a sub-form of 1X*, then if the value of 1Y* is unconditionally returned as the value of 1X*, with no intervening computation, then we say that 1X* tail-recursively evaluates 1Y*. In a tail recursive situation, it is not strictly necessary to remember anything about the first call to 2last* when the second one is activated. The stack frame for the first call can be discarded completely, allowing 2last* to use a bounded amount of stack space independent of the length of its argument. A system which does this is called 1tail recursive*. The Lisp machine system works tail recursively if the variable 2tail-recursion-flag* is non-2nil*. 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 2last* has been removed from the stack, you can no longer see its frame in the debugger. 3tail-recursion-flag* 1Variable* If this variable is non-2nil*, the calling stack frame is discarded when a tail-recursive call is made in compiled code. 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 2*catch*; it may have bound special variables; it may have a 2&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 2eval*; as a result, interpreted code is never completely tail recursive. =Node: Multiple Values =Text: 3MULTIPLE VALUES* 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 2setq*'ing special variables to the extra values. In most Lisp function calls, multiple values are not used. Special syntax is required both to 1produce* multiple values and to 1receive* them. The primitive for producing multiple values is 2values*, which takes any number of arguments and returns that many values. If the last form in the body of a function is a 2values* with three arguments, then a call to that function returns three values. Many system functions produce multiple values, but they all do it via 2values*. 3values* &rest 1args* Returns multiple values, its arguments. This is the primitive function for producing multiple values. It is legal to call 2values* with no arguments; it returns no values in that case. 3values-list* 1list* Returns multiple values, the elements of the 1list*. 2(values-list '(a b c))* is the same as 2(values* 2'a 'b 'c)*. 1list* may be 2nil*, the empty list, which causes no values to be returned. Equivalent to 2(apply 'values 1list*)*. 2return* and its variants can also be used, within a 2block*, 2do* or 2prog* special form, to return multiple values. They are explained on 4(FLOWCTL-2)Static Non-Local Exits*. Here are the special forms for receiving multiple values. 3multiple-value* 1(variable...)* 1form* 1Special Form* 3multiple-value-setq* 1(variable...)* 1form* 2multiple-value* is a special form used for calling a function which is expected to return more than one value. 1form* is evaluated, and the 1variables* are 1set* (not lambda-bound) to the values returned by 1form*. If more values are returned than there are variables, the extra values are ignored. If there are more variables than values returned, extra values of 2nil* are supplied. If 2nil* appears in the 1var-list*, then the corresponding value is ignored (setting 2nil* is not allowed anyway). Example: 3(multiple-value (symbol already-there-p)* 3 (intern "goo"))* In addition to its first value (the symbol), 2intern* returns a second value, which is non-2nil* if an existing symbol was found, or else 2nil* if 2intern* had to create one. So if the symbol 2goo* was already known, the variable 2already-there-p* is set non-2nil*, otherwise it is set to 2nil*. The third value returned by 2intern* is ignored by this form of call since there is no third variable in the 2multiple-value*. 2multiple-value* is usually used for effect rather than for value; however, its value is defined to be the first of the values returned by 1form*. 2multiple-value-setq* is the Common Lisp name for this construct. The two names are equivalent. 3multiple-value-bind* 1(variable...)* 1form* 1body...* 1Special Form* This is similar to 2multiple-value*, but locally binds the variables which receive the values, rather than setting them, and has a body--a set of forms which are evaluated with these local bindings in effect. First 1form* is evaluated. Then the 1variables* are bound to the values returned by 1form*. Then the 1body* forms are evaluated sequentially, the bindings are undone, and the result of the last 1body* form is returned. Example: 3(multiple-value-bind (sym already-there)* 3 (intern string)* 3 ;; If an existing symbol was found, deallocate the string.* 3 (if already-there* 3 (return-storage (prog1 string (setq string nil))))* 3 sym) multiple-value-call* 1function* 1argforms...* 1Special Form* Evaluates the argforms, saving all of their values, and then calls 1function* with all those values as arguments. This differs from 3(funcall 1function* 1argforms*...)* because that would get only one argument for 1function* from each 1argform*, whereas 2multiple-value-call* gets as many args from each 1argform* as the 1argform* cares to return. This works by consing a list of all the values returned, and applying 1function* to it. Example: 3(multiple-value-call 'append* 3 (values '(a b) '(c d))* 3 '(e f))* 3 => (a b c d e f) multiple-value-prog1* 1form* 1forms...* 1Special Form* Evaluates 1form*, saves its values, evaluates the 1forms*, discards their values, then returns whatever values 1form* produced. This does not cons. Example: 3(multiple-value-prog1 (values 1 2)* 3 (print 'foo))* 3 => 1 2 multiple-value-list* 1form* 1Special Form* 2multiple-value-list* evaluates 1form*, and returns a list of the values it returned. This is useful for when you don't know how many values to expect. Example: 3(setq a (multiple-value-list (intern "goo")))* 3a => (goo nil #)* This is similar to the example of 2multiple-value* above; 2a* is set to a list of three elements, the three values returned by 2intern*. 3nth-value* 1n* 1form* 1Special Form* Evaluates 1form* and returns its value number 1n*, 1n* = 0 meaning the first value. For example, 2(nth-value 1 (foo))* returns the second of 2foo*'s values. 2nth-value* operates without consing in compiled code if the first argument's value is known at compile time. When one form finished by tail recursively evaluating a subform (see 4(EVAL-4)Tail Recursion*), all of the subform's multiple values are passed back by the outer form. For example, the value of a 2cond* is the value of the last form in the selected clause. If the last form in that clause produces multiple values, so does the 2cond*. This 1passing-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 2setq*'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 2setq*'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 2(foo (bar))* is evaluated and the call to 2bar* returns many values, 2foo* 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 2multiple-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 2defun* or a 2lambda*, and variations such as the body of a function, the body of a 2let*, etc., pass back multiple values from the last form in the body. 2eval*, 2apply* and 2funcall*, pass back multiple values from the function called. 2progn* passes back multiple values from its last form. 2progv* and 2progw* do so also. 2prog1* and 2prog2*, however, do not pass back multiple values. Multiple values are passed back only from the last subform of an 2and* or an 2or* 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 2(or (foo) (bar))*. If 2foo* returns a non-2nil* first value, then only that value is returned as the value of the form. But if it returns 2nil* (as its first value), then 2or* returns whatever values the call to 2bar* returns. 2cond* 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 2cond* such as 2if*, 2select*, 2selectq*, and 2dispatch* pass back multiple values from the last form in the selected clause. If a 2block* form falls through the end, it returns all the values returned by the last expression in it. If 2return-from* or 2return* is used to exit a 2block* form, then the values returned by the 2block* form depend on the kind of 2return*. If 2return* is given two or more subforms, then 2block* returns as many values as the 2return* has subforms. However, if the 2return* has only one subform, then the 2block* returns all of the values returned by that one subform. 2prog* behaves like 2block* if it is exited with 2return* (or 2return-from*). If control falls through the end of a 2prog*, it returns the single value 2nil*. 2do* also behaves like 2block* with respect to 2return*, but if it is exited through the exit test, all the values of the last 1exit-form* are returned. 2unwind-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. 2catch* 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 2throw*. 3multiple-values-limit* 1Constant* The smallest number of values that might possibly fail to work. Returning a number of values less than this many cannot possibly run into trouble with an implementation limit on number of values returned. =Node: Evaluation and Function Calling Errors =Text: 3EVALUATION AND FUNCTION CALLING ERRORS* 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 (4(DEBUGGING-1)Handling Conditions*). The novice should skip this section. 3sys:invalid-function* (error) 1Condition* This is signaled when an object that is supposed to be applied to arguments is not a valid Lisp function. The condition instance supports the operation 2:function*, which returns the supposed function to be called. The 2:new-function* proceed type is provided; it expects one argument, a function to call instead. 3sys:invalid-lambda-list* (3sys:invalid-function* error) 1Condition* This condition name is present in addition to 2sys:invalid-function* when the function to be called looks like an interpreted function, and the only problem is the syntax of its lambda list. 3sys:too-few-arguments* (error) 1Condition* This condition is signaled when a function is applied to too few arguments. The condition instance supports the operations 2:function* and 2:arguments* which return the function and the list of the arguments provided. The proceed types 2:additional-arguments* and 2:new-argument-list* are provided. Both take one argument. In the first case, the argument is a list of arguments to pass in addition to the ones supplied. In the second, it is a list of arguments to replace the ones actually supplied. 3sys:too-many-arguments* (error) 1Condition* This is similar to 2sys:too-few-arguments*. Instead of the 2:additional-arguments* proceed type, 2:fewer-arguments* is provided. Its argument is a number, which is how many of the originally supplied arguments to use in calling the function again. 3sys:undefined-keyword-argument* (error) 1Condition* This is signaled when a function that takes keyword arguments is given a keyword that it does not accept, if 2&allow-other-keys* was not used in the function's definition and 2:allow-other-keys* was not specified by the caller (see 4(FUNCTIONS-0)Functions*). The 2:keyword* operation on the condition instance returns the extraneous keyword, and the 2:value* operation returns the value supplied with it. The proceed type 2:new-keyword* is provided. It expects one argument, which is a keyword to use instead of the one supplied. 3sys:cell-contents-error* (error) 1Condition Flavor* This condition name categorizes all the errors signaled because of references to void memory locations. It includes ``unbound'' variables, ``undefined'' functions, and other things. 2:address* A locative pointer to the referenced cell. 2:current-address* A locative pointer to the cell which currently contains the contents that were found in the referenced cell when the error happened. This can be different from the original address in the case of dynamic variable bindings, which move between special PDLs and symbol value cells. 2:cell-type* A keyword saying what type of cell was referred to: 2:function*, 2:value*, 2:closure*, or 2nil* for a cell that is not one of those. 2:containing-structure* The object (list, array, symbol) inside which the referenced memory cell is found. 2:data-type* 2:pointer*The data type and pointer fields of the contents of the memory cell, at the time of the error. Both are fixnums. The proceed type 2:no-action* takes no argument. If the cell's contents are now valid, the program proceeds, using them. Otherwise the error happens again. The proceed type 2:package-dwim* looks for symbols with the same name in other packages; but only if the containing structure is a symbol. Two other proceed types take one argument: 2:new-value* and 2:store-new-value*. The argument is used as the contents of the memory cell. 2:store-new-value* also permanently stores the argument into the cell. 3sys:unbound-variable* (sys:cell-contents-error error) 1Condition* This condition name categorizes all errors of variables whose values are void. 3sys:unbound-special-variable* 1Condition* 3sys:unbound-closure-variable* 1Condition* 3sys:unbound-instance-variable* 1Condition* These condition names appear in addition to 2sys:unbound-variable* to subcategorize the kind of variable reference that the error happened in. 3sys:undefined-function* (sys:cell-contents-error error) 1Condition* This condition name categorizes errors of function specs that are undefined. 3sys:wrong-type-argument* (error) 1Condition* This is signaled when a function checks the type of its argument and rejects it; for example, if you do 2(car 1)*. The condition instance supports these extra operations: 2:arg-name* The name of the erroneous argument. This may be 2nil* if there is no name, or if the system no longer remembers which argument it was. 2:old-value* The value that was supplied for the argument. 2:function* The function which received and rejected the argument. 2:description* A type specifier which says what sort of object was expected for this argument. The proceed type 2:argument-value* is provided; it expects one argument, which is a value to use instead of the erroneous value.