Teach the ASN.1 compiler the 'maps' option

When the 'maps' option is given, the SEQUENCE and SET types are
represented as maps instead of as records. Optional and default values
must be not be given as asn1_NOVALUE or asn1_DEFAULT in a map passed
to the M:encode/2 function; they must be omitted from the
map. Similarly, when decoding missing values will be omitted from the
map.

No .hrl files will be generated when the 'maps' options is used.
That means values in an ASN.1 module must be retrieved by calling the
appropriate function in generated module.

Since we one day hope to get rid of the options 'compact_bit_string',
'legacy_bit_string', and 'legacy_erlang_types', we will not allow them
to be combined with the 'maps' option.

1 files changed, 68 insertions, 9 deletions

diff --git a/lib/asn1/doc/src/asn1_getting_started.xml b/lib/asn1/doc/src/asn1_getting_started.xml
index d40b294c39..d2b73d63c3 100644
--- a/lib/asn1/doc/src/asn1_getting_started.xml
+++ b/lib/asn1/doc/src/asn1_getting_started.xml
@@ -187,6 +187,14 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn</pre>
         <item>
           <p>DER encoding rule. Only when using option <c>-ber</c>.</p>
         </item>
+        <tag><c>+maps</c></tag>
+        <item>
+          <p>Use maps instead of records to represent the <c>SEQUENCE</c> and
+	  <c>SET</c> types. No <c>.hrl</c> files will be generated.
+	  See the Section <seealso marker="asn1_getting_started#MAP_SEQ_SET">
+	  Map representation for SEQUENCE and SET</seealso>
+	  for more information.</p>
+        </item>
         <tag><c>+asn1config</c></tag>
         <item>
           <p>This functionality works together with option
@@ -766,8 +774,11 @@ Pdu ::= SEQUENCE {
    b REAL,
    c OBJECT IDENTIFIER,
    d NULL }      </pre>
-      <p>This is a 4-component structure called <c>Pdu</c>. The record format
-        is the major format for representation of <c>SEQUENCE</c> in Erlang.
+      <p>This is a 4-component structure called <c>Pdu</c>. By default,
+        a <c>SEQUENCE</c> is represented by a record in Erlang.
+	It can also be represented as a map; see
+	<seealso marker="asn1_getting_started#MAP_SEQ_SET">
+	Map representation for SEQUENCE and SET</seealso>.
         For each <c>SEQUENCE</c> and <c>SET</c> in an ASN.1 module an Erlang
         record declaration is generated. For <c>Pdu</c>, a record
         like the following is defined:</p>
@@ -878,6 +889,48 @@ SExt ::= SEQUENCE {
     </section>
 
     <section>
+      <marker id="MAP_SEQ_SET"></marker>
+      <title>Map representation for SEQUENCE and SET</title>
+      <p>If the ASN.1 module has been compiled with option <c>maps</c>,
+      the types <c>SEQUENCE</c> and <c>SET</c> are represented as maps.</p>
+      <p>In the following example, this ASN.1 specification is used:</p>
+      <pre>
+File DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
+Seq1 ::= SEQUENCE {
+    a INTEGER DEFAULT 42,
+    b BOOLEAN OPTIONAL,
+    c IA5String
+}
+END   </pre>
+
+      <p>Optional fields are to be omitted from the map if they have
+      no value:</p>
+
+      <pre>
+1> <input>asn1ct:compile('File', [per,maps]).</input>
+ok
+2> <input>{ok,E} = 'File':encode('Seq1', #{a=>0,c=>"string"}).</input>
+{ok,&lt;&lt;128,1,0,6,115,116,114,105,110,103&gt;&gt;} </pre>
+
+      <p>When decoding, optional fields will be omitted from the map:</p>
+
+      <pre>
+3> <input>'File':decode('Seq1', E).</input>
+{ok,#{a => 0,c => "string"}}   </pre>
+
+      <p>Default values can be omitted from the map:</p>
+      <pre>
+4> <input>{ok,E2} = 'File':encode('Seq1', #{c=>"string"}).</input>
+{ok,&lt;&lt;0,6,115,116,114,105,110,103&gt;&gt;}
+5> <input>'File':decode('Seq1', E2).</input>
+{ok,#{a => 42,c => "string"}}   </pre>
+
+    <note><p>It is not allowed to use the atoms <c>asn1_VALUE</c> and
+    <c>asn1_DEFAULT</c> with maps.</p></note>
+    </section>
+
+    <section>
       <marker id="CHOICE"></marker>
       <title>CHOICE</title>
       <p>The type <c>CHOICE</c> is a space saver and is similar to the
@@ -1004,11 +1057,16 @@ T ::= CHOICE {
 
   <section>
     <title>Naming of Records in .hrl Files</title>
+    <p>When the option <c>maps</c> is given, no <c>.hrl</c> files
+    will be generated. The rest of this section describes the behavior
+    of the compiler when <c>maps</c> is not used.</p>
+
     <p>When an ASN.1 specification is compiled, all defined types of type
-      <c>SET</c> or <c>SEQUENCE</c> result in a corresponding record in the
-      generated <c>.hrl</c> file. This is because the values for
-      <c>SET</c> and <c>SEQUENCE</c> are represented as records as
-      mentioned earlier.</p>
+    <c>SET</c> or <c>SEQUENCE</c> result in a corresponding record in the
+    generated <c>.hrl</c> file. This is because the values for
+    <c>SET</c> and <c>SEQUENCE</c> are represented as records
+    by default.</p>
+
     <p>Some special cases of this functionality are presented in the
       next section.</p>
 
@@ -1144,9 +1202,10 @@ SS ::= SET {
     <p>This example shows that a function is generated by the compiler
       that returns a valid Erlang representation of the value, although
       the value is of a complex type.</p>
-    <p>Furthermore, a macro is generated for each value in the <c>.hrl</c>
-      file. So, the defined value <c>tt</c> can also be extracted by
-      <c>?tt</c> in application code.</p>
+    <p>Furthermore, if the option <c>maps</c> is not used,
+    a macro is generated for each value in the <c>.hrl</c>
+    file. So, the defined value <c>tt</c> can also be extracted by
+    <c>?tt</c> in application code.</p>
   </section>
 
   <section>