[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Guile module system documentation committed
From: |
Neil Jerram |
Subject: |
Re: Guile module system documentation committed |
Date: |
07 May 2001 23:33:55 +0100 |
User-agent: |
Gnus/5.0808 (Gnus v5.8.8) Emacs/20.7 |
>>>>> "Martin" == Martin Grabmueller <address@hidden> writes:
Martin> I have committed it to CVS under the name
Martin> guile-core/devel/modules/module-snippets.texi
Martin> and would like some comments, [...]
This is wonderful! I haven't given thought yet to any of the bigger
questions like (i) how it affects my understanding of the module
system as a whole and (ii) whether this should be incorporated into
one of the existing Guile manuals, but I do have a few typos and
followup questions for you ... (presented below as a diff)
Neil
Index: module-snippets.texi
===================================================================
RCS file: /cvs/guile/guile-core/devel/modules/module-snippets.texi,v
retrieving revision 1.1
diff -u -r1.1 module-snippets.texi
--- module-snippets.texi 2001/05/07 19:29:22 1.1
+++ module-snippets.texi 2001/05/07 22:25:36
@@ -109,7 +109,7 @@
like and what operations are defined on it.
Modules in Guile are instances of a data type @code{module}. A module
-has the following fields.
+is a record with the following fields.
@table @var
@item obarray
@@ -171,7 +171,7 @@
* Module Hierarchy:: The currently implemented hierarchy.
* Modules and Interfaces:: How modules implement different scopes.
* Modules and Environments:: Relation between modules and environments.
-* Modules Miscallenea:: Miscellaneous module procedures.
+* Modules Miscellanea:: Miscellaneous module procedures.
@end menu
@@ -256,7 +256,7 @@
underlying mechanisms, on which @code{use-modules} is built.
Normally, you will not need to create new modules explicitly, adding
-definitions to it manually. For more often, you will want to load some
+definitions to it manually. Far more often, you will want to load some
Scheme code from a file, and install its definitions into a module, only
exporting the public bits. This is what the procedure
@code{resolve-module} is for.
@@ -308,10 +308,11 @@
@var{m}.''
@deffn procedure module-locally-bound? module sym
-Test if @var{sym} is bound in @var{module} directly, e.g. it does not
+Test if @var{sym} is bound in @var{module} directly, i.e. it does not
suffice that @var{sym} is bound in one of the used modules of
@var{module}. @dfn{Bound} means that the symbol is interned and bound
-to some well-defined value.
+to some well-defined value. NJFIXME - what does `well-defined' actually
+mean?
@end deffn
@deffn procedure module-bound? module sym
@@ -322,7 +323,7 @@
@end deffn
@deffn procedure module-symbol-locally-interned? module sym
-Test if @var{sym} is interned in @var{module} directly, e.g. it does not
+Test if @var{sym} is interned in @var{module} directly, i.e. it does not
suffice that @var{sym} is bound in one of the used modules of
@var{module}. Unlike @code{module-locally-bound}, the symbol is not
required to be bound to a well-defined value.
@@ -370,6 +371,7 @@
@deffn procedure module-add! module symbol var
Add the variable @var{var} to @var{module} under the name @var{symbol}.
+NJFIXME - what is the type of var here?
@end deffn
@deffn procedure module-remove! module symbol
@@ -390,6 +392,7 @@
@deffn procedure module-for-each proc module
Apply @var{proc} to every binding in @var{module}. @var{proc} is called
with two parameters, the name and variable for each binding.
+NJFIXME - local bindings? or this module plus its uses list recursively?
@end deffn
@deffn procedure module-map proc module
@@ -424,6 +427,9 @@
@code{#t} if the binding should be defined, @code{#f} otherwise.
@end table
+NJFIXME - presumably, if `define?' is #t, no recursion occurs, as the
+binding either exists in the first level module, or is created in the
+first level module - is this correct?
@c ===================================================================
@@ -471,7 +477,7 @@
For all evaluations, Guile maintains a so-called @dfn{current
address@hidden current module does not exist until Guile has been
completely booted, that means until @file{boot-9.scm} has been loaded.
-But this should be no issue unless you are doing weird things withe the
+But this should be no issue unless you are doing weird things with the
module system, which might be a bad idea, but YMMV.} This is used for
all top-level definitions and variable lookups. When the current module
changes, new definitions will go to the new module. The procedures in
@@ -516,6 +522,8 @@
of its used modules. If there is no such variable, then if the optional
third argument @var{default} is present, it is returned; otherwise an
error is signaled.
+NJFIXME - is this the same as module-symbol-binding? If not, what is
+the difference?
@end deffn
@deffn procedure module-set! module name value
@@ -567,6 +575,8 @@
the module bound to foo in some-root-module>
@end example
+NJFIXME - can any module be used as a ROOT?
+
@deffn procedure nested-ref root names
Look up the variable identified by the symbol list @var{names}, starting
in the module @var{root}.
@@ -624,6 +634,8 @@
with the Guile distribution are installed under @code{(app modules)} as
well.
+NJFIXME - so why do module install directories not include "app/modules"
+in their path? - or is that a silly question?
@c ===================================================================
@@ -657,7 +669,7 @@
@c ===================================================================
address@hidden Modules and Environments, Modules Miscallenea, Modules and
Interfaces, Module Data Type
address@hidden Modules and Environments, Modules Miscellanea, Modules and
Interfaces, Module Data Type
@section Modules and Environments
An environment belongs to a specific module, which can be determined by
@@ -669,8 +681,8 @@
@c ===================================================================
address@hidden Modules Miscallenea, , Modules and Environments, Module Data
Type
address@hidden Modules Miscallenea
address@hidden Modules Miscellanea, , Modules and Environments, Module Data
Type
address@hidden Modules Miscellanea
This chapter contains all miscellaneous information and procedure
documentation which I have not been able to include elsewhere. If
@@ -679,7 +691,8 @@
@deffn procedure set-system-module! m s
Set the @code{system-module} property of the module @var{m} to @var{s}.
address@hidden should be a module telling whehter @var{m} is a system module or
address@hidden should be a module - NJFIXME: not just a boolean? -
+telling whether @var{m} is a system module or
not. System modules are treated specially in some cases, for example
procedures defined in system modules are excluded from backtraces.
FIXME: Is this last sentence true?