From 9fe8adf35c16ab5d4566b03f3b36863c90b5b6dd Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Thu, 12 Mar 2015 15:35:13 +0100 Subject: Update Erlang Reference Manual Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Hans Bolinder. --- system/doc/reference_manual/macros.xml | 75 +++++++++++++++++++--------------- 1 file changed, 42 insertions(+), 33 deletions(-) (limited to 'system/doc/reference_manual/macros.xml') diff --git a/system/doc/reference_manual/macros.xml b/system/doc/reference_manual/macros.xml index 9fd0b0f287..01994aae5e 100644 --- a/system/doc/reference_manual/macros.xml +++ b/system/doc/reference_manual/macros.xml @@ -4,7 +4,7 @@
- 20032013 + 20032015 Ericsson AB. All Rights Reserved. @@ -21,7 +21,7 @@ - The Preprocessor + Preprocessor @@ -31,17 +31,17 @@
File Inclusion -

A file can be included in the following way:

+

A file can be included as follows:

 -include(File).
 -include_lib(File).
-

File, a string, should point out a file. The contents of - this file are included as-is, at the position of the directive.

+

File, a string, is to point out a file. The contents of + this file are included as is, at the position of the directive.

Include files are typically used for record and macro definitions that are shared by several modules. It is - recommended that the file name extension .hrl be used - for include files.

-

File may start with a path component $VAR, for + recommended to use the file name extension .hrl for + include files.

+

File can start with a path component $VAR, for some string VAR. If that is the case, the value of the environment variable VAR as returned by os:getenv(VAR) is substituted for $VAR. If @@ -49,21 +49,29 @@ as is.

If the filename File is absolute (possibly after variable substitution), the include file with that name is - included. Otherwise, the specified file is searched for in - the current working directory, in the same directory as - the module being compiled, and in the directories given by - the include option, in that order. - See erlc(1) and compile(3) for details.

-

Examples:

+ included. Otherwise, the specified file is searched for + in the following directories, and in this order:

+ + The current working directory + The directory where the module is being compiled + The directories given by the include option + +

For details, see the + erlc(1) manual page + in ERTS and + compile(3) + manual page in Compiler.

+

Examples:

 -include("my_records.hrl").
 -include("incdir/my_records.hrl").
 -include("/home/user/proj/my_records.hrl").
 -include("$PROJ_ROOT/my_records.hrl").
-

include_lib is similar to include, but should not +

include_lib is similar to include, but is not to point out an absolute file. Instead, the first path component (possibly after variable substitution) is assumed to be - the name of an application. Example:

+ the name of an application.

+

Example:

 -include_lib("kernel/include/file.hrl").

The code server uses code:lib_dir(kernel) to find @@ -74,7 +82,7 @@

Defining and Using Macros -

A macro is defined the following way:

+

A macro is defined as follows:

-define(Const, Replacement). -define(Func(Var1,...,VarN), Replacement). @@ -83,33 +91,34 @@ 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:

+

A macro is used as follows:

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

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

+ ?Const is replaced with Replacement.

+

Example:

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

This will be expanded to:

+

This is expanded to:

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

A macro ?Func(Arg1,...,ArgN) will be replaced with +

A macro ?Func(Arg1,...,ArgN) is replaced with Replacement, where all occurrences of a variable Var from the macro definition are replaced with the corresponding - argument Arg. Example:

+ argument Arg.

+

Example:

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

This will be expanded to:

+

This is expanded to:

bar(X) -> {a,a,b,b}, @@ -154,7 +163,7 @@ bar(X) -> -define(F0(), c). -define(F1(A), A). -define(C, m:f). -

the following will not work:

+

the following does not work:

f0() -> ?F0. % No, an empty list of arguments expected. @@ -165,7 +174,7 @@ f1(A) -> f() -> ?C(). -

will expand to

+

is expanded to

f() -> m:f(). @@ -185,7 +194,7 @@ f() -> defined. -else. Only allowed after an ifdef or ifndef - directive. If that condition was false, the lines following + directive. If that condition is false, the lines following else are evaluated instead. -endif. Specifies the end of an ifdef or ifndef @@ -194,7 +203,7 @@ f() ->

The macro directives cannot be used inside functions.

 -

Example:

+

Example:

-module(m). ... @@ -206,7 +215,7 @@ f() -> -endif. ... -

When trace output is desired, debug should be defined +

When trace output is desired, debug is to be defined when the module m is compiled:

 % erlc -Ddebug m.erl
@@ -215,18 +224,18 @@ or
 
 1> c(m, {d, debug}).
 {ok,m}
-

?LOG(Arg) will then expand to a call to io:format/2 +

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

Stringifying Macro Arguments

The construction ??Arg, where Arg is a macro - argument, will be expanded to a string containing the tokens of + argument, is 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:

+

Example:

-define(TESTCALL(Call), io:format("Call ~s: ~w~n", [??Call, Call])). @@ -236,7 +245,7 @@ or io:format("Call ~s: ~w~n",["myfunction ( 1 , 2 )",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 +

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

-- cgit v1.2.3