Lisp provides a variety of structures for flow of control.
Function application is the basic method for construction of
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.
A function may always call itself in Lisp. The calling of
a function by itself is known as recursion; it is analogous
to mathematical induction.
The performing of an action repeatedly (usually with some
changes between repetitions) is called iteration, and is provided as
a basic control structure in most languages. The do statement of
PL/I, the for statement of ALGOL/60, and so on are examples of
iteration primitives. Lisp provides two general iteration facilities:
do and loop, as well as a variety of special-purpose iteration
facilities. (loop is sufficiently complex that it is explained
in its own chapter later in the manual; see
A conditional construct is one which allows a program
to make a decision, and do one thing or another based on some logical
condition. Lisp provides the simple one-way conditionals and and or,
the simple two-way conditional if, and more general multi-way
conditionals such as cond and selectq.
The choice of which form to use in any particular situation is a matter
of personal taste and style.
There are some non-local exit control structures, analogous
to the leave, exit, and escape constructs in many modern
languages.
Zetalisp provides for both static (lexical) non-local exits with
block and return-from and dynamic non-local exits with catch
and throw. Another kind of non-local exit is the goto, provided
by the tagbody and go constructs.
Zetalisp also provides a coroutine capability,
explained in the section on stack-groups (
body...
The body forms are evaluated in order from left to right and the value
of the last one is returned.
progn is the primitive control structure construct for "compound
statements".
Example: (foo (cdr a)
(progn (setq b (extract frob))
(car b))
(cadr b))
Lambda-expressions, cond forms, do forms, and
many other control structure forms use progn implicitly, that is,
they allow multiple forms in their bodies.
first-form body...
prog1 is similar to progn, but it returns the value of its first form rather
than its last.
It is most commonly used to evaluate an expression with side effects, and return
a value which must be computed before the side effects happen.
Example: (setq x (prog1 y (setq y x)))
interchanges the values of the variables x and y. prog1 never
returns multiple values.
first-form second-form body...
prog2 is similar to progn and prog1, but it returns its
second form. It is included largely for compatibility with old programs.
if is the simplest conditional form. The ``if-then'' form looks like:
(if predicate-form then-form)
predicate-form is evaluated, and if the result is non-nil, the
then-form is evaluated and its result is returned. Otherwise, nil
is returned.
In the ``if-then-else'' form, it looks like
(if predicate-form then-form else-form)
predicate-form is evaluated, and if the result is non-nil, the
then-form is evaluated and its result is returned. Otherwise, the
else-form is evaluated and its result is returned.
If there are more than three subforms, if assumes you want more than
one else-form; if the predicate returns nil, they are evaluated
sequentially and the result of the last one is returned.
condition body...
If condition evaluates to something non-nil, the body is
executed and its value(s) returned. Otherwise, the value of the when
is nil and the body is not executed.
condition body...
If condition evaluates to nil, the body is
executed and its value(s) returned. Otherwise, the value of the unless
is nil and the body is not executed.
The cond special form consists of the symbol cond followed by
several clauses. Each clause consists of a predicate form, called
the condition, followed by zero or more body forms.
(cond (condition body body...)
(condition)
(condition body ...)
... )
The idea is that each clause represents a case which
is selected if its condition is satisfied and the conditions
of all preceding clauses were not satisfied. When a clause
is selected, its body forms are evaluated.
cond processes its clauses in order from left to right. First,
the condition of the current clause 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 body forms which are
evaluated in order from left to right. After evaluating the
body forms, cond returns without inspecting any remaining
clauses. The value of the cond form is the value of the
last body form evaluated, or the value of the condition if there
were no body forms in the clause. If cond runs out of clauses,
that is, if every condition evaluates to nil, and thus no case is
selected, the value of the cond is nil.
Example: (cond ((zerop x) ;First clause:
(+ y 3)) ; (zerop x) is the condition.
; (+ y 3) is the body.
((null y) ;A clause with 2 body forms:
(setq y 4) ; this
(cons x z)) ; and this.
(z) ;A clause with no body forms: the condition is
; just z. If z is non-nil, it is returned.
(t ;A condition of t
105) ; is always satisfied.
) ;This is the end of the cond.
cond-every has the same syntax as cond, but executes every clause whose
condition is satisfied, not just the first. If a condition is the symbol
otherwise, it is satisfied if and only if no preceding condition is
satisfied. The value returned
is the value of the last body form in the last clause whose condition
is satisfied. Multiple values are not returned.
form...
and evaluates the forms one at a time,
from left to right. If any form evaluates to nil, and
immediately returns nil without evaluating the remaining
forms. If all the forms evaluate to non-nil values, and returns
the value of the last form.
and can be used in two different ways. You can use it as a logical
and function, because it returns a true value only if all of its
arguments are true:
(if (and socrates-is-a-person
all-people-are-mortal)
(setq socrates-is-mortal t))
Because the order of evaluation is well-defined, you can do
(if (and (boundp 'x)
(eq x 'foo))
(setq y 'bar))
knowing that the x in the eq form will not be evaluated if x
is found to be void.
You can also use and as a simple conditional form:
(and (setq temp (assq x y))
(rplacd temp z))
(and bright-day
glorious-day
(princ "It is a bright and glorious day."))
but when is usually preferable.
Note: (and) => t, which is the identity for the and operation.
form...
or evaluates the forms one by one from left to right.
If a form evaluates to nil, or proceeds to evaluate the
next form. If there are no more forms, or returns nil.
But if a form evaluates to a non-nil value, or immediately returns
that value without evaluating any remaining forms.
As with and, or can be used either as a logical or function,
or as a conditional:
(or it-is-fish it-is-fowl)
(or it-is-fish it-is-fowl
(print "It is neither fish nor fowl.")
but it is often possible and cleaner to use unless in the latter case.
Note: (or) => nil, the identity for this operation.
selectq is a conditional which chooses one of its clauses to execute
by comparing the value of a form against various constants using eql.
Its form is as follows:
(selectq key-form
(test body...)
(test body...)
(test body...)
...)
The first thing selectq does is to evaluate key-form; call the resulting
value key. Then selectq considers
each of the clauses in turn. If key matches the clause's
test, the body of the clause
is evaluated, and selectq returns the value of the last
body form. If there are no matches, selectq returns nil.
A test may be any of:
| 1) A symbol | If the key is eql to the symbol, it matches.
|
| 2) A number | If the key is eql to the number, it matches.
key must have the same type and the same value
as the number.
|
| 3) A list | If the key is eql to one of the elements of the list,
then it matches. The elements of the list should be symbols
or numbers.
|
| 4) t or otherwise | The symbols t and otherwise are special tests which match anything.
Either symbol may be used, it makes no difference;
t is mainly for compatibility with Maclisp's caseq construct.
To be useful, this should be the last clause in the selectq.
|
Example: (selectq x
(foo (do-this))
(bar (do-that))
((baz quux mum) (do-the-other-thing))
(otherwise (ferror nil "Never heard of ~S" x)))
is equivalent to
(cond ((eq x 'foo) (do-this))
((eq x 'bar) (do-that))
((memq x '(baz quux mum)) (do-the-other-thing))
(t (ferror nil "Never heard of ~S" x)))
Note that the tests are not evaluated; if you want them to
be evaluated use select rather than selectq.
case is the Common Lisp name for this construct.
caseq is the Maclisp name; it identical
to selectq, which is not totally compatible with Maclisp,
because selectq accepts otherwise as well as t
where caseq would not accept otherwise, and because Maclisp
does some error-checking that selectq does not. Maclisp programs
that use caseq work correctly so long as they don't use the
symbol otherwise as a key.
key-form clauses...
Like case except that an uncorrectable error is signaled if
every clause fails. t or otherwise clauses are not allowed.
place clauses...
Like ecase except that the error is correctable. The first argument
is called place because it must be setf'able.
If the user proceeds from the error, a new value is read and stored into
place; then the clauses are tested again using the new value.
Errors repeat until a value is specified which makes some clause succeed.
Also see defselect (
select is like selectq, except that the elements of the
tests are evaluated before they are used.
This creates a syntactic ambiguity: if (bar baz) is seen the
first element of a clause, is it a list of two forms, or is it one
form? select interprets it as a list of two forms. If you
want to have a clause whose test is a single form, and that form
is a list, you have to write it as a list of one form.
Example: (select (frob x)
(foo 1)
((bar baz) 2)
(((current-frob)) 4)
(otherwise 3))
is equivalent to
(let ((var (frob x)))
(cond ((eq var foo) 1)
((or (eq var bar) (eq var baz)) 2)
((eq var (current-frob)) 4)
(t 3)))
selector is like select, except that you get to specify the function
used for the comparison instead of eq. For example,
(selector (frob x) equal
(('(one . two)) (frob-one x))
(('(three . four)) (frob-three x))
(otherwise (frob-any x)))
is equivalent to
(let ((var (frob x)))
(cond ((equal var '(one . two)) (frob-one x))
((equal var '(three . four)) (frob-three x))
(t (frob-any x))))
select-match is like select but each clause can specify a pattern
to match the key against. The general form of use looks like
(select-match key-form
(pattern condition body...)
(pattern condition body...)
...
(otherwise body...))
The value of key-form is matched against the patterns one at a
time until a match succeeds and the accompanying condition evaluates
to something non-nil. At this point the body of that clause is
executed and its value(s) returned. If all the patterns/conditions
fail, the body of the otherwise clause (if any) is executed. A
pattern can test the shape of the key object, and set variables
which the condition form can refer to. All the variables set by the
patterns are bound locally to the select-match form.
The patterns are matched using list-match-p (Also see loop (
In a word, do* is to do as let* is to let.
do* works like do but binds and steps the variables sequentially
instead of in parallel. This means that the init form for one
variable can use the values of previous variables. The repeat forms
refer to the new values of previous variables instead of their old
values. Here is an example:
(do* ((x xlist (cdr x))
(y (car x) (car x)))
(print (list x y)))
On each iteration, y's value is the car of x. The same
construction with do might get an error on entry since x
might not be bound yet.
do-named is like do but defines a block with a name
explicitly specified by the programmer in addition to the block
named nil which every do defines. This makes it possible to
use return-from to return from this do-named even from within
an inner do. An ordinary return there would return from the
inner do instead. do-named is obsolete now that block,
which is more general and more coherent, exists. See
The static non-local exit allows code deep within a construct to jump
to the end of that construct instantly, not executing anything except
unwind-protect's on the way. The construct which defines a static level
that can be exited non-locally is called block and the construct which
exits it is called return-from. The block being exited must be lexically
visible from the return-from which says to exit it; this is what `static' means. By contrast, catch and throw provide for dynamic non-local
exits; refer to the following section.
Here is an example of using a static non-local exit:
(block top
(let ((v1 (do-1)))
(when (all-done v1) (return-from top v1))
(do-2))
(do-3)
...
(do-last))
If (all-done v1) returns non-nil, the entire block
immediately returns the value of v1. Otherwise, the rest of the
body of the block is executed sequentially, and ultimately the value or
values of (do-last) are returned.
Note that the return-from form is very unusual: it does not ever
return a value itself, in the conventional sense. It isn't useful to
write (setq a (return-from foo 3)), because when the
return-from form is evaluated, the containing block is
immediately exited, and the setq never happens.
The fact that block's and return-from's are matched up lexically
means you cannot do this:
(defun foo (a)
(block foo1
(bar a)))
(defun bar (x)
(return-from foo1 x))
The (return-from foo1 x) gets an error because there is no lexically
visible block named foo1. The suitable block in the caller, foo,
is not even noticed.
Static handling allows the compiler to produce good code for return-from.
It is also useful with functional arguments:
(defun first-symbol (list)
(block done
(mapc #'(lambda (elt)
(if (symbolp elt) (return-from done elt)))
list)))
The return-from done sees the block done lexically.
Even if mapc had a block in it named done it would
have no effect on the execution of first-symbol.
When a function is defined with defun with a name which is a symbol,
a block whose name is the function name is automatically placed around
the body of the function definition. For example,
(defun foo (a)
(if (evenp a)
(return-from foo (list a)))
(1+ a))
(foo 4) => (4)
(foo 5) => 6
A function written explicitly with lambda does not have a block
unless you write one yourself.
A named prog, or a do-named, implicitly defines a block with
the specified name. So you can exit those constructs with return-from.
In fact, the ability to name prog's was the original way to define
a place for return-from to exit, before block was invented.
Every prog, do or loop, whether named or not, implicitly
defines a block named nil. Thus, named prog's define two
block's, one named nil and one named whatever name you specify.
As a result, you can use return (an abbreviation for return-from nil)
to return from the innermost lexically containing prog, do or
loop (or from a block nil if you happen to write one).
This function is like assq, but it returns an additional value
which is the index in the table of the entry it found. For example,
(defun assqn (x table)
(do ((l table (cdr l))
(n 0 (1+ n)))
((null l) nil)
(if (eq (caar l) x)
(return (values (car l) n)))))
There is one exception to this: a prog, do or loop with
name t defines only the block named t, no block named nil.
The compiler used to make use of this feature in expanding certain built-in
constructs into others.
name body...
Executes body, returning the values of the last form in body,
but permitting non-local exit using return-from forms present
lexically within body. name is not evaluated, and is used
to match up return-from forms with their block'ss.
(block foo
(return-from foo 24) t) => 24
(block foo t) => t
name values
Performs a non-local exit from the innermost lexically containing
block whose name is name. name is not evaluated.
When the compiler is used, return-from's are matched up with
block's at compile time.
values is evaluated and its values
become the values of the exited block form.
A return-from form may appear as or inside an argument to a regular
function, but if the return-from is executed then the function will never
actually be called. For example,
(block done
(foo (if a (return-from done t) nil)))
foo is actually called only if a's value is nil.
This style of coding is not recommended when foo is actually a function.
return-from can also be used with zero value forms, or with several
value forms. Then one value is returned from each value form.
Originally return-from always returned only one value from each
value form, even when there was only one value form. Passing
back all the values when there is a single values form is a later
change, which is also the Common Lisp standard. In fact, the single
value form case is much more powerful and subsumes all the others.
For example,
(return-from foo 1 2)
is equivalent to (return-from foo (values 1 2))
and (return-from foo)
is equivalent to (return-from foo (values))
It is unfortunate that the case of one value form is treated differently
from all other cases, but the power of being able to propagate any
number of values from a single form is worth it.
To return precisely one value, use (return-from foo (values form)).
It is legal to write simply (return-from foo), which returns no
values from the block.
See Jumping to a label or tag is another kind of static non-local exit. Compared with
return-from, it allows more flexibility in choosing where to send
control to, but does not allow values to be sent along. This is because
the tag does not have any way of saying what to do with any
values.
To define a tag, the tagbody special form is used.
In the body of a tagbody, all lists are treated as forms to be
evaluated (called statements when they occur in this context).
If no goto happens, all the forms are evaluated in sequence
and then the tagbody form returns nil. Thus, the statements
are evaluated only for effect.
An element of the tagbody's body which is a symbol is not a statement
but a tag instead. It identifies a place in the sequence of statements
which you can go to. Going to a tag is accomplished by the form
(go tag), executed at any point lexically within the tagbody.
go transfers control immediately to the first statement following
tag in its tagbody, pausing only to deal with any
unwind-protects that are being exited as a result. If there are
no more statements after tag in its tagbody, then that tagbody
returns nil immediately.
All lexically containing tagbody's are eligible to contain the
specified tag, with the innermost tagbody taking priority. If no
suitable tag is found, an error is signaled. The compiler matches
go's with tags at compile time and issues a compiler warning if no
tag is found. Example:
(block nil
(tagbody
(setq x some frob)
loop
do something
(if some predicate (go endtag))
do something more
(if (minusp x) (go loop))
endtag
(return z)))
is a kind of iteration made out of go-to's. This
tagbody can never exit normally because the return in the last
statement takes control away from it. This use of a return and block
is how one encapsulates a tagbody to produce a non-nil value.
It works to go from an internal lambda function to a tag
in a lexically containing function, as in
(defun foo (a)
(tagbody
t1
(bar #'(lambda () (go t1)))))
If bar ever invokes its argument, control goes to t1 and
bar is invoked anew. Not very useful, but it illustrates the technique.
statements-and-tags...
Executes all the elements of statements-and-tags which are lists (the statements),
and then returns nil. But meanwhile, all elements of statements-and-tags
which are symbols (the tags) are available for use with go in any of the
statements. Atoms other than symbols are meaningless in a tagbody.
The reason that tagbody returns nil rather than the value of the last
statement is that the designers of Common Lisp decided that one could not
reliably return a value from the tagbody by writing it as the last statement
since some of the time the expression for the desired value would be a symbol
rather than a list, and then it would be taken as a tag rather than the last statement
and it would not work.
tag
The go special form is used to ``go-to'' a tag defined
in a lexically containing tagbody form (or other form which
implicitly expands into a tagbody, such as prog, do or loop).
tag must be a symbol. It is not evaluated.
prog is an archaic special form which provides temporary variables,
static non-local exits, and tags for go. These aspects of prog
were individually abstracted out to inspire let, block and
tagbody. Now prog is obsolete, as it is much cleaner to use
let, block, tagbody or all three of them, or do or
loop. But prog appears in so many programs that it cannot be
eliminated.
A typical prog looks like (prog (variables...) body...),
which is equivalent to
(block nil
(let (variables...)
(tagbody body...)))
If the first subform of a prog is a non-nil symbol (rather than
a list of variables), it is the name of the prog, and return-from
(see | :tag | The tag being thrown to.
|
| :value | The value being thrown (the second argument to throw).
|
| :count | |
| :action | The additional two arguments given to *unwind-stack, if that was used.
|
The error occurs in the environment of the throw; no unwinding has yet taken place.
The proceed type :new-tag expects one argument, a tag to throw to instead.
tag value active-frame-count action
This is a generalization of throw provided for program-manipulating
programs such as the debugger.
tag and value are the same as the corresponding arguments to
throw.
A tag of t invokes a special feature whereby the entire stack is
unwound, and then the function action is called (see below). During
this process unwind-protect's receive control, but catch-all's do
not. This feature is provided for the benefit of system programs which
want to unwind a stack completely.
active-frame-count, if non-nil, is the number of frames
to be unwound. The definition of a frame is implementation-dependent.
If this counts down to zero before a suitable catch
is found, the *unwind-stack terminates and
that frame returns value to whoever called it.
This is similar to Maclisp's freturn function.
If action is non-nil, whenever the *unwind-stack would be
ready to terminate (either due to active-frame-count or due to
tag being caught as in throw), instead action is called
with one argument, value. If tag is t, meaning throw out
the whole way, then the function action is not allowed to return.
Otherwise the function action may return and its value will be
returned instead of value from the catch--or from an arbitrary
function if active-frame-count is in use. In this case the
catch does not return multiple values as it normally does when
thrown to. Note that it is often useful for action to be a
stack-group.
Note that if both active-frame-count and action are nil,
*unwind-stack is identical to throw.
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
(turn-on-water-faucet)
(hairy-function 3 nil 'foo)
(turn-off-water-faucet))
The non-local exit facilities of Lisp create situations in which the
above code won't work, however: if hairy-function should use
throw, return or go to transfer control outside of the
progn form, then (turn-off-water-faucet) will never be evaluated
(and the faucet will presumably be left running). This is particularly
likely if hairy-function gets an error and the user tells the
debugger to give up and flush the computation.
In order to allow the above program to work, it can
be rewritten using unwind-protect as follows:
(unwind-protect
(progn (turn-on-water-faucet)
(hairy-function 3 nil 'foo))
(turn-off-water-faucet))
If hairy-function transfers control out of the
evaluation of the unwind-protect, the
(turn-off-water-faucet) form is evaluated during the
transfer of control, before control arrives at the
catch, block or go tag to which it is being transferred.
If the progn returns normally, then the (turn-off-water-faucet)
is evaluated, and the unwind-protect returns the result of the progn.
The general form of unwind-protect looks like
(unwind-protect
protected-form
cleanup-form1
cleanup-form2
...)
protected-form is evaluated, and when it returns or when it attempts
to transfer control out of the unwind-protect, the cleanup-forms
are evaluated. The value of the unwind-protect is the value of
protected-form. Multiple values returned by the protected-form
are propagated back through the unwind-protect.
The cleanup forms are run in the variable-binding environment that you
would expect: that is, variables bound outside the scope of the
unwind-protect special form can be accessed, but variables bound
inside the protected-form can't be. In other words, the stack is
unwound to the point just outside the protected-form, then the
cleanup handler is run, and then the stack is unwound some more.
body...
(catch-all form) is like (catch some-tag form)
except that it catches a
throw to any tag at all. Since the tag thrown to
is one of the returned values, the caller of catch-all may continue
throwing to that tag if he wants. The one thing that catch-all
does not catch is a *unwind-stack with a tag of t.
catch-all is a macro which expands into catch with a tag of nil.
catch-all returns all the values thrown to it, or returned by the
body, plus three additional values: the tag thrown to, the
active-frame-count, and the action. The tag value is nil if the
body returned normally. The last two values are the third and fourth
arguments to *unwind-stack (see
applies function to
| successive | successive |
| sublists | elements |
---------------+--------------+---------------+
its own | | |
second | map(l) | mapc |
argument | | |
---------------+--------------+---------------+
list of the | | |
returns function | maplist | mapcar |
results | | |
---------------+--------------+---------------+
nconc of the | | |
function | mapcon | mapcan |
results | | |
---------------+--------------+---------------+
Note that map and mapl are synonymous. map is the
traditional name of this function. mapl is the Common Lisp name.
In Common Lisp, the function map does something different and
incompatible; see cli:map,