Common Lisp the Language, 2nd Edition

next up previous contents index
Next: Dynamic Non-Local Exits Up: Multiple Values Previous: Constructs for Handling

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

Implicit progn contexts

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.)

Conditional constructs

Returning from a block

Throwing out of a catch

Miscellaneous situations

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.

next up previous contents index
Next: Dynamic Non-Local Exits Up: Multiple Values Previous: Constructs for Handling