typesetting/quad/qtest/mds/module-syntax.md

# 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 ....)`.