aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--system/doc/reference_manual/macros.xml83
1 files changed, 83 insertions, 0 deletions
diff --git a/system/doc/reference_manual/macros.xml b/system/doc/reference_manual/macros.xml
index a1ba182eff..9d09ba9cb9 100644
--- a/system/doc/reference_manual/macros.xml
+++ b/system/doc/reference_manual/macros.xml
@@ -140,6 +140,89 @@ bar(X) ->
</section>
<section>
+ <title>Macros Overloading</title>
+ <warning>
+ <p>This section describes a feature introduced in R13B04. It remains fully
+ compatible with old code but previous versions of erlang does not support
+ the macros overloading.</p>
+ </warning>
+ <p>It is possible to have more than one definition of the same macro, except
+ for predefined macros. Only user-defined macros are considered here. In
+ order to overload a macro, a different signature should be used for each
+ overloaded version. A macro signature consists of its name and its number of
+ arguments.</p>
+
+ <taglist>
+ <tag>Object-like macro has no arguments</tag>
+ <item><code type="none">
+-define(M, io:format("object-like macro")).</code>
+ </item>
+ <tag>Function-like macro has 0 or more arguments.</tag>
+ <item><code type="none">
+-define(M(), io:format("function-like macro with 0 argument")).
+-define(M(X), io:format("function-like macro with 1 argument: ~p", [X])).
+-define(M(X, Y), io:format("function-like macro with 2 arguments: (~p, ~p)", [X,Y])).</code>
+ </item>
+ </taglist>
+ <p>An object-like macro should not be confused with a function-like macro
+ with 0 argument.</p>
+
+ <p>When a macro is used, the preprocessor selects the proper macro following
+ these rules: </p>
+ <list type="bulleted">
+ <item>if there is only the object-like definition, the preprocessor uses
+ it. Example:</item>
+<code type="none">
+-define(FUN, now).
+...
+call() ->
+ {?FUN, ?FUN()}.</code>
+This will be expended to:
+<code type="none">
+call() ->
+ {now, now()}.</code>
+
+ <item>if the preprocessor recognizes an object-like macro call, and if its
+ definition exists, the preprocessor uses it. Example:</item>
+<code type="none">
+-define(MOD, erlang).
+-define(MOD(X), X).
+...
+call() ->
+ ?MOD:module_info().</code>
+This will be expended to:
+<code type="none">
+call() ->
+ erlang:module_info().</code>
+
+ <item>if the preprocessor recognizes a function-like macro call, the
+ preprocessor chooses the definition with the same number of
+ arguments. Example: </item>
+<code type="none">
+-define(CALL(Fun), Fun()).
+-define(CALL(Mod, Fun), Mod:Fun()).
+...
+call() ->
+ ?CALL(kernel, module_info).</code>
+This will be expended to:
+<code type="none">
+call() ->
+ kernel:module_info().</code>
+
+ <item>in all other cases, the preprocessor throws an
+ error. Example:</item>
+<code type="none">
+-define(M, erlang).
+-define(M(X), X).
+...
+call() ->
+ ?M(kernel, module_info).</code>
+The compiler will fail with error <c>argument mismatch for macro 'M'</c>
+
+ </list>
+ </section>
+
+ <section>
<title>Flow Control in Macros</title>
<p>The following macro directives are supplied:</p>
<taglist>