4 Namespaces and Modules

A Scheme namespace (a top-level environment) is represented by a value of type Scheme_Env* – which is also a Scheme value, castable to Scheme_Object*. Calling scheme_basic_env returns a namespace that includes all of Scheme’s standard global procedures and syntax.

The scheme_basic_env function must be called once by an embedding program, before any other PLT Scheme 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 Scheme thread. Scheme 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 Scheme 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 prefixing through the current-module-name-prefix 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 Scheme #%variable-reference form produces a value that is opaque to Scheme 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).

void   scheme_add_global ( char* name,         Scheme_Object* val,         Scheme_Env* env)

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

void   scheme_add_global_symbol ( Scheme_Object* name,         Scheme_Object* val,         Scheme_Env* env)

Adds a value to the table of globals by symbol name instead of string name.

Scheme_Object*   scheme_lookup_global ( Scheme_Object* symbol,         Scheme_Env* env)

Given a global variable name (as a symbol) in sym, returns the current value.

Scheme_Bucket*   scheme_global_bucket ( Scheme_Object* symbol,         Scheme_Env* env)

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 Scheme. The pos argument should be -1 always. The env argument represents the namespace in which the module is declared.

void   scheme_set_global_bucket ( char* procname,         Scheme_Bucket* var,         Scheme_Object* val,         int set_undef)

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

Scheme_Object*   scheme_builtin_value ( const char* name)

Gets the binding of a name as it would be defined in the initial namespace.

Scheme_Env*   scheme_get_env ( Scheme_Config* config)

Returns the current namespace for the given parameterization (see Parameterizations). The current thread’s current parameterization is available as scheme_config.

Scheme_Env*   scheme_primitive_module ( Scheme_Object* name,         Scheme_Env* for_env)

Prepares a new primitive module whose name is the symbol name (plus any prefix that is active via current-module-name-prefix). 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.

void   scheme_finish_primitive_module ( Scheme_Env* env)

Finalizes a primitive module and makes it available for use within the module’s namespace.