When a source file contains no module directives, it is compiled into the module from which the compilation was invoked. This makes it possible to write small programs without caring about modules. However, serious applications should be structured into modules.
A proper module definition consists of
The directive module_interface/1 will first erase the module if it already exists, i.e. remove all items and interfaces contained in the module and then create a new empty module. This is necessary to maintain the integrity of the data and perform a complete recompilation of the module. The module interface contains the declarations and definitions of all modular items which this module shares with other modules that use it. As long as no further module directive occurs, all clauses and queries of the file have this module as definition module. The effect of module_interface/1 ends at the next module_interface/1 or begin_module/1 directive or a the end of the file. If the file contains queries to compile another file containing module directives, this is done and then the module of the current file is resumed.
module/1 in a file is an obsolete shorthand for a module with an empty interface (and it may not be available in future releases).
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.