|
|
# Module Syntax
|
|
|
|
|
|
The `#lang` at the start of a module file begins a shorthand for a
|
|
|
`module` form, much like `'` is a shorthand for a `quote` form. Unlike
|
|
|
`'`, the `#lang` shorthand does not work well in a REPL, in part because
|
|
|
it must be terminated by an end-of-file, but also because the longhand
|
|
|
expansion of `#lang` depends on the name of the enclosing file.
|
|
|
|
|
|
## 1. The `module` Form
|
|
|
|
|
|
The longhand form of a module declaration, which works in a REPL as well
|
|
|
as a file, is
|
|
|
|
|
|
```racket
|
|
|
(module name-id initial-module-path
|
|
|
decl ...)
|
|
|
```
|
|
|
|
|
|
where the `name-id` is a name for the module, `initial-module-path` is
|
|
|
an initial import, and each `decl` is an import, export, definition, or
|
|
|
expression. In the case of a file, `name-id` normally matches the name
|
|
|
of the containing file, minus its directory path or file extension, but
|
|
|
`name-id` is ignored when the module is `require`d through its file’s
|
|
|
path.
|
|
|
|
|
|
The `initial-module-path` is needed because even the `require` form must
|
|
|
be imported for further use in the module body. In other words, the
|
|
|
`initial-module-path` import bootstraps the syntax that is available in
|
|
|
the body. The most commonly used `initial-module-path` is `racket`,
|
|
|
which supplies most of the bindings described in this guide, including
|
|
|
`require`, `define`, and `provide`. Another commonly used
|
|
|
`initial-module-path` is `racket/base`, which provides less
|
|
|
functionality, but still much of the most commonly needed functions and
|
|
|
syntax.
|
|
|
|
|
|
For example, the `"cake.rkt"` example of the previous section could be
|
|
|
written as
|
|
|
|
|
|
```racket
|
|
|
(module cake 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)))
|
|
|
```
|
|
|
|
|
|
Furthermore, this `module` form can be evaluated in a REPL to declare a
|
|
|
`cake` module that is not associated with any file. To refer to such an
|
|
|
unassociated module, quote the module name:
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
```racket
|
|
|
> (require 'cake)
|
|
|
> (print-cake 3)
|
|
|
...
|
|
|
.-|||-.
|
|
|
| |
|
|
|
---------
|
|
|
```
|
|
|
|
|
|
Declaring a module does not immediately evaluate the body definitions
|
|
|
and expressions of the module. The module must be explicitly `require`d
|
|
|
at the top level to trigger evaluation. After evaluation is triggered
|
|
|
once, later `require`s do not re-evaluate the module body.
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
```racket
|
|
|
> (module hi racket
|
|
|
(printf "Hello\n"))
|
|
|
> (require 'hi)
|
|
|
Hello
|
|
|
> (require 'hi)
|
|
|
```
|
|
|
|
|
|
## 2. The `#lang` Shorthand
|
|
|
|
|
|
The body of a `#lang` shorthand has no specific syntax, because the
|
|
|
syntax is determined by the language name that follows `#lang`.
|
|
|
|
|
|
In the case of `#lang` `racket`, the syntax is
|
|
|
|
|
|
```racket
|
|
|
#lang racket
|
|
|
decl ...
|
|
|
```
|
|
|
|
|
|
which reads the same as
|
|
|
|
|
|
```racket
|
|
|
(module name racket
|
|
|
decl ...)
|
|
|
```
|
|
|
|
|
|
where `name` is derived from the name of the file that contains the
|
|
|
`#lang` form.
|
|
|
|
|
|
The `#lang` `racket/base` form has the same syntax as `#lang` `racket`,
|
|
|
except that the longhand expansion uses `racket/base` instead of
|
|
|
`racket`. The `#lang` `scribble/manual` form, in contrast, has a
|
|
|
completely different syntax that doesn’t even look like Racket, and
|
|
|
which we do not attempt to describe in this guide.
|
|
|
|
|
|
Unless otherwise specified, a module that is documented as a “language”
|
|
|
using the `#lang` notation will expand to `module` in the same way as
|
|
|
`#lang` `racket`. The documented language name can be used directly with
|
|
|
`module` or `require`, too.
|
|
|
|
|
|
## 3. Submodules
|
|
|
|
|
|
A `module` form can be nested within a module, in which case the nested
|
|
|
`module` form declares a _submodule_. Submodules can be referenced
|
|
|
directly by the enclosing module using a quoted name. The following
|
|
|
example prints `"Tony"` by importing `tiger` from the `zoo` submodule:
|
|
|
|
|
|
`"park.rkt"`
|
|
|
```racket
|
|
|
#lang racket
|
|
|
|
|
|
(module zoo racket
|
|
|
(provide tiger)
|
|
|
(define tiger "Tony"))
|
|
|
|
|
|
(require 'zoo)
|
|
|
|
|
|
tiger
|
|
|
```
|
|
|
|
|
|
Running a module does not necessarily run its submodules. In the above
|
|
|
example, running `"park.rkt"` runs its submodule `zoo` only because the
|
|
|
`"park.rkt"` module `require`s the `zoo` submodule. Otherwise, a module
|
|
|
and each of its submodules can be run independently. Furthermore, if
|
|
|
`"park.rkt"` is compiled to a bytecode file \(via `raco make`\), then
|
|
|
the code for `"park.rkt"` or the code for `zoo` can be loaded
|
|
|
independently.
|
|
|
|
|
|
Submodules can be nested within submodules, and a submodule can be
|
|
|
referenced directly by a module other than its enclosing module by using
|
|
|
a submodule path.
|
|
|
|
|
|
A `module*` form is similar to a nested `module` form:
|
|
|
|
|
|
```racket
|
|
|
(module* name-id initial-module-path-or-#f
|
|
|
decl ...)
|
|
|
```
|
|
|
|
|
|
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 `require`d 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`.
|
|
|
|
|
|
## 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 `require`d 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+`:
|
|
|
|
|
|
```racket
|
|
|
(module+ name-id
|
|
|
decl ...)
|
|
|
```
|
|
|
|
|
|
A submodule declared with `module+` is like one declared with `module*`
|
|
|
using `#f` as its `initial-module-path`. In addition, multiple
|
|
|
`module+` forms can specify the same submodule name, in which case the
|
|
|
bodies of the `module+` forms are combined to create a single submodule.
|
|
|
|
|
|
The combining behavior of `module+` 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*`:
|
|
|
|
|
|
`"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+` instead of `module*` allows tests to be interleaved with
|
|
|
function definitions.
|
|
|
|
|
|
The combining behavior of `module+` is also sometimes helpful for a
|
|
|
`main` module. Even when combining is not needed, `(module+ main ....)`
|
|
|
is preferred as it is more readable than `(module* main #f ....)`.
|