6.3 Module Paths
A module path is a reference to a module, as used with require or as the initial-module-path in a module form. It can be any of several forms:
(quote id) A module path that is a quoted identifier refers to a non-file module declaration using the identifier. This form of module reference makes the most sense in a REPL.
Examples:
rel-string A string module path 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), which is set while loading a file.)
Module Basics 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 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 collections and sub-collections, 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, which is commonly used at the initial import. The path racket is shorthand for racket/main; when an id has no /, then /main is automatically added to the end. Thus, racket or racket/main refers to the module whose source is the "main.rkt" file in the "racket" collection.
Examples:
> (module m racket (require racket/date) (printf "Today is ~s\n" (date->string (seconds->date (current-seconds))))) > (require 'm) Today is "Sunday, October 27th, 2024"
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 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 "racket/date.rkt") and (lib "racket/date"), which are equivalent to racket/date. Other examples include (lib "racket"), (lib "racket/main"), and (lib "racket/main.rkt"), which are all equivalent to racket.
Examples:
> (module m (lib "racket") (require (lib "racket/date.rkt")) (printf "Today is ~s\n" (date->string (seconds->date (current-seconds))))) > (require 'm) Today is "Sunday, October 27th, 2024"
(planet 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 path, a ".rkt" suffix is added automatically, and /main is used as the path if no sub-path element is supplied.
Examples:
> (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 package-string) Like the symbol form of a planet, 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.
(planet rel-string (user-string pkg-string vers ...))
vers = nat | (nat nat) | (= nat) | (+ nat) | (- nat) A more general form to access a library from the PLaneT server. In this general form, a PLaneT reference starts like a lib 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 (+ 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 (= nat) matches only exactly nat. A (- nat) matches nat or lower.
Examples:
> (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 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.
(submod base element ...+)
base = module-path | "." | ".." element = id | ".." Refers to a submodule of base. The sequence of elements within submod specify a path of submodule names to reach the final submodule.
Examples:
> (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 stands for the enclosing module. Using ".." as base is equivalent to using "." followed by an extra "..". When a path of the form (quote id) refers to a submodule, it is equivalent to (submod "." id).
Using ".." as an element cancels one submodule step, effectively referring to the enclosing module. For example, (submod "..") refers to the enclosing module of the submodule in which the path appears.
Examples: