6.20.10 Accessing Modules from C

The last sections have described how modules are used in Scheme code, which is the recommended way of creating and accessing modules. You can also work with modules from C, but it is more cumbersome.

The following procedures are available.

C Function: SCM scm_c_call_with_current_module (SCM module, SCM (*func)(void *), void *data)

Call func and make module the current module during the call. The argument data is passed to func. The return value of scm_c_call_with_current_module is the return value of func.

C Function: SCM scm_public_variable (SCM module_name, SCM name)

C Function: SCM scm_c_public_variable (const char *module_name, const char *name)

Find a the variable bound to the symbol name in the public interface of the module named module_name.

module_name should be a list of symbols, when represented as a Scheme object, or a space-separated string, in the const char * case. See scm_c_define_module below, for more examples.

Signals an error if no module was found with the given name. If name is not bound in the module, just returns #f.

C Function: SCM scm_private_variable (SCM module_name, SCM name)

C Function: SCM scm_c_private_variable (const char *module_name, const char *name)

Like scm_public_variable, but looks in the internals of the module named module_name instead of the public interface. Logically, these procedures should only be called on modules you write.

C Function: SCM scm_public_lookup (SCM module_name, SCM name)

C Function: SCM scm_c_public_lookup (const char *module_name, const char *name)

C Function: SCM scm_private_lookup (SCM module_name, SCM name)

C Function: SCM scm_c_private_lookup (const char *module_name, const char *name)

Like scm_public_variable or scm_private_variable, but if the name is not bound in the module, signals an error. Returns a variable, always.

static SCM eval_string_var;

/* NOTE: It is important that the call to 'my_init'
   happens-before all calls to 'my_eval_string'. */
void my_init (void)
{
  eval_string_var = scm_c_public_lookup ("ice-9 eval-string",
                                         "eval-string");
}

SCM my_eval_string (SCM str)
{
  return scm_call_1 (scm_variable_ref (eval_string_var), str);
}

C Function: SCM scm_public_ref (SCM module_name, SCM name)

C Function: SCM scm_c_public_ref (const char *module_name, const char *name)

C Function: SCM scm_private_ref (SCM module_name, SCM name)

C Function: SCM scm_c_private_ref (const char *module_name, const char *name)

Like scm_public_lookup or scm_private_lookup, but additionally dereferences the variable. If the variable object is unbound, signals an error. Returns the value bound to name in module_name.

In addition, there are a number of other lookup-related procedures. We suggest that you use the scm_public_ and scm_private_ family of procedures instead, if possible.

C Function: SCM scm_c_lookup (const char *name)

Return the variable bound to the symbol indicated by name in the current module. If there is no such binding or the symbol is not bound to a variable, signal an error.

C Function: SCM scm_lookup (SCM name)

Like scm_c_lookup, but the symbol is specified directly.

C Function: SCM scm_c_module_lookup (SCM module, const char *name)

C Function: SCM scm_module_lookup (SCM module, SCM name)

Like scm_c_lookup and scm_lookup, but the specified module is used instead of the current one.

C Function: SCM scm_module_variable (SCM module, SCM name)

Like scm_module_lookup, but if the binding does not exist, just returns #f instead of raising an error.

To define a value, use scm_define:

C Function: SCM scm_c_define (const char *name, SCM val)

Bind the symbol indicated by name to a variable in the current module and set that variable to val. When name is already bound to a variable, use that. Else create a new variable.

C Function: SCM scm_define (SCM name, SCM val)

Like scm_c_define, but the symbol is specified directly.

C Function: SCM scm_c_module_define (SCM module, const char *name, SCM val)

C Function: SCM scm_module_define (SCM module, SCM name, SCM val)

Like scm_c_define and scm_define, but the specified module is used instead of the current one.

In some rare cases, you may need to access the variable that scm_module_define would have accessed, without changing the binding of the existing variable, if one is present. In that case, use scm_module_ensure_local_variable:

C Function: SCM scm_module_ensure_local_variable (SCM module, SCM sym)

Like scm_module_define, but if the sym is already locally bound in that module, the variable’s existing binding is not reset. Returns a variable.

C Function: SCM scm_module_reverse_lookup (SCM module, SCM variable)

Find the symbol that is bound to variable in module. When no such binding is found, return #f.

C Function: SCM scm_c_define_module (const char *name, void (*init)(void *), void *data)

Define a new module named name and make it current while init is called, passing it data. Return the module.

The parameter name is a string with the symbols that make up the module name, separated by spaces. For example, ‘"foo bar"’ names the module ‘(foo bar)’.

When there already exists a module named name, it is used unchanged, otherwise, an empty module is created.

C Function: SCM scm_c_resolve_module (const char *name)

Find the module name name and return it. When it has not already been defined, try to auto-load it. When it can’t be found that way either, create an empty module. The name is interpreted as for scm_c_define_module.

C Function: SCM scm_c_use_module (const char *name)

Add the module named name to the uses list of the current module, as with (use-modules name). The name is interpreted as for scm_c_define_module.

C Function: void scm_c_export (const char *name, ...)

Add the bindings designated by name, ... to the public interface of the current module. The list of names is terminated by NULL.