From 9fe8adf35c16ab5d4566b03f3b36863c90b5b6dd Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Thu, 12 Mar 2015 15:35:13 +0100 Subject: Update Erlang Reference Manual Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Hans Bolinder. --- system/doc/reference_manual/modules.xml | 153 ++++++++++++++++++-------------- 1 file changed, 86 insertions(+), 67 deletions(-) (limited to 'system/doc/reference_manual/modules.xml') diff --git a/system/doc/reference_manual/modules.xml b/system/doc/reference_manual/modules.xml index 5cb0c11371..39c739a146 100644 --- a/system/doc/reference_manual/modules.xml +++ b/system/doc/reference_manual/modules.xml @@ -4,7 +4,7 @@
- 20032014 + 20032015 Ericsson AB. All Rights Reserved. @@ -33,7 +33,8 @@ Module Syntax

Erlang code is divided into modules. A module consists of a sequence of attributes and function declarations, each - terminated by period (.). Example:

+ terminated by period (.).

+

Example:

 -module(m).          % module attribute
 -export([fact/1]).   % module attribute
@@ -42,50 +43,52 @@ fact(N) when N>0 ->  % beginning of function declaration
     N * fact(N-1);   %  |
 fact(0) ->           %  |
     1.               % end of function declaration
-

See the Functions chapter - for a description of function declarations.

+

For a description of function declarations, see + Function Declaration Syntax.

Module Attributes

A module attribute defines a certain property of a - module. A module attribute consists of a tag and a value.

+ module.

+

A module attribute consists of a tag and a value:

 -Tag(Value).

Tag must be an atom, while Value must be a literal term. As a convenience in user-defined attributes, if the literal term Value has the syntax Name/Arity (where Name is an atom and Arity a positive integer), - the term Name/Arity will be translated to {Name,Arity}.

+ the term Name/Arity is translated to {Name,Arity}.

Any module attribute can be specified. The attributes are stored in the compiled code and can be retrieved by calling - Module:module_info(attributes) or by using - beam_lib(3).

+ Module:module_info(attributes), or by using the module + beam_lib(3) + in STDLIB.

-

There are several module attributes with predefined meanings, - some of which have arity two, but user-defined module +

Several module attributes have predefined meanings. + Some of them have arity two, but user-defined module attributes must have arity one.

Pre-Defined Module Attributes -

Pre-defined module attributes should be placed before any +

Pre-defined module attributes is to be placed before any function declaration.

-module(Module).

Module declaration, defining the name of the module. - The name Module, an atom, should be the same as - the file name minus the extension erl. Otherwise - code loading will + The name Module, an atom, is to be same as + the file name minus the extension .erl. Otherwise + code loading does not work as intended.

-

This attribute should be specified first and is the only - attribute which is mandatory.

+

This attribute is to be specified first and is the only + mandatory attribute.

 -export(Functions). -

Exported functions. Specifies which of the functions - defined within the module that are visible outside +

Exported functions. Specifies which of the functions, + defined within the module, that are visible from outside the module.

Functions is a list [Name1/Arity1, ..., NameN/ArityN], where each @@ -93,32 +96,37 @@ fact(0) -> % | -import(Module,Functions). -

Imported functions. Imported functions can be called - the same way as local functions, that is without any module +

Imported functions. Can be called + the same way as local functions, that is, without any module prefix.

Module, an atom, specifies which module to import functions from. Functions is a list similar as for - export above.

+ export.

 -compile(Options). -

Compiler options. Options, which is a single option - or a list of options, will be added to the option list when - compiling the module. See compile(3).

+

Compiler options. Options is a single option + or a list of options. + This attribute is added to the option list when + compiling the module. See the + compile(3) manual page in Compiler.

 -vsn(Vsn).

Module version. Vsn is any literal term and can be - retrieved using beam_lib:version/1, see - beam_lib(3).

+ retrieved using beam_lib:version/1, see the + beam_lib(3) + manual page in STDLIB.

If this attribute is not specified, the version defaults to the MD5 checksum of the module.

 -on_load(Function). -

Names a function that should be run automatically when a - module a loaded. See - code loading for more information.

+

This attribute names a function that is to be run + automatically when a + module is loaded. For more information, see + + Running a Function When a Module is Loaded.
@@ -130,9 +138,14 @@ fact(0) -> % | 
 -behaviour(Behaviour).

The atom Behaviour gives the name of the behaviour, - which can be a user defined behaviour or one of the OTP - standard behaviours gen_server, gen_fsm, - gen_event or supervisor.

+ which can be a user-defined behaviour or one of the following OTP + standard behaviours:

+ + gen_server + gen_fsm + gen_event + supervisor +

The spelling behavior is also accepted.

The callback functions of the module can be specified either directly by the exported function behaviour_info/1:

@@ -142,7 +155,7 @@ behaviour_info(callbacks) -> Callbacks. function:

 -callback Name(Arguments) -> Result.
-

where Arguments is a list of zero or more arguments. +

Here, Arguments is a list of zero or more arguments. The -callback attribute is to be preferred since the extra type information can be used by tools to produce documentation or find discrepancies.

@@ -153,7 +166,7 @@ behaviour_info(callbacks) -> Callbacks.
Record Definitions -

The same syntax as for module attributes is used by +

The same syntax as for module attributes is used for record definitions:

 -record(Record,Fields).
@@ -163,7 +176,7 @@ behaviour_info(callbacks) -> Callbacks.
- The Preprocessor + Preprocessor

The same syntax as for module attributes is used by the preprocessor, which supports file inclusion, macros, and conditional compilation:

@@ -171,7 +184,7 @@ behaviour_info(callbacks) -> Callbacks. -include("SomeFile.hrl"). -define(Macro,Replacement). -

Read more in The Preprocessor.

+

Read more in Preprocessor.

@@ -180,17 +193,17 @@ behaviour_info(callbacks) -> Callbacks. changing the pre-defined macros ?FILE and ?LINE:

 -file(File, Line).
-

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.

+

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.

Types and function specifications

A similar syntax as for module attributes is used for - specifying types and function specifications. + specifying types and function specifications: 

 -type my_type() :: atom() | integer().
@@ -200,32 +213,36 @@ behaviour_info(callbacks) -> Callbacks.

The description is based on EEP8 - - Types and function specifications - which will not be further updated. + Types and function specifications, + which is not to be further updated.

Comments -

Comments may be placed anywhere in a module except within strings - and quoted atoms. The comment begins with the character "%", +

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. Note that the terminating end-of-line has + has no effect. Notice that the terminating end-of-line has the effect of white space.

- The module_info/0 and module_info/1 functions + module_info/0 and module_info/1 functions

The compiler automatically inserts the two special, exported - functions into each module: Module:module_info/0 and - Module:module_info/1. These functions can be called to - retrieve information about the module.

+ functions into each module:

+ + Module:module_info/0 + Module:module_info/1 + +

These functions can be called to retrieve information + about the module.

module_info/0 -

The module_info/0 function in each module returns +

The module_info/0 function in each module, returns a list of {Key,Value} tuples with information about the module. Currently, the list contain tuples with the following Keys: module, attributes, compile, @@ -235,7 +252,7 @@ behaviour_info(callbacks) -> Callbacks.

module_info/1 -

The call module_info(Key), where key is an atom, +

The call module_info(Key), where Key is an atom, returns a single piece of information about the module.

The following values are allowed for Key:

@@ -243,44 +260,46 @@ behaviour_info(callbacks) -> Callbacks. module -

Return an atom representing the module name.

+

Returns an atom representing the module name.

 attributes -

Return a list of {AttributeName,ValueList} tuples, +

Returns a list of {AttributeName,ValueList} tuples, where AttributeName is the name of an attribute, - and ValueList is a list of values. Note: a given - attribute may occur more than once in the list with different + and ValueList 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.

-

The list of attributes will be empty if - the module has been stripped with - beam_lib(3).

+

The list of attributes becomes empty if + the module is stripped with the + beam_lib(3) + module (in STDLIB).

 compile -

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 - beam_lib(3).

+

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 + beam_lib(3) + module (in STDLIB).

 md5 -

Return a binary representing the MD5 checksum of the module.

+

Returns a binary representing the MD5 checksum of the module.

 exports -

Return a list of {Name,Arity} tuples with +

Returns a list of {Name,Arity} tuples with all exported functions in the module.

 functions -

Return a list of {Name,Arity} tuples with +

Returns a list of {Name,Arity} tuples with all functions in the module.

 -- cgit v1.2.3