\chapter{Program structure}
\label{programchapter}

\section{Programs}

A Scheme program consists of a sequence of expressions and definitions.
Expressions are described in chapter~\ref{expressionchapter};
definitions are the subject of the rest of the present chapter.

Programs are typically stored in files or entered interactively to a
running Scheme system, although other paradigms are possible;
questions of user interface lie outside the scope of this report.
(Indeed, Scheme would still be useful as a notation for expressing
computational methods even in the absence of a mechanical
implementation.)

Definitions occurring at the top level of a program are interpreted
declaratively.  They cause bindings to be created in the top level
environment.  Expressions occurring at the top level of a program are
interpreted imperatively; they are executed in order when the program is
invoked or loaded, and typically perform some kind of initialization.

\todo{Cromarty, etc.: disclaimer about top level?}


\section{Definitions}

Definitions are valid in some, but not all, contexts where expressions
are allowed.  They are valid only at the top level of a \hyper{program}
and, in some implementations, at the beginning of a \hyper{body}.

A definition should have one of the following forms:\mainschindex{define}

\begin{itemize}

\item {\tt(define \hyper{variable} \hyper{expression})}

This syntax is essential.

\item{\tt(define (\hyper{variable} \hyper{formals}) \hyper{body})}

This syntax is not essential.  \hyper{Formals} should be either a
sequence of zero or more variables, or a sequence of one or more
variables followed by a space-delimited period and another variable (as
in a lambda expression).  This form is equivalent to
\begin{scheme}
(define \hyper{variable}
  (lambda (\hyper{formals}) \hyper{body}))\rm.%
\end{scheme}

\item{\tt(define (\hyper{variable} .\ \hyper{formal}) \hyper{body})}

This syntax is not essential.  \hyper{Formal} should be a single
variable.  This form is equivalent to
\begin{scheme}
(define \hyper{variable}
  (lambda \hyper{formal} \hyper{body}))\rm.%
\end{scheme}

\end{itemize}


\subsection{Top level definitions}

At the top level of a program, a definition
\begin{scheme}
(define \hyper{variable} \hyper{expression})%
\end{scheme}
has essentially the same effect as the assignment expression
\begin{scheme}
(\ide{set!}\ \hyper{variable} \hyper{expression})%
\end{scheme}
if \hyper{variable} is bound.  If \hyper{variable} is not bound,
however, then the definition will bind \hyper{variable} to a new
location before performing the assignment, whereas it would be an error
to perform a \ide{set!}\ on an unbound\index{unbound} variable.

\begin{scheme}
(define add3
  (lambda (x) (+ x 3)))
(add3 3)                            \ev  6
(define first car)
(first '(1 2))                      \ev  1%
\end{scheme}

All Scheme implementations must support top level definitions.

Some implementations of Scheme use an initial environment in
which all possible variables are bound to locations, most of
which contain undefined values.  Top level definitions in
such an implementation are truly equivalent to assignments.

\todo{Rozas: equal time for opposition semantics?}


\subsection{Internal definitions}
\label{internaldefines}

Some implementations of Scheme permit definitions to occur at the
beginning of a \hyper{body} (that is, the body of a \ide{lambda},
\ide{let}, \ide{let*}, \ide{letrec}, or \ide{define} expression).  Such
definitions are known as {\em internal definitions} \mainindex{internal
definition} as opposed to the top level definitions described above.
The variable defined by an internal definition is local to the
\hyper{body}.  That is, \hyper{variable} is bound rather than assigned,
and the region of the binding is the entire \hyper{body}.  For example,

\begin{scheme}
(let ((x 5))
  (define foo (lambda (y) (bar x y)))
  (define bar (lambda (a b) (+ (* a b) a)))
  (foo (+ x 3)))                \ev  45%
\end{scheme}

A \hyper{body} containing internal definitions can always be converted
into a completely equivalent \ide{letrec} expression.  For example, the
\ide{let} expression in the above example is equivalent to

\begin{scheme}
(let ((x 5))
  (letrec ((foo (lambda (y) (bar x y)))
           (bar (lambda (a b) (+ (* a b) a))))
    (foo (+ x 3))))%
\end{scheme}

\todo{Say something about why definitions aren't allowed in sequence
expressions?  (For macros, a.k.a.~the ``{\tt progn \singlequote compile} hack''.)}
