► |  | Guide: PLT Scheme

1 | Welcome to PLT Scheme
2 | Scheme Essentials
3 | Built-In Datatypes
4 | Expressions and Definitions
5 | Programmer-Defined Datatypes
6 | Modules
7 | Contracts
8 | Input and Output
9 | Regular Expressions
10 | Exceptions and Control
11 | Iterations and Comprehensions
12 | Pattern Matching
13 | Classes and Objects
14 | Units (Components)
15 | Reflection and Dynamic Evaluation
16 | Macros
17 | Performance
18 | Running and Creating Executables
19 | Compilation and Configuration
20 | More Libraries
21 | Dialects of Scheme
| Bibliography
| Index

▼ | 6 | Modules

6.1 | Module Basics
6.2 | Module Syntax
6.3 | Module Paths
6.4 | Imports: require
6.5 | Exports: provide
6.6 | Assignment and Redefinition

top ← prev up next →

#### 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 "Thursday, July 8th, 2010"

> 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:

> > ( module m ( lib "scheme")
> ( require ( lib "scheme/date.ss"))
> ( printf "Today is ~s\n"
> (date->string ( seconds->date ( current-seconds )))))

> > ( require 'm)
> Today is "Thursday, July 8th, 2010"

> ( 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:

> > ( module m ( lib "scheme")
> ; Use "schematics"'s "random.plt" 1.0, file "random.ss":
> ( require ( planet schematics/random:1/random))
> ( 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:

> > ( module m ( lib "scheme")
> ( 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.

top ← prev up next →