From 4c182740d7180d3bdc8573ca17905898dcc2b819 Mon Sep 17 00:00:00 2001 From: Christopher Faulet Date: Thu, 10 Dec 2009 11:02:23 +0100 Subject: update the documentation on preprocessor in the reference manual New section added on Macros Overloading --- system/doc/reference_manual/macros.xml | 83 ++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) (limited to 'system') 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 @@ -139,6 +139,89 @@ bar(X) -> +
+ Macros Overloading + +

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.

+ +

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.

+ + + Object-like macro has no arguments + +-define(M, io:format("object-like macro")). + + Function-like macro has 0 or more arguments. + +-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])). + + +

An object-like macro should not be confused with a function-like macro + with 0 argument.

+ +

When a macro is used, the preprocessor selects the proper macro following + these rules:

+ + if there is only the object-like definition, the preprocessor uses + it. Example: + +-define(FUN, now). +... +call() -> + {?FUN, ?FUN()}. +This will be expended to: + +call() -> + {now, now()}. + + if the preprocessor recognizes an object-like macro call, and if its + definition exists, the preprocessor uses it. Example: + +-define(MOD, erlang). +-define(MOD(X), X). +... +call() -> + ?MOD:module_info(). +This will be expended to: + +call() -> + erlang:module_info(). + + if the preprocessor recognizes a function-like macro call, the + preprocessor chooses the definition with the same number of + arguments. Example: + +-define(CALL(Fun), Fun()). +-define(CALL(Mod, Fun), Mod:Fun()). +... +call() -> + ?CALL(kernel, module_info). +This will be expended to: + +call() -> + kernel:module_info(). + + in all other cases, the preprocessor throws an + error. Example: + +-define(M, erlang). +-define(M(X), X). +... +call() -> + ?M(kernel, module_info). +The compiler will fail with error argument mismatch for macro 'M' + + +
+
Flow Control in Macros

The following macro directives are supplied:

-- cgit v1.2.3 From c41689666b0410b51c1fe6acb9e2ec517fdfcad9 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Mon, 1 Feb 2010 14:38:07 +0100 Subject: documentation: Macros overloading partly rewritten --- system/doc/reference_manual/macros.xml | 113 +++++++++------------------------ 1 file changed, 31 insertions(+), 82 deletions(-) (limited to 'system') diff --git a/system/doc/reference_manual/macros.xml b/system/doc/reference_manual/macros.xml index 9d09ba9cb9..9dd5fc79bd 100644 --- a/system/doc/reference_manual/macros.xml +++ b/system/doc/reference_manual/macros.xml @@ -4,7 +4,7 @@
- 20032009 + 20032010 Ericsson AB. All Rights Reserved. @@ -13,12 +13,12 @@ compliance with the License. You should have received a copy of the Erlang Public License along with this software. If not, it can be retrieved online at http://www.erlang.org/. - + Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. - + The Preprocessor @@ -141,85 +141,34 @@ bar(X) ->
Macros Overloading - -

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.

- -

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.

- - - Object-like macro has no arguments - --define(M, io:format("object-like macro")). - - Function-like macro has 0 or more arguments. - --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])). - - -

An object-like macro should not be confused with a function-like macro - with 0 argument.

- -

When a macro is used, the preprocessor selects the proper macro following - these rules:

- - if there is only the object-like definition, the preprocessor uses - it. Example: - --define(FUN, now). -... -call() -> - {?FUN, ?FUN()}. -This will be expended to: - -call() -> - {now, now()}. - - if the preprocessor recognizes an object-like macro call, and if its - definition exists, the preprocessor uses it. Example: - --define(MOD, erlang). --define(MOD(X), X). -... -call() -> - ?MOD:module_info(). -This will be expended to: - -call() -> - erlang:module_info(). - - if the preprocessor recognizes a function-like macro call, the - preprocessor chooses the definition with the same number of - arguments. Example: - --define(CALL(Fun), Fun()). --define(CALL(Mod, Fun), Mod:Fun()). -... -call() -> - ?CALL(kernel, module_info). -This will be expended to: - -call() -> - kernel:module_info(). - - in all other cases, the preprocessor throws an - error. Example: - --define(M, erlang). --define(M(X), X). -... -call() -> - ?M(kernel, module_info). -The compiler will fail with error argument mismatch for macro 'M' - - +

It is possible to overload macros, except for predefined + macros. An overloaded macro has more than one definition, + each with a different number of arguments.

+

The feature was added in Erlang 5.7.5/OTP R13B04.

+

A macro ?Func(Arg1,...,ArgN) with a (possibly empty) + list of arguments results in an error message if there is at + least one definition of Func with arguments, but none + with N arguments.

+

Assuming these definitions:

+ +-define(F0(), c). +-define(F1(A), A). +-define(C, m:f). +

the following will not work:

+ +f0() -> + ?F0. % No, an empty list of arguments expected. + +f1(A) -> + ?F1(A, A). % No, exactly one argument expected. +

On the other hand,

+ +f() -> + ?C(). +

will expand to

+ +f() -> + m:f().
-- cgit v1.2.3