[ Term I/O | Reference Manual | Alphabetic Index ]

# expand_macros(?Term, -TransTerm)

Apply macro transformations to Term

Term
  A term.
TransTerm
  A variable.

## Description

Applies macro-transformations to Term, if any are visible in the caller 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