[ Control | Reference Manual | Alphabetic Index ]

+LookupModule : +Goal

Call the procedure visible in LookupModule rather than the caller module

LookupModule: Atom, or list of atoms
Goal: Callable term (atom or compound)

Description

This predicate provides a means to invoke a procedure which is not visible. Normally, when a procedure is called, the system looks for a visible definition (local or imported) in the caller module. This primitive on the other hand allows to specify a different lookup module.

One of two conditions must be satisfied for the lookup to succeed:

the predicate must be exported or reexported from the lookup module, or
the predicate is visible in the lookup module, and the LookupModule argument originates from a tool-call within LookupModule

The purpose of this is to allow calling procedures whose definition is not visible in the caller module. The two main uses of this facility are:

If there are several definitions of a procedure with the same name in different modules, :/2 can be used to specify which one to call.
If a module wants to define a procedure, but needs to call another procedure of the same name (but from a different module), :/2 can be used to call that one instead of the locally defined one.

Note that :/2 does not affect the caller (context) module of the call. The following table summarises the different idioms:

	Call within module(m)         lookup module    caller module

	..., twice(X), ...               m               m
	..., lm : twice(X), ...         lm               m
	..., twice(X) @ cm, ...          m              cm
	..., lm : twice(X) @ cm, ...    lm              cm
	..., call(twice(X)) @ cm, ...   cm              cm

It is possible to give a list of lookup modules, e.g.

        ..., [m1,m2]:Goal, ...

is equivalent to the conjunction

        ..., m1:Goal, m2:Goal, ...

With an empty list, the goal is completely ignored, so the idiom

        ..., []:Goal, ...

can be used to disable a subgoal.

If the lookup module does not exist (error 86), the event handler will try to find and autoload a library to supply the module.

Modules

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

Fail Conditions

Fails if Goal fails

Resatisfiable

Resatisfiable if Goal is resatisfiable

Exceptions

(4) instantiation fault: Goal is not instantiated.
(4) instantiation fault: LookupModule is not instantiated.
(5) type error: Goal is neither an atom nor a compound term.
(5) type error: LookupModule is neither an atom nor a list of atoms.
(68) calling an undefined procedure: Goal is an undefined procedure in LookupModule.
(86) lookup module does not exist: LookupModule does not exist.

Examples

% When two definitions are visible, qualify calls to disambiguate
% (extra parentheses may be needed around the invoked goal):

    :- lib(ic).     % exports $>= / 2
    :- lib(eplex).  % exports $>= / 2

	..., ic:(X $>= Y), ...
	..., eplex:(X $>= Y), ...


% Call multiple versions by giving a list of modules:

	..., [ic,eplex]:(X $>= Y), ...


% Call a predicate that is hidden by a local definition:

    :- lib(lists).     % exports print_list/1

    print_list(List) :-
	writeln("This is the list:"),
	lists:print_list(List).


% Library autoloading (when lookup module does not exist)

    ?- calendar:mjd_now(Now).
    WARNING: module 'calendar' does not exist, loading library...
    calendar.eco loaded in 0.00 seconds
    Now = 59647.379236111119
    Yes (0.00s cpu)