From 8a7f914affce3102e4889c2973ea2d2e99ad633d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Mon, 16 Jan 2017 16:47:58 +0100 Subject: 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. --- lib/asn1/doc/src/asn1_getting_started.xml | 77 +++++++++++++++++++++++++++---- lib/asn1/doc/src/asn1ct.xml | 17 ++++++- 2 files changed, 84 insertions(+), 10 deletions(-) (limited to 'lib/asn1/doc/src') 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

DER encoding rule. Only when using option -ber.

 + +maps + +

Use maps instead of records to represent the SEQUENCE and + SET types. No .hrl files will be generated. + See the Section + Map representation for SEQUENCE and SET + for more information.

+ +asn1config

This functionality works together with option @@ -766,8 +774,11 @@ Pdu ::= SEQUENCE { b REAL, c OBJECT IDENTIFIER, d NULL } -

This is a 4-component structure called Pdu. The record format - is the major format for representation of SEQUENCE in Erlang. +

This is a 4-component structure called Pdu. By default, + a SEQUENCE is represented by a record in Erlang. + It can also be represented as a map; see + + Map representation for SEQUENCE and SET. For each SEQUENCE and SET in an ASN.1 module an Erlang record declaration is generated. For Pdu, a record like the following is defined:

@@ -877,6 +888,48 @@ SExt ::= SEQUENCE { component, if present, otherwise the value asn1_NOVALUE.

+
+ + Map representation for SEQUENCE and SET +

If the ASN.1 module has been compiled with option maps, + the types SEQUENCE and SET are represented as maps.

+

In the following example, this ASN.1 specification is used:

+ 
+File DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
+Seq1 ::= SEQUENCE {
+    a INTEGER DEFAULT 42,
+    b BOOLEAN OPTIONAL,
+    c IA5String
+}
+END
+ +

Optional fields are to be omitted from the map if they have + no value:

+ + 
+1> asn1ct:compile('File', [per,maps]).
+ok
+2> {ok,E} = 'File':encode('Seq1', #{a=>0,c=>"string"}).
+{ok,<<128,1,0,6,115,116,114,105,110,103>>}
+ +

When decoding, optional fields will be omitted from the map:

+ + 
+3> 'File':decode('Seq1', E).
+{ok,#{a => 0,c => "string"}}
+ +

Default values can be omitted from the map:

+ 
+4> {ok,E2} = 'File':encode('Seq1', #{c=>"string"}).
+{ok,<<0,6,115,116,114,105,110,103>>}
+5> 'File':decode('Seq1', E2).
+{ok,#{a => 42,c => "string"}}
+ +

It is not allowed to use the atoms asn1_VALUE and + asn1_DEFAULT with maps.

 +
+
CHOICE @@ -1004,11 +1057,16 @@ T ::= CHOICE {
Naming of Records in .hrl Files +

When the option maps is given, no .hrl files + will be generated. The rest of this section describes the behavior + of the compiler when maps is not used.

+

When an ASN.1 specification is compiled, all defined types of type - SET or SEQUENCE result in a corresponding record in the - generated .hrl file. This is because the values for - SET and SEQUENCE are represented as records as - mentioned earlier.

+ SET or SEQUENCE result in a corresponding record in the + generated .hrl file. This is because the values for + SET and SEQUENCE are represented as records + by default.

+

Some special cases of this functionality are presented in the next section.

@@ -1144,9 +1202,10 @@ SS ::= SET {

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.

-

Furthermore, a macro is generated for each value in the .hrl - file. So, the defined value tt can also be extracted by - ?tt in application code.

+

Furthermore, if the option maps is not used, + a macro is generated for each value in the .hrl + file. So, the defined value tt can also be extracted by + ?tt in application code.

diff --git a/lib/asn1/doc/src/asn1ct.xml b/lib/asn1/doc/src/asn1ct.xml index ebe1ce44dc..859d6a50bb 100644 --- a/lib/asn1/doc/src/asn1ct.xml +++ b/lib/asn1/doc/src/asn1ct.xml @@ -170,11 +170,24 @@ File3.asn as for ber.

+ maps + +

This option changes the representation of the types + SEQUENCE and SET to use maps (instead of + records). This option also suppresses the generation of + .hrl files.

+

For details, see Section + + Map representation for SEQUENCE and SET + in the User's Guide. +

+ compact_bit_string

The BIT STRING type is decoded to "compact notation". This option is not recommended for new code. + This option cannot be combined with the option maps.

For details, see Section @@ -188,6 +201,7 @@ File3.asn The BIT STRING type is decoded to the legacy format, that is, a list of zeroes and ones. This option is not recommended for new code. + This option cannot be combined with the option maps.

For details, see Section BIT STRING @@ -202,7 +216,8 @@ File3.asn marker="asn1_getting_started#BIT STRING">BIT STRING and Section OCTET STRING in the User's Guide.

-

This option is not recommended for new code.

+

This option is not recommended for new code. + This option cannot be combined with the option maps.

 {n2n, EnumTypeName} -- cgit v1.2.3