## 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 declaration

See 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(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.

#### 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 extension erl. 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 each NameI is an atom and ArityI 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 for export 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. See compile(3).
-vsn(Vsn).
  Module version. Vsn is any literal term and can be retrieved using beam_lib:version/1, see beam_lib(3).
  If this attribute is not specified, the version defaults to the checksum of the module.

#### 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 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.

#### 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 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.

#### 4.2.5 Setting File and Line

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.

### 4.3 Comments

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.

Copyright © 1991-2008 Ericsson AB