4 Module-Processing Helpers
4.1 Reading Module Source Code
Calls thunk with all reader parameters reset to their default
to check whether evaluating it will declare a
at least if module
is bound in the top-level to
. The syntax object stx
can contain a
compiled expression. Also, stx
can be an end-of-file, on the
grounds that read-syntax
can produce an end-of-file.
The expected-module-sym argument is currently ignored. In
previous versions, the module form stx was obliged to declare
a module who name matched expected-module-sym.
If stx can declare a module in an appropriate top-level, then
the check-module-form procedure returns a syntax object that
certainly will declare a module (adding explicit context to the
leading module if necessary) in any top-level. Otherwise, if
source-v is not #f, a suitable exception is raised
using the write form of the source in the message; if
source-v is #f, #f is returned.
If stx is eof or eof wrapped as a syntax object, then an
error is raised or #f is returned.
4.2 Getting Module Compiled Code
Returns a compiled expression for the declaration of the module
specified by path and submodule-path, where
submodule-path is empty for a root module or a list for a
The compiled-subdir argument defaults to "compiled";
it specifies the sub-directory to search for a compiled version of the
module. The roots list specifies a compiled-file search path
in the same way as the current-compiled-file-roots parameter.
The compile-proc argument defaults to compile. This
procedure is used to compile module source if an already-compiled
version is not available. If submodule-path is not '(),
then compile-proc must return a compiled module form.
The ext-proc argument defaults to #f. If it is not
#f, it must be a procedure of two arguments that is called
when a native-code version of path should be used. In that
case, the arguments to ext-proc are the path for the
extension, and a boolean indicating whether the extension is a _loader
file (#t) or not (#f).
The rkt-try-ss? argument defaults to #t. If it is not
#f, then if path ends in ".rkt", then the
corresponding file ending in ".ss" will be tried as well.
The choose-proc argument is a procedure that takes three
paths: a source path, a ".zo" file path, and an extension path
(for a non-_loader extension). Some of the paths may not
exist. The result should be either 'src, 'zo,
'so, or #f, indicating which variant should be used
or (in the case of #f) that the default choice should be
The default choice is computed as follows: if a ".zo" version
of path is available and newer than path itself (in
one of the directories specified by compiled-subdir), then it
is used instead of the source. Native-code versions of path
are ignored, unless only a native-code non-_loader version exists
(i.e., path itself does not exist). A _loader extension
is selected a last resort.
If an extension is preferred or is the only file that exists, it is
supplied to ext-proc when ext-proc is #f,
or an exception is raised (to report that an extension file cannot be
used) when ext-proc is #f.
If notify-proc is supplied, it is called for the file
(source, ".zo" or extension) that is chosen.
If read-syntax-proc is provided, it is used to read the
module from a source file (but not from a bytecode file).
|(get-module-path|| ||path|| |
| || ||#:submodule? submodule?|| |
| || [||#:sub-path compiled-subdir0|| |
| || ||compiled-subdir|| |
| || ||#:roots roots|| |
| || ||#:choose choose-proc|| |
| || ||#:rkt-try-ss? rkt-try-ss?])|| |
| path : path-string?|
| submodule? : boolean?|
| ||choose-proc|| ||:|| |
| || || ||=|| ||(lambda (src zo so) #f)|
| rkt-try-ss? : boolean? = #t|
Produces two values. The first is the path of the latest source or compiled
file for the module specified by path
; this result is the path of the
file that get-module-code
would read to produce a compiled module
expression. The second value is 'src
, or 'so
depending on whether the first value represents a Racket source file, a
compiled bytecode file, or a native library file.
The compiled-subdir, roots, choose-proc, and
rkt-try-ss? arguments are interpreted the same as by
The submodule? argument represents whether the desired module is a
submodule of the one specified by path. When submodule? is
true, the result is never a 'so path, as native libraries cannot
Constructs the path used to store compilation metadata for a source file stored
in the directory path
. The argument roots
possible root directories to consider and to search for an existing file. The
arguments specify the subdirectories and filename of the
result relative to the chosen root. For example, the compiled ".zo"
file for "/path/to/source.rkt"
might be stored in
(get-metadata-path (build-path "/path/to") "compiled" "source_rkt.zo")
A parameter whose value is used like open-input-file
a module source or ".zo"
4.3 Resolving Module Paths to File Paths
Resolves a module path to filename path. The module path is resolved
relative to rel-to-path-v if it is a path string (assumed to
be for a file), to the directory result of calling the thunk if it is
a thunk, or to the current directory otherwise.
but the input is a module path index
; in this case, the rel-to-path-v
base is used where the module path index contains the “self” index.
depends on the “self” module path
index, then an exception is raised unless rel-to-path-v
'(submod #<path:banana.rkt> test)
4.4 Simplifying Module Paths
Returns a “simplified” module path by combining
, where the
latter must have one of the following forms: a '(lib ....)
symbol module path; a '(file ....)
module path; a
module path; a path
a '(submod base symbol ...)
would be allowed; or a thunk to generate one of those.
The result can be a path if module-path-v contains a path
element that is needed for the result, or if
rel-to-module-path-v is a non-string path that is needed for
the result. Similarly, the result can be 'submod wrapping a
path. Otherwise, the result is a module path (in the sense of
module-path?) that is not a plain filesystem path.
When the result is a 'lib or 'planet module path, it
is normalized so that equivalent module paths are represented by
equal? results. When the result is a 'submod module
path, it contains only symbols after the base module path, and the
base is normalized in the case of a 'lib or 'planet
When given a single argument, collapse-module-path-index
returns a module path that is relative if the given module path index
is relative, except that it returns #f if its argument is the
“self” module path index. A resulting module path is
not necessarily normalized.
Changed in version 22.214.171.124 of package base: Added the one-argument variant for
collapsing a relative module path
Changed in version 126.96.36.199: Added support for the “self” module
path index as the only argument, which
meant extending the result contract to
4.5 Inspecting Modules and Module Dependencies
and syntax/modresolve, in addition to the following:
A debugging aid that prints the import hierarchy starting from a given
4.6 Wrapping Module-Body Expressions
Added in version 188.8.131.52 of package base.
Constructs a function that is suitable for use as a
#%module-begin replacement, particularly to replace the
facet of #%module-begin that wraps each top-level
expression to print the expression’s result(s).
The function takes a syntax object and returns a syntax object using
module-begin-form. Assuming that module-begin-form
resembles #%plain-module-begin, each top-level expression
expr will be wrapped as (wrap-form expr), while
top-level declarations (such as define-values and
require forms) are left as-is. Expressions are detected after
macro expansion and begin splicing, and expansion is
interleaved with declaration processing as usual.