.c	Wednesday  Nov 30,1983  19:27  LQ+3D.13H.34M.4S.  -*- Bolio -*-


.chapter "Programming Constructs"

The lan{nil} special and toplevel forms.

.section "Definition Forms"

.subsection "Defining Functions"

.defspec defun name lambda-list {declaration}* [documentation] {form}*
Defines 2name* as a function, equivalent to a lambda expression
formed using the lambda list, declarations, and forms.

For lan{maclisp}-compatibility, the following idiosyncratic syntaxes
are recognized specially:
.table 2 250 250 0 0 0
.item (1)
If 2lambda-list* is the atom 3macro*, then this is assumed to
be a lan{maclisp}-style macro definition, and is transformed
appropriately.
.item (2)
If 2lambda-list* is a non-null list, then this is considered to be
a lan{maclisp} 3lexpr* definition.  2name* will be defined
as a function of a variable number of arguments, and the symbol
2lambda-list* bound to that number.  The functions 3arg* and
3setarg* may then be used (compatibly with lan{maclisp}) to
access the arguments.
.item (3)
If 2lambda-list* is the atom 3fexpr*, then this is assumed to
be a lan{maclisp}-style fexpr definition, and an attempt is made to
turn it into a lan{nil} special form.  Note, of course, that due to
evaluator semantics this will usually not work (calls to 3eval*
will, for instance, utilize a new lexical contour).
.end_table

In principle, 2name* is a general function specifier
("function-spec") as is done in lan{lispm}.  However, these have not
been put into lan{nil} yet, so one additional idiosyncratic syntax
(also lan{maclisp} compatible) is recognized:  2name* may be a
list of the form 3(2name* 2propname*)*, in which case the
function is placed on the 2propname* property of 2name*.  If
2propname* is 3macro*, the lan{nil} compiler will give you a
hard time on the grounds that you probably thought you were defining a
macro in lan{maclisp}.
.end_defspec

.subsection "Defining Macros"

A lan{lisp} term_i{macro} differs from an ordinary function in
that the code
of the macro is run, not to obtain a value for the form, but rather to
obtain a 2new* form to be used in place of the original form.  In
lan{lisp}, this is not done through any strange and miraculous
string-processing and substitution, but by lan{lisp} code itself;
lan{lisp} program code is just lan{lisp} data, which can be
manipulated and constructed by ordinary lan{lisp} programs.  When a
term_i{macro call} is encountered by a lan{lisp} compiler, the
code for the macro is run then and there, during the compilation, to
construct the new form which must be compiled instead.  For that
reason, lan{lisp} macros, while general lan{lisp} functions,
should not depend on their dynamic environment (although if properly
arranged they may have global declarative or definitional information
around).

.defspec defmacro name pattern {declarations}* {documentation}* {form}*
'cindex destructuring
This is the preferred way for macros to be defined.  2name* is
defined as a macro.  When a call to 2name* is encountered by the
interpreter or compiler, the list of arguments to 2name*
(specifically, the 3cdr* of the calling form) is matched against
2pattern*;  the 2form*s are then evaluated in an environment
where the variables specified by 2pattern* are bound to the
components of the arguments which they match, and the resulting value
is used in place of the original form.

2pattern* is generally a pattern of symbols and conses, but it may
also have in it, intermixed, 3&optional*, 3&rest*, and
3&body*.  The following defines 3foo* as a macro to be
synonymous with 3car*:
.lisp
(defmacro foo (x)
  (list 'car x))
.end_lisp
In lan{nil}, the 3&2mumble** keywords need not be
"top-level" within the pattern:
.lisp
(defmacro with-output-to-string ((var &optional string)
	                         &body form)
  ...)
.end_lisp
Especially useful for constructing code in the bodies of macros is the
backquote reader macro, (backquote-section-page).

Eventually, 3defmacro* will be extended to support these
additional lambda-list keywords:
.table 3 250 250 0 0 0
.item &key 2keyspec1*2keyspec2*...
Pretty much like the ordinary use of 3&key* in lambda lists
((lambda-list-section-page)).
.item &whole 2variable*
Binds 2variable* to the macro call form, so that one may get a
handle on the entire form.
.end_table
.end_defspec

.defspec macro name bvl {declarations}* [documentation] {form}*
Primitive macro definition.  You probably shouldn't use this, at least
not for routine macro definitions.

The macro function receives one argument, which is the macro call
form;  thus, 2bvl* should be a lambda list for a function of
exactly one argument.  It is possible that this will change in the
future, so one should stick to 3defmacro* if at all possible.
.end_defspec

.subsection "Defining Variables"

.defspec defvar var [init [documentation]]
Globally declares 2var* to be 3special*.  If there is an
2init*  form specified, then when this form is loaded (evaluated),
if 2var* is not already bound (dynamically), it will be set to the
value of 2init*.
.end_defspec

.defspec defparameter var init [documentation]
This is like spec{defvar}, only 2var* is 2always* set to the
value of 2init*.
.end_defspec

.defspec defconstant var init [documentation]
Similar, and additionally states that the value of 2var* is not
intended to change.  A correctable error is signaled if, when this
form is loaded (evaluated), 2var* has a value not 3equal* to
the value of 2init*.  (Continuing from this error will set
2var* to its new value;  continuing from similar errors not
signalled by 3defconstant* may not do the update.)

The lan{nil} compiler will, at its discretion, utilize the (defined
or implied by 2init* being a constant) value of 2var* inline.
So if you will be changing the value of a 3defconstant* variable
out from under other compiled code, you should perhaps be using
3defparameter*.
.end_defspec

.defspec special {variable}*
Globally declares each 2variable* to be 3special*.  Note that
this normally occurs within a 3declare* special form.  Within a
3declare* form, when processed by the compiler, the declaration is
made local to the compilation of that file.  As a toplevel special
form however, in addition to being declared local to that compilation,
the form will be output into the compiled file so will make the
declaration when that file is loaded (just as 3defvar* and
3defparameter* do).
.end_defspec

.subsection "Controlling Evaluation Time"

Macros often need to return multiple forms to be processed as if they
all appeared independently at toplevel.  For instance, 3defvar*
and its variants could all be trivially implemented as macros (if they
aren't already).  The canonical lan{maclisp} way to do this is to
return a 3progn* special form, the first element of which is the
form 3(quote compile)*.  This is unnecessary in lan{nil},
although it is absolutely harmless;  just plain 3progn* may be
used.  Note that 3(progn 'compile 2forms...*)* is treated the
same as 3(eval-when (load) 2forms...*)*.

A simplified 3defparameter*, which did not handle
documentation, could have been written like this:
.lisp
(defmacro defparameter (variable value-form)
  `(progn (special ,variable)
	  (setq ,variable ,value-form)))
.end_lisp

This behaviour and the special casing only applies to toplevel forms.

.defspec eval-when kwd-list {form}*
This is as if each of the 2form*s appeared at toplevel, but were
only there to be processed at the times specified by 2kwd-list*.
The allowable keywords for 2kwd-list* are
.table 3 250 250
.item eval
When the 3eval-when* form is evaluated by the interpreter.
.item load
When the 2form*s of the 3eval-when* are loaded compiled (they
will be treated as if they were seen at toplevel by the compiler;
e.g., 3defun*s will be compiled, etc.).
.item compile
The 2form*s will be evaluated immediately when processed by the
compiler.  Note that 3eval-when* keywords are 2not* symbols
in the keyword package (that is, you don't type them in with a colon
in front).
.end_table
Note that for historical reasons, these "keywords" are only keywords
in the general sense--they are not symbols in the keyword package
(typed in with a colon prefix).
.end_defspec

.section "Binding"

.defspec let ({variable value}*) {declaration}* {form}*
3let* evaluates all of the 2values*, and then binds all of the
2variables* to the corresponding values.   The 2forms* are
then evaluated in that environment, and the result(s) of the last
2form* is the result(s) of the 3let*.  For instance,
.lisp
(let ((a 2form1*) (b 2form2*))
  2compute*)
 ==>
((lambda (a b) 2compute*)
 2form1* 2form2*)
.end_lisp

Various other constructs in lan{nil} accept a list of lists of
variables and values syntactically the same as that used by 3let*.
This is what is meant by the term term_i{letlist}.

In lan{nil}, 3let* will accept, in place of a variable, a
pattern used for term_i{destructuring}.  The variables within the
pattern are bound to the corresponding parts of the value.  This is
the interface to destructuring used by 3defmacro*;  see it,
(defmacro-fun), for more information on this pattern-directed
destructuring.

Because lan{common lisp} 3let* is not defined to support
destructuring, it is recommended that, if destructuring is used, it be
hidden in a macro.  This will make it both easier to read (all the
extra parentheses needed to use 3let* with destructuring make it
hard to read), and also make it easier to change should 3let*
eventually be changed to 2not* support destructuring (at which
time there will be a primitive provided which does).  For instance,
the lan{nil} compiler defines the macro 3debind-args* to
destructure argument lists of forms being compiled:
.lisp
(defmacro debind-args (arglist-pattern form &body body)
  `(let ((,arglist-pattern (cdr ,form))) ,@body))
.end_lisp
Eventually lan{nil} will provide some special forms and functions
for getting at the destructuring and argument-list matching
functionality provided by 3defmacro*.
.end_defspec

.defspec let* ({(variable value)}*) {declaration}* {form}*
Syntactically, 3let** is similar to 3let*.  However, rather
than binding the variables in 2parallel*, it binds them
2sequentially*.  That is, when each 2value* form is evaluated,
the corresponding 2variable* is bound to that value, and the
following 2value*s are evaluated in that environment.  For
instance,
.lisp
(let* ((a 2form1*) (b 2form2*))
  2compute*)
 ==>
((lambda (a)
   ((lambda (b)
      2compute*)
    2form2*))
 2form1*)
.end_lisp
.end_defspec

.subsection "Dynamically Binding Variable Variables"

The routines in this section may be used to bind variables which are
not known at code-writing (or compile) time.  They all bind the
special (dynamic) value of the variable.

There are four variations on how the variables may be bound.  Which is
used is a matter of which is best suited for the particular task at
hand.  Basically, the variations all involve how the value is
computed.

.defspec progv varlist vallist forms...
3progv* binds each of the variables in 2varlist* to the
corresponding values in 2vallist*.  If there are too many values
in 2vallist*, the extras are ignored.  If there are too few, then
the extra variables will be bound "unbound".  Each of the 2forms*
is then evaluated in an environment in which the variables are so
bound;  they are all bound dynamically.

3progv* is defined by lan{common-lisp}.  None of the following
special forms are, however.
.end_defspec

The following three special forms all take an a-list as a
specification of what variables to bind to what values.  The 3car*
of each entry in the a-list is the variable to be bound.  If the
3cdr* is 3nil* (the entry has a length of 31*), then the
variable will be bound "unbound".  Otherwise, the 3cadr*
(2not* the 3cdr*) of the entry tells what value the variable
should be bound to:  the exact interpretation varies with the special
form in use.  In all cases, the bindings are performed sequentially:
each variable is bound to its value before the value for the next
variable to be bound is determined.

.defspec progw a-list forms...
The second element of each entry in 2a-list* is a form to
3eval* to get the value to bind the variable to.
.end_defspec

.defspec progwq a-list forms...
This is sort of a trivial special-case of 3progw*.  The second
element of each entry in 2a-list* is the actual value to bind the
variable to;  no evaluation is performed.
.end_defspec

.defspec progwf a-list forms...
2This function may not yet be in the existing 1lan{nil}**.

This is a variant of 3progw* more in keeping with a lan{lisp}
implementation in which things get compiled.  The second element of
each entry in 2a-list* is a function to be called on no arguments
to determine the value to bind the variable to.  This is much more
practical than 3progw* because it can eliminate a lot of
interpreter overhead.
.end_defspec

The typical use of these special forms is to provide a dynamic
environment, the specification of which may be augmented modularly,
and hence might not be totally known to the writer of the code which
performs the binding.  3progw* and its variants are usually more
convenient for this purpose than 3progv*, because the
specification of the environment
is in a single datastructure, which might be kept around as the value
of a variable.  Note however that 3progw*, 3progwq*, and
3progwf* are 2not* defined by lan{common-lisp}.  3progw*
is defined by lan{lisp machine lisp}, but 3progwq* and
3progwf* are not.

.section "Conditionals"

.defspec if predicate consequent [elseform]
3if* evaluates 2predicate*.  If the result is not false (i.e.,
not 3nil*), then the result of the 3if* is the result of
evaluating 2consequent*.  Otherwise, if 2elseform* is
specified, the result of the 3if* is the result of evaluating
2elseform*, otherwise 3nil*.
.end_defspec

.defun not x
3not* is used logically to invert the sense of a predicate.  That
is, it is by convention used to test for the object representing
term_i{boolean false}.  Because of the empty-list/boolean-false
duality of the symbol 3nil*, it is functionally equivalent to
3null* ((null-fun)), which logically checks for the
term_i{empty list} which is represented by the type named
3null*.  Thus, one often sees constructs of the form
.lisp
(if (not (null l)) 2consequent* 2elseform*)
.end_lisp
because 3null* is used to check for empty-listness (for instance,
being at the end of an iteration down a list), and the 3not* is
used to invert the sense, so that the 2consequent* will be run if
there is in fact something left to the list 3l*.
.end_defun

.defspec cond {(predicate {consequent}*)}*
General historical 3cond*.  Each 2predicate* to the 3cond*
is evaluated, in order.  If the result of an evaluation is false, then
the 3cond* evaluates the corresponding 2consequents* in that
"clause", returning as its value the value(s) of the last one, unless
there were no 2consequents*, in which case the value of the
3cond* is the value of the 2predicate* evaluation.
.lisp
(cond (2p1* 2c1*)
      (2p2* 2c2*)
      (t 2e*))
.end_lisp
is equivalent to
.lisp
(if 2p1* 2c1*
    (if 2p2* 2c2* 2e*))
.end_lisp
however 3cond* allows multiple 2consequents*, and also may
more clearly show the selection by clearly listing the sequentially
processed tests.

If all of the 2predicate*s are false, then 3cond* returns
3nil*.
.end_defspec


.defspec when predicate-form {consequent-form}*
.lisp
(when 2predicate-form*
  2consequent-1*
  2consequent-2*
  ...
  2consequent-n*)
 ==>
(cond (2predicate-form*
         2consequent-1*
         2consequent-2*
         ...
         2consequent-n*))
.end_lisp
If 2predicate-form* evaluates non-null, then the
2consequent-forms* are evaluated in order and the value(s) of the
last one returned as the value of the 3when* form;  otherwise, the
3when* form returns 3nil*.
.end_defspec

.defspec unless predicate-form {consequent-form}*
.lisp
(unless 2predicate-form*
  2consequent-1*
  2consequent-2*
  ...
  2consequent-n*)
 ==>
(when (not 2predicate-form*)
  2consequent-1*
  2consequent-2*
  ...
  2consequent-n*)
 ==>
(cond ((not 2predicate*)
         2consequent-1*
         2consequent-2*
         ...
         2consequent-n*))
.end_lisp
.end_defspec

.defspec and {form}*
Evaluates each 2form*, and if any returns (false), 3and*
immediately returns (false) without evaluating any subsequent forms;
otherwise, the result of the 3and* is the value(s) of the last
2form*.  3(and)* => 3t*.
.end_defspec

.defspec or {form}*
Evaluates each 2form*, and if one returns a non-null result, that
value is returned by 3or* without evaluating any of the following
forms.  3(or)* => 3nil*.

3or* is supposed to return exactly one value, no matter how many
were produced by the evaluation of a 2form*, 2except* for the
last 2form* which is evaluated tail-recursively (with respect to
multiple value propagation).  It doesn't currently behave quite this
way.
.end_defspec

.defspec case keyform {(({key*}) {consequent}*)}*
A dispatch form utilizing the 3eql* predicate.  In general,
.lisp
(case 2keyform*
  ((2key-1-1* 2key-1-2* ...) 2form-1-1* 2form-1-2* ...)
  ((2key-2-1* 2key-2-2* ...) 2form-2-1* 2form-2-2* ...)
  ...)
.end_lisp
is essentially the same as
.lisp
(let ((tem 2keyform*))
  (cond ((or (eql tem '2key-1-1*) (eql tem '2key-1-2*) ...)
	   2form-1-1* 2form-1-2* ...)
	((or (eql tem '2key-2-1*) (eql tem '2key-2-2*) ...)
	   2form-2-1* 2form-2-2*)
	...))
.end_lisp
Since the keys are constant, however, it is possible for the compiler
to determine the cheapest way to perform the comparisons;  see
3eql*, (eql-fun).  In fact, if there are a moderate number of
fixnum keys in a small range, the lan{nil} compiler may use the
lan{vax} 7CASE* instruction to perform the dispatching.

In place of a list of keys, one may use a single atomic key.  Also,
the symbols 3t* and 3otherwise* are special-cased and cause
that "clause" to 2always* be selected;  no subsequent clauses will
be examined.  For example,
.lisp
(case (* 2 2)
  (1 'one)
  (2 'two)
  (3 'three)
  (t 'many))
 => many
.end_lisp

Note that this function is what mac_i{selectq} thought it would once
be, and may be used in place of lan{maclisp} spec_i{caseq}.
.end_defspec

.defspec typecase object {(type-specifier {form}*)}*
3typecase* examines each of its "clauses" in turn.  If
2object* is of the type specified by that 2type-specifier*
(see 3typep*, (typep-fun)), then the 2form*s in that clause
are evaluated, and the value of the last form is returned by
3typecase*.  Note that a 2type-specifier* of 3t* will
always cause the corresponding clause to be selected.

3typecase* can often produce moderately better code than repeated
calls to 3typep*, by factoring out operations needed for more than
one of the checks.  The lan{nil} 3typecase* does not yet do any
clever pointer-type dispatch, however.

Remember that each "key" is a type specifier, not just a type name,
and definitely not a list of type names.  To test for more than one
type in one key, use 3(or 2type1* 2type2* ...)*.
.end_defspec


.section "Function Invocation"

Often the function one desires to call is not constant;  for instance,
it may have been passed in as an argument (like the second argument to
3sort*, (sort-fun), or as a 3:test* keyworded argument to
3member*, (member-fun), or something obtained from a property
list, hash table, or association list).  lan{nil} does not support the old
"functional variable" interpretation of a functional form;  that is,
in a form like 3(foo x y)*, the function called is 2never*
obtained from the value of a variable 3foo*.  Instead, because the
"name space" for functions and variables is completely distinct, so
special forms are provided for invoking functions which are obtained
by "normal" evaluation.

.defun funcall function &rest args
3funcall* calls 2function* on all of the arguments in
2args*.  It is 2not* a special form;  the 2function* is
evaluated in the regular fashion, and that value should be a function.
For instance, 3sort* ((sort-fun)), which could be defined
something like
.lisp
(defun sort (sequence pred &key key) ...)
.end_lisp
could invoke its 2pred* argument with something like
.lisp
(funcall pred (elt sequence i) (elt sequence j))
.end_lisp
.end_defun

.defun apply function &rest args
3apply* is somewhat like 3funcall*, but the last of the
2args* is a list of the remaining arguments to invoke
2function* on.  That is, if 3apply* is called like
.lisp
(apply 2fn* 2a1* 2a2* ... 2an* 2list*)
.end_lisp
then 2fn* will be invoked like
.lisp
(funcall 2fn* 2a1* 2a2* ... 2an* 2e1* 2e2* ... 2em*)
.end_lisp
where 2e1* 2e2* ... 2em* are the elements of 2list*.

Often, the last argument to 3apply* is a list which is the value
of an 3&rest* variable.  In lan{nil}, this list may instead be a
simple vector (it 2must* be simple), as might be obtained by use
of 3&restv* instead of 3&rest*.

Note that the lan{maclisp} 3apply* function only accepts two
arguments, if you don't count the optional third argument which is an
evaluation environment.
.end_defun

.defun lexpr-funcall function &rest args
Old name for what is now done by 3apply*.  3lexpr-funcall*,
unlike 3apply*, is compatible with lan{maclisp}.
.end_defun

.section "Iteration Constructs"

.subsection "Mapping Functions"

.defun mapc function list &rest more-lists
.defun1 mapl function list &rest more-lists
.defun1 mapcar function list &rest more-lists
.defun1 maplist function list &rest more-lists
.defun1 mapcan function list &rest more-lists
.defun1 mapcon function list &rest more-lists
These are the standard complement of lan{lisp} mapping functions,
which iterate down all of the lists in parallel.
They accumulate results in three different ways, and apply
2function* in two different ways.  In all cases, if more than one
list is supplied, they are stepped in parallel and the iteration
terminates when the end of the shortest one is reach.

fun{mapc} and fun{mapl} each returns its first argument as its
value;  that is, they are typically for effect.  3mapc* applies
2function* to the 3car*s of successive sublists, that is, to
the elements of the lists, whereas 3mapl* applies 2function*
to the sublists themselves.  Thus,
.lisp
(mapc #'print '(a b c))
.end_lisp
prints
.lisp
a
b
c
.end_lisp
whereas
.lisp
(mapl #'print '(a b c))
.end_lisp
prints
.lisp
(a b c)
(b c)
(c)
.end_lisp
Both return 2list*, their first argument.
Note that the function is not called on the null list, even though
that might be thought of as a sublist.  Random example where the
return value is useful:
.lisp
(mapl #'(lambda (subl)
	   (rplacd subl (delete (car subl) (cdr subl))))
      2some-list*)
.end_lisp
eliminates (destructively) all duplicate elements from
2some-list*.

3mapl* is what used to be called fun_i{map} in lan{maclisp}.
3map* is now a generic sequence function ((map-fun)).

3mapcar* and 3maplist* each returns a list of the results of
applying 2function* to their successive arguments;  for
3mapcar*, as with 3mapc*, the arguments are the elements of
the lists, and for 3maplist*, as with 3mapl*, they are the
sublists themselves.  For example:
.lisp
(mapcar #'(lambda (x y) (plus x y))
	'(1 2 3) '(9 10 11))
 => (10 12 14)
.end_lisp
That could have been written as
.lisp
(mapcar #'plus ...)
.end_lisp

3mapcan* and 3mapcon* "splice together" the results of
applying 2function* to its successive arguments, using
(essentially) 3nconc*.  One common use of 3mapcan* is to
3mapcar* conditionally:
.lisp
(mapcan #'(lambda (x) (and (2pred* x) (list (2f* x))))
	2some-list*)
.end_lisp
is kind of like doing 3(mapcar #'2f* 2some-list*)* having
first deleted those elements which do not satisfy 2pred*.

Because of the constrained nature of the iteration, 3mapcar*,
3maplist*, 3mapcan*, and 3mapcon* probably generate better
code than you (or even something like the 3loop* macro) could
write for generating the return value.
.end_defspec

.subsection "Other Iteration Forms"

.defspec dotimes (var count [endform]) {declaration}* {tag | form}*
2var* is stepped from 0 (inclusive) to the value of 2count*
(exclusive);  for each value, each of the 2form*s is evaluated.
When the iteration terminates, the value of 2endform* is returned.
The "body" of 3dotimes* is a "tagbody" body (see 3tagbody*).
Atomic tags may be inserted among the forms and jumped to with
3go* ((go-fun)), to produce strange and wondrous unstructured
code.

Additionally, 3dotimes* establishes an implicit block named
3nil* around the 3dotimes* form (see 3block*);  one may
thus use 3return* (or 3return-from* with a block name of
3nil*) to exit and return a value(s) from the 3dotimes*,
without running 2exitform*.  3block* and 3tagbody* are
described in (block-tagbody-section-page).
.end_defspec

.defspec dolist (var list [endform]) {declaration}* {tag | form}*
Similar to 3dotimes*, but steps 2var* through the elements of
2list*, the way 3mapc* ((mapc-fun)) does.
.end_defspec

.defspec dovector (var vector) {declaration}* {tag | form}*
Similar to 3dolist*, but for vectors.
.end_defspec

.defspec do ({var [init [step]]}*) (endtest {endform}*) {declaration}* {tag | form}*
3do* is a more general iteration construct.  The specified
variables are bound in parallel (as by 3let*, (let-fun)) to the
values of the corresponding initial values.  These are their values
for the first iteration.  For all subsequent iterations, the variables
which have step forms specified are all set in parallel to the values
of those step forms.  (That is, the values of all of the step forms
are computed before 2any* of the assignments have been made.)

On each iteration, 2endtest* is evaluated.  If the result is not
3nil*, then the iteration terminates and evaluates the
2endform*s as an implicit 3progn* (returning 3nil* if
there are no 2endform*s).  Otherwise, the "body" of the 3do*
is interpreted as by 3tagbody* ((tagbody-fun)).  Thus,
.lisp
(do (...) (nil) 2tagbody*...)
.end_lisp
is idiomatic for looping forever, and
.lisp
(do (...) (t ...) 2tagbody*...)
.end_lisp
will never get around to interpreting the forms in 2tagbody*.

3do* establishes an implicit block named 3nil* around the
entire 3do* form;  see (block-tagbody-section-page).

As a special hack for lan{maclisp} code, if 2endtest* is not
specified (and hence no 2endform*s could be specified), then the
body of the do is interpreted exactly once, and 3nil* returned;
that is, the 3do* should have been written as 3prog*
((prog-fun)), except that lan{maclisp} 3prog* does not accept
initial values for the variables.

The lan{maclisp} "old style do" is also supported in lan{nil}.
This takes the form
.lisp
(do 2var* 2init* 2step* 2endtest* 2tagbody*...)
.end_lisp
and is equivalent to
.lisp
(do ((2var* 2init* 2step*)) (2endtest*)
   2tagbody*...)
.end_lisp
New code should not use this format.
.end_defspec

.defspec do* ({(var [init [step]])}*) (endtest {endform}*) {declaration}* {tag | form}*
This is like 3do*, except that the variables are bound to their
initial values sequentially (like 3let** ((let*-fun)) rather
than 3let*), and the steps are also performed sequentially (like
3setq* rather than 3psetq*).
.end_defspec

See also the 3loop* macro, (loop-fun).  
3loop* is a "programmable iteration facility", which allows one to
combine various sorts of iterations (such as those provided by
3dotimes* and 3dovector*) with various sorts of result
accumulation (such as those provided by 3mapcar*, 3mapcan*,
3every*, 3some*, and other things such as summing and
counting).  Because it is complicated, it is documented fully in
chapter (loop-chapter), (loop-fun).  An earlier version of that
chapter appeared as ref{LOOP}, which is expected to be revised
similarly.

.subsection "Block and Tagbody"
.setq block-tagbody-section-page section-page

3block* and 3tagbody* together implement the flow-of-control
functionality provided by standard 3prog*.  3prog* could have
been implemented as a macro in terms of these and 3let*,
and in fact is described in that fashion by lan{common lisp}.

.defspec block name {declaration}* {form}*
3block* evaluates the 2forms*.  If a lexically apparent
3return-from* is evaluated with a tag of 2name* (or 2name*
is 3nil* and a 3return* is evaluated), then the value(s) of
the form given to 3return* or 3return-from* are returned as
the value of the 3block* form.  Otherwise, the 3block* form
returns the value(s) of the evaluation of the last 2form*.

Note that the argument to 3return* or 3return-from* is
evaluated in the environment in which it occurs, 2not* the
environment where the 3block* was established.
.end_defspec

.defspec return form
Evaluates 2form*, and returns the value(s) it returns from the
nearest lexically apparent 3block* with a name of 3nil*.  Many
special forms implicitly establish blocks named 3nil*, such as
3prog*, 3do*, 3dolist*, 3dotimes*, 3dovector*, and
(usually) 3loop*.

Note that this differs subtly from lan{zetalisp}.  In
lan{zetalisp}, 3return* returns from the innermost 3prog*
(i.e., block) which is 2not* named 3t*.  In lan{nil} (and
lan{common lisp}), a 3return* to a block name of 3nil* only
matches a block name of 3nil*, and the block name 3t* is not
distinguished in any way.
.end_defspec

.defspec return-from name form
Evaluates 2form*, and returns the value(s) it returns from the
nearest lexically apparent 3block* with a name of 2name*.
2name* is not evaluated.
.end_defspec

.defspec tagbody {tag | form}*
The body of a tagbody is examined sequentially.  If a form is atomic,
then it is a tag and is ignored, otherwise it is evaluated.  If during the
evaluation a lexically apparent call to 3go* is evaluated with an
argument of one of the tags, then control is returned to that point
within the 3tagbody* form, which resumes its interpretation.  If
the interpretation reaches the end of the 3tagbody*, the result is
3nil*.
.end_defspec

.defspec go tag
2tag* is not evaluated.  Control is returned to the nearest
lexically apparent 3tagbody* form with a tag name of 2tag*,
which resumes interpretation of the tagbody at the form following that
tag.
.end_defspec

It is important to note that the name matching of
3block*/3return-from* and 3tagbody*/3go* is
2lexical*.  For instance,
.lisp
(defun f (x)
  (block foobar
     (g #'(lambda (x) (return-from foobar x)) x)))
(defun g (fn x)
  (list (block foobar
	  (funcall fn x))))
(f 'foo)  =>  foo
.end_lisp
not 3(foo)*.  The lan{nil} compiler cannot handle this example,
however.  Also, the named block only has 2dynamic extent*;
if an attempt is made to return to a lexically apparent 3block*
construct which has been exited, the interpreter will complain.

.defspec prog varlist {declaration}* {tag | form}*
Standard 3prog*.  2varlist* may be a list of variables, or a
list of lists of variables and their initial values.  They will be
bound in parallel.  3prog* can be built from the above primitives:
.lisp
(let 2varlist*
   2the declarations*
   (block nil
     (tagbody 2the tags and forms*)))
.end_lisp

For compatibility with lan{zetalisp}, if the first "argument" to
3prog* is a non-null atom, then that is used as the name of the
block, with the varlist following.
.end_defspec

.defspec prog* varlist {declaration}* {tag | form}*
Like 3prog*, but binds the variables sequentially rather than in
parallel, i.e., like using 3let** ((let*-fun)) rather than
3let*.
.end_defspec

.section "Non-Local Flow of Control"

.defspec catch tag {form}*
lan{Common lisp} 3catch*.  2tag* is evaluated and the result
saved.  Then, if during the evaluation of the 2form*s, if a
3throw* to that tag (as tested for by 3eq*) occurs, the
3catch* form so named will return the values given to the
3throw*.  The tag so named has 2dynamic extent*.

The tag to 3catch* is allowed to be any lan{lisp} object.  This
means that one can generate a guaranteed unique tag by (for instance)
3(ncons nil)*, or by using a datastructure which is somehow
associated with the control point of the 3catch*.  This is, in
fact, how the lan{nil} interpreter implements the 3block* and
3tagbody* constructs;  it uses the datastructures in which it
stores its control-flow information as tags to 3catch*.

Note that this is incompatible with the standard lan{maclisp}
3catch* function documented in the 1974 manual (ref{Moonual}).
However, lan{pdp10 maclisp} has been bitching and moaning about use
of 3catch* for some year or more now, advising the use of
3*catch* instead (which is equivalent to lan{nil}'s
3catch*).
.end_defspec

.defspec throw tag form
2tag* and 2form* are evaluated.  Control is returned from the
nearest 3catch* established with a tag 3eq* to the value of
2tag*, and that 3catch* then returns all the values produced
by 2form*.

special form because of multiple value passback.  of course that
doesn't work reliably yet...

Note that this is incompatible with the old-fashioned lan{maclisp}
3throw* function.  However, in lan{pdp10 maclisp} 3throw*
has been out of vogue for some time, supplanted by 3*throw*, which
has syntax and semantics identical to this 3throw*, and which is
supported in lan{nil}.
.end_defspec

.defspec unwind-protect protected-form {cleanup-form}*
2protected-form* is evaluated, and the result returned.  Upon
exit, the 2cleanup-form*s are evaluated.  No matter how the exit
is achieved (3throw*, error, whatever).

In principle, 3unwind-protect* returns whatever extra values
2protected-form* did.  In the current implementation, this cannot
be guaranteed because no state is saved around the evaluation of the
2cleanup-form*s.
.end_defspec

.defspec *catch tag {form}*
Old name for what is now 3catch*.  Will be supported and identical
to what 3catch* is now indefinitely, for the sake of
lan{maclisp} programs, which use this name with identical syntax.
(Note however that lan{maclisp} 3catch* allows 2tag* to be a
list of tags, which means it can't be just any object.)
.end_defspec

.defspec *throw tag form
Old name for what is now 3throw*.  Will be supported and identical
to what 3throw* is now indefinitely, for the sake of
lan{maclisp} programs, which use this name with identical syntax.

This seems to be an ordinary function.  But then multiple-value
passback is unreliable.
.end_defspec

.section "Multiple Values"
2documentation*

lan{Nil} contains a kludgey implementation of term_i{multiple
values}, similar to what exists in lan{lispm}.  The implementation
is based on the hack put into lan{maclisp} some time ago, and
suffers from approximately the same deficiencies:  namely, that
multiple values passed back to forms receiving a single value
"normally" might hang around and be picked up later if no other
multiple-value passing is done.

.defun values &rest values
Returns as many values as it is given arguments;  the first value
being the first argument, etc.  It is permissible for there to be no
values.
.end_defun

.defun values-list list
Returns as multiple values all the elements of 2list*.
.end_defun

.defun values-vector vector
Because lan{nil} makes such great use of vectors, this is provided
also;  it returns all the elements of 2vector* as multiple values.

For example, in lan{nil} 3values* is defined by
.lisp
(defun values (&restv vec)
   (values-vector vec))
.end_lisp
Of course, the lan{nil} compiler will open-compile a call to
3values*.
.end_defun


.defspec multiple-value variables values-form
The variables in 2variables*, which must be a list of variables,
are set to the corresponding multiple values returned by the
evaluation of 2values-form*.  Extra values are ignored;  if too
few values are returned, the extra variables are set to (false).

3multiple-value* always returns exactly one value, the value of
the first value returned by 2values-form* (or (false) if none
were returned).

In lan{nil}, as in lan{lisp machine lisp}, one may use (false)
in place of a variable to cause the corresponding value to be ignored.
This is specifically disallowed by lan{common lisp}, and should not
be used.  The preferred way to handle this uses
3multiple-value-bind*, below.

The name of this will be changed to fun_i{multiple-value-setq} by
lan{common lisp}...
.end_defspec


.defspec multiple-value-bind variables values-form {declaration}* {form}*
Somewhat like 3multiple-value*, except the variables in
2variables* are 2bound* to the values produced by
2values-form*, and each of the 2form*s evaluated in that
environment.

Note that, although in lan{nil}
3nil* may be used as a placeholder in 2variables* for a value
which will not be used, it may not in lan{common lisp}.  The
preferred way to ignore a value is to use a name for it, and declare
that name to be ignored;  for instance,
.lisp
(multiple-value-bind (quo rem) (%bignum-quotient-norm x y)
  (declare (ignore quo))
  (hack-about-with rem))
.end_lisp
This additionally provides the benefit of having the value
"documented" by virtue of being associated with a named variable.
.end_defspec


.defspec multiple-value-list form
2form* is evaluated, and all of the values it produces are
returned as a list.  For example:
.lisp
(multiple-value-list (values 1 2))  =>  (1 2)
(multiple-value-list (values))      =>  nil
.end_lisp
.end_defspec


.section "Generalized Variables"
.setq setf-section-page section-page
.cindex generalized variables

.defmac setf {place value}*
fun_i{setf} is sort of a generalized 3setq*.  Essentially, a
3setf* form expands into the code needed to store each 2value*
into each 2place*.  For example, just as
.lisp
(setq x 3)
.end_lisp
stores 33* into 3x*,
.lisp
(setf (car l) 5)
.end_lisp
stores 35* into the 3car* of the value of 3l*.  As with
3setq*, multiple place/value pairs are handled sequentially.

3setf* always returns the last value stored.

3setf* works on variables, all defined 3car*/3cdr*
functions, array and sequence accessing functions (3aref*,
3elt*, 3vref*, 3char*, 3bit*), 3get*, various
attribute accessors (3symbol-plist*, 3symbol-value*,
3symbol-function*, etc.), and all accessors defined by either
3defstruct* or 3defflavor*.  In fact, it is the canonical (and
the only formally defined) way to modify slots of structures defined
with 3defstruct*.  It also operates on a number of low-level
lan{nil} primitives, including 3nibble*, 3get-a-byte*, and
3get-a-byte-2c*.

3setf* also operates on certain other forms whose "inversions" are
not strictly side-effecting, by performing the 3setf* on an
argument of the function (which must be valid as a 2place* to
3setf*).  These include 3ldb* and 3load-byte*.  For
instance, the side-effect performed by
.lisp
(setf (ldb 2bytespec* 2place*) 2val*)
.end_lisp
is the same as
.lisp
(setf 2place* (dpb 2val* 2bytespec* 2place*))
.end_lisp
although the return value should be different.
.end_defmac


The 3setf* methodology is even more helpful when the logical
operation being performed on the 2place* is "read-modify-write".
This means that the 2place* needs to only be specified once in the
form.

As of this writing, the lan{common lisp} compatible 3setf* has
not yet been installed in lan{nil}, so not all of the following
macros may be in the lan{nil} when it is released.  This pertains
to 3incf*, 3decf*, 3shiftf*, and 3rotatef*, and
anything having to do with how one might define such a macro.
3setf*, 3push*, and 3pop* have been in lan{nil} for some
time already.

.defmac push item place
Approximately
.lisp
(setf 2place* (cons 2item* 2place*))
.end_lisp
except that order of evaluation is preserved, and the forms of
2place* are evaluated only once.
.end_defmac

.defmac pop place
Approximately
.lisp
(prog1 (car 2place*) (setf 2place* (cdr 2place*))
.end_lisp
but the forms in 2place* are evaluated only once.  In otherwords,
3pop* treats the contents of 2place* as a list stack;  it
returns the top of the stack and pops it.
.end_defmac

.defmac incf place &optional (delta 1)
Sets 2place* to 2place* plus 2delta*.
.end_defmac

.defmac decf place &optional (delta 1)
Sets 2place* to 2place* minus 2delta*.
.end_defmac

.defun shiftf place1 place2 ... placen form
.lisp
(shiftf 2place* 2form*)
.end_lisp
is just like using 3setf*.
.lisp
(shiftf 2place1* 2place2* 2form*)
.end_lisp
stores the value of 2place2* into 2place1*, and then the value
of 2form* into 2place2*.
.end_defun

.defun rotatef place1 place2 ... placen
3rotatef* "rotates" the value of the 3places*.  The value of
2place2* is stored into 2place1*, 2place3* into
2place2* etc., and 2place1* into 2placen*, all in
parallel.
.end_defun

.section "Property Lists"

A term_i{property list} is a list of even length, of alternating
indicators and values.  This is, of course, the same datastructure
which is the property list of a symbol.  Note that this is not the
same as a term_i{disembodied property list}, which has 2odd*
length.  lan{Common Lisp} has
generalized the property list mechanism so that is attached neither
specifically to symbols or disembodied property lists, but rather
interfaces to 2generalized variables*.

Note:  as of this writing, the lan{common lisp} compatible
3setf*, on which both 3remf* and 3setf* on 3getf* are
dependent, has not been installed in lan{nil}.  As a result, there
is a chance they might not appear in this release.

.defun getf place indicator &optional default
3getf* fetches the value under the 2indicator* indicator from
the property list which 2place* evaluates to.  If no such
indicator exists, then 2default* is returned.  The standard
lan{maclisp} 3get* function could have been written as
.lisp
(defun get (x indicator)
  (typecase x
    (symbol (getf (symbol-plist x) indicator))
    (cons (getf (cdr x) indicator))
    (t 2error*)))
.end_lisp

It is not really necessary for 2place* to actually be a
generalized variable.  However, 3getf* may be used with 3setf*
(and all such similar constructs), in which case 2place* obviously
must be such a thing.  lan{Maclisp} 3putprop* could have been
written as
.lisp
(defun putprop (x value indicator)
  (typecase x
    (symbol (setf (getf (symbol-plist x) indicator) value))
    (cons (setf (getf (cdr x) indicator) value))
    (t 2error*)))
.end_lisp

The utility of 3getf* is that it may be used to manipulate
"property lists" stored in places other than symbols or the 3cdr*
of a 3cons*.  One might, for instance, define a structure with
3defstruct* ((defstruct-fun)) which has one slot used to hold
a property list:
.lisp
(defstruct (frobozz :named :conc-name)
   initial-data
   plist
   (hyperspace-shift-count 0))
.end_lisp
Then, items in the "property list" may be accessed by
.lisp
(getf (frobozz-plist 2frobozz*) 2indicator*)
.end_lisp
and set by
.lisp
(setf (getf (frobozz-plist 2frobozz*) 2indicator*) 2value*)
.end_lisp
One may also do such things as
.lisp
(incf (getf (frobozz-plist 2frobozz*) 2indicator*))
.end_lisp
to increment a value stored on the property list.
.end_defun

.defun remf place indicator
3remf* removes an indicator/value pair from the property list in
2place*.  In order to do so, 2place* must be a generalized
variable usable with 2setf*.  3remf* returns 3nil* if
there was no such pair for 3indicator*, 3t* otherwise.
.end_defun


.defun get-properties place names
3get-properties* allows one to search for a set of properties.  It
looks down the property list in 2place*;  when an indicator is
found which is in the list 2names*, then it returns three values:
the value under that indicator, the indicator, and the sublist of the
property list beginning with the indicator.  (Thus, the 3car* of
that sublist is the indicator, and the 3cadr* the value.  This
last value is what is returned by the lan{maclisp} 3getl*
function, (getl-fun).)  If none of the indicators specified in
2names* are found, then all three values 3get-properties*
returns are 3nil*.

Not only can 3get-properties* be used for searching for more than
one indicator at once, but the third value returned can be fed back to
3get-properties* to continue searching from that (or some later)
point in the property list.
.end_defun

Note also the property-list function 3get* ((get-fun)) and
3remprop* ((remprop-fun)).

