Celestin Apprentice 7

home *** CD-ROM | disk | FTP | other *** search

/ Celestin Apprentice 7 / Apprentice-Release7.iso / Environments / PowerLisp 2.01 / Supplemental Documentation / Documentation / Chapter 07. Control Structure < prev next >

Wrap

Text File | 1995-03-27 | 170.7 KB | 4,007 lines | [TEXT/ROSA]

Common Lisp the Language, 2nd Edition ------------------------------------------------------------------------------- 7. Control Structure Common Lisp provides a variety of special structures for organizing programs. Some have to do with flow of control (control structures), while others control access to variables (environment structures). Some of these features are implemented as special forms; others are implemented as macros, which typically expand into complex program fragments expressed in terms of special forms or other macros. Function application is the primary method for construction of Lisp programs. Operations are written as the application of a function to its arguments. Usually, Lisp programs are written as a large collection of small functions, each of which implements a simple operation. These functions operate by calling one another, and so larger operations are defined in terms of smaller ones. Lisp functions may call upon themselves recursively, either directly or indirectly. [change_begin] Locally defined functions (flet, labels) and macros (macrolet) are quite versatile. The new symbol macro facility allows even more syntactic flexibility. [change_end] While the Lisp language is more applicative in style than statement-oriented, it nevertheless provides many operations that produce side effects and consequently requires constructs for controlling the sequencing of side effects. The construct progn, which is roughly equivalent to an Algol begin-end block with all its semicolons, executes a number of forms sequentially, discarding the values of all but the last. Many Lisp control constructs include sequencing implicitly, in which case they are said to provide an ``implicit progn.'' Other sequencing constructs include prog1 and prog2. For looping, Common Lisp provides the general iteration facility do as well as a variety of special-purpose iteration facilities for iterating or mapping over various data structures. Common Lisp provides the simple one-way conditionals when and unless, the simple two-way conditional if, and the more general multi-way conditionals such as cond and case. The choice of which form to use in any particular situation is a matter of taste and style. Constructs for performing non-local exits with various scoping disciplines are provided: block, return, return-from, catch, and throw. The multiple-value constructs provide an efficient way for a function to return more than one value; see values. ------------------------------------------------------------------------------- * Constants and Variables o Reference o Assignment * Generalized Variables * Function Invocation * Simple Sequencing * Establishing New Variable Bindings * Conditionals * Blocks and Exits * Iteration o Indefinite Iteration o General Iteration o Simple Iteration Constructs o Mapping o The ``Program Feature'' * Structure Traversal and Side Effects * Multiple Values o Constructs for Handling Multiple Values o Rules Governing the Passing of Multiple Values * Dynamic Non-Local Exits ------------------------------------------------------------------------------- 7.1. Constants and Variables Because some Lisp data objects are used to represent programs, one cannot always notate a constant data object in a program simply by writing the notation for the object unadorned; it would be ambiguous whether a constant object or a program fragment was intended. The quote special form resolves this ambiguity. There are two kinds of variables in Common Lisp, in effect: ordinary variables and function names. There are some similarities between the two kinds, and in a few cases there are similar functions for dealing with them, for example boundp and fboundp. However, for the most part the two kinds of variables are used for very different purposes: one to name defined functions, macros, and special forms, and the other to name data objects. [change_begin] X3J13 voted in March 1989 (FUNCTION-NAME) to introduce the concept of a function-name, which may be either a symbol or a two-element list whose first element is the symbol setf and whose second element is a symbol. The primary purpose of this is to allow setf expander functions to be CLOS generic functions with user-defined methods. Many places in Common Lisp that used to require a symbol for a function name are changed to allow 2-lists as well; for example, defun is changed so that one may write (defun (setf foo) ...), and the function special form is changed to accept any function-name. See also fdefinition. By convention, any function named (setf f) should return its first argument as its only value, in order to preserve the specification that setf returns its newvalue. See setf. Implementations are free to extend the syntax of function-names to include lists beginning with additional symbols other than setf or lambda. [change_end] ------------------------------------------------------------------------------- * Reference * Assignment ------------------------------------------------------------------------------- 7.1. Reference The value of an ordinary variable may be obtained simply by writing the name of the variable as a form to be executed. Whether this is treated as the name of a special variable or a lexical variable is determined by the presence or absence of an applicable special declaration; see chapter 9. The following functions and special forms allow reference to the values of constants and variables in other ways. [Special Form] quote object (quote x) simply returns x. The object is not evaluated and may be any Lisp object whatsoever. This construct allows any Lisp object to be written as a constant value in a program. For example: (setq a 43) (list a (cons a 3)) => (43 (43 . 3)) (list (quote a) (quote (cons a 3)) => (a (cons a 3)) Since quote forms are so frequently useful but somewhat cumbersome to type, a standard abbreviation is defined for them: any form f preceded by a single quote (') character is assumed to have (quote ) wrapped around it to make (quote f). For example: (setq x '(the magic quote hack)) is normally interpreted by read to mean (setq x (quote (the magic quote hack))) See section 22.1.3. [change_begin] X3J13 voted in January 1989 (CONSTANT-MODIFICATION) to clarify that it is an error to destructively modify any object that appears as a constant in executable code, whether within a quote special form or as a self-evaluating form. See section 25.1 for a discussion of how quoted constants are treated by the compiler. X3J13 voted in March 1989 (QUOTE-SEMANTICS) to clarify that eval and compile are not permitted either to copy or to coalesce (``collapse'') constants (see eq) appearing in the code they process; the resulting program behavior must refer to objects that are eql to the corresponding objects in the source code. Moreover, the constraints introduced by the votes on issues (CONSTANT-COMPILABLE-TYPES) and (CONSTANT-CIRCULAR-COMPILATION) on what kinds of objects may appear as constants apply only to compile-file (see section 25.1). [change_end] [Special Form] function fn The value of function is always the functional interpretation of fn; fn is interpreted as if it had appeared in the functional position of a function invocation. In particular, if fn is a symbol, the functional definition associated with that symbol is returned; see symbol-function. If fn is a lambda-expression, then a ``lexical closure'' is returned, that is, a function that when invoked will execute the body of the lambda-expression in such a way as to observe the rules of lexical scoping properly. [change_begin] X3J13 voted in June 1988 (FUNCTION-TYPE) to specify that the result of a function special form is always of type function. This implies that a form (function fn) may be interpreted as (the (function fn)). It is an error to use the function special form on a symbol that does not denote a function in the lexical or global environment in which the special form appears. Specifically, it is an error to use the function special form on a symbol that denotes a macro or special form. Some implementations may choose not to signal this error for performance reasons, but implementations are forbidden to extend the semantics of function in this respect; that is, an implementation is not allowed to define the failure to signal an error to be a ``useful'' behavior. X3J13 voted in March 1989 (FUNCTION-NAME) to extend function to accept any function-name (a symbol or a list whose car is setf-see section 7.1) as well as lambda-expressions. Thus one may write (function (setf cadr)) to refer to the setf expansion function for cadr. [change_end] For example: (defun adder (x) (function (lambda (y) (+ x y)))) The result of (adder 3) is a function that will add 3 to its argument: (setq add3 (adder 3)) (funcall add3 5) => 8 This works because function creates a closure of the inner lambda-expression that is able to refer to the value 3 of the variable x even after control has returned from the function adder. More generally, a lexical closure in effect retains the ability to refer to lexically visible bindings, not just values. Consider this code: (defun two-funs (x) (list (function (lambda () x)) (function (lambda (y) (setq x y))))) (setq funs (two-funs 6)) (funcall (car funs)) => 6 (funcall (cadr funs) 43) => 43 (funcall (car funs)) => 43 The function two-funs returns a list of two functions, each of which refers to the binding of the variable x created on entry to the function two-funs when it was called with argument 6. This binding has the value 6 initially, but setq can alter a binding. The lexical closure created for the first lambda-expression does not ``snapshot'' the value 6 for x when the closure is created. The second function can be used to alter the binding (to 43, in the example), and this altered value then becomes accessible to the first function. In situations where a closure of a lambda-expression over the same set of bindings may be produced more than once, the various resulting closures may or may not be eq, at the discretion of the implementation. For example: (let ((x 5) (funs '())) (dotimes (j 10) (push #'(lambda (z) (if (null z) (setq x 0) (+ x z))) funs)) funs) The result of the above expression is a list of ten closures. Each logically requires only the binding of x. It is the same binding in each case, so the ten closures may or may not be the same identical (eq) object. On the other hand, the result of the expression (let ((funs '())) (dotimes (j 10) (let ((x 5)) (push (function (lambda (z) (if (null z) (setq x 0) (+ x z)))) funs))) funs) is also a list of ten closures. However, in this case no two of the closures may be eq, because each closure is over a distinct binding of x, and these bindings can be behaviorally distinguished because of the use of setq. The question of distinguishable behavior is important; the result of the simpler expression (let ((funs '())) (dotimes (j 10) (let ((x 5)) (push (function (lambda (z) (+ x z))) funs))) funs) is a list of ten closures that may be pairwise eq. Although one might think that a different binding of x is involved for each closure (which is indeed the case), the bindings cannot be distinguished because their values are identical and immutable, there being no occurrence of setq on x. A compiler would therefore be justified in transforming the expression to (let ((funs '())) (dotimes (j 10) (push (function (lambda (z) (+ 5 z))) funs)) funs) where clearly the closures may be the same after all. The general rule, then, is that the implementation is free to have two distinct evaluations of the same function form produce identical (eq) closures if it can prove that the two conceptually distinct resulting closures must in fact be behaviorally identical with respect to invocation. This is merely a permitted optimization; a perfectly valid implementation might simply cause every distinct evaluation of a function form to produce a new closure object not eq to any other. Frequently a compiler can deduce that a closure in fact does not need to close over any variable bindings. For example, in the code fragment (mapcar (function (lambda (x) (+ x 2))) y) the function (lambda (x) (+ x 2)) contains no references to any outside entity. In this important special case, the same ``closure'' may be used as the value for all evaluations of the function special form. Indeed, this value need not be a closure object at all; it may be a simple compiled function containing no environment information. This example is simply a special case of the foregoing discussion and is included as a hint to implementors familiar with previous methods of implementing Lisp. The distinction between closures and other kinds of functions is somewhat pointless, actually, as Common Lisp defines no particular representation for closures and no way to distinguish between closures and non-closure functions. All that matters is that the rules of lexical scoping be obeyed. Since function forms are so frequently useful but somewhat cumbersome to type, a standard abbreviation is defined for them: any form f preceded by #' (# followed by an apostrophe) is assumed to have (function ) wrapped around it to make (function f). For example, (remove-if #'numberp '(1 a b 3)) is normally interpreted by read to mean (remove-if (function numberp) '(1 a b 3)) See section 22.1.4. [Function] symbol-value symbol symbol-value returns the current value of the dynamic (special) variable named by symbol. An error occurs if the symbol has no value; see boundp and makunbound. Note that constant symbols are really variables that cannot be changed, and so symbol-value may be used to get the value of a named constant. In particular, symbol-value of a keyword will return that keyword. symbol-value cannot access the value of a lexical variable. This function is particularly useful for implementing interpreters for languages embedded in Lisp. The corresponding assignment primitive is set; alternatively, symbol-value may be used with setf. [Function] symbol-function symbol symbol-function returns the current global function definition named by symbol. An error is signalled if the symbol has no function definition; see fboundp. Note that the definition may be a function or may be an object representing a special form or macro. In the latter case, however, it is an error to attempt to invoke the object as a function. If it is desired to process macros, special forms, and functions equally well, as when writing an interpreter, it is best first to test the symbol with macro-function and special-form-p and then to invoke the functional value only if these two tests both yield false. This function is particularly useful for implementing interpreters for languages embedded in Lisp. symbol-function cannot access the value of a lexical function name produced by flet or labels; it can access only the global function value. The global function definition of a symbol may be altered by using setf with symbol-function. Performing this operation causes the symbol to have only the specified definition as its global function definition; any previous definition, whether as a macro or as a function, is lost. It is an error to attempt to redefine the name of a special form (see table 5-1). [change_begin] X3J13 voted in June 1988 (FUNCTION-TYPE) to clarify the behavior of symbol-function in the light of the redefinition of the type function. * It is permissible to call symbol-function on any symbol for which fboundp returns true. Note that fboundp must return true for a symbol naming a macro or a special form. * If fboundp returns true for a symbol but the symbol denotes a macro or special form, then the value returned by symbol-function is not well-defined but symbol-function will not signal an error. * When symbol-function is used with setf the new value must be of type function. It is an error to set the symbol-function of a symbol to a symbol, a list, or the value returned by symbol-function on the name of a macro or a special form. [change_end] [change_begin] [Function] fdefinition function-name X3J13 voted in March 1989 (FUNCTION-NAME) to add the function fdefinition to the language. It is exactly like symbol-function except that its argument may be any function-name (a symbol or a list whose car is setf-see section 7.1); it returns the current global function definition named by the argument function-name. One may use fdefinition with setf to change the current global function definition associated with a function-name. [change_end] [Function] boundp symbol boundp is true if the dynamic (special) variable named by symbol has a value; otherwise, it returns nil. See also set and makunbound. [Function] fboundp symbol fboundp is true if the symbol has a global function definition. Note that fboundp is true when the symbol names a special form or macro. macro-function and special-form-p may be used to test for these cases. [change_begin] X3J13 voted in June 1988 (FUNCTION-TYPE) to emphasize that, despite the tightening of the definition of the type function, fboundp must return true when the argument names a special form or macro. See also symbol-function and fmakunbound. X3J13 voted in March 1989 (FUNCTION-NAME) to extend fboundp to accept any function-name (a symbol or a list whose car is setf-see section 7.1). Thus one may write (fboundp '(setf cadr)) to determine whether a setf expansion function has been globally defined for cadr. [change_end] [Function] special-form-p symbol The function special-form-p takes a symbol. If the symbol globally names a special form, then a non-nil value is returned; otherwise nil is returned. A returned non-nil value is typically a function of implementation-dependent nature that can be used to interpret (evaluate) the special form. It is possible for both special-form-p and macro-function to be true of a symbol. This is possible because an implementation is permitted to implement any macro also as a special form for speed. On the other hand, the macro definition must be available for use by programs that understand only the standard special forms listed in table 5-1. ------------------------------------------------------------------------------- 7.1.2. Assignment The following facilities allow the value of a variable (more specifically, the value associated with the current binding of the variable) to be altered. Such alteration is different from establishing a new binding. Constructs for establishing new bindings of variables are described in section 7.5. [Special Form] setq {var form}* The special form (setq var1 form1 var2 form2 ...) is the ``simple variable assignment statement'' of Lisp. First form1 is evaluated and the result is stored in the variable var1, then form2 is evaluated and the result stored in var2, and so forth. The variables are represented as symbols, of course, and are interpreted as referring to static or dynamic instances according to the usual rules. Therefore setq may be used for assignment of both lexical and special variables. setq returns the last value assigned, that is, the result of the evaluation of its last argument. As a boundary case, the form (setq) is legal and returns nil. There must be an even number of argument forms. For example, in (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 is performed before the second form is evaluated, allowing that form to use the new value of x. See also the description of setf, the Common Lisp ``general assignment statement'' that is capable of assigning to variables, array elements, and other locations. [change_begin] Some programmers choose to avoid setq as a matter of style, always using setf for any kind of structure modification. Others use setq with simple variable names and setf with all other generalized variables. X3J13 voted in March 1989 (SYMBOL-MACROLET-SEMANTICS) to specify that if any var refers not to an ordinary variable but to a binding made by symbol-macrolet, then that var is handled as if setf had been used instead of setq. [change_end] [Macro] psetq {var form}* A psetq form is just like a setq form, except that the assignments happen in parallel. First all of the forms are evaluated, and then the variables are set to the resulting values. The value of the psetq form is nil. For example: (setq a 1) (setq b 2) (psetq a b b a) a => 2 b => 1 In this example, the values of a and b are exchanged by using parallel assignment. (If several variables are to be assigned in parallel in the context of a loop, the do construct may be appropriate.) See also the description of psetf, the Common Lisp ``general parallel assignment statement'' that is capable of assigning to variables, array elements, and other locations. [change_begin] X3J13 voted in March 1989 (SYMBOL-MACROLET-SEMANTICS) to specify that if any var refers not to an ordinary variable but to a binding made by symbol-macrolet, then that var is handled as if psetf had been used instead of psetq. [change_end] [Function] set symbol value set allows alteration of the value of a dynamic (special) variable. set causes the dynamic variable named by symbol to take on value as its value. [change_begin] X3J13 voted in January 1989 (ARGUMENTS-UNDERSPECIFIED) to clarify that the value may be any Lisp datum whatsoever. [change_end] Only the value of the current dynamic binding is altered; if there are no bindings in effect, the most global value is altered. For example, (set (if (eq a b) 'c 'd) 'foo) will either set c to foo or set d to foo, depending on the outcome of the test (eq a b). set returns value as its result. set cannot alter the value of a local (lexically bound) variable. The special form setq is usually used for altering the values of variables (lexical or dynamic) in programs. set is particularly useful for implementing interpreters for languages embedded in Lisp. See also progv, a construct that performs binding rather than assignment of dynamic variables. [Function] makunbound symbol fmakunbound symbol makunbound causes the dynamic (special) variable named by symbol to become unbound (have no value). fmakunbound does the analogous thing for the global function definition named by symbol. For example: (setq a 1) a => 1 (makunbound 'a) a => causes an error (defun foo (x) (+ x 1)) (foo 4) => 5 (fmakunbound 'foo) (foo 4) => causes an error Both functions return symbol as the result value. [change_begin] X3J13 voted in March 1989 (FUNCTION-NAME) to extend fmakunbound to accept any function-name (a symbol or a list whose car is setf - see section 7.1). Thus one may write (fmakunbound '(setf cadr)) to remove any global definition of a setf expansion function for cadr. [change_end] ------------------------------------------------------------------------------- 7.2. Generalized Variables In Lisp, a variable can remember one piece of data, that is, one Lisp object. The main operations on a variable are to recover that object and to alter the variable to remember a new object; these operations are often called access and update operations. The concept of variables named by symbols can be generalized to any storage location that can remember one piece of data, no matter how that location is named. Examples of such storage locations are the car and cdr of a cons, elements of an array, and components of a structure. For each kind of generalized variable, typically there are two functions that implement the conceptual access and update operations. For a variable, merely mentioning the name of the variable accesses it, while the setq special form can be used to update it. The function car accesses the car of a cons, and the function rplaca updates it. The function symbol-value accesses the dynamic value of a variable named by a given symbol, and the function set updates it. Rather than thinking about two distinct functions that respectively access and update a storage location somehow deduced from their arguments, we can instead simply think of a call to the access function with given arguments as a name for the storage location. Thus, just as x may be considered a name for a storage location (a variable), so (car x) is a name for the car of some cons (which is in turn named by x). Now, rather than having to remember two functions for each kind of generalized variable (having to remember, for example, that rplaca corresponds to car), we adopt a uniform syntax for updating storage locations named in this way, using the setf macro. This is analogous to the way we use the setq special form to convert the name of a variable (which is also a form that accesses it) into a form that updates it. The uniformity of this approach is illustrated in the following table. Access Function Update Function Update Using setf ---------------------------------------------------------------------- x (setq x datum) (setf x datum) (car x) (rplaca x datum) (setf (car x) datum) (symbol-value x) (set x datum) (setf (symbol-value x) datum) ---------------------------------------------------------------------- setf is actually a macro that examines an access form and produces a call to the corresponding update function. Given the existence of setf in Common Lisp, it is not necessary to have setq, rplaca, and set; they are redundant. They are retained in Common Lisp because of their historical importance in Lisp. However, most other update functions (such as putprop, the update function for get) have been eliminated from Common Lisp in the expectation that setf will be uniformly used in their place. [Macro] setf {place newvalue}* (setf place newvalue) takes a form place that when evaluated accesses a data object in some location and ``inverts'' it to produce a corresponding form to update the location. A call to the setf macro therefore expands into an update form that stores the result of evaluating the form newvalue into the place referred to by the access form. If more than one place-newvalue pair is specified, the pairs are processed sequentially; that is, (setf place1 newvalue1 place2 newvalue2) ... placen newvaluen) is precisely equivalent to (progn (setf place1 newvalue1) (setf place2 newvalue2) ... (setf placen newvaluen)) For consistency, it is legal to write (setf), which simply returns nil. The form place may be any one of the following: * The name of a variable (either lexical or dynamic). * A function call form whose first element is the name of any one of the following functions: aref car svref nth cdr get elt caar getf symbol-value rest cadr gethash symbol-function first cdar documentation symbol-plist second cddr fill-pointer macro-function third caaar caaaar cdaaar fourth caadr caaadr cdaadr fifth cadar caadar cdadar sixth caddr caaddr cdaddr seventh cdaar cadaar cddaar eighth cdadr cadadr cddadr ninth cddar caddar cdddar tenth cdddr cadddr cddddr [change_begin] X3J13 voted in March 1988 (AREF-1D) to add row-major-aref to this list. X3J13 voted in June 1989 (DEFINE-COMPILER-MACRO) to add compiler-macro-function to this list. X3J13 voted in March 1989 (FUNCTION-NAME) to clarify that this rule applies only when the function name refers to a global function definition and not to a locally defined function or macro. [change_end] * A function call form whose first element is the name of a selector function constructed by defstruct. [change_begin] X3J13 voted in March 1989 (FUNCTION-NAME) to clarify that this rule applies only when the function name refers to a global function definition and not to a locally defined function or macro. [change_end] * A function call form whose first element is the name of any one of the following functions, provided that the new value is of the specified type so that it can be used to replace the specified ``location'' (which is in each of these cases not truly a generalized variable): Function Name Required Type -------------------------------- char string-char schar string-char bit bit sbit bit subseq sequence -------------------------------- [change_begin] X3J13 voted in March 1989 (CHARACTER-PROPOSAL) to eliminate the type string-char and to redefine string to be the union of one or more specialized vector types, the types of whose elements are subtypes of the type character. In the preceding table, the type string-char should be replaced by some such phrase as ``the element-type of the argument vector.'' X3J13 voted in March 1989 (FUNCTION-NAME) to clarify that this rule applies only when the function name refers to a global function definition and not to a locally defined function or macro. [change_end] In the case of subseq, the replacement value must be a sequence whose elements may be contained by the sequence argument to subseq. (Note that this is not so stringent as to require that the replacement value be a sequence of the same type as the sequence of which the subsequence is specified.) If the length of the replacement value does not equal the length of the subsequence to be replaced, then the shorter length determines the number of elements to be stored, as for the function replace. * A function call form whose first element is the name of any one of the following functions, provided that the specified argument to that function is in turn a place form; in this case the new place has stored back into it the result of applying the specified ``update'' function (which is in each of these cases not a true update function): Function Name Argument That Is a place Update Function Used ---------------------------------------------------------------- char-bit first set-char-bit ldb second dpb mask-field second deposit-field ---------------------------------------------------------------- [change_begin] X3J13 voted in March 1989 (CHARACTER-PROPOSAL) to eliminate char-bit and set-char-bit. X3J13 voted in March 1989 (FUNCTION-NAME) to clarify that this rule applies only when the function name refers to a global function definition and not to a locally defined function or macro. [change_end] * A the type declaration form, in which case the declaration is transferred to the newvalue form, and the resulting setf form is analyzed. For example, (setf (the integer (cadr x)) (+ y 3)) is processed as if it were (setf (cadr x) (the integer (+ y 3))) * A call to apply where the first argument form is of the form #'name, that is, (function name), where name is the name of a function, calls to which are recognized as places by setf. Suppose that the use of setf with apply looks like this: (setf (apply #'name x1 x2 ... xn rest) x0) The setf method for the function name must be such that (setf (name z1 z2 ... zm) z0) expands into a store form (storefn zi zi ... zi zm) That is, it must expand into a function call such that all arguments but the last may be any permutation or subset of the new value z0 and the arguments of the access form, but the last argument of the storing call must be the same as the last argument of the access call. See define-setf-method for more details on accessing and storing forms. Given this, the setf-of-apply form shown above expands into (apply #'storefn xi xi ... xi rest) As an example, suppose that the variable indexes contains a list of subscripts for a multidimensional array foo whose rank is not known until run time. One may access the indicated element of the array by writing (apply #'aref foo indexes) and one may alter the value of the indicated element to that of newvalue by writing (setf (apply #'aref foo indexes) newvalue) [change_begin] X3J13 voted in March 1989 (FUNCTION-NAME) to clarify that this rule applies only when the function name apply refers to the global function definition and not to a locally defined function or macro named apply. [change_end] * A macro call, in which case setf expands the macro call and then analyzes the resulting form. [change_begin] X3J13 voted in March 1989 (FUNCTION-NAME) to clarify that this step uses macroexpand-1, not macroexpand. This allows the chance to apply any of the rules preceding this one to any of the intermediate expansions. [change_end] * Any form for which a defsetf or define-setf-method declaration has been made. [change_begin] X3J13 voted in March 1989 (FUNCTION-NAME) to clarify that this rule applies only when the function name in the form refers to a global function definition and not to a locally defined function or macro. X3J13 voted in March 1989 (FUNCTION-NAME) to add one more rule to the preceding list, coming after all those listed above: * Any other list whose first element is a symbol (call it f). In this case, the call to setf expands into a call to the function named by the list (setf f) (see section 7.1). The first argument is the new value and the remaining arguments are the values of the remaining elements of place. This expansion occurs regardless of whether either f or (setf f) is defined as a function locally, globally, or not at all. For example, (setf (f arg1 arg2 ...) newvalue) expands into a form with the same effect and value as (let ((#:temp1 arg1) ;Force correct order of evaluation (#:temp2 arg2) ... (#:temp0 newvalue)) (funcall (function (setf f)) #:temp0 #:temp1 #:temp2 ...)) By convention, any function named (setf f) should return its first argument as its only value, in order to preserve the specification that setf returns its newvalue. X3J13 voted in March 1989 (SYMBOL-MACROLET-SEMANTICS) to add this case as well: * A variable reference that refers to a symbol macro definition made by symbol-macrolet, in which case setf expands the reference and then analyzes the resulting form. [change_end] setf carefully arranges to preserve the usual left-to-right order in which the various subforms are evaluated. On the other hand, the exact expansion for any particular form is not guaranteed and may even be implementation-dependent; all that is guaranteed is that the expansion of a setf form will be an update form that works for that particular implementation, and that the left-to-right evaluation of subforms is preserved. The ultimate result of evaluating a setf form is the value of newvalue. Therefore (setf (car x) y) does not expand into precisely (rplaca x y), but into something more like (let ((G1 x) (G2 y)) (rplaca G1 G2) G2) the precise expansion being implementation-dependent. The user can define new setf expansions by using defsetf. [change_begin] X3J13 voted in June 1989 (SETF-MULTIPLE-STORE-VARIABLES) to extend the specification of setf to allow a place whose setf method has more than one store variable (see define-setf-method). In such a case as many values are accepted from the newvalue form as there are store variables; extra values are ignored and missing values default to nil, as is usual in situations involving multiple values. A proposal was submitted to X3J13 in September 1989 to add a setf method for values so that one could in fact write, for example, (setf (values quotient remainder) (truncate linewidth tabstop)) but unless this proposal is accepted users will have to define a setf method for values themselves (not a difficult task). [change_end] [Macro] psetf {place newvalue}* psetf is like setf except that if more than one place-newvalue pair is specified, then the assignments of new values to places are done in parallel. More precisely, all subforms that are to be evaluated are evaluated from left to right; after all evaluations have been performed, all of the assignments are performed in an unpredictable order. (The unpredictability matters only if more than one place form refers to the same place.) psetf always returns nil. [change_begin] X3J13 voted in June 1989 (SETF-MULTIPLE-STORE-VARIABLES) to extend the specification of psetf to allow a place whose setf method has more than one store variable (see define-setf-method). In such a case as many values are accepted from the newvalue form as there are store variables; extra values are ignored and missing values default to nil, as is usual in situations involving multiple values. [change_end] [Macro] shiftf {place}+ newvalue Each place form may be any form acceptable as a generalized variable to setf. In the form (shiftf place1 place2 ... placen newvalue), the values in place1 through placen are accessed and saved, and newvalue is evaluated, for a total of n+1 values in all. Values 2 through n+1 are then stored into place1 through placen, and value 1 (the original value of place1) is returned. It is as if all the places form a shift register; the newvalue is shifted in from the right, all values shift over to the left one place, and the value shifted out of place1 is returned. For example: (setq x (list 'a 'b 'c)) => (a b c) (shiftf (cadr x) 'z) => b and now x => (a z c) (shiftf (cadr x) (cddr x) 'q) => z and now x => (a (c) . q) The effect of (shiftf place1 place2 ... placen newvalue) is equivalent to (let ((var1 place1) (var2 place2) ... (varn placen)) (setf place1 var2) (setf place2 var3) ... (setf placen newvalue) var1) except that the latter would evaluate any subforms of each place twice, whereas shiftf takes care to evaluate them only once. For example: (setq n 0) (setq x '(a b c d)) (shiftf (nth (setq n (+ n 1)) x) 'z) => b and now x => (a z c d) but (setq n 0) (setq x '(a b c d)) (prog1 (nth (setq n (+ n 1)) x) (setf (nth (setq n (+ n 1)) x) 'z)) => b and now x => (a b z d) Moreover, for certain place forms shiftf may be significantly more efficient than the prog1 version. [change_begin] X3J13 voted in June 1989 (SETF-MULTIPLE-STORE-VARIABLES) to extend the specification of shiftf to allow a place whose setf method has more than one store variable (see define-setf-method). In such a case as many values are accepted from the newvalue form as there are store variables; extra values are ignored and missing values default to nil, as is usual in situations involving multiple values. [change_end] ------------------------------------------------------------------------------- Rationale: shiftf and rotatef have been included in Common Lisp as generalizations of two-argument versions formerly called swapf and exchf. The two-argument versions have been found to be very useful, but the names were easily confused. The generalization to many argument forms and the change of names were both inspired by the work of Suzuki [47], which indicates that use of these primitives can make certain complex pointer-manipulation programs clearer and easier to prove correct. ------------------------------------------------------------------------------- [Macro] rotatef {place}* Each place form may be any form acceptable as a generalized variable to setf. In the form (rotatef place1 place2 ... placen), the values in place1 through placen are accessed and saved. Values 2 through n and value 1 are then stored into place1 through placen. It is as if all the places form an end-around shift register that is rotated one place to the left, with the value of place1 being shifted around the end to placen. Note that (rotatef place1 place2) exchanges the contents of place1 and place2. The effect of (rotatef place1 place2 ... placen) is roughly equivalent to (psetf place1 place2 place2 place3 ... placen place1) except that the latter would evaluate any subforms of each place twice, whereas rotatef takes care to evaluate them only once. Moreover, for certain place forms rotatef may be significantly more efficient. rotatef always returns nil. [change_begin] X3J13 voted in June 1989 (SETF-MULTIPLE-STORE-VARIABLES) to extend the specification of rotatef to allow a place whose setf method has more than one store variable (see define-setf-method). In such a case as many values are accepted from the newvalue form as there are store variables; extra values are ignored and missing values default to nil, as is usual in situations involving multiple values. [change_end] Other macros that manipulate generalized variables include getf, remf, incf, decf, push, pop, assert, ctypecase, and ccase. Macros that manipulate generalized variables must guarantee the ``obvious'' semantics: subforms of generalized-variable references are evaluated exactly as many times as they appear in the source program, and they are evaluated in exactly the same order as they appear in the source program. In generalized-variable references such as shiftf, incf, push, and setf of ldb, the generalized variables are both read and written in the same reference. Preserving the source program order of evaluation and the number of evaluations is particularly important. As an example of these semantic rules, in the generalized-variable reference (setf reference value) the value form must be evaluated after all the subforms of the reference because the value form appears to the right of them. The expansion of these macros must consist of code that follows these rules or has the same effect as such code. This is accomplished by introducing temporary variables bound to the subforms of the reference. As an optimization in the implementation, temporary variables may be eliminated whenever it can be proved that removing them has no effect on the semantics of the program. For example, a constant need never be saved in a temporary variable. A variable, or for that matter any form that does not have side effects, need not be saved in a temporary variable if it can be proved that its value will not change within the scope of the generalized-variable reference. Common Lisp provides built-in facilities to take care of these semantic complications and optimizations. Since the required semantics can be guaranteed by these facilities, the user does not have to worry about writing correct code for them, especially in complex cases. Even experts can become confused and make mistakes while writing this sort of code. [change_begin] X3J13 voted in March 1988 (PUSH-EVALUATION-ORDER) to clarify the preceding discussion about the order of evaluation of subforms in calls to setf and related macros. The general intent is clear: evaluation proceeds from left to right whenever possible. However, the left-to-right rule does not remove the obligation on writers of macros and define-setf-method to work to ensure left-to-right order of evaluation. Let it be emphasized that, in the following discussion, a form is something whose syntactic use is such that it will be evaluated. A subform means a form that is nested inside another form, not merely any Lisp object nested inside a form regardless of syntactic context. The evaluation ordering of subforms within a generalized variable reference is determined by the order specified by the second value returned by get-setf-method. For all predefined generalized variable references (getf, ldb), this order of evaluation is exactly left-to-right. When a generalized variable reference is derived from a macro expansion, this rule is applied after the macro is expanded to find the appropriate generalized variable reference. This is intended to make it clear that if the user writes a defmacro or define-setf-method macro that doesn't preserve left-to-right evaluation order, the order specified in the user's code holds. For example, given (defmacro wrong-order (x y) `(getf ,y ,x)) then (push value (wrong-order place1 place2)) will evaluate place2 first and then place1 because that is the order they are evaluated in the macro expansion. For the macros that manipulate generalized variables (push, pushnew, getf, remf, incf, decf, shiftf, rotatef, psetf, setf, pop, and those defined with define-modify-macro) the subforms of the macro call are evaluated exactly once in left-to-right order, with the subforms of the generalized variable references evaluated in the order specified above. Each of push, pushnew, getf, remf, incf, decf, shiftf, rotatef, psetf, and pop evaluates all subforms before modifying any of the generalized variable locations. Moreover, setf itself, in the case when a call on it has more than two arguments, performs its operation on each pair in sequence. That is, in (setf place1 value1 place2 value2 ...) the subforms of place1 and value1 are evaluated, the location specified by place1 is modified to contain the value returned by value1, and then the rest of the setf form is processed in a like manner. For the macros check-type, ctypecase, and ccase, subforms of the generalized variable reference are evaluated once per test of a generalized variable, but they may be evaluated again if the type check fails (in the case of check-type) or if none of the cases holds (in ctypecase or ccase). For the macro assert, the order of evaluation of the generalized variable references is not specified. [change_end] Another reason for building in these functions is that the appropriate optimizations will differ from implementation to implementation. In some implementations most of the optimization is performed by the compiler, while in others a simpler compiler is used and most of the optimization is performed in the macros. The cost of binding a temporary variable relative to the cost of other Lisp operations may differ greatly between one implementation and another, and some implementations may find it best never to remove temporary variables except in the simplest cases. A good example of the issues involved can be seen in the following generalized-variable reference: (incf (ldb byte-field variable)) This ought to expand into something like (setq variable (dpb (1+ (ldb byte-field variable)) byte-field variable)) In this expansion example we have ignored the further complexity of returning the correct value, which is the incremented byte, not the new value of variable. Note that the variable byte-field is evaluated twice, and the variable variable is referred to three times: once as the location in which to store a value, and twice during the computation of that value. Now consider this expression: (incf (ldb (aref byte-fields (incf i)) (aref (determine-words-array) i))) It ought to expand into something like this: (let ((temp1 (aref byte-fields (incf i))) (temp2 (determine-words-array))) (setf (aref temp2 i) (dpb (1+ (ldb temp1 (aref temp2 i))) temp1 (aref temp2 i)))) Again we have ignored the complexity of returning the correct value. What is important here is that the expressions (incf i) and (determine-words-array) must not be duplicated because each may have a side effect or be affected by side effects. [change_begin] X3J13 voted in January 1989 (SETF-SUB-METHODS) to specify more precisely the order of evaluation of subforms when setf is used with an access function that itself takes a place as an argument, for example, ldb, mask-field, and getf. (The vote also discussed the function char-bit, but another vote (CHARACTER-PROPOSAL) removed that function from the language.) The setf methods for such accessors produce expansions that effectively require explicit calls to get-setf-method. The code produced as the macro expansion of a setf form that itself admits a generalized variable as an argument must essentially do the following major steps: * It evaluates the value-producing subforms, in left-to-right order, and binds the temporary variables to them; this is called binding the temporaries. * It reads the value from the generalized variable, using the supplied accessing form, to get the old value; this is called doing the access. Note that this is done after all the evaluations of the preceding step, including any side effects they may have. * It binds the store variable to a new value, and then installs this new value into the generalized variable using the supplied storing form; this is called doing the store. Doing the access for a generalized variable reference is not part of the series of evaluations that must be done in left-to-right order. The place-specifier forms ldb, mask-field, and getf admit (other) place specifiers as arguments. During the setf expansion of these forms, it is necessary to call get-setf-method to determine how the inner, nested generalized variable must be treated. In a form such as (setf (ldb byte-spec place-form) newvalue-form) the place referred to by the place-form must always be both accessed and updated; note that the update is to the generalized variable specified by place-form, not to any object of type integer. Thus this call to setf should generate code to do the following: * Evaluate byte-spec and bind into a temporary * Bind the temporaries for place-form * Evaluate newvalue-form and bind into the store variable * Do the access to place-form * Do the store into place-form with the given bit-field of the accessed integer replaced with the value in the store variable If the evaluation of newvalue-form alters what is found in the given place-such as setting a different bit-field of the integer-then the change of the bit-field denoted by byte-spec will be to that altered integer, because the access step must be done after the newvalue-form evaluation. Nevertheless, the evaluations required for binding the temporaries are done before the evaluation of the newvalue-form, thereby preserving the required left-to-right evaluation order. The treatment of mask-field is similar to that of ldb. In a form such as: (setf (getf place-form ind-form) newvalue-form) the place referred to by the place-form must always be both accessed and updated; note that the update is to the generalized variable specified by place-form, not necessarily to the particular list which is the property list in question. Thus this call to setf should generate code to do the following: * Bind the temporaries for place-form * Evaluate ind-form and bind into a temporary * Evaluate the newvalue-form and bind into the store variable * Do the access to place-form * Do the store into place-form with a possibly new property list obtained by combining the results of the evaluations and the access If the evaluation of newvalue-form alters what is found in the given place-such as setting a different named property in the list-then the change of the property denoted by ind-form will be to that altered list, because the access step is done after the newvalue-form evaluation. Nevertheless, the evaluations required for binding the temporaries are done before the evaluation of the newvalue-form, thereby preserving the required left-to-right evaluation order. Note that the phrase ``possibly new property list'' treats the implementation of property lists as a ``black box''; it can mean that the former property list is somehow destructively re-used, or it can mean partial or full copying of it. A side effect may or may not occur; therefore setf must proceed as if the resultant property list were a different copy needing to be stored back into the generalized variable. [change_end] The Common Lisp facilities provided to deal with these semantic issues include: * Built-in macros such as setf and push that follow the semantic rules. * The define-modify-macro macro, which allows new generalized-variable manipulating macros (of a certain restricted kind) to be defined easily. It takes care of the semantic rules automatically. * The defsetf macro, which allows new types of generalized-variable references to be defined easily. It takes care of the semantic rules automatically. * The define-setf-method macro and the get-setf-method function, which provide access to the internal mechanisms when it is necessary to define a complicated new type of generalized-variable reference or generalized-variable-manipulating macro. [change_begin] Also important are the changes that allow lexical environments to be used in appropriate ways in setf methods. [change_end] [Macro] define-modify-macro name lambda-list function [doc-string] This macro defines a read-modify-write macro named name. An example of such a macro is incf. The first subform of the macro will be a generalized-variable reference. The function is literally the function to apply to the old contents of the generalized-variable to get the new contents; it is not evaluated. lambda-list describes the remaining arguments for the function; these arguments come from the remaining subforms of the macro after the generalized-variable reference. lambda-list may contain &optional and &rest markers. (The &key marker is not permitted here; &rest suffices for the purposes of define-modify-macro.) doc-string is documentation for the macro name being defined. The expansion of a define-modify-macro is equivalent to the following, except that it generates code that follows the semantic rules outlined above. (defmacro name (reference . lambda-list) doc-string `(setf ,reference (function ,reference ,arg1 ,arg2 ...))) where arg1, arg2, ..., are the parameters appearing in lambda-list; appropriate provision is made for a &rest parameter. As an example, incf could have been defined by: (define-modify-macro incf (&optional (delta 1)) +) An example of a possibly useful macro not predefined in Common Lisp is (define-modify-macro unionf (other-set &rest keywords) union) [change_begin] X3J13 voted in March 1988 (GET-SETF-METHOD-ENVIRONMENT) to specify that define-modify-macro creates macros that take &environment arguments and perform the equivalent of correctly passing such lexical environments to get-setf-method in order to correctly maintain lexical references. [change_end] [Macro] defsetf access-fn {update-fn [doc-string] | lambda-list (store-variable) [[{declaration}* | doc-string]] {form}*} This defines how to setf a generalized-variable reference of the form (access-fn ...). The value of a generalized-variable reference can always be obtained simply by evaluating it, so access-fn should be the name of a function or a macro. The user of defsetf provides a description of how to store into the generalized-variable reference and return the value that was stored (because setf is defined to return this value). The implementation of defsetf takes care of ensuring that subforms of the reference are evaluated exactly once and in the proper left-to-right order. In order to do this, defsetf requires that access-fn be a function or a macro that evaluates its arguments, behaving like a function. Furthermore, a setf of a call on access-fn will also evaluate all of access-fn's arguments; it cannot treat any of them specially. This means that defsetf cannot be used to describe how to store into a generalized variable that is a byte, such as (ldb field reference). To handle situations that do not fit the restrictions imposed by defsetf, use define-setf-method, which gives the user additional control at the cost of increased complexity. A defsetf declaration may take one of two forms. The simple form is (defsetf access-fn update-fn doc-string) The update-fn must name a function (or macro) that takes one more argument than access-fn takes. When setf is given a place that is a call on access-fn, it expands into a call on update-fn that is given all the arguments to access-fn and also, as its last argument, the new value (which must be returned by update-fn as its value). For example, the effect of (defsetf symbol-value set) is built into the Common Lisp system. This causes the expansion (setf (symbol-value foo) fu) -> (set foo fu) for example. Note that (defsetf car rplaca) would be incorrect because rplaca does not return its last argument. The complex form of defsetf looks like (defsetf access-fn lambda-list (store-variable) . body) and resembles defmacro. The body must compute the expansion of a setf of a call on access-fn. The lambda-list describes the arguments of access-fn. &optional, &rest, and &key markers are permitted in lambda-list. Optional arguments may have defaults and ``supplied-p'' flags. The store-variable describes the value to be stored into the generalized-variable reference. ------------------------------------------------------------------------------- Rationale: The store-variable is enclosed in parentheses to provide for an extension to multiple store variables that would receive multiple values from the second subform of setf. The rules given below for coding setf methods discuss the proper handling of multiple store variables to allow for the possibility that this extension may be incorporated into Common Lisp in the future. ------------------------------------------------------------------------------- The body forms can be written as if the variables in the lambda-list were bound to subforms of the call on access-fn and the store-variable were bound to the second subform of setf. However, this is not actually the case. During the evaluation of the body forms, these variables are bound to names of temporary variables, generated as if by gensym or gentemp, that will be bound by the expansion of setf to the values of those subforms. This binding permits the body forms to be written without regard for order-of-evaluation issues. defsetf arranges for the temporary variables to be optimized out of the final result in cases where that is possible. In other words, an attempt is made by defsetf to generate the best code possible in a particular implementation. Note that the code generated by the body forms must include provision for returning the correct value (the value of store-variable). This is handled by the body forms rather than by defsetf because in many cases this value can be returned at no extra cost, by calling a function that simultaneously stores into the generalized variable and returns the correct value. An example of the use of the complex form of defsetf: (defsetf subseq (sequence start &optional end) (new-sequence) `(progn (replace ,sequence ,new-sequence :start1 ,start :end1 ,end) ,new-sequence)) [change_begin] X3J13 voted in March 1988 (FLET-IMPLICIT-BLOCK) to specify that the body of the expander function defined by the complex form of defsetf is implicitly enclosed in a block construct whose name is the same as the name of the access-fn. Therefore return-from may be used to exit from the function. X3J13 voted in March 1989 (DEFINING-MACROS-NON-TOP-LEVEL) to clarify that, while defining forms normally appear at top level, it is meaningful to place them in non-top-level contexts; the complex form of defsetf must define the expander function within the enclosing lexical environment, not within the global environment. [change_end] The underlying theory by which setf and related macros arrange to conform to the semantic rules given above is that from any generalized-variable reference one may derive its ``setf method,'' which describes how to store into that reference and which subforms of it are evaluated. ------------------------------------------------------------------------------- Compatibility note: To avoid confusion, it should be noted that the use of the word ``method'' here in connection with setf has nothing to do with its use in Lisp Machine Lisp in connection with message-passing and the Lisp Machine Lisp ``flavor system.'' [change_begin] And of course it also has nothing to do with the methods in the Common Lisp Object System (CLOS) . [change_end] ------------------------------------------------------------------------------- Given knowledge of the subforms of the reference, it is possible to avoid evaluating them multiple times or in the wrong order. A setf method for a given access form can be expressed as five values: * A list of temporary variables * A list of value forms (subforms of the given form) to whose values the temporary variables are to be bound * A second list of temporary variables, called store variables * A storing form * An accessing form The temporary variables will be bound to the values of the value forms as if by let*; that is, the value forms will be evaluated in the order given and may refer to the values of earlier value forms by using the corresponding variables. The store variables are to be bound to the values of the newvalue form, that is, the values to be stored into the generalized variable. In almost all cases only a single value is to be stored, and there is only one store variable. The storing form and the accessing form may contain references to the temporary variables (and also, in the case of the storing form, to the store variables). The accessing form returns the value of the generalized variable. The storing form modifies the value of the generalized variable and guarantees to return the values of the store variables as its values; these are the correct values for setf to return. (Again, in most cases there is a single store variable and thus a single value to be returned.) The value returned by the accessing form is, of course, affected by execution of the storing form, but either of these forms may be evaluated any number of times and therefore should be free of side effects (other than the storing action of the storing form). The temporary variables and the store variables are generated names, as if by gensym or gentemp, so that there is never any problem of name clashes among them, or between them and other variables in the program. This is necessary to make the special forms that do more than one setf in parallel work properly; these are psetf, shiftf, and rotatef. Computation of the setf method must always create new variable names; it may not return the same ones every time. Some examples of setf methods for particular forms: * For a variable x: () () (g0001) (setq x g0001) x * For (car exp): (g0002) (exp) (g0003) (progn (rplaca g0002 g0003) g0003) (car g0002) * For (subseq seq s e): (g0004 g0005 g0006) (seq s e) (g0007) (progn (replace g0004 g0007 :start1 g0005 :end1 g0006) g0007) (subseq g0004 g0005 g0006) [Macro] define-setf-method access-fn lambda-list [[ {declaration}* | doc-string ]] {form}* This defines how to setf a generalized-variable reference that is of the form (access-fn...). The value of a generalized-variable reference can always be obtained simply by evaluating it, so access-fn should be the name of a function or a macro. The lambda-list describes the subforms of the generalized-variable reference, as with defmacro. The result of evaluating the forms in the body must be five values representing the setf method, as described above. Note that define-setf-method differs from the complex form of defsetf in that while the body is being executed the variables in lambda-list are bound to parts of the generalized-variable reference, not to temporary variables that will be bound to the values of such parts. In addition, define-setf-method does not have defsetf's restriction that access-fn must be a function or a function-like macro; an arbitrary defmacro destructuring pattern is permitted in lambda-list. By definition there are no good small examples of define-setf-method because the easy cases can all be handled by defsetf. A typical use is to define the setf method for ldb: ;;; SETF method for the form (LDB bytespec int). ;;; Recall that the int form must itself be suitable for SETF. (define-setf-method ldb (bytespec int) (multiple-value-bind (temps vals stores store-form access-form) (get-setf-method int) ;Get SETF method for int (let ((btemp (gensym)) ;Temp var for byte specifier (store (gensym)) ;Temp var for byte to store (stemp (first stores))) ;Temp var for int to store ;; Return the SETF method for LDB as five values. (values (cons btemp temps) ;Temporary variables (cons bytespec vals) ;Value forms (list store) ;Store variables `(let ((,stemp (dpb ,store ,btemp ,access-form))) ,store-form ,store) ;Storing form `(ldb ,btemp ,access-form) ;Accessing form )))) [change_begin] X3J13 voted in March 1988 (GET-SETF-METHOD-ENVIRONMENT) to specify that the &environment lambda-list keyword may appear in the lambda-list in the same manner as for defmacro in order to obtain the lexical environment of the call to the setf macro. The preceding example should be modified to take advantage of this new feature. The setf method must accept an &environment parameter, which will receive the lexical environment of the call to setf; this environment must then be given to get-setf-method in order that it may correctly use any locally bound setf method that might be applicable to the place form that appears as the second argument to ldb in the call to setf. ;;; SETF method for the form (LDB bytespec int). ;;; Recall that the int form must itself be suitable for SETF. ;;; Note the use of an &environment parameter to receive the ;;; lexical environment of the call for use with GET-SETF-METHOD. (define-setf-method ldb (bytespec int &environment env) (multiple-value-bind (temps vals stores store-form access-form) (get-setf-method int env) ;Get SETF method for int (let ((btemp (gensym)) ;Temp var for byte specifier (store (gensym)) ;Temp var for byte to store (stemp (first stores))) ;Temp var for int to store ;; Return the SETF method for LDB as five values. (values (cons btemp temps) ;Temporary variables (cons bytespec vals) ;Value forms (list store) ;Store variables `(let ((,stemp (dpb ,store ,btemp ,access-form))) ,store-form ,store) ;Storing form `(ldb ,btemp ,access-form) ;Accessing form )))) X3J13 voted in March 1988 (FLET-IMPLICIT-BLOCK) to specify that the body of the expander function defined by define-setf-method is implicitly enclosed in a block construct whose name is the same as the name of the access-fn. Therefore return-from may be used to exit from the function. X3J13 voted in March 1989 (DEFINING-MACROS-NON-TOP-LEVEL) to clarify that, while defining forms normally appear at top level, it is meaningful to place them in non-top-level contexts; define-setf-method must define the expander function within the enclosing lexical environment, not within the global environment. [change_end] [old_change_begin] [Function] get-setf-method form get-setf-method returns five values constituting the setf method for form. The form must be a generalized-variable reference. get-setf-method takes care of error-checking and macro expansion and guarantees to return exactly one store variable. As an example, an extremely simplified version of setf, allowing no more and no fewer than two subforms, containing no optimization to remove unnecessary variables, and not allowing storing of multiple values, could be defined by: (defmacro setf (reference value) (multiple-value-bind (vars vals stores store-form access-form) (get-setf-method reference) (declare (ignore access-form)) `(let* ,(mapcar #'list (append vars stores) (append vals (list value))) ,store-form))) [old_change_end] [change_begin] X3J13 voted in March 1988 (GET-SETF-METHOD-ENVIRONMENT) to add an optional environment argument to get-setf-method. The revised definition and example are as follows. [Function] get-setf-method form &optional env get-setf-method returns five values constituting the setf method for form. The form must be a generalized-variable reference. The env must be an environment of the sort obtained through the &environment lambda-list keyword; if env is nil or omitted, the null lexical environment is assumed. get-setf-method takes care of error checking and macro expansion and guarantees to return exactly one store variable. As an example, an extremely simplified version of setf, allowing no more and no fewer than two subforms, containing no optimization to remove unnecessary variables, and not allowing storing of multiple values, could be defined by: (defmacro setf (reference value &environment env) (multiple-value-bind (vars vals stores store-form access-form) (get-setf-method reference env) ;Note use of environment (declare (ignore access-form)) `(let* ,(mapcar #'list (append vars stores) (append vals (list value))) ,store-form))) [change_end] [old_change_begin] [Function] get-setf-method-multiple-value form get-setf-method-multiple-value returns five values constituting the setf method for form. The form must be a generalized-variable reference. This is the same as get-setf-method except that it does not check the number of store variables; use this in cases that allow storing multiple values into a generalized variable. There are no such cases in standard Common Lisp, but this function is provided to allow for possible extensions. [old_change_end] [change_begin] X3J13 voted in March 1988 (GET-SETF-METHOD-ENVIRONMENT) to add an optional environment argument to get-setf-method. The revised definition is as follows. [Function] get-setf-method-multiple-value form &optional env get-setf-method-multiple-value returns five values constituting the setf method for form. The form must be a generalized-variable reference. The env must be an environment of the sort obtained through the &environment lambda-list keyword; if env is nil or omitted, the null lexical environment is assumed. This is the same as get-setf-method except that it does not check the number of store variables; use this in cases that allow storing multiple values into a generalized variable. There are no such cases in standard Common Lisp, but this function is provided to allow for possible extensions. X3J13 voted in March 1988 (GET-SETF-METHOD-ENVIRONMENT) to clarify that a setf method for a functional name is applicable only when the global binding of that name is lexically visible. If such a name has a local binding introduced by flet, labels, or macrolet, then global definitions of setf methods for that name do not apply and are not visible. All of the standard Common Lisp macros that modify a setf place (for example, incf, decf, pop, and rotatef) obey this convention. [change_end] ------------------------------------------------------------------------------- 7.3. Function Invocation The most primitive form for function invocation in Lisp of course has no name; any list that has no other interpretation as a macro call or special form is taken to be a function call. Other constructs are provided for less common but nevertheless frequently useful situations. [Function] apply function arg &rest more-args This applies function to a list of arguments. [old_change_begin] The function may be a compiled-code object, or a lambda-expression, or a symbol; in the latter case the global functional value of that symbol is used (but it is illegal for the symbol to be the name of a macro or special form). [old_change_end] [change_begin] X3J13 voted in June 1988 (FUNCTION-TYPE) to allow the function to be only of type symbol or function; a lambda-expression is no longer acceptable as a functional argument. One must use the function special form or the abbreviation #' before a lambda-expression that appears as an explicit argument form. [change_end] The arguments for the function consist of the last argument to apply appended to the end of a list of all the other arguments to apply but the function itself; it is as if all the arguments to apply except the function were given to list* to create the argument list. For example: (setq f '+) (apply f '(1 2)) => 3 (setq f #'-) (apply f '(1 2)) => -1 (apply #'max 3 5 '(2 7 3)) => 7 (apply 'cons '((+ 2 3) 4)) => ((+ 2 3) . 4) not (5 . 4) (apply #'+ '()) => 0 Note that if the function takes keyword arguments, the keywords as well as the corresponding values must appear in the argument list: (apply #'(lambda (&key a b) (list a b)) '(:b 3)) => (nil 3) This can be very useful in conjunction with the &allow-other-keys feature: (defun foo (size &rest keys &key double &allow-other-keys) (let ((v (apply #'make-array size :allow-other-keys t keys))) (if double (concatenate (type-of v) v v) v))) (foo 4 :initial-contents '(a b c d) :double t) => #(a b c d a b c d) [Function] funcall fn &rest arguments (funcall fn a1 a2 ... an) applies the function fn to the arguments a1, a2, ..., an. The fn may not be a special form or a macro; this would not be meaningful. [change_begin] X3J13 voted in June 1988 (FUNCTION-TYPE) to allow the fn to be only of type symbol or function; a lambda-expression is no longer acceptable as a functional argument. One must use the function special form or the abbreviation #' before a lambda-expression that appears as an explicit argument form. [change_end] For example: (cons 1 2) => (1 . 2) (setq cons (symbol-function '+)) (funcall cons 1 2) => 3 The difference between funcall and an ordinary function call is that the function is obtained by ordinary Lisp evaluation rather than by the special interpretation of the function position that normally occurs. ------------------------------------------------------------------------------- Compatibility note: The Common Lisp function funcall corresponds roughly to the Interlisp primitive apply*. ------------------------------------------------------------------------------- [Constant] call-arguments-limit The value of call-arguments-limit is a positive integer that is the upper exclusive bound on the number of arguments that may be passed to a function. This bound depends on the implementation but will not be smaller than 50. (Implementors are encouraged to make this limit as large as practicable without sacrificing performance.) The value of call-arguments-limit must be at least as great as that of lambda-parameters-limit. See also multiple-values-limit. ------------------------------------------------------------------------------- 7.4. Simple Sequencing Each of the constructs in this section simply evaluates all the argument forms in order. They differ only in what results are returned. [Special Form] progn {form}* The progn construct takes a number of forms and evaluates them sequentially, in order, from left to right. The values of all the forms but the last are discarded; whatever the last form returns is returned by the progn form. One says that all the forms but the last are evaluated for effect, because their execution is useful only for the side effects caused, but the last form is executed for value. progn is the primitive control structure construct for ``compound statements,'' such as begin-end blocks in Algol-like languages. Many Lisp constructs are ``implicit progn'' forms: as part of their syntax each allows many forms to be written that are to be evaluated sequentially, discarding the results of all forms but the last and returning the results of the last form. If the last form of the progn returns multiple values, then those multiple values are returned by the progn form. If there are no forms for the progn, then the result is nil. These rules generally hold for implicit progn forms as well. [Macro] prog1 first {form}* prog1 is similar to progn, but it returns the value of its first form. All the argument forms are executed sequentially; the value of the first form is saved while all the others are executed and is then returned. prog1 is most commonly used to evaluate an expression with side effects and to return a value that must be computed before the side effects happen. For example: (prog1 (car x) (rplaca x 'foo)) alters the car of x to be foo and returns the old car of x. prog1 always returns a single value, even if the first form tries to return multiple values. As a consequence, (prog1 x) and (progn x) may behave differently if x can produce multiple values. See multiple-value-prog1. A point of style: although prog1 can be used to force exactly a single value to be returned, it is conventional to use the function values for this purpose. [Macro] prog2 first second {form}* prog2 is similar to prog1, but it returns the value of its second form. All the argument forms are executed sequentially; the value of the second form is saved while all the other forms are executed and is then returned. prog2 is provided mostly for historical compatibility. (prog2 a b c ... z) == (progn a (prog1 b c ... z)) Occasionally it is desirable to perform one side effect, then a value-producing operation, then another side effect. In such a peculiar case, prog2 is fairly perspicuous. For example: (prog2 (open-a-file) (process-the-file) (close-the-file)) ;value is that of process-the-file prog2, like prog1, always returns a single value, even if the second form tries to return multiple values. As a consequence of this, (prog2 x y) and (progn x y) may behave differently if y can produce multiple values. ------------------------------------------------------------------------------- 7.5. Establishing New Variable Bindings During the invocation of a function represented by a lambda-expression (or a closure of a lambda-expression, as produced by function), new bindings are established for the variables that are the parameters of the lambda-expression. These bindings initially have values determined by the parameter-binding protocol discussed in section 5.2.2. The following constructs may also be used to establish bindings of variables, both ordinary and functional. [Special Form] let ({var | (var value)}*) {declaration}* {form}* A let form can be used to execute a series of forms with specified variables bound to specified values. More precisely, the form (let ((var1 value1) (var2 value2) ... (varm valuem)) declaration1 declaration2 ... declarationp body1 body2 ... bodyn) first evaluates the expressions value1, value2, and so on, in that order, saving the resulting values. Then all of the variables varj are bound to the corresponding values in parallel; each binding will be a lexical binding unless there is a special declaration to the contrary. The expressions bodyk are then evaluated in order; the values of all but the last are discarded (that is, the body of a let form is an implicit progn). The let form returns what evaluating bodyn produces (if the body is empty, which is fairly useless, let returns nil as its value). The bindings of the variables have lexical scope and indefinite extent. Instead of a list (varj valuej), one may write simply varj. In this case varj is initialized to nil. As a matter of style, it is recommended that varj be written only when that variable will be stored into (such as by setq) before its first use. If it is important that the initial value be nil rather than some undefined value, then it is clearer to write out (varj nil) if the initial value is intended to mean ``false,'' or (varj '()) if the initial value is intended to be an empty list. Note that the code (let (x) (declare (integer x)) (setq x (gcd y z)) ...) is incorrect; although x is indeed set before it is used, and is set to a value of the declared type integer, nevertheless x momentarily takes on the value nil in violation of the type declaration. Declarations may appear at the beginning of the body of a let. See declare. [change_begin] See also destructuring-bind. X3J13 voted in January 1989 (VARIABLE-LIST-ASYMMETRY) to regularize the binding formats for do, do*, let, let*, prog, prog*, and compiler-let. The new syntactic definition for let makes the value optional: [Special Form] let ({var | (var [value])}*) {declaration}* {form}* This changes let to allow a list (var) to appear, meaning the same as simply var. [change_end] [Special Form] let* ({var | (var value)}*) {declaration}* {form}* let* is similar to let, but the bindings of variables are performed sequentially rather than in parallel. This allows the expression for the value of a variable to refer to variables previously bound in the let* form. More precisely, the form (let* ((var1 value1) (var2 value2) ... (varm valuem)) declaration1 declaration2 ... declarationp body1 body2 ... bodyn) first evaluates the expression value1, then binds the variable var1 to that value; then it evaluates value2 and binds var2; and so on. The expressions bodyj are then evaluated in order; the values of all but the last are discarded (that is, the body of a let* form is an implicit progn). The let* form returns the results of evaluating bodyn (if the body is empty, which is fairly useless, let* returns nil as its value). The bindings of the variables have lexical scope and indefinite extent. Instead of a list (varj valuej), one may write simply varj. In this case varj is initialized to nil. As a matter of style, it is recommended that varj be written only when that variable will be stored into (such as by setq) before its first use. If it is important that the initial value be nil rather than some undefined value, then it is clearer to write out (varj nil) if the initial value is intended to mean ``false,'' or (varj '()) if the initial value is intended to be an empty list. Declarations may appear at the beginning of the body of a let*. See declare. [change_begin] X3J13 voted in January 1989 (VARIABLE-LIST-ASYMMETRY) to regularize the binding formats for do, do*, let, let*, prog, prog*, and compiler-let. The new syntactic definition for let* makes the value optional: [Special Form] let* ({var | (var [value])}*) {declaration}* {form}* This changes let* to allow a list (var) to appear, meaning the same as simply var. [change_end] [old_change_begin] [Special Form] compiler-let ({var | (var value)}*) {form}* When executed by the Lisp interpreter, compiler-let behaves exactly like let with all the variable bindings implicitly declared special. When the compiler processes this form, however, no code is compiled for the bindings; instead, the processing of the body by the compiler (including, in particular, the expansion of any macro calls within the body) is done with the special variables bound to the indicated values in the execution context of the compiler. This is primarily useful for communication among complicated macros. Declarations may not appear at the beginning of the body of a compiler-let. ------------------------------------------------------------------------------- Rationale: Because of the unorthodox handling by compiler-let of its variable bindings, it would be complicated and confusing to permit declarations that apparently referred to the variables bound by compiler-let. Disallowing declarations eliminates the problem. ------------------------------------------------------------------------------- X3J13 voted in January 1989 (VARIABLE-LIST-ASYMMETRY) to regularize the binding formats for do, do*, let, let*, prog, prog*, and compiler-let. The new syntactic definition for compiler-let makes the value optional: [Macro] compiler-let ({var | (var [value])}*) {form}* This changes compiler-let to allow a list (var) to appear, meaning the same as simply var. [old_change_end] [change_begin] X3J13 voted in June 1989 (COMPILER-LET-CONFUSION) to remove compiler-let from the language. Many uses of compiler-let can be replaced with more portable code that uses macrolet or symbol-macrolet. [change_end] [Special Form] progv symbols values {form}* progv is a special form that allows binding one or more dynamic variables whose names may be determined at run time. The sequence of forms (an implicit progn) is evaluated with the dynamic variables whose names are in the list symbols bound to corresponding values from the list values. (If too few values are supplied, the remaining symbols are bound and then made to have no value; see makunbound. If too many values are supplied, the excess values are ignored.) The results of the progv form are those of the last form. The bindings of the dynamic variables are undone on exit from the progv form. The lists of symbols and values are computed quantities; this is what makes progv different from, for example, let, where the variable names are stated explicitly in the program text. progv is particularly useful for writing interpreters for languages embedded in Lisp; it provides a handle on the mechanism for binding dynamic variables. [Special Form] flet ({(name lambda-list [[ {declaration}* | doc-string ]] {form}*)}*) {form}* labels ({(name lambda-list [[ {declaration}* | doc-string ]] {form}*)}*) {form}* macrolet ({(name varlist [[ {declaration}* | doc-string ]] {form}*)}*) {form}* flet may be used to define locally named functions. Within the body of the flet form, function names matching those defined by the flet refer to the locally defined functions rather than to the global function definitions of the same name. Any number of functions may be simultaneously defined. Each definition is similar in format to a defun form: first a name, then a parameter list (which may contain &optional, &rest, or &key parameters), then optional declarations and documentation string, and finally a body. (flet ((safesqrt (x) (sqrt (abs x)))) ;; The safesqrt function is used in two places. (safesqrt (apply #'+ (map 'list #'safesqrt longlist)))) The labels construct is identical in form to the flet construct. These constructs differ in that the scope of the defined function names for flet encompasses only the body, whereas for labels it encompasses the function definitions themselves. That is, labels can be used to define mutually recursive functions, but flet cannot. This distinction is useful. Using flet one can locally redefine a global function name, and the new definition can refer to the global definition; the same construction using labels would not have that effect. (defun integer-power (n k) ;A highly "bummed" integer (declare (integer n)) ; exponentiation routine (declare (type (integer 0 *) k)) (labels ((expt0 (x k a) (declare (integer x a) (type (integer 0 *) k)) (cond ((zerop k) a) ((evenp k) (expt1 (* x x) (floor k 2) a)) (t (expt0 (* x x) (floor k 2) (* x a))))) (expt1 (x k a) (declare (integer x a) (type (integer 1 *) k)) (cond ((evenp k) (expt1 (* x x) (floor k 2) a)) (t (expt0 (* x x) (floor k 2) (* x a)))))) (expt0 n k 1))) macrolet is similar in form to flet but defines local macros, using the same format used by defmacro. The names established by macrolet as names for macros are lexically scoped. [change_begin] I have observed that, while most Common Lisp users pronounce macrolet to rhyme with ``silhouette,'' a small but vocal minority pronounce it to rhyme with ``Chevrolet.'' A very few extremists furthermore adjust their pronunciation of flet similarly: they say ``flay.'' Hey, hey! TrËs outrÈ. [change_end] Macros often must be expanded at ``compile time'' (more generally, at a time before the program itself is executed), and so the run-time values of variables are not available to macros defined by macrolet. [old_change_begin] The precise rule is that the macro-expansion functions defined by macrolet are defined in the global environment; lexically scoped entities that would ordinarily be lexically apparent are not visible within the expansion functions. [old_change_end] [change_begin] X3J13 voted in March 1989 (DEFINING-MACROS-NON-TOP-LEVEL) to retract the previous sentence and specify that the macro-expansion functions created by macrolet are defined in the lexical environment in which the macrolet form appears, not in the null lexical environment. Declarations, macrolet definitions, and symbol-macrolet definitions affect code within the expansion functions in a macrolet, but the consequences are undefined if such code attempts to refer to any local variable or function bindings that are visible in that lexical environment. [change_end] However, lexically scoped entities are visible within the body of the macrolet form and are visible to the code that is the expansion of a macro call. The following example should make this clear: ;;; Example of scoping in macrolet. (defun foo (x flag) (macrolet ((fudge (z) ;;The parameters x and flag are not accessible ;; at this point; a reference to flag would be to ;; the global variable of that name. `(if flag (* ,z ,z) ,z))) ;;The parameters x and flag are accessible here. (+ x (fudge x) (fudge (+ x 1))))) The body of the macrolet becomes (+ x (if flag (* x x) x)) (if flag (* (+ x 1) (+ x 1)) (+ x 1))) after macro expansion. The occurrences of x and flag legitimately refer to the parameters of the function foo because those parameters are visible at the site of the macro call which produced the expansion. [change_begin] X3J13 voted in March 1988 (FLET-IMPLICIT-BLOCK) to specify that the body of each function or expander function defined by flet, labels, or macrolet is implicitly enclosed in a block construct whose name is the same as the name of the function. Therefore return-from may be used to exit from the function. X3J13 voted in March 1989 (FUNCTION-NAME) to extend flet and labels to accept any function-name (a symbol or a list whose car is setf-see section 7.1) as a name for a function to be locally defined. In this way one can create local definitions for setf expansion functions. (X3J13 explicitly declined to extend macrolet in the same manner.) X3J13 voted in March 1988 (FLET-DECLARATIONS) to change flet, labels, and macrolet to allow declarations to appear before the body. The new descriptions are therefore as follows: [Special Form] flet ({(name lambda-list [[ {declaration}* | doc-string ]] {form}*)}*) {declaration}* {form}* labels ({(name lambda-list [[ {declaration}* | doc-string ]] {form}*)}*) {declaration}* {form}* macrolet ({(name varlist [[ {declaration}* | doc-string ]] {form}*)}*) {declaration}* {form}* These are now syntactically more similar to such other binding forms as let. For flet and labels, the bodies of the locally defined functions are part of the scope of pervasive declarations appearing before the main body. (This is consistent with the treatment of initialization forms in let.) For macrolet, however, the bodies of the locally defined macro expander functions are not included in the scope of pervasive declarations appearing before the main body. (This is consistent with the rule, stated below, that the bodies of macro expander functions are in the global environment, not the local lexical environment.) Here is an example: (flet ((stretch (x) (* x *stretch-factor*)) (chop (x) (- x *chop-margin*))) (declare (inline stretch chop)) ;Illegal in original Common Lisp (if (> x *chop-margin*) (stretch (chop x)) (chop (stretch x)))) X3J13 voted to permit declarations of the sort noted above. [change_end] [change_begin] [Special Form] symbol-macrolet ({(var expansion)}*) {declaration}* {form}* X3J13 voted in June 1988 (CLOS) to adopt the Common Lisp Object System. Part of this proposal is a general mechanism, symbol-macrolet, for treating certain variable names as if they were parameterless macro calls. This facility may be useful independent of CLOS. X3J13 voted in March 1989 (SYMBOL-MACROLET-SEMANTICS) to modify the definition of symbol-macrolet substantially and also voted (SYMBOL-MACROLET-DECLARE) to allow declarations before the body of symbol-macrolet but with peculiar treatment of special and type declarations. The forms are executed as an implicit progn in a lexical environment that causes every reference to any defined var to be replaced by the corresponding expansion. It is as if the reference to the var were a parameterless macro call; the expansion is evaluated or otherwise processed in place of the reference (in particular, the expansion form is itself subject to further expansion-this is one of the changes (SYMBOL-MACROLET-SEMANTICS) from the original definition in the CLOS proposal). Note, however, that the names of such symbol macros occupy the name space of variables, not the name space of functions; just as one may have a function (or macro, or special form) and a variable with the same name without interference, so one may have an ordinary macro (or function, or special form) and a symbol macro with the same name. The use of symbol-macrolet can therefore be shadowed by let or other constructs that bind variables; symbol-macrolet does not substitute for all occurrences of a var as a variable but only for those occurrences that would be construed as references in the scope of a lexical binding of var as a variable. For example: (symbol-macrolet ((pollyanna 'goody)) (list pollyanna (let ((pollyanna 'two-shoes)) pollyanna))) => (goody two-shoes), not (goody goody) One might think that 'goody simply replaces all occurrences of pollyanna, and so the value of the let would be goody; but this is not so. A little reflection shows that under this incorrect interpretation the body in expanded form would be (list 'goody (let (('goody 'two-shoes)) 'goody)) which is syntactically malformed. The correct expanded form is (list 'goody (let ((pollyanna 'two-shoes)) pollyanna)) because the rebinding of pollyanna by the let form shadows the symbol macro definition. The expansion for each var is not evaluated at binding time but only after it has replaced a reference to the var. The setf macro allows a symbol macro to be used as a place, in which case its expansion is used; moreover, setq of a variable that is really a symbol macro will be treated as if setf had been used. The values of the last form are returned, or nil if there is no value. See macroexpand and macroexpand-1; they will expand symbol macros as well as ordinary macros. Certain declarations before the body are handled in a peculiar manner; see section 9.1. [change_end] ------------------------------------------------------------------------------- 7.6. Conditionals The traditional conditional construct in Lisp is cond. However, if is much simpler and is directly comparable to conditional constructs in other programming languages, so it is considered to be primitive in Common Lisp and is described first. Common Lisp also provides the dispatching constructs case and typecase, which are often more convenient than cond. [Special Form] if test then [else] The if special form corresponds to the if-then-else construct found in most algebraic programming languages. First the form test is evaluated. If the result is not nil, then the form then is selected; otherwise the form else is selected. Whichever form is selected is then evaluated, and if returns whatever is returned by evaluation of the selected form. (if test then else) == (cond (test then) (t else)) but if is considered more readable in some situations. The else form may be omitted, in which case if the value of test is nil then nothing is done and the value of the if form is nil. If the value of the if form is important in this situation, then the and construct may be stylistically preferable, depending on the context. If the value is not important, but only the effect, then the when construct may be stylistically preferable. [Macro] when test {form}* (when test form1 form2 ... ) first evaluates test. If the result is nil, then no form is evaluated, and nil is returned. Otherwise the forms constitute an implicit progn and are evaluated sequentially from left to right, and the value of the last one is returned. (when p a b c) == (and p (progn a b c)) (when p a b c) == (cond (p a b c)) (when p a b c) == (if p (progn a b c) nil) (when p a b c) == (unless (not p) a b c) As a matter of style, when is normally used to conditionally produce some side effects, and the value of the when form is normally not used. If the value is relevant, then it may be stylistically more appropriate to use and or if. [Macro] unless test {form}* (unless test form1 form2 ... ) first evaluates test. If the result is not nil, then the forms are not evaluated, and nil is returned. Otherwise the forms constitute an implicit progn and are evaluated sequentially from left to right, and the value of the last one is returned. (unless p a b c) == (cond ((not p) a b c)) (unless p a b c) == (if p nil (progn a b c)) (unless p a b c) == (when (not p) a b c) As a matter of style, unless is normally used to conditionally produce some side effects, and the value of the unless form is normally not used. If the value is relevant, then it may be stylistically more appropriate to use if. [Macro] cond {(test {form}*)}* A cond form has a number (possibly zero) of clauses, which are lists of forms. Each clause consists of a test followed by zero or more consequents. For example: (cond (test-1 consequent-1-1 consequent-1-2 ...) (test-2) (test-3 consequent-3-1 ...) ... ) The first clause whose test evaluates to non-nil is selected; all other clauses are ignored, and the consequents of the selected clause are evaluated in order (as an implicit progn). More specifically, cond processes its clauses in order from left to right. For each clause, the test is evaluated. If the result is nil, cond advances to the next clause. Otherwise, the cdr of the clause is treated as a list of forms, or consequents; these forms are evaluated in order from left to right, as an implicit progn. After evaluating the consequents, cond returns without inspecting any remaining clauses. The cond special form returns the results of evaluating the last of the selected consequents; if there were no consequents in the selected clause, then the single (and necessarily non-null) value of the test is returned. If cond runs out of clauses (every test produced nil, and therefore no clause was selected), the value of the cond form is nil. If it is desired to select the last clause unconditionally if all others fail, the standard convention is to use t for the test. As a matter of style, it is desirable to write a last clause (t nil) if the value of the cond form is to be used for something. Similarly, it is in questionable taste to let the last clause of a cond be a ``singleton clause''; an explicit t should be provided. (Note moreover that (cond ... (x)) may behave differently from (cond ... (t x)) if x might produce multiple values; the former always returns a single value, whereas the latter returns whatever values x returns. However, as a matter of style it is preferable to obtain this behavior by writing (cond ... (t (values x))), using the values function explicitly to indicate the discarding of any excess values.) For example: (setq z (cond (a 'foo) (b 'bar))) ;Possibly confusing (setq z (cond (a 'foo) (b 'bar) (t nil))) ;Better (cond (a b) (c d) (e)) ;Possibly confusing (cond (a b) (c d) (t e)) ;Better (cond (a b) (c d) (t (values e))) ;Better (if one value ; needed) (cond (a b) (c)) ;Possibly confusing (cond (a b) (t c)) ;Better (if a b c) ;Also better A Lisp cond form may be compared to a continued if-then-else as found in many algebraic programming languages: (cond (p ...) if p then ... (q ...) roughly else if q then ... (r ...) corresponds else if r then ... ... to ... (t ...)) else ... [Macro] case keyform {({({key}*) | key} {form}*)}* case is a conditional that chooses one of its clauses to execute by comparing a value to various constants, which are typically keyword symbols, integers, or characters (but may be any objects). Its form is as follows: (case keyform (keylist-1 consequent-1-1 consequent-1-2 ...) (keylist-2 consequent-2-1 ...) (keylist-3 consequent-3-1 ...) ...) Structurally case is much like cond, and it behaves like cond in selecting one clause and then executing all consequents of that clause. However, case differs in the mechanism of clause selection. The first thing case does is to evaluate the form keyform to produce an object called the key object. Then case considers each of the clauses in turn. If key is in the keylist (that is, is eql to any item in the keylist) of a clause, the consequents of that clause are evaluated as an implicit progn; case returns what was returned by the last consequent (or nil if there are no consequents in that clause). If no clause is satisfied, case returns nil. The keys in the keylists are not evaluated; literal key values must appear in the keylists. It is an error for the same key to appear in more than one clause; a consequence is that the order of the clauses does not affect the behavior of the case construct. Instead of a keylist, one may write one of the symbols t and otherwise. A clause with such a symbol always succeeds and must be the last clause (this is an exception to the order-independence of clauses). See also ecase and ccase, each of which provides an implicit otherwise clause to signal an error if no clause is satisfied. If there is only one key for a clause, then that key may be written in place of a list of that key, provided that no ambiguity results. Such a ``singleton key'' may not be nil (which is confusable with (), a list of no keys), t, otherwise, or a cons. ------------------------------------------------------------------------------- Compatibility note: The Lisp Machine Lisp caseq construct uses eq for the comparison. In Lisp Machine Lisp caseq therefore works for fixnums but not bignums. The MacLisp caseq construct simply prohibits the use of bignums; indeed, it permits only fixnums and symbols as clause keys. In the interest of hiding the fixnum-bignum distinction, and for general language consistency, case uses eql in Common Lisp. The Interlisp selectq construct is similar to case. ------------------------------------------------------------------------------- [Macro] typecase keyform {(type {form}*)}* typecase is a conditional that chooses one of its clauses by examining the type of an object. Its form is as follows: (typecase keyform (type-1 consequent-1-1 consequent-1-2 ...) (type-2 consequent-2-1 ...) (type-3 consequent-3-1 ...) ...) Structurally typecase is much like cond or case, and it behaves like them in selecting one clause and then executing all consequents of that clause. It differs in the mechanism of clause selection. The first thing typecase does is to evaluate the form keyform to produce an object called the key object. Then typecase considers each of the clauses in turn. The type that appears in each clause is a type specifier; it is not evaluated but is a literal type specifier. The first clause for which the key is of that clause's specified type is selected, the consequents of this clause are evaluated as an implicit progn, and typecase returns what was returned by the last consequent (or nil if there are no consequents in that clause). If no clause is satisfied, typecase returns nil. As for case, the symbol t or otherwise may be written for type to indicate that the clause should always be selected. See also etypecase and ctypecase, each of which provides an implicit otherwise clause to signal an error if no clause is satisfied. It is permissible for more than one clause to specify a given type, particularly if one is a subtype of another; the earliest applicable clause is chosen. Thus for typecase, unlike case, the order of the clauses may affect the behavior of the construct. For example: (typecase an-object (string ...) ;This clause handles strings ((array t) ...) ;This clause handles general arrays ((array bit) ...) ;This clause handles bit arrays (array ...) ;This handles all other arrays ((or list number) ...) ;This handles lists and numbers (t ...)) ;This handles all other objects A Common Lisp compiler may choose to issue a warning if a clause cannot be selected because it is completely shadowed by earlier clauses. ------------------------------------------------------------------------------- 7.7. Blocks and Exits The block and return-from constructs provide a structured lexical non-local exit facility. At any point lexically within a block construct, a return-from with the same name may be used to perform an immediate transfer of control that exits from the block. In the most common cases this mechanism is more efficient than the dynamic non-local exit facility provided by catch and throw, described in section 7.11. [Special Form] block name {form}* The block construct executes each form from left to right, returning whatever is returned by the last form. If, however, a return or return-from form that specifies the same name is executed during the execution of some form, then the results specified by the return or return-from are immediately returned as the value of the block construct, and execution proceeds as if the block had terminated normally. In this, block differs from progn; the progn construct has nothing to do with return. The name is not evaluated; it must be a symbol. The scope of the name is lexical; only a return or return-from textually contained in some form can exit from the block. The extent of the name is dynamic. Therefore it is only possible to exit from a given run-time incarnation of a block once, either normally or by explicit return. The defun form implicitly puts a block around the body of the function defined; the block has the same name as the function. Therefore one may use return-from to return prematurely from a function defined by defun. The lexical scoping of the block name is fully general and has consequences that may be surprising to users and implementors of other Lisp systems. For example, the return-from in the following example actually does work in Common Lisp as one might expect: (block loser (catch 'stuff (mapcar #'(lambda (x) (if (numberp x) (hairyfun x) (return-from loser nil))) items))) Depending on the situation, a return in Common Lisp may not be simple. A return can break up catchers if necessary to get to the block in question. It is possible for a ``closure'' created by function for a lambda-expression to refer to a block name as long as the name is lexically apparent. [Special Form] return-from name [result] return-from is used to return from a block or from such constructs as do and prog that implicitly establish a block. The name is not evaluated and must be a symbol. A block construct with the same name must lexically enclose the occurrence of return-from; whatever the evaluation of result produces is immediately returned from the block. (If the result form is omitted, it defaults to nil. As a matter of style, this form ought to be used to indicate that the particular value returned doesn't matter.) The return-from form itself never returns and cannot have a value; it causes results to be returned from a block construct. If the evaluation of result produces multiple values, those multiple values are returned by the construct exited. [Macro] return [result] (return form) is identical in meaning to (return-from nil form); it returns from a block named nil. Blocks established implicitly by iteration constructs such as do are named nil, so that return will exit properly from such a construct. ------------------------------------------------------------------------------- 7.8. Iteration Common Lisp provides a number of iteration constructs. The loop construct provides a trivial iteration facility; it is little more than a progn with a branch from the bottom back to the top. The do and do* constructs provide a general iteration facility for controlling the variation of several variables on each cycle. For specialized iterations over the elements of a list or n consecutive integers, dolist and dotimes are provided. The tagbody construct is the most general, permitting arbitrary go statements within it. (The traditional prog construct is a synthesis of tagbody, block, and let.) Most of the iteration constructs permit statically defined non-local exits (see return-from and return). ------------------------------------------------------------------------------- * Indefinite Iteration * General Iteration * Simple Iteration Constructs * Mapping * The ``Program Feature'' ------------------------------------------------------------------------------- 7.8.1. Indefinite Iteration The loop construct is the simplest iteration facility. It controls no variables, and simply executes its body repeatedly. [Macro] loop {form}* Each form is evaluated in turn from left to right. When the last form has been evaluated, then the first form is evaluated again, and so on, in a never-ending cycle. The loop construct never returns a value. Its execution must be terminated explicitly, using return or throw, for example. loop, like most iteration constructs, establishes an implicit block named nil. Thus return may be used to exit from a loop with specified results. [old_change_begin] A loop construct has this meaning only if every form is non-atomic (a list). The case where some form is atomic is reserved for future extensions. ------------------------------------------------------------------------------- Implementation note: There have been several proposals for a powerful iteration mechanism to be called loop. One version is provided in Lisp Machine Lisp. Implementors are encouraged to experiment with extensions to the loop syntax, but users should be advised that in all likelihood some specific set of extensions to loop will be adopted in a future revision of Common Lisp. ------------------------------------------------------------------------------- [old_change_end] [change_begin] X3J13 voted in January 1989 (LOOP-FACILITY) to include just such an extension of loop. See chapter 26. [change_end] ------------------------------------------------------------------------------- 7.8.2. General Iteration In contrast to loop, do and do* provide a powerful and general mechanism for repetitively recalculating many variables. [Macro] do ({(var [init [step]])}*) (end-test {result}*) {declaration}* {tag | statement}* do* ({(var [init [step]])}*) (end-test {result}*) {declaration}* {tag | statement}* The do special form provides a generalized iteration facility, with an arbitrary number of ``index variables.'' These variables are bound within the iteration and stepped in parallel in specified ways. They may be used both to generate successive values of interest (such as successive integers) or to accumulate results. When an end condition is met, the iteration terminates with a specified value. In general, a do loop looks like this: (do ((var1 init1 step1) (var2 init2 step2) ... (varn initn stepn)) (end-test . result) {declaration}* . tagbody) A do* loop looks exactly the same except that the name do is replaced by do*. The first item in the form is a list of zero or more index-variable specifiers. Each index-variable specifier is a list of the name of a variable var, an initial value init, and a stepping form step. If init is omitted, it defaults to nil. If step is omitted, the var is not changed by the do construct between repetitions (though code within the do is free to alter the value of the variable by using setq). An index-variable specifier can also be just the name of a variable. In this case, the variable has an initial value of nil and is not changed between repetitions. As a matter of style, it is recommended that an unadorned variable name be written only when that variable will be stored into (such as by setq) before its first use. If it is important that the initial value be nil rather than some undefined value, then it is clearer to write out (varj nil) if the initial value is intended to mean ``false,'' or (varj '()) if the initial value is intended to be an empty list. [change_begin] X3J13 voted in January 1989 (VARIABLE-LIST-ASYMMETRY) to regularize the binding formats for do, do*, let, let*, prog, prog*, and compiler-let. In the case of do and do* the first edition was inconsistent; the formal syntax fails to reflect the fact that a simple variable name may appear, as described in the preceding paragraph. The definitions should read [Macro] do ({var | (var [init [step]])}*) (end-test {result}*) {declaration}* {tag | statement}* do* ({var | (var [init [step]])}*) (end-test {result}*) {declaration}* {tag | statement}* for consistency with the reading of the first edition and the X3J13 vote. [change_end] Before the first iteration, all the init forms are evaluated, and each var is bound to the value of its respective init. This is a binding, not an assignment; when the loop terminates, the old values of those variables will be restored. For do, all of the init forms are evaluated before any var is bound; hence all the init forms may refer to the old bindings of all the variables (that is, to the values visible before beginning execution of the do construct). For do*, the first init form is evaluated, then the first var is bound to that value, then the second init form is evaluated, then the second var is bound, and so on; in general, the initj form can refer to the new binding vark if k < j, and otherwise to the old binding of vark. The second element of the loop is a list of an end-testing predicate form end-test and zero or more result forms. This resembles a cond clause. At the beginning of each iteration, after processing the variables, the end-test is evaluated. If the result is nil, execution proceeds with the body of the do (or do*) form. If the result is not nil, the result forms are evaluated in order as an implicit progn, and then do returns. do returns the results of evaluating the last result form. If there are no result forms, the value of do is nil. Note that this is not quite analogous to the treatment of clauses in a cond form, because a cond clause with no result forms returns the (non-nil) result of the test. At the beginning of each iteration other than the first, the index variables are updated as follows. All the step forms are evaluated, from left to right, and the resulting values are assigned to the respective index variables. Any variable that has no associated step form is not assigned to. For do, all the step forms are evaluated before any variable is updated; the assignment of values to variables is done in parallel, as if by psetq. Because all of the step forms are evaluated before any of the variables are altered, a step form when evaluated always has access to the old values of all the index variables, even if other step forms precede it. For do*, the first step form is evaluated, then the value is assigned to the first var, then the second step form is evaluated, then the value is assigned to the second var, and so on; the assignment of values to variables is done sequentially, as if by setq. For either do or do*, after the variables have been updated, the end-test is evaluated as described above, and the iteration continues. If the end-test of a do form is nil, the test will never succeed. Therefore this provides an idiom for ``do forever'': the body of the do is executed repeatedly, stepping variables as usual. (The loop construct performs a ``do forever'' that steps no variables.) The infinite loop can be terminated by the use of return, return-from, go to an outer level, or throw. For example: (do ((j 0 (+ j 1))) (nil) ;Do forever (format t "~%Input ~D:" j) (let ((item (read))) (if (null item) (return) ;Process items until nil seen (format t "~&Output ~D: ~S" j (process item))))) The remainder of the do form constitutes an implicit tagbody. Tags may appear within the body of a do loop for use by go statements appearing in the body (but such go statements may not appear in the variable specifiers, the end-test, or the result forms). When the end of a do body is reached, the next iteration cycle (beginning with the evaluation of step forms) occurs. An implicit block named nil surrounds the entire do form. A return statement may be used at any point to exit the loop immediately. declare forms may appear at the beginning of a do body. They apply to code in the do body, to the bindings of the do variables, to the init forms, to the step forms, to the end-test, and to the result forms. ------------------------------------------------------------------------------- Compatibility note: ``Old-style'' MacLisp do loops, that is, those of the form (do var init step end-test . body), are not supported in Common Lisp. Such old-style loops are considered obsolete and in any case are easily converted to a new-style do with the insertion of three pairs of parentheses. In practice the compiler can catch nearly all instances of old-style do loops because they will not have a legal format anyway. ------------------------------------------------------------------------------- Here are some examples of the use of do: (do ((i 0 (+ i 1)) ;Sets every null element of a-vector to zero (n (length a-vector))) ((= i n)) (when (null (aref a-vector i)) (setf (aref a-vector i) 0))) The construction (do ((x e (cdr x)) (oldx x x)) ((null x)) body) exploits parallel assignment to index variables. On the first iteration, the value of oldx is whatever value x had before the do was entered. On succeeding iterations, oldx contains the value that x had on the previous iteration. Very often an iterative algorithm can be most clearly expressed entirely in the step forms of a do, and the body is empty. For example, (do ((x foo (cdr x)) (y bar (cdr y)) (z '() (cons (f (car x) (car y)) z))) ((or (null x) (null y)) (nreverse z))) does the same thing as (mapcar #'f foo bar). Note that the step computation for z exploits the fact that variables are stepped in parallel. Also, the body of the loop is empty. Finally, the use of nreverse to put an accumulated do loop result into the correct order is a standard idiom. Another example: (defun list-reverse (list) (do ((x list (cdr x)) (y '() (cons (car x) y))) ((endp x) y))) Note the use of endp rather than null or atom to test for the end of a list; this may result in more robust code. As an example of nested loops, suppose that env holds a list of conses. The car of each cons is a list of symbols, and the cdr of each cons is a list of equal length containing corresponding values. Such a data structure is similar to an association list but is divided into ``frames''; the overall structure resembles a rib cage. A lookup function on such a data structure might be (defun ribcage-lookup (sym ribcage) (do ((r ribcage (cdr r))) ((null r) nil) (do ((s (caar r) (cdr s)) (v (cdar r) (cdr v))) ((null s)) (when (eq (car s) sym) (return-from ribcage-lookup (car v)))))) (Notice the use of indentation in the above example to set off the bodies of the do loops.) A do loop may be explained in terms of the more primitive constructs block, return, let, loop, tagbody, and psetq as follows: (block nil (let ((var1 init1) (var2 init2) ... (varn initn)) {declaration}* (loop (when end-test (return (progn . result))) (tagbody . tagbody) (psetq var1 step1 var2 step2 ... varn stepn)))) do* is exactly like do except that the bindings and steppings of the variables are performed sequentially rather than in parallel. It is as if, in the above explanation, let were replaced by let* and psetq were replaced by setq. ------------------------------------------------------------------------------- 7.8.3. Simple Iteration Constructs The constructs dolist and dotimes execute a body of code once for each value taken by a single variable. They are expressible in terms of do, but capture very common patterns of use. Both dolist and dotimes perform a body of statements repeatedly. On each iteration a specified variable is bound to an element of interest that the body may examine. dolist examines successive elements of a list, and dotimes examines integers from 0 to n-1 for some specified positive integer n. The value of any of these constructs may be specified by an optional result form, which if omitted defaults to the value nil. The return statement may be used to return immediately from a dolist or dotimes form, discarding any following iterations that might have been performed; in effect, a block named nil surrounds the construct. The body of the loop is implicitly a tagbody construct; it may contain tags to serve as the targets of go statements. Declarations may appear before the body of the loop. [Macro] dolist (var listform [resultform]) {declaration}* {tag | statement}* dolist provides straightforward iteration over the elements of a list. First dolist evaluates the form listform, which should produce a list. It then executes the body once for each element in the list, in order, with the variable var bound to the element. Then resultform (a single form, not an implicit progn) is evaluated, and the result is the value of the dolist form. (When the resultform is evaluated, the control variable var is still bound and has the value nil.) If resultform is omitted, the result is nil. (dolist (x '(a b c d)) (prin1 x) (princ " ")) => nil after printing ``a b c d '' (note the trailing space) An explicit return statement may be used to terminate the loop and return a specified value. [change_begin] X3J13 voted in January 1989 (MAPPING-DESTRUCTIVE-INTERACTION) to restrict user side effects; see section 7.9. [change_end] [Macro] dotimes (var countform [resultform]) {declaration}* {tag | statement}* dotimes provides straightforward iteration over a sequence of integers. The expression (dotimes (var countform resultform) . progbody) evaluates the form countform, which should produce an integer. It then performs progbody once for each integer from zero (inclusive) to count (exclusive), in order, with the variable var bound to the integer; if the value of countform is zero or negative, then the progbody is performed zero times. Finally, resultform (a single form, not an implicit progn) is evaluated, and the result is the value of the dotimes form. (When the resultform is evaluated, the control variable var is still bound and has as its value the number of times the body was executed.) If resultform is omitted, the result is nil. An explicit return statement may be used to terminate the loop and return a specified value. Here is an example of the use of dotimes in processing strings: ;;; True if the specified subsequence of the string is a ;;; palindrome (reads the same forwards and backwards). (defun palindromep (string &optional (start 0) (end (length string))) (dotimes (k (floor (- end start) 2) t) (unless (char-equal (char string (+ start k)) (char string (- end k 1))) (return nil)))) (palindromep "Able was I ere I saw Elba") => t (palindromep "A man, a plan, a canal-Panama!") => nil (remove-if-not #'alpha-char-p ;Remove punctuation "A man, a plan, a canal-Panama!") => "AmanaplanacanalPanama" (palindromep (remove-if-not #'alpha-char-p "A man, a plan, a canal-Panama!")) => t (palindromep (remove-if-not #'alpha-char-p "Unremarkable was I ere I saw Elba Kramer, nu?")) => t (palindromep (remove-if-not #'alpha-char-p "A man, a plan, a cat, a ham, a yak, a yam, a hat, a canal-Panama!")) => t (palindromep (remove-if-not #'alpha-char-p "Ja-da, ja-da, ja-da ja-da jing jing jing")) => nil Altering the value of var in the body of the loop (by using setq, for example) will have unpredictable, possibly implementation-dependent results. A Common Lisp compiler may choose to issue a warning if such a variable appears in a setq. ------------------------------------------------------------------------------- Compatbility note: The dotimes construct is the closest thing in Common Lisp to the Interlisp rptq construct. ------------------------------------------------------------------------------- See also do-symbols, do-external-symbols, and do-all-symbols. ------------------------------------------------------------------------------- 7.8.4. Mapping Mapping is a type of iteration in which a function is successively applied to pieces of one or more sequences. The result of the iteration is a sequence containing the respective results of the function applications. There are several options for the way in which the pieces of the list are chosen and for what is done with the results returned by the applications of the function. The function map may be used to map over any kind of sequence. The following functions operate only on lists. [Function] mapcar function list &rest more-lists maplist function list &rest more-lists mapc function list &rest more-lists mapl function list &rest more-lists mapcan function list &rest more-lists mapcon function list &rest more-lists For each of these mapping functions, the first argument is a function and the rest must be lists. The function must take as many arguments as there are lists. mapcar operates on successive elements of the lists. First the function is applied to the car of each list, then to the cadr of each list, and so on. (Ideally all the lists are the same length; if not, the iteration terminates when the shortest list runs out, and excess elements in other lists are ignored.) The value returned by mapcar is a list of the results of the successive calls to the function. For example: (mapcar #'abs '(3 -4 2 -5 -6)) => (3 4 2 5 6) (mapcar #'cons '(a b c) '(1 2 3)) => ((a . 1) (b . 2) (c . 3)) maplist is like mapcar except that the function is applied to the lists and successive cdr's of those lists rather than to successive elements of the lists. For example: (maplist #'(lambda (x) (cons 'foo x)) '(a b c d)) => ((foo a b c d) (foo b c d) (foo c d) (foo d)) (maplist #'(lambda (x) (if (member (car x) (cdr x)) 0 1))) '(a b a c d b c)) => (0 0 1 0 1 1 1) ;An entry is 1 if the corresponding element of the input ; list was the last instance of that element in the input list. mapl and mapc are like maplist and mapcar, respectively, except that they do not accumulate the results of calling the function. ------------------------------------------------------------------------------- Compatibility note: In all Lisp systems since Lisp 1.5, mapl has been called map. In the chapter on sequences it is explained why this was a bad choice. Here the name map is used for the far more useful generic sequence mapper, in closer accordance with the computer science literature, especially the growing body of papers on functional programming. Note that this remark, predating the design of the Common Lisp Object System, uses the term ``generic'' in a generic sense and not necessarily in the technical sense used by CLOS (see chapter 2). ------------------------------------------------------------------------------- These functions are used when the function is being called merely for its side effects rather than for its returned values. The value returned by mapl or mapc is the second argument, that is, the first sequence argument. mapcan and mapcon are like mapcar and maplist, respectively, except that they combine the results of the function using nconc instead of list. That is, (mapcon f x1 ... xn) == (apply #'nconc (maplist f x1 ... xn)) and similarly for the relationship between mapcan and mapcar. Conceptually, these functions allow the mapped function to return a variable number of items to be put into the output list. This is particularly useful for effectively returning zero or one item: (mapcan #'(lambda (x) (and (numberp x) (list x))) '(a 1 b c 3 4 d 5)) => (1 3 4 5) In this case the function serves as a filter; this is a standard Lisp idiom using mapcan. (The function remove-if-not might have been useful in this particular context, however.) Remember that nconc is a destructive operation, and therefore so are mapcan and mapcon; the lists returned by the function are altered in order to concatenate them. Sometimes a do or a straightforward recursion is preferable to a mapping operation; however, the mapping functions should be used wherever they naturally apply because this increases the clarity of the code. The functional argument to a mapping function must be acceptable to apply; it cannot be a macro or the name of a special form. Of course, there is nothing wrong with using a function that has &optional and &rest parameters as the functional argument. [change_begin] X3J13 voted in June 1988 (FUNCTION-TYPE) to allow the function to be only of type symbol or function; a lambda-expression is no longer acceptable as a functional argument. One must use the function special form or the abbreviation #' before a lambda-expression that appears as an explicit argument form. X3J13 voted in January 1989 (MAPPING-DESTRUCTIVE-INTERACTION) to restrict user side effects; see section 7.9. [change_end] ------------------------------------------------------------------------------- 7.8.5. The ``Program Feature'' Lisp implementations since Lisp 1.5 have had what was originally called ``the program feature,'' as if it were impossible to write programs without it! The prog construct allows one to write in an Algol-like or Fortran-like statement-oriented style, using go statements that can refer to tags in the body of the prog. Modern Lisp programming style tends to use prog rather infrequently. The various iteration constructs, such as do, have bodies with the characteristics of a prog. (However, the ability to use go statements within iteration constructs is very seldom called upon in practice.) Three distinct operations are performed by prog: it binds local variables, it permits use of the return statement, and it permits use of the go statement. In Common Lisp, these three operations have been separated into three distinct constructs: let, block, and tagbody. These three constructs may be used independently as building blocks for other types of constructs. [Special Form] tagbody {tag | statement}* The part of a tagbody after the variable list is called the body. An item in the body may be a symbol or an integer, in which case it is called a tag, or an item in the body may be a list, in which case it is called a statement. Each element of the body is processed from left to right. A tag is ignored; a statement is evaluated, and its results are discarded. If the end of the body is reached, the tagbody returns nil. If (go tag) is evaluated, control jumps to the part of the body labelled with the tag. ------------------------------------------------------------------------------- Compatibility note: The ``computed go'' feature of MacLisp is not supported. The syntax of a computed go is idiosyncratic, and the feature is not supported by Lisp Machine Lisp, NIL (New Implementation of Lisp), or Interlisp. The computed go has been infrequently used in MacLisp anyway and is easily simulated with no loss of efficiency by using a case statement each of whose clauses performs a (non-computed) go. ------------------------------------------------------------------------------- The scope of the tags established by a tagbody is lexical, and the extent is dynamic. Once a tagbody construct has been exited, it is no longer legal to go to a tag in its body. It is permissible for a go to jump to a tagbody that is not the innermost tagbody construct containing that go; the tags established by a tagbody will only shadow other tags of like name. The lexical scoping of the go targets named by tags is fully general and has consequences that may be surprising to users and implementors of other Lisp systems. For example, the go in the following example actually does work in Common Lisp as one might expect: (tagbody (catch 'stuff (mapcar #'(lambda (x) (if (numberp x) (hairyfun x) (go lose))) items)) (return) lose (error "I lost big!")) Depending on the situation, a go in Common Lisp does not necessarily correspond to a simple machine ``jump'' instruction. A go can break up catchers if necessary to get to the target. It is possible for a ``closure'' created by function for a lambda-expression to refer to a go target as long as the tag is lexically apparent. See chapter 3 for an elaborate example of this. [change_begin] There are some holes in this specification (and that of go) that leave some room for interpretation. For example, there is no explicit prohibition against the same tag appearing more than once in the same tagbody body. Every implementation I know of will complain in the compiler, if not in the interpreter, if there is a go to such a duplicated tag; but some implementors take the position that duplicate tags are permitted provided there is no go to such a tag. (``If a tree falls in the forest, and there is no one there to hear it, then no one needs to yell `Timber!''') Also, some implementations allow objects other than symbols, integers, and lists in the body and typically ignore them. Consequently, some programmers use redundant tags such as - for formatting purposes, and strings as comments: (defun dining-philosopher (j) (tagbody - think (unless (hungry) (go think)) - "Can't eat without chopsticks." (snatch (chopstick j)) (snatch (chopstick (mod (+ j 1) 5))) - eat (when (hungry) (mapc #'gobble-down '(twice-cooked-pork kung-pao-chi-ding wu-dip-har orange-flavor-beef two-side-yellow-noodles twinkies)) (go eat)) - "Can't think with my neighbors' stomachs rumbling." (relinquish (chopstick j)) (relinquish (chopstick (mod (+ j 1) 5))) - (if (happy) (go think) (become insurance-salesman)))) In certain implementations of Common Lisp they get away with it. Others abhor what they view as an abuse of unintended ambiguity in the language specification. For maximum portability, I advise users to steer clear of these issues. Similarly, it is best to avoid using nil as a tag, even though it is a symbol, because a few implementations treat nil as a list to be executed. To be extra careful, avoid calling from within a tagbody a macro whose expansion might not be a non-nil list; wrap such a call in (progn ...), or rewrite the macro to return (progn ...) if possible. [change_end] [Macro] prog ({var | (var [init])}*) {declaration}* {tag | statement}* prog* ({var | (var [init])}*) {declaration}* {tag | statement}* The prog construct is a synthesis of let, block, and tagbody, allowing bound variables and the use of return and go within a single construct. A typical prog construct looks like this: (prog (var1 var2 (var3 init3) var4 (var5 init5)) {declaration}* statement1 tag1 statement2 statement3 statement4 tag2 statement5 ... ) The list after the keyword prog is a set of specifications for binding var1, var2, etc., which are temporary variables bound locally to the prog. This list is processed exactly as the list in a let statement: first all the init forms are evaluated from left to right (where nil is used for any omitted init form), and then the variables are all bound in parallel to the respective results. Any declaration appearing in the prog is used as if appearing at the top of the let body. The body of the prog is executed as if it were a tagbody construct; the go statement may be used to transfer control to a tag. A prog implicitly establishes a block named nil around the entire prog construct, so that return may be used at any time to exit from the prog construct. Here is a fine example of what can be done with prog: (defun king-of-confusion (w) "Take a cons of two lists and make a list of conses. Think of this function as being like a zipper." (prog (x y z) ;Initialize x, y, z to nil (setq y (car w) z (cdr w)) loop (cond ((null y) (return x)) ((null z) (go err))) rejoin (setq x (cons (cons (car y) (car z)) x)) (setq y (cdr y) z (cdr z)) (go loop) err (cerror "Will self-pair extraneous items" "Mismatch - gleep! S" y) (setq z y) (go rejoin))) which is accomplished somewhat more perspicuously by (defun prince-of-clarity (w) "Take a cons of two lists and make a list of conses. Think of this function as being like a zipper." (do ((y (car w) (cdr y)) (z (cdr w) (cdr z)) (x '() (cons (cons (car y) (car z)) x))) ((null y) x) (when (null z) (cerror "Will self-pair extraneous items" "Mismatch - gleep! S" y) (setq z y)))) The prog construct may be explained in terms of the simpler constructs block, let, and tagbody as follows: (prog variable-list {declaration}* . body) == (block nil (let variable-list {declaration}* (tagbody . body))) The prog* special form is almost the same as prog. The only difference is that the binding and initialization of the temporary variables is done sequentially, so that the init form for each one can use the values of previous ones. Therefore prog* is to prog as let* is to let. For example, (prog* ((y z) (x (car y))) (return x)) returns the car of the value of z. [change_begin] I haven't seen prog used very much in the last several years. Apparently splitting it into functional constituents (let, block, tagbody) has been a success. Common Lisp programmers now tend to use whichever specific construct is appropriate. [change_end] [Special Form] go tag The (go tag) special form is used to do a ``go to'' within a tagbody construct. The tag must be a symbol or an integer; the tag is not evaluated. go transfers control to the point in the body labelled by a tag eql to the one given. If there is no such tag in the body, the bodies of lexically containing tagbody constructs (if any) are examined as well. It is an error if there is no matching tag lexically visible to the point of the go. The go form does not ever return a value. As a matter of style, it is recommended that the user think twice before using a go. Most purposes of go can be accomplished with one of the iteration primitives, nested conditional forms, or return-from. If the use of go seems to be unavoidable, perhaps the control structure implemented by go should be packaged as a macro definition. ------------------------------------------------------------------------------- 7.9. Structure Traversal and Side Effects [change_begin] X3J13 voted in January 1989 (MAPPING-DESTRUCTIVE-INTERACTION) to restrict side effects during the course of a built-in operation that can execute user-supplied code while traversing a data structure. Consider the following example: (let ((x '(apples peaches pumpkin pie))) (dolist (z x) (when (eq z 'peaches) (setf (cddr x) '(mango kumquat))) (format t " S " (car z)))) Depending on the details of the implementation of dolist, this bit of code could easily print apples peaches mango kumquat (which is perhaps what was intended), but it might as easily print apples peaches pumpkin pie Here is a plausible implementation of dolist that produces the first result: (defmacro dolist ((var listform &optional (resultform ''nil)) &body body) (let ((tailvar (gensym "DOLIST"))) `(do ((,tailvar ,listform (cdr ,tailvar))) ((null ,tailvar) ,resultform) (let ((,var (car ,tailvar))) ,@body)) But here is a plausible implementation of dolist that produces the second result: (defmacro dolist ((var listform &optional (resultform ''nil)) &body body) (let ((tailvar (gensym "DOLIST"))) `(do ((,tailvar ,listform)) ((null ,tailvar) ,resultform) (let ((,var (pop ,tailvar))) ,@body)) The X3J13 recognizes and legitimizes varying implementation practices: in general it is an error for code executed during a ``structure-traversing'' operation to destructively modify the structure in a way that might affect the ongoing traversal operation. The committee identified in particular the following special cases. For list traversal operations, the cdr chain may not be destructively modified. For array traversal operations, the array may not be adjusted (see adjust-array) and its fill pointer, if any, may not be modified. For hash table operations (such as with-hash-table-iterator and maphash), new entries may not be added or deleted, except that the very entry being processed by user code may be changed or deleted. For package symbol operations (for example, with-package-iterator and do-symbols), new symbols may not be interned in, nor symbols uninterned from, the packages being traversed or any packages they use, except that the very symbol being processed by user code may be uninterned. X3J13 noted that this vote is intended to clarify restrictions on the use of structure traversal operations that are not themselves inherently destructive; for example, it applies to map and dolist. Destructive operators such as delete require even more complicated restrictions and are addressed by a separate proposal. The X3J13 vote did not specify a complete list of the operations to which these restrictions apply. Table 7-1 shows what I believe to be a complete list of operations that traverse structures and take user code as a body (in the case of macros) or as a functional argument (in the case of functions). In addition, note that user code should not modify list structure that might be undergoing interpretation by the evaluator, whether explicitly invoked via eval or implicitly invoked, for example as in the case of a hook function (a defstruct print function, the value of *evalhook* or *applyhook*, etc.) that happens to be a closure of interpreted code. Similarly, defstruct print functions and other hooks should not perform side effects on data structures being printed or being processed by format, or on a string given to make-string-input-stream. You get the idea; be sensible. Note that an operation such as mapcar or dolist traverses not only cdr pointers (in order to chase down the list) but also car pointers (in order to obtain the elements themselves). The restriction against modification appears to apply to all these pointers. Table 7-1: Structure Traversal Operations Subject to Side Effect Restrictions ----------------------------------------------------------------------------- adjoin maphash reduce assoc mapl remove assoc-if maplist remove-duplicates assoc-if-not member remove-if count member-if remove-if-not count-if member-if-not search count-if-not merge set-difference delete mismatch set-exclusive-or delete-duplicates nintersection some delete-if notany sort delete-if-not notevery stable-sort do-all-symbols nset-difference sublis do-external-symbols nset-exclusive-or subsetp do-symbols nsublis subst dolist nsubst subst-if eval nsubst-if subst-if-not every nsubst-if-not substitute find nsubstitute substitute-if find-if nsubstitute-if substitute-if-not find-if-not nsubstitute-if-not tree-equal intersection nunion union certain loop clauses position with-hash-table-iterator map position-if with-input-from-string mapc position-if-not with-output-to-string mapcan rassoc with-package-iterator mapcar rassoc-if mapcon rassoc-if-not ----------------------------------------------------------------------------- [change_end] ------------------------------------------------------------------------------- 7.10. Multiple Values Ordinarily the result of calling a Lisp function is a single Lisp object. Sometimes, however, it is convenient for a function to compute several objects and return them. Common Lisp provides a mechanism for handling multiple values directly. This mechanism is cleaner and more efficient than the usual tricks involving returning a list of results or stashing results in global variables. ------------------------------------------------------------------------------- * Constructs for Handling Multiple Values * Rules Governing the Passing of Multiple Values ------------------------------------------------------------------------------- 7.10.1. Constructs for Handling Multiple Values Normally multiple values are not used. Special forms are required both to produce multiple values and to receive them. If the caller of a function does not request multiple values, but the called function produces multiple values, then the first value is given to the caller and all others are discarded; if the called function produces zero values, then the caller gets nil as a value. The primary 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 will return three values. Other special forms also produce multiple values, but they can be described in terms of values. Some built-in Common Lisp functions, such as floor, return multiple values; those that do are so documented. The special forms and macros for receiving multiple values are as follows: multiple-value-list multiple-value-call multiple-value-prog1 multiple-value-bind multiple-value-setq These specify a form to evaluate and an indication of where to put the values returned by that form. [Function] values &rest args All of the arguments are returned, in order, as values. For example: (defun polar (x y) (values (sqrt (+ (* x x) (* y y))) (atan y x))) (multiple-value-bind (r theta) (polar 3.0 4.0) (vector r theta)) => #(5.0 0.9272952) The expression (values) returns zero values. This is the standard idiom for returning no values from a function. Sometimes it is desirable to indicate explicitly that a function will return exactly one value. For example, the function (defun foo (x y) (floor (+ x y) y)) will return two values because floor returns two values. It may be that the second value makes no sense, or that for efficiency reasons it is desired not to compute the second value. The values function is the standard idiom for indicating that only one value is to be returned, as shown in the following example. (defun foo (x y) (values (floor (+ x y) y))) This works because values returns exactly one value for each of its argument forms; as for any function call, if any argument form to values produces more than one value, all but the first are discarded. There is absolutely no way in Common Lisp for a caller to distinguish between returning a single value in the ordinary manner and returning exactly one ``multiple value.'' For example, the values returned by the expressions (+ 1 2) and (values (+ 1 2)) are identical in every respect: the single value 3. [Constant] multiple-values-limit The value of multiple-values-limit is a positive integer that is the upper exclusive bound on the number of values that may be returned from a function. This bound depends on the implementation but will not be smaller than 20. (Implementors are encouraged to make this limit as large as practicable without sacrificing performance.) See lambda-parameters-limit and call-arguments-limit. [Function] values-list list All of the elements of list are returned as multiple values. For example: (values-list (list a b c)) == (values a b c) In general, (values-list list) == (apply #'values list) but values-list may be clearer or more efficient. [Macro] multiple-value-list form multiple-value-list evaluates form and returns a list of the multiple values it returned. For example: (multiple-value-list (floor -3 4)) => (-1 1) multiple-value-list and values-list are therefore inverses of each other. [Special Form] multiple-value-call function {form}* multiple-value-call first evaluates function to obtain a function and then evaluates all of the forms. All the values of the forms are gathered together (not just one value from each) and are all given as arguments to the function. The result of multiple-value-call is whatever is returned by the function. For example: (+ (floor 5 3) (floor 19 4)) == (+ 1 4) => 5 (multiple-value-call #'+ (floor 5 3) (floor 19 4)) == (+ 1 2 4 3) => 10 (multiple-value-list form) == (multiple-value-call #'list form) [Special Form] multiple-value-prog1 form {form}* multiple-value-prog1 evaluates the first form and saves all the values produced by that form. It then evaluates the other forms from left to right, discarding their values. The values produced by the first form are returned by multiple-value-prog1. See prog1, which always returns a single value. [Macro] multiple-value-bind ({var}*) values-form {declaration}* {form}* The values-form is evaluated, and each of the variables var is bound to the respective value returned by that form. If there are more variables than values returned, extra values of nil are given to the remaining variables. If there are more values than variables, the excess values are simply discarded. The variables are bound to the values over the execution of the forms, which make up an implicit progn. For example: (multiple-value-bind (x) (floor 5 3) (list x)) => (1) (multiple-value-bind (x y) (floor 5 3) (list x y)) => (1 2) (multiple-value-bind (x y z) (floor 5 3) (list x y z)) => (1 2 nil) [Macro] multiple-value-setq variables form The variables must be a list of variables. The form is evaluated, and the variables are set (not bound) to the values returned by that form. If there are more variables than values returned, extra values of nil are assigned to the remaining variables. If there are more values than variables, the excess values are simply discarded. ------------------------------------------------------------------------------- Compatibility note: In Lisp Machine Lisp this is called multiple-value. The added clarity of the name multiple-value-setq in Common Lisp was deemed worth the incompatibility with Lisp Machine Lisp. ------------------------------------------------------------------------------- multiple-value-setq always returns a single value, which is the first value returned by form, or nil if form produces zero values. [change_begin] X3J13 voted in March 1989 (SYMBOL-MACROLET-SEMANTICS) to specify that if any var refers not to an ordinary variable but to a binding made by symbol-macrolet, then that var is handled as if setq were used to assign the appropriate value to it. [Macro] nth-value n form X3J13 voted in January 1989 (NTH-VALUE) to add a new macro named nth-value. The argument forms n and form are both evaluated. The value of n must be a non-negative integer, and the form may produce any number of values. The integer n is used as a zero-based index into the list of values. Value n of the form is returned as the single value of the nth-value form; nil is returned if the form produces no more than n values. As an example, mod could be defined as (defun mod (number divisor) (nth-value 1 (floor number divisor))) Value number 1 is the second value returned by floor, the first value being value number 0. One could define nth-value simply as (defmacro nth-value (n form) `(nth ,n (multiple-value-list ,form))) but the clever implementor will doubtless find an implementation technique for nth-value that avoids constructing an intermediate list of all the values of the form. [change_end] Common Lisp the Language, 2nd Edition BR> ------------------------------------------------------------------------------- 7.10.2. Rules Governing the Passing of Multiple Values It is often the case that the value of a special form or macro call is defined to be the value of one of its subforms. For example, the value of a cond is the value of the last form in the selected clause. In most such cases, if the subform produces multiple values, then the original form will also produce all of those values. This passing back of multiple values of course has no effect unless eventually one of the special forms for receiving multiple values is reached. To be explicit, multiple values can result from a special form under precisely these circumstances: Evaluation and application * eval returns multiple values if the form given it to evaluate produces multiple values. * apply, funcall, and multiple-value-call pass back multiple values from the function applied or called. Implicit progn contexts * The special form progn passes back multiple values resulting from evaluation of the last subform. Other situations referred to as ``implicit progn,'' where several forms are evaluated and the results of all but the last form are discarded, also pass back multiple values from the last form. These situations include the body of a lambda-expression, in particular those constructed by defun, defmacro, and deftype. Also included are bodies of the constructs eval-when, progv, let, let*, when, unless, block, multiple-value-bind, and catch, as well as clauses in such conditional constructs as case, typecase, ecase, etypecase, ccase, and ctypecase. [change_begin] X3J13 has voted to add many new constructs to the language that contain implicit progn contexts. I won't attempt to list them all here. Of particular interest, however, is locally, which may be regarded as simply a version of progn that permits declarations before its body. This provides a useful building block for constructing macros that permit declarations (but not documentation strings) before their bodies and pass back any multiple values produced by the last sub-form of a body. (If a body can contain a documentation string, most likely lambda is the correct building block to use.) [change_end] Conditional constructs * if passes back multiple values from whichever subform is selected (the then form or the else form). * and and or pass back multiple values from the last subform but not from subforms other than the last. * cond passes back multiple values from the last subform of the implicit progn of the selected clause. If, however, the clause selected is a singleton clause, then only a single value (the non-nil predicate value) is returned. This is true even if the singleton clause is the last clause of the cond. It is not permitted to treat a final clause (x) as being the same as (t x) for this reason; the latter passes back multiple values from the form x. Returning from a block * The block construct passes back multiple values from its last subform when it exits normally. If return-from (or return) is used to terminate the block prematurely, then return-from passes back multiple values from its subform as the values of the terminated block. Other constructs that create implicit blocks, such as do, dolist, dotimes, prog, and prog*, also pass back multiple values specified by return-from (or return). * do passes back multiple values from the last form of the exit clause, exactly as if the exit clause were a cond clause. Similarly, dolist and dotimes pass back multiple values from the resultform if that is executed. These situations are all examples of implicit uses of return-from. Throwing out of a catch * The catch construct returns multiple values if the result form in a throw exiting from such a catch produces multiple values. Miscellaneous situations * multiple-value-prog1 passes back multiple values from its first subform. However, prog1 always returns a single value. * unwind-protect returns multiple values if the form it protects returns multiple values. * the returns multiple values if the form it contains returns multiple values. Among special forms that never pass back multiple values are prog1, prog2, setq, and multiple-value-setq. The conventional way to force only one value to be returned from a form x is to write (values x). The most important rule about multiple values is: No matter how many values a form produces, if the form is an argument form in a function call, then exactly one value (the first one) is used. For example, if you write (cons (floor x)), then cons will always receive exactly one argument (which is of course an error), even though floor returns two values. To pass both values from floor to cons, one must write something like (multiple-value-call #'cons (floor x)). In an ordinary function call, each argument form produces exactly one argument; if such a form returns zero values, nil is used for the argument, and if more than one value, all but the first are discarded. Similarly, conditional constructs such as if that test the value of a form will use exactly one value, the first one, from that form and discard the rest; such constructs will use nil as the test value if zero values are returned. ------------------------------------------------------------------------------- 7.11. Dynamic Non-Local Exits Common Lisp provides a facility for exiting from a complex process in a non-local, dynamically scoped manner. There are two classes of special forms for this purpose, called catch forms and throw forms, or simply catches and throws. A catch form evaluates some subforms in such a way that, if a throw form is executed during such evaluation, the evaluation is aborted at that point and the catch form immediately returns a value specified by the throw. Unlike block and return (section 7.7), which allow for exiting a block form from any point lexically within the body of the block, the catch/throw mechanism works even if the throw form is not textually within the body of the catch form. The throw need only occur within the extent (time span) of the evaluation of the body of the catch. This is analogous to the distinction between dynamically bound (special) variables and lexically bound (local) variables. [Special Form] catch tag {form}* The catch special form serves as a target for transfer of control by throw. The form tag is evaluated first to produce an object that names the catch; it may be any Lisp object. A catcher is then established with the object as the tag. The forms are evaluated as an implicit progn, and the results of the last form are returned, except that if during the evaluation of the forms a throw should be executed such that the tag of the throw matches (is eq to) the tag of the catch and the catcher is the most recent outstanding catcher with that tag, then the evaluation of the forms is aborted and the results specified by the throw are immediately returned from the catch expression. The catcher established by the catch expression is disestablished just before the results are returned. The tag is used to match throws with catches. (catch 'foo form) will catch a (throw 'foo form) but not a (throw 'bar form). It is an error if throw is done when there is no suitable catch ready to catch it. Catch tags are compared using eq, not eql; therefore numbers and characters should not be used as catch tags. ------------------------------------------------------------------------------- Compatibility note: The name catch comes from MacLisp, but the syntax of catch in Common Lisp is different. The MacLisp syntax was (catch form tag), where the tag was not evaluated. ------------------------------------------------------------------------------- [Special Form] unwind-protect protected-form {cleanup-form}* Sometimes it is necessary to evaluate a form and make sure that certain side effects take place after the form is evaluated; a typical example is (progn (start-motor) (drill-hole) (stop-motor)) The non-local exit facility of Common Lisp creates a situation in which the above code won't work, however: if drill-hole should do a throw to a catch that is outside of the progn form (perhaps because the drill bit broke), then (stop-motor) will never be evaluated (and the motor will presumably be left running). This is particularly likely if drill-hole causes a Lisp error and the user tells the error-handler to give up and abort the computation. (A possibly more practical example might be (prog2 (open-a-file) (process-file) (close-the-file)) where it is desired always to close the file when the computation is terminated for whatever reason. This case is so important that Common Lisp provides the special form with-open-file for this purpose.) In order to allow the example hole-drilling program to work, it can be rewritten using unwind-protect as follows: ;; Stop the motor no matter what (even if it failed to start). (unwind-protect (progn (start-motor) (drill-hole)) (stop-motor)) If drill-hole does a throw that attempts to quit out of the unwind-protect, then (stop-motor) will be executed. This example assumes that it is correct to call stop-motor even if the motor has not yet been started. Remember that an error or interrupt may cause an exit even before any initialization forms have been executed. Any state restoration code should operate correctly no matter where in the protected code an exit occurred. For example, the following code is not correct: (unwind-protect (progn (incf *access-count*) (perform-access)) (decf *access-count*)) If an exit occurs before completion of the incf operation the decf operation will be executed anyway, resulting in an incorrect value for *access-count*. The correct way to code this is as follows: (let ((old-count *access-count*)) (unwind-protect (progn (incf *access-count*) (perform-access)) (setq *access-count* old-count))) As a general rule, unwind-protect guarantees to execute the cleanup-forms before exiting, whether it terminates normally or is aborted by a throw of some kind. (If, however, an exit occurs during execution of the cleanup-forms, no special action is taken. The cleanup-forms of an unwind-protect are not protected by that unwind-protect, though they may be protected if that unwind-protect occurs within the protected form of another unwind-protect.) unwind-protect returns whatever results from evaluation of the protected-form and discards all the results from the cleanup-forms. It should be emphasized that unwind-protect protects against all attempts to exit from the protected form, including not only ``dynamic exit'' facilities such as throw but also ``lexical exit'' facilities such as go and return-from. Consider this situation: (tagbody (let ((x 3)) (unwind-protect (if (numberp x) (go out)) (print x))) out ...) When the go is executed, the call to print is executed first, and then the transfer of control to the tag out is completed. [change_begin] X3J13 voted in March 1989 (EXIT-EXTENT) to clarify the interaction of unwind-protect with constructs that perform exits. Let an exit be a point out of which control can be transferred. For a throw the exit is the matching catch; for a return-from the exit is the corresponding block. For a go the exit is the statement within the tagbody (the one to which the target tag belongs) which is being executed at the time the go is performed. The extent of an exit is dynamic; it is not indefinite. The extent of an exit begins when the corresponding form (catch, block, or tagbody statement) is entered. When the extent of an exit has ended, it is no longer legal to return from it. Note that the extent of an exit is not the same thing as the scope or extent of the designator by which the exit is identified. For example, a block name has lexical scope but the extent of its exit is dynamic. The extent of a catch tag could differ from the extent of the exit associated with the catch (which is exactly what is at issue here). The difference matters when there are transfers of control from the cleanup clauses of an unwind-protect. When a transfer of control out of an exit is initiated by throw, return-from, or go, a variety of events occur before the transfer of control is complete: * The cleanup clauses of any intervening unwind-protect clauses are evaluated. * Intervening dynamic bindings of special variables and catch tags are undone. * Intervening exits are abandoned, that is, their extent ends and it is no longer legal to attempt to transfer control from them. * The extent of the exit being invoked ends. * Control is finally passed to the target. The first edition left the order of these events in some doubt. The implementation note for throw hinted that the first two processes are interwoven, but it was unclear whether it is permissible for an implementation to abandon all intervening exits before processing any intervening unwind-protect cleanup clauses. The clarification adopted by X3J13 is as follows. Intervening exits are abandoned as soon as the transfer of control is initiated; in the case of a throw, this occurs at the beginning of the ``second pass'' mentioned in the implementation note. It is an error to attempt a transfer of control to an exit whose dynamic extent has ended. Next the evaluation of unwind-protect cleanup clauses and the undoing of dynamic bindings and catch tags are performed together, in the order corresponding to the reverse of the order in which they were established. The effect of this is that the cleanup clauses of an unwind-protect will see the same dynamic bindings of variables and catch tags as were visible when the unwind-protect was entered. (However, some of those catch tags may not be useable because they correspond to abandoned exit points.) Finally control is transferred to the originally invoked exit and simultaneously that exit is abandoned. The effect of this specification is that once a program has attempted to transfer control to a particular exit, an unwind-protect cleanup form cannot step in and decide to transfer control to a more recent (nested) exit, blithely forgetting the original exit request. However, a cleanup form may restate the request to transfer to the same exit that started the cleanup process. Here is an example based on a nautical metaphor. The function gently moves an oar in the water with low force, but if an oar gets stuck, the caller will catch a crab. The function row takes a boat, an oar-stroking function, a stream, and a count; an oar is constructed for the boat and stream and the oar-stroking function is called :count times. The function life rows a particular boat. Merriment follows, except that if the oarsman is winded he must stop to catch his breath. (defun gently (oar) (stroke oar :force 0.5) (when (stuck oar) (throw 'crab nil))) (defun row (boat stroke-fn stream &key count) (let ((oar (make-oar boat stream))) (loop repeat count do (funcall stroke-fn oar)))) (defun life () (catch 'crab (catch 'breath (unwind-protect (row *your-boat* #'gently *query-io* :count 3)) (when (winded) (throw 'breath nil))) (loop repeat 4 (set-mode :merry)) (dream)))) Suppose that the oar gets stuck, causing gently to call throw with the tag crab. The program is then committed to exiting from the outer catch (the one with the tag crab). As control breaks out of the unwind-protect form, the winded test is executed. Suppose it is true; then another call to throw occurs, this time with the tag breath. The inner catch (the one with the tag breath) has been abandoned as a result of the first throw operation (still in progress). The clarification voted by X3J13 specifies that the program is in error for attempting to transfer control to an abandoned exit point. To put it in terms of the example: once you have begun to catch a crab, you cannot rely on being able to catch your breath. Implementations may support longer extents for exits than is required by this specification, but portable programs may not rely on such extended extents. (This specification is somewhat controversial. An alternative proposal was that the abandoning of exits should be lumped in with the evaluation of unwind-protect cleanup clauses and the undoing of dynamic bindings and catch tags, performing all in reverse order of establishment. X3J13 agreed that this approach is theoretically cleaner and more elegant but also more stringent and of little additional practical use. There was some concern that a more stringent specification might be a great added burden to some implementors and would achieve only a small gain for users.) [change_end] [Special Form] throw tag result The throw special form transfers control to a matching catch construct. The tag is evaluated first to produce an object called the throw tag; then the result form is evaluated, and its results are saved (if the result form produces multiple values, then all the values are saved). The most recent outstanding catch whose tag matches the throw tag is exited; the saved results are returned as the value(s) of the catch. A catch matches only if the catch tag is eq to the throw tag. In the process, dynamic variable bindings are undone back to the point of the catch, and any intervening unwind-protect cleanup code is executed. The result form is evaluated before the unwinding process commences, and whatever results it produces are returned from the catch. If there is no outstanding catcher whose tag matches the throw tag, no unwinding of the stack is performed, and an error is signalled. When the error is signalled, the outstanding catchers and the dynamic variable bindings are those in force at the point of the throw. ------------------------------------------------------------------------------- Implementation note: These requirements imply that throwing should typically make two passes over the control stack. In the first pass it simply searches for a matching catch. In this search every catch must be considered, but every unwind-protect should be ignored. On the second pass the stack is actually unwound, one frame at a time, undoing dynamic bindings and outstanding unwind-protect constructs in reverse order of creation until the matching catch is reached. ------------------------------------------------------------------------------- Compatibility note: The name throw comes from MacLisp, but the syntax of throw in Common Lisp is different. The MacLisp syntax was (throw form tag), where the tag was not evaluated. -------------------------------------------------------------------------------