[ Modules | Reference Manual | Alphabetic Index ]

import +Module

import +PredSpecs from +Module

Import a module, or import certain procedures from a module.

Module: Atom.
PredSpecs: One or more comma-separated terms of the form Name/Arity

Description

Importing is the way to make definitions from another module visible as if they were local definitions. Only items that have been exported from another module can be imported. Imports should usually be done at the beginning of module texts.

Importing a Module as a Whole

If the first form of import is used, e.g.

   	:- import amodule.

then all of the specified module's interface (i.e. everything that is exported or reexported there) gets imported.

Note that the module to import must already have been loaded, e.g. via compile/1 or ensure_loaded/1. To simplify this, you can use use_module/1 which is simply a combination of ensure_loaded/1 and import/1. If an attempt is make to import a module that does not exist yet, the system tries to create it by trying to load a library of that name.

Note that procedure imports a treated slightly differently from other (e.g. structure declaration) imports: While other imports have an immediate effect (e.g. making the structure declaration available), procedures are actually imported lazily: they are only made visible when they are referred to (e.g. called) subsequently in the importing module. This has the advantage that import ambiguities (i.e. the same procedure is exported from multiple imported modules) do not pose any problem as long as the ambiguous procedure is not actually used. When it is used, however, the system will report the conflict. The conflict can then either be resolved by using the import ... from ... construct, or it can be avoided by using explicit module qualification via :/2 everywhere.

When a local procedure is defined while a procedure with the same name could be lazily imported from an imported module, the system issues a warning (or even an error in the case of built-ins). If that was the intention, the warning should be suppressed by using an explicit local-declaration.

Importing Specific Procedures from a Module

An example of the second form of the import declaration is

   	:- import p/3,q/1 from amodule.

This causes only the specified procedures to be imported from the given module. Unlike above, this import has an immediate effect, and any attempt to import the same name from elsewhere, or to declare a local procedure of the same name will raise an error 94. Only procedures can be imported using this form of import/1.

Another difference compared to the first form of import/1 is that the module from which we import does not have to exist yet, and no attempt is made to load the module. This is therefore a way to overcome the otherwise enforced export-before-import rule and it allows a certain degree of circularity in the export-import relationship between modules. However, it is usually considered better programming style to have a strictly hierarchical module structure rather than circular dependencies, and to always build a new module on top of a self-contained set of more basic modules.

Note that when the compiler compiles a call to an imported procedure whose export is not yet known, it may use the wrong calling convention. This will lead to an incompatibility error later when the export becomes known. Forward declarations like tool/2 and external/1 can sometimes be used to prevent this problem.

Implicit Imports

Modules are implicitly imported by the module/3 and create_module/3 primitives, which import the modules given in their third argument. Modules created with module/1 or create_module/1 implicitly import the module eclipse_language.

Modes and Determinism

import(++) is det

Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

Exceptions

(4) instantiation fault: Module is not instantiated.
(5) type error: Module is instantiated, but not to an atom.
(80) not a module: Library file does not define Module.
(171) File does not exist :: Library file does not exist.
(92) trying to redefine an existing local procedure: Conflict with local definition.
(93) trying to redefine an existing exported procedure: Conflict with exported definition.
(94) trying to redefine an existing imported procedure: Conflict with another imported procedure.

Examples

% A module that exports a predicate and an operator:

    :- module(m1).

    :- export
    	before/2,
	op(700, xfx, before).

    A before B :-
    	A < B.

% Importing this module elsewhere:

    :- module(m2).

    :- import m1.    % or :- use_module(".../m1...").

    main :-
    	3 before 7.  % operator and procedure definition are visible!


% Importing a procedure:

    :- module(m3).

    :- import before/2 from m1.

    main :-
    	before(3,7).  % only procedure definition is visible!


% Error cases:

     :- import L.                                     (Error 4).
     :- import 1.                                     (Error 5).
     :- import a,b.                                   (Error 5).
     :- import op(X,Y,before) from eclipse_language.  (Error 5).
     :- import xxxx.                                  (Error 171).

     :- import p/1 from a.
     :- import p/1 from b.                            (Error 94).

     :- export p/1.
     :- import p/1 from b.                            (Error 93).

     p(99).
     :- import p/1 from b.                            (Error 92).