summaryrefslogtreecommitdiff
path: root/system/doc/reference_manual/typespec.xml
diff options
context:
space:
mode:
Diffstat (limited to 'system/doc/reference_manual/typespec.xml')
-rw-r--r--system/doc/reference_manual/typespec.xml56
1 files changed, 47 insertions, 9 deletions
diff --git a/system/doc/reference_manual/typespec.xml b/system/doc/reference_manual/typespec.xml
index 75482e5be1..8f3ba3b25a 100644
--- a/system/doc/reference_manual/typespec.xml
+++ b/system/doc/reference_manual/typespec.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2003</year><year>2022</year>
+ <year>2003</year><year>2023</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -83,17 +83,32 @@
</p>
<pre> atom() | integer()</pre>
<p>
- Because of subtype relations that exist between types, types
+ Because of subtype relations that exist between types, all types,
+ except <c>dynamic()</c>,
form a lattice where the top-most element, <c>any()</c>, denotes
the set of all Erlang terms and the bottom-most element, <c>none()</c>,
denotes the empty set of terms.
</p>
<p>
+ To facilitate <url href="https://en.wikipedia.org/wiki/Gradual_typing">
+ gradual typing</url> of Erlang, the type `dynamic()` is provided.
+ It is similar to
+ <url href="https://docs.python.org/3/library/typing.html#the-any-type">Any</url>
+ in Python,
+ <url href="https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any">any</url>
+ in TypeScript and
+ <url href="https://docs.hhvm.com/hack/built-in-types/dynamic">dynamic</url>
+ in Hack. `any()` and `dynamic()` interact with
+ <url href="https://learnyousomeerlang.com/dialyzer#success-typing">success typing</url>
+ the same way, so Dialyzer doesn't distinguish between them.
+ </p>
+ <p>
The set of predefined types and the syntax for types follows:
</p>
<pre><![CDATA[
Type :: any() %% The top type, the set of all Erlang terms
| none() %% The bottom type, contains no terms
+ | dynamic()
| pid()
| port()
| reference()
@@ -314,11 +329,6 @@
<tcaption>Additional built-in types</tcaption>
</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.
- </p>
<note>
<p>
The following built-in list types also exist,
@@ -345,7 +355,35 @@
This is described in <seeguide marker="#typeinrecords">
Type Information in Record Declarations</seeguide>.
</p>
+
+ <section>
+ <title>Redefining built-in types</title>
+ <change><p>
+ Starting from Erlang/OTP 26, is is permitted to define a type
+ having the same name as a built-in type.</p></change>
+ <p>It is recommended to
+ avoid deliberately reusing built-in names because it can be
+ confusing. However, when an Erlang/OTP release introduces a new
+ type, code that happened to define its own type having the same
+ name will continue to work.
+ </p>
+
+ <p>As an example, imagine that the Erlang/OTP 42 release introduces
+ a new type <c>gadget()</c> defined like this:</p>
+
+ <pre>
+ -type gadget() :: {'gadget', reference()}.</pre>
+
+ <p>Further imagine that some code has its own (different)
+ definition of <c>gadget()</c>, for example:</p>
+
+ <pre>
+ -type gadget() :: #{}.</pre>
+
+ <p>Since redefinitions are allowed, the code will still compile (but
+ with a warning), and Dialyzer will not emit any additional warnings.</p>
</section>
+</section>
<section>
<title>Type Declarations of User-Defined Types</title>
@@ -441,7 +479,7 @@
This is checked by the compiler and results in a compilation error
if a violation is detected.
</p>
- <note>
+ <change>
<p>Before Erlang/OTP 19, for fields without initial values,
the singleton type <c>'undefined'</c> was added to all declared types.
In other words, the following two record declarations had identical
@@ -458,7 +496,7 @@
This is no longer the case. If you require <c>'undefined'</c> in your record field
type, you must explicitly add it to the typespec, as in the 2nd example.
</p>
- </note>
+ </change>
<p>
Any record, containing type information or not, once defined,
can be used as a type using the following syntax: