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 MzScheme's standard global procedures and syntax.

The scheme_basic_env function must be called once by an embedding program, before any other MzScheme function is called (except scheme_make_param). The returned namespace is the initial current namespace for the main MzScheme thread. MzScheme extensions cannot call scheme_basic_env.

The current thread's current namespace is available from scheme_get_env, given the current parameterization (see section 9): 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).

4.1  Library Functions

¤ 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 section 9 for more information. 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.