<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html xmlns:fn="http://www.w3.org/2005/02/xpath-functions"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" href="../otp_doc.css" type="text/css"> <title>Erlang -- Modules</title> </head> <body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container"> <script id="js" type="text/javascript" language="JavaScript" src="../js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript"> <!-- function getWinHeight() { var myHeight = 0; if( typeof( window.innerHeight ) == 'number' ) { //Non-IE myHeight = window.innerHeight; } else if( document.documentElement && ( document.documentElement.clientWidth || document.documentElement.clientHeight ) ) { //IE 6+ in 'standards compliant mode' myHeight = document.documentElement.clientHeight; } else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) { //IE 4 compatible myHeight = document.body.clientHeight; } return myHeight; } function setscrollpos() { var objf=document.getElementById('loadscrollpos'); document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2; } function addEvent(obj, evType, fn){ if (obj.addEventListener){ obj.addEventListener(evType, fn, true); return true; } else if (obj.attachEvent){ var r = obj.attachEvent("on"+evType, fn); return r; } else { return false; } } addEvent(window, 'load', setscrollpos); //--></script><div id="leftnav"><div class="innertube"> <img alt="Erlang logo" src="../erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="../pdf/otp-system-documentation-7.3.1.pdf">PDF</a><br><a href="../index.html">Top</a></small><p><strong>Erlang Reference Manual</strong><br><strong>User's Guide</strong><br><small>Version 7.3.1</small></p> <br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p> <ul class="flipMenu" imagepath="../js/flipmenu"> <li id="no" title="Introduction" expanded="false">Introduction<ul> <li><a href="introduction.html"> Top of chapter </a></li> <li title="Purpose"><a href="introduction.html#idp281318652">Purpose</a></li> <li title="Prerequisites"><a href="introduction.html#idp280946564">Prerequisites</a></li> <li title="Document Conventions"><a href="introduction.html#idp281177364">Document Conventions</a></li> <li title="Complete List of BIFs"><a href="introduction.html#idp281241292">Complete List of BIFs</a></li> <li title="Reserved Words"><a href="introduction.html#idp281324940">Reserved Words</a></li> </ul> </li> <li id="no" title="Character Set and Source File Encoding" expanded="false">Character Set and Source File Encoding<ul> <li><a href="character_set.html"> Top of chapter </a></li> <li title="Character Set"><a href="character_set.html#idp281773964">Character Set</a></li> <li title="Source File Encoding"><a href="character_set.html#idp281660124">Source File Encoding</a></li> </ul> </li> <li id="no" title="Data Types" expanded="false">Data Types<ul> <li><a href="data_types.html"> Top of chapter </a></li> <li title="Terms"><a href="data_types.html#idp281294612">Terms</a></li> <li title="Number"><a href="data_types.html#idp281244644">Number</a></li> <li title="Atom"><a href="data_types.html#idp281498348">Atom</a></li> <li title="Bit Strings and Binaries"><a href="data_types.html#idp281496484">Bit Strings and Binaries</a></li> <li title="Reference"><a href="data_types.html#idp282146212">Reference</a></li> <li title="Fun"><a href="data_types.html#idp282147188">Fun</a></li> <li title="Port Identifier"><a href="data_types.html#idp282147604">Port Identifier</a></li> <li title="Pid"><a href="data_types.html#idp281724300">Pid</a></li> <li title="Tuple"><a href="data_types.html#idp281654700">Tuple</a></li> <li title="Map"><a href="data_types.html#idp281572268">Map</a></li> <li title="List"><a href="data_types.html#idp281677052">List</a></li> <li title="String"><a href="data_types.html#idp281504868">String</a></li> <li title="Record"><a href="data_types.html#idp281507652">Record</a></li> <li title="Boolean"><a href="data_types.html#idp280885396">Boolean</a></li> <li title="Escape Sequences"><a href="data_types.html#idp280887524">Escape Sequences</a></li> <li title="Type Conversions"><a href="data_types.html#idp282154396">Type Conversions</a></li> </ul> </li> <li id="no" title="Pattern Matching" expanded="false">Pattern Matching<ul> <li><a href="patterns.html"> Top of chapter </a></li> <li title="Pattern Matching"><a href="patterns.html#idp282166452">Pattern Matching</a></li> </ul> </li> <li id="loadscrollpos" title="Modules" expanded="true">Modules<ul> <li><a href="modules.html"> Top of chapter </a></li> <li title="Module Syntax"><a href="modules.html#idp282174676">Module Syntax</a></li> <li title="Module Attributes"><a href="modules.html#idp282177108">Module Attributes</a></li> <li title="Comments"><a href="modules.html#idp282208324">Comments</a></li> <li title="module_info/0 and module_info/1 functions"><a href="modules.html#idp282209284">module_info/0 and module_info/1 functions</a></li> </ul> </li> <li id="no" title="Functions" expanded="false">Functions<ul> <li><a href="functions.html"> Top of chapter </a></li> <li title="Function Declaration Syntax"><a href="functions.html#idp282228612">Function Declaration Syntax</a></li> <li title="Function Evaluation"><a href="functions.html#idp282236196">Function Evaluation</a></li> <li title="Tail recursion"><a href="functions.html#idp282246084">Tail recursion</a></li> <li title="Built-In Functions (BIFs)"><a href="functions.html#idp282248420">Built-In Functions (BIFs)</a></li> </ul> </li> <li id="no" title="Types and Function Specifications" expanded="false">Types and Function Specifications<ul> <li><a href="typespec.html"> Top of chapter </a></li> <li title="The Erlang Type Language"><a href="typespec.html#idp282256436">The Erlang Type Language</a></li> <li title="Types and their Syntax"><a href="typespec.html#idp282260428">Types and their Syntax</a></li> <li title="Type Declarations of User-Defined Types"><a href="typespec.html#idp282316436">Type Declarations of User-Defined Types</a></li> <li title="Type Information in Record Declarations"><a href="typespec.html#idp282325372">Type Information in Record Declarations</a></li> <li title="Specifications for Functions"><a href="typespec.html#idp282330908">Specifications for Functions</a></li> </ul> </li> <li id="no" title="Expressions" expanded="false">Expressions<ul> <li><a href="expressions.html"> Top of chapter </a></li> <li title="Expression Evaluation"><a href="expressions.html#idp282349612">Expression Evaluation</a></li> <li title="Terms"><a href="expressions.html#idp282352444">Terms</a></li> <li title="Variables"><a href="expressions.html#idp282353260">Variables</a></li> <li title="Patterns"><a href="expressions.html#idp282363228">Patterns</a></li> <li title="Match"><a href="expressions.html#idp282372668">Match</a></li> <li title="Function Calls"><a href="expressions.html#idp282376628">Function Calls</a></li> <li title="If"><a href="expressions.html#idp282391380">If</a></li> <li title="Case"><a href="expressions.html#idp282395684">Case</a></li> <li title="Send"><a href="expressions.html#idp282399988">Send</a></li> <li title="Receive"><a href="expressions.html#idp282405284">Receive</a></li> <li title="Term Comparisons"><a href="expressions.html#idp282416884">Term Comparisons</a></li> <li title="Arithmetic Expressions"><a href="expressions.html#idp282434564">Arithmetic Expressions</a></li> <li title="Boolean Expressions"><a href="expressions.html#idp282465284">Boolean Expressions</a></li> <li title="Short-Circuit Expressions"><a href="expressions.html#idp282474740">Short-Circuit Expressions</a></li> <li title="List Operations"><a href="expressions.html#idp282483892">List Operations</a></li> <li title="Map Expressions"><a href="expressions.html#idp282488356">Map Expressions</a></li> <li title="Bit Syntax Expressions"><a href="expressions.html#idp282528004">Bit Syntax Expressions</a></li> <li title="Fun Expressions"><a href="expressions.html#idp282565244">Fun Expressions</a></li> <li title="Catch and Throw"><a href="expressions.html#idp282575980">Catch and Throw</a></li> <li title="Try"><a href="expressions.html#idp282586068">Try</a></li> <li title="Parenthesized Expressions"><a href="expressions.html#idp282610596">Parenthesized Expressions</a></li> <li title="Block Expressions"><a href="expressions.html#idp282612652">Block Expressions</a></li> <li title="List Comprehensions"><a href="expressions.html#idp282614244">List Comprehensions</a></li> <li title="Bit String Comprehensions"><a href="expressions.html#idp282623404">Bit String Comprehensions</a></li> <li title="Guard Sequences"><a href="expressions.html#idp282632004">Guard Sequences</a></li> <li title="Operator Precedence"><a href="expressions.html#idp282666836">Operator Precedence</a></li> </ul> </li> <li id="no" title="Preprocessor" expanded="false">Preprocessor<ul> <li><a href="macros.html"> Top of chapter </a></li> <li title="File Inclusion"><a href="macros.html#idp282687052">File Inclusion</a></li> <li title="Defining and Using Macros"><a href="macros.html#idp282697524">Defining and Using Macros</a></li> <li title="Predefined Macros"><a href="macros.html#idp282706180">Predefined Macros</a></li> <li title="Macros Overloading"><a href="macros.html#idp282710348">Macros Overloading</a></li> <li title="Flow Control in Macros"><a href="macros.html#idp282714860">Flow Control in Macros</a></li> <li title="Stringifying Macro Arguments"><a href="macros.html#idp282723580">Stringifying Macro Arguments</a></li> </ul> </li> <li id="no" title="Records" expanded="false">Records<ul> <li><a href="records.html"> Top of chapter </a></li> <li title="Defining Records"><a href="records.html#idp282732108">Defining Records</a></li> <li title="Creating Records"><a href="records.html#idp282734276">Creating Records</a></li> <li title="Accessing Record Fields"><a href="records.html#idp282738284">Accessing Record Fields</a></li> <li title="Updating Records"><a href="records.html#idp282740892">Updating Records</a></li> <li title="Records in Guards"><a href="records.html#idp282742996">Records in Guards</a></li> <li title="Records in Patterns"><a href="records.html#idp282745748">Records in Patterns</a></li> <li title="Nested Records"><a href="records.html#idp282747492">Nested Records</a></li> <li title="Internal Representation of Records"><a href="records.html#idp282749884">Internal Representation of Records</a></li> </ul> </li> <li id="no" title="Errors and Error Handling" expanded="false">Errors and Error Handling<ul> <li><a href="errors.html"> Top of chapter </a></li> <li title="Terminology"><a href="errors.html#idp282757940">Terminology</a></li> <li title="Exceptions"><a href="errors.html#idp282766396">Exceptions</a></li> <li title="Handling of Run-time Errors in Erlang"><a href="errors.html#idp282777580">Handling of Run-time Errors in Erlang</a></li> <li title="Exit Reasons"><a href="errors.html#idp282781892">Exit Reasons</a></li> </ul> </li> <li id="no" title="Processes" expanded="false">Processes<ul> <li><a href="processes.html"> Top of chapter </a></li> <li title="Processes"><a href="processes.html#idp282811812">Processes</a></li> <li title="Process Creation"><a href="processes.html#idp282812692">Process Creation</a></li> <li title="Registered Processes"><a href="processes.html#idp282815876">Registered Processes</a></li> <li title="Process Termination"><a href="processes.html#idp282824132">Process Termination</a></li> <li title="Message Sending"><a href="processes.html#idp282830212">Message Sending</a></li> <li title="Links"><a href="processes.html#idp282832132">Links</a></li> <li title="Error Handling"><a href="processes.html#idp282836300">Error Handling</a></li> <li title="Monitors"><a href="processes.html#idp282844228">Monitors</a></li> <li title="Process Dictionary"><a href="processes.html#idp282850076">Process Dictionary</a></li> </ul> </li> <li id="no" title="Distributed Erlang" expanded="false">Distributed Erlang<ul> <li><a href="distributed.html"> Top of chapter </a></li> <li title="Distributed Erlang System"><a href="distributed.html#idp282854516">Distributed Erlang System</a></li> <li title="Nodes"><a href="distributed.html#idp282856812">Nodes</a></li> <li title="Node Connections"><a href="distributed.html#idp282861612">Node Connections</a></li> <li title="epmd"><a href="distributed.html#idp282865100">epmd</a></li> <li title="Hidden Nodes"><a href="distributed.html#idp282866572">Hidden Nodes</a></li> <li title="C Nodes"><a href="distributed.html#idp282869732">C Nodes</a></li> <li title="Security"><a href="distributed.html#idp282871876">Security</a></li> <li title="Distribution BIFs"><a href="distributed.html#idp282879572">Distribution BIFs</a></li> <li title="Distribution Command-Line Flags"><a href="distributed.html#idp282899532">Distribution Command-Line Flags</a></li> <li title="Distribution Modules"><a href="distributed.html#idp282909500">Distribution Modules</a></li> </ul> </li> <li id="no" title="Compilation and Code Loading" expanded="false">Compilation and Code Loading<ul> <li><a href="code_loading.html"> Top of chapter </a></li> <li title="Compilation"><a href="code_loading.html#idp282925036">Compilation</a></li> <li title="Code Loading"><a href="code_loading.html#idp282932764">Code Loading</a></li> <li title="Code Replacement"><a href="code_loading.html#idp282936164">Code Replacement</a></li> <li title="Running a Function When a Module is Loaded"><a href="code_loading.html#idp282941628">Running a Function When a Module is Loaded</a></li> </ul> </li> <li id="no" title="Ports and Port Drivers" expanded="false">Ports and Port Drivers<ul> <li><a href="ports.html"> Top of chapter </a></li> <li title="Ports"><a href="ports.html#idp282955284">Ports</a></li> <li title="Port Drivers"><a href="ports.html#idp282957788">Port Drivers</a></li> <li title="Port BIFs"><a href="ports.html#idp282960932">Port BIFs</a></li> </ul> </li> </ul> </div></div> <div id="content"> <div class="innertube"> <h1>5 Modules</h1> <h3><a name="idp282174676">5.1 Module Syntax</a></h3> <p>Erlang code is divided into <strong>modules</strong>. A module consists of a sequence of attributes and function declarations, each terminated by period (.).</p> <p><strong>Example:</strong></p> <div class="example"><pre> -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</pre></div> <p>For a description of function declarations, see <span class="bold_code"><a href="functions.html">Function Declaration Syntax</a></span>.</p> <h3><a name="idp282177108">5.2 Module Attributes</a></h3> <p>A <strong>module attribute</strong> defines a certain property of a module.</p> <p>A module attribute consists of a tag and a value:</p> <div class="example"><pre> -Tag(Value).</pre></div> <p><span class="code">Tag</span> must be an atom, while <span class="code">Value</span> must be a literal term. As a convenience in user-defined attributes, if the literal term <span class="code">Value</span> has the syntax <span class="code">Name/Arity</span> (where <span class="code">Name</span> is an atom and <span class="code">Arity</span> a positive integer), the term <span class="code">Name/Arity</span> is translated to <span class="code">{Name,Arity}</span>.</p> <p>Any module attribute can be specified. The attributes are stored in the compiled code and can be retrieved by calling <span class="code">Module:module_info(attributes)</span>, or by using the module <span class="bold_code"><a href="javascript:erlhref('../../','stdlib','beam_lib.html#chunks-2');">beam_lib(3)</a></span> in STDLIB.</p> <p>Several module attributes have predefined meanings. Some of them have arity two, but user-defined module attributes must have arity one.</p> <h4>Pre-Defined Module Attributes</h4> <p>Pre-defined module attributes is to be placed before any function declaration.</p> <dl> <dt><strong><span class="code">-module(Module).</span></strong></dt> <dd> <p>Module declaration, defining the name of the module. The name <span class="code">Module</span>, an atom, is to be same as the file name minus the extension <span class="code">.erl</span>. Otherwise <span class="bold_code"><a href="code_loading.html#loading">code loading</a></span> does not work as intended.</p> <p>This attribute is to be specified first and is the only mandatory attribute.</p> </dd> <dt><strong><span class="code">-export(Functions).</span></strong></dt> <dd> <p>Exported functions. Specifies which of the functions, defined within the module, that are visible from outside the module.</p> <p><span class="code">Functions</span> is a list <span class="code">[Name1/Arity1, ..., NameN/ArityN]</span>, where each <span class="code">NameI</span> is an atom and <span class="code">ArityI</span> an integer.</p> </dd> <dt><strong><span class="code">-import(Module,Functions).</span></strong></dt> <dd> <p>Imported functions. Can be called the same way as local functions, that is, without any module prefix.</p> <p><span class="code">Module</span>, an atom, specifies which module to import functions from. <span class="code">Functions</span> is a list similar as for <span class="code">export</span>.</p> </dd> <dt><strong><span class="code">-compile(Options).</span></strong></dt> <dd> <p>Compiler options. <span class="code">Options</span> is a single option or a list of options. This attribute is added to the option list when compiling the module. See the <span class="bold_code"><a href="javascript:erlhref('../../','compiler','compile.html');"> compile(3)</a></span> manual page in Compiler.</p> </dd> <dt><strong><span class="code">-vsn(Vsn).</span></strong></dt> <dd> <p>Module version. <span class="code">Vsn</span> is any literal term and can be retrieved using <span class="code">beam_lib:version/1</span>, see the <span class="bold_code"><a href="javascript:erlhref('../../','stdlib','beam_lib.html#version-1');">beam_lib(3)</a></span> manual page in STDLIB.</p> <p>If this attribute is not specified, the version defaults to the MD5 checksum of the module.</p> </dd> <dt><strong><span class="code">-on_load(Function).</span></strong></dt> <dd> <p>This attribute names a function that is to be run automatically when a module is loaded. For more information, see <span class="bold_code"><a href="code_loading.html#on_load"> Running a Function When a Module is Loaded</a></span>.</p> </dd> </dl> <h4>Behaviour Module Attribute</h4> <p>It is possible to specify that the module is the callback module for a <strong>behaviour</strong>:</p> <div class="example"><pre> -behaviour(Behaviour).</pre></div> <p>The atom <span class="code">Behaviour</span> gives the name of the behaviour, which can be a user-defined behaviour or one of the following OTP standard behaviours:</p> <ul> <li><span class="code">gen_server</span></li> <li><span class="code">gen_fsm</span></li> <li><span class="code">gen_event</span></li> <li><span class="code">supervisor</span></li> </ul> <p>The spelling <span class="code">behavior</span> is also accepted.</p> <p>The callback functions of the module can be specified either directly by the exported function <span class="code">behaviour_info/1</span>:</p> <div class="example"><pre> behaviour_info(callbacks) -> Callbacks.</pre></div> <p>or by a <span class="code">-callback</span> attribute for each callback function:</p> <div class="example"><pre> -callback Name(Arguments) -> Result.</pre></div> <p>Here, <span class="code">Arguments</span> is a list of zero or more arguments. The <span class="code">-callback</span> attribute is to be preferred since the extra type information can be used by tools to produce documentation or find discrepancies.</p> <p>Read more about behaviours and callback modules in <span class="bold_code"><a href="javascript:erlhref('../../','doc/design_principles','spec_proc.html#behaviours');"> OTP Design Principles</a></span>.</p> <h4>Record Definitions</h4> <p>The same syntax as for module attributes is used for record definitions:</p> <div class="example"><pre> -record(Record,Fields).</pre></div> <p>Record definitions are allowed anywhere in a module, also among the function declarations. Read more in <span class="bold_code"><a href="records.html">Records</a></span>.</p> <h4>Preprocessor</h4> <p>The same syntax as for module attributes is used by the preprocessor, which supports file inclusion, macros, and conditional compilation:</p> <div class="example"><pre> -include("SomeFile.hrl"). -define(Macro,Replacement).</pre></div> <p>Read more in <span class="bold_code"><a href="macros.html">Preprocessor</a></span>.</p> <h4>Setting File and Line</h4> <p>The same syntax as for module attributes is used for changing the pre-defined macros <span class="code">?FILE</span> and <span class="code">?LINE</span>:</p> <div class="example"><pre> -file(File, Line).</pre></div> <p>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.</p> <h4>Types and function specifications</h4> <p>A similar syntax as for module attributes is used for specifying types and function specifications: </p> <div class="example"><pre> -type my_type() :: atom() | integer(). -spec my_function(integer()) -> integer().</pre></div> <p>Read more in <span class="bold_code"><a href="typespec.html">Types and Function specifications</a></span>. </p> <p> The description is based on <span class="bold_code"><a href="http://www.erlang.org/eeps/eep-0008.html">EEP8 - Types and function specifications</a></span>, which is not to be further updated. </p> <h3><a name="idp282208324">5.3 Comments</a></h3> <p>Comments can be placed anywhere in a module except within strings and quoted atoms. A comment begins with the character "%", continues up to, but does not include the next end-of-line, and has no effect. Notice that the terminating end-of-line has the effect of white space.</p> <h3><a name="idp282209284">5.4 module_info/0 and module_info/1 functions</a></h3> <p>The compiler automatically inserts the two special, exported functions into each module:</p> <ul> <li><span class="code">Module:module_info/0</span></li> <li><span class="code">Module:module_info/1</span></li> </ul> <p>These functions can be called to retrieve information about the module.</p> <h4>module_info/0</h4> <p>The <span class="code">module_info/0</span> function in each module, returns a list of <span class="code">{Key,Value}</span> tuples with information about the module. Currently, the list contain tuples with the following <span class="code">Key</span>s: <span class="code">module</span>, <span class="code">attributes</span>, <span class="code">compile</span>, <span class="code">exports</span>, <span class="code">md5</span> and <span class="code">native</span>. The order and number of tuples may change without prior notice.</p> <h4>module_info/1</h4> <p>The call <span class="code">module_info(Key)</span>, where <span class="code">Key</span> is an atom, returns a single piece of information about the module.</p> <p>The following values are allowed for <span class="code">Key</span>:</p> <dl> <dt><strong><span class="code">module</span></strong></dt> <dd> <p>Returns an atom representing the module name.</p> </dd> <dt><strong><span class="code">attributes</span></strong></dt> <dd> <p>Returns a list of <span class="code">{AttributeName,ValueList}</span> tuples, where <span class="code">AttributeName</span> is the name of an attribute, and <span class="code">ValueList</span> is a list of values. Notice that a given attribute can occur more than once in the list with different values if the attribute occurs more than once in the module.</p> <p>The list of attributes becomes empty if the module is stripped with the <span class="bold_code"><a href="javascript:erlhref('../../','stdlib','beam_lib.html#strip-1');">beam_lib(3)</a></span> module (in STDLIB).</p> </dd> <dt><strong><span class="code">compile</span></strong></dt> <dd> <p>Returns a list of tuples with information about how the module was compiled. This list is empty if the module has been stripped with the <span class="bold_code"><a href="javascript:erlhref('../../','stdlib','beam_lib.html#strip-1');">beam_lib(3)</a></span> module (in STDLIB).</p> </dd> <dt><strong><span class="code">md5</span></strong></dt> <dd> <p>Returns a binary representing the MD5 checksum of the module. If the module has native code loaded, this will be the MD5 of the native code, not the BEAM bytecode.</p> </dd> <dt><strong><span class="code">exports</span></strong></dt> <dd> <p>Returns a list of <span class="code">{Name,Arity}</span> tuples with all exported functions in the module.</p> </dd> <dt><strong><span class="code">functions</span></strong></dt> <dd> <p>Returns a list of <span class="code">{Name,Arity}</span> tuples with all functions in the module.</p> </dd> <dt><strong><span class="code">native</span></strong></dt> <dd> <p>Return <span class="code">true</span> if the module has native compiled code. Return <span class="code">false</span> otherwise. In a system compiled without HiPE support, the result is always <span class="code">false</span></p> </dd> </dl> </div> <div class="footer"> <hr> <p>Copyright © 2003-2018 Ericsson AB. All Rights Reserved.</p> </div> </div> </div></body> </html>