> ## 7 Macros

> ### 7.1 Defining and Using Macros

> A macro is defined the following way:

>     -define(Const, Replacement).
>     -define(Func(Var1,...,VarN), Replacement).

> A macro definition can be placed anyhere among the attributes and function declarations of a module, but the definition must come before any usage of the macro.

> If a macro is used in several modules, it is recommended that the macro definition is placed in an include file.

> A macro is used the following way:

>     ?Const
>     ?Func(Arg1,...,ArgN)

> Macros are expanded during compilation. A simple macro `?Const` will be replaced with `Replacement`. Example:

>     -define(TIMEOUT, 200).
>     ...
>     call(Request) ->
>         server:call(refserver, Request, ?TIMEOUT).

> This will be expanded to:

>     call(Request) ->
>         server:call(refserver, Request, 200).

> A macro `?Func(Arg1,...,ArgN)` will be replaced with `Replacement`, where all occurences of a variable `Var` from the macro definition are replaced with the corresponding argument `Arg`. Example:

>     -define(MACRO1(X, Y), {a, X, b, Y}).
>     ...
>     bar(X) ->
>         ?MACRO1(a, b),
>         ?MACRO1(X, 123)

> This will be expanded to:

>     bar(X) ->
>         {a,a,b,b},
>         {a,X,b,123}.

> It is good programming practice, but not mandatory, to ensure that a macro definition is a valid Erlang syntactic form.

> To view the result of macro expansion, a module can be compiled with the `'P'` option. `compile:file(File, ['P'])`. This produces a listing of the parsed code after preprocessing and parse transforms, in the file `File.P`.

> ### 7.2 Predefined Macros

> The following macros are predefined:

> `?MODULE`
>   The name of the current module.
> `?MODULE_STRING`.
>   The name of the current module, as a string.
> `?FILE`.
>   The file name of the current module.
> `?LINE`.
>   The current line number.
> `?MACHINE`.
>   The machine name, `'BEAM'`.

> ### 7.3 Flow Control in Macros

> The following macro directives are supplied:

> `-undef(Macro).`
>   Causes the macro to behave as if it had never been defined.
> `-ifdef(Macro).`
>   Evaluate the following lines only if `Macro` is defined.
> `-ifndef(Macro).`
>   Evaluate the following lines only if `Macro` is not defined.
> `-else.`
>   Only allowed after an `ifdef` or `ifndef` directive. If that condition was false, the lines following `else` are evaluated instead.
> `-endif.`
>   Specifies the end of an `ifdef` or `ifndef` directive.

> Example:

>     -module(m).
>     ...

>     -ifdef(debug).
>     -define(LOG(X), io:format("{~p,~p}: ~p~n", [?MODULE,?LINE,X])).
>     -else.
>     -define(LOG(X), true).
>     -endif.

>     ...

> When trace output is desired, `debug` should be defined when the module `m` is compiled:

>     % erlc -Ddebug m.erl

>     or

>     1> c(m, {d, debug}).
>     {ok,m}

> `?LOG(Arg)` will then expand to a call to `io:format/2` and provide the user with some simple trace output.

> ### 7.4 Stringifying Macro Arguments

> The construction `??Arg`, where `Arg` is a macro argument, will be expanded to a string containing the tokens of the argument. This is similar to the `#arg` stringifying construction in C.

> The feature was added in Erlang 5.0/OTP R7.

> Example:

>     -define(TESTCALL(Call), io:format("Call ~s: ~w~n", [??Call, Call])).

>     ?TESTCALL(myfunction(1,2)),
>     ?TESTCALL(you:function(2,1)).

> results in

>     io:format("Call ~s: ~w~n",["myfunction ( 1 , 2 )",m:myfunction(1,2)]),
>     io:format("Call ~s: ~w~n",["you : function ( 2 , 1 )",you:function(2,1)]).

> That is, a trace output with both the function called and the resulting value.

Copyright © 1991-2003 Ericsson Utvecklings AB