► |  | Inside: Racket C API

I | Inside Racket CS
II | Inside Racket BC (3m and CGC)
III | Appendices
| Index

▼ | II | Inside Racket BC (3m and CGC)

8 | Overview (BC)
9 | Embedding into a Program (BC)
10 | Writing Racket Extensions (BC)
11 | Values and Types (BC)
12 | Memory Allocation (BC)
13 | Namespaces and Modules (BC)
14 | Procedures (BC)
15 | Evaluation (BC)
16 | Exceptions and Escape Continuations (BC)
17 | Threads (BC)
18 | Parameterizations (BC)
19 | Continuation Marks (BC)
20 | String Encodings (BC)
21 | Bignums, Rationals, and Complex Numbers (BC)
22 | Ports and the Filesystem (BC)
23 | Structures (BC)
24 | Security Guards (BC)
25 | Custodians (BC)
26 | Subprocesses (BC)
27 | Miscellaneous Utilities (BC)

top ← prev up next →

### 13`` Namespaces and Modules (BC)

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 (BC)): 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 (BC)). 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.
top ← prev up next →