11.3.228 term_expansion/6   hook

Synopsis

:- 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.

Arguments

Term1

term

Term to transform.

Layout1

term

Layout term of Term1.

Tokens1

list of atom

Term2

term

Transformed term.

Layout2

term

Layout term of Term2.

Tokens2

list of atom

Description

expand_term/2 calls this hook predicate first; if it succeeds, then 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, then 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

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

See Also

ref-lod-exp, Glossary.