The Module Interface

The module interface is a set of goals and procedure definitions which are made available to other modules. Moreover, the module interface may contain the definition of the syntax which is needed to read its body part. The notion of the module interface serves several purposes:

• It specifies which items are to be shared with other modules.

• It makes possible to share modular items that cannot be directly exported and imported.

• It specifies the part of the module, which has to be compiled and executed even if the module is only processed by source-level tools. For instance, if the module body contains terms with an associated macro, the corresponding macro transformation predicate has to be compiled even if the module body is only being read in.

If the module is used by another module via the predicate use_module/1, all queries that appear in the module interface part will be executed in the other module, except for export/1 and global/1 predicates. Therefore, declarations of local operators, macros, records etc. will be executed in the caller module and these items will become available there. The macro transformation predicates must be exported to be visible in the using module. The export/1 queries in the module interface are conceptually replaced by import_from/2 and thus the exported predicates are imported in the caller module.

Predicate definitions which appear in the module interface will not be repeated when the module is used; if they have to be accessible in another module, they should be exported instead.

Here is an sample module that can serve as a guideline of which declarations to place where:

:- module_interface(mod).

% syntax directives for this and for importing modules
:- op(300, xfx, >>>).
:- set_chtab(0'$, lower_case).
:- define_macro((|)/2, trans_bar/2, []).

% libraries to use here and in the importing modules
:- use_module(library(cio)).

% predicates to import here and in importing modules
:- import current_predicate_body/2 from sepia_kernel

% predicates defined globally by this module
:- global g/1.

% predicates exported from this module
:- export p/1, t/1, e/1.
:- export trans_bar/2.      % needed for the macro above

% type declarations for exported tools and externals
:- tool(t/1).
:- external(e/1).

% definition of macro transformation predicates
trans_bar(no_macro_expansion('|'(X,Y)), (X;Y)).

:- begin_module(mod).        % the module body

% syntax directives for this module only
:- op(300, xfx, <<<).

% predicates to import only here
:- import setof_body/4 from sepia_kernel.

% special type predicate definitions
:- tool(t/1, t_body/2).
:- external(e/1, my_c_function).

% normal predicate definitions
g(hello).
p(world).

When calling use_module(mod), all queries in the interface will be executed and the macro transformation correctly defined. The module interface may also contains goals not directly related to the definition module, like e.g. the import from in the above example.

The module body can also contain declaration of local modular items, however they remain local in the definition module. The definition of the module body starts with the begin_module/1 directive and it can be used only if the module already exists, either created by create_module/1, compile/2 or by defining the module interface. There may be several begin_module/1 directives for the same module. When they are compiled, their contents is added to the module body.