3.3 Destructuring

In many places within iterate clauses where a variable is expected, a
list can be written instead. In these cases, the value to be assigned
is destructured according to the pattern described by the list.
As a simple example, the clause

(for (key . item) in alist)

will result in key being set to the car of each element
in alist, and item being set to the cdr. The
pattern list may be nested to arbitrary depth, and (as the example
shows) need not be terminated with nil; the only requirement is
that each leaf be a bindable symbol (or nil, in which case no
binding is generated for that piece of the structure).

Sometimes, you might like to do the equivalent of a
multiple-value-setq in a clause. This “multiple-value
destructuring” can be expressed by writing (values pat1pat2 ...) for a destructuring pattern, as in

(for (values (a . b) c d) = (three-valued-function ...))

Note that the pati can themselves be destructuring patterns
(though not multiple-value destructuring patterns). You can't do
multiple-value destructuring in a with clause; instead wrap the
whole iterate form in a multiple-value-bind.

Rationale: There are subtle interactions between variable declarations and
evaluation order that make the correct implementation of
multiple-value destructuring in a with somewhat tricky.

The destructuring feature of iterate is available as a separate
mechanism, using the dsetq macro:

— Macro: dsetq template expr

Performs destructuring of expr using template. May be
used outside of an iterate form. Yields the primary value of
expr.