← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to system/doc/reference_manual/macros.xml

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
system/doc/reference_manual/macros.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>2003</year><year>2010</year>
 
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
 
9
    </copyright>
 
10
    <legalnotice>
 
11
      The contents of this file are subject to the Erlang Public License,
 
12
      Version 1.1, (the "License"); you may not use this file except in
 
13
      compliance with the License. You should have received a copy of the
 
14
      Erlang Public License along with this software. If not, it can be
 
15
      retrieved online at http://www.erlang.org/.
 
16
 
 
17
      Software distributed under the License is distributed on an "AS IS"
 
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
19
      the License for the specific language governing rights and limitations
 
20
      under the License.
 
21
 
 
22
    </legalnotice>
 
23
 
 
24
    <title>The Preprocessor</title>
 
25
    <prepared></prepared>
 
26
    <docno></docno>
 
27
    <date></date>
 
28
    <rev></rev>
 
29
    <file>macros.xml</file>
 
30
  </header>
 
31
 
 
32
    <section>
 
33
      <title>File Inclusion</title>
 
34
      <p>A file can be included in the following way:</p>
 
35
      <pre>
 
36
-include(File).
 
37
-include_lib(File).</pre>
 
38
      <p><c>File</c>, a string, should point out a file. The contents of
 
39
        this file are included as-is, at the position of the directive.</p>
 
40
      <p>Include files are typically used for record and macro
 
41
        definitions that are shared by several modules. It is
 
42
        recommended that the file name extension <c>.hrl</c> be used
 
43
        for include files.</p>
 
44
      <p><c>File</c> may start with a path component <c>$VAR</c>, for
 
45
        some string <c>VAR</c>. If that is the case, the value of
 
46
        the environment variable <c>VAR</c> as returned by
 
47
        <c>os:getenv(VAR)</c> is substituted for <c>$VAR</c>. If
 
48
        <c>os:getenv(VAR)</c> returns <c>false</c>, <c>$VAR</c> is left
 
49
        as is.</p>
 
50
      <p>If the filename <c>File</c> is absolute (possibly after
 
51
        variable substitution), the include file with that name is
 
52
        included. Otherwise, the specified file is searched for in
 
53
        the current working directory, in the same directory as
 
54
        the module being compiled, and in the directories given by
 
55
        the <c>include</c> option, in that order.
 
56
        See <c>erlc(1)</c> and <c>compile(3)</c> for details.</p>
 
57
      <p>Examples:</p>
 
58
      <pre>
 
59
-include("my_records.hrl").
 
60
-include("incdir/my_records.hrl").
 
61
-include("/home/user/proj/my_records.hrl").
 
62
-include("$PROJ_ROOT/my_records.hrl").</pre>
 
63
      <p><c>include_lib</c> is similar to <c>include</c>, but should not
 
64
        point out an absolute file. Instead, the first path component
 
65
        (possibly after variable substitution) is assumed to be
 
66
        the name of an application. Example:</p>
 
67
      <pre>
 
68
-include_lib("kernel/include/file.hrl").</pre>
 
69
      <p>The code server uses <c>code:lib_dir(kernel)</c> to find
 
70
        the directory of the current (latest) version of Kernel, and
 
71
        then the subdirectory <c>include</c> is searched for the file
 
72
        <c>file.hrl</c>.</p>
 
73
    </section>
 
74
 
 
75
  <section>
 
76
    <title>Defining and Using Macros</title>
 
77
    <p>A macro is defined the following way:</p>
 
78
    <code type="none">
 
79
-define(Const, Replacement).
 
80
-define(Func(Var1,...,VarN), Replacement).</code>
 
81
    <p>A macro definition can be placed anywhere among the attributes
 
82
      and function declarations of a module, but the definition must
 
83
      come before any usage of the macro.</p>
 
84
    <p>If a macro is used in several modules, it is recommended that
 
85
      the macro definition is placed in an include file.</p>
 
86
    <p>A macro is used the following way:</p>
 
87
    <code type="none">
 
88
?Const
 
89
?Func(Arg1,...,ArgN)</code>
 
90
    <p>Macros are expanded during compilation. A simple macro
 
91
      <c>?Const</c> will be replaced with <c>Replacement</c>.
 
92
      Example:</p>
 
93
    <code type="none">
 
94
-define(TIMEOUT, 200).
 
95
...
 
96
call(Request) ->
 
97
    server:call(refserver, Request, ?TIMEOUT).</code>
 
98
    <p>This will be expanded to:</p>
 
99
    <code type="none">
 
100
call(Request) ->
 
101
    server:call(refserver, Request, 200).</code>
 
102
    <p>A macro <c>?Func(Arg1,...,ArgN)</c> will be replaced with
 
103
      <c>Replacement</c>, where all occurrences of a variable <c>Var</c>
 
104
      from the macro definition are replaced with the corresponding
 
105
      argument <c>Arg</c>. Example:</p>
 
106
    <code type="none">
 
107
-define(MACRO1(X, Y), {a, X, b, Y}).
 
108
...
 
109
bar(X) ->
 
110
    ?MACRO1(a, b),
 
111
    ?MACRO1(X, 123)</code>
 
112
    <p>This will be expanded to:</p>
 
113
    <code type="none">
 
114
bar(X) ->
 
115
    {a,a,b,b},
 
116
    {a,X,b,123}.</code>
 
117
    <p>It is good programming practice, but not mandatory, to ensure
 
118
      that a macro definition is a valid Erlang syntactic form.</p>
 
119
    <p>To view the result of macro expansion, a module can be compiled
 
120
      with the <c>'P'</c> option. <c>compile:file(File, ['P'])</c>.
 
121
      This produces a listing of the parsed code after preprocessing
 
122
      and parse transforms, in the file <c>File.P</c>.</p>
 
123
  </section>
 
124
 
 
125
  <section>
 
126
    <title>Predefined Macros</title>
 
127
    <p>The following macros are predefined:</p>
 
128
    <taglist>
 
129
      <tag><c>?MODULE</c></tag>
 
130
      <item>The name of the current module.</item>
 
131
      <tag><c>?MODULE_STRING</c>.</tag>
 
132
      <item>The name of the current module, as a string.</item>
 
133
      <tag><c>?FILE</c>.</tag>
 
134
      <item>The file name of the current module.</item>
 
135
      <tag><c>?LINE</c>.</tag>
 
136
      <item>The current line number.</item>
 
137
      <tag><c>?MACHINE</c>.</tag>
 
138
      <item>The machine name, <c>'BEAM'</c>.</item>
 
139
    </taglist>
 
140
  </section>
 
141
 
 
142
  <section>
 
143
    <title>Macros Overloading</title>
 
144
    <p>It is possible to overload macros, except for predefined
 
145
      macros. An overloaded macro has more than one definition,
 
146
      each with a different number of arguments.</p>
 
147
    <p>The feature was added in Erlang 5.7.5/OTP R13B04.</p>
 
148
    <p>A macro <c>?Func(Arg1,...,ArgN)</c> with a (possibly empty)
 
149
      list of arguments results in an error message if there is at
 
150
      least one definition of <c>Func</c> with arguments, but none
 
151
      with N arguments.</p>
 
152
    <p>Assuming these definitions:</p>
 
153
    <code type="none">
 
154
-define(F0(), c).
 
155
-define(F1(A), A).
 
156
-define(C, m:f).</code>
 
157
    <p>the following will not work:</p>
 
158
    <code type="none">
 
159
f0() ->
 
160
    ?F0. % No, an empty list of arguments expected.
 
161
 
 
162
f1(A) ->
 
163
    ?F1(A, A). % No, exactly one argument expected.</code>
 
164
    <p>On the other hand,</p>
 
165
    <code>
 
166
f() ->
 
167
    ?C().</code>
 
168
    <p>will expand to</p>
 
169
    <code>
 
170
f() ->
 
171
    m:f().</code>
 
172
  </section>
 
173
 
 
174
  <section>
 
175
    <title>Flow Control in Macros</title>
 
176
    <p>The following macro directives are supplied:</p>
 
177
    <taglist>
 
178
      <tag><c>-undef(Macro).</c></tag>
 
179
      <item>Causes the macro to behave as if it had never been defined.</item>
 
180
      <tag><c>-ifdef(Macro).</c></tag>
 
181
      <item>Evaluate the following lines only if <c>Macro</c> is
 
182
       defined.</item>
 
183
      <tag><c>-ifndef(Macro).</c></tag>
 
184
      <item>Evaluate the following lines only if <c>Macro</c> is not
 
185
       defined.</item>
 
186
      <tag><c>-else.</c></tag>
 
187
      <item>Only allowed after an <c>ifdef</c> or <c>ifndef</c>
 
188
       directive. If that condition was false, the lines following
 
189
      <c>else</c> are evaluated instead.</item>
 
190
      <tag><c>-endif.</c></tag>
 
191
      <item>Specifies the end of an <c>ifdef</c> or <c>ifndef</c>
 
192
       directive.</item>
 
193
    </taglist>
 
194
    <note>
 
195
      <p>The macro directives cannot be used inside functions.</p>
 
196
    </note>
 
197
    <p>Example:</p>
 
198
    <code type="none">
 
199
-module(m).
 
200
...
 
201
 
 
202
-ifdef(debug).
 
203
-define(LOG(X), io:format("{~p,~p}: ~p~n", [?MODULE,?LINE,X])).
 
204
-else.
 
205
-define(LOG(X), true).
 
206
-endif.
 
207
 
 
208
...</code>
 
209
    <p>When trace output is desired, <c>debug</c> should be defined
 
210
      when the module <c>m</c> is compiled:</p>
 
211
    <pre>
 
212
% <input>erlc -Ddebug m.erl</input>
 
213
 
 
214
or
 
215
 
 
216
1> <input>c(m, {d, debug}).</input>
 
217
{ok,m}</pre>
 
218
    <p><c>?LOG(Arg)</c> will then expand to a call to <c>io:format/2</c>
 
219
      and provide the user with some simple trace output.</p>
 
220
  </section>
 
221
 
 
222
  <section>
 
223
    <title>Stringifying Macro Arguments</title>
 
224
    <p>The construction <c>??Arg</c>, where <c>Arg</c> is a macro
 
225
      argument, will be expanded to a string containing the tokens of
 
226
      the argument. This is similar to the <c>#arg</c> stringifying
 
227
      construction in C.</p>
 
228
    <p>The feature was added in Erlang 5.0/OTP R7.</p>
 
229
    <p>Example:</p>
 
230
    <code type="none">
 
231
-define(TESTCALL(Call), io:format("Call ~s: ~w~n", [??Call, Call])).
 
232
 
 
233
?TESTCALL(myfunction(1,2)),
 
234
?TESTCALL(you:function(2,1)).</code>
 
235
    <p>results in</p>
 
236
    <code type="none">
 
237
io:format("Call ~s: ~w~n",["myfunction ( 1 , 2 )",m:myfunction(1,2)]),
 
238
io:format("Call ~s: ~w~n",["you : function ( 2 , 1 )",you:function(2,1)]).</code>
 
239
    <p>That is, a trace output with both the function called and
 
240
      the resulting value.</p>
 
241
  </section>
 
242
</chapter>
 
243