   This file documents the MIT Scheme system.

   Copyright (C) 1988-2002 Massachusetts Institute of Technology

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".

Lexical Binding
===============

   The three binding constructs `let', `let*', and `letrec', give
Scheme block structure.  The syntax of the three constructs is
identical, but they differ in the regions they establish for their
variable bindings.  In a `let' expression, the initial values are
computed before any of the variables become bound.  In a `let*'
expression, the evaluations and bindings are sequentially interleaved.
And in a `letrec' expression, all the bindings are in effect while the
initial values are being computed (thus allowing mutually recursive
definitions).

 - special form: let ((VARIABLE INIT) ...) expression expression ...
     The INITs are evaluated in the current environment (in some
     unspecified order), the VARIABLEs are bound to fresh locations
     holding the results, the EXPRESSIONs are evaluated sequentially in
     the extended environment, and the value of the last EXPRESSION is
     returned.  Each binding of a VARIABLE has the EXPRESSIONs as its
     region.

     MIT Scheme allows any of the INITs to be omitted, in which case
     the corresponding VARIABLEs are unassigned.

     Note that the following are equivalent:

          (let ((VARIABLE INIT) ...) EXPRESSION EXPRESSION ...)
          ((lambda (VARIABLE ...) EXPRESSION EXPRESSION ...) INIT ...)

     Some examples:

          (let ((x 2) (y 3))
            (* x y))                              =>  6

          (let ((x 2) (y 3))
            (let ((foo (lambda (z) (+ x y z)))
                  (x 7))
              (foo 4)))                           =>  9

     See Iteration, for information on "named `let'".

 - special form: let* ((VARIABLE INIT) ...) expression expression ...
     `let*' is similar to `let', but the bindings are performed
     sequentially from left to right, and the region of a binding is
     that part of the `let*' expression to the right of the binding.
     Thus the second binding is done in an environment in which the
     first binding is visible, and so on.

     Note that the following are equivalent:

          (let* ((VARIABLE1 INIT1)
                 (VARIABLE2 INIT2)
                 ...
                 (VARIABLEN INITN))
             EXPRESSION
             EXPRESSION ...)

          (let ((VARIABLE1 INIT1))
            (let ((VARIABLE2 INIT2))
              ...
                (let ((VARIABLEN INITN))
                  EXPRESSION
                  EXPRESSION ...)
              ...))

     An example:

          (let ((x 2) (y 3))
            (let* ((x 7)
                   (z (+ x y)))
              (* z x)))                           =>  70

 - special form: letrec ((VARIABLE INIT) ...) expression expression ...
     The VARIABLEs are bound to fresh locations holding unassigned
     values, the INITs are evaluated in the extended environment (in
     some unspecified order), each VARIABLE is assigned to the result
     of the corresponding INIT, the EXPRESSIONs are evaluated
     sequentially in the extended environment, and the value of the last
     EXPRESSION is returned.  Each binding of a VARIABLE has the entire
     `letrec' expression as its region, making it possible to define
     mutually recursive procedures.

     MIT Scheme allows any of the INITs to be omitted, in which case
     the corresponding VARIABLEs are unassigned.

          (letrec ((even?
                    (lambda (n)
                      (if (zero? n)
                          #t
                          (odd? (- n 1)))))
                   (odd?
                    (lambda (n)
                      (if (zero? n)
                          #f
                          (even? (- n 1))))))
            (even? 88))                           =>  #t

     One restriction on `letrec' is very important: it shall be possible
     to evaluated each INIT without assigning or referring to the value
     of any VARIABLE.  If this restriction is violated, then it is an
     error.  The restriction is necessary because Scheme passes
     arguments by value rather than by name.  In the most common uses
     of `letrec', all the INITs are `lambda' or `delay' expressions and
     the restriction is satisfied automatically.

Dynamic Binding
===============

 - special form: fluid-let ((VARIABLE INIT) ...) expression expression
          ...
     The INITs are evaluated in the current environment (in some
     unspecified order), the current values of the VARIABLEs are saved,
     the results are assigned to the VARIABLEs, the EXPRESSIONs are
     evaluated sequentially in the current environment, the VARIABLEs
     are restored to their original values, and the value of the last
     EXPRESSION is returned.

     The syntax of this special form is similar to that of `let', but
     `fluid-let' temporarily rebinds existing variables.  Unlike `let',
     `fluid-let' creates no new bindings; instead it _assigns_ the
     value of each INIT to the binding (determined by the rules of
     lexical scoping) of its corresponding VARIABLE.

     MIT Scheme allows any of the INITs to be omitted, in which case
     the corresponding VARIABLEs are temporarily unassigned.

     An error of type `condition-type:unbound-variable' is signalled if
     any of the VARIABLEs are unbound.  However, because `fluid-let'
     operates by means of side effects, it is valid for any VARIABLE to
     be unassigned when the form is entered.

     Here is an example showing the difference between `fluid-let' and
     `let'.  First see how `let' affects the binding of a variable:

          (define variable #t)
          (define (access-variable) variable)
          variable                                =>  #t
          (let ((variable #f))
            (access-variable))                    =>  #t
          variable                                =>  #t

     `access-variable' returns `#t' in this case because it is defined
     in an environment with `variable' bound to `#t'.  `fluid-let', on
     the other hand, temporarily reuses an existing variable:

          variable                                =>  #t
          (fluid-let ((variable #f))              ;reuses old binding
            (access-variable))                    =>  #f
          variable                                =>  #t

     The "extent" of a dynamic binding is defined to be the time period
     during which the variable contains the new value.  Normally this
     time period begins when the body is entered and ends when it is
     exited; on a sequential machine it is normally a contiguous time
     period.  However, because Scheme has first-class continuations, it
     is possible to leave the body and then reenter it, as many times
     as desired.  In this situation, the extent becomes non-contiguous.

     When the body is exited by invoking a continuation, the new value
     is saved, and the variable is set to the old value.  Then, if the
     body is reentered by invoking a continuation, the old value is
     saved, and the variable is set to the new value.  In addition,
     side effects to the variable that occur both inside and outside of
     body are preserved, even if continuations are used to jump in and
     out of body repeatedly.

   Here is a complicated example that shows the interaction between
dynamic binding and continuations:

     (define (complicated-dynamic-binding)
       (let ((variable 1)
             (inside-continuation))
         (write-line variable)
         (call-with-current-continuation
          (lambda (outside-continuation)
            (fluid-let ((variable 2))
              (write-line variable)
              (set! variable 3)
              (call-with-current-continuation
               (lambda (k)
                 (set! inside-continuation k)
                 (outside-continuation #t)))
              (write-line variable)
              (set! inside-continuation #f))))
         (write-line variable)
         (if inside-continuation
             (begin
               (set! variable 4)
               (inside-continuation #f)))))

Evaluating `(complicated-dynamic-binding)' writes the following on the
console:

     1
     2
     1
     3
     4

Commentary: the first two values written are the initial binding of
`variable' and its new binding after the `fluid-let''s body is entered.
Immediately after they are written, `variable' is set to `3', and then
`outside-continuation' is invoked, causing us to exit the body.  At
this point, `1' is written, demonstrating that the original value of
`variable' has been restored, because we have left the body.  Then we
set `variable' to `4' and reenter the body by invoking
`inside-continuation'.  At this point, `3' is written, indicating that
the side effect that previously occurred within the body has been
preserved.  Finally, we exit body normally, and write `4',
demonstrating that the side effect that occurred outside of the body
was also preserved.

Definitions
===========

 - special form: define variable [expression]
 - special form: define FORMALS expression expression ...
     Definitions are valid in some but not all contexts where
     expressions are allowed.  Definitions may only occur at the top
     level of a program and at the beginning of a lambda body (that is,
     the body of a `lambda', `let', `let*', `letrec', `fluid-let', or
     "procedure `define'" expression).  A definition that occurs at the
     top level of a program is called a "top-level definition", and a
     definition that occurs at the beginning of a body is called an
     "internal definition".

     In the second form of `define' (called ""procedure `define'""),
     the component FORMALS is identical to the component of the same
     name in a `named-lambda' expression.  In fact, these two
     expressions are equivalent:

          (define (NAME1 NAME2 ...)
            EXPRESSION
            EXPRESSION ...)

          (define NAME1
            (named-lambda (NAME1 NAME2 ...)
              EXPRESSION
              EXPRESSION ...))

Top-Level Definitions
---------------------

   A top-level definition,

     (define VARIABLE EXPRESSION)

has essentially the same effect as this assignment expression, if
VARIABLE is bound:

     (set! VARIABLE EXPRESSION)

   If VARIABLE is not bound, however, `define' binds VARIABLE to a new
location in the current environment before performing the assignment
(it is an error to perform a `set!' on an unbound variable).  If you
omit EXPRESSION, the variable becomes unassigned; an attempt to
reference such a variable is an error.

     (define add3
        (lambda (x) (+ x 3)))                =>  unspecified
     (add3 3)                                =>  6

     (define first car)                      =>  unspecified
     (first '(1 2))                          =>  1

     (define bar)                            =>  unspecified
     bar                                     error--> Unassigned variable

Internal Definitions
--------------------

   An "internal definition" is a definition that occurs at the
beginning of a BODY (that is, the body of a `lambda', `let', `let*',
`letrec', `fluid-let', or "procedure `define'" expression), rather than
at the top level of a program.  The variable defined by an internal
definition is local to the BODY.  That is, VARIABLE is bound rather
than assigned, and the region of the binding is the entire BODY.  For
example,

     (let ((x 5))
       (define foo (lambda (y) (bar x y)))
       (define bar (lambda (a b) (+ (* a b) a)))
       (foo (+ x 3)))                        =>  45

   A BODY containing internal definitions can always be converted into
a completely equivalent `letrec' expression.  For example, the `let'
expression in the above example is equivalent to

     (let ((x 5))
       (letrec ((foo (lambda (y) (bar x y)))
                (bar (lambda (a b) (+ (* a b) a))))
         (foo (+ x 3))))

Assignments
===========

 - special form: set! variable [expression]
     If EXPRESSION is specified, evaluates EXPRESSION and stores the
     resulting value in the location to which VARIABLE is bound.  If
     EXPRESSION is omitted, VARIABLE is altered to be unassigned; a
     subsequent reference to such a VARIABLE is an error.  In either
     case, the value of the `set!' expression is unspecified.

     VARIABLE must be bound either in some region enclosing the `set!'
     expression, or at the top level.  However, VARIABLE is permitted
     to be unassigned when the `set!' form is entered.

          (define x 2)                            =>  unspecified
          (+ x 1)                                 =>  3
          (set! x 4)                              =>  unspecified
          (+ x 1)                                 =>  5

     VARIABLE may be an `access' expression (see Environments).
     This allows you to assign variables in an arbitrary environment.
     For example,

          (define x (let ((y 0)) (the-environment)))
          (define y 'a)
          y                                       =>  a
          (access y x)                            =>  0
          (set! (access y x) 1)                   =>  unspecified
          y                                       =>  a
          (access y x)                            =>  1

Quoting
=======

   This section describes the expressions that are used to modify or
prevent the evaluation of objects.

 - special form: quote datum
     `(quote DATUM)' evaluates to DATUM.  DATUM may be any external
     representation of a Scheme object (see External Representations).
     Use `quote' to include literal constants in
     Scheme code.

          (quote a)                               =>  a
          (quote #(a b c))                        =>  #(a b c)
          (quote (+ 1 2))                         =>  (+ 1 2)

     `(quote DATUM)' may be abbreviated as `'DATUM'.  The two notations
     are equivalent in all respects.

          'a                                      =>  a
          '#(a b c)                               =>  #(a b c)
          '(+ 1 2)                                =>  (+ 1 2)
          '(quote a)                              =>  (quote a)
          ''a                                     =>  (quote a)

     Numeric constants, string constants, character constants, and
     boolean constants evaluate to themselves, so they don't need to be
     quoted.

          '"abc"                                  =>  "abc"
          "abc"                                   =>  "abc"
          '145932                                 =>  145932
          145932                                  =>  145932
          '#t                                     =>  #t
          #t                                      =>  #t
          '#\a                                    =>  #\a
          #\a                                     =>  #\a

 - special form: quasiquote template
     "Backquote" or "quasiquote" expressions are useful for constructing
     a list or vector structure when most but not all of the desired
     structure is known in advance.  If no commas appear within the
     TEMPLATE, the result of evaluating ``TEMPLATE' is equivalent (in
     the sense of `equal?') to the result of evaluating `'TEMPLATE'.
     If a comma appears within the TEMPLATE, however, the expression
     following the comma is evaluated ("unquoted") and its result is
     inserted into the structure instead of the comma and the
     expression.  If a comma appears followed immediately by an at-sign
     (@), then the following expression shall evaluate to a list; the
     opening and closing parentheses of the list are then "stripped
     away" and the elements of the list are inserted in place of the
     comma at-sign expression sequence.

          `(list ,(+ 1 2) 4)                       =>  (list 3 4)

          (let ((name 'a)) `(list ,name ',name))   =>  (list a 'a)

          `(a ,(+ 1 2) ,@(map abs '(4 -5 6)) b)    =>  (a 3 4 5 6 b)

          `((foo ,(- 10 3)) ,@(cdr '(c)) . ,(car '(cons)))
                                                   =>  ((foo 7) . cons)

          `#(10 5 ,(sqrt 4) ,@(map sqrt '(16 9)) 8)
                                                   =>  #(10 5 2 4 3 8)

          `,(+ 2 3)                                =>  5

     Quasiquote forms may be nested.  Substitutions are made only for
     unquoted components appearing at the same nesting level as the
     outermost backquote.  The nesting level increases by one inside
     each successive quasiquotation, and decreases by one inside each
     unquotation.

          `(a `(b ,(+ 1 2) ,(foo ,(+ 1 3) d) e) f)
               =>  (a `(b ,(+ 1 2) ,(foo 4 d) e) f)

          (let ((name1 'x)
                (name2 'y))
             `(a `(b ,,name1 ,',name2 d) e))
               =>  (a `(b ,x ,'y d) e)

     The notations ``TEMPLATE' and (`quasiquote TEMPLATE') are
     identical in all respects.  `,EXPRESSION' is identical to `(unquote
     EXPRESSION)' and `,@EXPRESSION' is identical to `(unquote-splicing
     EXPRESSION)'.

          (quasiquote (list (unquote (+ 1 2)) 4))
               =>  (list 3 4)

          '(quasiquote (list (unquote (+ 1 2)) 4))
               =>  `(list ,(+ 1 2) 4)
               _i.e.,_ (quasiquote (list (unquote (+ 1 2)) 4))

     Unpredictable behavior can result if any of the symbols
     `quasiquote', `unquote', or `unquote-splicing' appear in a
     TEMPLATE in ways otherwise than as described above.

Conditionals
============

   The behavior of the "conditional expressions" is determined by
whether objects are true or false.  The conditional expressions count
only `#f' as false.  They count everything else, including `#t', pairs,
symbols, numbers, strings, vectors, and procedures as true (but
True and False).

   In the descriptions that follow, we say that an object has "a true
value" or "is true" when the conditional expressions treat it as true,
and we say that an object has "a false value" or "is false" when the
conditional expressions treat it as false.

 - special form: if predicate consequent [alternative]
     PREDICATE, CONSEQUENT, and ALTERNATIVE are expressions.  An `if'
     expression is evaluated as follows: first, PREDICATE is evaluated.
     If it yields a true value, then CONSEQUENT is evaluated and its
     value is returned.  Otherwise ALTERNATIVE is evaluated and its
     value is returned.  If PREDICATE yields a false value and no
     ALTERNATIVE is specified, then the result of the expression is
     unspecified.

     An `if' expression evaluates either CONSEQUENT or ALTERNATIVE,
     never both.  Programs should not depend on the value of an `if'
     expression that has no ALTERNATIVE.

          (if (> 3 2) 'yes 'no)                   =>  yes
          (if (> 2 3) 'yes 'no)                   =>  no
          (if (> 3 2)
              (- 3 2)
              (+ 3 2))                            =>  1

 - special form: cond clause clause ...
     Each CLAUSE has this form:

          (PREDICATE EXPRESSION ...)

     where PREDICATE is any expression.  The last CLAUSE may be an
     "`else' clause", which has the form:

          (else EXPRESSION EXPRESSION ...)

     A `cond' expression does the following:

       1. Evaluates the PREDICATE expressions of successive CLAUSEs in
          order, until one of the PREDICATEs evaluates to a true value.

       2. When a PREDICATE evaluates to a true value, `cond' evaluates
          the EXPRESSIONs in the associated CLAUSE in left to right
          order, and returns the result of evaluating the last
          EXPRESSION in the CLAUSE as the result of the entire `cond'
          expression.

          If the selected CLAUSE contains only the PREDICATE and no
          EXPRESSIONs, `cond' returns the value of the PREDICATE as the
          result.

       3. If all PREDICATEs evaluate to false values, and there is no
          `else' clause, the result of the conditional expression is
          unspecified; if there is an `else' clause, `cond' evaluates
          its EXPRESSIONs (left to right) and returns the value of the
          last one.

          (cond ((> 3 2) 'greater)
                ((< 3 2) 'less))                  =>  greater

          (cond ((> 3 3) 'greater)
                ((< 3 3) 'less)
                (else 'equal))                    =>  equal

     Normally, programs should not depend on the value of a `cond'
     expression that has no `else' clause.  However, some Scheme
     programmers prefer to write `cond' expressions in which at least
     one of the PREDICATEs is always true.  In this style, the final
     CLAUSE is equivalent to an `else' clause.

     Scheme supports an alternative CLAUSE syntax:

          (PREDICATE => RECIPIENT)

     where RECIPIENT is an expression.  If PREDICATE evaluates to a
     true value, then RECIPIENT is evaluated.  Its value must be a
     procedure of one argument; this procedure is then invoked on the
     value of the PREDICATE.

          (cond ((assv 'b '((a 1) (b 2))) => cadr)
                (else #f))                        =>  2

 - special form: case key clause clause ...
     KEY may be any expression.  Each CLAUSE has this form:

          ((OBJECT ...) EXPRESSION EXPRESSION ...)

     No OBJECT is evaluated, and all the OBJECTs must be distinct.  The
     last CLAUSE may be an "`else' clause", which has the form:

          (else EXPRESSION EXPRESSION ...)

     A `case' expression does the following:

       1. Evaluates KEY and compares the result with each OBJECT.

       2. If the result of evaluating KEY is equivalent (in the sense of
          `eqv?'; see Equivalence Predicates) to an OBJECT, `case'
          evaluates the EXPRESSIONs in the corresponding CLAUSE from
          left to right and returns the result of evaluating the last
          EXPRESSION in the CLAUSE as the result of the `case'
          expression.

       3. If the result of evaluating KEY is different from every
          OBJECT, and if there's an `else' clause, `case' evaluates its
          EXPRESSIONs and returns the result of the last one as the
          result of the `case' expression.  If there's no `else'
          clause, `case' returns an unspecified result.  Programs
          should not depend on the value of a `case' expression that
          has no `else' clause.

     For example,

          (case (* 2 3)
             ((2 3 5 7) 'prime)
             ((1 4 6 8 9) 'composite))            =>  composite

          (case (car '(c d))
             ((a) 'a)
             ((b) 'b))                            =>  unspecified

          (case (car '(c d))
             ((a e i o u) 'vowel)
             ((w y) 'semivowel)
             (else 'consonant))                   =>  consonant

 - special form: and expression ...
     The EXPRESSIONs are evaluated from left to right, and the value of
     the first EXPRESSION that evaluates to a false value is returned.
     Any remaining EXPRESSIONs are not evaluated.  If all the
     EXPRESSIONs evaluate to true values, the value of the last
     EXPRESSION is returned.  If there are no EXPRESSIONs then `#t' is
     returned.

          (and (= 2 2) (> 2 1))                   =>  #t
          (and (= 2 2) (< 2 1))                   =>  #f
          (and 1 2 'c '(f g))                     =>  (f g)
          (and)                                   =>  #t

 - special form: or expression ...
     The EXPRESSIONs are evaluated from left to right, and the value of
     the first EXPRESSION that evaluates to a true value is returned.
     Any remaining EXPRESSIONs are not evaluated.  If all EXPRESSIONs
     evaluate to false values, the value of the last EXPRESSION is
     returned.  If there are no EXPRESSIONs then `#f' is returned.

          (or (= 2 2) (> 2 1))                    =>  #t
          (or (= 2 2) (< 2 1))                    =>  #t
          (or #f #f #f)                           =>  #f
          (or (memq 'b '(a b c)) (/ 3 0))         =>  (b c)

Sequencing
==========

   The `begin' special form is used to evaluate expressions in a
particular order.

 - special form: begin expression expression ...
     The EXPRESSIONs are evaluated sequentially from left to right, and
     the value of the last EXPRESSION is returned.  This expression
     type is used to sequence side effects such as input and output.

          (define x 0)
          (begin (set! x 5)
                 (+ x 1))                 =>  6

          (begin (display "4 plus 1 equals ")
                 (display (+ 4 1)))
                                          -|  4 plus 1 equals 5
                                          =>  unspecified

     Often the use of `begin' is unnecessary, because many special forms
     already support sequences of expressions (that is, they have an
     implicit `begin').  Some of these special forms are:

          case
          cond
          define          ;"procedure `define'" only
          do
          fluid-let
          lambda
          let
          let*
          letrec
          named-lambda

     The obsolete special form `sequence' is identical to `begin'.  It
     should not be used in new code.

Iteration
=========

   The "iteration expressions" are: "named `let'" and `do'.  They are
also binding expressions, but are more commonly referred to as
iteration expressions.  Because Scheme is properly tail-recursive, you
don't need to use these special forms to express iteration; you can
simply use appropriately written "recursive" procedure calls.

 - special form: let name ((VARIABLE INIT) ...) expression expression
          ...
     MIT Scheme permits a variant on the syntax of `let' called "named
     `let'" which provides a more general looping construct than `do',
     and may also be used to express recursions.

     Named `let' has the same syntax and semantics as ordinary `let'
     except that NAME is bound within the EXPRESSIONs to a procedure
     whose formal arguments are the VARIABLEs and whose body is the
     EXPRESSIONs.  Thus the execution of the EXPRESSIONs may be
     repeated by invoking the procedure named by NAME.

     MIT Scheme allows any of the INITs to be omitted, in which case
     the corresponding VARIABLEs are unassigned.

     Note: the following expressions are equivalent:

          (let NAME ((VARIABLE INIT) ...)
            EXPRESSION
            EXPRESSION ...)

          ((letrec ((NAME
                     (named-lambda (NAME VARIABLE ...)
                       EXPRESSION
                       EXPRESSION ...)))
             NAME)
           INIT ...)

     Here is an example:

          (let loop
               ((numbers '(3 -2 1 6 -5))
                (nonneg '())
                (neg '()))
            (cond ((null? numbers)
                   (list nonneg neg))
                  ((>= (car numbers) 0)
                   (loop (cdr numbers)
                         (cons (car numbers) nonneg)
                         neg))
                  (else
                   (loop (cdr numbers)
                         nonneg
                         (cons (car numbers) neg)))))

               =>  ((6 1 3) (-5 -2))

 - special form: do ((VARIABLE INIT STEP) ...) (TEST EXPRESSION ...)
          command ...
     `do' is an iteration construct.  It specifies a set of variables to
     be bound, how they are to be initialized at the start, and how
     they are to be updated on each iteration.  When a termination
     condition is met, the loop exits with a specified result value.

     `do' expressions are evaluated as follows: The INIT expressions
     are evaluated (in some unspecified order), the VARIABLEs are bound
     to fresh locations, the results of the INIT expressions are stored
     in the bindings of the VARIABLEs, and then the iteration phase
     begins.

     Each iteration begins by evaluating TEST; if the result is false,
     then the COMMAND expressions are evaluated in order for effect,
     the STEP expressions are evaluated in some unspecified order, the
     VARIABLEs are bound to fresh locations, the results of the STEPs
     are stored in the bindings of the VARIABLEs, and the next
     iteration begins.

     If TEST evaluates to a true value, then the EXPRESSIONs are
     evaluated from left to right and the value of the last EXPRESSION
     is returned as the value of the `do' expression.  If no
     EXPRESSIONs are present, then the value of the `do' expression is
     unspecified in standard Scheme; in MIT Scheme, the value of TEST
     is returned.

     The region of the binding of a VARIABLE consists of the entire
     `do' expression except for the INITs.  It is an error for a
     VARIABLE to appear more than once in the list of `do' variables.

     A STEP may be omitted, in which case the effect is the same as if
     `(VARIABLE INIT VARIABLE)' had been written instead of `(VARIABLE
     INIT)'.

          (do ((vec (make-vector 5))
                (i 0 (+ i 1)))
              ((= i 5) vec)
             (vector-set! vec i i))               =>  #(0 1 2 3 4)

          (let ((x '(1 3 5 7 9)))
             (do ((x x (cdr x))
                  (sum 0 (+ sum (car x))))
                 ((null? x) sum)))                =>  25

Structure Definitions
=====================

   This section provides examples and describes the options and syntax
of `define-structure', an MIT Scheme macro that is very similar to
`defstruct' in Common Lisp.  The differences between them are
summarized at the end of this section.  For more information, see
Steele's Common Lisp book.

 - special form: define-structure (name structure-option ...)
          slot-description ...
     Each SLOT-DESCRIPTION takes one of the following forms:

          SLOT-NAME
          (SLOT-NAME DEFAULT-INIT [SLOT-OPTION VALUE]*)

     The fields NAME and SLOT-NAME must both be symbols.  The field
     DEFAULT-INIT is an expression for the initial value of the slot.
     It is evaluated each time a new instance is constructed.  If it is
     not specified, the initial content of the slot is undefined.
     Default values are only useful with a BOA constructor with
     argument list or a keyword constructor (see below).

     Evaluation of a `define-structure' expression defines a structure
     descriptor and a set of procedures to manipulate instances of the
     structure.  These instances are represented as records by default
     (see Records) but may alternately be lists or vectors.  The
     accessors and modifiers are marked with compiler declarations so
     that calls to them are automatically transformed into appropriate
     references.  Often, no options are required, so a simple call to
     `define-structure' looks like:

          (define-structure foo a b c)

     This defines a type descriptor `foo', a constructor `make-foo', a
     predicate `foo?', accessors `foo-a', `foo-b', and `foo-c', and
     modifiers `set-foo-a!', `set-foo-b!', and `set-foo-c!'.

     In general, if no options are specified, `define-structure' defines
     the following (using the simple call above as an example):

    type descriptor
          The name of the type descriptor is the same as the name of the
          structure, e.g. `foo'.  The type descriptor satisfies the
          predicate `record-type?'.

    constructor
          The name of the constructor is `"make-"' followed by the name
          of the structure, e.g. `make-foo'.  The number of arguments
          accepted by the constructor is the same as the number of
          slots; the arguments are the initial values for the slots,
          and the order of the arguments matches the order of the slot
          definitions.

    predicate
          The name of the predicate is the name of the structure
          followed by `"?"', e.g. `foo?'.  The predicate is a procedure
          of one argument, which returns `#t' if its argument is a
          record of the type defined by this structure definition, and
          `#f' otherwise.

    accessors
          For each slot, an accessor is defined.  The name of the
          accessor is formed by appending the name of the structure, a
          hyphen, and the name of the slot, e.g. `foo-a'.  The accessor
          is a procedure of one argument, which must be a record of the
          type defined by this structure definition.  The accessor
          extracts the contents of the corresponding slot in that
          record and returns it.

    modifiers
          For each slot, a modifier is defined.  The name of the
          modifier is formed by appending `"set-"', the name of the
          accessor, and `"!"', e.g. `set-foo-a!'.  The modifier is a
          procedure of two arguments, the first of which must be a
          record of the type defined by this structure definition, and
          the second of which may be any object.  The modifier modifies
          the contents of the corresponding slot in that record to be
          that object, and returns an unspecified value.

     When options are not supplied, `(NAME)' may be abbreviated to
     NAME.  This convention holds equally for STRUCTURE-OPTIONS and
     SLOT-OPTIONS.  Hence, these are equivalent:

          (define-structure foo a b c)
          (define-structure (foo) (a) b (c))

     as are

          (define-structure (foo keyword-constructor) a b c)
          (define-structure (foo (keyword-constructor)) a b c)

     When specified as option values, `false' and `nil' are equivalent
     to `#f', and `true' and `t' are equivalent to `#t'.

   Possible SLOT-OPTIONS are:

 - slot option: read-only value
     When given a VALUE other than `#f', this specifies that no
     modifier should be created for the slot.

 - slot option: type type-descriptor
     This is accepted but not presently used.

   Possible STRUCTURE-OPTIONS are:

 - structure option: predicate [name]
     This option controls the definition of a predicate procedure for
     the structure.  If NAME is not given, the predicate is defined with
     the default name (see above).  If NAME is `#f', the predicate is
     not defined at all.  Otherwise, NAME must be a symbol, and the
     predicate is defined with that symbol as its name.

 - structure option: copier [name]
     This option controls the definition of a procedure to copy
     instances of the structure.  This is a procedure of one argument,
     a structure instance, that makes a newly allocated copy of the
     structure and returns it.  If NAME is not given, the copier is
     defined, and the name of the copier is `"copy-"' followed by the
     structure name (e.g.  `copy-foo').  If NAME is `#f', the copier is
     not defined.  Otherwise, NAME must be a symbol, and the copier is
     defined with that symbol as its name.

 - structure option: print-procedure expression
     Evaluating EXPRESSION must yield a procedure of two arguments,
     which is used to print instances of the structure.  The procedure
     is an "unparser method" (see Custom Output).  If the structure
     instances are records, this option has the same effect as calling
     `set-record-type-unparser-method!'.

 - structure option: constructor [name [argument-list]]
     This option controls the definition of constructor procedures.
     These constructor procedures are called "BOA constructors", for "By
     Order of Arguments", because the arguments to the constructor
     specify the initial contents the structure's slots by the order in
     which they are given.  This is as opposed to "keyword
     constructors", which specify the initial contents using keywords,
     and in which the order of arguments is irrelevant.

     If NAME is not given, a constructor is defined with the default
     name and arguments (see above).  If NAME is `#f', no constructor
     is defined; ARGUMENT-LIST may not be specified in this case.
     Otherwise, NAME must be a symbol, and a constructor is defined
     with that symbol as its name.  If NAME is a symbol, ARGUMENT-LIST
     is optionally allowed; if it is omitted, the constructor accepts
     one argument for each slot in the structure definition, in the
     same order in which the slots appear in the definition.
     Otherwise, ARGUMENT-LIST must be a lambda list (see Lambda Expressions),
     and each of the parameters of the lambda list must
     be the name of a slot in the structure.  The arguments accepted by
     the constructor are defined by this lambda list.  Any slot that is
     not specified by the lambda list is initialized to the
     DEFAULT-INIT as specified above; likewise for any slot specified
     as an optional parameter when the corresponding argument is not
     supplied.

     If the `constructor' option is specified, the default constructor
     is not defined.  Additionally, the `constructor' option may be
     specified multiple times to define multiple constructors with
     different names and argument lists.

          (define-structure (foo
                             (constructor make-foo (#!optional a b)))
            (a 6 read-only #t)
            (b 9))

 - structure option: keyword-constructor [name]
     This option controls the definition of keyword constructor
     procedures.  A "keyword constructor" is a procedure that accepts
     arguments that are alternating slot names and values.  If NAME is
     omitted, a keyword constructor is defined, and the name of the
     constructor is `"make-"' followed by the name of the structure
     (e.g.  `make-foo').  Otherwise, NAME must be a symbol, and a
     keyword constructor is defined with this symbol as its name.

     If the `keyword-constructor' option is specified, the default
     constructor is not defined.  Additionally, the
     `keyword-constructor' option may be specified multiple times to
     define multiple keyword constructors; this is usually not done
     since such constructors would all be equivalent.

          (define-structure (foo (keyword-constructor make-bar)) a b)
          (foo-a (make-bar 'b 20 'a 19))         => 19

 - structure option: type-descriptor name
     This option cannot be used with the `type' or `named' options.

     By default, structures are implemented as records.  The name of the
     structure is defined to hold the type descriptor of the record
     defined by the structure.  The `type-descriptor' option specifies a
     different name to hold the type descriptor.

          (define-structure foo a b)
          foo             => #[record-type 18]

          (define-structure (bar (type-descriptor bar-rtd)) a b)
          bar             error--> Unbound variable: bar
          bar-rtd         => #[record-type 19]

 - structure option: conc-name [name]
     By default, the prefix for naming accessors and modifiers is the
     name of the structure followed by a hyphen.  The `conc-name'
     option can be used to specify an alternative.  If NAME is not
     given, the prefix is the name of the structure followed by a
     hyphen (the default).  If NAME is `#f', the slot names are used
     directly, without prefix.  Otherwise, NAME must a symbol, and that
     symbol is used as the prefix.

          `(define-structure (foo (conc-name moby/)) a b)'

     defines accessors `moby/a' and `moby/b', and modifiers
     `set-moby/a!' and `set-moby/b!'.

          `(define-structure (foo (conc-name #f)) a b)'

     defines accessors `a' and `b', and modifiers `set-a!' and `set-b!'.

 - structure option: type representation-type
     This option cannot be used with the `type-descriptor' option.

     By default, structures are implemented as records.  The `type'
     option overrides this default, allowing the programmer to specify
     that the structure be implemented using another data type.  The
     option value REPRESENTATION-TYPE specifies the alternate data
     type; it is allowed to be one of the symbols `vector' or `list',
     and the data type used is the one corresponding to the symbol.

     If this option is given, and the `named' option is not specified,
     the representation will not be tagged, and neither a predicate nor
     a type descriptor will be defined; also, the `print-procedure'
     option may not be given.

          (define-structure (foo (type list)) a b)
          (make-foo 1 2)                          => (1 2)

 - structure option: named [expression]
     This is valid only in conjunction with the `type' option and
     specifies that the structure instances be tagged to make them
     identifiable as instances of this structure type.  This option
     cannot be used with the `type-descriptor' option.

     In the usual case, where EXPRESSION is not given, the `named'
     option causes a type descriptor and predicate to be defined for the
     structure (recall that the `type' option without `named'
     suppresses their definition), and also defines a default unparser
     method for the structure instances (which can be overridden by the
     `print-procedure' option).  If the default unparser method is not
     wanted then the `print-procedure' option should be specified as
     `#F'.  This causes the structure to be printed in its native
     representation, as a list or vector, which includes the type
     descriptor.  The type descriptor is a unique object, _not_ a
     record type, that describes the structure instances and is
     additionally stored in the structure instances to identify them:
     if the representation type is `vector', the type descriptor is
     stored in the zero-th slot of the vector, and if the
     representation type is `list', it is stored as the first element
     of the list.

          (define-structure (foo (type vector) named) a b c)
          (vector-ref (make-foo 1 2 3) 0) => #[structure-type 52]

     If EXPRESSION is specified, it is an expression that is evaluated
     to yield a tag object.  The EXPRESSION is evaluated once when the
     structure definition is evaluated (to specify the unparser
     method), and again whenever a predicate or constructor is called.
     Because of this, EXPRESSION is normally a variable reference or a
     constant.  The value yielded by EXPRESSION may be any object at
     all.  That object is stored in the structure instances in the same
     place that the type descriptor is normally stored, as described
     above.  If EXPRESSION is specified, no type descriptor is defined,
     only a predicate.

          (define-structure (foo (type vector) (named 'foo)) a b c)
          (vector-ref (make-foo 1 2 3) 0) => foo

 - structure option: safe-accessors [boolean]
     This option allows the programmer to have some control over the
     safety of the slot accessors (and modifiers) generated by
     `define-structure'.  If `safe-accessors' is not specified, or if
     BOOLEAN is `#f', then the accessors are optimized for speed at the
     expense of safety; when compiled, the accessors will turn into
     very fast inline sequences, usually one to three machine
     instructions in length.  However, if `safe-accessors' is specified
     and BOOLEAN is either omitted or `#t', then the accessors are
     optimized for safety, will check the type and structure of their
     argument, and will be close-coded.

          (define-structure (foo safe-accessors) a b c)

 - structure option: initial-offset offset
     This is valid only in conjunction with the `type' option.  OFFSET
     must be an exact non-negative integer and specifies the number of
     slots to leave open at the beginning of the structure instance
     before the specified slots are allocated.  Specifying an OFFSET of
     zero is equivalent to omitting the `initial-offset' option.

     If the `named' option is specified, the structure tag appears in
     the first slot, followed by the "offset" slots, and then the
     regular slots.  Otherwise, the "offset" slots come first, followed
     by the regular slots.

          (define-structure (foo (type vector) (initial-offset 3))
            a b c)
          (make-foo 1 2 3)                => #(() () () 1 2 3)

   The essential differences between MIT Scheme's `define-structure'
and Common Lisp's `defstruct' are:

   * The default constructor procedure takes positional arguments, in
     the same order as specified in the definition of the structure.  A
     keyword constructor may be specified by giving the option
     `keyword-constructor'.

   * BOA constructors are described using Scheme lambda lists.  Since
     there is nothing corresponding to `&aux' in Scheme lambda lists,
     this functionality is not implemented.

   * By default, no `copier' procedure is defined.

   * The side-effect procedure corresponding to the accessor `foo' is
     given the name `set-foo!'.

   * Keywords are ordinary symbols - use `foo' instead of `:foo'.

   * The option values `false', `nil', `true', and `t' are treated as
     if the appropriate boolean constant had been specified instead.

   * The `print-function' option is named `print-procedure'.  Its
     argument is a procedure of two arguments (the unparser state and
     the structure instance) rather than three as in Common Lisp.

   * By default, named structures are tagged with a unique object of
     some kind.  In Common Lisp, the structures are tagged with
     symbols.  This depends on the Common Lisp package system to help
     generate unique tags; MIT Scheme has no such way to generate
     unique symbols.

   * The `named' option may optionally take an argument, which is
     normally the name of a variable (any expression may be used, but
     it is evaluated whenever the tag name is needed).  If used,
     structure instances will be tagged with that variable's value.
     The variable must be defined when `define-structure' is evaluated.

   * The `type' option is restricted to the values `vector' and `list'.

   * The `include' option is not implemented.