14.1 Namespaces (original) (raw)
14.1 Namespaces🔗ℹ
See Namespaces for basic information on thenamespace model.
A new namespace is created with procedures likemake-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 andeval-syntax.
Returns #t if v is a namespace value, #fotherwise.
Creates a new namespace that is empty, and whose module registry contains only mappings for some internal, predefined modules, such as '#%kernel. The namespace’s base phase is the same as the base phase of the current namespace. Attach modules from an existing namespace to the new one with namespace-attach-module.
The new namespace is associated with a new root namespace, which has the same module registry as the returned namespace and has a base phase of 0. The new root namespace is the same as the returned namespace if both have base phase 0.
Creates a new empty namespace like make-empty-namespace, but with racket/baseattached. The namespace’s base phase is the same as thephase in which the make-base-empty-namespacefunction was created.
Creates a new namespace like make-empty-namespace, but with racket/base attached andrequired into the top-level environment. The namespace’sbase phase is the same as the phase in which themake-base-namespace function was created.
Binds id to a namespace anchor that can be used withnamespace-anchor->empty-namespace andnamespace-anchor->namespace.
This form can be used only in a top-level context or in amodule-context.
Returns #t if v is a namespace-anchor value,#f otherwise.
Returns an empty namespace that shares a module registryand root namespace with the source of the anchor, and whose base phase is thephase in which the anchor was created.
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 adefine-namespace-anchor form in a top-level content, then the source is the namespace in which the anchor definition was evaluated.
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 for the module’s body in the anchor’s phase. The result is the same as a namespace obtained via module->namespace, and the module is similarly madeavailable if it is not available already.
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.
Similar to datum->syntax restricted to symbols. Thelexical information of the resulting identifier corresponds to the top-level environment of the current namespace; the identifier has no source location or properties.
Returns an identifier whose binding is module in thebase phase of where if it is a namespace, or in thewhere phase level otherwise.
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.
(namespace-variable-value sym [use-mapping? failure-thunk namespace]) → any sym : symbol? use-mapping? : any/c = #t failure-thunk : (or/c (-> any) #f) = #f namespace : namespace? = (current-namespace)
Returns a value for sym in namespace, usingnamespace’s base phase. The returned value depends onuse-mapping?:
- If use-mapping? is true (the default), and ifsym 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, thenfailure-thunk is called or theexn: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 anexn:fail:contract:variable or exn:fail:syntaxexception.
Sets the value of sym in the top-level environment ofnamespace in the base phase, defining sym if it is not already defined.
If map? is supplied as true, then the namespace’sidentifier mapping is also adjusted (seeNamespaces) in the phase level corresponding to the base phase, so that sym maps to the variable.
If as-constant? is true, then the variable is made a constant (so future assignments are rejected) after v is installed as the value.
Changed in version 6.90.0.14 of package base: Added the as-constant? argument.
Removes the sym variable, if any, in the top-level environment of namespace in its base phase. The namespace’s identifier mapping (see Namespaces) is unaffected.
Returns a list of all symbols that are mapped to variables, syntax, and imports in namespace for the phase levelcorresponding to the namespace’s base phase.
(namespace-require quoted-raw-require-spec [namespace]) → void? quoted-raw-require-spec : any/c namespace : namespace? = (current-namespace)
Performs the import corresponding to quoted-raw-require-specin the top-level environment of namespace, like a top-level #%require. The quoted-raw-require-specargument must be either a datum that corresponds to a quotedraw-require-spec for #%require, which includes module paths, or it can be a resolved module path.
Module paths in quoted-raw-require-spec are resolved with respect to current-load-relative-directory orcurrent-directory (if the former is #f), even if the current namespace corresponds to a module body.
Changed in version 6.90.0.16 of package base: Added the namespace optional argument.
(namespace-require/copy quoted-raw-require-spec [namespace]) → void? quoted-raw-require-spec : any/c namespace : namespace? = (current-namespace)
Like namespace-require for syntax exported from the module, but exported variables at the namespace’s base phase are treated differently: the export’s current value is copied to a top-level variable in namespace.
Changed in version 6.90.0.16 of package base: Added the namespace optional argument.
(namespace-require/constant quoted-raw-require-spec [namespace]) → void? quoted-raw-require-spec : any/c namespace : namespace? = (current-namespace)
Like namespace-require, but for each exported variable at thenamespace’s base phase, 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.
Changed in version 6.90.0.16 of package base: Added the namespace optional argument.
(namespace-require/expansion-time quoted-raw-require-spec [namespace]) → void? quoted-raw-require-spec : any/c namespace : namespace? = (current-namespace)
Like namespace-require, but only the transformer part of the module is executed relative to namespace’s base phase; that is, the module is merely visited, and notinstantiated (see Module Expansion, Phases, and Visits). If the required module has not been instantiated before, the module’s variables remain undefined.
Changed in version 6.90.0.16 of package base: Added the namespace optional argument.
Attaches the instantiated module named by modname in src-namespace (at its base phase) to themodule registry of dest-namespace.
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 are also attached todest-namespace (while visits at the module’s phase and instances at higher or lower phases are not attached, nor even made available for on-demandvisits). The inspector of the module invocation indest-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 aninstantiated module in src-namespace, or if the name of any module to be attached already has a different declaration or same-phase instance indest-namespace, then theexn:fail:contract exception is raised.
If src-namespace and dest-namespace do not have the same base phase, then theexn:fail:contract exception is raised.
Unlike namespace-require,namespace-attach-module does notinstantiate the module, but copies the module instance from the source namespace to the target namespace.
Examples:
> (namespace-require ''food) > (define ns (current-namespace)) require: unknown module module name: 'food #t #f
Like namespace-attach-module, but the module specified by modname need only be declared (and not necessarily instantiated) in src-namespace, and the module is merely declared in dest-namespace.
Changes the inspector for the instance of the module referenced bymodname in namespace’s module registry so that it is controlled by the current code inspector. The giveninspector must currently control the invocation of the module in namespace’s module registry, otherwise the inspector is not changed. See also Code Inspectors.
Returns the module registry of the given namespace. This value is useful only for identification via eq?.
Calls thunk while holding a reentrant lock for the namespace’smodule registry.
Namespace functions do not automatically use the registry lock, but it can be used via namespace-call-with-registry-lock among threads that load and instantiate modules to avoid internal race conditions. On-demand instantiation of available modules also takes the lock; see Module Expansion, Phases, and Visits.
Added in version 8.1.0.5 of package base.
(module->namespace mod [src-namespace]) → namespace? src-namespace : namespace? = (current-namespace)
Returns a namespace that corresponds to the body of an instantiated module in src-namespace’s module registry and in thesrc-namespace’s base phase, making the moduleavailable for on-demand visits at src-namespace’sbase phase. The returned namespace has the same module registry as src-namespace. Modifying a binding in the resulting 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 providedeclarations are not allowed.
If the current code inspector does not control the invocation of the module in src-namespace’s module registry, theexn:fail:contract exception is raised; see also Code Inspectors.
Bindings in the result namespace cannot be modified if thecompile-enforce-module-constants parameter was true when the module was declared, unless the module declaration itself included assignments to the binding via set!.
Changed in version 6.90.0.16 of package base: Added the src-namespace optional argument.
Changed in version 6.90.0.16 of package base: Added the namespace optional argument.
Returns #f if the module declaration formodule-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; seeCompiled 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 byidentifier-binding.
Returns #t if the variable represented by varrefwill retain its current value (i.e., varref refers to a variable that cannot be further modified by set! ordefine), #f otherwise.
Returns an empty namespace that shares module declarations and instances with the namespace in which varref is instantiated, and with the same phase as varref.
If varref refers to a module-level variable, then the result is a namespace for the module’s body in the referenced variable’s phase; the result is the same as a namespace obtained via module->namespace, and the module is similarly madeavailable if it is not available already.
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 module-level variable, the result is a path or symbol naming the module’s source (which is typically, but not always, the same as in the resolved module path). If the relevant module is a submodule, the result corresponds to the enclosing top-level module’s source.
If varref refers to a top-level variable, then the result is #f.
Returns the phase of the variable referenced by varref.
Returns the phase in which the module is instantiated for the variable referenced by varref, or 0 if the variable for varref is not within a module.
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.
Returns #t if the module of the variable reference itself (not necessarily a referenced variable) is compiled in unsafe mode,#f otherwise. Unsafe mode can be enabled through thelinklet interface or enable for a module with(#%declare #:unsafe).
The variable-reference-from-unsafe? procedure is intended for use as
which the compiler can optimize to a literal #t or#f (since the enclosing module is being compiled inunsafe mode or not).
Added in version 6.12.0.4 of package base.