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 declaration
See the Functions chapter for a description of function declarations.
A module attribute defines a certain property of a module. A module attribute consists of a tag and a value.
-Tag(Value).
Tag
must be an atom, while Value
must be a literal
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 are several module attributes with predefined meanings, some of which have arity two, but user-defined module attributes must have arity one.
Pre-defined module attributes should be placed before any function declaration.
-module(Module).
Module
, an atom, should be the same as
the file name minus the extension erl
. Otherwise
code loading will
not work as intended.-export(Functions).
Functions
is a list
[Name1/Arity1, ..., NameN/ArityN]
, where each
NameI
is an atom and ArityI
an integer.-import(Module,Functions).
Module
, an atom, specifies which module to import
functions from. Functions
is a list similar as for
export
above.-compile(Options).
Options
, which is a single option
or a list of options, will be added to the option list when
compiling the module. See compile(3)
.-vsn(Vsn).
Vsn
is any literal term and can be
retrieved using beam_lib:version/1
, see
beam_lib(3).
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 behaviours gen_server
, gen_fsm
,
gen_event
or supervisor
.
The spelling behavior
is also accepted.
Read more about behaviours and callback modules in OTP Design Principles.
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.
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 string VAR
. If that is the case, the value of
the environment variable VAR
as returned by
os:getenv(VAR)
is substituted for $VAR
. If
os:getenv(VAR)
returns false
, $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
the include
option, in that order.
See erlc(1)
and compile(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 to include
, 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 subdirectory include
is searched for the file
file.hrl
.
The same syntax as for module attributes is used for
changing the pre-defined macros ?FILE
and ?LINE
:
-file(File, Line).
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.
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.