4 Module-Processing Helpers
4.1 Reading Module Source Code
Calls thunk with all reader parameters reset to their default
values.
Inspects
stx to check whether evaluating it will declare a
module—
at least if
module is bound in the top-level to
Racket’s
module. 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
| (get-module-code | | path | | | | | | | [ | #:submodule-path submodule-path | | | | | | | | #:sub-path compiled-subdir0 | | | | | | | | compiled-subdir | | | | | | | | #:roots roots | | | | | | | | #:compile compile-proc0 | | | | | | | | compile-proc | | | | | | | | #:extension-handler ext-proc0 | | | | | | | | ext-proc | | | | | | | | #:notify notify-proc | | | | | | | | #:source-reader read-syntax-proc | | | | | | | | #:rkt-try-ss? rkt-try-ss? | | | | | | | | #:choose choose-proc]) | | → | | any |
|
| path : path-string? |
| submodule-path : (listof symbol?) = '() |
|
| | compiled-subdir | | : | | | | | | | = | | compiled-subdir0 |
|
|
| compile-proc0 : (any/c . -> . any) = compile |
| compile-proc : (any/c . -> . any) = compile-proc0 |
| ext-proc0 : (or/c false/c (path? boolean? . -> . any)) = #f |
|
| notify-proc : (any/c . -> . any) = void |
|
| rkt-try-ss? : boolean? = #t |
|
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
submodule.
The
roots,
compiled-subdir,
choose-proc, and
rkt-try-ss? and
submodule-path arguments determine which file is consulted
to find the compiled code. If the default values are provided,
then this function uses the same logic as the default
value of
current-load/use-compiled. In more detail:
If submodule-path is not the empty list, then the compiled code
will never be located in a dynamic extension;
instead the original source or a "zo" file will be used.
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 called with the
original source file (which might have had its ending
changed, c.f. the rkt-try-ss? argument) and two
other paths that end with "zo" and "so"
(but they are not necessarily the paths that
get-module-code uses). If the choose-proc
returns 'src, then compiled files are not used. If
it returns any other result, the result is ignored. In
previous versions of this function, the choose-proc offered more control over
which file was used but it no longer does;
the current interface is kept for backwards compatibility.
The compiled-subdir argument defaults to (use-compiled-file-paths);
it specifies the sub-directories to search for a compiled version of the
module. If compiled-subdir is a list, then the first directory
that contains a file with an appropriate name is used as the compiled file.
The roots list specifies a compiled-file search path
in the same way as the current-compiled-file-roots parameter;
it defaults to the current value of current-compiled-file-roots.
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
dynamic extension,
and a boolean indicating whether the extension is a _loader
file (#t) or not (#f).
If a dynamic 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
dynamic 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).
Changed in version 6.90.0.7 of package base: Use (default-compiled-sub-path)
for the default value of compiled-subdir.
Changed in version 8.6.0.12: Generalize the #:sub-path argument,
change #:sub-path’s default to (use-compiled-file-paths),
and pay less attention to the #:choose argument.
| (get-module-path | | path | | | | | #:submodule? submodule? | | | | [ | #:sub-path compiled-subdir0 | | | | | compiled-subdir | | | | | #:roots roots | | | | | #:rkt-try-ss? rkt-try-ss? | | | | | #:choose choose-proc]) | |
|
|
| path : path-string? |
| submodule? : boolean? |
|
| | compiled-subdir | | : | | | | | | | = | | compiled-subdir0 |
|
|
| rkt-try-ss? : boolean? = #t |
| choose-proc : any/c = #f |
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,
'zo, 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 get-module-code.
The submodule? argument represents whether the desired module is a
submodule of the one specified by path. When submodule? is
true, the result path never refers to a
dynamic extension
and the result symbol is never 'so, as native libraries cannot
provide submodules.
Changed in version 6.90.0.7 of package base: Use (default-compiled-sub-path)
for the default value of compiled-subdir.
Changed in version 8.6.0.12: Generalize the #:sub-path argument,
change #:sub-path’s default to (use-compiled-file-paths),
and pay less attention to the #:choose argument.
This function used to provide the default for the #:sub-path
argument to get-module-code and get-module-path, but
it is no longer used by this library.
Added in version 6.90.0.7 of package base.
Constructs the path used to store compilation metadata for a source file stored
in the directory
path. The argument
roots specifies the
possible root directories to consider and to search for an existing file. The
sub-path 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 to read
a module source or
".zo" file.
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.
When module-path-v refers to a module using a
collection-based path, resolution invokes the current module name resolver, but without loading the module even if it is not
declared. Beware that concurrent resolution in namespaces that share a
module registry can create race conditions when loading modules; see
also namespace-call-with-registry-lock.
Like
resolve-module-path 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.
If
module-path-index depends on the “self” module path
index, then an exception is raised unless
rel-to-path-v is a
path string.
See module-path-index-resolve.
Examples:
|
#<path:/home/scheme/pltbuild/racket/racket/collects/racket/main.rkt> |
|
#<path:/home/scheme/pltbuild/racket/build/user/8.11.1/pkgs/racket-doc/syntax/apple.rkt> |
|
'(submod #<path:banana.rkt> test) |
4.4 Simplifying Module Paths
Returns a “simplified” module path by combining
module-path-v with
rel-to-module-path-v, where the
latter must have one of the following forms: a
'(lib ....) or
symbol module path; a
'(file ....) module path; a
'(planet ....) module path; a
path;
'(quote symbol);
a
'(submod base symbol ...) module path
where
base 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
base.
Examples:
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 6.1.1.8 of package base: Added the one-argument variant for
collapsing a relative module path
index.
Changed in version 6.9.0.5: Added support for the “self” module
path index as the only argument, which
meant extending the result contract to
include #f
4.5 Inspecting Modules and Module Dependencies
Re-exports syntax/modread,
syntax/modcode, syntax/modcollapse,
and syntax/modresolve, in addition to the following:
A debugging aid that prints (by default) the import hierarchy starting
from a given module path. Supply an alternate
show function
to handle each path instead of having it printed; the second argument
is a result of
resolved-module-path-name.
If dag? is true, then a module is passed to show
only the first time is encountered in the hierarchy at a given phase.
If path-to-module-path-v is a module path, then only the
spines of the tree that reach path-to-module-path-v are
shown.
Changed in version 6.12.0.4 of package base: Added the #:dag? and
#:path-to arguments.
Changed in version 7.0.0.10: Added the #:show argument.
4.6 Wrapping Module-Body Expressions
Added in version 6.0.0.1 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.