9.4 KiB
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:
> (module m racket
(provide color)
(define color "blue"))
> (module n racket
(require 'm)
(printf "my favorite color is ~a\n" color))
> (require 'n)
my favorite color is blue
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. If the path has no suffix, ".rkt"
is added
automatically.
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.)
missing
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 "Monday, January 21st, 2019"
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 "Monday, January 21st, 2019"
(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 vers
es 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 vers
es 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 element
s 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:
> (module zoo racket
(module monkey-house racket
(provide monkey)
(define monkey "Curious George"))
(module crocodile-house racket
(require (submod ".." monkey-house))
(provide dinner)
(define dinner monkey)))
> (require (submod 'zoo crocodile-house))
> dinner
"Curious George"