Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 38 ยท Modules and Contracts

Modules and provide

Organize Racket programs into modules: require and provide, rename and prefix imports, submodules like main and test, collections and paths, plus a JavaScript module-registry stand-in.

A real program is more than one file. A module in Racket is a file (or a module form) that defines names and chooses which of them to share. Modules give you namespaces, a clear dependency graph, compile-time separation, and a place to hang tests and entry points. Standard Scheme (R6RS and R7RS) has libraries with the same purpose; Racket's module system is its own, richer version.

This lesson covers require, provide, renaming and prefixes, submodules (main, test), and how Racket finds modules. The next lesson, Contracts Basics, uses provide to guard module boundaries.

Racket runs modules from files, which our site cannot do, so the Racket code is read-only. The runnable block is a JavaScript stand-in for a module registry with provide and require.

One file, one module

Every file starting with #lang racket (or racket/base) is a module. Names are private unless you provide them:

RACKET
;; file: geometry.rkt
#lang racket

(provide circle-area
         (struct-out point))

(struct point (x y))

(define pi-approx 3.14159)           ; private helper

(define (circle-area r)
  (* pi-approx r r))

Another file imports it with require:

RACKET
;; file: main.rkt
#lang racket
(require "geometry.rkt")

(circle-area 2)          ; => 12.56636
(point-x (point 3 4))    ; => 3
;; pi-approx is not visible here: it was not provided

A string is a path relative to the current file; a bare name like racket/list refers to a collection that ships with Racket (or is installed with raco pkg). The (struct-out point) form exports the struct constructor, predicate and accessors together.

provide forms worth knowing

  • (provide name ...) exports named bindings.
  • (provide (all-defined-out)) exports everything defined in the module (handy but exposes internals).
  • (provide (struct-out s)) exports a structure's constructor, accessors and so on.
  • (provide (rename-out [internal-name public-name])) exports under another name.
  • (provide (contract-out ...)) exports with contracts, covered in the next lessons.
  • (all-from-out "other.rkt") re-exports everything another module provides.

Keep the exported surface small. Everything you provide is a promise to other code; everything else you are free to change.

require forms: avoid name clashes

When two modules export the same name, Racket reports an error instead of silently choosing one. You control imports with modifiers:

RACKET
(require (prefix-in g: "geometry.rkt"))    ; g:circle-area
(require (only-in racket/list first last)) ; just these two
(require (except-in racket/list range))    ; everything but range
(require (rename-in "geometry.rkt" [circle-area area]))

prefix-in is the cleanest fix when two libraries are both useful; only-in documents exactly what you rely on. Using (require ...) at the top of a module is the norm, and cycles between modules are not allowed (module A cannot require B if B requires A), which keeps the dependency graph a tree-like structure.

Submodules: main and test

A submodule is a module nested inside another file. Two names are special: main runs when the file is run as a program, and test runs when tests are run, but neither runs when the file is merely required by another module.

RACKET
#lang racket
(provide add)
(define (add a b) (+ a b))

(module+ main
  (displayln (add 2 3)))        ; runs with: racket file.rkt

(module+ test
  (require rackunit)
  (check-equal? (add 2 2) 4))   ; runs with: raco test file.rkt

module+ lets you add to a submodule in several places and gives it access to the enclosing module's bindings. This is the idiomatic way to keep a program's entry point and its tests in the same file as the code, without side effects on import. The testing lesson goes deeper.

flowchart TD
  F["file.rkt module"] --> P["provided names"]
  F --> M["(module+ main) runs as program"]
  F --> T["(module+ test) runs under raco test"]
  O["other.rkt"] -->|"require"| P

Importing a file gives you its provided names only; main and test stay out of the way.

Stand-in: a module registry

JavaScript has its own modules (import/export), but they cannot be demonstrated in a single editor block. This stand-in implements the essentials in plain JavaScript: modules are factories that return their exports, provide is the object they return, require executes a module once and caches it, and cyclic requires are rejected.

JS Stand-in: modules with provide, require and prefix

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The "(geometry loaded)" message appears once, even though two modules asked for it: a module is instantiated once and shared. That matches Racket, where each module has a single instance per program run.

Paths and packages

For larger projects Racket uses packages installed with raco pkg install; their modules are found through collection paths, so you write (require my-lib/util) instead of a file path. Your own project becomes a package by adding an info.rkt file. Use relative paths inside a project, collection paths for libraries.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What makes a name visible to other modules?

    Definitions are private to the module unless they appear in a provide form.
  2. 2. What does (require (prefix-in g: "geometry.rkt")) do?

    prefix-in adds a prefix to every imported name, avoiding clashes.
  3. 3. When does a (module+ main ...) submodule run?

    main runs when the file is executed, not when it is merely required, so imports have no side effects.
  4. 4. What happens if two required modules export the same name?

    Conflicting imports are errors, which you resolve with prefix-in, only-in, except-in or rename-in.

Summary

  • Each file is a module; names are private unless provided.
  • require imports modules; prefix-in, only-in, except-in and rename-in control the names.
  • Cyclic dependencies are not allowed, and a module is instantiated once.
  • module+ main and module+ test hold the entry point and tests without side effects on import.
  • Collections and packages let you refer to libraries by name instead of by path.

Next: Contracts Basics