Release v6.1

Author: arobenko

CMakeLists.txt

@@ -11,7 +11,7 @@ if (NOT ASCIIDOCTOR_PDF_EXE)
     message(FATAL_ERROR "asciidoctor-pdf is not found")
 endif ()
 
-set (VERSION "v6.0")
+set (VERSION "v6.1")
 set (MAIN_FILE "${PROJECT_SOURCE_DIR}/commsdsl_spec.adoc")
 
 add_custom_target("pdf" ALL

commsdsl_spec.adoc

@@ -1,6 +1,6 @@
-= CommsDSL Specification v6.0
+= CommsDSL Specification v6.1
 Alex Robenko
-v6.0, 2023-03
+v6.1, 2023-06
 :doctype: article
 :toc: left
 :source-highlighter: rouge

fields/bundle.adoc

@@ -54,7 +54,7 @@ of the **<bundle>**, then all the members must be wrapped in
 ----
 
 [[fields-bundle-reusing-other-bundle]]
-==== Reusing Other <bundle&gtp ====
+==== Reusing Other <bundle> ====
 Like any other field, **<bundle>** supports **reuse** of any other **<bundle>**.
 Such reuse copies all the fields from original **<bundle>** in addition
 to all the properties. Any new defined member field gets **appended** to the copied ones.

fields/common.adoc

@@ -71,7 +71,7 @@ it is **NOT** allowed for <<fields-enum, &lt;enum&gt; >> field to reuse definiti
 [[fields-common-forcing-generation]]
 ==== Forcing Generation ====
 By default the code generator is expected not to generate code for fields that
-are not <<intro-references, referenced>> by any other field to reduce amount of 
+are not <<intro-references, referenced>> by any message or any other field to reduce amount of
 generated code. However, there may be cases when a field releated definitions are expected
 to find their way into the generated code even the field itself is not referenced
 anywhere. To help with such forcing the **forceGen** <<intro-properties, property>>
@@ -363,7 +363,7 @@ the **CommsDSL** provides the following <<intro-properties, properties>>.
 The value of the <<intro-properties, properties>> above can be one of the following:
 
 * **any** (default) - Inject the overriding code if available, use the code generated by default if not.
-* **replace** - The default code code is incorrect, replace it with the provided one. The code generator is expected
+* **replace** - The default code is incorrect, replace it with the provided one. The code generator is expected
 to report a failure in case the overriding code is unavailable.
 * **extend** - The default code is still incorrect, but the code generator is expected to 
 produce it (with some minor renaming to avoid names clashing) to allow reuse and extension in the overriding code. The code generator is expected

fields/list.adoc

@@ -205,6 +205,12 @@ suffix field is supported using **termSuffix** property. Just like with
 <<fields-list-count-prefix, countPrefix>>, and <<fields-list-length-prefix, lengthPrefix>>,
 the termination suffix can be specified as a child XML node or referenced when
 defined externally.
+
+The termination suffix is determined by the _successful_ read attempt before attempting to read the
+list element. It means that the termination suffix field needs to fail its read operation if it's not
+encountered. In most cases specifying valid value(s) in conjunction with the **failOnInvalid** property
+is sufficient.
+
 [source,xml]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
@@ -215,19 +221,19 @@ defined externally.
                 <int name="Element" type="uint32" />
             </element>
             <termSuffix>
-                <int name="TermSuffix" type="uint8" defaultValue="0"/>
+                <int name="TermSuffix" type="uint8" defaultValidValue="0" failOnInvalid="true" />
             </termSuffix>
         </list>
         
-        <int name="ExternalTermSuffix" type="uint8" />
+        <int name="ExternalTermSuffix" type="uint8" validRange="[0, 1]" failOnInvalid="true" />
         <list name="List2" termSuffix="ExternalTermSuffix">
             <int name="Element" type="uint32" />
         </list>
     </fields>
 </schema>
 ----
 
-**NOTE**, that **count**, **countPrefix**, **lengthPrefix**, and **termSuffix** properties
+**NOTE** that **count**, **countPrefix**, **lengthPrefix**, and **termSuffix** properties
 are mutually exclusive, i.e. cannot be used together.
 
 [[fields-list-element-length-prefix]]

fields/optional.adoc

@@ -77,7 +77,7 @@ specified using **defaultMode** <<intro-properties, property>>.
 [[fields-optional-existence-conditions]]
 ==== Existence Condition ====
 Many protocols introduce optional fields, and the existence of such fields
-depend on the value of some other field. Classic example would be having 
+depends on the value of some other field. Classic example would be having
 some kind of flags field (see <<fields-set, **&lt;set&gt;** >>) where some bit specifies
 whether other field that follows exists or not. Such conditions can be expressed
 using **cond** <<intro-properties, property>>.
@@ -92,13 +92,13 @@ using **cond** <<intro-properties, property>>.
         <optional name="Val1" defaultMode="missing" cond="$Flags.Val1Exists">
             <int name="ActVal1" type="uint32" />
         </optional>
-    </fields>
+    </message>
 </schema>
 ----
 **NOTE**, that **cond** property can be used only for **&lt;optional&gt;** field
 that is a member of a <<fields-bundle, &lt;bundle&gt; >> or a 
 <<messages-messages, &lt;message&gt; >>. The **cond** expression 
-specifies condition when the **&lt;optional&gt;** field exists, and must always
+specifies condition when the **&lt;optional&gt;** field exists, and is expected to
 reference other **sibling** field. Such reference is always prefixed with `$` character
 to indicate that the field is a **sibling** of the **&lt;optional&gt;** and 
 not some external field.
@@ -129,7 +129,7 @@ For example:
         <optional name="F3" defaultMode="exists" cond="$F1 &lt; $F2">
             <int name="WrappedF3" type="uint32" />
         </optional>
-    </fields>
+    </message>
 </schema>
 ----
 The `F3` above exists, only if value of **F1** is less than value of **F2**
@@ -146,14 +146,39 @@ Deep (nested) conditions are also expected to be supported by the code generator
                 <bit name="B0" idx="0" />
                 <bit name="B1" idx="1" />
             </set>
-        </fitfield>
+        </bitfield>
         <optional name="F2" defaultMode="missing" cond="$F1.Mem2.B0">
             <int name="WrappedF2" type="uint32" />
         </optional>
         <optional name="F3" defaultMode="exists" cond="!$F1.Mem2.B1">
             <int name="WrappedF3" type="uint32" />
         </optional>
-    </fields>
+    </message>
+</schema>
+----
+
+When referencing the member of another `<optional>` field in the existence condition,
+a check that the wrapping `<optional>` field **exists** in addition to the
+actual specified condition is automatically implied.
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <message name="Msg1" id="1">
+        <set name="F1">
+            <bit name="B0" idx="0" />
+            <bit name="B1" idx="1" />
+        </set>
+        <optional name="F2" defaultMode="missing" cond="$F1.B0">
+            <set name="WrappedF2">
+                <bit name="B0" idx="0" />
+                <bit name="B1" idx="1" />
+            </set>
+        </optional>
+        <optional name="F3" defaultMode="exists" cond="!$F2.WrappedF2.B1">
+            <int name="WrappedF3" type="uint32" />
+        </optional>
+    </message>
 </schema>
 ----
 
@@ -171,7 +196,7 @@ as the reference to a sibling field described above.
                 <bit name="B0" idx="0" />
                 <bit name="B1" idx="1" />
             </set>
-        </fitfield>
+        </bitfield>
     </interface>
 
     <message name="Msg1" id="1">
@@ -181,7 +206,7 @@ as the reference to a sibling field described above.
         <optional name="F2" defaultMode="exists" cond="!%Flags.Mem2.B1">
             <int name="WrappedF2" type="uint32" />
         </optional>
-    </fields>
+    </message>
 </schema>
 ----
 **WARNING**: The **CommsDSL** specification supports multiple interfaces and doesn't impose any restriction
@@ -191,6 +216,54 @@ the referenced field. The code generator may also not impose many restrictions o
 Usage of the wrong **&lt;interface&gt;** class with the missing referenced
 field in the end application may result in compilation errors.
 
+Since **v6.1** of this specification comparing the size of the collection type fields (
+**&lt;data&gt;**, **&lt;string&gt;**, and **&lt;list&gt;**) is also supported. The size check condition is determined
+by the usage of the `#` character after the one indicating sibling (`$`) or interface (`%`) reference.
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <message name="Msg1" id="1">
+        <data name="F1">
+            <lengthPrefix>
+                <int name="Length" type="uint8" />
+            </lengthPrefix>
+        </data>
+        <optional name="F2" defaultMode="missing" cond="$#F1 != 0">
+            <int name="ActF1" type="uint32" />
+        </optional>
+    </message>
+</schema>
+----
+In the example above the `F2` field exists if `F1` is not empty, i.e. its size is not `0`.
+
+Also since **v6.1** of this specification check whether the previously encountered **&lt;optional&gt;** field
+exists is also supporting in another **&lt;optional&gt;** field condition. Such check is determined by the
+usage of the `?` character after the one indicating sibling (`$`) or interface (`%`) reference.
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <message name="Msg1" id="1">
+        <set name="F1">
+            <bit name="B0" idx="0" />
+            <bit name="B1" idx="1" />
+        </set>
+        <optional name="F2" defaultMode="missing" cond="$F1.B0">
+            <set name="ActF2">
+                <bit name="B0" idx="0" />
+                <bit name="B1" idx="1" />
+            </set>
+        </optional>
+        <optional name="F3" defaultMode="exists" cond="!$?F2">
+            <int name="ActF3" type="uint32" />
+        </optional>
+    </fields>
+</schema>
+----
+In the example above `F3` exists when `F2` is missing.
+
 [[fields-optional-multiple-existence-conditions]]
 ==== Multiple Existence Conditions ====
 The **CommsDSL** also allows usage of multiple existence condition statements. However,
@@ -253,7 +326,8 @@ place in the input buffer.
 ==== Missing On Invalid ====
 Similar to <<fields-optional-missing-on-failed-read, missingOnReadFail>>, but with a bit of different
 flavour, the property **missingOnInvalid** insures that the **&lt;optional&gt;** field is marked as
-"missing" when the held field's value is invalid. If case of recognition the invalid value
+"missing" when the held field's value is invalid (applicable to the __refresh__ operation).
+In case of recognition of the invalid value
 during the __read__ operation, the **&lt;optional&gt;** field must be marked as "missing" and
 reading of the following fields must continue from the place in the input buffer as if the __read__
 operation of the **&lt;optional&gt;** field didn't take place.