4 Modules
4.1 Module Syntax
Erlang code is divided into modules. A module consists of a sequence of attributes and function declarations, each terminated by period (.). Example:
-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 declarationSee the Functions chapter for a description of function declarations.
4.2 Module Attributes
A module attribute defines a certain property of a module. A module attribute consists of a tag and a value.
-Tag(Term).Any module attribute can be specified. The attributes are stored in the compiled code and can be retrieved by using, for example, the function
beam_lib:chunks/2
.There exists a number of module attributes with predefined meanings.
4.2.1 Pre-Defined Module Attributes
Pre-defined module attributes should be placed before any function declaration.
-module(Module).
- Module declaration, defining the name of the module. The name
Module
, an atom, should be the same as the file name minus the extensionerl
. Otherwise code loading will not work as intended.
This attribute should be specified first and is the only attribute which is mandatory.
-export(Functions).
- Exported functions. Specifies which of the functions defined within the module that are visible outside the module.
Functions
is a list[Name1/Arity1, ..., NameN/ArityN]
, where eachNameI
is an atom andArityI
an integer.
-import(Module,Functions).
- Imported functions. Imported functions can be called the same way as local functions, that is without any module prefix.
Module
, an atom, specifies which module to import functions from.Functions
is a list similar as forexport
above.
-compile(Options).
- Compiler options.
Options
, which is a single option or a list of options, will be added to the option list when compiling the module. Seecompile(3)
.
4.2.2 Behaviour Module Attribute
It is possible to specify that the module is the callback module for a behaviour:
-behaviour(Behaviour).The atom
Behaviour
gives the name of the behaviour, which can be a user defined behaviour or one of the OTP standard behavioursgen_server
,gen_fsm
,gen_event
orsupervisor
.The spelling
behavior
is also accepted.Read more about behaviours and callback modules in OTP Design Principles.
4.2.3 Macro and Record Definitions
The same syntax as for module attributes is used for macro and record definitions:
-define(Macro,Replacement). -record(Record,Fields).Macro and record definitions are allowed anywhere in a module, also among the function declarations.
Read more in Macros and Records.
4.2.4 File Inclusion
The same syntax as for module attributes is used for file inclusion:
-include(File). -include_lib(File).
File
, a string, should point out a file. The contents of this file are included as-is, at the position of the directive.
Include files are typically used for record- and macro definitions that are shared by several modules. It is recommended that the file name extension
.hrl
be used for include files.
File
may start with a path component$VAR
, for some stringVAR
. If that is the case, the value of the environment variableVAR
as returned byos:getenv(VAR)
is substituted for$VAR
. Ifos:getenv(VAR)
returnsfalse
,$VAR
is left as is.If the filename
File
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 theinclude
option, in that order. Seeerlc(1)
andcompile(3)
for details.Examples:
-include("my_records.hrl"). -include("incdir/my_records.hrl"). -include("/home/user/proj/my_records.hrl"). -include("$PROJ_ROOT/my_records.hrl").
include_lib
is similar toinclude
, 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:-include_lib("kernel/include/file.hrl").The code server uses
code:lib_dir(kernel)
to find the directory of the current (latest) version of Kernel, and then the subdirectoryinclude
is searched for the filefile.hrl
.4.3 Comments
Comments are allowed anywhere within a module. Comments start with the character
%
and stop at end of line.