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"
| (require setup/main-collects) |
procedure
(path->main-collects-relative path)
→ (or/c path? (cons/c 'collects (listof bytes?))) path : (or/c bytes? path-string?)
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.
procedure
(main-collects-relative->path rel) → path?
rel :
(or/c bytes? path-string? (cons/c 'collects (listof bytes?)))
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
| (require setup/path-to-relative) |
procedure
(path->relative-string/library path [ default]) → any/c path : path-string?
default : (or/c (-> path-string? any/c) any/c) = (lambda (x) (if (path? x) (path->string x) x))
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.
procedure
(path->relative-string/setup path [default]) → any
path : path-string?
default : (or/c (-> path-string? any/c) any/c) = (lambda (x) (if (path? x) (path->string x) x))
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.
procedure
(make-path->relative-string dirs [default])
→ (path-string? any/c . -> . any) dirs : (listof (cons (-> path?) string?))
default : (or/c (-> path-string? any/c) any/c) = (lambda (x) (if (path? x) (path->string x) x))
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).