11.3.122 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 its first argument in order to to construct the goal to invoke.

An integer is treated the same as ‘:’ above by the SICStus runtime. 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

Exceptions in the context of loading code are printed as error messages.

instantiation_error

MetaSpec not ground.

type_error

MetaSpec not a valid specification.

context_error

Declaration appeared in a goal.

permission_error

Declaration appeared as a clause.

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) -> … ; … ),
   …

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/3) 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.