11.3.248 use_module/[1,2,3]

Synopsis

use_module(+File)

Loads the module file(s) File, 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. Imports according to Imports. The File argument must be a variable or a legal file specification but is otherwise ignored.

use_module(-Module, +File, +Imports)

Module is a variable or has not been loaded. Loads module file File, if not already loaded and up-to-date. Imports according to Imports, i.e. similar to what use_module(File, Imports) does. Finally, the Module argument is bound to the loaded module.

Arguments

:File

file_spec or list of file_spec, must be ground

Any legal file specification. Only use_module/1 accepts a list of file specifications, file extensions optional.

Imports

list of simple_pred_spec or the atom all, must be ground

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 loaded module are to be imported.

Module

atom

The module name in File, 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 should be module files; if they are not, then warnings are issued.

use_module/1 imports all the exported predicates of the loaded modules into the calling module (or module M if specified).

use_module/2 imports only the predicates in Imports from the loaded module. If an attempt is made to import a predicate that is not public, then a warning is issued.

use_module/3 allows Module to be imported without requiring that its source file (File) be known, as long as the Module already exists in the system.

Generally, use_module/3 is similar to use_module/2, except that if Module is already in the system, then 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, then 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, or Module is a module that has not been loaded, then File must exist, and the module name in File is returned.

use_module/1 is similar to ensure_loaded/1 except that all files should be module files; if they are not, then warnings are issued.

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-bas.

After possibly 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 the file is not a module file, then nothing is imported. If any of the predicates in Imports are not public predicates, then a warning is issued, but the predicates are imported nonetheless. This lack of strictness is for convenience; if you forget to declare a predicate to be public, then 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 use_module/[2,3], 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.

Exceptions

See also load_files/[2,3].

instantiation_error

File or Imports is not ground.

type_error

In File or Imports.

Examples

use_module/[1,2] could be defined as:

use_module(Files) :-
    load_files(Files, [if(changed)]).

use_module(File, Imports) :-
    load_files([File], [if(changed),imports(Imports)]).

use_module/3 can be used to access the (primary) module name of a module file:

| ?- use_module(Module, library(clpfd), all).
% loading .../library/clpfd.po...
[...]
% loaded .../library/clpfd.po in module clpfd, 830 msec 496796 bytes
Module = clpfd ? 
yes

See Also

ref-lod-lod.