13.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.

(namespace? v) → boolean?

v : any/c

Returns #t if v is a namespace value, #f otherwise.

(make-empty-namespace) → namespace?

Creates a new namespace that is empty, and whose module registry contains no mappings. Attach modules from an existing namespace to the new one with namespace-attach-module.

(make-base-empty-namespace) → namespace?

Creates a new empty namespace, but with scheme/base attached.

(make-base-namespace) → namespace?

Creates a new namespace with scheme/base attached and required into the top-level environment.

(define-namespace-anchor id)

Binds id to a namespace anchor that can be used with namespace-anchor->empty-namespace and namespace-anchor->namespace.

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

(namespace-anchor? v) → boolean?

v : any/c

Returns #t if v is a namespace-anchor value, #f otherwise.

(namespace-anchor->empty-namespace a) → namespace?

a : namespace-anchor?

Returns an empty namespace that shares a module registry with the source of the anchor.

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. The resulting namespace corresponds to phase 0, independent of the phase of a’s definition.

(namespace-anchor->namespace a) → namespace?

a : namespace-anchor?

Returns a namespace corresponding to the source of the anchor.

If the anchor is from a define-namespace-anchor form in a module context, then the result is a namespace obtained via module->namespace using the resolved name of the enclosing module and the module registry of the module instance at phase 0.

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.

(current-namespace) → namespace?

(current-namespace n) → void?

n : namespace?

A parameter that determines the current namespace.

(namespace-symbol->identifier sym) → identifier?

sym : symbol?

Similar to datum->syntax restricted to symbols. The lexical context of the resulting identifier corresponds to the top-level environment of the current namespace; the identifier has no source location or properties.

(namespace-variable-value   sym            [ use-mapping?             failure-thunk             namespace])   →   any

sym : symbol?

use-mapping? : any/c = #t

failure-thunk : (or/c (-> any) false/c) = #f

namespace : namespace? = (current-namespace)

Returns a value for sym in namespace. The returned value depends on use-mapping?:

• 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.

(namespace-set-variable-value!   sym             v            [ map?             namespace])   →   void?

sym : symbol?

v : any/c

map? : any/c = #f

namespace : namespace? = (current-namespace)

Sets the value of sym in the top-level environment of namespace for phase level 0, defining sym if it is not already defined.

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

(namespace-undefine-variable!   sym            [ namespace])   →   void?

sym : symbol?

namespace : namespace? = (current-namespace)

Removes the sym variable, if any, in the top-level environment of namespace at phase level 0. The namespace’s identifier mapping (see Namespaces) is unaffected.

(namespace-mapped-symbols [namespace]) → (listof symbol?)

namespace : namespace? = (current-namespace)

Returns a list of all symbols that are mapped to variables, syntax, and imports in namespace for phase level 0.

(namespace-require quoted-raw-require-spec) → void?

quoted-raw-require-spec : any/c

Performs the import corresponding to quoted-raw-require-spec in the top-level environment of the current namespace, like a top-level #%require. The quoted-raw-require-spec argument must be a datum that corresponds to a quoted raw-require-spec for #%require, which includes module paths.

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.

(namespace-require/copy quoted-raw-require-spec) → void?

quoted-raw-require-spec : any/c

Like namespace-require for syntax exported from the module, but exported variables at phase level 0 are treated differently: the export’s current value is copied to a top-level variable in the current namespace.

(namespace-require/constant quoted-raw-require-spec) → void?

quoted-raw-require-spec : any/c

Like namespace-require, but for each exported variable at phase level 0, the export’s value is copied to a corresponding top-level variable that is made immutable. Despite setting the top-level variable, the corresponding identifier is bound as imported.

(namespace-require/expansion-time quoted-raw-require-spec)

→ void?

quoted-raw-require-spec : any/c

Like namespace-require, but only the transformer part of the module is executed; that is, the module is merely visited, and not instantiated (see Module Phases). If the required module has not been instantiated before, the module’s variables remain undefined.

(namespace-attach-module   src-namespace             modname            [ dest-namespace])   →   any

src-namespace : namespace?

modname : module-path?

dest-namespace : namespace? = (current-namespace)

Attaches the instantiated module named by modname in src-namespace to the module registry of dest-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. In addition to modname, every module that it imports (directly or indirectly) is also recorded in the current namespace’s module registry. 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 instance in dest-namespace, then the exn:fail:contract exception is raised. The inspector of the module invocation in dest-namespace is the same as inspector of the invocation in src-namespace.

(namespace-unprotect-module   inspector             modname            [ namespace])   →   void?

inspector : inspector?

modname : module-path?

namespace : namespace? = (current-namespace)

Changes the inspector for the instance of the module referenced by modname in namespace’s module registry so that it is controlled by the current code inspector. The given inspector must currently control the invocation of the module in namespace’s module registry, otherwise the exn:fail:contract exception is raised. See also Code Inspectors.

(namespace-module-registry namespace) → any

namespace : namespace?

Returns the module registry of the given namespace. This value is useful only for identification via eq?.

(module->namespace modname) → namespace?

modname : module-path?

Returns a namespace that corresponds to the body of an instantiated module in the current namespace’s module registry. The returned namespace has the same module registry as the current namespace. Modifying a binding in the namespace changes the binding seen in modules that require the namespace’s module.

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!.

(namespace-syntax-introduce stx) → syntax-object?

stx : syntax-object?

Returns a syntax object like stx, except that the current namespace’s bindings are included in the syntax object’s lexical information (see Syntax Objects). The additional context is overridden by any existing top-level bindings in the syntax object’s lexical information, or by any existing or future module bindings in the lexical information.

(module-provide-protected?   module-path-index             sym)   →   boolean?

module-path-index : (or/c symbol? module-path-index?)

sym : symbol?

Returns #f if the module declaration for module-path-index defines sym and exports it unprotected, #t otherwise (which may mean that the symbol corresponds to an unexported definition, a protected export, or an identifier that is not defined at all within the module).

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.

(variable-reference->empty-namespace varref) → namespace?

varref : variable-reference?

Returns an empty namespace that shares module declarations and instances with the namespace in which varref is instantiated. The namespace corresponds to phase 0, independent of the phase of varref’s binding.

(variable-reference->top-level-namespace varref) → namespace?

varref : variable-reference?

If varref refers to a top-level binding, the result is varref’s namespace if it corresponds to a phase 0 binding, otherwise it is the phase 0 namespace associated with varref’s namespace.

If varref refers to a module binding, then the exn:fail:contract exception is raised.

(variable-reference->resolved-module-path varref)

→ resolved-module-path?

varref : variable-reference?

If varref refers to a module binding, the result is a resolved module path naming the module.

If varref refers to a top-level binding, then the exn:fail:contract exception is raised.