1 files changed, 84 insertions, 0 deletions
diff --git a/doc/ref/introspection.texi b/doc/ref/introspection.texi
new file mode 100644
index 00000000..9c8387d2
--- /dev/null
+++ b/doc/ref/introspection.texi
@@ -0,0 +1,84 @@
+@node Module Introspection
+@chapter Guile Module Introspection
+
+These are various procedures for getting information about modules,
+usually in a static (only looking at ``dead'' source code) way. They
+are currently strewn about a couple files, all under
+@file{hnh/module-introspection}.
+
+TODO rework the file structure.
+
+TODO the all-*-under-directory procedures really need to be
+straightened out.
+
+@defun module-uses* forms
+Find all dependencies of a module by statically analyzing it's source code.
+
+It gives worse resluts than Guile's built in @code{module-uses}, but
+has the benefit that a module which doesn't compile can still be checked.
+
+@var{froms} should be a list gotten by repeateadly calling @code{read}
+on a Scheme source file.
+@end defun
+
+@defun unique-symbols tree
+Return a list of all symbols occuring in @var{tree}. Each symbol is
+noted exactly once, anything which isn't a symbol is discarded.
+@end defun
+
+@defun module-declaration? form
+Checks if @var{form} starts with @code{'define-module}.
+@end defun
+
+@defun find-module-declaration forms
+@anchor{find-module-declaration}
+In a list of forms, find the first one which satisfies @code{module-declarations?}.
+@end defun
+
+@defun get-forms port
+Repeatadly call @code{read} on @var{port}, and return a list of the
+read forms in order of occurence in the file.
+@end defun
+
+@defun all-files-and-modules-under-directory dir
+Like @code{all-modules-under-directory}, but returns 2-lists of
+filename + module name.
+@end defun
+
+@defun all-files-under-directory directory extension
+Return a flat list of all ``regular'' files under @var{directory},
+whose end in @var{extension}.
+
+@example
+(all-files-under-directory "module" ".scm)
+⇒ '("module/hnh/util.scm")
+@end example
+@end defun
+
+@defun all-modules-under-directory directory
+Finds all ``.scm'' files under @var{directory}, and then read them to
+find a module declaration @pref{find-module-declaration}. Returns both
+the list of all the files, as well as all modules found, as a list of
+module lists, each one suitable to be sent to
+@code{reslove-interface}.
+
+Scheme files without a module declaration are not included in the
+result.
+@end defun
+
+@defun fs-find dir
+Find all files under @var{dir}. This includes all file types,
+including directories.
+
+@example
+(fs-find "module")
+;; Would return something on the following form:
+⇒ `(("module/hnh/util.scm" ,(stat "module/hnh/util.scm") regular)
+    ("module/hnh"          ,(stat "module/hnh")          directory)
+    ("module"              ,(stat "module")              directory)
+    ...)
+@end example
+@end defun
+
+@defun module-file-mapping dir
+@end defun