<commit_before><?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2003</year><year>2014</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.

      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.

    </legalnotice>

    <title>Types and Function Specifications</title>
    <prepared><NAME>, <NAME>, <NAME></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
    <file>typespec.xml</file>
  </header>

  <section>
    <title>The Erlang Type Language</title>
    <p>
      Erlang is a dynamically typed language. Still, it comes with a
      notation 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 <c>Dialyzer</c>,
      and can be exploited by documentation tools such as <c>Edoc</c> 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 <c>@type</c> and
      <c>@spec</c> declarations used by <c>Edoc</c>.
    </p>
  </section>
  <section>
    <marker id="syntax"></marker>
    <title>Types and their Syntax</title>
    <p>
      Types describe sets of Erlang terms.
      Types consist and are built from a set of predefined types
      (e.g. <c>integer()</c>, <c>atom()</c>, <c>pid()</c>, ...)
      described below.
      Predefined types represent a typically infinite set of Erlang terms which
      belong to this type.  For example, the type <c>atom()</c> stands for the
      set of all Erlang atoms.
    </p>
    <p>
      For integers and atoms, we allow for singleton types (e.g. the integers
      <c>-1</c> and <c>42</c> or the atoms <c>'foo'</c> and <c>'bar'</c>).

      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>
    <pre>  atom() | 'bar' | integer() | 42</pre>
    <p>
      describes the same set of terms as the type union:
    </p>
    <pre>  atom() | integer()</pre>
    <p>
      Because of sub-type relations that exist between types, types
      form a lattice where the topmost 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>
      The set of predefined types and the syntax for types is given below:
    </p>
    <pre><![CDATA[
  Type :: any()                 %% The top type, the set of all Erlang terms
        | none()                %% The bottom type, contains no terms
        | pid()
        | port()
        | reference()
        | []                    %% nil
        | Atom
        | Bitstring
        | float()
        | Fun
        | Integer
        | List
        | Tuple
        | Union
        | UserDefined           %% described in Section 6.3

  Atom :: atom()
        | Erlang_Atom           %% 'foo', 'bar', ...

  Bitstring :: <<>>
             | <<_:M>>          %% M is a positive integer
             | <<_:_*N>>        %% N is a positive integer
             | <<_:M, _:_*N>>

  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)
        | maybe_improper_list(Type1, Type2)    %% Type1=contents, Type2=termination
        | nonempty_improper_list(Type1, Type2) %% Type1 and Type2 as above
        | nonempty_list(Type)                  %% Proper non-empty list

  Tuple :: tuple()                             %% stands for a tuple of any size
         | {}
         | {TList}

  TList :: Type
         | Type, TList

  Union :: Type1 | Type2
]]></pre>
  <p>
    The general form of bitstrings is <c>&lt;&lt;_:M, _:_*N&gt;&gt;</c>,
    where <c>M</c> and <c>N</c> are positive integers. It denotes a
    bitstring that is <c>M + (k*N)</c> bits long (i.e., a bitstring that
    starts with <c>M</c> bits and continues with <c>k</c> segments of
    <c>N</c> bits each, where <c>k</c> is also a positive integer).
    The notations <c>&lt;&lt;_:_*N&gt;&gt;</c>, <c>&lt;&lt;_:M&gt;&gt;</c>,
    and <c>&lt;&lt;&gt;&gt;</c> are convenient shorthands for the cases
    that <c>M</c>, <c>N</c>, or both, respectively, are zero.
  </p>
  <p>
    Because lists are commonly used, they have shorthand type notations. 
    The types <c>list(T)</c> and <c>nonempty_list(T)</c> have the shorthands
    <c>[T]</c> and <c>[T,...]</c>, respectively.
    The only difference between the two shorthands is that <c>[T]</c> may be an 
    empty list but <c>[T,...]</c> may not.
  </p>
  <p>
    Notice that the shorthand for <c>list()</c>, i.e. the list of
    elements of unknown type, is <c>[_]</c> (or <c>[any()]</c>), not <c>[]</c>. 
    The notation <c>[]</c> 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.
  </p>
  <table>
    <row>
      <cell><b>Built-in type</b></cell><cell><b>Defined as</b></cell>
    </row>
    <row>
      <cell><c>term()</c></cell><cell><c>any()</c></cell>
    </row>
    <row>
      <cell><c>binary()</c></cell><cell><c>&lt;&lt;_:_*8&gt;&gt;</c></cell>
    </row>
    <row>
      <cell><c>bitstring()</c></cell><cell><c>&lt;&lt;_:_*1&gt;&gt;</c></cell>
    </row>
    <row> 
      <cell><c>boolean()</c></cell><cell><c>'false' | 'true'</c></cell>
    </row>
    <row> 
      <cell><c>byte()</c></cell><cell><c>0..255</c></cell>
    </row>
    <row>
      <cell><c>char()</c></cell><cell><c>0..16#10ffff</c></cell>
    </row>
    <row> 
      <cell><c>number()</c></cell><cell><c>integer() | float()</c></cell>
    </row>
    <row> 
      <cell><c>list()</c></cell><cell><c>[any()]</c></cell>
    </row>
    <row> 
      <cell><c>maybe_improper_list()</c></cell><cell><c>maybe_improper_list(any(), any())</c></cell>
    </row>
    <row> 
      <cell><c>nonempty_list()</c></cell><cell><c>nonempty_list(any())</c></cell>
    </row>
    <row>
      <cell><c>string()</c></cell><cell><c>[char()]</c></cell>
    </row>
    <row> 
      <cell><c>nonempty_string()</c></cell><cell><c>[char(),...]</c></cell>
    </row>
    <row> 
      <cell><c>iodata()</c></cell><cell><c>iolist() | binary()</c></cell>
    </row>
    <row>
      <cell><c>iolist()</c></cell><cell><c>maybe_improper_list(byte() | binary() | iolist(), binary() | [])</c></cell>
    </row>
    <row>
      <cell><c>module()</c></cell><cell><c>atom()</c></cell>
    </row>
    <row> 
      <cell><c>mfa()</c></cell><cell><c>{atom(),atom(),arity()}</c></cell>
    </row>
    <row>
      <cell><c>arity()</c></cell><cell><c>0..255</c></cell>
    </row>
    <row>
      <cell><c>node()</c></cell><cell><c>atom()</c></cell>
    </row>
    <row>
      <cell><c>timeout()</c></cell><cell><c>'infinity' | non_neg_integer()</c></cell>
    </row>
    <row>
      <cell><c>no_return()</c></cell><cell><c>none()</c></cell> 
    </row>
  </table>
  <p>
  In addition, the following three built-in types exist and can be
  thought as defined below, though strictly their "type definition" is
  not valid syntax according to the type language defined above.
  </p>
  <table>
    <row>
      <cell><b>Built-in type</b></cell><cell><b>Could be thought defined by the syntax</b></cell>
    </row>
    <row>
      <cell><c>non_neg_integer()</c></cell><cell><c>0..</c></cell>
    </row>
    <row>
      <cell><c>pos_integer()</c></cell><cell><c>1..</c></cell>
    </row>
    <row>
      <cell><c>neg_integer()</c></cell><cell><c>..-1</c></cell>
    </row>
  </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>
    The following built-in list types also exist, 
    but they are expected to be rarely used. Hence, they have long names:
  </note>
  <pre>
  nonempty_maybe_improper_list() :: nonempty_maybe_improper_list(any(), any())
  nonempty_improper_list(Type1, Type2)
  nonempty_maybe_improper_list(Type1, Type2)</pre>
  <p>
    where the last two types
    define the set of Erlang terms one would expect.
  </p>
  <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>
  <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.
  </p>
  </section>
  
  <section>
    <title>Type declarations of user-defined types</title>
    <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>
    <pre>
  -type my_struct_type() :: Type.
  -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
      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<commit_msg>doc: Descripe Maps type syntax<commit_after><?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2003</year><year>2014</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.

      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.

    </legalnotice>

    <title>Types and Function Specifications</title>
    <prepared><NAME>, <NAME>, <NAME></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
    <file>typespec.xml</file>
  </header>

  <section>
    <title>The Erlang Type Language</title>
    <p>
      Erlang is a dynamically typed language. Still, it comes with a
      notation 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 <c>Dialyzer</c>,
      and can be exploited by documentation tools such as <c>Edoc</c> 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 <c>@type</c> and
      <c>@spec</c> declarations used by <c>Edoc</c>.
    </p>
  </section>
  <section>
    <marker id="syntax"></marker>
    <title>Types and their Syntax</title>
    <p>
      Types describe sets of Erlang terms.
      Types consist and are built from a set of predefined types
      (e.g. <c>integer()</c>, <c>atom()</c>, <c>pid()</c>, ...)
      described below.
      Predefined types represent a typically infinite set of Erlang terms which
      belong to this type.  For example, the type <c>atom()</c> stands for the
      set of all Erlang atoms.
    </p>
    <p>
      For integers and atoms, we allow for singleton types (e.g. the integers
      <c>-1</c> and <c>42</c> or the atoms <c>'foo'</c> and <c>'bar'</c>).

      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>
    <pre>  atom() | 'bar' | integer() | 42</pre>
    <p>
      describes the same set of terms as the type union:
    </p>
    <pre>  atom() | integer()</pre>
    <p>
      Because of sub-type relations that exist between types, types
      form a lattice where the topmost 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>
      The set of predefined types and the syntax for types is given below:
    </p>
    <pre><![CDATA[
  Type :: any()                 %% The top type, the set of all Erlang terms
        | none()                %% The bottom type, contains no terms
        | pid()
        | port()
        | reference()
        | []                    %% nil
        | Atom
        | Bitstring
        | float()
        | Fun
        | Integer
        | List
        | Map
        | Tuple
        | Union
        | UserDefined           %% described in Section 6.3

  Atom :: atom()
        | Erlang_Atom           %% 'foo', 'bar', ...

  Bitstring :: <<>>
             | <<_:M>>          %% M is a positive integer
             | <<_:_*N>>        %% N is a positive integer
             | <<_:M, _:_*N>>

  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)
        | maybe_improper_list(Type1, Type2)    %% Type1=contents, Type2=termination
        | nonempty_improper_list(Type1, Type2) %% Type1 and Type2 as above
        | nonempty_list(Type)                  %% Proper non-empty list

  Map :: map()                                 %% stands for a map of any size
       | #{}                                   %% stands for a map of any size
       | #{PairList}

  Tuple :: tuple()                             %% stands for a tuple of any size
         | {}
         | {TList}

  PairList :: Type => Type
            | Type => Type, PairList

  TList :: Type
         | Type, TList

  Union :: Type1 | Type2
]]></pre>
  <p>
    The general form of bitstrings is <c>&lt;&lt;_:M, _:_*N&gt;&gt;</c>,
    where <c>M</c> and <c>N</c> are positive integers. It denotes a
    bitstring that is <c>M + (k*N)</c> bits long (i.e., a bitstring that
    starts with <c>M</c> bits and continues with <c>k</c> segments of
    <c>N</c> bits each, where <c>k</c> is also a positive integer).
    The notations <c>&lt;&lt;_:_*N&gt;&gt;</c>, <c>&lt;&lt;_:M&gt;&gt;</c>,
    and <c>&lt;&lt;&gt;&gt;</c> are convenient shorthands for the cases
    that <c>M</c>, <c>N</c>, or both, respectively, are zero.
  </p>
  <p>
    Because lists are commonly used, they have shorthand type notations. 
    The types <c>list(T)</c> and <c>nonempty_list(T)</c> have the shorthands
    <c>[T]</c> and <c>[T,...]</c>, respectively.
    The only difference between the two shorthands is that <c>[T]</c> may be an 
    empty list but <c>[T,...]</c> may not.
  </p>
  <p>
    Notice that the shorthand for <c>list()</c>, i.e. the list of
    elements of unknown type, is <c>[_]</c> (or <c>[any()]</c>), not <c>[]</c>. 
    The notation <c>[]</c> 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.
  </p>
  <table>
    <row>
      <cell><b>Built-in type</b></cell><cell><b>Defined as</b></cell>
    </row>
    <row>
      <cell><c>term()</c></cell><cell><c>any()</c></cell>
    </row>
    <row>
      <cell><c>binary()</c></cell><cell><c>&lt;&lt;_:_*8&gt;&gt;</c></cell>
    </row>
    <row>
      <cell><c>bitstring()</c></cell><cell><c>&lt;&lt;_:_*1&gt;&gt;</c></cell>
    </row>
    <row> 
      <cell><c>boolean()</c></cell><cell><c>'false' | 'true'</c></cell>
    </row>
    <row> 
      <cell><c>byte()</c></cell><cell><c>0..255</c></cell>
    </row>
    <row>
      <cell><c>char()</c></cell><cell><c>0..16#10ffff</c></cell>
    </row>
    <row> 
      <cell><c>number()</c></cell><cell><c>integer() | float()</c></cell>
    </row>
    <row> 
      <cell><c>list()</c></cell><cell><c>[any()]</c></cell>
    </row>
    <row> 
      <cell><c>maybe_improper_list()</c></cell><cell><c>maybe_improper_list(any(), any())</c></cell>
    </row>
    <row> 
      <cell><c>nonempty_list()</c></cell><cell><c>nonempty_list(any())</c></cell>
    </row>
    <row>
      <cell><c>string()</c></cell><cell><c>[char()]</c></cell>
    </row>
    <row> 
      <cell><c>nonempty_string()</c></cell><cell><c>[char(),...]</c></cell>
    </row>
    <row> 
      <cell><c>iodata()</c></cell><cell><c>iolist() | binary()</c></cell>
    </row>
    <row>
      <cell><c>iolist()</c></cell><cell><c>maybe_improper_list(byte() | binary() | iolist(), binary() | [])</c></cell>
    </row>
    <row>
      <cell><c>module()</c></cell><cell><c>atom()</c></cell>
    </row>
    <row> 
      <cell><c>mfa()</c></cell><cell><c>{atom(),atom(),arity()}</c></cell>
    </row>
    <row>
      <cell><c>arity()</c></cell><cell><c>0..255</c></cell>
    </row>
    <row>
      <cell><c>node()</c></cell><cell><c>atom()</c></cell>
    </row>
    <row>
      <cell><c>timeout()</c></cell><cell><c>'infinity' | non_neg_integer()</c></cell>
    </row>
    <row>
      <cell><c>no_return()</c></cell><cell><c>none()</c></cell> 
    </row>
  </table>
  <p>
  In addition, the following three built-in types exist and can be
  thought as defined below, though strictly their "type definition" is
  not valid syntax according to the type language defined above.
  </p>
  <table>
    <row>
      <cell><b>Built-in type</b></cell><cell><b>Could be thought defined by the syntax</b></cell>
    </row>
    <row>
      <cell><c>non_neg_integer()</c></cell><cell><c>0..</c></cell>
    </row>
    <row>
      <cell><c>pos_integer()</c></cell><cell><c>1..</c></cell>
    </row>
    <row>
      <cell><c>neg_integer()</c></cell><cell><c>..-1</c></cell>
    </row>
  </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>
    The following built-in list types also exist, 
    but they are expected to be rarely used. Hence, they have long names:
  </note>
  <pre>
  nonempty_maybe_improper_list() :: nonempty_maybe_improper_list(any(), any())
  nonempty_improper_list(Type1, Type2)
  nonempty_maybe_improper_list(Type1, Type2)</pre>
  <p>
    where the last two types
    define the set of Erlang terms one would expect.
  </p>
  <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>
  <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.
  </p>
  <note>
	  <p>Map types, both <c>map()</c> and <c>#{ ... }</c>, are considered experimental during OTP 17.</p>
	  <p>No type information of maps pairs, only the containing map types, are used by Dialyzer in OTP 17.</p>
  </note>
  </section>
  
  <section>
    <title>Type declarations of user-defined types</title>
    <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>
    <pre>
  -type my_struct_type() :: Type.
  -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
      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
{'fraction_non_alphanumeric': 0.15598873912301656, 'fraction_numerical': 0.005033270772905648, 'mean_word_length': 2.5076301615798924, 'pattern_counts': {'":': 0, '<': 895, '<?xml version=': 2, '>': 903, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 3, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5513484', 'n_tokens_mistral': 7728, 'n_tokens_neox': 7346, 'n_words': 2454}