Release v5.0

Author: arobenko

CMakeLists.txt

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

aliases/aliases.adoc

@@ -1,3 +1,5 @@
+
+<<<
 [[aliases-aliases]]
 == Aliases ==
 It is not uncommon for a particular field to change its meaning and as the

appendix/alias.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-alias]]
 === Properties of &lt;alias&gt; ===
 Refer to <<aliases-aliases, Aliases>> chapter for detailed description. 

appendix/appendix.adoc

@@ -1,8 +1,11 @@
+
+<<<
 [[appendix-appendix]]
 == Appendix ==
 This chapter contains list of properties for all the elements described earlier
 in this document for a quick reference.
 
+include::reference.adoc[]
 include::schema.adoc[]
 include::fields.adoc[]
 include::enum.adoc[]

appendix/bitfield.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-bitfield]]
 === Properties of &lt;bitfield&gt; Field ===
 The **&lt;bitfield&gt;** field has all the <<appendix-fields, common>> properties as
@@ -18,4 +19,5 @@ Extra child XML elements allowed:
 |XML Element|DSL Version ^.^|Description
 
 |**&lt;members&gt;**|1|Wraps member fields.
+|**&lt;replace&gt;**|5|Wraps replacing member fields after copying using **reuse** property.
 |===

appendix/bundle.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-bundle]]
 === Properties of &lt;bundle&gt; Field ===
 The **&lt;bundle&gt;** field has all the <<appendix-fields, common>> properties as
@@ -19,4 +20,5 @@ Extra child XML elements allowed:
 
 |**&lt;members&gt;**|1|Wraps member fields.
 |**&lt;alias&gt;**|3|Alias names for other member fields. See <<aliases-aliases, Aliases>> for more info.
+|**&lt;replace&gt;**|5|Wraps replacing member fields after copying using **reuse** property.
 |===

appendix/checksum.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-checksum]]
 === Properties of &lt;checksum&gt; Frame Layer ===
 The **&lt;checksum&gt;** layer has all the <<appendix-layers, common>> properties as

appendix/custom.adoc

@@ -1,12 +1,16 @@
+<<<
 [[appendix-custom]]
 === Properties of &lt;custom&gt; Frame Layer ===
 The **&lt;custom&gt;** layer has all the <<appendix-layers, common>> properties as
 well as ones listed below. Refer to <<frames-custom, &lt;custom&gt; Layer>> chapter
 for detailed description. 
 
-[cols="^.^28,^.^10,^.^8,^.^8,^.^10,36", options="header"]
+[cols="^.^27,^.^11,^.^8,^.^10,^.^10,34", options="header"]
 |===
 |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description
-
-|**idReplacement**|<<intro-boolean, bool>>|1|no|false|Mark the layer as one replacing <<frames-id, &lt;id&gt; >>.
+|**[.line-through]#idReplacement#**|<<intro-boolean, bool>>|1|no|false|Mark the layer as one replacing <<frames-id, &lt;id&gt; >>. + 
+**Deprecated**, use `semanticLayerType="id"` instead.
+|**semanticLayerType**|"payload", "id", "size", "sync", "checksum", "value", "custom"|5|no|custom|Specify what other layer **&lt;custom&gt;** one is replacing.
+|**checksumFrom**|<<intro-names, name>> string|5|no (unless **semanticLayerType** is "checksum" and **checksumUntil** is empty)||Name of the frame layer, from which the checksum calculation starts. Applicable only when `semanticLayerType="checksum"`.
+|**checksumUntil**|<<intro-names, name>> string|5|no (unless **semanticLayerType** is "checksum" and **checksumFrom** is empty)||Name of the frame layer, until (and including) which the checksum calculation is executed. Applicable only when `semanticLayerType="checksum"`.
 |===

appendix/data.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-data]]
 === Properties of &lt;data&gt; Field ===
 The **&lt;data&gt;** field has all the <<appendix-fields, common>> properties as

appendix/enum.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-enum]]
 === Properties of &lt;enum&gt; Field ===
 The **&lt;enum&gt;** field has all the <<appendix-fields, common>> properties as

appendix/fields.adoc

@@ -1,3 +1,5 @@
+
+<<<
 [[appendix-fields]]
 === Common Properties of Fields ===
 Refer to <<fields-common, Common Properties of Fields>> chapter for detailed description. 
@@ -8,7 +10,7 @@ Refer to <<fields-common, Common Properties of Fields>> chapter for detailed des
 
 |**name**|<<intro-names, name>> string|1|yes||Name of the field.
 |**description**|string|1|no||Human readable description of the field.
-|**reuse**|<<intro-references, reference>> string|1|no||Field definition of which to copy.
+|**reuse**|<<intro-references, reference>> string|1|no||Field, definition of which to copy.
 |**displayName**|string|1|no||Name of the field to display. If empty, the code generator must use value of property **name** instead. In order to force empty name to display, use "_" (underscore).
 |**displayReadOnly**|<<intro-boolean, bool>>|1|no|false|Disable modification of the field in visual analysis tool(s).
 |**displayHidden**|<<intro-boolean, bool>>|1|no|false|Don't display field at all in visual analysis tool(s).
@@ -24,10 +26,13 @@ Applicable only to members of the <<messages-messages, &lt;message&gt; >> or <<f
 |**customizable**|<<intro-boolean, bool>>|1|no|false|Mark the field to allow compile time customization regardless of code generator's level of customization.
 |**semanticType**|"none", "messageId", "version", "length"|1|no|none|Specify semantic type of the field. It allows code generator to generate special code for special cases. Value "length" was introduced in **v2** of this specification.
 |**forceGen**|<<intro-boolean, bool>>|3|no|false|Force generation of field's code regardless of it's being referenced or not.
+|**valueOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **value** operation.
 |**readOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **read** operation.
 |**writeOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **write** operation.
 |**refreshOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **refresh** operation.
 |**lengthOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **length** retrieval.
 |**validOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **valid** retrieval.
 |**nameOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **name** retrieval.
+|**copyCodeFrom**|<<intro-references, reference>> string|5|no||Specify field, overriding or other extra code of which needs to be copied.
+|**reuseCode**|<<intro-boolean, bool>>|5|no|false|In case of **reuse** apply **copyCodeFrom** with the same <<intro-references, reference>> string.
 |===

appendix/float.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-float]]
 === Properties of &lt;float&gt; Field ===
 The **&lt;float&gt;** field has all the <<appendix-fields, common>> properties as

appendix/frame.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-frame]]
 === Properties of &lt;frame&gt; ===
 Refer to <<frames-frames, Frames>> chapter

appendix/int.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-int]]
 === Properties of &lt;int&gt; Field ===
 The **&lt;int&gt;** field has all the <<appendix-fields, common>> properties as

appendix/interface.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-interface]]
 === Properties of &lt;interface&gt; ===
 Refer to <<interfaces-interfaces, Interfaces>> chapter

appendix/layers.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-layers]]
 === Common Properties of Frame Layers ===
 Refer to <<frames-common, Common Properties of Layers>> chapter for detailed description. 

appendix/list.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-list]]
 === Properties of &lt;list&gt; Field ===
 The **&lt;list&gt;** field has all the <<appendix-fields, common>> properties as
@@ -14,5 +15,6 @@ for detailed description.
 |**lengthPrefix**|<<fields-fields, field>> or <<intro-references, reference>>|1|no||Prefix field containing serialization length of the list. Cannot be used tegether with **count** or **countPrefix**.
 |**elemLengthPrefix**|<<fields-fields, field>>|1|no||Prefix field containing serialization length of the list **element**.
 |**elemFixedLength**|<<intro-boolean, bool>>|1|no|false|Indication of whether list has and will allways have fixed length element, so **elemLengthPrefix** prefixes only the first element and not the rest.
+|**termSuffix**|<<fields-fields, field>>|5|no||Suffix field terminating the list.
 |===
 

appendix/message.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-message]]
 === Properties of &lt;message&gt; ===
 Refer to <<messages-messages, Messages>> chapter
@@ -27,6 +28,7 @@ Must be greater than value of **sinceVersion**.
 |**lengthOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **length** retrieval.
 |**validOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **valid** retrieval.
 |**nameOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **name** retrieval.
+|**copyCodeFrom**|<<intro-references, reference>> string|5|no||Specify message, overriding or other extra code of which needs to be copied.
 |===
 
 Extra child XML elements allowed:
@@ -37,4 +39,5 @@ Extra child XML elements allowed:
 
 |**&lt;fields&gt;**|1|Wraps member fields.
 |**&lt;alias&gt;**|3|Alias names for other member fields. See <<aliases-aliases, Aliases>> for more info.
+|**&lt;replace&gt;**|5|Wraps replacing fields after copying using **copyFieldsFrom** property.
 |===

appendix/optional.adoc

@@ -1,17 +1,20 @@
+<<<
 [[appendix-optional]]
 === Properties of &lt;optional&gt; Field ===
 The **&lt;optional&gt;** field has all the <<appendix-fields, common>> properties as
 well as ones listed below. Refer to <<fields-optional, &lt;optional&gt; Field>> chapter
 for detailed description. 
 
-[cols="^.^28,^.^10,^.^8,^.^8,^.^10,36", options="header"]
+[cols="^.^27,^.^11,^.^8,^.^8,^.^10,36", options="header"]
 |===
 |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description
 
 |**field**|<<fields-fields, field>>|1|no||Wrapped field.
 |**defaultMode**|"tentative", "missing", "exist"|1|no|tentative|Default mode of the field. See also <<appendix-optional-default-mode, Default Mode Strings>> below.
 |**cond**|string|1|no||Condition when the field exists.
 |**displayExtModeCtrl**|<<intro-boolean, bool>>|1|no|false|Disable manual update of the mode in GUI analysis tools.
+|**missingOnReadFail**|<<intro-boolean, bool>>|5|no|false|Mark the field as "missing" if its read operation fails.
+|**missingOnInvalid**|<<intro-boolean, bool>>|5|no|false|Mark the field as "missing" if the field's value is invalid.
 |===
 
 Inner field must be specified using **field** property or as 

appendix/ref.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-ref]]
 === Properties of &lt;ref&gt; Field ===
 The **&lt;ref&gt;** field has all the <<appendix-fields, common>> properties as

appendix/reference.adoc

@@ -0,0 +1,14 @@
+[[appendix-reference]]
+=== Reference Prefix ===
+Lists available prefixes allowing distinction of different <<intro-references, references>>.
+
+[cols="^.^10,^.^20,70", options="header"]
+|===
+|Prefix Character|DSL Version|Description
+
+||1|Regular reference to a field within the same schema.
+|`$`|1|Reference to a sibling field.
+|`^`|2|Reference to a field when it's not possible to distinguish between value and reference.
+|`@`|5|Reference to a field in a different schema.
+|===
+

appendix/schema.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-schema]]
 === Properties of &lt;schema&gt; ===
 Refer to <<schema-schema, Schema>> chapter for detailed description.

appendix/set.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-set]]
 === Properties of &lt;set&gt; Field ===
 The **&lt;set&gt;** field has all the <<appendix-fields, common>> properties as
@@ -16,6 +17,7 @@ for detailed description.
 |**endian**|"big" or "little"|1|no|endian of <<schema-schema, schema>>|Endian of the field.
 |**nonUniqueAllowed**|<<intro-boolean, bool>>|1|no|false|Allow non unique **&lt;bit&gt;**-s.
 |**validCheckVersion**|<<intro-boolean, bool>>|1|no|false|Take into account protocol version when generating code for field's value validity check.
+|**availableLengthLimit**|<<intro-boolean, bool>>|4|no|false|Allow having less bytes in the buffer than required by the **type** or **length** when performing (de)serialization.
 |===
 
 ==== Properties of &lt;bit&gt; Child Element of &lt;set&gt; Field ====

appendix/string.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-string]]
 === Properties of &lt;string&gt; Field ===
 The **&lt;string&gt;** field has all the <<appendix-fields, common>> properties as

appendix/units.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-units]]
 === Units ===
 The tables below contain lists of available units.

appendix/value.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-value]]
 === Properties of &lt;value&gt; Frame Layer ===
 The **&lt;value&gt;** layer has all the <<appendix-layers, common>> properties as

appendix/variant.adoc

@@ -1,3 +1,4 @@
+<<<
 [[appendix-variant]]
 === Properties of &lt;variant&gt; Field ===
 The **&lt;variant&gt;** field has all the <<appendix-fields, common>> properties as
@@ -20,5 +21,6 @@ Extra child XML elements allowed:
 |XML Element|DSL Version ^.^|Description
 
 |**&lt;members&gt;**|1|Wraps member fields.
+|**&lt;replace&gt;**|5|Wraps replacing member fields after copying using **reuse** property.
 |===
 

commsdsl_spec.adoc

@@ -1,6 +1,6 @@
-= CommsDSL Specification v4.0
+= CommsDSL Specification v5.0
 Alex Robenko
-v4.0, 2022-05
+v5.0, 2022-08
 :doctype: article
 :toc: left
 :source-highlighter: rouge

fields/bitfield.adoc

@@ -14,6 +14,7 @@ Since **v2** of the specification it is also allowed to use
 The **&lt;bitfield&gt;** field has all the <<fields-common, common>> properties
 as well as extra properties and elements described below.
 
+[[fields-bitfield-member-fields]]
 ==== Member Fields ====
 Member fields need to be listed as children XML elements of the **&lt;bitfield&gt;**.
 Every such member is expected to use **bitLength** property to specify its
@@ -69,6 +70,7 @@ of the **&lt;bitfield&gt;**, then all the members must be wrapped in
 </schema>
 ----
 
+[[fields-bitfield-endian]]
 ==== Endian ====
 When serializing, the **&lt;bitfield&gt;** object needs to combine the
 values of all the members into single unsigned raw value of appropriate length,
@@ -87,4 +89,58 @@ is overridden using extra **endian** property of the **&lt;bitfield&gt;** field.
 </schema>
 ----
 
+[[fields-bitfield-replacing-member-fields]]
+==== Replacing Member Fields ====
+It is possible to replace some of the copied member fields after 
+<<fields-common-reusing-other-fields, reuse>> using **&lt;replace&gt;**
+child node, which wraps the replacing fields.
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<schema name="MyProtocol" endian="big">
+    <fields>
+        <bitfield name="SomeBitfield" endian="little">
+            <int name="Mem1" type="uint8" bitLength="4" />
+            <enum name="Mem2" type="uint8" bitLength="4">
+                <validValue name="V0" val="0" />
+                <validValue name="V1" val="1" />
+            </enum>
+        </bitfield>
+        
+        <bitfield name="SomeOtherBitfield" reuse="SomeBitfield">
+            <replace>
+                <set name="Mem2" type="uint8" bitLength="4">
+                    <bit name="B0" idx="0" />
+                    <bit name="B1" idx="1" />
+                </set>
+            </replace>
+        </bitfield>
+    </fields>
+</schema>
+----
+The replacing field must have the same name as the reused member field it is
+replacing. The **&lt;replace&gt;** child node may have multiple member fields replacing
+the copied ones. The order of the fields inside the **&lt;replace&gt;** child node
+is not important, the order of the fields is determined by the original 
+**&lt;bitfield&gt;** field, which was <<fields-common-reusing-other-fields, reused>>.
+
+The example above is equivalent to defining `SomeOtherBitfield` **&lt;bitfield&gt;** field
+in the following way.
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<schema name="MyProtocol" endian="big">
+    <fields>
+        <bitfield name="SomeOtherBitfield">
+            <int name="Mem1" type="uint8" bitLength="4" />
+            <set name="Mem2" type="uint8" bitLength="4">
+                <bit name="B0" idx="0" />
+                <bit name="B1" idx="1" />
+            </set>
+        </bitfield>
+    </fields>
+</schema>
+----
+
 Use <<appendix-bitfield, properties table>> for future references.