..
   This file is part of Logtalk <https://logtalk.org/>
   SPDX-FileCopyrightText: 1998-2025 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.


.. _expansion_expansion:

Term and goal expansion
=======================

Logtalk supports a *term and goal expansion mechanism* that can be used to
define source-to-source transformations. Two common uses are the definition
of language extensions and domain-specific languages.

Logtalk improves upon the term-expansion mechanism found on some Prolog
systems by providing the user with fine-grained control on *if*, *when*,
and *how* expansions are applied. It allows declaring in a source file itself
which expansions, if any, will be used when compiling it. It allows declaring
which expansions will be used when compiling a file using compile and loading
predicate options. It also allows defining a default expansion for all source
files. It defines a concept of *hook objects* that can be used as building
blocks to create custom and reusable *expansion workflows* with explicit and
well-defined semantics. It prevents the simple act of loading expansion rules
affecting subsequent compilation of files. It prevents conflicts between groups
of expansion rules of different origins. It avoids a set of buggy expansion
rules from breaking other sets of expansion rules.


Defining expansions
-------------------

Term and goal expansions are defined using, respectively, the predicates
:ref:`methods_term_expansion_2` and :ref:`methods_goal_expansion_2`, which
are declared in the :ref:`expanding <apis:expanding/0>` built-in protocol.
Note that, unlike Prolog systems also providing these two predicates, they
are **not** declared as :term:`multifile predicates <multifile predicate>`
in the protocol. This design decision is key for giving the programmer full
control of the expansion process and preventing the problems inflicting most
of the Prolog systems that provide a term-expansion mechanism.

An example of an object defining expansion rules:

::

   :- object(an_object,
       implements(expanding)).

       term_expansion(ping, pong).
       term_expansion(
           colors,
           [white, yellow, blue, green, read, black]
       ).

       goal_expansion(a, b).
       goal_expansion(b, c).
       goal_expansion(X is Expression, true) :-
           catch(X is Expression, _, fail).

   :- end_object.

These predicates can be explicitly called using the :ref:`methods_expand_term_2`
and :ref:`methods_expand_goal_2` built-in methods or called automatically
by the compiler when compiling a source file (see the section below on *hook
objects*).

In the case of source files referenced in :ref:`directives_include_1`
directives, expansions are only applied automatically when the directives are
found in source files, not when used as arguments in the :ref:`predicates_create_object_4`,
:ref:`predicates_create_protocol_3`, and :ref:`predicates_create_category_4`,
predicates. This restriction prevents inconsistent results when, for example,
an expansion is defined for a predicate with clauses found in both an included
file and as argument in a call to the ``create_object/4`` predicate.

Clauses for the ``term_expansion/2`` predicate are called until one of them
succeeds. The returned expansion can be a single term or a list of terms
(including the empty list). For example:

.. code-block:: text

   | ?- an_object::expand_term(ping, Term).

   Term = pong
   yes

   | ?- an_object::expand_term(colors, Colors).

   Colors = [white, yellow, blue, green, read, black]
   yes

When no ``term_expansion/2`` clause applies, the same term that we are
trying to expand is returned:

.. code-block:: text

   | ?- an_object::expand_term(sounds, Sounds).

   Sounds = sounds
   yes

Clauses for the ``goal_expansion/2`` predicate are recursively called on the
expanded goal until a fixed point is reached. For example:

.. code-block:: text

   | ?- an_object::expand_goal(a, Goal).

   Goal = c
   yes

   | ?- an_object::expand_goal(X is 3+2*5, Goal).

   X = 13,
   Goal = true
   yes

When no ``goal_expansion/2`` clause applies, the same goal that we are
trying to expand is returned:

.. code-block:: text

   | ?- an_object::expand_goal(3 =:= 5, Goal).

   Goal = (3=:=5)
   yes

The goal-expansion mechanism prevents an infinite loop when expanding a goal
by checking that a goal to be expanded was not the result from a previous
expansion of the same goal. For example, consider the following object:

::

   :- object(fixed_point,
       implements(expanding)).

       goal_expansion(a, b).
       goal_expansion(b, c).
       goal_expansion(c, (a -> b; c)).

   :- end_object.

The expansion of the goal ``a`` results in the goal ``(a -> b; c)`` with no
attempt to further expand the ``a``, ``b``, and ``c`` goals as they have
already been expanded.

Goal-expansion applies to goal arguments of control constructs, meta-arguments
in built-in or ``user`` defined meta-predicates, meta-arguments in local
user-defined meta-predicates, meta-arguments in meta-predicate messages when
static binding is possible, and ``initialization/1``, ``if/1``, and ``elif/1``
directives.


Expanding grammar rules
-----------------------

A common term expansion is the translation of grammar rules into predicate
clauses. This transformation is performed automatically by the compiler
when a source file entity defines grammar rules. It can also be done
explicitly by calling the ``expand_term/2`` built-in method. For example:

.. code-block:: text

   | ?- logtalk::expand_term((a --> b, c), Clause).

   Clause = (a(A,B) :- b(A,C), c(C,B))
   yes

Note that the default translation of grammar rules can be overridden by
defining clauses for the :ref:`methods_term_expansion_2` predicate.


Bypassing expansions
--------------------

Terms and goals wrapped by the :ref:`control_external_call_1` control
construct are not expanded. For example:

.. code-block:: text

   | ?- an_object::expand_term({ping}, Term).

   Term = {ping}
   yes

   | ?- an_object::expand_goal({a}, Goal).

   Goal = {a}
   yes

This also applies to source file terms and source file goals when using hook
objects (discussed next).


Hook objects
------------

Term and goal expansion of a source file during its compilation is performed
by using *hook objects*. A hook object is simply an object implementing the
:ref:`expanding <apis:expanding/0>` built-in protocol and defining clauses
for the term and goal expansion hook predicates. Hook objects must be compiled
and loaded prior to being used to expand a source file.

To compile a source file using a hook object, we can use the
:ref:`hook <flag_hook>` compiler flag in the second argument of the
:ref:`predicates_logtalk_compile_2` and :ref:`predicates_logtalk_load_2`
built-in predicates. For example:

.. code-block:: text

   | ?- logtalk_load(source_file, [hook(hook_object)]).
   ...

In alternative, we can use a :ref:`directives_set_logtalk_flag_2`
directive in the source file itself. For example:

::

   :- set_logtalk_flag(hook, hook_object).

To use multiple hook objects in the same source file, simply write each
directive before the block of code that it should handle. For example:

::

   :- object(h1,
       implements(expanding)).

       term_expansion((:- public(a/0)), (:- public(b/0))).
       term_expansion(a, b).

   :- end_object.

::

   :- object(h2,
       implements(expanding)).

       term_expansion((:- public(a/0)), (:- public(c/0))).
       term_expansion(a, c).

   :- end_object.

::

   :- set_logtalk_flag(hook, h1).

   :- object(s1).

       :- public(a/0).
       a.

   :- end_object.


   :- set_logtalk_flag(hook, h2).

   :- object(s2).

       :- public(a/0).
       a.

   :- end_object.

.. code-block:: text

   | ?- {h1, h2, s}.
   ...

   | ?- s1::b.
   yes

   | ?- s2::c.
   yes

It is also possible to define a default hook object by defining a global
value for the ``hook`` flag by calling the :ref:`predicates_set_logtalk_flag_2`
predicate. For example:

.. code-block:: text

   | ?- set_logtalk_flag(hook, hook_object).

   yes

Note that, due to the ``set_logtalk_flag/2`` directive being local to a source
file, using it to specify a hook object will override any defined default hook
object or any hook object specified as a ``logtalk_compile/2`` or ``logtalk_load/2``
predicate compiler option for compiling or loading the source file.

.. note::

   Clauses for the ``term_expansion/2`` and ``goal_expansion/2`` predicates
   defined within an object or a category are never used in the compilation
   of the object or the category itself.

.. index:: single: begin_of_file
.. index:: single: end_of_file


Virtual source file terms and loading context
---------------------------------------------

When using a hook object to expand the terms of a source file, two
virtual file terms are generated: ``begin_of_file`` and ``end_of_file``.
These terms allow the user to define term-expansions before and after
the actual source file terms.

Logtalk also provides a :ref:`predicates_logtalk_load_context_2`
built-in predicate that can be used to access the compilation/loading
context when performing expansions. The :ref:`logtalk <objects_logtalk>`
built-in object also provides a set of predicates that can be useful,
notably when adding Logtalk support for language extensions originally
developed for Prolog.

As an example of using the virtual terms and the ``logtalk_load_context/2``
predicate, assume that you want to convert plain Prolog files to Logtalk by
wrapping the Prolog code in each file using an object (named after the file)
that implements a given protocol. This could be accomplished by defining
the following hook object:

::

   :- object(wrapper(_Protocol_),
       implements(expanding)).

       term_expansion(begin_of_file, (:- object(Name,implements(_Protocol_)))) :-
           logtalk_load_context(file, File),
           os::decompose_file_name(File,_ , Name, _).

       term_expansion(end_of_file, (:- end_object)).

   :- end_object.

Assuming, e.g., ``my_car.pl`` and ``lease_car.pl`` files  to be wrapped and
a ``car_protocol`` protocol, we could then load them using:

.. code-block:: text

   | ?- logtalk_load(
            ['my_car.pl', 'lease_car.pl'],
            [hook(wrapper(car_protocol))]
        ).

   yes

.. note::

   When a source file also contains plain Prolog directives and predicates,
   these are term-expanded but not goal-expanded (with the exception of the
   ``initialization/1``, ``if/1``, and ``elif/1`` directives, where the goal
   argument is expanded to improve code portability across backends).


Default compiler expansion workflow
-----------------------------------

When :ref:`compiling a source file <programming_multi_pass_compiler>`,
the compiler will first try, by default,
the source file-specific hook object specified using a local
``set_logtalk_flag/2`` directive, if defined. If that expansion fails,
it tries the hook object specified using the ``hook/1`` compiler option
in the ``logtalk_compile/2`` or ``logtalk_load/2`` goal that compiles
or loads the file, if defined. If that expansion fails, it tries the
default hook object, if defined. If that expansion also fails, the
compiler tries the Prolog dialect-specific expansion rules found
in the :term:`adapter file` (which are used to support non-standard
Prolog features).


User defined expansion workflows
--------------------------------

Sometimes we have multiple hook objects that we need to combine and use in
the compilation of a source file. Logtalk includes a :doc:`../libraries/hook_flows`
library that supports two basic expansion workflows: a :ref:`pipeline <apis:hook_pipeline/1>`
of hook objects, where the expansion results from a hook object are fed to
the next hook object in the pipeline, and a :ref:`set <apis:hook_set/1>` of
hook objects, where expansions are tried until one of them succeeds. These
workflows are implemented as parametric objects, allowing combining them to
implement more sophisticated expansion workflows. There is also a
:doc:`../libraries/hook_objects` library that provides convenient hook
objects for defining custom expansion workflows. This library includes a
hook object that can be used to restore the default expansion workflow used
by the compiler.

For example, assuming that you want to apply the Prolog backend-specific
expansion rules defined in its adapter file, using the
:ref:`backend_adapter_hook <apis:backend_adapter_hook/0>` library object,
passing the resulting terms to your own expansion when compiling a source
file, we could use the goal:

.. code-block:: text

   | ?- logtalk_load(
            source,
            [hook(hook_pipeline([backend_adapter_hook, my_expansion]))]
        ).

As a second example, we can prevent expansion of a source file using the library
object :ref:`identity_hook <apis:identity_hook/0>` by adding as the first term in a
source file the directive:

::

   :- set_logtalk_flag(hook, identity_hook).

The file will be compiled as-is as any hook object (specified as a compiler
option or as a default hook object) and any backend adapter expansion rules
are overridden by the directive.


Using Prolog defined expansions
-------------------------------

In order to use clauses for the ``term_expansion/2`` and ``goal_expansion/2``
predicates defined in plain Prolog, simply specify the pseudo-object ``user``
as the hook object when compiling source files. When using
:term:`backend Prolog compilers <backend Prolog compiler>` that support a
module system, it can also be specified a module containing clauses for the
expanding predicates as long as the module name doesn't coincide with an
object name. When defining a custom workflow, the library object
:ref:`prolog_module_hook/1 <apis:prolog_module_hook/1>` can be used as a
workflow step. For example, assuming a module ``functions`` defining expansion
rules that we want to use:

.. code-block:: text

   | ?- logtalk_load(
            source,
            [hook(hook_set([prolog_module_hook(functions), my_expansion]))]
        ).

But note that Prolog module libraries may provide definitions of the expansion
predicates that are not compatible with the Logtalk compiler. In particular,
when setting the hook object to ``user``, be aware of any Prolog library that
is loaded, possibly by default or implicitly by the Prolog system, that may be
contributing definitions of the expansion predicates. It is usually safer to
define a specific hook object for combining multiple expansions in a fully
controlled way.

.. note::

   The ``user`` object declares ``term_expansion/2`` and ``goal_expansion/2``
   as multifile and dynamic predicates. This helps in avoiding predicate
   existence errors when compiling source files with the ``hook`` flag set
   to ``user`` as these predicates are only natively declared by some of the
   supported backend Prolog compilers.

Debugging expansions
--------------------

The ``term_expansion/2`` and ``goal_expansion/2`` predicates can be
:ref:`debugged <debugging_debugging>` like any other object predicates. Note
that expansions can often be manually tested by sending
:ref:`methods_expand_term_2` and :ref:`methods_expand_goal_2`
messages to a hook object with the term or goal whose expansion you want to
check as argument. An alternative to the debugging tools is to use a
:term:`monitor` for the runtime messages that call the predicates. For example,
assume a ``expansions_debug.lgt`` file with the contents:

::

   :- initialization(
       define_events(after, edcg, _, _, expansions_debug)
   ).


   :- object(expansions_debug,
       implements(monitoring)).

       after(edcg, term_expansion(T,E), _) :-
           writeq(term_expansion(T,E)), nl.

   :- end_object.

We can use this monitor to help debug the expansion rules of the
:doc:`../libraries/edcg` library when applied to the ``edcgs`` example using
the queries:

.. code-block:: text

   | ?- {expansions_debug}.
   ...

   | ?- set_logtalk_flag(events, allow).
   yes

   | ?- {edcgs(loader)}.
   ...
   term_expansion(begin_of_file,begin_of_file)
   term_expansion((:-object(gemini)),[(:-object(gemini)),(:-op(1200,xfx,-->>))])
   term_expansion(acc_info(castor,A,B,C,true),[])
   term_expansion(pass_info(pollux),[])
   term_expansion(pred_info(p,1,[castor,pollux]),[])
   term_expansion(pred_info(q,1,[castor,pollux]),[])
   term_expansion(pred_info(r,1,[castor,pollux]),[])
   term_expansion((p(A)-->>B is A+1,q(B),r(B)),(p(A,C,D,E):-B is A+1,q(B,C,F,E),r(B,F,D,E)))
   term_expansion((q(A)-->>[]),(q(A,B,B,C):-true))
   term_expansion((r(A)-->>[]),(r(A,B,B,C):-true))
   term_expansion(end_of_file,end_of_file)
   ...

This solution does not require compiling the ``edcg`` hook object in debug
mode or access to its source code (e.g., to modify its expansion rules to
emit debug messages). We could also simply use the ``user`` pseudo-object
as the monitor object:

.. code-block:: text

   | ?- assertz((
            after(_, term_expansion(T,E), _) :-
               writeq(term_expansion(T,E)), nl
        )).
   yes

   | ?- define_events(after, edcg, _, Sender, user).
   yes

Another alternative is to use a pipeline of hook objects with the library
``hook_pipeline/1`` and ``write_to_stream_hook`` objects to write the
expansion results to a file. For example, using the ``unique.lgt`` test
file from the ``edcgs`` library directory:

.. code-block:: text

   | ?- {hook_flows(loader), hook_objects(loader)}.
   ...

   | ?- open('unique_expanded.lgt', write, Stream),
        logtalk_compile(
            unique,
            [hook(hook_pipeline([edcg,write_to_stream_hook(Stream,[quoted(true)])]))]
        ),
        close(Stream).
   ...

The generated ``unique_expanded.lgt`` file will contain the clauses resulting
from the expansion of the EDCG rules found in the ``unique.lgt`` file by the
``edcg`` hook object expansion.
