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:
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: |
| | | | | > (require 'n) | my favorite color is blue | |
|
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.)
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.
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: |
| | | > (require 'm) | Today is "Wednesday, February 1st, 2012" | |
|
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.
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: |
| | | > (require 'm) | Today is "Wednesday, February 1st, 2012" | |
|
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.
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.
The automatic ".ss" and ".rkt" conversions apply as
with other forms.
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.