<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../otp_doc.css" type="text/css">
<title>Erlang -- Types and Function Specifications</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="../pdf/otp-system-documentation-5.9.3.1.pdf">PDF</a><br><a href="../index.html">Top</a></small><p><strong>Erlang Reference Manual</strong><br><strong>User's Guide</strong><br><small>Version 5.9.3.1</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../js/flipmenu">
<li id="no" title="Introduction" expanded="false">Introduction<ul>
<li><a href="introduction.html">
Top of chapter
</a></li>
<li title="Purpose"><a href="introduction.html#id73748">Purpose</a></li>
<li title="Prerequisites"><a href="introduction.html#id66106">Prerequisites</a></li>
<li title="Document Conventions"><a href="introduction.html#id67296">Document Conventions</a></li>
<li title="Complete List of BIFs"><a href="introduction.html#id68121">Complete List of BIFs</a></li>
<li title="Reserved Words"><a href="introduction.html#id60679">Reserved Words</a></li>
<li title="Character Set"><a href="introduction.html#id61758">Character Set</a></li>
</ul>
</li>
<li id="no" title="Data Types" expanded="false">Data Types<ul>
<li><a href="data_types.html">
Top of chapter
</a></li>
<li title="Terms"><a href="data_types.html#id63330">Terms</a></li>
<li title="Number"><a href="data_types.html#id68697">Number</a></li>
<li title="Atom"><a href="data_types.html#id62285">Atom</a></li>
<li title="Bit Strings and Binaries"><a href="data_types.html#id68011">Bit Strings and Binaries</a></li>
<li title="Reference"><a href="data_types.html#id58120">Reference</a></li>
<li title="Fun"><a href="data_types.html#id67499">Fun</a></li>
<li title="Port Identifier"><a href="data_types.html#id69290">Port Identifier</a></li>
<li title="Pid"><a href="data_types.html#id60853">Pid</a></li>
<li title="Tuple"><a href="data_types.html#id73719">Tuple</a></li>
<li title="List"><a href="data_types.html#id73198">List</a></li>
<li title="String"><a href="data_types.html#id68626">String</a></li>
<li title="Record"><a href="data_types.html#id65682">Record</a></li>
<li title="Boolean"><a href="data_types.html#id67471">Boolean</a></li>
<li title="Escape Sequences"><a href="data_types.html#id73885">Escape Sequences</a></li>
<li title="Type Conversions"><a href="data_types.html#id69219">Type Conversions</a></li>
</ul>
</li>
<li id="no" title="Pattern Matching" expanded="false">Pattern Matching<ul>
<li><a href="patterns.html">
Top of chapter
</a></li>
<li title="Pattern Matching"><a href="patterns.html#id68202">Pattern Matching</a></li>
</ul>
</li>
<li id="no" title="Modules" expanded="false">Modules<ul>
<li><a href="modules.html">
Top of chapter
</a></li>
<li title="Module Syntax"><a href="modules.html#id68326">Module Syntax</a></li>
<li title="Module Attributes"><a href="modules.html#id68358">Module Attributes</a></li>
<li title="Comments"><a href="modules.html#id74337">Comments</a></li>
<li title="The module_info/0 and module_info/1 functions"><a href="modules.html#id74350">The module_info/0 and module_info/1 functions</a></li>
</ul>
</li>
<li id="no" title="Functions" expanded="false">Functions<ul>
<li><a href="functions.html">
Top of chapter
</a></li>
<li title="Function Declaration Syntax"><a href="functions.html#id74609">Function Declaration Syntax</a></li>
<li title="Function Evaluation"><a href="functions.html#id74724">Function Evaluation</a></li>
<li title="Tail recursion"><a href="functions.html#id74875">Tail recursion</a></li>
<li title="Built-In Functions, BIFs"><a href="functions.html#id74908">Built-In Functions, BIFs</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Types and Function Specifications" expanded="true">Types and Function Specifications<ul>
<li><a href="typespec.html">
Top of chapter
</a></li>
<li title="Introduction of Types"><a href="typespec.html#id75024">Introduction of Types</a></li>
<li title="Types and their Syntax"><a href="typespec.html#id75072">Types and their Syntax</a></li>
<li title="Type declarations of user-defined types"><a href="typespec.html#id75688">Type declarations of user-defined types</a></li>
<li title="Type information in record declarations"><a href="typespec.html#id75770">Type information in record declarations</a></li>
<li title="Specifications for functions"><a href="typespec.html#id75847">Specifications for functions</a></li>
</ul>
</li>
<li id="no" title="Expressions" expanded="false">Expressions<ul>
<li><a href="expressions.html">
Top of chapter
</a></li>
<li title="Expression Evaluation"><a href="expressions.html#id76067">Expression Evaluation</a></li>
<li title="Terms"><a href="expressions.html#id76110">Terms</a></li>
<li title="Variables"><a href="expressions.html#id76122">Variables</a></li>
<li title="Patterns"><a href="expressions.html#id76253">Patterns</a></li>
<li title="Match"><a href="expressions.html#id76372">Match</a></li>
<li title="Function Calls"><a href="expressions.html#id76431">Function Calls</a></li>
<li title="If"><a href="expressions.html#id76631">If</a></li>
<li title="Case"><a href="expressions.html#id76696">Case</a></li>
<li title="Send"><a href="expressions.html#id76761">Send</a></li>
<li title="Receive"><a href="expressions.html#id76844">Receive</a></li>
<li title="Term Comparisons"><a href="expressions.html#id77009">Term Comparisons</a></li>
<li title="Arithmetic Expressions"><a href="expressions.html#id77270">Arithmetic Expressions</a></li>
<li title="Boolean Expressions"><a href="expressions.html#id77776">Boolean Expressions</a></li>
<li title="Short-Circuit Expressions"><a href="expressions.html#id77931">Short-Circuit Expressions</a></li>
<li title="List Operations"><a href="expressions.html#id78047">List Operations</a></li>
<li title="Bit Syntax Expressions"><a href="expressions.html#id78116">Bit Syntax Expressions</a></li>
<li title="Fun Expressions"><a href="expressions.html#id78658">Fun Expressions</a></li>
<li title="Catch and Throw"><a href="expressions.html#id78840">Catch and Throw</a></li>
<li title="Try"><a href="expressions.html#id78986">Try</a></li>
<li title="Parenthesized Expressions"><a href="expressions.html#id79344">Parenthesized Expressions</a></li>
<li title="Block Expressions"><a href="expressions.html#id79376">Block Expressions</a></li>
<li title="List Comprehensions"><a href="expressions.html#id79401">List Comprehensions</a></li>
<li title="Bit String Comprehensions"><a href="expressions.html#id79541">Bit String Comprehensions</a></li>
<li title="Guard Sequences"><a href="expressions.html#id79673">Guard Sequences</a></li>
<li title="Operator Precedence"><a href="expressions.html#id80211">Operator Precedence</a></li>
</ul>
</li>
<li id="no" title="The Preprocessor" expanded="false">The Preprocessor<ul>
<li><a href="macros.html">
Top of chapter
</a></li>
<li title="File Inclusion"><a href="macros.html#id80530">File Inclusion</a></li>
<li title="Defining and Using Macros"><a href="macros.html#id80659">Defining and Using Macros</a></li>
<li title="Predefined Macros"><a href="macros.html#id80782">Predefined Macros</a></li>
<li title="Macros Overloading"><a href="macros.html#id80850">Macros Overloading</a></li>
<li title="Flow Control in Macros"><a href="macros.html#id80919">Flow Control in Macros</a></li>
<li title="Stringifying Macro Arguments"><a href="macros.html#id81056">Stringifying Macro Arguments</a></li>
</ul>
</li>
<li id="no" title="Records" expanded="false">Records<ul>
<li><a href="records.html">
Top of chapter
</a></li>
<li title="Defining Records"><a href="records.html#id81178">Defining Records</a></li>
<li title="Creating Records"><a href="records.html#id81209">Creating Records</a></li>
<li title="Accessing Record Fields"><a href="records.html#id81264">Accessing Record Fields</a></li>
<li title="Updating Records"><a href="records.html#id81303">Updating Records</a></li>
<li title="Records in Guards"><a href="records.html#id81336">Records in Guards</a></li>
<li title="Records in Patterns"><a href="records.html#id81368">Records in Patterns</a></li>
<li title="Nested records"><a href="records.html#id81395">Nested records</a></li>
<li title="Internal Representation of Records"><a href="records.html#id81430">Internal Representation of Records</a></li>
</ul>
</li>
<li id="no" title="Errors and Error Handling" expanded="false">Errors and Error Handling<ul>
<li><a href="errors.html">
Top of chapter
</a></li>
<li title="Terminology"><a href="errors.html#id81550">Terminology</a></li>
<li title="Exceptions"><a href="errors.html#id81678">Exceptions</a></li>
<li title="Handling of Run-Time Errors in Erlang"><a href="errors.html#id81851">Handling of Run-Time Errors in Erlang</a></li>
<li title="Exit Reasons"><a href="errors.html#id81913">Exit Reasons</a></li>
</ul>
</li>
<li id="no" title="Processes" expanded="false">Processes<ul>
<li><a href="processes.html">
Top of chapter
</a></li>
<li title="Processes"><a href="processes.html#id82387">Processes</a></li>
<li title="Process Creation"><a href="processes.html#id82400">Process Creation</a></li>
<li title="Registered Processes"><a href="processes.html#id82449">Registered Processes</a></li>
<li title="Process Termination"><a href="processes.html#id82560">Process Termination</a></li>
<li title="Message Sending"><a href="processes.html#id82650">Message Sending</a></li>
<li title="Links"><a href="processes.html#id82679">Links</a></li>
<li title="Error Handling"><a href="processes.html#id82744">Error Handling</a></li>
<li title="Monitors"><a href="processes.html#id82854">Monitors</a></li>
<li title="Process Dictionary"><a href="processes.html#id82946">Process Dictionary</a></li>
</ul>
</li>
<li id="no" title="Distributed Erlang" expanded="false">Distributed Erlang<ul>
<li><a href="distributed.html">
Top of chapter
</a></li>
<li title="Distributed Erlang System"><a href="distributed.html#id83013">Distributed Erlang System</a></li>
<li title="Nodes"><a href="distributed.html#id83044">Nodes</a></li>
<li title="Node Connections"><a href="distributed.html#id83114">Node Connections</a></li>
<li title="epmd"><a href="distributed.html#id83164">epmd</a></li>
<li title="Hidden Nodes"><a href="distributed.html#id83184">Hidden Nodes</a></li>
<li title="C Nodes"><a href="distributed.html#id83230">C Nodes</a></li>
<li title="Security"><a href="distributed.html#id83254">Security</a></li>
<li title="Distribution BIFs"><a href="distributed.html#id83364">Distribution BIFs</a></li>
<li title="Distribution Command Line Flags"><a href="distributed.html#id83662">Distribution Command Line Flags</a></li>
<li title="Distribution Modules"><a href="distributed.html#id83799">Distribution Modules</a></li>
</ul>
</li>
<li id="no" title="Compilation and Code Loading" expanded="false">Compilation and Code Loading<ul>
<li><a href="code_loading.html">
Top of chapter
</a></li>
<li title="Compilation"><a href="code_loading.html#id84002">Compilation</a></li>
<li title="Code Loading"><a href="code_loading.html#id84112">Code Loading</a></li>
<li title="Code Replacement"><a href="code_loading.html#id84159">Code Replacement</a></li>
<li title="Running a function when a module is loaded"><a href="code_loading.html#id84234">Running a function when a module is loaded</a></li>
</ul>
</li>
<li id="no" title="Ports and Port Drivers" expanded="false">Ports and Port Drivers<ul>
<li><a href="ports.html">
Top of chapter
</a></li>
<li title="Ports"><a href="ports.html#id84374">Ports</a></li>
<li title="Port Drivers"><a href="ports.html#id84409">Port Drivers</a></li>
<li title="Port BIFs"><a href="ports.html#id84449">Port BIFs</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>6 Types and Function Specifications</h1>
<h3><a name="id75024">6.1
Introduction of Types</a></h3>
<p>
Erlang is a dynamically typed language. Still, it comes with a
language extension for declaring sets of Erlang terms to form a
particular type, effectively forming a specific sub-type of the set
of all Erlang terms.
</p>
<p>
Subsequently, these types can be used to specify types of record fields
and the argument and return types of functions.
</p>
<p>
Type information can be used to document function interfaces,
provide more information for bug detection tools such as <span class="code">Dialyzer</span>,
and can be exploited by documentation tools such as <span class="code">Edoc</span> for
generating program documentation of various forms.
It is expected that the type language described in this document will
supersede and replace the purely comment-based <span class="code">@type</span> and
<span class="code">@spec</span> declarations used by <span class="code">Edoc</span>.
</p>
<h3><a name="id75072">6.2
Types and their Syntax</a></h3>
<a name="syntax"></a>
<p>
Types describe sets of Erlang terms.
Types consist and are built from a set of predefined types (e.g. <span class="code">integer()</span>,
<span class="code">atom()</span>, <span class="code">pid()</span>, ...) described below.
Predefined types represent a typically infinite set of Erlang terms which
belong to this type.
For example, the type <span class="code">atom()</span> stands for the set of all Erlang atoms.
</p>
<p>
For integers and atoms, we allow for singleton types (e.g. the integers <span class="code">-1</span>
and <span class="code">42</span> or the atoms <span class="code">'foo'</span> and <span class="code">'bar'</span>).
All other types are built using unions of either predefined types or singleton
types. In a type union between a type and one of its sub-types the sub-type is
absorbed by the super-type and the union is subsequently treated as if the
sub-type was not a constituent of the union. For example, the type union:
</p>
<div class="example"><pre>
atom() | 'bar' | integer() | 42</pre></div>
<p>
describes the same set of terms as the type union:
</p>
<div class="example"><pre>
atom() | integer()</pre></div>
<p>
Because of sub-type relations that exist between types, types form a lattice
where the topmost element, any(), denotes the set of all Erlang terms and
the bottom-most element, none(), denotes the empty set of terms.
</p>
<p>
The set of predefined types and the syntax for types is given below:
</p>
<div class="example"><pre>
Type :: any() %% The top type, the set of all Erlang terms.
| none() %% The bottom type, contains no terms.
| pid()
| port()
| reference()
| [] %% nil
| Atom
| Binary
| float()
| Fun
| Integer
| List
| Tuple
| Union
| UserDefined %% described in Section 2
Union :: Type1 | Type2
Atom :: atom()
| Erlang_Atom %% 'foo', 'bar', ...
Binary :: binary() %% <<_:_ * 8>>
| <<>>
| <<_:Erlang_Integer>> %% Base size
| <<_:_*Erlang_Integer>> %% Unit size
| <<_:Erlang_Integer, _:_*Erlang_Integer>>
Fun :: fun() %% any function
| fun((...) -> Type) %% any arity, returning Type
| fun(() -> Type)
| fun((TList) -> Type)
Integer :: integer()
| Erlang_Integer %% ..., -1, 0, 1, ... 42 ...
| Erlang_Integer..Erlang_Integer %% specifies an integer range
List :: list(Type) %% Proper list ([]-terminated)
| improper_list(Type1, Type2) %% Type1=contents, Type2=termination
| maybe_improper_list(Type1, Type2) %% Type1 and Type2 as above
Tuple :: tuple() %% stands for a tuple of any size
| {}
| {TList}
TList :: Type
| Type, TList
</pre></div>
<p>
Because lists are commonly used, they have shorthand type notations.
The type <span class="code">list(T)</span> has the shorthand <span class="code">[T]</span>.
The shorthand <span class="code">[T,...]</span> stands for
the set of non-empty proper lists whose elements are of type <span class="code">T</span>.
The only difference between the two shorthands is that <span class="code">[T]</span> may be an
empty list but <span class="code">[T,...]</span> may not.
</p>
<p>
Notice that the shorthand for <span class="code">list()</span>, i.e. the list of
elements of unknown type, is <span class="code">[_]</span> (or <span class="code">[any()]</span>), not <span class="code">[]</span>.
The notation <span class="code">[]</span> specifies the singleton type for the empty list.
</p>
<p>
For convenience, the following types are also built-in.
They can be thought as predefined aliases for the type unions also shown in
the table. (Some type unions below slightly abuse the syntax of types.)
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle"><strong>Built-in type</strong></td>
<td align="left" valign="middle"><strong>Stands for</strong></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">term()</span></td>
<td align="left" valign="middle"><span class="code">any()</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">boolean()</span></td>
<td align="left" valign="middle"><span class="code">'false' | 'true'</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">byte()</span></td>
<td align="left" valign="middle"><span class="code">0..255</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">char()</span></td>
<td align="left" valign="middle"><span class="code">0..16#10ffff</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">non_neg_integer()</span></td>
<td align="left" valign="middle"><span class="code">0..</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">pos_integer()</span></td>
<td align="left" valign="middle"><span class="code">1..</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">neg_integer()</span></td>
<td align="left" valign="middle"><span class="code">..-1</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">number()</span></td>
<td align="left" valign="middle"><span class="code">integer() | float()</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">list()</span></td>
<td align="left" valign="middle"><span class="code">[any()]</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">maybe_improper_list()</span></td>
<td align="left" valign="middle"><span class="code">maybe_improper_list(any(), any())</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">maybe_improper_list(T)</span></td>
<td align="left" valign="middle"><span class="code">maybe_improper_list(T, any())</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">string()</span></td>
<td align="left" valign="middle"><span class="code">[char()]</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">nonempty_string()</span></td>
<td align="left" valign="middle"><span class="code">[char(),...]</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">iolist()</span></td>
<td align="left" valign="middle"><span class="code">maybe_improper_list(char() | binary() | iolist(), binary() | [])</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">module()</span></td>
<td align="left" valign="middle"><span class="code">atom()</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">mfa()</span></td>
<td align="left" valign="middle"><span class="code">{atom(),atom(),byte()}</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">node()</span></td>
<td align="left" valign="middle"><span class="code">atom()</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">timeout()</span></td>
<td align="left" valign="middle"><span class="code">'infinity' | non_neg_integer()</span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">no_return()</span></td>
<td align="left" valign="middle"><span class="code">none()</span></td>
</tr>
</table>
<p>
Users are not allowed to define types with the same names as the
predefined or built-in ones. This is checked by the compiler and
its violation results in a compilation error.
(For bootstrapping purposes, it can also result to just a warning if this
involves a built-in type which has just been introduced.)
</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
The following built-in list types also exist,
but they are expected to be rarely used. Hence, they have long names:
</p></div>
</div>
<div class="example"><pre>
nonempty_maybe_improper_list(Type) :: nonempty_maybe_improper_list(Type, any())
nonempty_maybe_improper_list() :: nonempty_maybe_improper_list(any())</pre></div>
<p>
where the following two types
define the set of Erlang terms one would expect:
</p>
<div class="example"><pre>
nonempty_improper_list(Type1, Type2)
nonempty_maybe_improper_list(Type1, Type2)</pre></div>
<p>
Also for convenience, we allow for record notation to be used.
Records are just shorthands for the corresponding tuples.
</p>
<div class="example"><pre>
Record :: #Erlang_Atom{}
| #Erlang_Atom{Fields}</pre></div>
<p>
Records have been extended to possibly contain type information.
This is described in the sub-section <span class="bold_code"><a href="#typeinrecords">"Type information in record declarations"</a></span> below.
</p>
<h3><a name="id75688">6.3
Type declarations of user-defined types</a></h3>
<p>
As seen, the basic syntax of a type is an atom followed by closed
parentheses. New types are declared using '-type' and '-opaque'
compiler attributes as in the following:
</p>
<div class="example"><pre>
-type my_struct_type() :: Type.
-opaque my_opaq_type() :: Type.</pre></div>
<p>
where the type name is an atom (<span class="code">'my_struct_type'</span> in the above)
followed by parentheses. Type is a type as defined in the
previous section.
A current restriction is that Type can contain only predefined types,
or user-defined types which are either module-local (i.e., with a
definition that is present in the code of the module) or are remote
types (i.e., types defined in and exported by other modules; see below).
For module-local types, the restriction that their definition
exists in the module is enforced by the compiler and results in a
compilation error. (A similar restriction currently exists for records.)
</p>
<p>
Type declarations can also be parameterized by including type variables
between the parentheses. The syntax of type variables is the same as
Erlang variables (starts with an upper case letter).
Naturally, these variables can - and should - appear on the RHS of the
definition. A concrete example appears below:
</p>
<div class="example"><pre>
-type orddict(Key, Val) :: [{Key, Val}].</pre></div>
<p>
A module can export some types in order to declare that other modules
are allowed to refer to them as <strong>remote types</strong>.
This declaration has the following form:
<div class="example"><pre>
-export_type([T1/A1, ..., Tk/Ak]).</pre></div>
where the Ti's are atoms (the name of the type) and the Ai's are their
arguments. An example is given below:
<div class="example"><pre>
-export_type([my_struct_type/0, orddict/2]).</pre></div>
Assuming that these types are exported from module <span class="code">'mod'</span> then
one can refer to them from other modules using remote type expressions
like those below:
<div class="example"><pre>
mod:my_struct_type()
mod:orddict(atom(), term())</pre></div>
One is not allowed to refer to types which are not declared as exported.
</p>
<p>
Types declared as <span class="code">opaque</span> represent sets of terms whose
structure is not supposed to be visible in any way outside of
their defining module (i.e., only the module defining them is
allowed to depend on their term structure). Consequently, such
types do not make much sense as module local - module local
types are not accessible by other modules anyway - and should
always be exported.
</p>
<a name="typeinrecords"></a>
<h3><a name="id75770">6.4
Type information in record declarations</a></h3>
<p>
The types of record fields can be specified in the declaration of the
record. The syntax for this is:
</p>
<div class="example"><pre>
-record(rec, {field1 :: Type1, field2, field3 :: Type3}).</pre></div>
<p>
For fields without type annotations, their type defaults to any().
I.e., the above is a shorthand for:
</p>
<div class="example"><pre>
-record(rec, {field1 :: Type1, field2 :: any(), field3 :: Type3}).</pre></div>
<p>
In the presence of initial values for fields,
the type must be declared after the initialization as in the following:
</p>
<div class="example"><pre>
-record(rec, {field1 = [] :: Type1, field2, field3 = 42 :: Type3}).</pre></div>
<p>
Naturally, the initial values for fields should be compatible
with (i.e. a member of) the corresponding types.
This is checked by the compiler and results in a compilation error
if a violation is detected. For fields without initial values,
the singleton type <span class="code">'undefined'</span> is added to all declared types.
In other words, the following two record declarations have identical
effects:
</p>
<div class="example"><pre>
-record(rec, {f1 = 42 :: integer(),
f2 :: float(),
f3 :: 'a' | 'b'}).
-record(rec, {f1 = 42 :: integer(),
f2 :: 'undefined' | float(),
f3 :: 'undefined' | 'a' | 'b'}).</pre></div>
<p>
For this reason, it is recommended that records contain initializers,
whenever possible.
</p>
<p>
Any record, containing type information or not, once defined,
can be used as a type using the syntax:
</p>
<div class="example"><pre>
#rec{}</pre></div>
<p>
In addition, the record fields can be further specified when using
a record type by adding type information about the field in
the following manner:
</p>
<div class="example"><pre>
#rec{some_field :: Type}</pre></div>
<p>
Any unspecified fields are assumed to have the type in the original
record declaration.
</p>
<h3><a name="id75847">6.5
Specifications for functions</a></h3>
<p>
A specification (or contract) for a function is given using the new
compiler attribute <span class="code">'-spec'</span>. The general format is as follows:
</p>
<div class="example"><pre>
-spec Module:Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre></div>
<p>
The arity of the function has to match the number of arguments,
or else a compilation error occurs.
</p>
<p>
This form can also be used in header files (.hrl) to declare type
information for exported functions.
Then these header files can be included in files that (implicitly or
explicitly) import these functions.
</p>
<p>
For most uses within a given module, the following shorthand suffices:
</p>
<div class="example"><pre>
-spec Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre></div>
<p>
Also, for documentation purposes, argument names can be given:
</p>
<div class="example"><pre>
-spec Function(ArgName1 :: Type1, ..., ArgNameN :: TypeN) -> RT.</pre></div>
<p>
A function specification can be overloaded.
That is, it can have several types, separated by a semicolon (<span class="code">;</span>):
</p>
<div class="example"><pre>
-spec foo(T1, T2) -> T3
; (T4, T5) -> T6.</pre></div>
<p>
A current restriction, which currently results in a warning
(OBS: not an error) by the compiler, is that the domains of
the argument types cannot be overlapping.
For example, the following specification results in a warning:
</p>
<div class="example"><pre>
-spec foo(pos_integer()) -> pos_integer()
; (integer()) -> integer().</pre></div>
<p>
Type variables can be used in specifications to specify relations for
the input and output arguments of a function.
For example, the following specification defines the type of a
polymorphic identity function:
</p>
<div class="example"><pre>
-spec id(X) -> X.</pre></div>
<p>
However, note that the above specification does not restrict the input
and output type in any way.
We can constrain these types by guard-like subtype constraints:
</p>
<div class="example"><pre>
-spec id(X) -> X when is_subtype(X, tuple()).</pre></div>
<p>
or equivalently by the more succinct and more modern form of the above:
</p>
<div class="example"><pre>
-spec id(X) -> X when X :: tuple().</pre></div>
<p>
and provide bounded quantification. Currently, the <span class="code">::</span> constraint
(the <span class="code">is_subtype/2</span> guard) is the only guard constraint which can
be used in the <span class="code">'when'</span> part of a <span class="code">'-spec'</span> attribute.
</p>
<p>
The scope of an <span class="code">::</span> constraint is the
<span class="code">(...) -> RetType</span>
specification after which it appears. To avoid confusion,
we suggest that different variables are used in different
constituents of an overloaded contract as in the example below:
</p>
<div class="example"><pre>
-spec foo({X, integer()}) -> X when X :: atom()
; ([Y]) -> Y when Y :: number().</pre></div>
<p>
Some functions in Erlang are not meant to return;
either because they define servers or because they are used to
throw exceptions as the function below:
</p>
<div class="example"><pre>
my_error(Err) -> erlang:throw({error, Err}).</pre></div>
<p>
For such functions we recommend the use of the special no_return()
type for their "return", via a contract of the form:
</p>
<div class="example"><pre>
-spec my_error(term()) -> no_return().</pre></div>
</div>
<div class="footer">
<hr>
<p>Copyright © 2003-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
122
