Erlang -- Modules

User's Guide
PDF
Top

Erlang Reference Manual
User's Guide
Version 5.9.1

Expand All
Contract All

Chapters

- Introduction
  - Top of chapter
  - Purpose
  - Prerequisites
  - Document Conventions
  - Complete List of BIFs
  - Reserved Words
  - Character Set
- Data Types
  - Top of chapter
  - Terms
  - Number
  - Atom
  - Bit Strings and Binaries
  - Reference
  - Fun
  - Port Identifier
  - Pid
  - Tuple
  - List
  - String
  - Record
  - Boolean
  - Escape Sequences
  - Type Conversions
- Pattern Matching
  - Top of chapter
  - Pattern Matching
- Modules
  - Top of chapter
  - Module Syntax
  - Module Attributes
  - Comments
  - The module_info/0 and module_info/1 functions
- Functions
  - Top of chapter
  - Function Declaration Syntax
  - Function Evaluation
  - Tail recursion
  - Built-In Functions, BIFs
- Types and Function Specifications
  - Top of chapter
  - Introduction of Types
  - Types and their Syntax
  - Type declarations of user-defined types
  - Type information in record declarations
  - Specifications for functions
- Expressions
  - Top of chapter
  - Expression Evaluation
  - Terms
  - Variables
  - Patterns
  - Match
  - Function Calls
  - If
  - Case
  - Send
  - Receive
  - Term Comparisons
  - Arithmetic Expressions
  - Boolean Expressions
  - Short-Circuit Expressions
  - List Operations
  - Bit Syntax Expressions
  - Fun Expressions
  - Catch and Throw
  - Try
  - Parenthesized Expressions
  - Block Expressions
  - List Comprehensions
  - Bit String Comprehensions
  - Guard Sequences
  - Operator Precedence
- The Preprocessor
  - Top of chapter
  - File Inclusion
  - Defining and Using Macros
  - Predefined Macros
  - Macros Overloading
  - Flow Control in Macros
  - Stringifying Macro Arguments
- Records
  - Top of chapter
  - Defining Records
  - Creating Records
  - Accessing Record Fields
  - Updating Records
  - Records in Guards
  - Records in Patterns
  - Nested records
  - Internal Representation of Records
- Errors and Error Handling
  - Top of chapter
  - Terminology
  - Exceptions
  - Handling of Run-Time Errors in Erlang
  - Exit Reasons
- Processes
  - Top of chapter
  - Processes
  - Process Creation
  - Registered Processes
  - Process Termination
  - Message Sending
  - Links
  - Error Handling
  - Monitors
  - Process Dictionary
- Distributed Erlang
  - Top of chapter
  - Distributed Erlang System
  - Nodes
  - Node Connections
  - epmd
  - Hidden Nodes
  - C Nodes
  - Security
  - Distribution BIFs
  - Distribution Command Line Flags
  - Distribution Modules
- Compilation and Code Loading
  - Top of chapter
  - Compilation
  - Code Loading
  - Code Replacement
  - Running a function when a module is loaded
- Ports and Port Drivers
  - Top of chapter
  - Ports
  - Port Drivers
  - Port BIFs

# 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. As a convenience in user-defined attributes, the literal term Value the syntax Name/Arity (where Name is an atom and Arity a positive integer) will be 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 beam_lib(3).

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

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 MD5 checksum of the module.

-on_load(Function).

  Names a function that should be run automatically when a module a loaded. See code loading for more information.

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

#### Record Definitions

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

    -record(Record,Fields).

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

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

#### 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 will not be further updated.

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

### 4.4 The module_info/0 and module_info/1 functions

The compiler automatically inserts the two special, exported functions into each module: Module:module_info/0 and Module:module_info/1. These functions can be called to retrieve information about the module.

#### module_info/0

The module_info/0 function in each module returns a list of {Key,Value} tuples with information about the module. Currently, the list contain tuples with the following Keys: attributes, compile, exports, and imports. The order and number of tuples may change without prior notice.

Warning

The {imports,Value} tuple may be removed in a future release because Value is always an empty list. Do not write code that depends on it being present.

#### module_info/1

The call module_info(Key), where key is an atom, returns a single piece of information about the module.

The following values are allowed for Key:

attributes

  Return a list of {AttributeName,ValueList} tuples, where AttributeName is the name of an attribute, and ValueList is a list of values. Note: a given attribute may occur more than once in the list with different values if the attribute occurs more than once in the module.

  The list of attributes will be empty if the module has been stripped with beam_lib(3).

compile

  Return a list of tuples containing information about how the module was compiled. This list will be empty if the module has been stripped with beam_lib(3).

imports

  Always return an empty list. The imports key may not be supported in future release.

exports

  Return a list of {Name,Arity} tuples with all exported functions in the module.

functions

  Return a list of {Name,Arity} tuples with all functions in the module.