### 5.5 Structure Comparisons
```
The module* form differs from module in that it inverts the possibilities for reference between the submodule and enclosing module:

-  A submodule declared with module can be required by its enclosing module, but the submodule cannot require the enclosing module or lexically reference the enclosing module’s bindings.

-  A submodule declared with module* can require its enclosing module, but the enclosing module cannot require the submodule.

In addition, a module* form can specify #f in place of an initial-module-path, in which case the submodule sees all of the enclosing module’s bindings—including bindings that are not exported via provide.

One use of submodules declared with module* and #f is to export additional bindings through a submodule that are not normally exported from the module:

> > "cake.rkt"
> >
> > > ```racket
> > > #lang racket
> > > ( provide print-cake )
> > > ( define ( print-cake n )
> > > ( show " ~a " n #\. )
> > > ( show " .-~a-. " n #\| )
> > > ( show " | ~a | " n #\space )
> > > ( show "---~a---" n #\- ) )
> > > ( define ( show fmt n ch )
> > > ( printf fmt ( make-string n ch ) )
> > > ( newline ) )
> > > ( module* extras #f
> > > ( provide show ) )
> > > ```

In this revised "cake.rkt" module, show is not imported by a module that uses (require "cake.rkt"), since most clients of "cake.rkt" will not want the extra function. A module can require the extra submodule using (require (submod "cake.rkt" extras)) to access the otherwise hidden show function.See submodule paths for more information on submod.

#### 6.2.4 Main and Test Submodules

The following variant of "cake.rkt" includes a main submodule that calls print-cake:

> > "cake.rkt"
> >
> > > ```racket
> > > #lang racket
> > > ( define ( print-cake n )
> > > ( show " ~a " n #\. )
> > > ( show " .-~a-. " n #\| )
> > > ( show " | ~a | " n #\space )
> > > ( show "---~a---" n #\- ) )
> > > ( define ( show fmt n ch )
> > > ( printf fmt ( make-string n ch ) )
> > > ( newline ) )
> > > ( module* main #f
> > > ( print-cake 10 ) )
> > > ```

Running a module does not run its module*-defined submodules. Nevertheless, running the above module via racket or DrRacket prints a cake with 10 candles, because the main submodule is a special case.

When a module is provided as a program name to the racket executable or run directly within DrRacket, if the module has a main submodule, the main submodule is run after its enclosing module. Declaring a main submodule thus specifies extra actions to be performed when a module is run directly, instead of required as a library within a larger program.

A main submodule does not have to be declared with module*. If the main module does not need to use bindings from its enclosing module, it can be declared with module. More commonly, main is declared using module+:

> > ```
(module+ name-id
> > decl ... )```

A submodule declared with [module+](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._module%252B%2529%2529&version=8.18.0.13) is like one declared with [module*](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._module%252A%2529%2529&version=8.18.0.13) using #f as its initial-module-path. In addition, multiple [module+](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._module%252B%2529%2529&version=8.18.0.13) forms can specify the same submodule name, in which case the bodies of the [module+](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._module%252B%2529%2529&version=8.18.0.13) forms are combined to create a single submodule.

The combining behavior of [module+](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._module%252B%2529%2529&version=8.18.0.13) is particularly useful for defining a test submodule, which can be conveniently run using raco test in much the same way that main is conveniently run with racket. For example, the following "physics.rkt" module exports drop and to-energy functions, and it defines a test module to hold unit tests:

> > "physics.rkt"
> >
> > > ```racket
> > > #lang racket
> > > ( module+ test
> > > ( require rackunit )
> > > ( define ε 1e-10 ) )
> > > ( provide drop
> > > to-energy )
> > > ( define ( drop t )
> > > ( * 1/2 9.8 t t ) )
> > > ( module+ test
> > > ( check-= ( drop 0 ) 0 ε )
> > > ( check-= ( drop 10 ) 490 ε ) )
> > > ( define ( to-energy m )
> > > ( * m ( expt 299792458.0 2 ) ) )
> > > ( module+ test
> > > ( check-= ( to-energy 0 ) 0 ε )
> > > ( check-= ( to-energy 1 ) 9e+16 1e+15 ) )
> > > ```

Importing "physics.rkt" into a larger program does not run the drop and to-energy tests—or even trigger the loading of the test code, if the module is compiled—but running raco test physics.rkt at a command line runs the tests.

The above "physics.rkt" module is equivalent to using [module*](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._module%252A%2529%2529&version=8.18.0.13):

> > "physics.rkt"
> >
> > > ```racket
> > > #lang racket
> > > ( provide drop
> > > to-energy )
> > > ( define ( drop t )
> > > ( * 1/2 49/5 t t ) )
> > > ( define ( to-energy m )
> > > ( * m ( expt 299792458 2 ) ) )
> > > ( module* test #f
> > > ( require rackunit )
> > > ( define ε 1e-10 )
> > > ( check-= ( drop 0 ) 0 ε )
> > > ( check-= ( drop 10 ) 490 ε )
> > > ( check-= ( to-energy 0 ) 0 ε )
> > > ( check-= ( to-energy 1 ) 9e+16 1e+15 ) )
> > > ```

Using [module+](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._module%252B%2529%2529&version=8.18.0.13) instead of [module*](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._module%252A%2529%2529&version=8.18.0.13) allows tests to be interleaved with function definitions.

The combining behavior of [module+](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._module%252B%2529%2529&version=8.18.0.13) is also sometimes helpful for a main module. Even when combining is not needed, ([module+](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._module%252B%2529%2529&version=8.18.0.13) main ....) is preferred as it is more readable than ([module*](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._module%252A%2529%2529&version=8.18.0.13) main #f ....).

------------------------------------------------------------------------

# 6.3 Module Paths

### 6.3 Module Paths

A module path is a reference to a module, as used with [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) or as the initial-module-path in a [module](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._module%2529%2529&version=8.18.0.13) form. It can be any of several forms:

> > |                                                                                |
> > |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > | ([quote](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=quote.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._quote%2529%2529&version=8.18.0.13) id) |
>
> A [module path](#%28tech._module._path%29) that is a quoted identifier refers to a non-file [module](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._module%2529%2529&version=8.18.0.13) declaration using the identifier. This form of module reference makes the most sense in a [REPL](intro.html#%28tech._repl%29).
>
>

>
> Examples:
>
>

>
>

>
> > ```racket
> > > ( module m racket ( provide color ) ( define color "blue" ) )
> > > ( module n racket ( require ' m ) ( printf "my favorite color is ~a\n" color ) )
> > > ( require ' n )
> > my favorite color is blue
> > ```
>
>

> > |            |
> > |------------|
> > | rel-string |
>
> A string [module path](#%28tech._module._path%29) is a relative path using Unix-style conventions: / is the path separator, .. refers to the parent directory, and . refers to the same directory. The rel-string must not start or end with a path separator.
>
> The path is relative to the enclosing file, if any, or it is relative to the current directory. (More precisely, the path is relative to the value of ([current-load-relative-directory](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=eval.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._current-load-relative-directory%2529%2529&version=8.18.0.13)), which is set while loading a file.)
>
> [Module Basics](module-basics.html) shows examples using relative paths.
>
> If a relative path ends with a ".ss" suffix, it is converted to ".rkt". If the file that implements the referenced module actually ends in ".ss", the suffix will be changed back when attempting to load the file (but a ".rkt" suffix takes precedence). This two-way conversion provides compatibility with older versions of Racket.

> > |     |
> > |-----|
> > | id  |
>
> A [module path](#%28tech._module._path%29) that is an unquoted identifier refers to an installed library. The id is constrained to contain only ASCII letters, ASCII numbers, +, -, \_, and /, where / separates path elements within the identifier. The elements refer to [collection](module-basics.html#%28tech._collection%29)s and sub-[collections](module-basics.html#%28tech._collection%29), instead of directories and sub-directories.
>
> An example of this form is racket/date. It refers to the module whose source is the "date.rkt" file in the "racket" collection, which is installed as part of Racket. The ".rkt" suffix is added automatically.
>
> Another example of this form is [racket](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=index.html&version=8.18.0.13), which is commonly used at the initial import. The path [racket](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=index.html&version=8.18.0.13) is shorthand for racket/main; when an id has no /, then /main is automatically added to the end. Thus, [racket](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=index.html&version=8.18.0.13) or racket/main refers to the module whose source is the "main.rkt" file in the "racket" collection.
>
>

>
> Examples:
>
>

>
>

>
> > ```racket
> > > ( module m racket ( require racket/date ) ( printf "Today is ~s\n" ( date->string ( seconds->date ( current-seconds ) ) ) ) )
> > > ( require ' m )
> > Today is "Monday, September 1st, 2025"
> > ```
>
>

>
> When the full path of a module ends with ".rkt", if no such file exists but one does exist with the ".ss" suffix, then the ".ss" suffix is substituted automatically. This transformation provides compatibility with older versions of Racket.

> > |                                                                                |
> > |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > | ([lib](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._lib%2529%2529&version=8.18.0.13) rel-string) |
>
> Like an unquoted-identifier path, but expressed as a string instead of an identifier. Also, the rel-string can end with a file suffix, in which case ".rkt" is not automatically added.
>
> Example of this form include ([lib](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._lib%2529%2529&version=8.18.0.13) "racket/date.rkt") and ([lib](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._lib%2529%2529&version=8.18.0.13) "racket/date"), which are equivalent to racket/date. Other examples include ([lib](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._lib%2529%2529&version=8.18.0.13) "racket"), ([lib](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._lib%2529%2529&version=8.18.0.13) "racket/main"), and ([lib](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._lib%2529%2529&version=8.18.0.13) "racket/main.rkt"), which are all equivalent to [racket](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=index.html&version=8.18.0.13).
>
>

>
> Examples:
>
>

>
>

>
> > ```racket
> > > ( module m ( lib "racket" ) ( require ( lib "racket/date.rkt" ) ) ( printf "Today is ~s\n" ( date->string ( seconds->date ( current-seconds ) ) ) ) )
> > > ( require ' m )
> > Today is "Monday, September 1st, 2025"
> > ```
>
>

> > |                                                                                |
> > |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > | ([planet](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._planet%2529%2529&version=8.18.0.13) id) |
>
> Accesses a third-party library that is distributed through the PLaneT server. The library is downloaded the first time that it is needed, and then the local copy is used afterward.
>
> The id encodes several pieces of information separated by a /: the package owner, then package name with optional version information, and an optional path to a specific library with the package. Like id as shorthand for a [lib](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._lib%2529%2529&version=8.18.0.13) path, a ".rkt" suffix is added automatically, and /main is used as the path if no sub-path element is supplied.
>
>

>
> Examples:
>
>

>
>

>
> > ```racket
> > > ( module m ( lib "racket" ) ; Use "schematics" ' s "random.plt" 1.0, file "random.rkt" : ( require ( planet schematics/random:1/random ) ) ( display ( random-gaussian ) ) )
> > > ( require ' m )
> > 0.9050686838895684
> > ```
>
>

>
> As with other forms, an implementation file ending with ".ss" can be substituted automatically if no implementation file ending with ".rkt" exists.

> > |                                                                                |
> > |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > | ([planet](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._planet%2529%2529&version=8.18.0.13) package-string) |
>
> Like the symbol form of a [planet](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._planet%2529%2529&version=8.18.0.13), but using a string instead of an identifier. Also, the package-string can end with a file suffix, in which case ".rkt" is not added.
>
> As with other forms, an ".ss" extension is converted to ".rkt", while an implementation file ending with ".ss" can be substituted automatically if no implementation file ending with ".rkt" exists.

> > <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td>([planet](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._planet%2529%2529&version=8.18.0.13) rel-string (user-string pkg-string vers ...))</td></tr><tr><td> </td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><tbody><tr><td style="text-align: right;" data-valign="baseline">vers</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: center;" data-valign="baseline">=</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline">nat</td></tr><tr><td style="text-align: right;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: center;" data-valign="baseline">|</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline">(nat nat)</td></tr><tr><td style="text-align: right;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: center;" data-valign="baseline">|</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline">([=](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._%7E3d%2529%2529&version=8.18.0.13) nat)</td></tr><tr><td style="text-align: right;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: center;" data-valign="baseline">|</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline">([+](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._%252B%2529%2529&version=8.18.0.13) nat)</td></tr><tr><td style="text-align: right;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: center;" data-valign="baseline">|</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline">([-](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._-%2529%2529&version=8.18.0.13) nat)</td></tr></tbody></table></td></tr></tbody></table>
>
> A more general form to access a library from the PLaneT server. In this general form, a PLaneT reference starts like a [lib](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._lib%2529%2529&version=8.18.0.13) reference with a relative path, but the path is followed by information about the producer, package, and version of the library. The specified package is downloaded and installed on demand.
>
> The verses specify a constraint on the acceptable version of the package, where a version number is a sequence of non-negative integers, and the constraints determine the allowable values for each element in the sequence. If no constraint is provided for a particular element, then any version is allowed; in particular, omitting all verses means that any version is acceptable. Specifying at least one vers is strongly recommended.
>
> For a version constraint, a plain nat is the same as ([+](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._%252B%2529%2529&version=8.18.0.13) nat), which matches nat or higher for the corresponding element of the version number. A (start-nat end-nat) matches any number in the range start-nat to end-nat, inclusive. A ([=](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._%7E3d%2529%2529&version=8.18.0.13) nat) matches only exactly nat. A ([-](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._-%2529%2529&version=8.18.0.13) nat) matches nat or lower.
>
>

>
> Examples:
>
>

>
>

>
> > ```racket
> > > ( module m ( lib "racket" ) ( require ( planet "random.rkt" ( "schematics" "random.plt" 1 0 ) ) ) ( display ( random-gaussian ) ) )
> > > ( require ' m )
> > 0.9050686838895684
> > ```
>
>

>
> The automatic ".ss" and ".rkt" conversions apply as with other forms.

> > |                                                                                |
> > |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > | ([file](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._file%2529%2529&version=8.18.0.13) string) |
>
> Refers to a file, where string is a relative or absolute path using the current platform’s conventions. This form is not portable, and it should not be used when a plain, portable rel-string suffices.
>
> The automatic ".ss" and ".rkt" conversions apply as with other forms.

> > <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td>([submod](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._submod%2529%2529&version=8.18.0.13) base element ...+)</td></tr><tr><td> </td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><tbody><tr><td style="text-align: right;" data-valign="baseline">base</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: center;" data-valign="baseline">=</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline">module-path</td></tr><tr><td style="text-align: right;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: center;" data-valign="baseline">|</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline">"."</td></tr><tr><td style="text-align: right;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: center;" data-valign="baseline">|</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline">".."</td></tr><tr><td style="text-align: right;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: center;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline"> </td></tr><tr><td style="text-align: right;" data-valign="baseline">element</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: center;" data-valign="baseline">=</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline">id</td></tr><tr><td style="text-align: right;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: center;" data-valign="baseline">|</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline">".."</td></tr></tbody></table></td></tr></tbody></table>
>
> Refers to a submodule of base. The sequence of elements within [submod](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._submod%2529%2529&version=8.18.0.13) specify a path of submodule names to reach the final submodule.
>
>

>
> Examples:
>
>

>
>

>
> > ```racket
> > > ( module zoo racket ( module monkey-house racket ( provide monkey ) ( define monkey "Curious George" ) ) )
> > > ( require ( submod ' zoo monkey-house ) )
> > > monkey
> > "Curious George"
> > ```
>
>

>
> Using "." as base within [submod](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._submod%2529%2529&version=8.18.0.13) stands for the enclosing module. Using ".." as base is equivalent to using "." followed by an extra "..". When a path of the form ([quote](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=quote.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._quote%2529%2529&version=8.18.0.13) id) refers to a submodule, it is equivalent to ([submod](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._submod%2529%2529&version=8.18.0.13) "." id).
>
> Using ".." as an element cancels one submodule step, effectively referring to the enclosing module. For example, ([submod](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._submod%2529%2529&version=8.18.0.13) "..") refers to the enclosing module of the submodule in which the path appears.
>
>

>
> Examples:
>
>

>
>

>
> > ```racket
> > > ( module zoo racket ( module monkey-house racket ( provide monkey ) ( define monkey "Curious George" ) ) ( module crocodile-house racket ( require ( submod ".." monkey-house ) ) ( provide dinner ) ( define dinner monkey ) ) )
> > > ( require ( submod ' zoo crocodile-house ) )
> > > dinner
> > "Curious George"
> > ```
>
>

------------------------------------------------------------------------

# 6.4 Imports: require

### 6.4 Imports: [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13)

The [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) form imports from another module. A [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) form can appear within a module, in which case it introduces bindings from the specified module into the importing module. A [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) form can also appear at the top level, in which case it both imports bindings and instantiates the specified module; that is, it evaluates the body definitions and expressions of the specified module, if they have not been evaluated already.

A single [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) can specify multiple imports at once:

> > |                                                                                |
> > |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > | ([require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) require-spec ...) |

Specifying multiple require-specs in a single [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) is essentially the same as using multiple [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13)s, each with a single require-spec. The difference is minor, and confined to the top-level: a single [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) can import a given identifier at most once, whereas a separate [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) can replace the bindings of a previous [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) (both only at the top level, outside of a module).

The allowed shape of a require-spec is defined recursively:

> > > |             |
> > > |-------------|
> > > | module-path |
> >
> > In its simplest form, a require-spec is a module-path (as defined in the previous section, [Module Paths](module-paths.html)). In this case, the bindings introduced by [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) are determined by [provide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._provide%2529%2529&version=8.18.0.13) declarations within each module referenced by each module-path.
> >
> >

> >
> > Examples:
> >
> >

> >
> >

> >
> > > ```racket
> > > > ( module m racket ( provide color ) ( define color "blue" ) )
> > > > ( module n racket ( provide size ) ( define size 17 ) )
> > > > ( require ' m ' n )
> > > > ( list color size )
> > > '("blue" 17)
> > > ```
> >
> >

> > > <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td>([only-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._only-in%2529%2529&version=8.18.0.13) require-spec id-maybe-renamed ...)</td></tr><tr><td> </td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><tbody><tr><td style="text-align: right;" data-valign="baseline">id-maybe-renamed</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: center;" data-valign="baseline">=</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline">id</td></tr><tr><td style="text-align: right;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: center;" data-valign="baseline">|</td><td style="text-align: left;" data-valign="baseline"> </td><td style="text-align: left;" data-valign="baseline">[orig-id bind-id]</td></tr></tbody></table></td></tr></tbody></table>
> >
> > An [only-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._only-in%2529%2529&version=8.18.0.13) form limits the set of bindings that would be introduced by a base require-spec. Also, [only-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._only-in%2529%2529&version=8.18.0.13) optionally renames each binding that is preserved: in a \[orig-id bind-id\] form, the orig-id refers to a binding implied by require-spec, and bind-id is the name that will be bound in the importing context instead of orig-id.
> >
> >

> >
> > Examples:
> >
> >

> >
> >

> >
> > > ```racket
> > > > ( module m ( lib "racket" ) ( provide tastes-great? less-filling? ) ( define tastes-great? #t ) ( define less-filling? #t ) )
> > > > ( require ( only-in ' m tastes-great? ) )
> > > > tastes-great?
> > > #t
> > > > less-filling?
> > > less-filling?: undefined;
> > > cannot reference an identifier before its definition
> > > in module: top-level
> > > > ( require ( only-in ' m [ less-filling? lite? ] ) )
> > > > lite?
> > > #t
> > > ```
> >
> >

> > > |                                                                                |
> > > |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > > | ([except-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._except-in%2529%2529&version=8.18.0.13) require-spec id ...) |
> >
> > This form is the complement of [only-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._only-in%2529%2529&version=8.18.0.13): it excludes specific bindings from the set specified by require-spec.

> > > |                                                                                |
> > > |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > > | ([rename-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._rename-in%2529%2529&version=8.18.0.13) require-spec \[orig-id bind-id\] ...) |
> >
> > This form supports renaming like [only-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._only-in%2529%2529&version=8.18.0.13), but leaving alone identifiers from require-spec that are not mentioned as an orig-id.

> > > |                                                                                |
> > > |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > > | ([prefix-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._prefix-in%2529%2529&version=8.18.0.13) prefix-id require-spec) |
> >
> > This is a shorthand for renaming, where prefix-id is added to the front of each identifier specified by require-spec.

The [only-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._only-in%2529%2529&version=8.18.0.13), [except-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._except-in%2529%2529&version=8.18.0.13), [rename-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._rename-in%2529%2529&version=8.18.0.13), and [prefix-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._prefix-in%2529%2529&version=8.18.0.13) forms can be nested to implement more complex manipulations of imported bindings. For example,

> ([require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) ([prefix-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._prefix-in%2529%2529&version=8.18.0.13) m: ([except-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._except-in%2529%2529&version=8.18.0.13) 'm ghost)))

imports all bindings that m exports, except for the ghost binding, and with local names that are prefixed with m:.

Equivalently, the [prefix-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._prefix-in%2529%2529&version=8.18.0.13) could be applied before [except-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._except-in%2529%2529&version=8.18.0.13), as long as the omission with [except-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._except-in%2529%2529&version=8.18.0.13) is specified using the m: prefix:

> ([require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) ([except-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._except-in%2529%2529&version=8.18.0.13) ([prefix-in](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._prefix-in%2529%2529&version=8.18.0.13) m: 'm) m:ghost))

------------------------------------------------------------------------

# 6.5 Exports: provide

### 6.5 Exports: [provide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._provide%2529%2529&version=8.18.0.13)

By default, all of a module’s definitions are private to the module. The [provide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._provide%2529%2529&version=8.18.0.13) form specifies definitions to be made available where the module is [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13)d.

> > |                                                                                |
> > |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > | ([provide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._provide%2529%2529&version=8.18.0.13) provide-spec ...) |

A [provide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._provide%2529%2529&version=8.18.0.13) form can only appear at module level (i.e., in the immediate body of a [module](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._module%2529%2529&version=8.18.0.13)). Specifying multiple provide-specs in a single [provide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._provide%2529%2529&version=8.18.0.13) is exactly the same as using multiple [provide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._provide%2529%2529&version=8.18.0.13)s each with a single provide-spec.

Each identifier can be exported at most once from a module across all [provide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._provide%2529%2529&version=8.18.0.13)s within the module. More precisely, the external name for each export must be distinct; the same internal binding can be exported multiple times with different external names.

The allowed shape of a provide-spec is defined recursively:

> > > |            |
> > > |------------|
> > > | identifier |
> >
> > In its simplest form, a provide-spec indicates a binding within its module to be exported. The binding can be from either a local definition, or from an import.

> > > |                                                                                |
> > > |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > > | ([rename-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._rename-out%2529%2529&version=8.18.0.13) \[orig-id export-id\] ...) |
> >
> > A [rename-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._rename-out%2529%2529&version=8.18.0.13) form is similar to just specifying an identifier, but the exported binding orig-id is given a different name, export-id, to importing modules.

> > > |                                                                                |
> > > |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > > | ([struct-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._struct-out%2529%2529&version=8.18.0.13) struct-id) |
> >
> > A [struct-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._struct-out%2529%2529&version=8.18.0.13) form exports the bindings created by ([struct](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=define-struct.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._struct%2529%2529&version=8.18.0.13) struct-id ....).
> >
> > > > > See [Programmer-Defined Datatypes](define-struct.html) for information on [define-struct](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=define-struct.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._define-struct%2529%2529&version=8.18.0.13).

> > > |                                                                                |
> > > |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > > | ([all-defined-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._all-defined-out%2529%2529&version=8.18.0.13)) |
> >
> > The [all-defined-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._all-defined-out%2529%2529&version=8.18.0.13) shorthand exports all bindings that are defined within the exporting module (as opposed to imported).
> >
> > Use of the [all-defined-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._all-defined-out%2529%2529&version=8.18.0.13) shorthand is generally discouraged, because it makes less clear the actual exports for a module, and because Racket programmers get into the habit of thinking that definitions can be added freely to a module without affecting its public interface (which is not the case when [all-defined-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._all-defined-out%2529%2529&version=8.18.0.13) is used).

> > > |                                                                                |
> > > |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > > | ([all-from-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._all-from-out%2529%2529&version=8.18.0.13) module-path) |
> >
> > The [all-from-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._all-from-out%2529%2529&version=8.18.0.13) shorthand exports all bindings in the module that were imported using a require-spec that is based on module-path.
> >
> > Although different module-paths could refer to the same file-based module, re-exporting with [all-from-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._all-from-out%2529%2529&version=8.18.0.13) is based specifically on the module-path reference, and not the module that is actually referenced.

> > > |                                                                                |
> > > |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > > | ([except-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._except-out%2529%2529&version=8.18.0.13) provide-spec id ...) |
> >
> > Like provide-spec, but omitting the export of each id, where id is the external name of the binding to omit.

> > > |                                                                                |
> > > |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
> > > | ([prefix-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._prefix-out%2529%2529&version=8.18.0.13) prefix-id provide-spec) |
> >
> > Like provide-spec, but adding prefix-id to the beginning of the external name for each exported binding.

------------------------------------------------------------------------

# 6.6 Assignment and Redefinition

### 6.6 Assignment and Redefinition

The use of [set!](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=set_.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._set%2521%2529%2529&version=8.18.0.13) on variables defined within a module is limited to the body of the defining module. That is, a module is allowed to change the value of its own definitions, and such changes are visible to importing modules. However, an importing context is not allowed to change the value of an imported binding.

Examples:

> ```racket
> > ( module m racket ( provide counter increment! ) ( define counter 0 ) ( define ( increment! ) ( set! counter ( add1 counter ) ) ) )
> > ( require ' m )
> > counter
> 0
> > ( increment! )
> > counter
> 1
> > ( set! counter -1 )
> set!: cannot mutate module-required identifier
> at: counter
> in: (set! counter -1)
> ```

As the above example illustrates, a module can always grant others the ability to change its exports by providing a mutator function, such as increment!.

The prohibition on assignment of imported variables helps support modular reasoning about programs. For example, in the module,

> ```racket
> ( module m racket
> ( provide rx:fish fishy-string? )
> ( define rx:fish #rx"fish" )
> ( define ( fishy-string? s )
> ( regexp-match? rx:fish s ) ) )
> ```

the function fishy-string? will always match strings that contain “fish”, no matter how other modules use the rx:fish binding. For essentially the same reason that it helps programmers, the prohibition on assignment to imports also allows many programs to be executed more efficiently.

Along the same lines, when a module contains no [set!](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=set_.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._set%2521%2529%2529&version=8.18.0.13) of a particular identifier that is defined within the module, then the identifier is considered a constant that cannot be changed—not even by re-declaring the module.

Consequently, re-declaration of a module is not generally allowed. For file-based modules, simply changing the file does not lead to a re-declaration in any case, because file-based modules are loaded on demand, and the previously loaded declarations satisfy future requests. It is possible to use Racket’s reflection support to re-declare a module, however, and non-file modules can be re-declared in the [REPL](intro.html#%28tech._repl%29); in such cases, the re-declaration may fail if it involves the re-definition of a previously constant binding.

> ```racket
> > ( module m racket ( define pie 3.141597 ) )
> > ( require ' m )
> > ( module m racket ( define pie 3 ) )
> define-values: assignment disallowed;
> cannot re-define a constant
> constant: pie
> in module:'m
> ```

For exploration and debugging purposes, the Racket reflective layer provides a [compile-enforce-module-constants](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=eval.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._compile-enforce-module-constants%2529%2529&version=8.18.0.13) parameter to disable the enforcement of constants.

> ```racket
> > ( compile-enforce-module-constants #f )
> > ( module m2 racket ( provide pie ) ( define pie 3.141597 ) )
> > ( require ' m2 )
> > ( module m2 racket ( provide pie ) ( define pie 3 ) )
> > ( compile-enforce-module-constants #t )
> > pie
> 3
> ```

------------------------------------------------------------------------

# 6.7 Modules and Macros

### 6.7 Modules and Macros

Racket’s module system cooperates closely with Racket’s [macro](macros.html#%28tech._macro%29) system for adding new syntactic forms to Racket. For example, in the same way that importing [racket/base](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=index.html&version=8.18.0.13) introduces syntax for [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) and [lambda](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=lambda.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._lambda%2529%2529&version=8.18.0.13), importing other modules can introduce new syntactic forms (in addition to more traditional kinds of imports, such as functions or constants).

We introduce macros in more detail later, in [Macros](macros.html), but here’s a simple example of a module that defines a pattern-based macro:

> ```racket
> ( module noisy racket
> ( provide define-noisy )
> ( define-syntax-rule ( define-noisy ( id arg ... ) body )
> ( define ( id arg ... )
> ( show-arguments ' id ( list arg ... ) )
> body ) )
> ( define ( show-arguments name args )
> ( printf "calling ~s with arguments ~e" name args ) ) )
> ```

The define-noisy binding provided by this module is a [macro](macros.html#%28tech._macro%29) that acts like [define](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=define.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._define%2529%2529&version=8.18.0.13) for a function, but it causes each call to the function to print the arguments that are provided to the function:

> ```racket
> > ( require ' noisy )
> > ( define-noisy ( f x y ) ( + x y ) )
> > ( f 1 2 )
> calling f with arguments '(1 2)
> 3
> ```

Roughly, the define-noisy form works by replacing

> ```racket
> ( define-noisy ( f x y )
> ( + x y ) )
> ```

with

> ```racket
> ( define ( f x y )
> ( show-arguments ' f ( list x y ) )
> ( + x y ) )
> ```

Since show-arguments isn’t provided by the noisy module, however, this literal textual replacement is not quite right. The actual replacement correctly tracks the origin of identifiers like show-arguments, so they can refer to other definitions in the place where the macro is defined—even if those identifiers are not available at the place where the macro is used.

There’s more to the macro and module interaction than identifier binding. The [define-syntax-rule](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=stx-patterns.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fmisc..rkt%2529._define-syntax-rule%2529%2529&version=8.18.0.13) form is itself a macro, and it expands to compile-time code that implements the transformation from define-noisy into [define](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=define.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._define%2529%2529&version=8.18.0.13). The module system keeps track of which code needs to run at compile and which needs to run normally, as explained more in [Compile and Run-Time Phases](stx-phases.html) and [Module Instantiations and Visits](macro-module.html).

------------------------------------------------------------------------

# 6.8 Protected Exports

### 6.8 Protected Exports

Sometimes, a module needs to export bindings to other modules that are at the same trust level as the exporting module, while at the same time preventing access from untrusted modules. Such exports should use the [protect-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._protect-out%2529%2529&version=8.18.0.13) form in [provide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._provide%2529%2529&version=8.18.0.13). For example, [ffi/unsafe](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=foreign&rel=index.html&version=8.18.0.13) exports all of its unsafe bindings as protected in this sense.

Levels of trust are implemented with [code inspectors](code-inspectors_protect.html#%28tech._code._inspector%29) (see [Code Inspectors for Trusted and Untrusted Code](code-inspectors_protect.html)). Only modules loaded with an equally strong code inspector as an exporting module can use protected bindings from the exporting module. Operations like [dynamic-require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=Module_Names_and_Loading.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._dynamic-require%2529%2529&version=8.18.0.13) are granted access depending on the current code inspector as determined by [current-code-inspector](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=modprotect.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._current-code-inspector%2529%2529&version=8.18.0.13).

When a module re-exports a protected binding, it does not need to use [protect-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._protect-out%2529%2529&version=8.18.0.13) again. Access is always determined by the code inspector of the module that originally defines a protected binding. When using a protected binding within a module, take care to either provide new bindings from the module with [protect-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._protect-out%2529%2529&version=8.18.0.13) or ensure that no provided bindings expose functionality that was meant to be protected in the first place.

------------------------------------------------------------------------

# 7 Contracts

## 7 Contracts

This chapter provides a gentle introduction to Racket’s contract system.

> > > [Contracts](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=contracts.html&version=8.18.0.13) in [The Racket Reference](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=index.html&version=8.18.0.13) provides more on contracts.

|                                                                                |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|     [7.1 Contracts and Boundaries](contract-boundaries.html)                                                                             |
|       [7.1.1 Contract Violations](contract-boundaries.html#%28part._contracts-amount0%29)                                                |
|       [7.1.2 Experimenting with Contracts and Modules](contract-boundaries.html#%28part._.Experimenting_with_.Contracts_and_.Modules%29) |
|       [7.1.3 Experimenting with Nested Contract Boundaries](contract-boundaries.html#%28part._contracts-intro-nested%29)                 |
|     [7.2 Simple Contracts on Functions](contract-func.html)                                                                              |
|       [7.2.1 Styles of ->](contract-func.html#%28part._.Styles_of_-_%29)                                                              |
|       [7.2.2 Using define/contract and ->](contract-func.html#%28part._simple-nested%29)                                              |
|       [7.2.3 any and any/c](contract-func.html#%28part._any_and_any_c%29)                                                                |
|       [7.2.4 Rolling Your Own Contracts](contract-func.html#%28part._contracts-own%29)                                                   |
|       [7.2.5 Contracts on Higher-order Functions](contract-func.html#%28part._.Contracts_on_.Higher-order_.Functions%29)                 |
|       [7.2.6 Contract Messages with “???”](contract-func.html#%28part._contracts-flat-named-contracts%29)                                |
|       [7.2.7 Dissecting a contract error message](contract-func.html#%28part._contracts-dissecting-contract-errors%29)                   |
|     [7.3 Contracts on Functions in General](contracts-general-functions.html)                                                            |
|       [7.3.1 Optional Arguments](contracts-general-functions.html#%28part._contracts-optional%29)                                        |
|       [7.3.2 Rest Arguments](contracts-general-functions.html#%28part._contracts-rest-args%29)                                           |
|       [7.3.3 Keyword Arguments](contracts-general-functions.html#%28part._contracts-keywords%29)                                         |
|       [7.3.4 Optional Keyword Arguments](contracts-general-functions.html#%28part._contracts-optional-keywords%29)                       |
|       [7.3.5 Contracts for case-lambda](contracts-general-functions.html#%28part._contracts-case-lambda%29)                              |
|       [7.3.6 Argument and Result Dependencies](contracts-general-functions.html#%28part._contracts-arrow-d%29)                           |
|       [7.3.7 Checking State Changes](contracts-general-functions.html#%28part._contracts-arrow-d-eval-order%29)                          |
|       [7.3.8 Multiple Result Values](contracts-general-functions.html#%28part._contracts-multiple%29)                                    |
|       [7.3.9 Fixed but Statically Unknown Arities](contracts-general-functions.html#%28part._contracts-no-domain%29)                     |
|     [7.4 Contracts: A Thorough Example](contracts-first.html)                                                                            |
|     [7.5 Contracts on Structures](contracts-struct.html)                                                                                |
|       [7.5.1 Guarantees for a Specific Value](contracts-struct.html#%28part._contracts-single-struct%29)                                 |
|       [7.5.2 Guarantees for All Values](contracts-struct.html#%28part._contracts-define-struct%29)                                       |
|       [7.5.3 Checking Properties of Data Structures](contracts-struct.html#%28part._contracts-lazy-contracts%29)                         |
|     [7.6 Abstract Contracts using #:exists and #:∃](contracts-exists.html)                                                               |
|     [7.7 Additional Examples](contracts-examples.html)                                                                                |
|       [7.7.1 A Customer-Manager Component](contracts-examples.html#%28part._.A_.Customer-.Manager_.Component%29)                         |
|       [7.7.2 A Parameteric (Simple) Stack](contracts-examples.html#%28part._.A_.Parameteric__.Simple__.Stack%29)                         |
|       [7.7.3 A Dictionary](contracts-examples.html#%28part._.A_.Dictionary%29)                                                           |
|       [7.7.4 A Queue](contracts-examples.html#%28part._.A_.Queue%29)                                                                     |
|     [7.8 Building New Contracts](Building_New_Contracts.html)                                                                            |
|       [7.8.1 Contract Struct Properties](Building_New_Contracts.html#%28part._.Contract_.Struct_.Properties%29)                          |
|       [7.8.2 With all the Bells and Whistles](Building_New_Contracts.html#%28part._.With_all_the_.Bells_and_.Whistles%29)                |
|     [7.9 Gotchas](contracts-gotchas.html)                                                                                |
|       [7.9.1 Contracts and eq?](contracts-gotchas.html#%28part._.Contracts_and_eq_%29)                                                   |
|       [7.9.2 Contract boundaries and define/contract](contracts-gotchas.html#%28part._contracts-gotcha-nested%29)                        |
|       [7.9.3 Exists Contracts and Predicates](contracts-gotchas.html#%28part._contracts-exists-gotcha%29)                                |
|       [7.9.4 Defining Recursive Contracts](contracts-gotchas.html#%28part._.Defining_.Recursive_.Contracts%29)                           |
|       [7.9.5 Mixing set! and contract-out](contracts-gotchas.html#%28part._.Mixing_set__and_contract-out%29)                             |

------------------------------------------------------------------------

# 7.1 Contracts and Boundaries

### 7.1 Contracts and Boundaries

Like a contract between two business partners, a software contract is an agreement between two parties. The agreement specifies obligations and guarantees for each “product” (or value) that is handed from one party to the other.

A contract thus establishes a boundary between the two parties. Whenever a value crosses this boundary, the contract monitoring system performs contract checks, making sure the partners abide by the established contract.

In this spirit, Racket encourages contracts mainly at module boundaries. Specifically, programmers may attach contracts to [provide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._provide%2529%2529&version=8.18.0.13) clauses and thus impose constraints and promises on the use of exported values. For example, the export specification

> ```racket
> #lang racket
> ( provide ( contract-out [ amount positive? ] ) )
> ( define amount ... )
> ```

promises to all clients of the above module that the value of amount will always be a positive number. The contract system monitors the module’s obligation carefully. Every time a client refers to amount, the monitor checks that the value of amount is indeed a positive number.

The contracts library is built into the Racket language, but if you wish to use racket/base, you can explicitly require the contracts library like this:

> ```racket
> #lang racket/base
> ( require racket/contract ) ; now we can write contracts
> ( provide ( contract-out [ amount positive? ] ) )
> ( define amount ... )
> ```

#### 7.1.1 Contract Violations

If we bind amount to a number that is not positive,

> ```racket
> #lang racket
> ( provide ( contract-out [ amount positive? ] ) )
> ( define amount 0 )
> ```

then, when the module is required, the monitoring system signals a violation of the contract and blames the module for breaking its promises.

An even bigger mistake would be to bind amount to a non-number value:

> ```racket
> #lang racket
> ( provide ( contract-out [ amount positive? ] ) )
> ( define amount ' amount )
> ```

In this case, the monitoring system will apply [positive?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._positive%7E3f%2529%2529&version=8.18.0.13) to a symbol, but [positive?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._positive%7E3f%2529%2529&version=8.18.0.13) reports an error, because its domain is only numbers. To make the contract capture our intentions for all Racket values, we can ensure that the value is both a number and is positive, combining the two contracts with [and/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._and%252Fc%2529%2529&version=8.18.0.13):

> ([provide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._provide%2529%2529&version=8.18.0.13) ([contract-out](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=attaching-contracts-to-values.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._contract-out%2529%2529&version=8.18.0.13) \[amount ([and/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._and%252Fc%2529%2529&version=8.18.0.13) [number?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._number%7E3f%2529%2529&version=8.18.0.13) [positive?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._positive%7E3f%2529%2529&version=8.18.0.13))\]))

#### 7.1.2 Experimenting with Contracts and Modules

All of the contracts and modules in this chapter (excluding those just following) are written using the standard #lang syntax for describing modules. Since modules serve as the boundary between parties in a contract, examples involve multiple modules.

To experiment with multiple modules within a single module or within DrRacket’s [definitions area](intro.html#%28tech._definitions._area%29), use Racket’s submodules. For example, try the example earlier in this section like this:

> ```racket
> #lang racket
> ( module+ server
> ( provide ( contract-out [ amount ( and/c number? positive? ) ] ) )
> ( define amount 150 ) )
> ( module+ main
> ( require ( submod ".." server ) )
> ( + amount 10 ) )
> ```

Each of the modules and their contracts are wrapped in parentheses with the [module+](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._module%252B%2529%2529&version=8.18.0.13) keyword at the front. The first form after [module](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=module.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._module%2529%2529&version=8.18.0.13) is the name of the module to be used in a subsequent [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) statement (where each reference through a [require](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=8.18.0.13) prefixes the name with "..").

#### 7.1.3 Experimenting with Nested Contract Boundaries

In many cases, it makes sense to attach contracts at module boundaries. It is often convenient, however, to be able to use contracts at a finer granularity than modules. The [define/contract](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=attaching-contracts-to-values.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fregion..rkt%2529._define%252Fcontract%2529%2529&version=8.18.0.13) form enables this kind of use:

> ```racket
> #lang racket
> ( define/contract amount
> ( and/c number? positive? )
> 150 )
> ( + amount 10 )
> ```

In this example, the [define/contract](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=attaching-contracts-to-values.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fregion..rkt%2529._define%252Fcontract%2529%2529&version=8.18.0.13) form establishes a contract boundary between the definition of amount and its surrounding context. In other words, the two parties here are the definition and the module that contains it.

Forms that create these nested contract boundaries can sometimes be subtle to use because they may have unexpected performance implications or blame a party that may seem unintuitive. These subtleties are explained in [Using define/contract and ->](contract-func.html#%28part._simple-nested%29) and [Contract boundaries and define/contract](contracts-gotchas.html#%28part._contracts-gotcha-nested%29).

------------------------------------------------------------------------

# 7.2 Simple Contracts on Functions

### 7.2 Simple Contracts on Functions

A mathematical function has a domain and a range. The domain indicates the kind of values that the function can accept as arguments, and the range indicates the kind of values that it produces. The conventional notation for describing a function with its domain and range is

> f : A [->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) B

where A is the domain of the function and B is the range.

Functions in a programming language have domains and ranges, too, and a contract can ensure that a function receives only values in its domain and produces only values in its range. A [->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) creates such a contract for a function. The forms after a [->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) specify contracts for the domains and finally a contract for the range.

Here is a module that might represent a bank account:

> ```racket
> #lang racket
> ( provide ( contract-out
> [ deposit ( -> number? any ) ]
> [ balance ( -> number? ) ] ) )
> ( define amount 0 )
> ( define ( deposit a ) ( set! amount ( + amount a ) ) )
> ( define ( balance ) amount )
> ```

The module exports two functions:

-   deposit, which accepts a number and returns some value that is not specified in the contract, and

-   balance, which returns a number indicating the current balance of the account.

When a module exports a function, it establishes two channels of communication between itself as a “server” and the “client” module that imports the function. If the client module calls the function, it sends a value into the server module. Conversely, if such a function call ends and the function returns a value, the server module sends a value back to the client module. This client–server distinction is important, because when something goes wrong, one or the other of the parties is to blame.

If a client module were to apply deposit to 'millions, it would violate the contract. The contract-monitoring system would catch this violation and blame the client for breaking the contract with the above module. In contrast, if the balance function were to return 'broke, the contract-monitoring system would blame the server module.

A [->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) by itself is not a contract; it is a contract combinator, which combines other contracts to form a contract.

#### 7.2.1 Styles of [->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13)

If you are used to mathematical functions, you may prefer a contract arrow to appear between the domain and the range of a function, not at the beginning. If you have read [How to Design Programs](https://htdp.org), you have seen this many times. Indeed, you may have seen contracts such as these in other people’s code:

> ```racket
> ( provide ( contract-out
> [ deposit ( number? . -> . any ) ] ) )
> ```

If a Racket S-expression contains two dots with a symbol in the middle, the reader re-arranges the S-expression and place the symbol at the front, as described in [Lists and Racket Syntax](Pairs__Lists__and_Racket_Syntax.html#%28part._lists-and-syntax%29). Thus,

> ([number?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._number%7E3f%2529%2529&version=8.18.0.13) . [->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) . [any](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%2529%2529&version=8.18.0.13))

is just another way of writing

> ([->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) [number?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._number%7E3f%2529%2529&version=8.18.0.13) [any](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%2529%2529&version=8.18.0.13))

#### 7.2.2 Using [define/contract](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=attaching-contracts-to-values.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fregion..rkt%2529._define%252Fcontract%2529%2529&version=8.18.0.13) and [->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13)

The [define/contract](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=attaching-contracts-to-values.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fregion..rkt%2529._define%252Fcontract%2529%2529&version=8.18.0.13) form introduced in [Experimenting with Nested Contract Boundaries](contract-boundaries.html#%28part._contracts-intro-nested%29) can also be used to define functions that come with a contract. For example,

> ```racket
> ( define/contract ( deposit amount )
> ( -> number? any )
> ; implementation goes here
> .... )
> ```

which defines the deposit function with the contract from earlier. Note that this has two potentially important impacts on the use of deposit:

1.  The contract will be checked on any call to deposit that is outside of the definition of deposit – even those inside the module in which it is defined. Because there may be many calls inside the module, this checking may cause the contract to be checked too often, which could lead to a performance degradation. This is especially true if the function is called repeatedly from a loop.

2.  In some situations, a function may be written to accept a more lax set of inputs when called by other code in the same module. For such use cases, the contract boundary established by [define/contract](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=attaching-contracts-to-values.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fregion..rkt%2529._define%252Fcontract%2529%2529&version=8.18.0.13) is too strict.

#### 7.2.3 [any](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%2529%2529&version=8.18.0.13) and [any/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%252Fc%2529%2529&version=8.18.0.13)

The [any](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%2529%2529&version=8.18.0.13) contract used for deposit matches any kind of result, and it can only be used in the range position of a function contract. Instead of [any](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%2529%2529&version=8.18.0.13) above, we could use the more specific contract [void?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=void.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._void%7E3f%2529%2529&version=8.18.0.13), which says that the function will always return the ([void](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=void.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._void%2529%2529&version=8.18.0.13)) value. The [void?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=void.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._void%7E3f%2529%2529&version=8.18.0.13) contract, however, would require the contract monitoring system to check the return value every time the function is called, even though the “client” module can’t do much with the value. In contrast, [any](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%2529%2529&version=8.18.0.13) tells the monitoring system not to check the return value, it tells a potential client that the “server” module makes no promises at all about the function’s return value, even whether it is a single value or multiple values.

The [any/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%252Fc%2529%2529&version=8.18.0.13) contract is similar to [any](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%2529%2529&version=8.18.0.13), in that it makes no demands on a value. Unlike [any](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%2529%2529&version=8.18.0.13), [any/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%252Fc%2529%2529&version=8.18.0.13) indicates a single value, and it is suitable for use as an argument contract. Using [any/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%252Fc%2529%2529&version=8.18.0.13) as a range contract imposes a check that the function produces a single value. That is,

> ([->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) [integer?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._integer%7E3f%2529%2529&version=8.18.0.13) [any](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%2529%2529&version=8.18.0.13))

describes a function that accepts an integer and returns any number of values, while

> ([->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) [integer?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._integer%7E3f%2529%2529&version=8.18.0.13) [any/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%252Fc%2529%2529&version=8.18.0.13))

describes a function that accepts an integer and produces a single result (but does not say anything more about the result). The function

> ([define](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=define.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._define%2529%2529&version=8.18.0.13) (f x) ([values](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=values.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._values%2529%2529&version=8.18.0.13) ([+](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._%252B%2529%2529&version=8.18.0.13) x 1) ([-](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._-%2529%2529&version=8.18.0.13) x 1)))

matches ([->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) [integer?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._integer%7E3f%2529%2529&version=8.18.0.13) [any](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%2529%2529&version=8.18.0.13)), but not ([->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) [integer?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._integer%7E3f%2529%2529&version=8.18.0.13) [any/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%252Fc%2529%2529&version=8.18.0.13)).

Use [any/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%252Fc%2529%2529&version=8.18.0.13) as a result contract when it is particularly important to promise a single result from a function. Use [any](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%2529%2529&version=8.18.0.13) when you want to promise as little as possible (and incur as little checking as possible) for a function’s result.

#### 7.2.4 Rolling Your Own Contracts

The deposit function adds the given number to the value of amount. While the function’s contract prevents clients from applying it to non-numbers, the contract still allows them to apply the function to complex numbers, negative numbers, or inexact numbers, none of which sensibly represent amounts of money.

The contract system allows programmers to define their own contracts as functions:

> ```racket
> #lang racket
> ( define ( amount? a )
> ( and ( number? a ) ( integer? a ) ( exact? a ) ( >= a 0 ) ) )
> ( provide ( contract-out
> ; an amount is a natural number of cents
> ; is the given number an amount?
> [ deposit ( -> amount? any ) ]
> [ amount? ( -> any/c boolean? ) ]
> [ balance ( -> amount? ) ] ) )
> ( define amount 0 )
> ( define ( deposit a ) ( set! amount ( + amount a ) ) )
> ( define ( balance ) amount )
> ```

This module defines an amount? function and uses it as a contract within [->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) contracts. When a client calls the deposit function as exported with the contract ([->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) amount? [any](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._any%2529%2529&version=8.18.0.13)), it must supply an exact, nonnegative integer, otherwise the amount? function applied to the argument will return #f, which will cause the contract-monitoring system to blame the client. Similarly, the server module must provide an exact, nonnegative integer as the result of balance to remain blameless.

Of course, it makes no sense to restrict a channel of communication to values that the client doesn’t understand. Therefore the module also exports the amount? predicate itself, with a contract saying that it accepts an arbitrary value and returns a boolean.

In this case, we could also have used [natural-number/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._natural-number%252Fc%2529%2529&version=8.18.0.13) in place of amount?, since it implies exactly the same check:

> ```racket
> ( provide ( contract-out
> [ deposit ( -> natural-number/c any ) ]
> [ balance ( -> natural-number/c ) ] ) )
> ```

Every function that accepts one argument can be treated as a predicate and thus used as a contract. For combining existing checks into a new one, however, contract combinators such as [and/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._and%252Fc%2529%2529&version=8.18.0.13) and [or/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._or%252Fc%2529%2529&version=8.18.0.13) are often useful. For example, here is yet another way to write the contracts above:

> ```racket
> ( define amount/c
> ( and/c number? integer? exact? ( or/c positive? zero? ) ) )
> ( provide ( contract-out
> [ deposit ( -> amount/c any ) ]
> [ balance ( -> amount/c ) ] ) )
> ```

Other values also serve double duty as contracts. For example, if a function accepts a number or #f, ([or/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._or%252Fc%2529%2529&version=8.18.0.13) [number?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._number%7E3f%2529%2529&version=8.18.0.13) #f) suffices. Similarly, the amount/c contract could have been written with a 0 in place of [zero?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._zero%7E3f%2529%2529&version=8.18.0.13). If you use a regular expression as a contract, the contract accepts strings and byte strings that match the regular expression.

Naturally, you can mix your own contract-implementing functions with combinators like [and/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._and%252Fc%2529%2529&version=8.18.0.13). Here is a module for creating strings from banking records:

> ```racket
> #lang racket
> ( define ( has-decimal? str )
> ( define L ( string-length str ) )
> ( and ( >= L 3 )
> ( char=? #\. ( string-ref str ( - L 3 ) ) ) ) )
> ( provide ( contract-out
> ; convert a random number to a string
> [ format-number ( -> number? string? ) ]
> ; convert an amount into a string with a decimal
> ; point, as in an amount of US currency
> [ format-nat ( -> natural-number/c
> ( and/c string? has-decimal? ) ) ] ) )
> ```

The contract of the exported function format-number specifies that the function consumes a number and produces a string. The contract of the exported function format-nat is more interesting than the one of format-number. It consumes only natural numbers. Its range contract promises a string that has a . in the third position from the right.

If we want to strengthen the promise of the range contract for format-nat so that it admits only strings with digits and a single dot, we could write it like this:

> ```racket
> #lang racket
> ( define ( digit-char? x )
> ( member x ' ( #\1 #\2 #\3 #\4 #\5 #\6 #\7 #\8 #\9 #\0 ) ) )
> ( define ( has-decimal? str )
> ( define L ( string-length str ) )
> ( and ( >= L 3 )
> ( char=? #\. ( string-ref str ( - L 3 ) ) ) ) )
> ( define ( is-decimal-string? str )
> ( define L ( string-length str ) )
> ( and ( has-decimal? str )
> ( andmap digit-char?
> ( string->list ( substring str 0 ( - L 3 ) ) ) )
> ( andmap digit-char?
> ( string->list ( substring str ( - L 2 ) L ) ) ) ) )
> ....
> ( provide ( contract-out
> ....
> ; convert an amount (natural number) of cents
> ; into a dollar-based string
> [ format-nat ( -> natural-number/c
> ( and/c string?
> is-decimal-string? ) ) ] ) )
> ```

Alternately, in this case, we could use a regular expression as a contract:

> ```racket
> #lang racket
> ( provide
> ( contract-out
> ....
> ; convert an amount (natural number) of cents
> ; into a dollar-based string
> [ format-nat ( -> natural-number/c
> ( and/c string? #rx"[0-9]*\\.[0-9][0-9]" ) ) ] ) )
> ```

#### 7.2.5 Contracts on Higher-order Functions

Function contracts are not just restricted to having simple predicates on their domains or ranges. Any of the contract combinators discussed here, including function contracts themselves, can be used as contracts on the arguments and results of a function.

For example,

> ([->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) [integer?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._integer%7E3f%2529%2529&version=8.18.0.13) ([->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) [integer?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._integer%7E3f%2529%2529&version=8.18.0.13) [integer?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._integer%7E3f%2529%2529&version=8.18.0.13)))

is a contract that describes a curried function. It matches functions that accept one argument and then return another function accepting a second argument before finally returning an integer. If a server exports a function make-adder with this contract, and if make-adder returns a value other than a function, then the server is to blame. If make-adder does return a function, but the resulting function is applied to a value other than an integer, then the client is to blame.

Similarly, the contract

> ([->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) ([->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) [integer?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._integer%7E3f%2529%2529&version=8.18.0.13) [integer?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._integer%7E3f%2529%2529&version=8.18.0.13)) [integer?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._integer%7E3f%2529%2529&version=8.18.0.13))

describes functions that accept other functions as its input. If a server exports a function twice with this contract and the twice is applied to a value other than a function of one argument, then the client is to blame. If twice is applied to a function of one argument and twice calls the given function on a value other than an integer, then the server is to blame.

#### 7.2.6 Contract Messages with “???”

You wrote your module. You added contracts. You put them into the interface so that client programmers have all the information from interfaces. It’s a piece of art:

> ```racket
> > ( module bank-server racket ( provide ( contract-out [ deposit ( -> ( λ ( x ) ( and ( number? x ) ( integer? x ) ( >= x 0 ) ) ) any ) ] ) ) ( define total 0 ) ( define ( deposit a ) ( set! total ( + a total ) ) ) )
> ```

Several clients used your module. Others used their modules in turn. And all of a sudden one of them sees this error message:

> ```racket
> > ( require ' bank-server )
> > ( deposit -1 0 )
> deposit: contract violation
> expected: ???
> given: -10
> in: the 1st argument of
> (-> ??? any)
> contract from: bank-server
> blaming: top-level
> (assuming the contract is correct)
> at: eval:2:0
> ```

What is the ??? doing there? Wouldn’t it be nice if we had a name for this class of data much like we have string, number, and so on?

For this situation, Racket provides flat named contracts. The use of “contract” in this term shows that contracts are first-class values. The “flat” means that the collection of data is a subset of the built-in atomic classes of data; they are described by a predicate that consumes all Racket values and produces a boolean. The “named” part says what we want to do, which is to name the contract so that error messages become intelligible:

> ```racket
> > ( module improved-bank-server racket ( provide ( contract-out [ deposit ( -> ( flat-named-contract ' amount ( λ ( x ) ( and ( number? x ) ( integer? x ) ( >= x 0 ) ) ) ) any ) ] ) ) ( define total 0 ) ( define ( deposit a ) ( set! total ( + a total ) ) ) )
> ```

With this little change, the error message becomes quite readable:

> ```racket
> > ( require ' improved-bank-server )
> > ( deposit -1 0 )
> deposit: contract violation
> expected: amount
> given: -10
> in: the 1st argument of
> (-> amount any)
> contract from: improved-bank-server
> blaming: top-level
> (assuming the contract is correct)
> at: eval:5:0
> ```

#### 7.2.7 Dissecting a contract error message

In general, each contract error message consists of six sections:

-

    a name for the function or method associated with the contract and either the phrase “contract violation” or “broke its contract” depending on whether the contract was violated by the client or the server; e.g. in the previous example:

    |                             |
    |-----------------------------|
    | deposit: contract violation |

-

    a description of the precise aspect of the contract that was violated,

    |                  |
    |------------------|
    | expected: amount |
    | given: -10       |

-

    the complete contract plus a path into it showing which aspect was violated,

    |                         |
    |-------------------------|
    | in: the 1st argument of |
    | (-> amount any)         |

-

    the module where the contract was put (or, more generally, the boundary that the contract mediates),

    |                                     |
    |-------------------------------------|
    | contract from: improved-bank-server |

-

    who was blamed,

    |                                    |
    |------------------------------------|
    | blaming: top-level                 |
    | (assuming the contract is correct) |

-

    and the source location where the contract appears.

    |              |
    |--------------|
    | at: eval:5:0 |

------------------------------------------------------------------------

# 7.3 Contracts on Functions in General

### 7.3 Contracts on Functions in General

The [->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) contract constructor works for functions that take a fixed number of arguments and where the result contract is independent of the input arguments. To support other kinds of functions, Racket supplies additional contract constructors, notably [->*](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%252A%2529%2529&version=8.18.0.13) and [->i](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3ei%2529%2529&version=8.18.0.13).

#### 7.3.1 Optional Arguments

Take a look at this excerpt from a string-processing module:

> ```racket
> #lang racket
> ( provide
> ( contract-out
> ; pad the given str left and right with
> ; the (optional) char so that it is centered
> [ string-pad-center ( -> * ( string? natural-number/c )
> ( char? )
> string? ) ] ) )
> ( define ( string-pad-center str width [ pad #\space ] )
> ( define field-width ( min width ( string-length str ) ) )
> ( define rmargin ( ceiling ( / ( - width field-width ) 2 ) ) )
> ( define lmargin ( floor ( / ( - width field-width ) 2 ) ) )
> ( string-append ( build-string lmargin ( λ ( x ) pad ) )
> str
> ( build-string rmargin ( λ ( x ) pad ) ) ) )
> ```

The module exports string-pad-center, a function that creates a string of a given width with the given string in the center. The default fill character is #\\space; if the client module wishes to use a different character, it may call string-pad-center with a third argument, a char, overwriting the default.

The function definition uses optional arguments, which is appropriate for this kind of functionality. The interesting point here is the formulation of the contract for the string-pad-center.

The contract combinator [->*](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%252A%2529%2529&version=8.18.0.13), demands several groups of contracts:

-   The first one is a parenthesized group of contracts for all required arguments. In this example, we see two: [string?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=strings.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._string%7E3f%2529%2529&version=8.18.0.13) and [natural-number/c](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fprivate%252Fmisc..rkt%2529._natural-number%252Fc%2529%2529&version=8.18.0.13).

-   The second one is a parenthesized group of contracts for all optional arguments: [char?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=characters.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._char%7E3f%2529%2529&version=8.18.0.13).

-   The last one is a single contract: the result of the function.

Note that if a default value does not satisfy a contract, you won’t get a contract error for this interface. If you can’t trust yourself to get the initial value right, you need to communicate the initial value across a boundary.

#### 7.3.2 Rest Arguments

The [max](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._max%2529%2529&version=8.18.0.13) operator consumes at least one real number, but it accepts any number of additional arguments. You can write other such functions using a [rest argument](lambda.html#%28tech._rest._argument%29), such as in max-abs:

> > > See [Declaring a Rest Argument](lambda.html#%28part._rest-args%29) for an introduction to rest arguments.

> ```racket
> ( define ( max-abs n . rst )
> ( foldr ( lambda ( n m ) ( max ( abs n ) m ) ) ( abs n ) rst ) )
> ```

To describe this function through a contract, you can use the [...](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=stx-patterns.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fstxcase-scheme..rkt%2529._......%2529%2529&version=8.18.0.13) feature of [->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13).

> ```racket
> ( provide
> ( contract-out
> [ max-abs ( -> real? real? ... real? ) ] ) )
> ```

Alternatively, you can use [->*](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%252A%2529%2529&version=8.18.0.13) with a #:rest keyword, which specifies a contract on a list of arguments after the required and optional arguments:

> ```racket
> ( provide
> ( contract-out
> [ max-abs ( -> * ( real? ) ( ) #:rest ( listof real? ) real? ) ] ) )
> ```

As always for [->*](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%252A%2529%2529&version=8.18.0.13), the contracts for the required arguments are enclosed in the first pair of parentheses, which in this case is a single real number. The empty pair of parenthesis indicates that there are no optional arguments (not counting the rest arguments). The contract for the rest argument follows #:rest; since all additional arguments must be real numbers, the list of rest arguments must satisfy the contract ([listof](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=data-structure-contracts.html%23%2528def._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._listof%2529%2529&version=8.18.0.13) [real?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._real%7E3f%2529%2529&version=8.18.0.13)).

#### 7.3.3 Keyword Arguments

It turns out that the [->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) contract constructor also contains support for keyword arguments. For example, consider this function, which creates a simple GUI and asks the user a yes-or-no question:

> > > See [Declaring Keyword Arguments](lambda.html#%28part._lambda-keywords%29) for an introduction to keyword arguments.

> ```racket
> #lang racket/gui
> ( define ( ask-yes-or-no-question question
> #:default answer
> #:title title
> #:width w
> #:height h )
> ( define d ( new dialog% [ label title ] [ width w ] [ height h ] ) )
> ( define msg ( new message% [ label question ] [ parent d ] ) )
> ( define ( yes ) ( set! answer #t ) ( send d show #f ) )
> ( define ( no ) ( set! answer #f ) ( send d show #f ) )
> ( define yes-b ( new button%
> [ label "Yes" ] [ parent d ]
> [ callback ( λ ( x y ) ( yes ) ) ]
> [ style ( if answer ' ( border ) ' ( ) ) ] ) )
> ( define no-b ( new button%
> [ label "No" ] [ parent d ]
> [ callback ( λ ( x y ) ( no ) ) ]
> [ style ( if answer ' ( ) ' ( border ) ) ] ) )
> ( send d show #t )
> answer )
> ( provide ( contract-out
> [ ask-yes-or-no-question
> ( -> string?
> #:default boolean?
> #:title string?
> #:width exact-integer?
> #:height exact-integer?
> boolean? ) ] ) )
> ```

> > > If you really want to ask a yes-or-no question via a GUI, you should use [message-box/custom](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=gui&rel=Windowing_Functions.html%23%2528def._%2528%2528lib._mred%252Fmain..rkt%2529._message-box%252Fcustom%2529%2529&version=8.18.0.13). For that matter, it’s usually better to provide buttons with more specific answers than “yes” and “no.”

The contract for ask-yes-or-no-question uses [->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13), and in the same way that [lambda](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=lambda.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._lambda%2529%2529&version=8.18.0.13) (or [define](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=define.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._define%2529%2529&version=8.18.0.13)-based functions) allows a keyword to precede a functions formal argument, [->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) allows a keyword to precede a function contract’s argument contract. In this case, the contract says that ask-yes-or-no-question must receive four keyword arguments, one for each of the keywords #:default, #:title, #:width, and #:height. As in a function definition, the order of the keywords in [->](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%2529%2529&version=8.18.0.13) relative to each other does not matter for clients of the function; only the relative order of argument contracts without keywords matters.

#### 7.3.4 Optional Keyword Arguments

Of course, many of the parameters in ask-yes-or-no-question (from the previous question) have reasonable defaults and should be made optional:

> ```racket
> ( define ( ask-yes-or-no-question question
> #:default answer
> #:title [ title "Yes or No?" ]
> #:width [ w 400 ]
> #:height [ h 200 ] )
> ... )
> ```

To specify this function’s contract, we need to use [->*](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=function-contracts.html%23%2528form._%2528%2528lib._racket%252Fcontract%252Fbase..rkt%2529._-%7E3e%252A%2529%2529&version=8.18.0.13) again. It supports keywords just as you might expect in both the optional and mandatory argument sections. In this case, we have the mandatory keyword #:default and optional keywords #:title, #:width, and #:height. So, we write the contract like this:

> ```racket
> ( provide ( contract-out
> [ ask-yes-or-no-question
> ( -> * ( string?
> #:default boolean? )
> ( #:title string?
> #:width exact-integer?
> #:height exact-integer? )
> boolean? ) ] ) )
> ```

That is, we put the mandatory keywords in the first section, and we put the optional ones in the second section.

#### 7.3.5 Contracts for [case-lambda](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=lambda.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._case-lambda%2529%2529&version=8.18.0.13)

A function defined with [case-lambda](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=lambda.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._case-lambda%2529%2529&version=8.18.0.13) might impose different constraints on its arguments depending on how many are provided. For example, a report-cost function might convert either a pair of numbers or a string into a new string:

> > > See [Arity-Sensitive Functions: case-lambda](lambda.html#%28part._case-lambda%29) for an introduction to [case-lambda](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=reference&rel=lambda.html%23%2528form._%2528%2528quote._%7E23%7E25kernel%2529._case-lambda%2529%2529&version=8.18.0.13).

> ```
(define report-cost
> ( case-lambda
> [ ( lo hi ) ( format "between $~a and $~a" lo hi ) ]
> [ ( desc ) ( format "~a of dollars" desc ) ] ) )

> ( report-cost 5 8 )
> "between $5 and $8"
> > ( report-cost "millions" )
> "millions of dollars"
```