
expand_macros(?Term, -TransTerm)

   Apply macro transformations to Term

Arguments
   Term                A term.
   TransTerm           A variable.

Type
   Term I/O

Description
    Applies macro-transformations to Term, if any are visible in the
    context module. If no transformation is visible, TransTerm is identical
    to Term.
    
    Normally, macro expansion is performed implicitly by the parser, i.e.
    when using either the compiler or term-input builtins like read/1,2,
    read_term/2,3 or readvar/2,3.
    
    For certain meta-programming applications, where one needs to work with
    the original unexpanded form of the input, this is undesirable.
    In such cases, macro-expansion can be switched off during reading
    and later performed explicitly using expand_macros/2.
    
    For reading input without macro expansion, set the stream-flag
    macro_expansion to off before reading (see set_stream_property/3
    or open/4), or use the facilities of the library(source_processor).


Modes and Determinism
   expand_macros(?, -) is det

Modules
   This predicate is sensitive to its module context (tool predicate, see @/2).

Examples
   
    % Given the program:

        t(water, wine).
        :- local macro(water, t/2, []).


    % Implicit macro expansion by read/1:
    ?- open(string("water"),read,S),
        read(S,X),
        close(S).
    X = wine
    yes.

    % Implicit macro expansion switched off:
    ?- open(string("water"),read,S,[macro_expansion(off)]),
        read(S,X),
        close(S).
    X = water
    yes.

    % Explicit macro expansion:
    ?- open(string("water"),read,S,[macro_expansion(off)]),
        read(S,X),
        expand_macros(X,Y),
        close(S).
    X = water
    Y = wine
    yes.

    % All occurrences are expanded:
    ?- open(string("[water,beer,fizzy(water)]"),read,S,[macro_expansion(off)]),
        read(S,X),
        expand_macros(X,Y),
        close(S).
    X = [water, beer, fizzy(water)]
    Y = [wine, beer, fizzy(wine)]
    yes.


See Also
   macro / 3, expand_clause / 2, expand_goal / 2, open / 4, set_stream_property / 3, library(source_processor), portray / 3, portray_term / 3
