5.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. As a convenience in user-defined attributes, if the literal term Value has the syntax Name/Arity (where Name is an atom and Arity a positive integer), the term Name/Arity is translated to {Name,Arity}.

Any module attribute can be specified. The attributes are stored in the compiled code and can be retrieved by calling Module:module_info(attributes), or by using the module beam_lib(3) in STDLIB.

Several module attributes have predefined meanings. Some of them have arity two, but user-defined module attributes must have arity one.

Pre-Defined Module Attributes

Pre-defined module attributes is to be placed before any function declaration.

• -module(Module).
• Module declaration, defining the name of the module. The name Module, an atom, is to be same as the file name minus the extension .erl. Otherwise code loading does not work as intended.

This attribute is to be specified first and is the only mandatory attribute.

• -export(Functions).
• Exported functions. Specifies which of the functions, defined within the module, that are visible from 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. 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.

• -compile(Options).

• Compiler options. Options is a single option or a list of options. This attribute is added to the option list when compiling the module. See the compile(3) manual page in Compiler.

• -vsn(Vsn).

• Module version. Vsn is any literal term and can be retrieved using beam_lib:version/1, see the beam_lib(3) manual page in STDLIB.

If this attribute is not specified, the version defaults to the MD5 checksum of the module.

• -on_load(Function).
• This attribute names a function that is to be run automatically when a module is loaded. For more information, see Running a Function When a Module is Loaded.

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 following OTP standard behaviours:

• gen_server
• gen_statem
• gen_event
• supervisorThe spelling behavior is also accepted.

The callback functions of the module can be specified either directly by the exported function behaviour_info/1:

behaviour_info(callbacks) -> Callbacks.

or by a -callback attribute for each callback function:

-callback Name(Arguments) -> Result.

Here, Arguments is a list of zero or more arguments. The -callback attribute is to be preferred since the extra type information can be used by tools to produce documentation or find discrepancies.

Read more about behaviours and callback modules in OTP Design Principles.

Record Definitions

The same syntax as for module attributes is used for record definitions:

-record(Record,Fields).

Record definitions are allowed anywhere in a module, also among the function declarations.Read more in Records.

Preprocessor

The same syntax as for module attributes is used by the preprocessor, which supports file inclusion, macros,and conditional compilation:

-include("SomeFile.hrl").
-define(Macro,Replacement).

Read more in Preprocessor.

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 is generated by another tool. It also indicates the correspondence of source files to lines of the original user-written file, from which the source program is produced.

Types and function specifications

A similar syntax as for module attributes is used for specifying types and function specifications:

-type my_type() :: atom() | integer().
-spec my_function(integer()) -> integer().

Read more in Types and Function specifications.

The description is based on EEP8 - Types and function specifications, which is not to be further updated.