
+LookupModule : +Goal

   Call the procedure visible in LookupModule rather than the context module

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

Type
   Control

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 context 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 context 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 context module of the call.
   The following table summarises the different idioms:

	Call within module(m)         lookup module    context 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 --- Goal is not instantiated.
     4 --- LookupModule is not instantiated.
     5 --- Goal is neither an atom nor a compound term.
     5 --- LookupModule is neither an atom nor a list of atoms.
    68 --- Goal is an undefined procedure in LookupModule.
    86 --- 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)


See Also
   call / 1, @ / 2, export / 1
