Namespace Library

_Namespace_ Library
===================

Time-stamp: <05/10/28 11:41:36 nhw>

Keywords: _namespace, _eval_, _require-


Introduction
============

This library provides some useful functions on namespaces.
The most common usage is to create custom namespaces in
which to dynamically evaluate code (that is, to use eval)


Basic Types
===========

To use these definitions:

   (require (planet "namespace.ss" ("schematics" "namespace.plt" 1 0)))

> exn:namespace

The basic exception raised by the functions in this module
when they encounter an error.


Macros
======

To use these definitions:

   (require (planet "namespace.ss" ("schematics" "namespace.plt" 1 0)))

> (with-namespace namespace expr ...)

Execute exprs in the given namespace, which is to say
current-namespace is parameterised to namespace in the scope
of expr ...


Functions
=========

To use these definitions:

   (require (planet "namespace.ss" ("schematics" "namespace.plt" 1 0)))

> (file-name->module-name path)
   file-name->module-name : string -> symbol

Convert a file name to the symbol that the module name is
expected to be.  Essentially the extension is trimmed from
the file name.  Raise exn:namespace if there is no file or
it is invalid.

> (require-spec-file require-spec)
   require-spec-file : sexp -> string

Extract the file (unix-relative-path-string, path-string, or
filename-string) from a require-spec.  Raises exn:namespace
if no file is present or the require-spec is malformed.  The
syntax of a require-spec is given in section 5.2 of the
MzScheme manual.

> (namespace-attach/require namespace require-spec)
   namespace-attach/require : namespace sexp -> #void

Attach and require the module specified by require-spec to
the given namespace.  If you want to share a module between
the current namespace and the namespace you have created
this is the way to do it. You might choose to do this so
changes in state in the module are visible between
namespaces, or to reduce memory usage.  The module must have
been already required in the current namespace.  The
current-namespace and current-module-name-resolver are used
to resolve the require-spec to a module.

This is most useful for creating a custom namespace in which
to evaluate code.  For example, to create and use a
namespace with the "etc.ss" from MzLib loaded:

  (require "etc.ss")
  (let ((namespace (make-namespace 'initial)))
    (namespace-attach/require
     namespace
     '(lib "etc.ss"))
    (with-namespace
      namespace
      (assert-false (eval '(boolean=? #t #f)))))

Note this requires "etc.ss" in the current namepsace.  If
you wish to avoid this step simply use namespace-require:

  (let ((namespace (make-namespace 'initial)))
    (with-namespace   
      namespace
      (namespace-require '(lib "etc.ss"))
      (assert-false (eval '(boolean=? #t #f)))))