Usage inference and the module system

The import and export statements of a module $M$ are used by the compiler for inferring usage of predicates. At compilation time, if a predicate $P/N$ occurs as callable in the body of a clause defined in $M$, but $P$ is neither defined in $M$ nor imported into $M$ from some other module, a warning is issued that $P/N$ is undefined. Here ``occurs as callable'' means that $P/N$ is found as a literal in the body of a clause, or within a system meta-predicate, such as assert/1, findall/3, etc. Currently, occurrences of a term inside user-defined meta-predicates are not considered as callable by XSB's usage inference algorithm. Alternatively, if $P/N$ is defined in $M$, it is used if $P/N$ is exported by $M$, or if $P/N$ occurs as callable in a clause for a predicate that is used in $M$. The compiler issues warnings about all unused predicates in a module. On the other hand, since all modules are compiled separately, the usage inference algorithm has no way of checking whether a predicate imported from a given module is actually exported by that module.

Usage inference can be highly useful during code development for ensuring that all predicates are defined within a set of files, for eliminating dead code, etc. In addition, import and export declarations are used by the xsbdoc documentation system to generate manuals for code ^3.5. For these reasons, it is sometimes the case that usage inference is desired even in situations where a given file is not ready to be made into a module, or it is not appropriate for the file to be a module for some other reason. In such a case the directives document_export/1 and document_import/1 can be used, and have the same syntax as export/1 and import/1, respectively. These directives affect only usage inference and xsbdoc. A file is treated as a module if and only if it includes an export/1 statement, and only import/1 statements affect dynamic loading and name resolution for predicates.