Next: MzLib Overview Up: PLT MzScheme: Language Manual Previous: Saving and Restoring Program

# Library Collections and MzLib

A library is a fragment of MzScheme code that can be used in multiple programs. MzScheme provides an mechanism for grouping libraries into collections that can be distributed and easily added to a local MzScheme installation. A collection is normally installed into a directory named `collects` that is in the same directory as the MzScheme executable. Each installed collection is represented as a subdirectory within the `collects` directory.

Client programs incorporate a library by using the library name along with the name of the library's collection: `(require-library library-file-path collection )` loads a library from library-file-path in the collection named by the first collection, where both library-file-path and collection are literal strings that will be used as elements in a pathname. If additional collection strings are provided, they are used to form a path into a subcollection. If the collection arguments are omitted, the library is loaded from the `mzlib` collection. The `require-library` form returns the result(s) of the last expression in the library file.

The `info.ss` library in a collection is special by convention. This library is used to provide information about the collection to `mzc` (the MzScheme compiler) or MrEd. For more information see PLT mzc: MzScheme Compiler Manual and PLT MrEd: Graphical Toolbox Manual.

When `require-library` is used to load a file, the library name and the resulting value(s) are recored in a table associated with the current namespace. If `require-library` is evaluated for a library that is already registered in the current namespace's load table, then the library is not loaded again; the result(s) recorded in the load table is returned, instead.

While `require-library` loads a library file, it sets the `current-require-relative-collection` parameter to the path of collection names that specify the library's subcollection. This path is used by the `require-relative-library` form: `(require-relative-library library-file-path collection )` requires library-file-path from the collection specified by the `current-require-relative-collection` parameter; if extra collections are provided, they are appended to the end of the subcollection path in `current-require-relative-collection` for finding library-file-path.

There is usually one standard `collects` directory, but MzScheme supports any number of directories containing collections. The search path for collections is determined by the `current-library-collection-paths` parameter (see section 9.4.1.8). The list of paths in `current-library-collection-paths` is searched from first to last to locate a collection when a library is requested. The value of the parameter is initialized by the stand-alone version of MzScheme as follows: ``

      (current-library-collection-paths
       (path-list-string->path-list
        (or (getenv "PLTCOLLECTS") "")
        (or (ormap (lambda (p) (and p (directory-exists? p) (list p)))
                   (list (let ([v (getenv "PLTHOME")]) (and v (build-path v "collects")))
                         (find-executable-path program "collects")
                         "/usr/local/lib/plt/collects" ; Unix only
                         "/boot/apps/plt/collects" ; BeOS only
                         "c:\\plt\\collects")) ; Windows only
            null)))

where `program` is the name used to start MzScheme (always a complete path for MacOS). See also section 11.2.1 for information about `path-list-string->path-list` and `find-executable-path`. `(collection-path collection )` returns the path containing the libraries of collection; if the collection is not found, the `exn:i/o:filesystem` exception is raised.

The `require-library` form loads library files using `load/use-compiled`. In the table of loaded libraries, library names are registered using the original suffix even when `load/use-compiled` loads a compiled version of a file.

Since `require-library`'s libraries and collections are specified via string literals, this form supports the static analysis of programs by MrSpidey, DrScheme's static debugger. The `require-library/proc` procedure generalizes `require-library` to a procedural form, but it is not supported by the static debugger. Nevertheless, the `require-library` form normally expands to an application of `require-library/proc`: ``

      (require-library library collection   )

      (require-library/proc library collection   )

Similarly, `require-relative-library/proc` is the procedure form of `require-relative-library`.

The `provide-library` procedure installs values lazily into the current namespace's table of library values, if no values are yet registered for the specified library. `(provide-library thunk library-file-path collection )` installs thunk as the value-generator for library-file-path within the collection specified by the collection strings (defaulting to `"mzlib"` if no collection is provided). A `#f` return value indicates that the library already has values in the table, and thunk is ignored. Otherwise, the result is `#t`, and when the library is later requested via `require-library`, thunk is called to obtain the library's value(s). The thunk procedure is called only the first time that the library is requested, and then the returned values replace thunk in the namespace's table.

MzScheme is distributed with a standard collection of utility libraries with MzLib as the representative library. The name of this collection is `mzlib`, so the libraries are distributed in a `mzlib` subdirectory of the `collects` library collection directory. MzLib is described in section 15.1.

- MzLib Overview
  - Thanks
- MzLib Libraries
  - Awk: `awk.ss`
  - Classes with `define`d Methods: `classd.ss`
  - Command-line Parsing: `cmdline.ss`
  - Compatibility: `compat.ss`
  - Compiling Files: `compile.ss`
  - Core: `core.ss`
  - Dates: `date.ss`
  - Deflating (Compressing) Data: `deflate.ss`
  - Structures: `defstru.ss`
  - Filesystem: `file.ss`
  - Functions: `functio.ss`
  - Inflating Compressed Data: `inflate.ss`
  - Invoking with Exports to a Namespace: `invoke.ss`
  - Macros: `macro.ss`
  - Match: `match.ss`
  - Math: `math.ss`
  - MzLib: `mzlib.ss`
  - Converted Printing: `pconver.ss`
  - Pretty Printing: `pretty.ss`
  - Requiring Libraries and Files: `refer.ss`
  - Restarting MzScheme with Arguments: `restart.ss`
  - Sharing: `shared.ss`
  - MrSpidey: `spidey.ss`
  - Strings: `string.ss`
  - Syntax Rules: `synrule.ss`
  - Threads: `thread.ss`
  - Tracing: `trace.ss`
  - Tracing Loads: `traceld.ss`
  - Transcripts: `transcr.ss`

Next: MzLib Overview Up: PLT MzScheme: Language Manual Previous: Saving and Restoring Program