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.
Transformed term.
Layout term of Term2.
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 [].
A clause of this predicate should conform to the following template, where convert(Term1,Term2,Layout1,Layout2) 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, Lay1, Tokens1, Term2, Lay2, [Token|Tokens1]) :-
nonmember(Token, Tokens1),
convert(Term1, Lay1, Term2, Lay2), !.
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.
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.