_module-utils.ss : Utilities for the PLT Scheme module system_

Written by: Carl Eastlund (cce at ccs dot neu dot edu)
Keywords: _module_ _namespace_ _evaluate_ _evaluation_ _language_

This software is distributed under a BSD-style license (see license.txt).

================================================================================

This module introduces a new type ModuleHandle representing a connection to a
specific module.  The module provides the following procedures:

--------------------

> (module-handle? value) : Boolean
  value : Any

Reports whether a value is a module handle.

--------------------

> (get-module module-path) : ModuleHandle
  module-path : Any (depends on current-module-name-resolver)

Loads the module corresponding to the given path into a new module registry and
returns a handle to it.

Example: (get-module '(lib "htdp-beginner.ss" "lang"))

--------------------

> (module-path module-handle) : Any
  module-handle : ModuleHandle

Returns the module path originally used to create the handle.

Example:
(module-path (get-module '(lib "htdp-beginner.ss" "lang")))
;; = '(lib "htdp-beginner.ss" "lang")

--------------------

> (module->external-namespace module-handle) : Namespace
  module-handle : ModuleHandle

Returns a new namespace built from the given module's exports.  This is the
namespace used, for instance, inside a new module that uses the given module as
its language.

Example:
(module->external-namespace (get-module '(lib "htdp-beginner.ss" "lang")))

--------------------

> (module->internal-namespace module-handle) : Namespace
  module-handle : ModuleHandle

Returns the namespace used inside the given module.  The is the namespace used,
for instance, at the REPL for the (module ...) language level after running the
given module.

Example:
(module->internal-namespace (get-module '(lib "htdp-beginner.ss" "lang")))

--------------------

> (module-exported-names module-handle) : (Listof Symbol)
  module-handle : ModuleHandle

Returns the list of names exported from the given module.  It is equivalent to
(namespace-mapped-symbols (module->external-namespace module-handle)).

Example:
(module-exported-names (get-module '(lib "htdp-beginner.ss" "lang")))

--------------------

> ((module->eval module-handle) expr) : Any
  module-handle : ModuleHandle
  expr : (Or Syntax CompiledExpr S-expr)

Constructs a function which evaluates expressions in the language defined by the
given module.

Example:
((module->eval (get-module '(lib "htdp-beginner.ss" "lang")))
 '(posn-x (make-posn 1 2)))
;; = 1