use_module/[1,2,3]

Synopsis

use_module(+Files)

Loads the module-file(s) Files, if not already loaded and up-to-date imports all exported predicates.

use_module(+File, +Imports)

Loads module-file File, if not already loaded and up-to-date imports according to Imports.

use_module(+Module, -File, +Imports)

Module is already loaded and up-to-date. Imports according to Imports.

use_module(-Module, +File, +Imports)

Module has not been loaded, or is out-of-date. Loads Module from File and imports according to Imports.

Arguments

File file_spec or list of file_spec [MOD]

Any legal file specification. Only use_module/1 accepts a list of file specifications. A .pl or .qof extension may be omitted in a file specification.

Imports list of simple_pred_spec or atom

Either a list of predicate specifications in the Name/Arity form to import into the calling module, or the atom all, meaning all predicates exported by the module are to be imported.

Module atom

The module name in Files, or a variable, in which case the module name is returned.

Description

Loads each specified file except the previously loaded files that have not been changed since last loaded. All files must be module-files, and all the public predicates of the modules are imported into the calling module (or module M if specified).

use_module/2 imports only the predicates in Imports when loading Files.

use_module/3 allows Module to be imported into another module without requiring that its source file (File) be known, as long as the Module already exists in the system. This predicate is particularly useful when the module in question has been linked with the Development Kernel as described in sap-srs.

Generally, use_module/3 is similar to use_module/[1,2], except that if Module is already in the system, Module, or predicates from Module, are simply imported into the calling module, and File is not loaded again. If Module does not already exist in the system, File is loaded, and use_module/3 behaves like use_module/2, except that Module is unified, after the file has been loaded, with the actual name of the module in File. If Module is a variable, File must exist, and the module name in File is returned.

When use_module/3 is called from an embedded command in a file being compiled with qpc, and File is unbound, an initialization/1 fact is generated, so that the actual execution of the use_module/3 command is delayed until the QOF file is loaded. This means that the module given must exist when the QOF file is loaded, but not when it is created.

As File is not checked if Module already exists in the system, and File can even be left unnamed in that case, for example,

     :- use_module(mod1, _, all).
     

In other words, the filename may be an unbound variable as long as Module is already in the system.

Special case of load_files/2 and is defined as

     use_module(Files) :-
         load_files(Files, [if(changed),
                            load_type(latest),
                            must_be_module(true)]).
     
     use_module(File, Imports) :-
         load_files(File, [if(changed),
                           load_type(latest),
                           must_be_module(true),
                           imports(Imports)]).
     

use_module/1 is similar to ensure_loaded/1 except that all files must be module-files.

An attempt to import a predicate may fail or require intervention by the user because a predicate with the same name and arity has already been defined in, or imported into, the loading module (or module M if specified). Details of what happens in the event of such a name clash are given in ref-mod-ncl.

After loading the module-file, the source module will attempt to import all the predicates in Imports. Imports must be a list of predicate specifications in Name/Arity form. If any of the predicates in Imports are not public predicates, an error message is printed, but the predicates are imported nonetheless. This lack of strictness is for convenience; if you forget to declare a predicate to be public, you can supply the necessary declaration and reload its module, without having to reload the module that has imported the predicate.

While use_module/1 may be more convenient at the top level, use_module/2 is recommended in files because it helps document the interface between modules by making the list of imported predicates explicit.

For consistency, use_module/2 has also been extended so that the Imports may be specified as the term all, in which case it behaves the same as use_module/1, importing the entire module into the caller.

For further details on loading files, see ref-lod. On file specifications, see ref-fdi.

Exceptions

instantiation_error

M, Files, or Imports is not ground.

type_error

One of the arguments is the wrong type.

existence_error

A specified file does not exist. If the fileerrors flag is off, the predicate fails instead of raising this exception.

permission_error

A specified file is protected. If the fileerrors flag is off, the predicate fails instead of raising this exception.

See Also

compile/1, ensure_loaded/1, initialization/1, load_files/[1,2], volatile/1, ref-lod, ref-fdi