11.3.227 term_expansion/6   hook


:- multifile user:term_expansion/6.

user:term_expansion(+Term1, +Layout1, +Tokens1, -Term2, -Layout2, -Tokens2)

Overrides or complements the standard transformations to be done by expand_term/2.




Term to transform.



Layout term of Term1.


list of atom



Transformed term.



Layout term of Term2.


list of atom


expand_term/2 calls this hook predicate first; if it succeeds, the standard grammar rule expansion is not tried.

Tokens1 is a list of atoms, each atom uniquely identifying an expansion. It is used to look up what expansions have already been applied to the clause or goal. The tokens are defined by the user, and should simply be added to the input list, before expansions recursively are applied. This token list can for instance be used to avoid cyclic expansions. The token dcg is reserved and denotes grammar rule expansion. Tokens2 should be unified with [Token|Tokens1].

Layout1 and Layout2 are for supporting source-linked debugging in the context of clause expansion. The predicate should construct a suitable Layout2 compatible with Term2 that contains the line number information from Layout1. If source-linked debugging of Term2 is not important, Layout2 should be []. The recording of source info is affected by the source_info prolog flag (see ref-lps-flg).

A clause of this predicate should conform to the following template, where convert(Term1, Layout1, Expansion, Layout) should be a goal that performs the actual transformation. Token should be the atom uniquely identifying this particular transformation rule. Tokens2 should be unified with [Token|Tokens1].

user:term_expansion(Term1, Layout1, Tokens1, Term2, Layout2, Tokens2) :-
        nonmember(Token, Tokens1),
        convert(Term1, Layout1, Expansion, Layout),
        !, % commit to this expansion
        Term2 = Expansion,
        Layout2 = Layout,
        Tokens2 = [Token|Tokens1].

This hook predicate may return a list of terms rather than a single term. Each of the terms in the list is then treated as a separate clause (or directive).

This hook predicate may also be used to transform queries entered at the terminal in response to the ‘| ?- ’ prompt. In this case, it will be called with Term1 = ?-(Query) and should succeed with Term2 = ?-(ExpandedQuery).

For accessing aspects of the load context, e.g. the name of the file being compiled, the predicate prolog_load_context/2 (see ref-lps-lco) can be used.


Exceptions are treated as failures, except an error message is printed also.

See Also

ref-lod-exp, Glossary.

Send feedback on this subject.