The R13B03 release.OTP_R13B03

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>
+