6 Namespaces and Modules
A Racket namespace (a top-level environment) is represented by a value
of type Scheme_Env* — which is also a Racket value, castable
to Scheme_Object*. Calling scheme_basic_env returns a
namespace that includes all of Racket’s standard global procedures
and syntax.
The scheme_basic_env function must be called once by an
embedding program, before any other Racket function is called
(except scheme_make_param), but scheme_main_setup
automatically calls scheme_basic_env. The returned namespace is
the initial current namespace for the main Racket thread. Racket
extensions cannot call scheme_basic_env.
The current thread’s current namespace is available from
scheme_get_env, given the current parameterization (see
Parameterizations): scheme_get_env(scheme_config).
New values can be added as globals in a namespace using
scheme_add_global. The scheme_lookup_global function
takes a Racket symbol and returns the global value for that name, or
NULL if the symbol is undefined.
A module’s set of top-level bindings is implemented using
the same machinery as a namespace. Use scheme_primitive_module
to create a new Scheme_Env* that represents a primitive
module. The name provided to scheme_primitive_module is subject
to change through the current-module-declare-name parameter
(which is normally set by the module name resolver when auto-loading
module files). After installing variables into the module with
scheme_add_global, etc., call
scheme_finish_primitive_module on the Scheme_Env* value
to make the module declaration available. All defined variables are
exported from the primitive module.
The Racket #%variable-reference form produces a value
that is opaque to Racket code. Use SCHEME_PTR_VAL on the result
of #%variable-reference to obtain the same kind of value as
returned by scheme_global_bucket (i.e., a bucket containing the
variable’s value, or NULL if the variable is not yet defined).
Adds a value to the table of globals for the namespace env,
where name is a null-terminated string. (The string’s case will
be normalized in the same way as for interning a symbol.)
Adds a value to the table of globals by symbol name instead of string
name.
Given a global variable name (as a symbol) in sym, returns the current
value.
Given a global variable name (as a symbol) in sym, returns the bucket
where the value is stored. When the value in this bucket is NULL, then
the global variable is undefined.
The Scheme_Bucket structure is defined as:
typedef struct Scheme_Bucket { |
Scheme_Object so; /* so.type = scheme_variable_type */ |
void *key; |
void *val; |
} Scheme_Bucket; |
Scheme_Bucket* | | scheme_module_bucket | ( | Scheme_Object* mod, | | | | | Scheme_Object* symbol, | | | | | int pos, | | | | | Scheme_Env* env) |
|
Like
scheme_global_bucket, but finds a variable in a
module. The
mod and
symbol arguments are as for
dynamic-require in Racket. The
pos argument should be
-1 always. The
env argument represents the namespace in
which the module is declared.
Changes the value of a global variable. The
procname argument is
used to report errors (in case the global variable is constant, not
yet bound, or bound as syntax). If
set_undef is not 1, then the
global variable must already have a binding. (For example,
set! cannot set unbound variables, while
define
can.)
Gets the binding of a name as it would be defined in the initial
namespace.
Returns the current namespace for the given parameterization (see
Parameterizations). The current thread’s current parameterization is
available as
scheme_config.
Prepares a new primitive module whose name is the symbol
name (or an
alternative that is active via
current-module-declare-name). The
module will be declared within the namespace
for_env. The
result is a
Scheme_Env * value that can be used with
scheme_add_global, etc., but it represents a module instead
of a namespace. The module is not fully declared until
scheme_finish_primitive_module is called, at which point all
variables defined in the module become exported.
Finalizes a primitive module and makes it available for use within the
module’s namespace.