Erlang: macros

I'm not a big fan of metaprogramming, but it's necessary to know more than one ways to remove duplication in our programs: this way you can compare the available tools, instead of blindly following subroutine extraction because it's the only known way to remove redundant code.

So here are two ways to extract duplicated code in Erlang:

• concentrate the code in a function that is called or instantiated multiple times.
• Concentrate the code into a construct that generates multiple functions or lists of statements.

Macros (the latter item) are expanded at compile time to Erlang code, so that they are directly substituted into the calling code. As an example from another language, consider C preprocessing directives such as #define and #ifdef, or function inlining; dynamic language macros such as Lisp quoting and unquoting are not a good comparison as it consists of code generation, not of compile-time substitution.

Why not functions?

For starters, macros have the ability to be called where a function can't; the book Erlang programming makes the example of making guard clauses readable by generating them with a macro.

Moreover, macros are a powerful debugging tool, because you can manipulate the code that produced an expression when passing it to a macro, instead of only act on the resulting value.
For example, EUnit's ?assertEqual itself is a macro and not a function. When it fails, it can show you not only the difference between the expected and the actual value, but also the original expression that generated it:

fail_test() -> ?assertEqual(43, 21 + 21).

results in:

macros_11: fail_test...*failed*
::error:{assertEqual_failed,[{module,macros_11},
  {line,32},
  {expression,"21 + 21"},
  {expected,43},
  {value,42}]}
  in function macros_11:'-fail_test/0-fun-0-'/1

This introspection over expressions saves you from writing many assertion messages to clear up failure reasons. In a world where unit tests commonly issue multiple processes, debugging comes at your rescue.

Note also that due to Erlang's background, macros can generate different versions of the code for development and production, like in C programs. The seams for testing and isolation are available at compile time, not at runtime like we are used to with Java and other higher-level languages. Nevertheless, Michael Feathers defines this kind of seam as equally valid for testing in Working effectively with legacy code.

In practice

The simplest use of a macro is for constant definition:

-define(ANSWER, 42).

constant_test() ->
  ?assertEqual(42, ?ANSWER).

The macro is defined with a base name, which is then recalled by prepending a ? to it.

Macros are not only single symbols: they can compose expressions while being substituted.

-define(INC, 1+).

hello_test() ->
  ?assertEqual(43, ?INC 42).

Macros, for being at least equivalent to functions, must be able to take arguments:

-define(HELLO(Who), string:concat("Hello, ", Who)).

parameterized_test() ->
  ?assertEqual("Hello, World!", ?HELLO("World")).

And as suggested by our textbook, we can rewrite guard clauses in English via defining macros for them:

-define(IsZero(N), N == 0).

factorial(N) when ?IsZero(N) -> 1;
factorial(N)  -> N * factorial(N - 1).

cannot_always_use_a_function_test() ->
  ?assertEqual(6, factorial(3)).

The introspection capability of macros is accessible via some special expressions available inside their definition. ??Parameter generates a string containing the expression that generated Parameter.

-define(VALUE(Call),[??Call,Call]).

debugging_test() ->
  ?assertEqual(["length ( [ 1 , 2 , 3 ] )", 3], ?VALUE(length([1,2,3]))).  

Moreover, some magic constants (a la PHP __DIR__ and __FILE__) are substituted at compile time for you:

magic_constants_test() ->
  ?assertEqual(macros_11, ?MODULE),
  ?assertEqual("macros_11", ?MODULE_STRING),
  ?assertEqual("src/macros_11.erl", ?FILE),
  ?assertEqual(36, ?LINE).

Conclusions

Macros are a powerful tool, that can easily be abused if it's not clearly defined when functions are the simplest choice; after all, you're generating code instead of executing what you have written, adding an indirection step between you and the machine. Indirection can solve all problems in computer science, but it can also create lots of them when there's debugging.
All the code for this article is available on Github.