Merge branch 'egil/maps-doc'

* egil/maps-doc:
  doc: Add Maps example for sequential programming
  doc: Mention map expressions and map guards
  doc: Add maps to reference manual
  edoc: Add map/0 as a new predefined type
  doc: Descripe Maps type syntax
  doc: Clearify language of user-defined attributes
  doc: Document Maps datatype in reference manual
  erts: Document map guard functions
  erts: Fix is_map/1 spec

8 files changed, 454 insertions, 5 deletions

diff --git a/system/doc/getting_started/seq_prog.xml b/system/doc/getting_started/seq_prog.xml
index 3830a34e5a..fd49102263 100644
--- a/system/doc/getting_started/seq_prog.xml
+++ b/system/doc/getting_started/seq_prog.xml
@@ -419,6 +419,129 @@ list_length([First | Rest]) ->
   </section>
 
   <section>
+    <title>Maps</title>
+	<p>Maps are a set of key to value associations. These associations
+		are encapsulated with "#{" and "}". To create an association from
+		"key" to value 42, we write:</p>
+<code type="none">
+> #{ "key" => 42 }.
+#{"key" => 42}</code>
+    <p>We will jump straight into the deep end with an example using some
+		interesting features.</p>
+	<p>The following example shows how we calculate alpha blending using
+		maps to reference color and alpha channels:</p>
+    <code type="none">
+-module(color).
+
+-export([new/4, blend/2]).
+
+-define(is_channel(V), (is_float(V) andalso V &gt;= 0.0 andalso V =&lt; 1.0)).
+
+new(R,G,B,A) when ?is_channel(R), ?is_channel(G),
+                  ?is_channel(B), ?is_channel(A) ->
+    #{red =&gt; R, green =&gt; G, blue =&gt; B, alpha =&gt; A}.
+
+blend(Src,Dst) ->
+    blend(Src,Dst,alpha(Src,Dst)).
+
+blend(Src,Dst,Alpha) when Alpha > 0.0 ->
+    Dst#{
+        red   := red(Src,Dst) / Alpha,
+        green := green(Src,Dst) / Alpha,
+        blue  := blue(Src,Dst) / Alpha,
+        alpha := Alpha
+    };
+blend(_,Dst,_) ->
+    Dst#{
+        red   := 0.0,
+        green := 0.0,
+        blue  := 0.0,
+        alpha := 0.0
+    }.
+
+alpha(#{alpha := SA}, #{alpha := DA}) ->
+    SA + DA*(1.0 - SA).
+
+red(#{red := SV, alpha := SA}, #{red := DV, alpha := DA}) ->
+    SV*SA + DV*DA*(1.0 - SA).
+green(#{green := SV, alpha := SA}, #{green := DV, alpha := DA}) ->
+    SV*SA + DV*DA*(1.0 - SA).
+blue(#{blue := SV, alpha := SA}, #{blue := DV, alpha := DA}) ->
+    SV*SA + DV*DA*(1.0 - SA).</code>
+    <p>Compile (file <c>color.erl</c>) and test:</p>
+    <pre>
+> <input>c(color).</input>
+{ok,color}
+> <input>C1 = color:new(0.3,0.4,0.5,1.0).</input>
+#{alpha => 1.0,blue => 0.5,green => 0.4,red => 0.3}
+> <input>C2 = color:new(1.0,0.8,0.1,0.3).</input>
+#{alpha => 0.3,blue => 0.1,green => 0.8,red => 1.0}
+> <input>color:blend(C1,C2).</input>
+#{alpha => 1.0,blue => 0.5,green => 0.4,red => 0.3}
+> <input>color:blend(C2,C1).</input>
+#{alpha => 1.0,blue => 0.38,green => 0.52,red => 0.51}
+</pre>
+    <p>This example warrant some explanation:</p>
+    <code type="none">
+-define(is_channel(V), (is_float(V) andalso V &gt;= 0.0 andalso V =&lt; 1.0)).</code>
+    <p>
+		First we define a macro <c>is_channel</c> to help with our guard tests.
+		This is only here for convenience and to reduce syntax cluttering.
+
+		You can read more about <seealso marker="doc/reference_manual:macros">Macros</seealso>
+		in the Erlang Reference Manual.
+	</p>
+    <code type="none">
+new(R,G,B,A) when ?is_channel(R), ?is_channel(G),
+                  ?is_channel(B), ?is_channel(A) ->
+    #{red =&gt; R, green =&gt; G, blue =&gt; B, alpha =&gt; A}.</code>
+    <p>
+		The function <c>new/4</c> creates a new map term with and lets the keys
+		<c>red</c>, <c>green</c>, <c>blue</c> and <c>alpha</c> be associated
+		with an initial value. In this case we only allow for float
+		values between and including 0.0 and 1.0 as ensured by the <c>?is_channel/1</c> macro
+		for each argument. Only the <c>=></c> operator is allowed when creating a new map.
+    </p>
+	<p>
+		By calling <c>blend/2</c> on any color term created by <c>new/4</c> we can calculate
+		the resulting color as determined by the two maps terms.
+	</p>
+	<p>
+		The first thing <c>blend/2</c> does is to calculate the resulting alpha channel.
+	</p>
+    <code type="none">
+alpha(#{alpha := SA}, #{alpha := DA}) ->
+    SA + DA*(1.0 - SA).</code>
+    <p>
+		We fetch the value associated with key <c>alpha</c> for both arguments using
+		the <c>:=</c> operator. Any other keys
+		in the map are ignored, only the key <c>alpha</c> is required and checked for.
+	</p>
+	<p>This is also the case for functions <c>red/2</c>, <c>blue/2</c> and <c>green/2</c>.</p>
+    <code type="none">
+red(#{red := SV, alpha := SA}, #{red := DV, alpha := DA}) ->
+    SV*SA + DV*DA*(1.0 - SA).</code>
+    <p>
+		The difference here is that we check for two keys in each map argument. The other keys
+		are ignored.
+	</p>
+    <p>
+		Finally we return the resulting color in <c>blend/3</c>.
+	</p>
+    <code type="none">
+blend(Src,Dst,Alpha) when Alpha > 0.0 ->
+    Dst#{
+        red   := red(Src,Dst) / Alpha,
+        green := green(Src,Dst) / Alpha,
+        blue  := blue(Src,Dst) / Alpha,
+        alpha := Alpha
+    };</code>
+    <p>
+		We update the <c>Dst</c> map with new channel values. The syntax for updating an existing key with a new value is done with <c>:=</c> operator.
+	</p>
+  </section>
+
+  <section>
     <title>Standard Modules and Manual Pages</title>
     <p>Erlang has a lot of standard modules to help you do things. For
       example, the module <c>io</c> contains a lot of functions to help
diff --git a/system/doc/reference_manual/data_types.xml b/system/doc/reference_manual/data_types.xml
index 8c690d6b86..0031664dfb 100644
--- a/system/doc/reference_manual/data_types.xml
+++ b/system/doc/reference_manual/data_types.xml
@@ -190,6 +190,38 @@ adam
   </section>
 
   <section>
+    <title>Map</title>
+    <p>Compound data type with a variable number of key-value associations:</p>
+    <pre>
+#{Key1=>Value1,...,KeyN=>ValueN}</pre>
+	<p>Each key-value association in the map is called an
+		<em>association pair</em>. The key and value parts of the pair are
+		called <em>elements</em>. The number of association pairs is said to be
+      the <em>size</em> of the map.</p>
+    <p>There exists a number of BIFs to manipulate maps.</p>
+    <p>Examples:</p>
+    <pre>
+1> <input>M1 = #{name=>adam,age=>24,date=>{july,29}}.</input>
+#{age => 24,date => {july,29},name => adam}
+2> <input>maps:get(name,M1).</input>
+adam
+3> <input>maps:get(date,M1).</input>
+{july,29}
+4> <input>M2 = maps:update(age,25,M1).</input>
+#{age => 25,date => {july,29},name => adam}
+5> <input>map_size(M).</input>
+3
+6> <input>map_size(#{}).</input>
+0</pre>
+    <p>A collection of maps processing functions can be found in
+	the STDLIB module <seealso marker="stdlib:maps"><c>maps</c></seealso>.</p>
+    <p>Read more about <seealso marker="maps">Maps</seealso>.</p>
+  <note>
+	  <p>Maps are considered experimental during OTP 17.</p>
+  </note>
+  </section>
+
+  <section>
     <title>List</title>
     <p>Compound data type with a variable number of terms.</p>
     <pre>
diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml
index e9de3e006e..37208710fe 100644
--- a/system/doc/reference_manual/expressions.xml
+++ b/system/doc/reference_manual/expressions.xml
@@ -56,7 +56,7 @@ Expr1 + Expr2</code>
     <marker id="term"></marker>
     <title>Terms</title>
     <p>The simplest form of expression is a term, that is an integer,
-      float, atom, string, list or tuple.
+      float, atom, string, list, map or tuple.
       The return value is the term itself.</p>
   </section>
 
@@ -1348,6 +1348,9 @@ end</pre>
         <cell align="left" valign="middle"><c>is_list/1</c></cell>
       </row>
       <row>
+        <cell align="left" valign="middle"><c>is_map/1</c></cell>
+      </row>
+      <row>
         <cell align="left" valign="middle"><c>is_number/1</c></cell>
       </row>
       <row>
@@ -1398,6 +1401,9 @@ end</pre>
         <cell align="left" valign="middle"><c>length(List)</c></cell>
       </row>
       <row>
+        <cell align="left" valign="middle"><c>map_size(Map)</c></cell>
+      </row>
+      <row>
         <cell align="left" valign="middle"><c>node()</c></cell>
       </row>
       <row>
diff --git a/system/doc/reference_manual/maps.xml b/system/doc/reference_manual/maps.xml
new file mode 100644
index 0000000000..78808ce4a2
--- /dev/null
+++ b/system/doc/reference_manual/maps.xml
@@ -0,0 +1,274 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <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>Maps</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+    <file>maps.xml</file>
+  </header>
+
+  <note>
+	  <p>Maps are considered experimental during OTP 17 and may be subject to change.</p>
+	  <p>The documentation below describes it being possible to use arbitrary
+		  expressions or variables as keys, this is <em>NOT</em> implemented in the current
+		  version of Erlang/OTP.</p>
+	  <p>Exceptions returns <c>badarg</c> instead of <c>badmap</c>, this will change in
+		  the future releases.</p>
+  </note>
+
+  <section>
+	  <title>Creating Maps</title>
+	  <p>
+		  Constructing a new map is done by letting an expression <c>K</c> be associated with
+		  another expression <c>V</c>:
+	  </p>
+	  <code>#{ K => V }</code>
+	  <p>
+		  New maps may include multiple associations at construction by listing every
+		  association:
+	  </p>
+	  <code>#{ K1 => V1, .., Kn => Vn }</code>
+	  <p>
+		  An empty map is constructed by not associating any terms with each other:
+	  </p>
+	  <code>#{}</code>
+	  <p>
+		  All keys and values in the map are terms. Any expression is first evaluated and
+		  then the resulting terms are used as <em>key</em> and <em>value</em> respectively.
+	  </p>
+	  <p>
+		  Keys and values are separated by the <c>=></c> arrow and associations are
+		  separated by <c>,</c>.
+	  </p>
+
+	  <p>
+		  Examples:
+	  </p>
+	  <code>
+M0 = #{},                 % empty map
+M1 = #{a => &lt;&lt;"hello"&gt;&gt;}, % single association with literals
+M2 = #{1 => 2, b => b},   % multiple associations with literals
+M3 = #{k => {A,B}},       % single association with variables
+M4 = #{{"w", 1} => f()}.  % compound key associated with an evaluated expression</code>
+	  <p>
+		  where, <c>A</c> and <c>B</c> are any expressions and <c>M0</c> through <c>M4</c>
+		  are the resulting map terms.
+	  </p>
+	  <p>
+		  If two matching keys are declared, the latter key will take precedence.
+	  </p>
+	  <p>
+		  Example:
+	  </p>
+
+<pre>
+1> <input>#{1 => a, 1 => b}.</input>
+#{1 => b }
+2> <input>#{1.0 => a, 1 => b}.</input>
+#{1 => b, 1.0 => a}
+</pre>
+	  <p>
+		  The order in which the expressions constructing the keys and their
+		  associated values are evaluated is not defined. The syntactic order of
+		  the key-value pairs in the construction is of no relevance, except in
+		  the above mentioned case of two matching keys.
+	  </p>
+  </section>
+
+  <section>
+	  <title>Updating Maps</title>
+	  <p>
+		  Updating a map has similar syntax as constructing it.
+	  </p>
+	  <p>
+		  An expression defining the map to be updated is put in front of the expression
+		  defining the keys to be updated and their respective values.
+	  </p>
+	  <code>M#{ K => V }</code>
+	  <p>
+		  where <c>M</c> is a term of type map and <c>K</c> and <c>V</c> are any expression.
+	  </p>
+	  <p>
+		  If key <c>K</c> does not match any existing key in the map, a new association
+		  will be created from key <c>K</c> to value <c>V</c>.  If key <c>K</c> matches
+		  an existing key in map <c>M</c> its associated value will be replaced by the
+		  new value <c>V</c>. In both cases the evaluated map expression will return a new map.
+	  </p>
+	  <p>
+		  If <c>M</c> is not of type map an exception of type <c>badmap</c> is thrown.
+	  </p>
+	  <p>
+		  To only update an existing value, the following syntax is used,
+	  </p>
+	  <code>M#{ K := V } </code>
+	  <p>
+		  where <c>M</c> is an term of type map, <c>V</c> is an expression and <c>K</c>
+		  is an expression which evaluates to an existing key in <c>M</c>.
+	  </p>
+	  <p>
+		  If key <c>K</c> does not match any existing keys in map <c>M</c> an exception
+		  of type <c>badarg</c> will be triggered at runtime. If a matching key <c>K</c>
+		  is present in map <c>M</c> its associated value will be replaced by the new
+		  value <c>V</c> and the evaluated map expression returns a new map.
+	  </p>
+	  <p>
+		  If <c>M</c> is not of type map an exception of type <c>badmap</c> is thrown.
+	  </p>
+	  <p>
+		  Examples:
+	  </p>
+	  <code>
+M0 = #{},
+M1 = M0#{a => 0},
+M2 = M1#{a => 1, b => 2},
+M3 = M2#{"function" => fun() -> f() end},
+M4 = M3#{a := 2, b := 3}.  % 'a' and 'b' was added in `M1` and `M2`.</code>
+	  <p>
+		  where <c>M0</c> is any map. It follows that <c>M1 .. M4</c> are maps as well.
+	  </p>
+	  <p>
+		  More Examples:
+	  </p>
+<pre>
+1> <input>M = #{1 => a}.</input>
+#{1 => a }
+2> <input>M#{1.0 => b}.</input>
+#{1 => a, 1.0 => b}.
+3> <input>M#{1 := b}.</input>
+#{1 => b}
+4> <input>M#{1.0 := b}.</input>
+** exception error: bad argument
+</pre>
+	  <p>
+		  As in construction, the order in which the key and value expressions
+		  are evaluated is not defined. The
+		  syntactic order of the key-value pairs in the update is of no
+		  relevance, except in the case where two keys match, in which
+		  case the latter value is used.
+	  </p>
+  </section>
+
+  <section>
+	  <title>Maps in Patterns</title>
+	  <p>
+		  Matching of key-value associations from maps is done in the following way:
+	  </p>
+
+	  <code>#{ K := V } = M</code>
+	  <p>
+		  where <c>M</c> is any map. The key <c>K</c> has to be an expression with bound
+		  variables or a literals, and <c>V</c> can be any pattern with either bound or
+		  unbound variables.
+	  </p>
+	  <p>
+		  If the variable <c>V</c> is unbound, it will be bound to the value associated
+		  with the key <c>K</c>, which has to exist in the map <c>M</c>. If the variable
+		  <c>V</c> is bound, it has to match the value associated with <c>K</c> in <c>M</c>.
+	  </p>
+	  <p> Example: </p>
+<code>
+1> <input>M = #{"tuple" => {1,2}}.</input>
+#{"tuple" => {1,2}}
+2> <input>#{"tuple" := {1,B}} = M.</input>
+#{"tuple" => {1,2}}
+3> <input>B.</input>
+2.</code>
+	  <p>
+		  This will bind variable <c>B</c> to integer <c>2</c>.
+	  </p>
+	  <p>
+		  Similarly, multiple values from the map may be matched:
+	  </p>
+	  <code>#{ K1 := V1, .., Kn := Vn } = M</code>
+	  <p>
+		  where keys <c>K1 .. Kn</c> are any expressions with literals or bound variables. If all
+		  keys exist in map <c>M</c> all variables in <c>V1 .. Vn</c> will be matched to the
+		  associated values of their respective keys.
+	  </p>
+	  <p>
+		  If the matching conditions are not met, the match will fail, either with
+	  </p>
+	  <list>
+		  <item>
+			  a <c>badmatch</c> exception, if used in the context of the matching operator
+			  as in the example, 
+		  </item>
+		  <item>
+			  or resulting in the next clause being tested in function heads and
+			  case expressions.
+		  </item>
+	  </list>
+	  <p>
+		  Matching in maps only allows for <c>:=</c> as delimiters of associations.
+		  The order in which keys are declared in matching has no relevance.
+	  </p>
+	  <p>
+		  Duplicate keys are allowed in matching and will match each pattern associated
+		  to the keys.
+	  </p>
+	  <code>#{ K := V1, K := V2 } = M</code>
+	  <p>
+		  Matching an expression against an empty map literal will match its type but
+		  no variables will be bound:
+	  </p>
+	  <code>#{} = Expr</code>
+	  <p>
+		  This expression will match if the expression <c>Expr</c> is of type map, otherwise
+		  it will fail with an exception <c>badmatch</c>.
+	  </p>
+	  <section>
+		  <title>Matching syntax: Example with literals in function heads</title>
+		  <p>
+			  Matching of literals as keys are allowed in function heads.
+		  </p>
+		  <code>
+%% only start if not_started
+handle_call(start, From, #{ state := not_started } = S) ->
+...
+    {reply, ok, S#{ state := start }};
+
+%% only change if started
+handle_call(change, From, #{ state := start } = S) ->
+...
+    {reply, ok, S#{ state := changed }};</code>
+	  </section>
+  </section>
+  <section>
+	  <title>Maps in Guards</title>
+	  <p>
+		  Maps are allowed in guards as long as all sub-expressions are valid guard expressions.
+	  </p>
+	  <p>
+		  Two guard BIFs handles maps:
+	  </p>
+	  <list>
+		  <item>
+			  <seealso marker="erts:erlang#is_map/1">is_map/1</seealso>
+		  </item>
+		  <item>
+			  <seealso marker="erts:erlang#map_size/1">map_size/1</seealso>
+		  </item>
+	  </list>
+  </section>
+</chapter>
diff --git a/system/doc/reference_manual/modules.xml b/system/doc/reference_manual/modules.xml
index cd4c3a1b1b..f0ec7ef165 100644
--- a/system/doc/reference_manual/modules.xml
+++ b/system/doc/reference_manual/modules.xml
@@ -53,10 +53,10 @@ fact(0) ->           %  |
     <pre>
 -Tag(Value).</pre>
     <p><c>Tag</c> must be an atom, while <c>Value</c> must be a literal
-      term. As a convenience in user-defined attributes, the literal term
-      <c>Value</c> the syntax <c>Name/Arity</c>
-      (where <c>Name</c> is an atom and <c>Arity</c> a positive integer)
-      will be translated to <c>{Name,Arity}</c>.</p>
+      term. As a convenience in user-defined attributes, if the literal term
+      <c>Value</c> has the syntax <c>Name/Arity</c>
+      (where <c>Name</c> is an atom and <c>Arity</c> a positive integer),
+	  the term <c>Name/Arity</c> will be translated to <c>{Name,Arity}</c>.</p>
 
     <p>Any module attribute can be specified. The attributes are stored
       in the compiled code and can be retrieved by calling
diff --git a/system/doc/reference_manual/part.xml b/system/doc/reference_manual/part.xml
index ee8f3dd7eb..36fb888748 100644
--- a/system/doc/reference_manual/part.xml
+++ b/system/doc/reference_manual/part.xml
@@ -36,6 +36,7 @@
   <xi:include href="typespec.xml"/>
   <xi:include href="expressions.xml"/>
   <xi:include href="macros.xml"/>
+  <xi:include href="maps.xml"/>
   <xi:include href="records.xml"/>
   <xi:include href="errors.xml"/>
   <xi:include href="processes.xml"/>
diff --git a/system/doc/reference_manual/typespec.xml b/system/doc/reference_manual/typespec.xml
index 71aec732cf..cc35c6eb21 100644
--- a/system/doc/reference_manual/typespec.xml
+++ b/system/doc/reference_manual/typespec.xml
@@ -100,6 +100,7 @@
         | Fun
         | Integer
         | List
+        | Map
         | Tuple
         | Union
         | UserDefined           %% described in Section 6.3
@@ -126,10 +127,17 @@
         | 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
 
@@ -275,6 +283,10 @@
     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>
diff --git a/system/doc/reference_manual/xmlfiles.mk b/system/doc/reference_manual/xmlfiles.mk
index 6886c8c7cf..181e6f8042 100644
--- a/system/doc/reference_manual/xmlfiles.mk
+++ b/system/doc/reference_manual/xmlfiles.mk
@@ -24,6 +24,7 @@ REF_MAN_CHAPTER_FILES = \
 	functions.xml \
 	expressions.xml \
 	macros.xml \
+	maps.xml \
 	records.xml \
 	errors.xml \
 	processes.xml \