..
   This file is part of Logtalk <https://logtalk.org/>  
   SPDX-FileCopyrightText: 1998-2024 Paulo Moura <pmoura@logtalk.org>
   SPDX-License-Identifier: Apache-2.0

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.


.. rst-class:: align-right

**directive**

.. index:: pair: meta_predicate/1; Directive
.. _directives_meta_predicate_1:

``meta_predicate/1``
====================

Description
-----------

::

   meta_predicate(Template)
   meta_predicate((Template, ...))
   meta_predicate([Template, ...])

   meta_predicate(Entity::Template)
   meta_predicate((Entity::Template, ...))
   meta_predicate([Entity::Template, ...])

   meta_predicate(Module:Template)
   meta_predicate((Module:Template, ...))
   meta_predicate([Module:Template, ...])

Declares :term:`meta-predicates <meta-predicate>`, i.e., predicates that
have arguments interpreted as goals, arguments interpreted as
:term:`closures <closure>` used to construct goals, or arguments with
sub-terms that will be interpreted as goals or closures. Meta-arguments
are always called in the meta-predicate
:term:`calling context <predicate calling context>`, not in the
meta-predicate :term:`definition context <predicate definition context>`.

Meta-arguments which are goals are represented by the integer ``0``.
Meta-arguments which are closures are represented by a positive integer,
``N``, representing the number of additional arguments that will be
appended to the closure in order to construct the corresponding goal
(typically by calling the :ref:`methods_call_N` built-in method).
Meta-arguments with sub-terms that will be interpreted as goals or closures
are represented by ``::``. Meta-arguments that will be called using the
``bagof/3`` or ``setof/3`` predicates and that can thus be
existentially-qualified are represented by the atom ``^``. Normal arguments
are represented by the atom ``*``.

Logtalk allows the use of this directive to override the original
meta-predicate directive. This is sometimes necessary when calling
Prolog built-in meta-predicates or Prolog module meta-predicates due
to the lack of standardization of the syntax of the meta-predicate
templates.

.. warning::

   Some backend Prolog compilers declare the atom ``meta_predicate`` as
   an operator for a lighter syntax. But this makes the code non-portable
   and is therefore a practice best avoided.

Template and modes
------------------

::

   meta_predicate(+meta_predicate_template_term)

   meta_predicate(+object_identifier::+meta_predicate_template_term)
   meta_predicate(+category_identifier::+meta_predicate_template_term)

   meta_predicate(+module_identifier:+meta_predicate_template_term)

Examples
--------

::

   % findall/3 second argument is interpreted as a goal:
   :- meta_predicate(findall(*, 0, *)).

   % both forall/2 arguments are interpreted as goals:
   :- meta_predicate(forall(0, 0)).

   % maplist/3 first argument is interpreted as a closure
   % that will be expanded to a goal by appending two
   % arguments:
   :- meta_predicate(maplist(2, *, *)).

.. seealso::

   :ref:`directives_meta_non_terminal_1`,
   :ref:`methods_predicate_property_2`
