Finding Racket Paths
1 API for Finding Racket Paths
whereis-module
whereis-collection
whereis-pkg
whereis-raco
whereis-system
whereis-binding
whereis-binding/  symbol
2 raco whereis:   Finding Racket Paths
7.8

Finding Racket Paths

This package provides an API and raco command that consolidates support for finding paths significant to Racket.

1 API for Finding Racket Paths

 (require whereis) package: whereis

The procedures provided by whereis return local filesystem paths corresponding to Racket modules, collections, packages, etc.

See also raco whereis: Finding Racket Paths.

procedure

(whereis-module modpath)  path?

  modpath : (or/c module-path? module-path-index?)
Returns the path containing the declaration of the given module.

The example results are for a development build of racket in /home/me/dev. Your results will differ.

Examples:
> (whereis-module 'racket/list)

#<path:/home/me/dev/racket/racket/collects/racket/list.rkt>

> (whereis-module 'racket/draw)

#<path:/home/me/dev/racket/racket/share/pkgs/draw-lib/racket/draw.rkt>

> (whereis-module '(submod racket reader)) ; same as racket

#<path:/home/me/dev/racket/racket/collects/racket/main.rkt>

If modpath cannot be resolved or resolves to a nonexistant file, an exception is raised. If modpath refers to a submodule, the path of the enclosing top-level module is returned.

procedure

(whereis-collection collection)  (listof path?)

  collection : collection-name?
Returns a list of directory paths corresponding to the given collection. Note that a collection may have multiple directories, depending on collection roots and installed packages.

Examples:
> (whereis-collection "json")

'(#<path:/home/me/dev/racket/racket/collects/json>

  #<path:/home/me/dev/racket/pkgs/racket-doc/json>)

> (whereis-collection "racket/gui")

'(#<path:/home/me/dev/racket/racket/collects/racket/gui>

  #<path:/home/me/dev/racket/racket/share/pkgs/gui-lib/racket/gui>)

> (whereis-collection "drracket")

'(#<path:/home/me/dev/racket/racket/share/pkgs/drracket/drracket>

  #<path:/home/me/dev/racket/racket/share/pkgs/drracket-tool-lib/drracket>

  #<path:/home/me/dev/racket/racket/share/pkgs/drracket-plugin-lib/drracket>)

In contrast to collection-path, this procedure returns returns all directories associated with collection.

If no directories are found for collection, an exception is raised.

procedure

(whereis-pkg pkg)  path?

  pkg : string?
Returns the directory containing pkg, which must be installed in some scope.

Like (pkg-directory pkg), but simplifies the result path.

Examples:
> (whereis-pkg "base")

#<path:/home/me/dev/racket/pkgs/base>

> (whereis-pkg "pict-lib")

#<path:/home/me/dev/racket/racket/share/pkgs/pict-lib>

If pkg is not installed, an exception is raised.

procedure

(whereis-raco command)  path?

  command : string?
Returns the path of the module implementing the given raco command.

Examples:
> (whereis-raco "exe")

#<path:/home/me/dev/racket/pkgs/compiler-lib/compiler/commands/exe.rkt>

> (whereis-raco "whereis")

#<path:/home/me/dev/racket/pkgs/compiler-lib/compiler/commands/whereis.rkt>

An error is reported if the given raco command is not registered. If the command is implemented by a submodule, the path of the enclosing top-level module is returned.

procedure

(whereis-system name)  (or/c path? (listof path?))

  name : symbol?
Prints the path or paths corresponding to the given system location.

The following location names are supported:
  • 'home-dir, 'pref-dir, 'pref-file, 'temp-dir, 'init-dir, 'init-file, 'addon-dir, 'doc-dir, 'desk-dir, 'sys-dir Equivalent to (find-system-path name).

    Example: (whereis-system 'temp-dir).

  • 'exec-file, 'config-dir, 'host-config-dir, 'collects-dir, 'host-collects-dir Like (find-system-path name), but relative paths are converted into absolute paths by interpreting them with respect to the path of the racket executable.

    Example: (whereis-system 'config-dir).

  • the name of a procedure from setup/dirs that returns a path or list of paths.

    Example: (whereis-system 'get-config-dir).

If name is unknown or if the implementation returns #f, an exception is raised.

procedure

(whereis-binding id [phase])  path?

  id : identifier?
  phase : (or/c exact-integer? #f) = (syntax-local-phase-level)
Returns the path of the module that defines the binding referred to by id (at phase phase). Note that the defined name might be different due to renamings.

Examples:
> (whereis-binding #'lambda)

#<path:/home/me/dev/racket/racket/collects/racket/private/kw.rkt>

> (whereis-binding #'in-list)

#<path:/home/me/dev/racket/racket/collects/racket/private/for.rkt>

Note that this procedure does not see through contract-out. That is, contract-out defines and exports an auxiliary macro to perform contract checking, and this procedure reports the definition site of the macro (the site where contract-out is used) instead of the definition site of the binding being protected.

If id does not refer to a module export at phase phase, or if the binding was defined by a built-in module (such as '#%kernel), an error is reported. If id is defined in a submodule, the path of the enclosing top-level module is returned.

procedure

(whereis-binding/symbol providing-mod name)  path?

  providing-mod : module-path?
  name : symbol?
Like whereis-binding, but the binding is name exported by providing-mod. Note that the defined name might be different due to renamings.

Examples:
> (whereis-binding/symbol 'racket 'define)

#<path:/home/me/dev/racket/racket/collects/racket/private/kw.rkt>

> (whereis-binding/symbol 'racket 'in-list)

#<path:/home/me/dev/racket/racket/collects/racket/private/for.rkt>

If providing-mod does not have an export named name, or if the binding was defined by a built-in module (such as '#%kernel), an error is reported. If id is defined in a submodule, the path of the enclosing top-level module is returned.

2 raco whereis: Finding Racket Paths

The raco whereis command prints the local filesystem path corresponding to Racket modules, collections, packages, etc.

Command-line flags: