Peter Siebel - Practical Common Lisp

(funcall #'+ (values 1 2) (values 3 4)) ==> 4

(multiple-value-call #'+ (values 1 2) (values 3 4)) ==> 10

However, it's fairly rare that you'll simply want to pass all the values returned by a function onto another function. More likely, you'll want to stash the multiple values in different variables and then do something with them. The MULTIPLE-VALUE-BIND macro, which you saw in Chapter 11, is the most frequently used operator for accepting multiple return values. Its skeleton looks like this:

(multiple-value-bind ( variable *) values-form

body-form *)

The values-form is evaluated, and the multiple values it returns are bound to the variables . Then the body-forms are evaluated with those bindings in effect. Thus:

(multiple-value-bind (x y) (values 1 2)

(+ x y)) ==> 3

Another macro, MULTIPLE-VALUE-LIST , is even simpler—it takes a single form, evaluates it, and collects the resulting multiple values into a list. In other words, it's the inverse of VALUES-LIST .

CL-USER> (multiple-value-list (values 1 2))

(1 2)

CL-USER> (values-list (multiple-value-list (values 1 2)))

1

2

However, if you find yourself using MULTIPLE-VALUE-LIST a lot, it may be a sign that some function should be returning a list to start with rather than multiple values.

Finally, if you want to assign multiple values returned by a form to existing variables, you can use VALUES as a SETF able place. For example:

CL-USER> (defparameter *x* nil)

*X*

CL-USER> (defparameter *y* nil)

*Y*

CL-USER> (setf (values *x* *y*) (floor (/ 57 34)))

1

23/34

CL-USER> *x*

1

CL-USER> *y*

23/34

A special operator you'll need to understand in order to write certain kinds of macros is EVAL-WHEN . For some reason, Lisp books often treat EVAL-WHEN as a wizards-only topic. But the only prerequisite to understanding EVAL-WHEN is an understanding of how the two functions LOAD and COMPILE-FILE interact. And understanding EVAL-WHEN will be important as you start writing certain kinds of more sophisticated macros, such as the ones you'll write in Chapters 24 and 31.

I've touched briefly on the relation between LOAD and COMPILE-FILE in previous chapters, but it's worth reviewing again here. The job of LOAD is to load a file and evaluate all the top-level forms it contains. The job of COMPILE-FILE is to compile a source file into a FASL file, which can then be loaded with LOAD such that (load "foo.lisp")and (load "foo.fasl")are essentially equivalent.

Because LOAD evaluates each form before reading the next, the side effects of evaluating forms earlier in the file can affect how forms later in the form are read and evaluated. For instance, evaluating an IN-PACKAGE form changes the value of *PACKAGE* , which will affect the way subsequent forms are read. [217] The reason loading a file with an IN-PACKAGE form in it has no effect on the value of *PACKAGE* after LOAD returns is because LOAD binds *PACKAGE* to its current value before doing anything else. In other words, something equivalent to the following LET is wrapped around the rest of the code in LOAD : (let ((*package* *package*)) ...) Any assignment to *PACKAGE* will be to the new binding, and the old binding will be restored when LOAD returns. It also binds the variable *READTABLE* , which I haven't discussed, in the same way. Similarly, a DEFMACRO form early in a file can define a macro that can then be used by code later in the file. [218] In some implementations, you may be able to get away with evaluating DEFUN s that use undefined macros in the function body as long as the macros are defined before the function is actually called. But that works, if at all, only when LOAD ing the definitions from source, not when compiling with COMPILE-FILE , so in general macro definitions must be evaluated before they're used.

COMPILE-FILE , on the other hand, normally doesn't evaluate the forms it's compiling; it's when the FASL is loaded that the forms—or their compiled equivalents—will be evaluated. However, COMPILE-FILE must evaluate some forms, such as IN-PACKAGE and DEFMACRO forms, in order to keep the behavior of (load "foo.lisp")and (load "foo.fasl")consistent.

So how do macros such as IN-PACKAGE and DEFMACRO work when processed by COMPILE-FILE ? In some pre-Common Lisp versions of Lisp, the file compiler simply knew it should evaluate certain macros in addition to compiling them. Common Lisp avoided the need for such kludges by borrowing the EVAL-WHEN special operator from Maclisp. This operator, as its name suggests, allows you to control when specific bits of code are evaluated. The skeleton of an EVAL-WHEN form looks like this:

(eval-when ( situation *)

body-form *)

There are three possible situations — :compile-toplevel, :load-toplevel, and :execute—and which ones you specify controls when the body-forms will be evaluated. An EVAL-WHEN with multiple situations is equivalent to several EVAL-WHEN forms, one per situation, each with the same body code. To explain the meaning of the three situations, I'll need to explain a bit about how COMPILE-FILE , which is also referred to as the file compiler , goes about compiling a file.

To explain how COMPILE-FILE compiles EVAL-WHEN forms, I need to introduce a distinction between compiling top-level forms and compiling non-top-level forms. A top-level form is, roughly speaking, one that will be compiled into code that will be run when the FASL is loaded. Thus, all forms that appear directly at the top level of a source file are compiled as top-level forms. Similarly, any forms appearing directly in a top-level PROGN are compiled as top-level forms since the PROGN itself doesn't do anything—it just groups together its subforms, which will be run when the FASL is loaded. [219] By contrast, the subforms in a top-level LET aren't compiled as top-level forms because they're not run directly when the FASL is loaded. They will run, but it's in the runtime context of the bindings established by the LET . Theoretically, a LET that binds no variables could be treated like a PROGN , but it's not—the forms appearing in a LET are never treated as top-level forms. Similarly, forms appearing directly in a MACROLET or SYMBOL-MACROLET are compiled as top-level forms because after the compiler has expanded the local macros or symbol macros, there will be no remnant of the MACROLET or SYMBOL-MACROLET in the compiled code. Finally, the expansion of a top-level macro form will be compiled as a top-level form.