14.1 Namespaces

See Namespaces for basic information on the namespace model.

A new namespace is created with procedures like make-empty-namespace, and make-base-namespace, which return a first-class namespace value. A namespace is used by setting the current-namespace parameter value, or by providing the namespace to procedures such as eval and eval-syntax.

This form can be used only in a top-level context or in a module-context.

If the anchor is from a define-namespace-anchor form in a module context, then the source is the namespace in which the containing module is instantiated. If the anchor is from a define-namespace-anchor form in a top-level content, then the source is the namespace in which the anchor definition was evaluated.

If the anchor is from a define-namespace-anchor form in a module context, then the result is a namespace for the module’s body in the anchor’s phase. The result is the same as a namespace obtained via module->namespace.

If the anchor is from a define-namespace-anchor form in a top-level content, then the result is the namespace in which the anchor definition was evaluated.

The lexical information of the identifier includes bindings (in the same phase level) for all syntactic forms that appear in fully expanded code (see Fully Expanded Programs), but using the name reported by the second element of identifier-binding for the binding; the lexical information may also include other bindings.

• If use-mapping? is true (the default), and if sym maps to a top-level variable or an imported variable (see Namespaces), then the result is the same as evaluating sym as an expression. If sym maps to syntax or imported syntax, then failure-thunk is called or the exn:fail:syntax exception is raised. If sym is mapped to an undefined variable or an uninitialized module variable, then failure-thunk is called of the exn:fail:contract:variable exception is raised.

• If use-mapping? is #f, the namespace’s syntax and import mappings are ignored. Instead, the value of the top-level variable named sym in namespace is returned. If the variable is undefined, then failure-thunk is called or the exn:fail:contract:variable exception is raised.

If failure-thunk is not #f, namespace-variable-value calls failure-thunk to produce the return value in place of raising an exn:fail:contract:variable or exn:fail:syntax exception.

If map? is supplied as true, then the namespace’s identifier mapping is also adjusted (see Namespaces) in the phase level corresponding to the base phase, so that sym maps to the variable.

Module paths in quoted-raw-require-spec are resolved with respect to current-load-relative-directory or current-directory (if the former is #f), even if the current namespace corresponds to a module body.

In addition to modname, every module that it imports (directly or indirectly) is also recorded in the current namespace’s module registry, and instances at the same phase or lower are also attached to dest-namespace (while visits at the module’s phase and instances at higher phases are not attached, nor even made available for on-demand visits). The inspector of the module invocation in dest-namespace is the same as inspector of the invocation in src-namespace.

If modname is not a symbol, the current module name resolver is called to resolve the path, but no module is loaded; the resolved form of modname is used as the module name in dest-namespace.

If modname refers to a submodule or a module with submodules, unless the module was loaded from bytecode (i.e., a ".zo" file) independently from submodules within the same top-level module, then declarations for all submodules within the module’s top-level module are also attached to dest-namespace.

If modname does not refer to an instantiated module in src-namespace, or if the name of any module to be attached already has a different declaration or same-phase instance in dest-namespace, then the exn:fail:contract exception is raised.

If src-namespace and dest-namespace do not have the same base phase, then the exn:fail:contract exception is raised.

Module paths in a top-level require expression are resolved with respect to the namespace’s module. New provide declarations are not allowed.

If the current code inspector does not control the invocation of the module in the current namespace’s module registry, the exn:fail:contract exception is raised; see also Code Inspectors.

Bindings in the namespace cannot be modified if the compile-enforce-module-constants parameter was true when the module was declared, unless the module declaration itself included assignments to the binding via set!.

The module-path-index argument can be a symbol; see Compiled Modules and References for more information on module path indices.

Typically, the arguments to module-provide-protected? correspond to the first two elements of a list produced by identifier-binding.

If varref refers to a top-level variable, then the result is the namespace in which the referenced variable is defined.

If varref refers to a top-level variable, then the result is #f.

If varref refers to a top-level variable, then the result is #f.

If varref refers to a top-level variable, then the result is #f.

For a variable with a module, the result is less than the result of (variable-reference->phase varref) by n when the variable is bound at phase level n within the module.