@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
@code{(hnh module-introspection)}.

@node General Module Introspection Utilities
@section General utilities

The module @code{(hnh module-introspection)} contains general helper
funcions for inspecting source code.

@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

@node Module Uses
@section Module Uses


@defun module-uses* forms
Find all dependencies of a module by statically analyzing its 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.

The return value is a list of sublists, where the car of each list is
the module's name (for example @code{(ice-9 format)}), and the cdr
being a keyword tagged list with the following tags and types,
corresponding to @code{use-modules} parameters.

@table @samp
@item #:select
List of imported symbols, present if only a subset of the exported
symbols are imported.

@item #:hide
List of symbols removed from the import. Always present, but may be an
empty list if nothing was hidden.

@item #:prefix
A symbol which prefixes all imported symbols.

@item #:renamer
literally what is written.

@item #:version
A list of exact integers.

@end table

Note that if the module was imported multiple times then it will be
present multiple times in the list, possibly with different options.
@end defun

@node Finding all Modules in Directory
@section Finding all Modules in Directory

TODO the all-*-under-directory procedures really need to be
straightened out.

@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 (@pxref{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