.. _library_hook_flows:

hook_flows

Hook objects (i.e. objects that define term- and goal-expansion rules) can be combined to define expansion workflows. While in some cases the expansions are independent and thus can be applied in any order, in other cases a specific order is required. The hook_pipeline and hook_set parametric objects in this library implement the two most common scenarios of combining multiple hook objects for the expansion of source files. These parametric hook objects can be combined to define workflows of any complexity (e.g. a pipeline where one of the steps is set with an element that is a pipeline). These two basic hook flows can also used as examples of how to construct your own custom expansion workflows.

API documentation

Open the `../../docs/library_index.html#hook-flows <../../docs/library_index.html#hook-flows>`__ link in a web browser.

Loading

To load all entities in this library, load the loader.lgt file:

::

| ?- logtalk_load(hook_flows(loader)).

Testing

To test this library predicates, load the tester.lgt file:

::

| ?- logtalk_load(hook_flows(tester)).

Usage

Pre-processing a source file with a hook object can be accomplished by either compiling the source file using the option hook(HookObject) or by adding to the top of the file the directive:

::

:- set_logtalk_flag(hook, HookObject).

Note that set_logtalk_flag/2 directives are local to an entity or a source file.

The hook_pipeline(Pipeline) is a parametric object where the parameter is a list of hook objects, interpreted as a pre-processing pipeline: the results of a hook object are passed to the next hook object. Terms and goals that are not expanded by a hook object are passed as-is to the next hook object. This parametric object is used when a set of expansions must be applied in a specific order. It also allows overriding the default compiler semantics where term-expansion rules are tried in sequence only until one of them succeeds.

The hook_set(Set) is a parametric object where the parameter is a list of hook objects, interpreted as a set of hook objects. The hook objects are tried in sequence until one of them succeeds in expanding the current term (goal) into a different term (goal). This parametric object is used when applying multiple independent expansions (i.e. expansions that don't apply to the same terms or goals).

Both the hook_pipeline(Pipeline) and hook_set(Set) objects assume that the individual hook objects publicly implement the expanding protocol (this is the default) as they send term_expansion/2 and goal_expansion/2 messages to those objects.

When using a backend Prolog compiler that supports modules, it's also possible to use as parameter a list of hook modules as long as their names do not coincide with the names of loaded objects.