← Back to branch summary

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

« back to all changes in this revision

Viewing changes to system/doc/reference_manual/modules.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/modules.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>Modules</title>
 
25
    <prepared></prepared>
 
26
    <docno></docno>
 
27
    <date></date>
 
28
    <rev></rev>
 
29
    <file>modules.xml</file>
 
30
  </header>
 
31
 
 
32
  <section>
 
33
    <title>Module Syntax</title>
 
34
    <p>Erlang code is divided into <em>modules</em>. A module consists
 
35
      of a sequence of attributes and function declarations, each
 
36
      terminated by period (.). Example:</p>
 
37
    <pre>
 
38
-module(m).          % module attribute
 
39
-export([fact/1]).   % module attribute
 
40
 
 
41
fact(N) when N>0 ->  % beginning of function declaration
 
42
    N * fact(N-1);   %  |
 
43
fact(0) ->           %  |
 
44
    1.               % end of function declaration</pre>
 
45
    <p>See the <seealso marker="functions">Functions</seealso> chapter
 
46
      for a description of function declarations.</p>
 
47
  </section>
 
48
 
 
49
  <section>
 
50
    <title>Module Attributes</title>
 
51
    <p>A <em>module attribute</em> defines a certain property of a
 
52
      module. A module attribute consists of a tag and a value.</p>
 
53
    <pre>
 
54
-Tag(Value).</pre>
 
55
    <p><c>Tag</c> must be an atom, while <c>Value</c> must be a literal
 
56
      term. As a convenience in user-defined attributes, the literal term
 
57
      <c>Value</c> the syntax <c>Name/Arity</c>
 
58
      (where <c>Name</c> is an atom and <c>Arity</c> a positive integer)
 
59
      will be translated to <c>{Name,Arity}</c>.</p>
 
60
 
 
61
    <p>Any module attribute can be specified. The attributes are stored
 
62
      in the compiled code and can be retrieved by calling
 
63
      <c>Module:module_info(attributes)</c> or by using
 
64
      <seealso marker="stdlib:beam_lib#chunks/2">beam_lib(3)</seealso>.</p>
 
65
 
 
66
    <p>There are several module attributes with predefined meanings,
 
67
      some of which have arity two, but user-defined module
 
68
      attributes must have arity one.</p>
 
69
 
 
70
    <section>
 
71
      <title>Pre-Defined Module Attributes</title>
 
72
      <p>Pre-defined module attributes should be placed before any
 
73
        function declaration.</p>
 
74
      <taglist>
 
75
        <tag><c>-module(Module).</c></tag>
 
76
        <item>
 
77
          <p>Module declaration, defining the name of the module.
 
78
            The name <c>Module</c>, an atom, should be the same as
 
79
            the file name minus the extension <c>erl</c>. Otherwise
 
80
            <seealso marker="code_loading#loading">code loading</seealso> will
 
81
            not work as intended.</p>
 
82
          <p>This attribute should be specified first and is the only
 
83
            attribute which is mandatory.</p>
 
84
        </item>
 
85
        <tag><c>-export(Functions).</c></tag>
 
86
        <item>
 
87
          <p>Exported functions. Specifies which of the functions
 
88
            defined within the module that are visible outside
 
89
            the module.</p>
 
90
          <p><c>Functions</c> is a list
 
91
            <c>[Name1/Arity1, ..., NameN/ArityN]</c>, where each
 
92
            <c>NameI</c> is an atom and <c>ArityI</c> an integer.</p>
 
93
        </item>
 
94
        <tag><c>-import(Module,Functions).</c></tag>
 
95
        <item>
 
96
          <p>Imported functions. Imported functions can be called
 
97
            the same way as local functions, that is without any module
 
98
            prefix.</p>
 
99
          <p><c>Module</c>, an atom, specifies which module to import
 
100
            functions from. <c>Functions</c> is a list similar as for
 
101
            <c>export</c> above.</p>
 
102
        </item>
 
103
        <tag><c>-compile(Options).</c></tag>
 
104
        <item>
 
105
          <p>Compiler options. <c>Options</c>, which is a single option
 
106
            or a list of options, will be added to the option list when
 
107
            compiling the module. See <c>compile(3)</c>.</p>
 
108
        </item>
 
109
        <tag><c>-vsn(Vsn).</c></tag>
 
110
        <item>
 
111
          <p>Module version. <c>Vsn</c> is any literal term and can be
 
112
            retrieved using <c>beam_lib:version/1</c>, see
 
113
            <seealso marker="stdlib:beam_lib#version/1">beam_lib(3)</seealso>.</p>
 
114
          <p>If this attribute is not specified, the version defaults
 
115
            to the MD5 checksum of the module.</p>
 
116
        </item>
 
117
      </taglist>
 
118
    </section>
 
119
 
 
120
    <section>
 
121
      <title>Behaviour Module Attribute</title>
 
122
      <p>It is possible to specify that the module is the callback
 
123
        module for a <em>behaviour</em>:</p>
 
124
      <pre>
 
125
-behaviour(Behaviour).</pre>
 
126
      <p>The atom <c>Behaviour</c> gives the name of the behaviour,
 
127
        which can be a user defined behaviour or one of the OTP
 
128
        standard behaviours <c>gen_server</c>, <c>gen_fsm</c>,
 
129
        <c>gen_event</c> or <c>supervisor</c>.</p>
 
130
      <p>The spelling <c>behavior</c> is also accepted.</p>
 
131
      <p>Read more about behaviours and callback modules in OTP Design
 
132
        Principles.</p>
 
133
    </section>
 
134
 
 
135
    <section>
 
136
      <title>Record Definitions</title>
 
137
      <p>The same syntax as for module attributes is used by
 
138
        for record definitions:</p>
 
139
      <pre>
 
140
-record(Record,Fields).</pre>
 
141
      <p>Record definitions are allowed anywhere in a module,
 
142
        also among the function declarations.
 
143
        Read more in <seealso marker="records">Records</seealso>.</p>
 
144
    </section>
 
145
 
 
146
    <section>
 
147
      <title>The Preprocessor</title>
 
148
      <p>The same syntax as for module attributes is used by
 
149
        the preprocessor, which supports file inclusion, macros,
 
150
        and conditional compilation:</p>
 
151
      <pre>
 
152
-include("SomeFile.hrl").
 
153
-define(Macro,Replacement).</pre>
 
154
 
 
155
      <p>Read more in <seealso marker="macros">The Preprocessor</seealso>.</p>
 
156
    </section>
 
157
 
 
158
    <section>
 
159
      <title>Setting File and Line</title>
 
160
      <p>The same syntax as for module attributes is used for
 
161
        changing the pre-defined macros <c>?FILE</c> and <c>?LINE</c>:</p>
 
162
      <pre>
 
163
-file(File, Line).</pre>
 
164
      <p>This attribute is used by tools such as Yecc to inform the
 
165
        compiler that the source program was generated by another tool
 
166
        and indicates the correspondence of source files to lines of
 
167
        the original user-written file from which the source program
 
168
        was produced.</p>
 
169
    </section>
 
170
 
 
171
    <section>
 
172
        <title>Types and function specifications</title>
 
173
        <p>A similar syntax as for module attributes is used for 
 
174
        specifying types and function specifications.
 
175
        </p>
 
176
        <pre>
 
177
-type my_type() :: atom() | integer().
 
178
-spec my_function(integer()) -> integer().
 
179
        </pre>
 
180
        <p>Read more in <seealso marker="typespec">Types and Function specifications</seealso>.
 
181
        </p>
 
182
        <p>
 
183
          The desciption is based on
 
184
            <url href="http://www.erlang.org/eeps/eep-0008.html">EEP8 -
 
185
            Types and function specifications</url>
 
186
            which will not be further updated.
 
187
        </p>
 
188
    </section>
 
189
  </section>
 
190
 
 
191
  <section>
 
192
    <title>Comments</title>
 
193
    <p>Comments may be placed anywhere in a module except within strings
 
194
      and quoted atoms. The comment begins with the character "%",
 
195
      continues up to, but does not include the next end-of-line, and
 
196
      has no effect. Note that the terminating end-of-line has
 
197
      the effect of white space.</p>
 
198
  </section>
 
199
 
 
200
  <section>
 
201
    <title>The module_info/0 and module_info/1 functions</title>
 
202
 
 
203
    <p>The compiler automatically inserts the two special, exported
 
204
      functions into each module: <c>Module:module_info/0</c> and
 
205
      <c>Module:module_info/1</c>. These functions can be called to
 
206
      retrieve information about the module.</p>
 
207
 
 
208
    <section>
 
209
      <title>module_info/0</title>
 
210
      <p>The <c>module_info/0</c> function in each module returns
 
211
      a list of <c>{Key,Value}</c> tuples with information about
 
212
      the module. Currently, the list contain tuples with the following
 
213
      <c>Key</c>s: <c>attributes</c>, <c>compile</c>, 
 
214
      <c>exports</c>, and <c>imports</c>. The order and number of tuples
 
215
      may change without prior notice.</p>
 
216
 
 
217
      <warning><p>The <c>{imports,Value}</c> tuple may be removed in a future
 
218
      release because <c>Value</c> is always an empty list.
 
219
      Do not write code that depends on it being present.</p></warning>
 
220
    </section>
 
221
 
 
222
    <section>
 
223
      <title>module_info/1</title>
 
224
      <p>The call <c>module_info(Key)</c>, where key is an atom,
 
225
       returns a single piece of information about the module.</p>
 
226
 
 
227
      <p>The following values are allowed for <c>Key</c>:</p>
 
228
 
 
229
      <taglist>
 
230
        <tag><c>attributes</c></tag>
 
231
          <item>
 
232
          <p>Return a list of <c>{AttributeName,ValueList}</c> tuples,
 
233
          where <c>AttributeName</c> is the name of an attribute,
 
234
          and <c>ValueList</c> is a list of values. Note: a given
 
235
          attribute may occur more than once in the list with different
 
236
          values if the attribute occurs more than once in the module.</p>
 
237
 
 
238
          <p>The list of attributes will be empty if
 
239
          the module has been stripped with
 
240
          <seealso marker="stdlib:beam_lib#strip/1">beam_lib(3)</seealso>.</p>
 
241
          </item>
 
242
 
 
243
        <tag><c>compile</c></tag>
 
244
          <item>
 
245
          <p>Return a list of tuples containing information about
 
246
          how the module was compiled. This list will be empty if
 
247
          the module has been stripped with
 
248
          <seealso marker="stdlib:beam_lib#strip/1">beam_lib(3)</seealso>.</p>
 
249
          </item>
 
250
 
 
251
        <tag><c>imports</c></tag>
 
252
          <item>
 
253
          <p>Always return an empty list. The <c>imports</c> key may not
 
254
          be supported in future release.</p>
 
255
          </item>
 
256
 
 
257
        <tag><c>exports</c></tag>
 
258
          <item>
 
259
          <p>Return a list of <c>{Name,Arity}</c> tuples with
 
260
          all exported functions in the module.</p>
 
261
          </item>
 
262
 
 
263
        <tag><c>functions</c></tag>
 
264
          <item>
 
265
          <p>Return a list of <c>{Name,Arity}</c> tuples with
 
266
          all functions in the module.</p>
 
267
          </item>
 
268
      </taglist>
 
269
    </section>
 
270
  </section>
 
271
 
 
272
</chapter>
 
273