Skip to content

Commit 80d5905

Browse files
arobenkoarobenko
committed
Release v3.0
2 parents a4b7ad9 + 4824533 commit 80d5905

File tree

15 files changed

+275
-20
lines changed

15 files changed

+275
-20
lines changed

‎SUMMARY.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
* [Referencing Values of Other Fields](fields/references.md)
3131
* [Messages](messages/messages.md)
3232
* [Interfaces](interfaces/interfaces.md)
33+
* [Aliases](aliases/aliases.md)
3334
* [Frames](frames/frames.md)
3435
* [Common Properties of Layers](frames/common.md)
3536
* [payload Layer](frames/payload.md)
@@ -58,6 +59,7 @@
5859
* [Units](appendix/units.md)
5960
* [Properties of message](appendix/message.md)
6061
* [Properties of interface](appendix/interface.md)
62+
* [Properties of alias](appendix/alias.md)
6163
* [Properties of frame](appendix/frame.md)
6264
* [Common Properties of Layers](appendix/layers.md)
6365
* [Properties of checksum Layer](appendix/checksum.md)

‎aliases/aliases.md

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Aliases
2+
It is not uncommon for a particular field to change its meaning and as the
3+
result to change its name over time when the protocol evolves. Simple change
4+
of the name in the schema may result in various compilation errors of old
5+
client code when new version of the protocol definition library is released.
6+
To help with such case the **CommsDSL** introduces an ability to create
7+
**alias** names for the existing fields.
8+
9+
For example let's assume there is some message definition like the one below:
10+
```
11+
<?xml version="1.0" encoding="UTF-8"?>
12+
<schema ...>
13+
<message name="Msg1" id="0x1">
14+
<int name="SomeField" type="uint32" />
15+
...
16+
</message>
17+
</schema>
18+
```
19+
In case there is a need to rename the **SomeField** name to be **SomeOtherField**,
20+
then the message definition can add an **&lt;alias&gt;** with the old name to
21+
the renamed field in order to keep the old client code compiling.
22+
```
23+
<?xml version="1.0" encoding="UTF-8"?>
24+
<schema ...>
25+
<message name="Msg1" id="0x1">
26+
<fields>
27+
<int name="SomeOtherField" type="uint32" />
28+
...
29+
</fields>
30+
<alias name="SomeField" field="$SomeOtherField" />
31+
</message>
32+
</schema>
33+
```
34+
In such case the code generator must allow access of the renamed field by
35+
both old and new names.
36+
37+
Note that the message fields must be bundled in **&lt;fields&gt;** XML element
38+
in order to allow usage of non-field definition **&lt;alias&gt;** XML child of
39+
the **&lt;message&gt;** node.
40+
41+
Also note that value of the **field** property of the **&lt;alias&gt;** element
42+
must start with `$` character to indicate that the referenced field is a sibling
43+
one, similar to [&lt;optional&gt;](../fields/optional.md) field conditions.
44+
45+
Quite often, in order to keep protocol backward compatible, developers convert
46+
existing numeric field into a [&lt;bitfield&gt;](../fields/bitfield.md) when
47+
need arises to add some extra field to the message. For example, let's assume
48+
there was an enum field with limited number of valid values:
49+
```
50+
<?xml version="1.0" encoding="UTF-8"?>
51+
<schema ...>
52+
<message name="Msg1" id="0x1">
53+
<enum name="SomeEnum" type="uint8">
54+
<validValue name="V1" val="0" />
55+
<validValue name="V2" val="1" />
56+
<validValue name="V3" val="2" />
57+
</enum>
58+
...
59+
</message>
60+
</schema>
61+
```
62+
When need arises to introduce new value the developer may decide to save I/O
63+
traffic reuse the same byte occupied by the `SomeEnum` field, like below.
64+
```
65+
<?xml version="1.0" encoding="UTF-8"?>
66+
<schema ...>
67+
<message name="Msg1" id="0x1">
68+
<bitfield name="F1"
69+
<enum name="SomeEnum" type="uint8" bitLength="2">
70+
<validValue name="V1" val="0" />
71+
<validValue name="V2" val="1" />
72+
<validValue name="V3" val="2" />
73+
</enum>
74+
<int name="SomeInt" type="uint8" bitLength="6"
75+
</bitfield>
76+
...
77+
</message>
78+
</schema>
79+
```
80+
In order to keep old client code compiling it is possible to introduce
81+
alias to the `SomeEnum` member of the [&lt;bitfield&gt;](../fields/bitfield.md)
82+
like this:
83+
```
84+
<?xml version="1.0" encoding="UTF-8"?>
85+
<schema ...>
86+
<message name="Msg1" id="0x1">
87+
<fields>
88+
<bitfield name="F1"
89+
<enum name="SomeEnum" type="uint8" bitLength="2">
90+
...
91+
</enum>
92+
<int name="SomeInt" type="uint8" bitLength="6"
93+
</bitfield>
94+
...
95+
</fields>
96+
<alias name="SomeEnum" field="$F1.SomeEnum" />
97+
</message>
98+
</schema>
99+
```
100+
There can be any number of different **&lt;alias&gt;** nodes. The elements
101+
that are allowed to have **&lt;alias&gt;**-es are [&lt;message&gt;](../messages/messages.md),
102+
[&lt;interface&gt;](../interfaces/interfaces.md), and [&lt;bundle&gt;](../fields/bundle.md).
103+
104+
#### Description
105+
The **&lt;alias&gt;** node may also have **description**
106+
[property](../intro/properties.md) which is expected to find its way into
107+
the generated code as a comment for the relevant access functions.
108+
```
109+
<?xml version="1.0" encoding="UTF-8"?>
110+
<schema ...>
111+
<message name="Msg1" id="1">
112+
...
113+
<alias name="SomeField" field="SomeOtherField">
114+
<description>
115+
Some long
116+
multiline
117+
description
118+
</description>
119+
</alias>
120+
</message>
121+
</schema>
122+
```
123+
124+
#### More on Aliases in &lt;message&gt;-es
125+
When a new [&lt;message&gt;](../messages/messages.md) is defined it can
126+
copy all the fields from other already defined [&lt;message&gt;](../messages/messages.md)
127+
(using **copyFieldsFrom** [property](../intro/properties.md)).
128+
By default all the [&lt;alias&gt;](../aliases/aliases.md) definitions are also copied.
129+
It is possible to modify this default behavior by using **copyFieldsAliases**
130+
[property](../intro/properties.md) with [boolean](../intro/boolean.md) value.
131+
```
132+
<?xml version="1.0" encoding="UTF-8"?>
133+
<schema ...>
134+
<message name="Msg1" id="1">
135+
...
136+
</message>
137+
138+
<message name="Msg2" id="2" copyFieldsAliases="false">
139+
...
140+
</message>
141+
142+
</schema>
143+
```
144+
145+
#### More on Aliases in &lt;interface&gt;-es
146+
Similar to [&lt;message&gt;](../messages/messages.md)-es
147+
[&lt;interface&gt;](../interfaces/interfaces.md) can also use **copyFieldsFrom**
148+
[property](../intro/properties.md) to copy its field from some other
149+
[&lt;interface&gt;](../interfaces/interfaces.md) definition and have all
150+
the aliases copied by default. The control of such default copying behavior
151+
is also done by using **copyFieldsAliases**
152+
[property](../intro/properties.md) with [boolean](../intro/boolean.md) value.
153+
```
154+
<?xml version="1.0" encoding="UTF-8"?>
155+
<schema ...>
156+
<interface name="Interface1">
157+
...
158+
</interface>
159+
160+
<interface name="Interface2" copyFieldsAliases="false">
161+
...
162+
</interface>
163+
164+
</schema>
165+
```
166+
167+
#### More on Aliases in &lt;bundle&gt;-es
168+
When a new [&lt;bundle&gt;](../fields/bundle.md) field is defined it can
169+
reuse definition of already defined other [&lt;bundle&gt;](../fields/bundle.md)
170+
(using **reuse** [property](../intro/properties.md)).
171+
By default all the [&lt;alias&gt;](../aliases/aliases.md) definitions are also copied.
172+
It is possible to modify this default behavior by using **reuseAliases**
173+
[property](../intro/properties.md) with [boolean](../intro/boolean.md) value.
174+
```
175+
<?xml version="1.0" encoding="UTF-8"?>
176+
<schema ...>
177+
<fields>
178+
<bundle name="B1">
179+
...
180+
<alias .../>
181+
<alias .../>
182+
</bundle>
183+
184+
<bundle name="B2" reuse="B1" reuseAliases="false">
185+
...
186+
</bundle>
187+
</fields>
188+
</schema>
189+
```
190+
191+
Use [properties table](../appendix/alias.md) for future references.
192+
193+

‎appendix/alias.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
## Properties of &lt;alias&gt;
2+
Refer to [Aliases](../aliases/aliases.md) chapter for detailed description.
3+
Introduced in DSL version **3**.
4+
5+
|Property Name|Allowed type / value|DSL Version|Required|Default Value|Description|
6+
|:-----------:|:------------------:|:---------:|:------:|:-----------:|-----------|
7+
|**name**|[name](../intro/names.md) string|3|yes||Name of the alias.|
8+
|**description**|string|3|no||Human readable description of the alias.|
9+
|**field**|relative [reference](../intro/references.md) string|3|yes||Reference to the aliased field, must start with `$` character.|
10+

‎appendix/bitfield.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ for detailed description.
88
|**endian**|"big" or "little"|1|no|endian of [schema](../schema/schema.md)|Endian of the field.|
99

1010

11-
The **&lt;bitfield&gt;** field also allows listing of member fields using
12-
**&lt;members&gt;** child XML element.
11+
Extra child XML elements allowed:
1312

13+
|XML Element|DSL Version|Description|
14+
|:---------:|:---------:|-----------|
15+
|**&lt;members&gt;**|1|Wraps member fields.|

‎appendix/bundle.md

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,16 @@
11
## Properties of &lt;bundle&gt; Field
2-
The **&lt;bundle&gt;** field has all the [common](fields.md) properties.
3-
Refer to [&lt;bundle&gt; Field](../fields/bundle.md) chapter
2+
The **&lt;bundle&gt;** field has all the [common](fields.md) properties as
3+
well as ones listed below. Refer to [&lt;bundle&gt; Field](../fields/bundle.md) chapter
44
for detailed description.
55

6-
The **&lt;bundle&gt;** field also allows listing of member fields using
7-
**&lt;members&gt;** child XML element.
6+
|Property Name|Allowed type / value|DSL Version|Required|Default Value|Description|
7+
|:-----------:|:------------------:|:---------:|:------:|:-----------:|-----------|
8+
|**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.|
9+
10+
Extra child XML elements allowed:
11+
12+
|XML Element|DSL Version|Description|
13+
|:---------:|:---------:|-----------|
14+
|**&lt;members&gt;**|1|Wraps member fields.|
15+
|**&lt;alias&gt;**|3|Alias names for other member fields. See [Aliases](../aliases/aliases.md) for more info.|
816

‎appendix/frame.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ for detailed description.
77
|**name**|[name](../intro/names.md) string|1|yes||Name of the frame.|
88
|**description**|string|1|no||Human readable description of the frame.|
99

10-
The **&lt;frame&gt;** also allows listing of layers using
11-
**&lt;layers&gt;** child XML element.
10+
Extra child XML elements allowed:
11+
12+
|XML Element|DSL Version|Description|
13+
|:---------:|:---------:|-----------|
14+
|**&lt;layers&gt;**|1|Wraps member layers.|
1215

‎appendix/interface.md

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,13 @@ for detailed description.
77
|**name**|[name](../intro/names.md) string|1|yes||Name of the interface.|
88
|**description**|string|1|no||Human readable description of the interface.|
99
|**copyFieldsFrom**|[reference](../intro/references.md) string|1|no||Interface definition from which fields need to be copied.|
10+
|**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).|
1011

11-
The **&lt;interfaces&gt;** also allows listing of fields using
12-
**&lt;fields&gt;** child XML element.
12+
13+
Extra child XML elements allowed:
14+
15+
|XML Element|DSL Version|Description|
16+
|:---------:|:---------:|-----------|
17+
|**&lt;fields&gt;**|1|Wraps member fields.|
18+
|**&lt;alias&gt;**|3|Alias names for other member fields. See [Aliases](../aliases/aliases.md) for more info.|
1319

‎appendix/message.md

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ for detailed description.
66
|:-----------:|:------------------:|:---------:|:------:|:-----------:|-----------|
77
|**name**|[name](../intro/names.md) string|1|yes||Name of the message.|
88
|**id**|[numeric](../intro/numeric.md)|1|yes||Numeric ID of the message.|
9-
|**description**|string|1|no||Human readable description of the interface.|
9+
|**description**|string|1|no||Human readable description of the message.|
1010
|**displayName**|string|1|no||Name of the message to display. If empty, the code generator must use value of property **name** instead.|
1111
|**copyFieldsFrom**|[reference](../intro/references.md) string|1|no||Message definition from which fields need to be copied.|
1212
|**order**|[numeric](../intro/numeric.md)|1|no|0|Relative order of the messages with the same **id**.|
@@ -15,8 +15,12 @@ for detailed description.
1515
|**removed**|[bool](../intro/boolean.md)|1|no|false|Indicates whether deprecated message has been removed from being supported.|
1616
|**sender**|"both", "client", "server"|1|no|both|Endpoint that sends the message.|
1717
|**customizable**|[bool](../intro/boolean.md)|1|no|false|Mark the message to allow compile time customization regardless of code generator's level of customization.|
18+
|**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).|
1819

20+
Extra child XML elements allowed:
1921

20-
The **&lt;message&gt;** also allows listing of fields using
21-
**&lt;fields&gt;** child XML element.
22+
|XML Element|DSL Version|Description|
23+
|:---------:|:---------:|-----------|
24+
|**&lt;fields&gt;**|1|Wraps member fields.|
25+
|**&lt;alias&gt;**|3|Alias names for other member fields. See [Aliases](../aliases/aliases.md) for more info.|
2226

‎appendix/optional.md

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,16 @@ for detailed description.
1111
|**displayExtModeCtrl**|[bool](../intro/boolean.md)|1|no|false|Disable manual update of the mode in GUI analysis tools.|
1212

1313
Inner field must be specified using **field** property or as
14-
child XML element. The **&lt;optional&gt;** field also allows wrapping of inner field using
15-
**&lt;field&gt;** child XML element.
14+
child XML element.
1615

17-
Multiple conditions can be wrapped in either **&lt;and&gt;** or **&lt;or&gt;**
18-
child XML element.
16+
Extra child XML elements allowed:
17+
18+
|XML Element|DSL Version|Description|
19+
|:---------:|:---------:|-----------|
20+
|**&lt;field&gt;**|1|Wraps member field.|
21+
|**&lt;cond&gt;**|1|Condition when field exists.|
22+
|**&lt;and&gt;**|1|Logical "and" of conditions.|
23+
|**&lt;or&gt;**|1|Logical "or" of conditions.|
1924

2025
#### Default Mode Strings
2126
|Mode|Accepted Values (case insensitive)|

‎appendix/variant.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@ for detailed description.
99
|**displayIdxReadOnlyHidden**|[bool](../intro/boolean.md)|1|no|false|Hide active index of the member when field displayed in read-only mode.|
1010

1111

12-
The **&lt;variant&gt;** field also allows listing of member fields using
13-
**&lt;members&gt;** child XML element.
12+
Extra child XML elements allowed:
13+
14+
|XML Element|DSL Version|Description|
15+
|:---------:|:---------:|-----------|
16+
|**&lt;members&gt;**|1|Wraps member fields.|
1417

‎book.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"title" : "CommsDSL Specification",
3+
"author" : "Alex Robenko (arobenko@gmail.com)"
4+
}

‎fields/bundle.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,4 +71,9 @@ to all the properties. Any new defined member field gets **appended** to the cop
7171
```
7272
In the example above *SomeOtherBundle* has **3** member fields: *F1*, *F2*, and *F3*.
7373

74+
#### Alias Names to Member Fields
75+
Sometimes an existing member field may be renamed and/or moved. It is possible to
76+
create alias names for the fields to keep the old client code being able to compile
77+
and work. Please refer to [Aliases](../aliases/aliases.md) chapter for more details.
78+
7479
Use [properties table](../appendix/bundle.md) for future references.

‎interfaces/interfaces.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,4 +106,9 @@ having "version" value as **semanticType** property, will be considered
106106
for fields that, were introduced and/or deprecated at some stage, i.e. use
107107
**sinceVersion** and/or **derecated** + **removed** properties.
108108

109+
#### Alias Names to Fields
110+
Sometimes an contained field may be renamed and/or moved. It is possible to
111+
create alias names for the fields to keep the old client code being able to compile
112+
and work. Please refer to [Aliases](../aliases/aliases.md) chapter for more details.
113+
109114
Use [properties table](../appendix/interface.md) for future references.

‎intro/version.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
## Version
2-
Current version of this document is **2.1**
2+
Current version of this document is **3.0**
33

44
This document is versioned using [Semantic Versioning](https://semver.org/)
55
without **MAJOR** number (in intension not to have any non-backward compatible changes).

‎messages/messages.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -313,5 +313,10 @@ customizable at compile time.
313313
</schema>
314314
```
315315

316+
#### Alias Names to Member Fields
317+
Sometimes an existing member field may be renamed and/or moved. It is possible to
318+
create alias names for the fields to keep the old client code being able to compile
319+
and work. Please refer to [Aliases](../aliases/aliases.md) chapter for more details.
320+
316321
Use [properties table](../appendix/message.md) for future references.
317322

0 commit comments

Comments
 (0)