aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/reference_manual
diff options
context:
space:
mode:
authorHans Bolinder <[email protected]>2010-09-07 12:18:50 +0200
committerHans Bolinder <[email protected]>2010-09-07 12:18:50 +0200
commit5d41b3bfce72ab583dd3c25c543ffe568a1696c5 (patch)
tree0c40cb8d9650979d9572c5d46c5ed3887e8e06de /system/doc/reference_manual
parent730bb4644985cdcb163b9b32f90c4f0fc133c57e (diff)
downloadotp-5d41b3bfce72ab583dd3c25c543ffe568a1696c5.tar.gz
otp-5d41b3bfce72ab583dd3c25c543ffe568a1696c5.tar.bz2
otp-5d41b3bfce72ab583dd3c25c543ffe568a1696c5.zip
Update the Types and Function Specifications chapter in the Reference Manual.
The latest additions to the extension of Erlang used for describing types and specifications have been documented. There are new compiler attributes such as -opaque and -export_all as well as an alternative syntax for subtype constraints ('::' instead of is_subtype/2).
Diffstat (limited to 'system/doc/reference_manual')
-rwxr-xr-xsystem/doc/reference_manual/typespec.xml90
1 files changed, 30 insertions, 60 deletions
diff --git a/system/doc/reference_manual/typespec.xml b/system/doc/reference_manual/typespec.xml
index 29ec2ad78b..f08639f9a1 100755
--- a/system/doc/reference_manual/typespec.xml
+++ b/system/doc/reference_manual/typespec.xml
@@ -50,11 +50,6 @@
supersede and replace the purely comment-based <c>@type</c> and
<c>@spec</c> declarations used by <c>Edoc</c>.
</p>
- <warning>
- The syntax and semantics described here is still preliminary and might be
- slightly changed and extended before it becomes officially supported.
- The plan is that this will happen in R14B.
- </warning>
</section>
<section>
<marker id="syntax"></marker>
@@ -165,7 +160,7 @@ TList :: Type
<cell><c>term()</c></cell><cell><c>any()</c></cell>
</row>
<row>
- <cell><c>bool()</c></cell><cell><c>'false' | 'true'</c></cell>
+ <cell><c>boolean()</c></cell><cell><c>'false' | 'true'</c></cell>
</row>
<row>
<cell><c>byte()</c></cell><cell><c>0..255</c></cell>
@@ -233,24 +228,21 @@ TList :: Type
</note>
<pre>
nonempty_maybe_improper_list(Type) :: nonempty_maybe_improper_list(Type, any())
-nonempty_maybe_improper_list() :: nonempty_maybe_improper_list(any())
- </pre>
+nonempty_maybe_improper_list() :: nonempty_maybe_improper_list(any())</pre>
<p>
where the following two types
define the set of Erlang terms one would expect:
</p>
<pre>
nonempty_improper_list(Type1, Type2)
-nonempty_maybe_improper_list(Type1, Type2)
- </pre>
+nonempty_maybe_improper_list(Type1, Type2)</pre>
<p>
Also for convenience, we allow for record notation to be used.
Records are just shorthands for the corresponding tuples.
</p>
<pre>
Record :: #Erlang_Atom{}
- | #Erlang_Atom{Fields}
- </pre>
+ | #Erlang_Atom{Fields}</pre>
<p>
Records have been extended to possibly contain type information.
This is described in the sub-section <seealso marker="#typeinrecords">"Type information in record declarations"</seealso> below.
@@ -266,8 +258,7 @@ Record :: #Erlang_Atom{}
</p>
<pre>
-type my_struct_type() :: Type.
--opaque my_opaq_type() :: Type.
- </pre>
+-opaque my_opaq_type() :: Type.</pre>
<p>
where the type name is an atom (<c>'my_struct_type'</c> in the above)
followed by parentheses. Type is a type as defined in the
@@ -288,27 +279,23 @@ Record :: #Erlang_Atom{}
definition. A concrete example appears below:
</p>
<pre>
--type orddict(Key, Val) :: [{Key, Val}].
- </pre>
+-type orddict(Key, Val) :: [{Key, Val}].</pre>
<p>
A module can export some types in order to declare that other modules
are allowed to refer to them as <em>remote types</em>.
This declaration has the following form:
<pre>
--export_type([T1/A1, ..., Tk/Ak]).
- </pre>
+-export_type([T1/A1, ..., Tk/Ak]).</pre>
where the Ti's are atoms (the name of the type) and the Ai's are their
arguments. An example is given below:
<pre>
--export_type([my_struct_type/0, orddict/2]).
- </pre>
+-export_type([my_struct_type/0, orddict/2]).</pre>
Assuming that these types are exported from module <c>'mod'</c> then
one can refer to them from other modules using remote type expressions
like those below:
<pre>
mod:my_struct_type()
-mod:orddict(atom(), term())
- </pre>
+mod:orddict(atom(), term())</pre>
One is not allowed to refer to types which are not declared as exported.
</p>
<p>
@@ -324,30 +311,25 @@ mod:orddict(atom(), term())
<marker id="typeinrecords"/>
<section>
- <title>
- Type information in record declarations
- </title>
+ <title>Type information in record declarations</title>
<p>
The types of record fields can be specified in the declaration of the
record. The syntax for this is:
</p>
<pre>
--record(rec, {field1 :: Type1, field2, field3 :: Type3}).
- </pre>
+-record(rec, {field1 :: Type1, field2, field3 :: Type3}).</pre>
<p>
For fields without type annotations, their type defaults to any().
I.e., the above is a shorthand for:
</p>
<pre>
--record(rec, {field1 :: Type1, field2 :: any(), field3 :: Type3}).
- </pre>
+-record(rec, {field1 :: Type1, field2 :: any(), field3 :: Type3}).</pre>
<p>
In the presence of initial values for fields,
the type must be declared after the initialization as in the following:
</p>
<pre>
--record(rec, {field1 = [] :: Type1, field2, field3 = 42 :: Type3}).
- </pre>
+-record(rec, {field1 = [] :: Type1, field2, field3 = 42 :: Type3}).</pre>
<p>
Naturally, the initial values for fields should be compatible
with (i.e. a member of) the corresponding types.
@@ -364,8 +346,7 @@ mod:orddict(atom(), term())
-record(rec, {f1 = 42 :: integer(),
f2 :: 'undefined' | float(),
- f3 :: 'undefined' | 'a' | 'b'}).
- </pre>
+ f3 :: 'undefined' | 'a' | 'b'}).</pre>
<p>
For this reason, it is recommended that records contain initializers,
whenever possible.
@@ -375,16 +356,14 @@ mod:orddict(atom(), term())
can be used as a type using the syntax:
</p>
<pre>
-#rec{}
- </pre>
+#rec{}</pre>
<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>
<pre>
-#rec{some_field :: Type}
- </pre>
+#rec{some_field :: Type}</pre>
<p>
Any unspecified fields are assumed to have the type in the original
record declaration.
@@ -398,8 +377,7 @@ mod:orddict(atom(), term())
compiler attribute <c>'-spec'</c>. The general format is as follows:
</p>
<pre>
--spec Module:Function(ArgType1, ..., ArgTypeN) -> ReturnType.
- </pre>
+-spec Module:Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre>
<p>
The arity of the function has to match the number of arguments,
or else a compilation error occurs.
@@ -414,22 +392,19 @@ mod:orddict(atom(), term())
For most uses within a given module, the following shorthand suffices:
</p>
<pre>
--spec Function(ArgType1, ..., ArgTypeN) -> ReturnType.
- </pre>
+-spec Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre>
<p>
Also, for documentation purposes, argument names can be given:
</p>
<pre>
--spec Function(ArgName1 :: Type1, ..., ArgNameN :: TypeN) -> RT.
- </pre>
+-spec Function(ArgName1 :: Type1, ..., ArgNameN :: TypeN) -> RT.</pre>
<p>
A function specification can be overloaded.
That is, it can have several types, separated by a semicolon (<c>;</c>):
</p>
<pre>
-spec foo(T1, T2) -> T3
- ; (T4, T5) -> T6.
- </pre>
+ ; (T4, T5) -> T6.</pre>
<p>
A current restriction, which currently results in a warning
(OBS: not an error) by the compiler, is that the domains of
@@ -438,8 +413,7 @@ mod:orddict(atom(), term())
</p>
<pre>
-spec foo(pos_integer()) -> pos_integer()
- ; (integer()) -> integer().
- </pre>
+ ; (integer()) -> integer().</pre>
<p>
Type variables can be used in specifications to specify relations for
the input and output arguments of a function.
@@ -447,20 +421,19 @@ mod:orddict(atom(), term())
polymorphic identity function:
</p>
<pre>
--spec id(X) -> X.
- </pre>
+-spec id(X) -> X.</pre>
<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>
<pre>
--spec id(X) -> X when is_subtype(X, tuple()).
- </pre>
- or equivalently by the more succint and more modern form of the above:
+-spec id(X) -> X when is_subtype(X, tuple()).</pre>
+ <p>
+ or equivalently by the more succinct and more modern form of the above:
+ </p>
<pre>
--spec id(X) -> X when X :: tuple().
- </pre>
+-spec id(X) -> X when X :: tuple().</pre>
<p>
and provide bounded quantification. Currently, the <c>::</c> constraint
(the <c>is_subtype/2</c> guard) is the only guard constraint which can
@@ -475,23 +448,20 @@ mod:orddict(atom(), term())
</p>
<pre>
-spec foo({X, integer()}) -> X when X :: atom()
- ; ([Y]) -> Y when Y :: number().
- </pre>
+ ; ([Y]) -> Y when Y :: number().</pre>
<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>
<pre>
-my_error(Err) -> erlang:throw({error, Err}).
- </pre>
+my_error(Err) -> erlang:throw({error, Err}).</pre>
<p>
For such functions we recommend the use of the special no_return()
type for their "return", via a contract of the form:
</p>
<pre>
--spec my_error(term()) -> no_return().
- </pre>
+-spec my_error(term()) -> no_return().</pre>
</section>
</chapter>