Release v3.0

commschamp · Oct 18, 2019 · 80d5905 · 80d5905
2 parents a4b7ad9 + 4824533
commit 80d5905
Show file tree

Hide file tree

Showing 15 changed files with 275 additions and 20 deletions.
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -30,6 +30,7 @@
     * [Referencing Values of Other Fields](fields/references.md)    
 * [Messages](messages/messages.md)
 * [Interfaces](interfaces/interfaces.md)
+* [Aliases](aliases/aliases.md)
 * [Frames](frames/frames.md)
     * [Common Properties of Layers](frames/common.md)
     * [payload Layer](frames/payload.md)
@@ -58,6 +59,7 @@
     * [Units](appendix/units.md)
     * [Properties of message](appendix/message.md)
     * [Properties of interface](appendix/interface.md)
+    * [Properties of alias](appendix/alias.md)    
     * [Properties of frame](appendix/frame.md)
     * [Common Properties of Layers](appendix/layers.md)
     * [Properties of checksum Layer](appendix/checksum.md)

diff --git a/aliases/aliases.md b/aliases/aliases.md
@@ -0,0 +1,193 @@
+# Aliases
+It is not uncommon for a particular field to change its meaning and as the
+result to change its name over time when the protocol evolves. Simple change
+of the name in the schema may result in various compilation errors of old
+client code when new version of the protocol definition library is released.
+To help with such case the **CommsDSL** introduces an ability to create
+**alias** names for the existing fields.
+
+For example let's assume there is some message definition like the one below:
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <message name="Msg1" id="0x1">
+        <int name="SomeField" type="uint32" />
+        ...
+    </message>
+</schema> 
+```
+In case there is a need to rename the **SomeField** name to be **SomeOtherField**,
+then the message definition can add an **&lt;alias&gt;** with the old name to
+the renamed field in order to keep the old client code compiling. 
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <message name="Msg1" id="0x1">
+        <fields>
+            <int name="SomeOtherField" type="uint32" />
+            ...
+        </fields>
+        <alias name="SomeField" field="$SomeOtherField" />
+    </message>
+</schema> 
+```
+In such case the code generator must allow access of the renamed field by
+both old and new names.
+
+Note that the message fields must be bundled in **&lt;fields&gt;** XML element
+in order to allow usage of non-field definition **&lt;alias&gt;** XML child of
+the **&lt;message&gt;** node.
+
+Also note that value of the **field** property of the **&lt;alias&gt;** element
+must start with `$` character to indicate that the referenced field is a sibling
+one, similar to [&lt;optional&gt;](../fields/optional.md) field conditions.
+
+Quite often, in order to keep protocol backward compatible, developers convert
+existing numeric field into a [&lt;bitfield&gt;](../fields/bitfield.md) when
+need arises to add some extra field to the message. For example, let's assume
+there was an enum field with limited number of valid values:
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <message name="Msg1" id="0x1">
+        <enum name="SomeEnum" type="uint8">
+            <validValue name="V1" val="0" />
+            <validValue name="V2" val="1" />
+            <validValue name="V3" val="2" />
+        </enum>
+        ...
+    </message>
+</schema> 
+```
+When need arises to introduce new value the developer may decide to save I/O
+traffic reuse the same byte occupied by the `SomeEnum` field, like below.
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <message name="Msg1" id="0x1">
+        <bitfield name="F1"
+            <enum name="SomeEnum" type="uint8" bitLength="2">
+                <validValue name="V1" val="0" />
+                <validValue name="V2" val="1" />
+                <validValue name="V3" val="2" />
+            </enum>
+            <int name="SomeInt" type="uint8" bitLength="6"
+        </bitfield>
+        ...
+    </message>
+</schema> 
+```
+In order to keep old client code compiling it is possible to introduce
+alias to the `SomeEnum` member of the [&lt;bitfield&gt;](../fields/bitfield.md) 
+like this:
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <message name="Msg1" id="0x1">
+        <fields>
+            <bitfield name="F1"
+                <enum name="SomeEnum" type="uint8" bitLength="2">
+                    ...
+                </enum>
+                <int name="SomeInt" type="uint8" bitLength="6"
+            </bitfield>
+            ...
+        </fields>
+        <alias name="SomeEnum" field="$F1.SomeEnum" />
+    </message>
+</schema> 
+```
+There can be any number of different **&lt;alias&gt;** nodes. The elements
+that are allowed to have **&lt;alias&gt;**-es are [&lt;message&gt;](../messages/messages.md),
+[&lt;interface&gt;](../interfaces/interfaces.md), and [&lt;bundle&gt;](../fields/bundle.md).
+
+#### Description
+The **&lt;alias&gt;** node may also have **description** 
+[property](../intro/properties.md) which is expected to find its way into
+the generated code as a comment for the relevant access functions.
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <message name="Msg1" id="1">
+        ...
+        <alias name="SomeField" field="SomeOtherField">
+            <description>
+                Some long
+                multiline
+                description
+            </description>
+        </alias>
+    </message>
+</schema>
+```
+
+#### More on Aliases in &lt;message&gt;-es
+When a new [&lt;message&gt;](../messages/messages.md) is defined it can
+copy all the fields from other already defined [&lt;message&gt;](../messages/messages.md)
+(using **copyFieldsFrom** [property](../intro/properties.md)).
+By default all the [&lt;alias&gt;](../aliases/aliases.md) definitions are also copied.
+It is possible to modify this default behavior by using **copyFieldsAliases** 
+[property](../intro/properties.md) with [boolean](../intro/boolean.md) value.
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <message name="Msg1" id="1">
+        ...
+    </message>
+
+    <message name="Msg2" id="2" copyFieldsAliases="false">
+        ...
+    </message>
+    
+</schema>
+```
+
+#### More on Aliases in &lt;interface&gt;-es
+Similar to [&lt;message&gt;](../messages/messages.md)-es 
+[&lt;interface&gt;](../interfaces/interfaces.md) can also use **copyFieldsFrom** 
+[property](../intro/properties.md) to copy its field from some other 
+[&lt;interface&gt;](../interfaces/interfaces.md) definition and have all
+the aliases copied by default. The control of such default copying behavior
+is also done by using **copyFieldsAliases** 
+[property](../intro/properties.md) with [boolean](../intro/boolean.md) value.
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <interface name="Interface1">
+        ...
+    </interface>
+
+    <interface name="Interface2" copyFieldsAliases="false">
+        ...
+    </interface>
+    
+</schema>
+```
+
+#### More on Aliases in &lt;bundle&gt;-es
+When a new [&lt;bundle&gt;](../fields/bundle.md) field is defined it can
+reuse definition of already defined other [&lt;bundle&gt;](../fields/bundle.md)
+(using **reuse** [property](../intro/properties.md)).
+By default all the [&lt;alias&gt;](../aliases/aliases.md) definitions are also copied.
+It is possible to modify this default behavior by using **reuseAliases** 
+[property](../intro/properties.md) with [boolean](../intro/boolean.md) value.
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<schema ...>
+    <fields>
+        <bundle name="B1">
+            ...
+            <alias .../>
+            <alias .../>
+        </bundle>
+
+        <bundle name="B2" reuse="B1" reuseAliases="false">
+            ...
+        </bundle>
+    </fields>
+</schema>
+```
+
+Use [properties table](../appendix/alias.md) for future references.
+
+
diff --git a/appendix/alias.md b/appendix/alias.md
@@ -0,0 +1,10 @@
+## Properties of &lt;alias&gt;
+Refer to [Aliases](../aliases/aliases.md) chapter for detailed description. 
+Introduced in DSL version **3**.
+
+|Property Name|Allowed type / value|DSL Version|Required|Default Value|Description|
+|:-----------:|:------------------:|:---------:|:------:|:-----------:|-----------|
+|**name**|[name](../intro/names.md) string|3|yes||Name of the alias.|
+|**description**|string|3|no||Human readable description of the alias.|
+|**field**|relative [reference](../intro/references.md) string|3|yes||Reference to the aliased field, must start with `$` character.|
+
diff --git a/appendix/bitfield.md b/appendix/bitfield.md
@@ -8,6 +8,8 @@ for detailed description.
 |**endian**|"big" or "little"|1|no|endian of [schema](../schema/schema.md)|Endian of the field.|
 
 
-The **&lt;bitfield&gt;** field also allows listing of member fields using
-**&lt;members&gt;** child XML element.
+Extra child XML elements allowed:
 
+|XML Element|DSL Version|Description|
+|:---------:|:---------:|-----------|
+|**&lt;members&gt;**|1|Wraps member fields.|
diff --git a/appendix/bundle.md b/appendix/bundle.md
@@ -1,8 +1,16 @@
 ## Properties of &lt;bundle&gt; Field
-The **&lt;bundle&gt;** field has all the [common](fields.md) properties. 
-Refer to [&lt;bundle&gt; Field](../fields/bundle.md) chapter
+The **&lt;bundle&gt;** field has all the [common](fields.md) properties as
+well as ones listed below. Refer to [&lt;bundle&gt; Field](../fields/bundle.md) chapter
 for detailed description. 
 
-The **&lt;bundle&gt;** field also allows listing of member fields using
-**&lt;members&gt;** child XML element.
+|Property Name|Allowed type / value|DSL Version|Required|Default Value|Description|
+|:-----------:|:------------------:|:---------:|:------:|:-----------:|-----------|
+|**reuseAliases**|[bool](../intro/boolean.md)|3|no|true|Control copy of the defined [aliases](../aliases/aliases.md) from reused other [&lt;bundle&gt;](../fields/bundle.md) when  **reuse** property is used.|
+
+Extra child XML elements allowed:
+
+|XML Element|DSL Version|Description|
+|:---------:|:---------:|-----------|
+|**&lt;members&gt;**|1|Wraps member fields.|
+|**&lt;alias&gt;**|3|Alias names for other member fields. See [Aliases](../aliases/aliases.md) for more info.|
 
diff --git a/appendix/frame.md b/appendix/frame.md
@@ -7,6 +7,9 @@ for detailed description.
 |**name**|[name](../intro/names.md) string|1|yes||Name of the frame.|
 |**description**|string|1|no||Human readable description of the frame.|
 
-The **&lt;frame&gt;** also allows listing of layers using
-**&lt;layers&gt;** child XML element.
+Extra child XML elements allowed:
+
+|XML Element|DSL Version|Description|
+|:---------:|:---------:|-----------|
+|**&lt;layers&gt;**|1|Wraps member layers.|
 
diff --git a/appendix/interface.md b/appendix/interface.md
@@ -7,7 +7,13 @@ for detailed description.
 |**name**|[name](../intro/names.md) string|1|yes||Name of the interface.|
 |**description**|string|1|no||Human readable description of the interface.|
 |**copyFieldsFrom**|[reference](../intro/references.md) string|1|no||Interface definition from which fields need to be copied.|
+|**copyFieldsAliases**|[bool](../intro/boolean.md)|3|no|true|Control copy of the defined [aliases](../aliases/aliases.md) when **copyFieldsFrom** property is used to copy fields from the other [&lt;interface&gt;](../interfaces/interfaces.md).|
 
-The **&lt;interfaces&gt;** also allows listing of fields using
-**&lt;fields&gt;** child XML element.
+
+Extra child XML elements allowed:
+
+|XML Element|DSL Version|Description|
+|:---------:|:---------:|-----------|
+|**&lt;fields&gt;**|1|Wraps member fields.|
+|**&lt;alias&gt;**|3|Alias names for other member fields. See [Aliases](../aliases/aliases.md) for more info.|
 
diff --git a/appendix/message.md b/appendix/message.md
@@ -6,7 +6,7 @@ for detailed description.
 |:-----------:|:------------------:|:---------:|:------:|:-----------:|-----------|
 |**name**|[name](../intro/names.md) string|1|yes||Name of the message.|
 |**id**|[numeric](../intro/numeric.md)|1|yes||Numeric ID of the message.|
-|**description**|string|1|no||Human readable description of the interface.|
+|**description**|string|1|no||Human readable description of the message.|
 |**displayName**|string|1|no||Name of the message to display. If empty, the code generator must use value of property **name** instead.|
 |**copyFieldsFrom**|[reference](../intro/references.md) string|1|no||Message definition from which fields need to be copied.|
 |**order**|[numeric](../intro/numeric.md)|1|no|0|Relative order of the messages with the same **id**.|
@@ -15,8 +15,12 @@ for detailed description.
 |**removed**|[bool](../intro/boolean.md)|1|no|false|Indicates whether deprecated message has been removed from being supported.|
 |**sender**|"both", "client", "server"|1|no|both|Endpoint that sends the message.| 
 |**customizable**|[bool](../intro/boolean.md)|1|no|false|Mark the message to allow compile time customization regardless of code generator's level of customization.|
+|**copyFieldsAliases**|[bool](../intro/boolean.md)|3|no|true|Control copy of the defined [aliases](../aliases/aliases.md) when **copyFieldsFrom** property is used to copy fields from the other [&lt;message&gt;](../messages/messages.md).|
 
+Extra child XML elements allowed:
 
-The **&lt;message&gt;** also allows listing of fields using
-**&lt;fields&gt;** child XML element.
+|XML Element|DSL Version|Description|
+|:---------:|:---------:|-----------|
+|**&lt;fields&gt;**|1|Wraps member fields.|
+|**&lt;alias&gt;**|3|Alias names for other member fields. See [Aliases](../aliases/aliases.md) for more info.|
 
diff --git a/appendix/optional.md b/appendix/optional.md
@@ -11,11 +11,16 @@ for detailed description.
 |**displayExtModeCtrl**|[bool](../intro/boolean.md)|1|no|false|Disable manual update of the mode in GUI analysis tools.|
 
 Inner field must be specified using **field** property or as 
-child XML element. The **&lt;optional&gt;** field also allows wrapping of inner field using
-**&lt;field&gt;** child XML element.
+child XML element. 
 
-Multiple conditions can be wrapped in either **&lt;and&gt;** or **&lt;or&gt;**
-child XML element.
+Extra child XML elements allowed:
+
+|XML Element|DSL Version|Description|
+|:---------:|:---------:|-----------|
+|**&lt;field&gt;**|1|Wraps member field.|
+|**&lt;cond&gt;**|1|Condition when field exists.|
+|**&lt;and&gt;**|1|Logical "and" of conditions.|
+|**&lt;or&gt;**|1|Logical "or" of conditions.|
 
 #### Default Mode Strings
 |Mode|Accepted Values (case insensitive)|

diff --git a/appendix/variant.md b/appendix/variant.md
@@ -9,6 +9,9 @@ for detailed description.
 |**displayIdxReadOnlyHidden**|[bool](../intro/boolean.md)|1|no|false|Hide active index of the member when field displayed in read-only mode.|
 
 
-The **&lt;variant&gt;** field also allows listing of member fields using
-**&lt;members&gt;** child XML element.
+Extra child XML elements allowed:
+
+|XML Element|DSL Version|Description|
+|:---------:|:---------:|-----------|
+|**&lt;members&gt;**|1|Wraps member fields.|
 
diff --git a/book.json b/book.json
@@ -0,0 +1,4 @@
+{
+    "title" : "CommsDSL Specification",
+    "author" : "Alex Robenko (arobenko@gmail.com)"
+}
diff --git a/fields/bundle.md b/fields/bundle.md
@@ -71,4 +71,9 @@ to all the properties. Any new defined member field gets **appended** to the cop
 ```
 In the example above *SomeOtherBundle* has **3** member fields: *F1*, *F2*, and *F3*.
 
+#### Alias Names to Member Fields
+Sometimes an existing member field may be renamed and/or moved. It is possible to
+create alias names for the fields to keep the old client code being able to compile
+and work. Please refer to [Aliases](../aliases/aliases.md) chapter for more details.
+
 Use [properties table](../appendix/bundle.md) for future references.
diff --git a/interfaces/interfaces.md b/interfaces/interfaces.md
@@ -106,4 +106,9 @@ having "version" value as **semanticType** property, will be considered
 for fields that, were introduced and/or deprecated at some stage, i.e. use
 **sinceVersion** and/or **derecated** + **removed** properties.
 
+#### Alias Names to Fields
+Sometimes an contained field may be renamed and/or moved. It is possible to
+create alias names for the fields to keep the old client code being able to compile
+and work. Please refer to [Aliases](../aliases/aliases.md) chapter for more details.
+
 Use [properties table](../appendix/interface.md) for future references.
diff --git a/intro/version.md b/intro/version.md
@@ -1,5 +1,5 @@
 ## Version
-Current version of this document is **2.1**
+Current version of this document is **3.0**
 
 This document is versioned using [Semantic Versioning](https://semver.org/) 
 without **MAJOR** number (in intension not to have any non-backward compatible changes).

diff --git a/messages/messages.md b/messages/messages.md
@@ -313,5 +313,10 @@ customizable at compile time.
 </schema>
 ```
 
+#### Alias Names to Member Fields
+Sometimes an existing member field may be renamed and/or moved. It is possible to
+create alias names for the fields to keep the old client code being able to compile
+and work. Please refer to [Aliases](../aliases/aliases.md) chapter for more details.
+
 Use [properties table](../appendix/message.md) for future references.