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:
> (module m scheme
(provide color)
(define color "blue"))
> (module n scheme
(require 'm)
(printf "my favorite color is ~a\n" color))
> (require 'n)
my favorite color is blue
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 scheme/date. It refers to the module whose source is the "date.ss" file in the "scheme" collection, which is installed as part of PLT Scheme. The ".ss" suffix is added automatically.
Another example of this form is scheme, which is commonly used at the initial import. The path scheme is shorthand for scheme/main; when an id has no /, then /main is automatically added to the end. Thus, scheme or scheme/main refers to the module whose source is the "main.ss" file in the "scheme" collection.
Examples:
> (module m scheme
(require scheme/date)
(printf "Today is ~s\n"
(date->string (seconds->date (current-seconds)))))
> (require 'm)
Today is "Friday, July 4th, 2008"
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.
(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 case the relevant suffix is not ".ss".
Example of this form include (lib "scheme/date.ss") and (lib "scheme/date"), which are equivalent to scheme/date. Other examples include (lib "scheme"), (lib "scheme/main"), and (lib "scheme/main.ss"), which are all equivalent to scheme.
Examples:
(printf "Today is ~s\n"
(date->string (seconds->date (current-seconds)))))
> (require 'm)
Today is "Friday, July 4th, 2008"
(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 ".ss" suffix is added automatically, and /main is used as the path if no sub-path element is supplied.
Examples:
; Use "schematics"'s "random.plt" 1.0, file "random.ss":
(display (random-gaussian)))
> (require 'm)
0.9050686838895684
(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 case the relevant suffix is not ".ss".
(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:
(require (planet "random.ss" ("schematics" "random.plt" 1 0)))
(display (random-gaussian)))
> (require 'm)
0.9050686838895684
(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.