146 lines
5.6 KiB
Racket
146 lines
5.6 KiB
Racket
#lang scribble/doc
|
|
@(require "utils.ss")
|
|
|
|
@title[#:tag "im:env"]{Namespaces and Modules}
|
|
|
|
A Scheme namespace (a top-level environment) is represented by a value
|
|
of type @cppi{Scheme_Env*} --- which is also a Scheme value, castable
|
|
to @cpp{Scheme_Object*}. Calling @cppi{scheme_basic_env} returns a
|
|
namespace that includes all of Scheme's standard global procedures
|
|
and syntax.
|
|
|
|
The @cpp{scheme_basic_env} function must be called once by an
|
|
embedding program, before any other PLT Scheme function is called
|
|
(except @cpp{scheme_make_param}), but @cpp{scheme_main_setup}
|
|
automatically calls @cpp{scheme_basic_env}. The returned namespace is
|
|
the initial current namespace for the main Scheme thread. Scheme
|
|
extensions cannot call @cpp{scheme_basic_env}.
|
|
|
|
The current thread's current namespace is available from
|
|
@cppi{scheme_get_env}, given the current parameterization (see
|
|
@secref["config"]): @cpp{scheme_get_env(scheme_config)}.
|
|
|
|
New values can be added as @as-index{globals} in a namespace using
|
|
@cppi{scheme_add_global}. The @cppi{scheme_lookup_global} function
|
|
takes a Scheme symbol and returns the global value for that name, or
|
|
@cpp{NULL} if the symbol is undefined.
|
|
|
|
A @as-index{module}'s set of top-level bindings is implemented using
|
|
the same machinery as a namespace. Use @cppi{scheme_primitive_module}
|
|
to create a new @cpp{Scheme_Env*} that represents a primitive
|
|
module. The name provided to @cppi{scheme_primitive_module} is subject
|
|
to prefixing through the @scheme[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
|
|
@cppi{scheme_add_global}, etc., call
|
|
@cppi{scheme_finish_primitive_module} on the @cpp{Scheme_Env*} value
|
|
to make the module declaration available. All defined variables are
|
|
exported from the primitive module.
|
|
|
|
The Scheme @indexed-scheme[#%variable-reference] form produces a value
|
|
that is opaque to Scheme code. Use @cpp{SCHEME_PTR_VAL} on the result
|
|
of @scheme[#%variable-reference] to obtain the same kind of value as
|
|
returned by @cpp{scheme_global_bucket} (i.e., a bucket containing the
|
|
variable's value, or @cpp{NULL} if the variable is not yet defined).
|
|
|
|
@; ----------------------------------------------------------------------
|
|
|
|
@function[(void scheme_add_global
|
|
[char* name]
|
|
[Scheme_Object* val]
|
|
[Scheme_Env* env])]{
|
|
|
|
Adds a value to the table of globals for the namespace @var{env},
|
|
where @var{name} is a null-terminated string. (The string's case will
|
|
be normalized in the same way as for interning a symbol.)}
|
|
|
|
@function[(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.}
|
|
|
|
@function[(Scheme_Object* scheme_lookup_global
|
|
[Scheme_Object* symbol]
|
|
[Scheme_Env* env])]{
|
|
|
|
Given a global variable name (as a symbol) in @var{sym}, returns the current
|
|
value.}
|
|
|
|
@function[(Scheme_Bucket* scheme_global_bucket
|
|
[Scheme_Object* symbol]
|
|
[Scheme_Env* env])]{
|
|
|
|
Given a global variable name (as a symbol) in @var{sym}, returns the bucket
|
|
where the value is stored. When the value in this bucket is @cpp{NULL}, then
|
|
the global variable is undefined.
|
|
|
|
The @cppi{Scheme_Bucket} structure is defined as:
|
|
|
|
@verbatim[#:indent 2]{
|
|
typedef struct Scheme_Bucket {
|
|
Scheme_Object so; /* so.type = scheme_variable_type */
|
|
void *key;
|
|
void *val;
|
|
} Scheme_Bucket;
|
|
}}
|
|
|
|
@function[(Scheme_Bucket* scheme_module_bucket
|
|
[Scheme_Object* mod]
|
|
[Scheme_Object* symbol]
|
|
[int pos]
|
|
[Scheme_Env* env])]{
|
|
|
|
Like @cpp{scheme_global_bucket}, but finds a variable in a
|
|
module. The @var{mod} and @var{symbol} arguments are as for
|
|
@scheme[dynamic-require] in Scheme. The @var{pos} argument should be
|
|
@cpp{-1} always. The @var{env} argument represents the namespace in
|
|
which the module is declared.}
|
|
|
|
@function[(void scheme_set_global_bucket
|
|
[char* procname]
|
|
[Scheme_Bucket* var]
|
|
[Scheme_Object* val]
|
|
[int set_undef])]{
|
|
|
|
Changes the value of a global variable. The @var{procname} argument is
|
|
used to report errors (in case the global variable is constant, not
|
|
yet bound, or bound as syntax). If @var{set_undef} is not 1, then the
|
|
global variable must already have a binding. (For example,
|
|
@scheme[set!] cannot set unbound variables, while @scheme[define]
|
|
can.)}
|
|
|
|
@function[(Scheme_Object* scheme_builtin_value
|
|
[const-char* name])]{
|
|
|
|
Gets the binding of a name as it would be defined in the initial
|
|
namespace.}
|
|
|
|
@function[(Scheme_Env* scheme_get_env
|
|
[Scheme_Config* config])]{
|
|
|
|
Returns the current namespace for the given parameterization (see
|
|
@secref["config"]). The current thread's current parameterization is
|
|
available as @cppi{scheme_config}.}
|
|
|
|
@function[(Scheme_Env* scheme_primitive_module
|
|
[Scheme_Object* name]
|
|
[Scheme_Env* for_env])]{
|
|
|
|
Prepares a new primitive module whose name is the symbol @var{name} (plus any
|
|
prefix that is active via @scheme[current-module-name-prefix]). The
|
|
module will be declared within the namespace @var{for_env}. The
|
|
result is a @cpp{Scheme_Env *} value that can be used with
|
|
@cpp{scheme_add_global}, etc., but it represents a module instead
|
|
of a namespace. The module is not fully declared until
|
|
@cpp{scheme_finish_primitive_module} is called, at which point all
|
|
variables defined in the module become exported.}
|
|
|
|
@function[(void scheme_finish_primitive_module
|
|
[Scheme_Env* env])]{
|
|
|
|
Finalizes a primitive module and makes it available for use within the
|
|
module's namespace.}
|