aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/reference_manual/modules.xml
diff options
context:
space:
mode:
Diffstat (limited to 'system/doc/reference_manual/modules.xml')
-rw-r--r--system/doc/reference_manual/modules.xml254
1 files changed, 254 insertions, 0 deletions
diff --git a/system/doc/reference_manual/modules.xml b/system/doc/reference_manual/modules.xml
new file mode 100644
index 0000000000..8b14ca3459
--- /dev/null
+++ b/system/doc/reference_manual/modules.xml
@@ -0,0 +1,254 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2003</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>Modules</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ <file>modules.xml</file>
+ </header>
+
+ <section>
+ <title>Module Syntax</title>
+ <p>Erlang code is divided into <em>modules</em>. A module consists
+ of a sequence of attributes and function declarations, each
+ terminated by period (.). Example:</p>
+ <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>
+ <p>See the <seealso marker="functions">Functions</seealso> chapter
+ for a description of function declarations.</p>
+ </section>
+
+ <section>
+ <title>Module Attributes</title>
+ <p>A <em>module attribute</em> defines a certain property of a
+ module. A module attribute consists of a tag and a value.</p>
+ <pre>
+-Tag(Value).</pre>
+ <p><c>Tag</c> must be an atom, while <c>Value</c> must be a literal
+ term. As a convenience in user-defined attributes, the literal term
+ <c>Value</c> the syntax <c>Name/Arity</c>
+ (where <c>Name</c> is an atom and <c>Arity</c> a positive integer)
+ will be translated to <c>{Name,Arity}</c>.</p>
+
+ <p>Any module attribute can be specified. The attributes are stored
+ in the compiled code and can be retrieved by calling
+ <c>Module:module_info(attributes)</c> or by using
+ <seealso marker="stdlib:beam_lib#chunks/2">beam_lib(3)</seealso>.</p>
+
+ <p>There are several module attributes with predefined meanings,
+ some of which have arity two, but user-defined module
+ attributes must have arity one.</p>
+
+ <section>
+ <title>Pre-Defined Module Attributes</title>
+ <p>Pre-defined module attributes should be placed before any
+ function declaration.</p>
+ <taglist>
+ <tag><c>-module(Module).</c></tag>
+ <item>
+ <p>Module declaration, defining the name of the module.
+ The name <c>Module</c>, an atom, should be the same as
+ the file name minus the extension <c>erl</c>. Otherwise
+ <seealso marker="code_loading#loading">code loading</seealso> will
+ not work as intended.</p>
+ <p>This attribute should be specified first and is the only
+ attribute which is mandatory.</p>
+ </item>
+ <tag><c>-export(Functions).</c></tag>
+ <item>
+ <p>Exported functions. Specifies which of the functions
+ defined within the module that are visible outside
+ the module.</p>
+ <p><c>Functions</c> is a list
+ <c>[Name1/Arity1, ..., NameN/ArityN]</c>, where each
+ <c>NameI</c> is an atom and <c>ArityI</c> an integer.</p>
+ </item>
+ <tag><c>-import(Module,Functions).</c></tag>
+ <item>
+ <p>Imported functions. Imported functions can be called
+ the same way as local functions, that is without any module
+ prefix.</p>
+ <p><c>Module</c>, an atom, specifies which module to import
+ functions from. <c>Functions</c> is a list similar as for
+ <c>export</c> above.</p>
+ </item>
+ <tag><c>-compile(Options).</c></tag>
+ <item>
+ <p>Compiler options. <c>Options</c>, which is a single option
+ or a list of options, will be added to the option list when
+ compiling the module. See <c>compile(3)</c>.</p>
+ </item>
+ <tag><c>-vsn(Vsn).</c></tag>
+ <item>
+ <p>Module version. <c>Vsn</c> is any literal term and can be
+ retrieved using <c>beam_lib:version/1</c>, see
+ <seealso marker="stdlib:beam_lib#version/1">beam_lib(3)</seealso>.</p>
+ <p>If this attribute is not specified, the version defaults
+ to the MD5 checksum of the module.</p>
+ </item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>Behaviour Module Attribute</title>
+ <p>It is possible to specify that the module is the callback
+ module for a <em>behaviour</em>:</p>
+ <pre>
+-behaviour(Behaviour).</pre>
+ <p>The atom <c>Behaviour</c> gives the name of the behaviour,
+ which can be a user defined behaviour or one of the OTP
+ standard behaviours <c>gen_server</c>, <c>gen_fsm</c>,
+ <c>gen_event</c> or <c>supervisor</c>.</p>
+ <p>The spelling <c>behavior</c> is also accepted.</p>
+ <p>Read more about behaviours and callback modules in OTP Design
+ Principles.</p>
+ </section>
+
+ <section>
+ <title>Record Definitions</title>
+ <p>The same syntax as for module attributes is used by
+ for record definitions:</p>
+ <pre>
+-record(Record,Fields).</pre>
+ <p>Record definitions are allowed anywhere in a module,
+ also among the function declarations.
+ Read more in <seealso marker="records">Records</seealso>.</p>
+ </section>
+
+ <section>
+ <title>The Preprocessor</title>
+ <p>The same syntax as for module attributes is used by
+ the preprocessor, which supports file inclusion, macros,
+ and conditional compilation:</p>
+ <pre>
+-include("SomeFile.hrl").
+-define(Macro,Replacement).</pre>
+
+ <p>Read more in <seealso marker="macros">The Preprocessor</seealso>.</p>
+ </section>
+
+ <section>
+ <title>Setting File and Line</title>
+ <p>The same syntax as for module attributes is used for
+ changing the pre-defined macros <c>?FILE</c> and <c>?LINE</c>:</p>
+ <pre>
+-file(File, Line).</pre>
+ <p>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.</p>
+ </section>
+ </section>
+
+ <section>
+ <title>Comments</title>
+ <p>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.</p>
+ </section>
+
+ <section>
+ <title>The module_info/0 and module_info/1 functions</title>
+
+ <p>The compiler automatically inserts the two special, exported
+ functions into each module: <c>Module:module_info/0</c> and
+ <c>Module:module_info/1</c>. These functions can be called to
+ retrieve information about the module.</p>
+
+ <section>
+ <title>module_info/0</title>
+ <p>The <c>module_info/0</c> function in each module returns
+ a list of <c>{Key,Value}</c> tuples with information about
+ the module. Currently, the list contain tuples with the following
+ <c>Key</c>s: <c>attributes</c>, <c>compile</c>,
+ <c>exports</c>, and <c>imports</c>. The order and number of tuples
+ may change without prior notice.</p>
+
+ <warning><p>The <c>{imports,Value}</c> tuple may be removed in a future
+ release because <c>Value</c> is always an empty list.
+ Do not write code that depends on it being present.</p></warning>
+ </section>
+
+ <section>
+ <title>module_info/1</title>
+ <p>The call <c>module_info(Key)</c>, where key is an atom,
+ returns a single piece of information about the module.</p>
+
+ <p>The following values are allowed for <c>Key</c>:</p>
+
+ <taglist>
+ <tag><c>attributes</c></tag>
+ <item>
+ <p>Return a list of <c>{AttributeName,ValueList}</c> tuples,
+ where <c>AttributeName</c> is the name of an attribute,
+ and <c>ValueList</c> 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.</p>
+
+ <p>The list of attributes will be empty if
+ the module has been stripped with
+ <seealso marker="stdlib:beam_lib#strip/1">beam_lib(3)</seealso>.</p>
+ </item>
+
+ <tag><c>compile</c></tag>
+ <item>
+ <p>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
+ <seealso marker="stdlib:beam_lib#strip/1">beam_lib(3)</seealso>.</p>
+ </item>
+
+ <tag><c>imports</c></tag>
+ <item>
+ <p>Always return an empty list. The <c>imports</c> key may not
+ be supported in future release.</p>
+ </item>
+
+ <tag><c>exports</c></tag>
+ <item>
+ <p>Return a list of <c>{Name,Arity}</c> tuples with
+ all exported functions in the module.</p>
+ </item>
+
+ <tag><c>functions</c></tag>
+ <item>
+ <p>Return a list of <c>{Name,Arity}</c> tuples with
+ all functions in the module.</p>
+ </item>
+ </taglist>
+ </section>
+ </section>
+
+</chapter>
+