diff options
Diffstat (limited to 'system/doc/reference_manual/modules.xml')
| -rw-r--r-- | system/doc/reference_manual/modules.xml | 254 |
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> + |