8.7 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 "collets" tree, and a way to
display such paths (e.g., in error messages).
8.7.1 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.
For historical reasons, if rel is any kind of value other
than specified in the contract above, it is returned as-is.
8.7.2 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 the "collects" tree, the
result will be a string that begins with "<collects>/".
Similarly, a path in the user-specific collects results in a prefix of
"<user-collects>/", and a PLaneT path results in
"<planet>/".
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
which is applied onto the path to get the result, or the result
itself.
Note that this function can be a non-string only if default
is given, and it does not return a string.
Similar to
path->relative-string/library, but more suited for
output during compilation:
"collects" paths are shown with no
prefix, and in the user-specific collects with just a
"<user>" prefix.
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
which is applied onto the path to get the result, or the result
itself.
Note that this function can be a non-string only if default
is given, and it does not return a string.
dirs determines the prefix substitutions. It should 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).