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

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 Racket. 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 (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.

void

 

scheme_finish_primitive_module

(

Scheme_Env* env)

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