6.10 API for Relative Paths

► |  | 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.10 | API for Relative Paths

6.10.1 | Representing Collection-Based Paths
6.10.2 | Representing Paths Relative to "collects"
6.10.3 | Representing Paths Relative to the Documentation
6.10.4 | Displaying Paths Relative to a Common Root

On this page:

6.10.1`` Representing Collection-Based Paths
path->collects-relative
collects-relative->path
path->module-path
6.10.2`` Representing Paths Relative to "collects"
path->main-collects-relative
main-collects-relative->path
6.10.3`` Representing Paths Relative to the Documentation
path->main-doc-relative
main-doc-relative->path
6.10.4`` Displaying Paths Relative to a Common Root
path->relative-string/ library
path->relative-string/ setup
make-path->relative-string

top ← prev up next →

#### 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

(require setup/collects) | package: base

> > procedure
> > (path->collects-relative |  | path |
> > |  | #:cache cache) |
> | → |  |
> (or/c path-string?
> (cons/c 'collects
> (cons/c bytes? (non-empty-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
> (cons/c bytes? (non-empty-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 immutable?)))

Like path->collects-relative, but the result is either path or a normalized (in the sense of collapse-module-path) module path.

##### 6.10.2`` Representing Paths Relative to "collects"

(require setup/main-collects) | package: base

> procedure (path->main-collects-relative path)
> → (or/c path? (cons/c 'collects (non-empty-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 (non-empty-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).

##### 6.10.3`` Representing Paths Relative to the Documentation

(require setup/main-doc) | package: base

> procedure (path->main-doc-relative path)
> → (or/c path? (cons/c 'doc (non-empty-listof bytes?)))
> path : (or/c bytes? path-string?)

Like path->main-collects-relative, except that it checks for a prefix relative to (find-doc-dir) and returns a list starting with 'doc if so.

> procedure (main-doc-relative->path rel) → path>
> | rel |  | : |  |
> (or/c bytes?
> path-string?
> (cons/c 'doc (non-empty-listof bytes?)))

Like path->main-collects-relative, except it is the inverse of path->main-doc-relative.

##### 6.10.4`` 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>/", 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.

> > 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 →