1.15 XSB Lint

The xsb_lint_impexp.P file contains a simple tool to analyze import/exports and definitions and uses of predicates. It tries to find possible inconsistencies, producing warnings when it finds them and generating document_import/document_export declarations that might be useful. It can be used after a large multi-file, multi-module XSB program has been written to find possible inconsistencies in (or interesting aspects of) how predicates are defined and used.

XSB source files that contain an export compiler directive are considered as modules. Predicates defined in modules, but not exported, are local to that module. When compiling a module, the XSB compiler generates useful warnings when predicates are used but not defined or defined but not used. All predicates that are defined in source files that do not contain an export directive are compiled to be defined in a global module, called usermod, and no warning messages are generated. The user may add document_export and document_import compiler directives (exactly analogous to the export and import directives) to non-module source files. These directives are ignored by the compiler for its compilation, but cause the define-use analysis to be done and any warning messages to be issued, if appropriate. This allows a user to get the benefit of the define-use analysis without using modules. (See Volume 1, Chapter 3 for more details.)

The xsb_lint_impexp utility processes both modules and regular XSB source files that contain document_export statements. xsb_lint_impexp is not itself a module. To use it, [xsb_lint_impexp] must be consulted, which will define the checkImpExps/{1,2} and add_libraries/1 predicates in usermod.

add_libraries(+DirectoryNameList)

add_libraries/1 takes a list of directory names and adds them to the library_directory/1 predicate. This causes the XSB system to look for XSB source code files in these directories. To use checkImpExps/{1,2}, all the directories that contain files (or modules) referenced (recursively) in the files to be processed must be in the library_directory/1 predicate. This predicate can be used to add a number of directories at once.

checkImpExps(+Options,+FileNameList)

checkImpExps/1 reads all the XSB source files named in the list FileNameList, and all files they reference (recursively), and produces a listing that describes properties of how they reference predicates.

Options is a list of atoms (from the following list) indicating details of how checkImpExps should work.

1. used_elsewhere: Print a warning message in the case of a predicate defined in a file, not used there, but used elsewhere (in a file in FileNameList). This can be useful to see whether it might be better to move the predicate definition to another file, but it produces many warnings for predicates in multi-use libraries.
2. unused: Print a warning message in the case of a predicate that is exported but never used. This can be useful to see if predicate is not used anywhere, and thus could be deleted. Again this produces many warnings for predicates in multi-use libraries.
3. all_files: By default, only predicates in files that contain a :- document_export or :- export declaration are processed. This option causes predicates of all files (and modules) to be processed.
4. all_symbol_uses: Treat all non-predicate uses of symbols (even constants) as predicate uses for the purpose of generating imports.
5. no_symbol_uses: Don't treat any non-predicate uses of symbols as predicate uses for the purpose of generating imports.

We further explain the final two options, which allow the user to determine more precisely what uses of a symbol are considered as uses of it as the predicate symbol. All uses of symbols that appear in a ``predicate context", i.e., in the body of a rule or in a meta-predicate argument position of a use of a meta-predicate, are considered uses of that predicate symbol. The default is also to allow nonconstant symbols appearing in any other context to also count as uses of that symbol as that predicate symbol. This is useful for programs that define their own meta-predicates.

checkImpExps(+FileNameList)

checkImpExps/1 is currently equivalent to checkImpExps([],FileNameList).