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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
<TITLE>Modules</TITLE>
<SCRIPT type="text/javascript" src="../../doc/erlresolvelinks.js">
</SCRIPT>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
ALINK="#FF0000">
<CENTER>
<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif"></A>
</CENTER>
<A NAME="4"><!-- Empty --></A>
<H2>4 Modules</H2>
<A NAME="4.1"><!-- Empty --></A>
<H3>4.1 Module Syntax</H3>
<P>Erlang code is divided into <STRONG>modules</STRONG>. A module consists
of a sequence of attributes and function declarations, each
terminated by period (.). Example:
<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>See the <A HREF="functions.html">Functions</A> chapter
for a description of function declarations.<A NAME="4.2"><!-- Empty --></A>
<H3>4.2 Module Attributes</H3>
<P>A <STRONG>module attribute</STRONG> defines a certain property of a
module. A module attribute consists of a tag and a value.
<PRE>
-Tag(Value).
</PRE>
<P><CODE>Tag</CODE> must be an atom, while <CODE>Value</CODE> must be a literal
term.
<P>Any module attribute can be specified. The attributes are stored
in the compiled code and can be retrieved by using, for example,
the function <CODE>beam_lib:chunks/2</CODE>.
<P>There are several module attributes with predefined meanings,
some of which have arity two, but user-defined module
attributes must have arity one.<A NAME="4.2.1"><!-- Empty --></A>
<H4>4.2.1 Pre-Defined Module Attributes</H4>
<P>Pre-defined module attributes should be placed before any
function declaration.
<P>
<DL>
<DT>
<CODE>-module(Module).</CODE>
</DT>
<DD>
Module declaration, defining the name of the module.
The name <CODE>Module</CODE>, an atom, should be the same as
the file name minus the extension <CODE>erl</CODE>. Otherwise
<A HREF="code.html#loading">code loading</A> will
not work as intended.<BR>
This attribute should be specified first and is the only
attribute which is mandatory.<BR>
</DD>
<DT>
<CODE>-export(Functions).</CODE>
</DT>
<DD>
Exported functions. Specifies which of the functions
defined within the module that are visible outside
the module.<BR>
<CODE>Functions</CODE> is a list
<CODE>[Name1/Arity1, ..., NameN/ArityN]</CODE>, where each
<CODE>NameI</CODE> is an atom and <CODE>ArityI</CODE> an integer.<BR>
</DD>
<DT>
<CODE>-import(Module,Functions).</CODE>
</DT>
<DD>
Imported functions. Imported functions can be called
the same way as local functions, that is without any module
prefix.<BR>
<CODE>Module</CODE>, an atom, specifies which module to import
functions from. <CODE>Functions</CODE> is a list similar as for
<CODE>export</CODE> above.<BR>
</DD>
<DT>
<CODE>-compile(Options).</CODE>
</DT>
<DD>
Compiler options. <CODE>Options</CODE>, which is a single option
or a list of options, will be added to the option list when
compiling the module. See <CODE>compile(3)</CODE>.<BR>
</DD>
<DT>
<CODE>-vsn(Vsn).</CODE>
</DT>
<DD>
Module version. <CODE>Vsn</CODE> is any literal term and can be
retrieved using <CODE>beam_lib:version/1</CODE>, see
<A HREF="javascript:erlhref('../../', 'stdlib', 'beam_lib.html#version/1');">beam_lib(3)</A>.
<BR>
If this attribute is not specified, the version defaults
to the checksum of the module.<BR>
</DD>
</DL>
<A NAME="4.2.2"><!-- Empty --></A>
<H4>4.2.2 Behaviour Module Attribute</H4>
<P>It is possible to specify that the module is the callback
module for a <STRONG>behaviour</STRONG>:
<PRE>
-behaviour(Behaviour).
</PRE>
<P>The atom <CODE>Behaviour</CODE> gives the name of the behaviour,
which can be a user defined behaviour or one of the OTP
standard behaviours <CODE>gen_server</CODE>, <CODE>gen_fsm</CODE>,
<CODE>gen_event</CODE> or <CODE>supervisor</CODE>.
<P>The spelling <CODE>behavior</CODE> is also accepted.
<P>Read more about behaviours and callback modules in OTP Design
Principles.<A NAME="4.2.3"><!-- Empty --></A>
<H4>4.2.3 Macro and Record Definitions</H4>
<P>The same syntax as for module attributes is used for
macro and record definitions:
<PRE>
-define(Macro,Replacement).
-record(Record,Fields).
</PRE>
<P>Macro and record definitions are allowed anywhere in a module,
also among the function declarations.
<P>Read more in <A HREF="macros.html">Macros</A> and
<A HREF="records.html">Records</A>.<A NAME="4.2.4"><!-- Empty --></A>
<H4>4.2.4 File Inclusion</H4>
<P>The same syntax as for module attributes is used for
file inclusion:
<PRE>
-include(File).
-include_lib(File).
</PRE>
<P><CODE>File</CODE>, a string, should 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 <CODE>.hrl</CODE> be used
for include files.
<P><CODE>File</CODE> may start with a path component <CODE>$VAR</CODE>, for
some string <CODE>VAR</CODE>. If that is the case, the value of
the environment variable <CODE>VAR</CODE> as returned by
<CODE>os:getenv(VAR)</CODE> is substituted for <CODE>$VAR</CODE>. If
<CODE>os:getenv(VAR)</CODE> returns <CODE>false</CODE>, <CODE>$VAR</CODE> is left
as is.
<P>If the filename <CODE>File</CODE> 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 <CODE>include</CODE> option, in that order.
See <CODE>erlc(1)</CODE> and <CODE>compile(3)</CODE> for details.
<P>Examples:
<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><CODE>include_lib</CODE> is similar to <CODE>include</CODE>, but should not
point out an absolute file. Instead, the first path component
(possibly after variable substitution) is assumed to be
the name of an application. Example:
<PRE>
-include_lib("kernel/include/file.hrl").
</PRE>
<P>The code server uses <CODE>code:lib_dir(kernel)</CODE> to find
the directory of the current (latest) version of Kernel, and
then the subdirectory <CODE>include</CODE> is searched for the file
<CODE>file.hrl</CODE>.<A NAME="4.2.5"><!-- Empty --></A>
<H4>4.2.5 Setting File and Line</H4>
<P>The same syntax as for module attributes is used for
changing the pre-defined macros <CODE>?FILE</CODE> and <CODE>?LINE</CODE>:
<PRE>
-file(File, Line).
</PRE>
<P>This attribute is used by tools such as Yecc to inform the
compiler that the source program was generated by another tool
and indicates the correspondence of source files to lines of
the original user-written file from which the source program
was produced.<A NAME="4.3"><!-- Empty --></A>
<H3>4.3 Comments</H3>
<P>Comments may be placed anywhere in a module except within strings
and quoted atoms. The comment begins with the character "%",
continues up to, but does not include the next end-of-line, and
has no effect. Note that the terminating end-of-line has
the effect of white space.<CENTER>
<HR>
<SMALL>
Copyright © 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>
|
