Thank you for your comment

Beau­tiful Racket / explainers

Modules

A module is the basic orga­ni­za­tional unit of code in Racket. Three simple rules:

  1. All program code is contained in a module, through the use of module or one of its vari­ants. A module expres­sion includes a name, an expander, and a body containing other expres­sions:

    (module module-name expander
       other-expressions
       to-expand
       and-evaluate ...)
    1
2
3
4
    (module module-name expander
   other-expressions
   to-expand
   and-evaluate ...)
    copy to clipboard

    For instance, the code below creates a module named my-module, using the br expander, with one expres­sion inside (in an excep­tion to the usual custom, run these samples in DrRacket without a #lang br line at the top, or on the REPL):

    (module my-module br
      (* 6 7))
    1
2
    (module my-module br
  (* 6 7))
    copy to clipboard
    42
    1
    42
    copy to clipboard

  2. The expander supplies the initial bind­ings that are avail­able to expres­sions inside the module. If these expres­sions refer to bind­ings not provided by the expander, or not other­wise imported within the module (with require), then the module will not run.

    For instance, this module will run, because format-datum is provided by the br language:

    (module mod-name br
      (format-datum '(hello world)))
    1
2
    (module mod-name br
  (format-datum '(hello world)))
    copy to clipboard
    '(hello world)
    1
    '(hello world)
    copy to clipboard

    But this module won’t run, because format-datum is not provided by the racket language:

    (module mod-name racket
      (format-datum '(hello world)))
    1
2
    (module mod-name racket
  (format-datum '(hello world)))
    copy to clipboard
    format-datum: unbound identifier in module in: format-datum
    1
    format-datum: unbound identifier in module in: format-datum
    copy to clipboard

    But that can be fixed with a require, and this version will run:

    (module mod-name racket
      (require br)
      (format-datum '(hello world)))
    1
2
3
    (module mod-name racket
  (require br)
  (format-datum '(hello world)))
    copy to clipboard
    '(hello world)
    1
    '(hello world)
    copy to clipboard

  3. Modules are “lazy” in the sense that the code inside a module never runs until that module is explic­itly requested (say, by a require from else­where—see importing and exporting).

Source files with a #lang line

The #lang line is just a disguised module expres­sion. Every source file with a #lang line expands to a sin­gle mod­ule expres­sion at the top level. For instance, these two programs are the same, and will both eval­uate to 42:

#lang br
(* 6 7)
1
2
#lang br
(* 6 7)
copy to clipboard
(module my-module br
  (* 6 7))
1
2
(module my-module br
  (* 6 7))
copy to clipboard

This is why in Racket lingo, a source file is itself called a mod­ule.

“What about expres­sions entered at a REPL?” These expres­sions are treated as if they belong to the top-level module of the language being used.

Submod­ules

Modules can be nested inside each other to create hier­ar­chies of submod­ules. They can be nested to any depth, but typi­cally only descend one level. Submod­ules are defined with the same module syntax as regular modules. Submod­ules have two addi­tional rules:

  1. A submodule can require its enclosing module, or vice versa, but not both.

  2. Contrary to Racket’s usual eval­u­a­tion rules, a submodule does not auto­mat­i­cally run when its enclosing module runs; like­wise, running a submodule does not auto­mat­i­cally run its enclosing module.

This last rule is impor­tant, because it extends the “lazy” behavior in a nicely magical way: even when modules are nested, they behave like totally inde­pen­dent programs.

In the example below, the awake submodule has an enclosing tired module and a nested also-tired submodule that will each take a long time to run. But with a (require (submod ...)) expres­sion, we can run the awake submodule without trig­gering the others:

#lang br
(module tired br
  (sleep 10000)
  (module awake br
    (define greeting "Good morning")
    (provide greeting)
    (module also-tired br
      (sleep 10000))))

(require (submod "." tired awake))
greeting ; "Good morning"
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
#lang br
(module tired br
  (sleep 10000)
  (module awake br
    (define greeting "Good morning")
    (provide greeting)
    (module also-tired br
      (sleep 10000))))

(require (submod "." tired awake))
greeting ; "Good morning"
copy to clipboard

submod allows access to submod­ules through a path­like nota­tion. In this case, "." means “start in the current module”, and tired awake is the “path” to the submodule.

Special module forms

module+ defines a module that adopts all the bind­ings of the surrounding module. It can still define and provide addi­tional bind­ings. It can also be defined in sepa­rate pieces: all module+ expres­sions with the same name will be combined into a single submodule.

module* defines a module that can require its enclosing module (but not vice versa).

Main submod­ules

Any code in a main submodule will be eval­u­ated when the enclosing module is run directly in DrRacket or from the command line—but not when the module is imported with require. This allows a module to provide bind­ings but specify addi­tional behavior for when it’s invoked directly.

For instance, this source file prints a count­down and then also calls launch-rocket, because it’s in the main submodule:

#lang br
(provide launch-rocket)
(define (launch-rocket) (displayln "whee"))
(displayln "4, 3, 2, 1 ...")
(module+ main
  (launch-rocket))
1
2
3
4
5
6
#lang br
(provide launch-rocket)
(define (launch-rocket) (displayln "whee"))
(displayln "4, 3, 2, 1 ...")
(module+ main
  (launch-rocket))
copy to clipboard
4, 3, 2, 1 ...
whee
1
2
4, 3, 2, 1 ...
whee
copy to clipboard

But when the same code is wrapped in a submodule and imported with require, the main submodule doesn’t run:

#lang br
(module rocket br
  (provide launch-rocket)
  (define (launch-rocket) (displayln "whee"))
  (displayln "4, 3, 2, 1 ...")
  (module+ main
    (launch-rocket)))

(require 'rocket)
1
2
3
4
5
6
7
8
9
#lang br
(module rocket br
  (provide launch-rocket)
  (define (launch-rocket) (displayln "whee"))
  (displayln "4, 3, 2, 1 ...")
  (module+ main
    (launch-rocket)))

(require 'rocket)
copy to clipboard
4, 3, 2, 1 ...
1
4, 3, 2, 1 ...
copy to clipboard

Test submod­ules

It’s common in Racket to put unit tests inside a submodule called test (usually declared with module+, so it can use all the vari­ables defined nearby). See unit testing.

Reader submod­ules

When a language is spec­i­fied on the #lang line, Racket will first try to invoke the reader for that language. The first place Racket looks for a reader is in a reader submodule of the source file indi­cated.

#lang "yo.rkt" ; looks for reader in `(submod "yo.rkt" reader)`
#lang br ; looks for reader in `(submod br reader)`
1
2
#lang "yo.rkt" ; looks for reader in `(submod "yo.rkt" reader)`
#lang br ; looks for reader in `(submod br reader)`
copy to clipboard

Further

← prev next →