diff options
Diffstat (limited to 'system/doc/reference_manual/typespec.xml')
| -rw-r--r-- | system/doc/reference_manual/typespec.xml | 56 |
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: |