aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/reference_manual/macros.xml
diff options
context:
space:
mode:
Diffstat (limited to 'system/doc/reference_manual/macros.xml')
-rw-r--r--system/doc/reference_manual/macros.xml96
1 files changed, 53 insertions, 43 deletions
diff --git a/system/doc/reference_manual/macros.xml b/system/doc/reference_manual/macros.xml
index 9fd0b0f287..3b1f72e5d6 100644
--- a/system/doc/reference_manual/macros.xml
+++ b/system/doc/reference_manual/macros.xml
@@ -4,24 +4,25 @@
<chapter>
<header>
<copyright>
- <year>2003</year><year>2013</year>
+ <year>2003</year><year>2015</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
- The contents of this file are subject to the Erlang Public License,
- Version 1.1, (the "License"); you may not use this file except in
- 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.
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
</legalnotice>
- <title>The Preprocessor</title>
+ <title>Preprocessor</title>
<prepared></prepared>
<docno></docno>
<date></date>
@@ -31,17 +32,17 @@
<section>
<title>File Inclusion</title>
- <p>A file can be included in the following way:</p>
+ <p>A file can be included as follows:</p>
<pre>
-include(File).
-include_lib(File).</pre>
- <p><c>File</c>, a string, should point out a file. The contents of
- this file are included as-is, at the position of the directive.</p>
+ <p><c>File</c>, a string, is to point out a file. The contents of
+ this file are included as is, at the position of the directive.</p>
<p>Include files are typically used for record and macro
definitions that are shared by several modules. It is
- recommended that the file name extension <c>.hrl</c> be used
- for include files.</p>
- <p><c>File</c> may start with a path component <c>$VAR</c>, for
+ recommended to use the file name extension <c>.hrl</c> for
+ include files.</p>
+ <p><c>File</c> can start with a path component <c>$VAR</c>, for
some string <c>VAR</c>. If that is the case, the value of
the environment variable <c>VAR</c> as returned by
<c>os:getenv(VAR)</c> is substituted for <c>$VAR</c>. If
@@ -49,21 +50,29 @@
as is.</p>
<p>If the filename <c>File</c> 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 <c>include</c> option, in that order.
- See <c>erlc(1)</c> and <c>compile(3)</c> for details.</p>
- <p>Examples:</p>
+ included. Otherwise, the specified file is searched for
+ in the following directories, and in this order:</p>
+ <list type="ordered">
+ <item>The current working directory</item>
+ <item>The directory where the module is being compiled</item>
+ <item>The directories given by the <c>include</c> option</item>
+ </list>
+ <p>For details, see the
+ <seealso marker="erts:erlc">erlc(1)</seealso> manual page
+ in ERTS and
+ <seealso marker="compiler:compile">compile(3)</seealso>
+ manual page in Compiler.</p>
+ <p><em>Examples:</em></p>
<pre>
-include("my_records.hrl").
-include("incdir/my_records.hrl").
-include("/home/user/proj/my_records.hrl").
-include("$PROJ_ROOT/my_records.hrl").</pre>
- <p><c>include_lib</c> is similar to <c>include</c>, but should not
+ <p><c>include_lib</c> is similar to <c>include</c>, 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:</p>
+ the name of an application.</p>
+ <p><em>Example:</em></p>
<pre>
-include_lib("kernel/include/file.hrl").</pre>
<p>The code server uses <c>code:lib_dir(kernel)</c> to find
@@ -74,7 +83,7 @@
<section>
<title>Defining and Using Macros</title>
- <p>A macro is defined the following way:</p>
+ <p>A macro is defined as follows:</p>
<code type="none">
-define(Const, Replacement).
-define(Func(Var1,...,VarN), Replacement).</code>
@@ -83,33 +92,34 @@
come before any usage of the macro.</p>
<p>If a macro is used in several modules, it is recommended that
the macro definition is placed in an include file.</p>
- <p>A macro is used the following way:</p>
+ <p>A macro is used as follows:</p>
<code type="none">
?Const
?Func(Arg1,...,ArgN)</code>
<p>Macros are expanded during compilation. A simple macro
- <c>?Const</c> will be replaced with <c>Replacement</c>.
- Example:</p>
+ <c>?Const</c> is replaced with <c>Replacement</c>.</p>
+ <p><em>Example:</em></p>
<code type="none">
-define(TIMEOUT, 200).
...
call(Request) ->
server:call(refserver, Request, ?TIMEOUT).</code>
- <p>This will be expanded to:</p>
+ <p>This is expanded to:</p>
<code type="none">
call(Request) ->
server:call(refserver, Request, 200).</code>
- <p>A macro <c>?Func(Arg1,...,ArgN)</c> will be replaced with
+ <p>A macro <c>?Func(Arg1,...,ArgN)</c> is replaced with
<c>Replacement</c>, where all occurrences of a variable <c>Var</c>
from the macro definition are replaced with the corresponding
- argument <c>Arg</c>. Example:</p>
+ argument <c>Arg</c>.</p>
+ <p><em>Example:</em></p>
<code type="none">
-define(MACRO1(X, Y), {a, X, b, Y}).
...
bar(X) ->
?MACRO1(a, b),
?MACRO1(X, 123)</code>
- <p>This will be expanded to:</p>
+ <p>This is expanded to:</p>
<code type="none">
bar(X) ->
{a,a,b,b},
@@ -154,7 +164,7 @@ bar(X) ->
-define(F0(), c).
-define(F1(A), A).
-define(C, m:f).</code>
- <p>the following will not work:</p>
+ <p>the following does not work:</p>
<code type="none">
f0() ->
?F0. % No, an empty list of arguments expected.
@@ -165,7 +175,7 @@ f1(A) ->
<code>
f() ->
?C().</code>
- <p>will expand to</p>
+ <p>is expanded to</p>
<code>
f() ->
m:f().</code>
@@ -185,7 +195,7 @@ f() ->
defined.</item>
<tag><c>-else.</c></tag>
<item>Only allowed after an <c>ifdef</c> or <c>ifndef</c>
- directive. If that condition was false, the lines following
+ directive. If that condition is false, the lines following
<c>else</c> are evaluated instead.</item>
<tag><c>-endif.</c></tag>
<item>Specifies the end of an <c>ifdef</c> or <c>ifndef</c>
@@ -194,7 +204,7 @@ f() ->
<note>
<p>The macro directives cannot be used inside functions.</p>
</note>
- <p>Example:</p>
+ <p><em>Example:</em></p>
<code type="none">
-module(m).
...
@@ -206,7 +216,7 @@ f() ->
-endif.
...</code>
- <p>When trace output is desired, <c>debug</c> should be defined
+ <p>When trace output is desired, <c>debug</c> is to be defined
when the module <c>m</c> is compiled:</p>
<pre>
% <input>erlc -Ddebug m.erl</input>
@@ -215,18 +225,18 @@ or
1> <input>c(m, {d, debug}).</input>
{ok,m}</pre>
- <p><c>?LOG(Arg)</c> will then expand to a call to <c>io:format/2</c>
+ <p><c>?LOG(Arg)</c> is then expanded to a call to <c>io:format/2</c>
and provide the user with some simple trace output.</p>
</section>
<section>
<title>Stringifying Macro Arguments</title>
<p>The construction <c>??Arg</c>, where <c>Arg</c> 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 <c>#arg</c> stringifying
construction in C.</p>
<p>The feature was added in Erlang 5.0/OTP R7.</p>
- <p>Example:</p>
+ <p><em>Example:</em></p>
<code type="none">
-define(TESTCALL(Call), io:format("Call ~s: ~w~n", [??Call, Call])).
@@ -236,7 +246,7 @@ or
<code type="none">
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)]).</code>
- <p>That is, a trace output with both the function called and
+ <p>That is, a trace output, with both the function called and
the resulting value.</p>
</section>
</chapter>