_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-resolve module-handle) : Symbol
  module-handle : ModuleHandle

Returns a symbol representing the module in the handle's registry.  May not
correspond to the current namespace's module registry.

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

> (module-attach module-handle namespace) : Void
  module-handle : ModuleHandle
  namespace : Namespace

Attaches the module to the given namespace's module registry.

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

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

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

> (eval-in/top-level module-handle exprs) : Any
  module-handle : ModuleHandle
  exprs : (NonEmptyListof (Or Syntax CompiledExpr S-expr))

Evaluates each expression at the top level in the language defined by the given
module.

Example:
(eval-in/top-level (get-module '(lib "htdp-beginner.ss" "lang"))
                   '[(+ 1 2) (* 3 4)])
;; = 12

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

> (eval-in/module module-handle exprs) : Any
  module-handle : ModuleHandle
  exprs : (NonEmptyListof (Or Syntax CompiledExpr S-expr))

Evaluates each expression in the context of a module whose language is defined
by the given module.

Example:
(eval-in/module (get-module '(lib "htdp-beginner.ss" "lang"))
                '[(define (plus x y) (+ x y))
                  (plus 1 2)])
;; = 3