~ chicken-core (chicken-5) 2a5bd0ab7f1e9d0c795eab6cc1cddc71e5d636a7

commit 2a5bd0ab7f1e9d0c795eab6cc1cddc71e5d636a7
Author:     felix <felix@z.(none)>
AuthorDate: Fri Mar 25 12:24:21 2011 +0100
Commit:     felix <felix@z.(none)>
CommitDate: Fri Mar 25 12:24:21 2011 +0100

    documented alternative functor syntax

diff --git a/manual/Modules b/manual/Modules
index 4c434c2f..6b91f329 100644
--- a/manual/Modules
+++ b/manual/Modules
@@ -44,7 +44,7 @@ CHICKEN's module system has the following features and shortcomings:
 <macro>(module NAME (EXPORT ...) BODY ...)</macro><br>
 <macro>(module NAME (EXPORT ...) FILENAME)</macro>
 <macro>(module NAME * BODY ...)</macro>
-<macro>(module NAME1 = NAME2)</macro>
+<macro>(module NAME1 = NAME2 [BODY ...])</macro>
 <macro>(module NAME = (FUNCTORNAME MODULENAME1 ...))</macro>
 
 Defines a module with the name {{NAME}}, a set of exported bindings
@@ -77,14 +77,15 @@ be a symbol naming an interface.
 When the {{BODY}} consists of a single string, it is treated
 like {{(include FILENAME)}}.
 
-The syntax {{(module NAME1 = NAME2)}} defines an alias {{NAME1}}
-for the module {{NAME2}}, so {{NAME1}} can be used in place of 
-{{NAME2}} in all forms that accept module names. Module aliases
-defined inside a module are local to that module.
-
 {{(module NAME = (FUNCTORNAME MODULENAME1 ...))}} instantiates
 a ''functor'' (see below for information about functors).
 
+The syntax {{(module NAME1 = NAME2)}} defines an alias {{NAME1}} for
+the module {{NAME2}}, so {{NAME1}} can be used in place of {{NAME2}}
+in all forms that accept module names. Module aliases defined inside a
+module are local to that module. If followed by a module body, then
+this is a special form of ''functor instantiation''.
+
 Nested modules, modules not at toplevel (i.e. local modules) or
 mutually recursive modules are not supported. As an exception
 module alias definitions are allowed inside a module definition.
@@ -431,6 +432,21 @@ requirement that a specific export of an argument-module must be
 syntax or non-syntax - it can be syntax in one instantiation and a
 procedure definition in another.
 
+The common case of using a functor with a single argument module
+that is not used elsewhere can be expressed in the following way:
+
+<enscript highlight=scheme>
+(module NAME = FUNCTORNAME BODY ...)
+</enscript>
+
+which is the same as
+
+<enscript highlight=scheme>
+(begin
+  (module _NAME * BODY ...)
+  (module NAME = (FUNCTORNAME _NAME)))
+</enscript>
+
 Since functors exist at compile time, they can be stored in
 import-libraries via {{-emit-import-library FUNCTORNAME}} or
 {{-emit-all-import-libraries}} (see [[Using the compiler]] for more
@@ -441,6 +457,9 @@ has no runtime code, so it is sufficient to merely {{import}} it (as
 opposed to using {{require-extension}} or one of its variants, which
 also loads the run-time part of a module).
 
+Note that functor-instantiation creates a complete copy of the
+functor body.
+
 
 ---
 Previous: [[Macros]]