path: root/system/doc/reference_manual/modules.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2003</year><year>2014</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, if the literal term
      <c>Value</c> has the syntax <c>Name/Arity</c>
      (where <c>Name</c> is an atom and <c>Arity</c> a positive integer),
	  the term <c>Name/Arity</c> 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>
        <tag><c>-on_load(Function).</c></tag>
        <item>
          <p>Names a function that should be run automatically when a
            module a loaded. See <seealso marker="code_loading#on_load">
            code loading</seealso> for more information.</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>The callback functions of the module can be specified either
        directly by the exported function <c>behaviour_info/1</c>:</p>
        <pre>
behaviour_info(callbacks) -> Callbacks.</pre>
      <p>or by a <c>-callback</c> attribute for each callback
        function:</p>
      <pre>
-callback Name(Arguments) -> Result.</pre>
      <p>where <c>Arguments</c> is a list of zero or more arguments.
       The <c>-callback</c> 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
        <seealso marker="doc/design_principles:spec_proc#behaviours">
        OTP Design Principles</seealso>.</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>
        <title>Types and function specifications</title>
	<p>A similar syntax as for module attributes is used for 
	specifying types and function specifications.
	</p>
	<pre>
-type my_type() :: atom() | integer().
-spec my_function(integer()) -> integer().
	</pre>
        <p>Read more in <seealso marker="typespec">Types and Function specifications</seealso>.
	</p>
	<p>
	  The description is based on
	    <url href="http://www.erlang.org/eeps/eep-0008.html">EEP8 -
	    Types and function specifications</url>
	    which will not be further updated.
	</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>module</c>, <c>attributes</c>, <c>compile</c>,
      <c>exports</c>, <c>imports</c> and <c>md5</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>module</c></tag>
	  <item>
	  <p>Return an atom representing the module name.</p>
	  </item>

        <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>md5</c></tag>
	  <item>
	  <p>Return a binary representing the MD5 checksum of the module.</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>