Multiple Values
===============
Common Lisp functions can return zero or more results. Emacs Lisp
functions, by contrast, always return exactly one result. This package
makes no attempt to emulate Common Lisp multiple return values; Emacs
versions of Common Lisp functions that return more than one value
either return just the first value (as in `compiler-macroexpand') or
return a list of values (as in `get-setf-method'). This package _does_
define placeholders for the Common Lisp functions that work with
multiple values, but in Emacs Lisp these functions simply operate on
lists instead. The `values' form, for example, is a synonym for `list'
in Emacs.
- Special Form: multiple-value-bind (var...) values-form forms...
This form evaluates VALUES-FORM, which must return a list of
values. It then binds the VARs to these respective values, as if
by `let', and then executes the body FORMS. If there are more
VARs than values, the extra VARs are bound to `nil'. If there are
fewer VARs than values, the excess values are ignored.
- Special Form: multiple-value-setq (var...) form
This form evaluates FORM, which must return a list of values. It
then sets the VARs to these respective values, as if by `setq'.
Extra VARs or values are treated the same as in
`multiple-value-bind'.
The older Quiroz package attempted a more faithful (but still
imperfect) emulation of Common Lisp multiple values. The old method
"usually" simulated true multiple values quite well, but under certain
circumstances would leave spurious return values in memory where a
later, unrelated `multiple-value-bind' form would see them.
Since a perfect emulation is not feasible in Emacs Lisp, this
package opts to keep it as simple and predictable as possible.