|
|
# 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:
|
|
|
|
|
|
```racket
|
|
|
(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:
|
|
|
|
|
|
```racket
|
|
|
> (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
|
|
|
```
|
|
|
|
|
|
```racket
|
|
|
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\] 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.
|
|
|
|
|
|
```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:
|
|
|
|
|
|
```racket
|
|
|
> (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.
|
|
|
|
|
|
```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:
|
|
|
|
|
|
```racket
|
|
|
> (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"
|
|
|
```
|
|
|
|
|
|
```racket
|
|
|
(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:
|
|
|
|
|
|
```racket
|
|
|
> (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.
|
|
|
|
|
|
```racket
|
|
|
(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.
|
|
|
|
|
|
```racket
|
|
|
(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:
|
|
|
|
|
|
```racket
|
|
|
> (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.
|
|
|
|
|
|
```racket
|
|
|
(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.
|
|
|
|
|
|
```racket
|
|
|
(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:
|
|
|
|
|
|
```racket
|
|
|
> (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:
|
|
|
|
|
|
```racket
|
|
|
> (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"
|
|
|
```
|