On this page:
unit
define-signature
open
define-values-for-export
contracted
only
except
rename
prefix
import
export
link
tag
init-depend
extends

7.1 Creating Units🔗ℹ

syntax

(unit
  (import tagged-sig-spec ...)
  (export tagged-sig-spec ...)
  init-depends-decl
  unit-body-expr-or-defn
  ...)
 
tagged-sig-spec = sig-spec
  | (tag id sig-spec)
     
sig-spec = sig-id
  | (prefix id sig-spec)
  | (rename sig-spec (id id) ...)
  | (only sig-spec id ...)
  | (except sig-spec id ...)
     
init-depends-decl = 
  | (init-depend tagged-sig-id ...)
     
tagged-sig-id = sig-id
  | (tag id sig-id)
Produces a unit that encapsulates its unit-body-expr-or-defns. Expressions in the unit body can refer to identifiers bound by the sig-specs of the import clause, and the body must include one definition for each identifier of a sig-spec in the export clause. An identifier that is exported cannot be set!ed in either the defining unit or importing units, although the implicit assignment to initialize the variable may be visible as a mutation.

Each import or export sig-spec ultimately refers to a sig-id, which is an identifier that is bound to a signature by define-signature. The lexical information of each identifier imported through a sig-id starts with the lexical information of the sig-id; see define-signature form more information.

In a specific import or export position, the set of identifiers bound or required by a particular sig-id can be adjusted in a few ways:

As suggested by the grammar, these adjustments to a signature can be nested arbitrarily.

A unit’s declared imports are matched with actual supplied imports by signature. That is, the order in which imports are supplied to a unit when linking is irrelevant; all that matters is the signature implemented by each supplied import. One actual import must be provided for each declared import. Similarly, when a unit implements multiple signatures, the order of the export signatures does not matter.

To support multiple imports or exports for the same signature, an import or export can be tagged using the form (tag id sig-spec). When an import declaration of a unit is tagged, then one actual import must be given the same tag (with the same signature) when the unit is linked. Similarly, when an export declaration is tagged for a unit, then references to that particular export must explicitly use the tag.

A unit is prohibited syntactically from importing two signatures that are not distinct, unless they have different tags; two signatures are distinct only if they share no ancestor through extends. The same syntactic constraint applies to exported signatures. In addition, a unit is prohibited syntactically from importing the same identifier twice (after renaming and other transformations on a sig-spec), exporting the same identifier twice (again, after renaming), or exporting an identifier that is imported.

When units are linked, the bodies of the linked units are executed in an order that is specified at the linking site. An optional (init-depend tagged-sig-id ...) declaration constrains the allowed orders of linking by specifying that the current unit must be initialized after the unit that supplies the corresponding import. Each tagged-sig-id in an init-depend declaration must have a corresponding import in the import clause.

syntax

(define-signature sig-id extension-decl
  (sig-elem ...))
 
extension-decl = 
  | extends sig-id
     
sig-elem = id
  | (define-syntaxes (id ...) expr)
  | (define-values (id ...) expr)
  | (define-values-for-export (id ...) expr)
  | (contracted [id contract] ...)
  | (open sig-spec)
  | (struct id (field ...) struct-option ...)
  | (sig-form-id . datum)
     
field = id
  | [id #:mutable]
     
struct-option = #:mutable
  | #:constructor-name constructor-id
  | #:extra-constructor-name constructor-id
  | #:omit-constructor
  | #:omit-define-syntaxes
  | #:omit-define-values
Binds an identifier sig-id to a signature that specifies a group of bindings for import or export:

When a define-signature form includes an extends clause, then the define signature automatically includes everything in the extended signature. Furthermore, any implementation of the new signature can be used as an implementation of the extended signature.

The lexical information of each id within a signature is compared to the lexical information of sig-id. The extra scopes of id relative to sig-id are recorded for the id. When the sig-id is used as a reference (e.g., in the import clause of unit), a variant of id is created for the referencing context by starting with the lexical information of the referencing sig-id, and then adding the extra scopes for id.

syntax

(open sig-spec)

Allowed only in a sig-elem; see define-signature.

syntax

(define-values-for-export (id ...) expr)

Allowed only in a sig-elem; see define-signature.

syntax

(contracted [id contract] ...)

Allowed only in a sig-elem; see define-signature.

syntax

(only sig-spec id ...)

Allowed only in a sig-spec; see unit.

syntax

(except sig-spec id ...)

Allowed only in a sig-spec; see unit.

syntax

(rename sig-spec (id id) ...)

Allowed only in a sig-spec; see unit.

syntax

(prefix id sig-spec)

Allowed only in a sig-spec; see unit.

syntax

(import tagged-sig-spec ...)

Allowed only in certain forms; see, for example, unit.

syntax

(export tagged-sig-spec ...)

Allowed only in certain forms; see, for example, unit.

syntax

(link linkage-decl ...)

Allowed only in certain forms; see, for example, compound-unit.

syntax

(tag id sig-spec)

(tag id sig-id)
Allowed only in certain forms; see, for example, unit.

syntax

(init-depend tagged-sig-id ...)

Allowed only in a init-depend-decl; see unit.

syntax

extends

Allowed only within define-signature.