[ ECLiPSe Module built-in.|Group Index| Full Index]

tool(+PredSpecI, +PredSpecB)

Declares PredSpecI as a tool interface procedure and PredSpecB as its body procedure.

+PredSpecI
Expression of the form Atom/Integer.
+PredSpecB
Expression of the form Atom/Integer.

Description

It defines PredSpecI as a tool interface procedure in the caller module and declares PredSpecB as its body procedure. The arity of PredSpecB must be one higher than the arity of PredSpecI, otherwise an exception is raised. This is because when PredSpecI is called, the system puts the name of the caller module in the additional argument and calls PredSpecB.

The default visibility for the interface is local.

The tool/2 declaration can be used before the body procedure is defined.

If PredSpecI already exists and if the system has already compiled some calls to it, tool/2 gives error 62 (``inconsistent procedure redefinition'') since the system cannot provide the caller's home module for calls which are already compiled.

Therefore, when there are modules which are compiled before the tool/2 declaration but which call PredSpecI, tool/1 should be used before the first call to inform the system that this is a tool interface procedure.

Fail Conditions

None.

Resatisfiable

No.

Exceptions

(4) Instantiation fault
Either PredSpecI or PredSpecB is not instantiated.
(5) Type error
Either PredSpecI or PredSpecB is instantiated, but not to an expression of the form Atom/Integer.
(6) Range error
The arity of PredSpecB is not one greater than that of PredSpecI.
(62)
A call to PredSpec has already been compiled before the tool declaration (``inconsistent procedure redefinition'').

Examples


Success:
     [eclipse]: module(m1).
     [m1]: global call2/1.
     yes.
     [m1]: [user].
      call2(P):-
      call(P),
      call(P).
      user        compiled 120 bytes in 0.03 seconds
     yes.
     [m1]: module(m2).
     [m2]: [user].
      p(1).
      user        compiled 40 bytes in 0.00 seconds
     yes.
     [m2]: call2(p(X)).
     calling an undefined procedure p(_g54) in module m1
     [m2]: module(m1).
     [m1]: tool(call2/1,call2_body/2).
     yes.
     [m1]: [user].
      call2_body(P,M):-
      call(P,M),
      call(P,M).
      user        compiled 112 bytes in 0.00 seconds
     yes.
     [m1]: module(m2).
     [m2]: call2(p(X)).
     X = 1
     yes.

     % define a predicate that prints its caller module:

     [eclipse]: tool(where_am_i/0, writeln/1).
     yes.
     [eclipse]: where_am_i.
     eclipse
     yes.

Error:
     tool(L, tb/1).                   (Error 4).
     tool(ti/0, L).                   (Error 4).
     tool(ti, tb/1).                  (Error 5).
     tool(ti/0, tb).                  (Error 5).
     tool(ti/0, tb/2).                (Error 6).

     [eclipse]: [user].
      % :- tool(ti/0) here would prevent error 62 below
      p :- ti. % call compiled before tool declaration
      user        compiled 32 bytes in 0.02 seconds
     yes.
     [eclipse]: tool(ti/0, tb/1).            (Error 62).


See Also

tool / 1, tool_body / 3