6.9 API for Reading "info.rkt" Files

► |  | raco: Racket Command-Line Tools

1 | raco make: Compiling Source to Bytecode
2 | raco exe: Creating Stand-Alone Executables
3 | raco distribute: Sharing Stand-Alone Executables
4 | raco planet: Automatic Package Distribution
5 | raco pkg: Package Management
6 | raco setup: Installation Management
7 | raco decompile: Decompiling Bytecode
8 | raco demod: Demodularizing Programs
9 | raco link: Library Collection Links
10 | raco pack: Packing Library Collections
11 | raco unpack: Unpacking Library Collections
12 | raco ctool: Working with C Code
13 | raco test: Run tests
14 | raco docs: Documentation Search
15 | raco expand: Macro Expansion
16 | raco read: Reading and Pretty-Printing
17 | raco scribble: Building Documentation
18 | Adding a raco Command
19 | Installation Configuration and Search Paths

▼ | 6 | raco setup: Installation Management

6.1 | Running raco setup
6.2 | Installing ".plt" Archives
6.3 | Controlling raco setup with "info.rkt" Files
6.4 | "info.rkt" File Format
6.5 | Package Dependency Checking
6.6 | API for Setup
6.7 | API for Installing ".plt" Archives
6.8 | API for Finding Installation Directories
6.9 | API for Reading "info.rkt" Files
6.10 | API for Relative Paths
6.11 | API for Collection Names
6.12 | API for Collection Searches
6.13 | API for Platform Specifications
6.14 | API for Cross-Platform Configuration
6.15 | API for Cross-References for Installed Manuals
6.16 | API for Materializing User-Specific Documentation
6.17 | API for Staging Documentation Installs
6.18 | Layered Installations
6.19 | Tethered Installations

On this page:

get-info
get-info/ full
find-relevant-directories
find-relevant-directory-records
directory-record
reset-relevant-directories-state!

Racket
top contents ← prev up next →

### 6.9 API for Reading "info.rkt" Files🔗ℹ

(require setup/getinfo) | package: base

The setup/getinfo library provides functions for accessing fields in "info.rkt" files. The file format for "info.rkt" files is documented in "info.rkt" File Format.

> > procedure
> > (get-info |  | collection-names |
> > | [ | #:namespace namespace |
> > |  | #:bootstrap? bootstrap?]) |
> | → |  |
> (or/c
> ((symbol?) ((-> any)) . ->* . any)
> #f)
> collection-names : (listof string?)
> namespace : (or/c namespace? #f) = #f
> bootstrap? : any/c = #f

Accepts a list of strings naming a collection or sub-collection, and calls get-info/full with the full path corresponding to the named collection and the namespace argument.

> > procedure
> > (get-info/full |  | path |
> > | [ | #:namespace namespace |
> > |  | #:bootstrap? bootstrap?]) |
> | → |  |
> (or/c
> ((symbol?) ((-> any)) . ->* . any)
> #f)
> path : path-string?
> namespace : (or/c namespace? #f) = #f
> bootstrap? : any/c = #f

Accepts a path to a directory. If it finds either a well-formed "info.rkt" file or an "info.ss" file (with preference for the "info.rkt" file), it returns an info procedure that accepts either one or two arguments. The first argument to the info procedure is always a symbolic name, and the result is the value of the name in the "info.rkt" file, if the name is defined. The optional second argument, thunk, is a procedure that takes no arguments to be called when the name is not defined; the result of the info procedure is the result of the thunk in that case. If the name is not defined and no thunk is provided, then an exception is raised.

The get-info/full function returns #f if there is no "info.rkt" (or "info.ss") file in the directory. If there is a "info.rkt" (or "info.ss") file that has the wrong shape (i.e., not a module using info or setup/infotab), or if the "info.rkt" file fails to load, then an exception is raised. If the "info.rkt" file loaded, get-info/full returns the info procedure. If the "info.rkt" file does not exist, then get-info/full does the same checks for the "info.ss" file, either raising an exception or returning the info procedure from the "info.ss" file.

The "info.rkt" (or "info.ss") module is loaded into namespace if it is not #f, or a private, weakly-held namespace otherwise.

If bootstrap? is true, then use-compiled-file-paths is set to '() while reading "info.rkt" (or "info.ss"), in case an existing compiled file is broken. Furthermore, the info and setup/infotab modules are attached to namespace from the namespace of get-info/full before attempting to load "info.rkt" (or "info.ss").

As the module is loaded, the environment variable set is pruned to contain only environment variables that are listed in the PLT_INFO_ALLOW_VARS environment variable, which contains a ;-separated list of names. By default, the list of allowed variable names is empty.

Changed in version 6.5.0.2 of package base: Added environment-variable pruning and PLT_INFO_ALLOW_VARS support.

> procedure (find-relevant-directories syms [mode]) → (listof path?)
> syms : (listof symbol?)
> | mode |  | : |  | (or/c 'preferred 'all-available 'no-planet 'no-user)
> |  |  | = |  | 'preferred

Returns a list of paths identifying collections and installed PLaneT packages whose "info.rkt" file defines one or more of the given symbols. The result is based on a cache that is computed by raco setup.

Note that the cache may be out of date by the time you call get-info/full, so do not assume that every returned directory’s "info.rkt" file will supply one of the requested symbols.

The result is in a canonical order (sorted lexicographically by directory name), and the paths it returns are suitable for providing to get-info/full.

If mode is specified, it must be either 'preferred (the default), 'all-available, 'no-planet, or 'no-user. If mode is 'all-available, find-relevant-directories returns all installed directories whose info files contain the specified symbols—for instance, all versions of all installed PLaneT packages will be searched if 'all-available is specified. If mode is 'preferred, then only a subset of “preferred” packages will be searched: only the directory containing the most recent version of any PLaneT package will be returned. If mode is 'no-planet, then PLaneT packages are not included in the search. If mode is 'no-user, then only installation-wide directories are searched, which means omitting PLaneT package directories.

Regardless of mode, note that find-relevant-directories will not consider package-level "info.rkt" files for multi-collection packages, since those files are not part of any collection or PLaneT package. In contrast, a single-collection package’s "info.rkt" file is part of a collection, and thus will be considered.

Collection links from the installation-wide collection links file or packages with installation scope are cached with the installation’s main "lib" directory, and links from the user-specific collection links file and packages are cached with the user-specific directory (build-path (find-system-path 'addon-dir) "collects") for all-version cases, and in (build-path (find-system-path 'addon-dir) (version) "collects") for version-specific cases. These cache paths can be redirected by an 'info-domain-root entry in "config.rktd" (see Installation Configuration and Search Paths).

> procedure (find-relevant-directory-records syms key)
> → (listof directory-record?)
> syms : (listof symbol?)
> key : (or/c 'preferred 'all-available 'no-planet 'no-user)

Like find-relevant-directories, but returns directory-record structs instead of path?s.

> > struct
> > (struct |  | directory-record (maj min spec path syms)
> #:extra-constructor-name make-directory-record)
> maj : integer?
> min : integer?
> spec : any/c
> path : path?
> syms : (listof symbol?)

A struct that records information about a collection or a PLaneT package that has been installed. Collections will have the major version being 1 and the minor version being 0. The spec field is a quoted module spec; the path field is where the info.rkt file for this collection or PLaneT package exists on the filesystem; the syms field holds the identifiers defined in that file.

> procedure (reset-relevant-directories-state!) → void?

Resets the cache used by find-relevant-directories.
top contents ← prev up next →