aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/reference_manual/modules.xml
blob: 6f93198ec1c75f3ffd7731172a0bf1d5ba7fa032 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2003</year><year>2018</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      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>Modules</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
    <file>modules.xml</file>
  </header>

  <section>
    <title>Module Syntax</title>
    <p>Erlang code is divided into <em>modules</em>. A module consists
      of a sequence of attributes and function declarations, each
      terminated by period (.).</p>
      <p><em>Example:</em></p>
    <pre>
-module(m).          % module attribute
-export([fact/1]).   % module attribute

fact(N) when N>0 ->  % beginning of function declaration
    N * fact(N-1);   %  |
fact(0) ->           %  |
    1.               % end of function declaration</pre>
    <p>For a description of function declarations, see
    <seealso marker="functions">Function Declaration Syntax</seealso>.</p>
  </section>

  <section>
    <title>Module Attributes</title>
    <p>A <em>module attribute</em> defines a certain property of a
      module.</p>
    <p>A module attribute consists of a tag and a value:</p>
    <pre>
-Tag(Value).</pre>
    <p><c>Tag</c> must be an atom, while <c>Value</c> must be a literal
      term. As a convenience in user-defined attributes, if the literal term
      <c>Value</c> has the syntax <c>Name/Arity</c>
      (where <c>Name</c> is an atom and <c>Arity</c> a positive integer),
	  the term <c>Name/Arity</c> is translated to <c>{Name,Arity}</c>.</p>

    <p>Any module attribute can be specified. The attributes are stored
      in the compiled code and can be retrieved by calling
      <c>Module:module_info(attributes)</c>, or by using the module
      <seealso marker="stdlib:beam_lib#chunks/2">beam_lib(3)</seealso>
       in STDLIB.</p>

    <p>Several module attributes have predefined meanings.
      Some of them have arity two, but user-defined module
      attributes must have arity one.</p>

    <section>
      <title>Pre-Defined Module Attributes</title>
      <p>Pre-defined module attributes is to be placed before any
        function declaration.</p>
      <taglist>
        <tag><c>-module(Module).</c></tag>
        <item>
          <p>Module declaration, defining the name of the module.
            The name <c>Module</c>, an atom, is to be same as
            the file name minus the extension <c>.erl</c>. Otherwise
            <seealso marker="code_loading#loading">code loading</seealso> does
            not work as intended.</p>
          <p>This attribute is to be specified first and is the only
            mandatory attribute.</p>
        </item>
        <tag><c>-export(Functions).</c></tag>
        <item>
          <p>Exported functions. Specifies which of the functions,
            defined within the module, that are visible from outside
            the module.</p>
          <p><c>Functions</c> is a list
            <c>[Name1/Arity1, ..., NameN/ArityN]</c>, where each
            <c>NameI</c> is an atom and <c>ArityI</c> an integer.</p>
        </item>
        <tag><c>-import(Module,Functions).</c></tag>
        <item>
          <p>Imported functions. Can be called
            the same way as local functions, that is, without any module
            prefix.</p>
          <p><c>Module</c>, an atom, specifies which module to import
            functions from. <c>Functions</c> is a list similar as for
            <c>export</c>.</p>
        </item>
        <tag><c>-compile(Options).</c></tag>
        <item>
          <p>Compiler options. <c>Options</c> is a single option
            or a list of options.
            This attribute is added to the option list when
            compiling the module. See the <seealso marker="compiler:compile">
            compile(3)</seealso> manual page in Compiler.</p>
        </item>
        <tag><c>-vsn(Vsn).</c></tag>
        <item>
          <p>Module version. <c>Vsn</c> is any literal term and can be
            retrieved using <c>beam_lib:version/1</c>, see the
            <seealso marker="stdlib:beam_lib#version/1">beam_lib(3)</seealso>
            manual page in STDLIB.</p>
          <p>If this attribute is not specified, the version defaults
            to the MD5 checksum of the module.</p>
        </item>
        <tag><c>-on_load(Function).</c></tag>
        <item>
          <p>This attribute names a function that is to be run
            automatically when a
            module is loaded. For more information, see
	    <seealso marker="code_loading#on_load">
            Running a Function When a Module is Loaded</seealso>.</p>
        </item>
      </taglist>
    </section>

    <section>
      <title>Behaviour Module Attribute</title>
      <p>It is possible to specify that the module is the callback
        module for a <em>behaviour</em>:</p>
      <pre>
-behaviour(Behaviour).</pre>
      <p>The atom <c>Behaviour</c> gives the name of the behaviour,
        which can be a user-defined behaviour or one of the following OTP
        standard behaviours:</p>
	<list type="bulleted">
	  <item><c>gen_server</c></item>
	  <item><c>gen_statem</c></item>
	  <item><c>gen_event</c></item>
	  <item><c>supervisor</c></item>
	</list>
      <p>The spelling <c>behavior</c> is also accepted.</p>
      <p>The callback functions of the module can be specified either
        directly by the exported function <c>behaviour_info/1</c>:</p>
        <pre>
behaviour_info(callbacks) -> Callbacks.</pre>
      <p>or by a <c>-callback</c> attribute for each callback
        function:</p>
      <pre>
-callback Name(Arguments) -> Result.</pre>
      <p>Here, <c>Arguments</c> is a list of zero or more arguments.
       The <c>-callback</c> attribute is to be preferred since the
       extra type information can be used by tools to produce
       documentation or find discrepancies.</p>
      <p>Read more about behaviours and callback modules in
        <seealso marker="doc/design_principles:spec_proc#behaviours">
        OTP Design Principles</seealso>.</p>
    </section>

    <section>
      <title>Record Definitions</title>
      <p>The same syntax as for module attributes is used
        for record definitions:</p>
      <pre>
-record(Record,Fields).</pre>
      <p>Record definitions are allowed anywhere in a module,
        also among the function declarations.
	Read more in <seealso marker="records">Records</seealso>.</p>
    </section>

    <section>
      <title>Preprocessor</title>
      <p>The same syntax as for module attributes is used by
        the preprocessor, which supports file inclusion, macros,
	and conditional compilation:</p>
      <pre>
-include("SomeFile.hrl").
-define(Macro,Replacement).</pre>

      <p>Read more in <seealso marker="macros">Preprocessor</seealso>.</p>
    </section>

    <section>
      <title>Setting File and Line</title>
      <p>The same syntax as for module attributes is used for
        changing the pre-defined macros <c>?FILE</c> and <c>?LINE</c>:</p>
      <pre>
-file(File, Line).</pre>
      <p>This attribute is used by tools, such as Yecc, to inform the
        compiler that the source program is generated by another tool.
        It also indicates the correspondence of source files to lines of
        the original user-written file, from which the source program
        is produced.</p>
    </section>

    <section>
        <title>Types and function specifications</title>
	<p>A similar syntax as for module attributes is used for 
	specifying types and function specifications:
	</p>
	<pre>
-type my_type() :: atom() | integer().
-spec my_function(integer()) -> integer().</pre>
        <p>Read more in <seealso marker="typespec">Types and Function specifications</seealso>.
	</p>
	<p>
	  The description is based on
	    <url href="http://www.erlang.org/eeps/eep-0008.html">EEP8 -
	    Types and function specifications</url>,
	    which is not to be further updated.
	</p>
    </section>
  </section>

  <section>
    <title>Comments</title>
    <p>Comments can be placed anywhere in a module except within strings
      and quoted atoms. A comment begins with the character "%",
      continues up to, but does not include the next end-of-line, and
      has no effect. Notice that the terminating end-of-line has
      the effect of white space.</p>
  </section>

  <section>
    <title>module_info/0 and module_info/1 functions</title>

    <p>The compiler automatically inserts the two special, exported
      functions into each module:</p>
      <list type="bulleted">
	<item><c>Module:module_info/0</c></item>
	<item><c>Module:module_info/1</c></item>
      </list>
      <p>These functions can be called to retrieve information
        about the module.</p>

    <section>
      <title>module_info/0</title>
      <p>The <c>module_info/0</c> function in each module, returns
      a list of <c>{Key,Value}</c> tuples with information about
      the module. Currently, the list contain tuples with the following
      <c>Key</c>s: <c>module</c>, <c>attributes</c>, <c>compile</c>,
      <c>exports</c>, <c>md5</c> and <c>native</c>.
      The order and number of tuples
      may change without prior notice.</p>
    </section>

    <section>
      <title>module_info/1</title>
      <p>The call <c>module_info(Key)</c>, where <c>Key</c> is an atom,
       returns a single piece of information about the module.</p>

      <p>The following values are allowed for <c>Key</c>:</p>

      <taglist>
        <tag><c>module</c></tag>
	  <item>
	  <p>Returns an atom representing the module name.</p>
	  </item>

        <tag><c>attributes</c></tag>
	  <item>
	  <p>Returns a list of <c>{AttributeName,ValueList}</c> tuples,
	  where <c>AttributeName</c> is the name of an attribute,
	  and <c>ValueList</c> is a list of values. Notice that a given
	  attribute can occur more than once in the list with different
	  values if the attribute occurs more than once in the module.</p>

	  <p>The list of attributes becomes empty if
	  the module is stripped with the
	  <seealso marker="stdlib:beam_lib#strip/1">beam_lib(3)</seealso>
	  module (in STDLIB).</p>
	  </item>

        <tag><c>compile</c></tag>
	  <item>
	  <p>Returns a list of tuples with information about
	  how the module was compiled. This list is empty if
	  the module has been stripped with the
	  <seealso marker="stdlib:beam_lib#strip/1">beam_lib(3)</seealso>
	  module (in STDLIB).</p>
	  </item>

        <tag><c>md5</c></tag>
	  <item>
	  <p>Returns a binary representing the MD5 checksum of the module.
          If the module has native code loaded, this will be the MD5 of the
          native code, not the BEAM bytecode.</p>
	  </item>

        <tag><c>exports</c></tag>
	  <item>
	  <p>Returns a list of <c>{Name,Arity}</c> tuples with
	  all exported functions in the module.</p>
	  </item>

        <tag><c>functions</c></tag>
	  <item>
	  <p>Returns a list of <c>{Name,Arity}</c> tuples with
	  all functions in the module.</p>
	  </item>

        <tag><c>nifs</c></tag>
	  <item>
	  <p>Returns a list of <c>{Name,Arity}</c> tuples with
	  all NIF functions in the module.</p>
	  </item>

        <tag><c>native</c></tag>
	  <item>
	  <p>Return <c>true</c> if the module has native compiled code.
          Return <c>false</c> otherwise. In a system compiled without HiPE
          support, the result is always <c>false</c></p>
	  </item>
      </taglist>
    </section>
  </section>

</chapter>