From 0fac96af120a47ed686c26745af50288086e22d3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Tue, 12 Sep 2023 23:51:26 +0200
Subject: Even more documentation.

---
 doc/ref/introspection.texi | 84 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 doc/ref/introspection.texi

(limited to 'doc/ref/introspection.texi')

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
-- 
cgit v1.2.3