6.10 API for Relative Paths
The Racket installation tree can usually be moved around the filesystem.
To support this, care must be taken to avoid absolute paths. The
following two APIs cover two aspects of this: a way to convert a path to
a value that is relative to the "collects" tree, and a way to
display such paths (e.g., in error messages).
6.10.1 Representing Collection-Based Paths
Checks whether
path (normalized by
path->complete-path and
simplify-path with
#f as its second argument) matches the result of
collection-file-path. If so, the result is a list starting
with
'collects and containing the relevant path elements as
byte strings. If not, the path is returned as-is.
The cache argument is used with path->pkg, if needed.
6.10.2 Representing Paths Relative to "collects"
Checks whether
path has a prefix that matches the prefix to
the main
"collects" directory as determined by
(find-collects-dir). If so, the result is a list starting
with
'collects and containing the remaining path elements as
byte strings. If not, the path is returned as-is.
The path argument should be a complete path. Applying
simplify-path before path->main-collects-relative is
usually a good idea.
For historical reasons, path can be a byte string, which is
converted to a path using bytes->path.
See also collects-relative->path.
6.10.3 Representing Paths Relative to the Documentation
(main-doc-relative->path rel) → path>
|
|
6.10.4 Displaying Paths Relative to a Common Root
Produces a string suitable for display in error messages. If the path
is an absolute one that is inside a package, the
result is a string that begins with "<pkgs>/". If the path
is an absolute one that is inside the "collects" tree, the
result is a string that begins with "<collects>/".
Similarly, a path in the user-specific collects results in a prefix of
"<user-collects>/", a PLaneT path results in
"<planet>/", and a path into documentation results in
"<doc>/" or "<user-doc>/".
If cache is not #f, it is used as a cache argument
for pkg->path to speed up detection and conversion of
package paths.
If the path is not absolute, or if it is not in any of these, it is
returned as-is (converted to a string if needed). If default
is given, it specifies the return value instead: it can be a procedure
that is applied onto the path to get the result, or the result
itself.
Note that this function can return a non-string only if
default is given and it does not return a string.
The dirs argument determines the prefix substitutions. It must be an
association list mapping a path-producing thunk to a prefix string for
paths in the specified path.
default determines the default for the resulting function
(which can always be overridden by an additional argument to this
function).