11.3.120 meta_predicate/1 [declaration]

Synopsis

:- meta_predicate +MetaSpec

Provides for module name expansion of arguments in calls to the predicate given by MetaSpec. All meta_predicate/1 declarations should be at the beginning of a module.

Arguments

:MetaSpec

callable, must be ground

Goal template or list of goal templates, of the form functor(Arg1, Arg2,...). Each Argn is one of:

‘:’

requires module name expansion

If the argument will be treated as a goal then it is better to explicitly indicate this using an integer, see the next item.

nsuppressed

a non-negative integer.

This is a special case of ‘:’ that means that the argument can be made into a goal by adding nsuppressed additional arguments. E.g., if the argument will be passed to call/1 then 0 (zero) should be used.

As another example, the meta_predicate declaration for the built-in call/3 would be :- meta_predicate call(2,?,?), since call/3 will add two arguments to the first argument in order to to construct the goal to invoke.

An integer is treated the same as ‘:’ above by the SICStus run-time. Other tools, such as the cross referencer (see The Cross-Referencer) and the SICStus Prolog IDE (see SICStus Prolog IDE), will use this information to better follow predicate references in analyzed source code.

‘+’

‘-’

‘?’

ignored

Exceptions

type_error

domain_error

in MetaSpec

context_error

“declaration appeared in query”

Examples

Consider a sort routine, mysort/3, to which the name of the comparison predicate is passed as an argument:

     mysort(LessThanOrEqual, InputList, OutputList) :-
        ...
        %% LessThanOrEqual is called exactly like the built-in @=</2
        ( call(LessThanOrEqual, Term1, Term2) -> ... ; ... ),
        ...

If LessThanOrEqual is module sensitive, an appropriate meta_predicate declaration for mysort/3 is:

     :- meta_predicate mysort(2, +, -).

since the first argument, LessThanOrEqual, will have two additional arguments added to it (by call/4) when invoked.

This means that whenever a goal mysort(A, B, C) appears in a clause, it will be transformed at load time into mysort(M:A, B, C), where M is the source module. The transformation will happen unless:

1. A has an explicit module prefix, or
2. A is a variable and the same variable appears in the head of the clause in a module-name-expansion position.

See Also

Meta-Predicate Declarations, ref-mod-mne.