►raco:   Racket Command-Line Tools
▼6 raco setup:   Installation Management
►6.9 API for Relative Paths
On this page:
6.9.1 Representing Collection-Based Paths
path->collects-relative
collects-relative->path
path->module-path
6.9.2 Representing Paths Relative to "collects"
path->main-collects-relative
main-collects-relative->path
6.9.3 Displaying Paths Relative to a Common Root
path->relative-string/  library
path->relative-string/  setup
make-path->relative-string
  top  ← prev  up  next → 

6.9 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).

6.9.1 Representing Collection-Based Paths

 (require setup/collects) package: base

procedure

(path->collects-relative path 
  #:cache cache) 
 → (or/c path-string? (cons/c 'collects (listof bytes?)))
  path : path-string?
  cache : (or/c #f (and/c hash? (not/c immutable?)))
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.

procedure

(collects-relative->path rel) → path-string?

  rel : 
(or/c path-string?
      (cons/c 'collects bytes? bytes? (listof bytes?)))
The inverse of path->collects-relative: if rel is a pair that starts with 'collects, then it is converted back to a path using collection-file-path.

procedure

(path->module-path path #:cache cache)

 → (or/c path-string? module-path?)
  path : path-string?
  cache : (or/c #f (and/c hash? (not/c imutable?)))
Like path->collects-relative, but the result is either path or a normalized (in the sense of collapse-module-path) module path.

6.9.2 Representing Paths Relative to "collects"

 (require setup/main-collects) package: base

procedure

(path->main-collects-relative path)

 → (or/c path? (cons/c 'collects (listof bytes?)))
  path : (or/c bytes? path-string?)
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.

procedure

(main-collects-relative->path rel) → path?

  rel : 
(or/c bytes? path-string?
      (cons/c 'collects (listof bytes?)))
The inverse of path->main-collects-relative: if rel is a pair that starts with 'collects, then it is converted back to a path relative to (find-collects-dir).

For historical reasons, if rel is any kind of value other than specified in the contract above, it is returned as-is.

6.9.3 Displaying Paths Relative to a Common Root

 (require setup/path-to-relative) package: base

procedure

(path->relative-string/library path    
  [default    
  #:cache cache]) → any/c
  path : path-string?
  default : (or/c (-> path-string? any/c) any/c)
   = (lambda (x) (if (path? x) (path->string x) x))
  cache : (or/c #f (and/c hash? (not/c immutable?))) = #f
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>/", and a PLaneT path results in "<planet>/".

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.

procedure

(path->relative-string/setup path    
  [default    
  #:cache cache]) → any/c
  path : path-string?
  default : (or/c (-> path-string? any/c) any/c)
   = (lambda (x) (if (path? x) (path->string x) x))
  cache : (or/c #f (and/c hash? (not/c immutable?))) = #f
The same as path->relative-string/library, for backward compatibility.

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))
This function produces functions like path->relative-string/library and path->relative-string/setup.

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).

  top  ← prev  up  next →