Top-level programs

A top-level program specifies an entry point for defining and running a Scheme program. A top-level program specifies a set of libraries to import and code to run. Through the imported libraries, whether directly or through the transitive closure of importing, a top-level program defines a complete Scheme program.

Top-level programs follow the convention of many common platforms of accepting a list of string command-line arguments that may be used to pass data to the program.

7.1  Top-level program syntax

A top-level program is a delimited piece of text, typically a file, that follows the following syntax:

<toplevel program> → <import form> <toplevel body>
<import form> → (import <import spec>*)
<toplevel body> → <toplevel body form>*
<toplevel body form> → <definition> | <expression>
The rules for <toplevel program> specify syntax at the form level.

The <import form> is identical to the import clause in libraries (see section 6.1), and specifies a set of libraries to import. A <toplevel body> is like a <library body> (see section 6.1), except that definitions and expressions may occur in any order. Thus, the syntax specified by <toplevel body form> refers to the result of macro expansion.

Rationale:   By allowing the interleaving of definitions and expressions, top-level programs support exploratory and interactive development, without imposing unnecessary organizational overhead on code which may not be intended for reuse.

When base-library begin, let-syntax, or letrec-syntax forms occur in a top-level body prior to the first expression, they are spliced into the body; see section 9.5.7. Some or all of the body, including portions wrapped in begin, let-syntax, or letrec-syntax forms, may be specified by a syntactic abstraction (see section 6.3.2).

7.2  Top-level program semantics

A top-level program is executed by treating the program similarly to a library, and evaluating its definitions and expressions. The semantics of a top-level body may be roughly explained by a simple translation into a library body: Each <expression> that appears before a definition in the top-level body is converted into a dummy definition (define <variable> (begin <expression> <unspecified>)), where <variable> is a fresh identifier and <unspecified> is a side-effect-free expression returning unspecified values. (It is generally impossible to determine which forms are definitions and expressions without concurrently expanding the body, so the actual translation is somewhat more complicated; see chapter 8.)

On platforms that support it, a top-level program may access its command line by calling the command-line procedure (see library section on “Command-line access and exit values”).