cddl 0.8.4 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -3
- package/build/cli/commands/repl.d.ts.map +1 -1
- package/build/cli/commands/validate.d.ts.map +1 -1
- package/build/cli/commands/validate.js +1 -1
- package/build/lexer.d.ts.map +1 -1
- package/build/lexer.js +1 -3
- package/build/parser.d.ts.map +1 -1
- package/build/parser.js +26 -0
- package/docs/README.md +47 -0
- package/docs/arrays.md +356 -0
- package/docs/ast-structure.md +166 -0
- package/docs/basic-types.md +243 -0
- package/docs/comments.md +307 -0
- package/docs/groups.md +351 -0
- package/docs/operators.md +466 -0
- package/docs/properties.md +334 -0
- package/docs/ranges.md +339 -0
- package/docs/references.md +340 -0
- package/docs/variables.md +335 -0
- package/package.json +8 -8
package/docs/groups.md
ADDED
|
@@ -0,0 +1,351 @@
|
|
|
1
|
+
# Groups
|
|
2
|
+
|
|
3
|
+
Groups are a fundamental building block of CDDL definitions. They define a collection of properties and are used to represent structured data. This document explains how groups are represented in the AST.
|
|
4
|
+
|
|
5
|
+
## Group Definition
|
|
6
|
+
|
|
7
|
+
In the AST, a group is represented by the following structure:
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
export type Group = {
|
|
11
|
+
Type: 'group'
|
|
12
|
+
Name: string
|
|
13
|
+
IsChoiceAddition: boolean
|
|
14
|
+
Properties: (Property|Property[])[]
|
|
15
|
+
Comments: Comment[]
|
|
16
|
+
}
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Where:
|
|
20
|
+
- `Type`: Always set to 'group' to identify this node as a group
|
|
21
|
+
- `Name`: The name of the group
|
|
22
|
+
- `IsChoiceAddition`: A boolean indicating if this group is a choice addition (using the `/=` operator)
|
|
23
|
+
- `Properties`: An array of property definitions or property choice arrays
|
|
24
|
+
- `Comments`: An array of comments associated with the group
|
|
25
|
+
|
|
26
|
+
## Group Properties
|
|
27
|
+
|
|
28
|
+
The properties of a group define its structure. Each property can be one of:
|
|
29
|
+
|
|
30
|
+
1. A single property definition:
|
|
31
|
+
```typescript
|
|
32
|
+
Property
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
2. An array of property definitions for choices:
|
|
36
|
+
```typescript
|
|
37
|
+
Property[]
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
This allows for representing properties with alternatives.
|
|
41
|
+
|
|
42
|
+
## Anonymous and Named Groups
|
|
43
|
+
|
|
44
|
+
Groups can be either named (top-level) or anonymous (inline). Named groups appear as top-level assignments in the AST, while anonymous groups can appear as property types within other groups or arrays.
|
|
45
|
+
|
|
46
|
+
### Named Group Example
|
|
47
|
+
|
|
48
|
+
```cddl
|
|
49
|
+
person = {
|
|
50
|
+
name: tstr,
|
|
51
|
+
age: uint
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
AST representation:
|
|
56
|
+
|
|
57
|
+
```json
|
|
58
|
+
{
|
|
59
|
+
"Type": "group",
|
|
60
|
+
"Name": "person",
|
|
61
|
+
"IsChoiceAddition": false,
|
|
62
|
+
"Properties": [
|
|
63
|
+
{
|
|
64
|
+
"HasCut": true,
|
|
65
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
66
|
+
"Name": "name",
|
|
67
|
+
"Type": ["tstr"],
|
|
68
|
+
"Comments": []
|
|
69
|
+
},
|
|
70
|
+
{
|
|
71
|
+
"HasCut": true,
|
|
72
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
73
|
+
"Name": "age",
|
|
74
|
+
"Type": ["uint"],
|
|
75
|
+
"Comments": []
|
|
76
|
+
}
|
|
77
|
+
],
|
|
78
|
+
"Comments": []
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### Anonymous Group Example
|
|
83
|
+
|
|
84
|
+
```cddl
|
|
85
|
+
person = {
|
|
86
|
+
name: tstr,
|
|
87
|
+
address: {
|
|
88
|
+
street: tstr,
|
|
89
|
+
city: tstr
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
AST representation:
|
|
95
|
+
|
|
96
|
+
```json
|
|
97
|
+
{
|
|
98
|
+
"Type": "group",
|
|
99
|
+
"Name": "person",
|
|
100
|
+
"IsChoiceAddition": false,
|
|
101
|
+
"Properties": [
|
|
102
|
+
{
|
|
103
|
+
"HasCut": true,
|
|
104
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
105
|
+
"Name": "name",
|
|
106
|
+
"Type": ["tstr"],
|
|
107
|
+
"Comments": []
|
|
108
|
+
},
|
|
109
|
+
{
|
|
110
|
+
"HasCut": true,
|
|
111
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
112
|
+
"Name": "address",
|
|
113
|
+
"Type": [{
|
|
114
|
+
"Type": "group",
|
|
115
|
+
"Name": "",
|
|
116
|
+
"IsChoiceAddition": false,
|
|
117
|
+
"Properties": [
|
|
118
|
+
{
|
|
119
|
+
"HasCut": true,
|
|
120
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
121
|
+
"Name": "street",
|
|
122
|
+
"Type": ["tstr"],
|
|
123
|
+
"Comments": []
|
|
124
|
+
},
|
|
125
|
+
{
|
|
126
|
+
"HasCut": true,
|
|
127
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
128
|
+
"Name": "city",
|
|
129
|
+
"Type": ["tstr"],
|
|
130
|
+
"Comments": []
|
|
131
|
+
}
|
|
132
|
+
],
|
|
133
|
+
"Comments": []
|
|
134
|
+
}],
|
|
135
|
+
"Comments": []
|
|
136
|
+
}
|
|
137
|
+
],
|
|
138
|
+
"Comments": []
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Group Composition
|
|
143
|
+
|
|
144
|
+
CDDL allows groups to be composed by including another group. This is represented in the AST using a property with an empty name that references the included group.
|
|
145
|
+
|
|
146
|
+
```cddl
|
|
147
|
+
address = {
|
|
148
|
+
street: tstr,
|
|
149
|
+
city: tstr
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
fullAddress = {
|
|
153
|
+
address,
|
|
154
|
+
country: tstr
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
AST representation:
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
[
|
|
162
|
+
{
|
|
163
|
+
"Type": "group",
|
|
164
|
+
"Name": "address",
|
|
165
|
+
"IsChoiceAddition": false,
|
|
166
|
+
"Properties": [
|
|
167
|
+
{
|
|
168
|
+
"HasCut": true,
|
|
169
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
170
|
+
"Name": "street",
|
|
171
|
+
"Type": ["tstr"],
|
|
172
|
+
"Comments": []
|
|
173
|
+
},
|
|
174
|
+
{
|
|
175
|
+
"HasCut": true,
|
|
176
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
177
|
+
"Name": "city",
|
|
178
|
+
"Type": ["tstr"],
|
|
179
|
+
"Comments": []
|
|
180
|
+
}
|
|
181
|
+
],
|
|
182
|
+
"Comments": []
|
|
183
|
+
},
|
|
184
|
+
{
|
|
185
|
+
"Type": "group",
|
|
186
|
+
"Name": "fullAddress",
|
|
187
|
+
"IsChoiceAddition": false,
|
|
188
|
+
"Properties": [
|
|
189
|
+
{
|
|
190
|
+
"HasCut": false,
|
|
191
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
192
|
+
"Name": "",
|
|
193
|
+
"Type": [{
|
|
194
|
+
"Type": "group",
|
|
195
|
+
"Value": "address",
|
|
196
|
+
"Unwrapped": false
|
|
197
|
+
}],
|
|
198
|
+
"Comments": []
|
|
199
|
+
},
|
|
200
|
+
{
|
|
201
|
+
"HasCut": true,
|
|
202
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
203
|
+
"Name": "country",
|
|
204
|
+
"Type": ["tstr"],
|
|
205
|
+
"Comments": []
|
|
206
|
+
}
|
|
207
|
+
],
|
|
208
|
+
"Comments": []
|
|
209
|
+
}
|
|
210
|
+
]
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
## Group Choice Additions
|
|
214
|
+
|
|
215
|
+
CDDL allows extending choices using the `/=` operator. This is represented in the AST with the `IsChoiceAddition` flag set to `true`.
|
|
216
|
+
|
|
217
|
+
```cddl
|
|
218
|
+
delivery = {
|
|
219
|
+
street: tstr,
|
|
220
|
+
number: uint,
|
|
221
|
+
city: city
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
delivery /= {
|
|
225
|
+
lat: float,
|
|
226
|
+
long: float,
|
|
227
|
+
drone-type: tstr
|
|
228
|
+
}
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
AST representation:
|
|
232
|
+
|
|
233
|
+
```json
|
|
234
|
+
[
|
|
235
|
+
{
|
|
236
|
+
"Type": "group",
|
|
237
|
+
"Name": "delivery",
|
|
238
|
+
"IsChoiceAddition": false,
|
|
239
|
+
"Properties": [
|
|
240
|
+
{
|
|
241
|
+
"HasCut": true,
|
|
242
|
+
"Name": "street",
|
|
243
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
244
|
+
"Type": ["tstr"],
|
|
245
|
+
"Comments": []
|
|
246
|
+
},
|
|
247
|
+
{
|
|
248
|
+
"HasCut": true,
|
|
249
|
+
"Name": "number",
|
|
250
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
251
|
+
"Type": ["uint"],
|
|
252
|
+
"Comments": []
|
|
253
|
+
},
|
|
254
|
+
{
|
|
255
|
+
"HasCut": true,
|
|
256
|
+
"Name": "city",
|
|
257
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
258
|
+
"Type": [{
|
|
259
|
+
"Type": "group",
|
|
260
|
+
"Value": "city",
|
|
261
|
+
"Unwrapped": false
|
|
262
|
+
}],
|
|
263
|
+
"Comments": []
|
|
264
|
+
}
|
|
265
|
+
],
|
|
266
|
+
"Comments": []
|
|
267
|
+
},
|
|
268
|
+
{
|
|
269
|
+
"Type": "group",
|
|
270
|
+
"Name": "delivery",
|
|
271
|
+
"IsChoiceAddition": true,
|
|
272
|
+
"Properties": [
|
|
273
|
+
{
|
|
274
|
+
"HasCut": true,
|
|
275
|
+
"Name": "lat",
|
|
276
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
277
|
+
"Type": ["float"],
|
|
278
|
+
"Comments": []
|
|
279
|
+
},
|
|
280
|
+
{
|
|
281
|
+
"HasCut": true,
|
|
282
|
+
"Name": "long",
|
|
283
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
284
|
+
"Type": ["float"],
|
|
285
|
+
"Comments": []
|
|
286
|
+
},
|
|
287
|
+
{
|
|
288
|
+
"HasCut": true,
|
|
289
|
+
"Name": "drone-type",
|
|
290
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
291
|
+
"Type": ["tstr"],
|
|
292
|
+
"Comments": []
|
|
293
|
+
}
|
|
294
|
+
],
|
|
295
|
+
"Comments": []
|
|
296
|
+
}
|
|
297
|
+
]
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
## Property Choices
|
|
301
|
+
|
|
302
|
+
CDDL allows for choice between properties in a group, represented by the `/` operator. In the AST, this is represented as an array of properties within the `Properties` array.
|
|
303
|
+
|
|
304
|
+
```cddl
|
|
305
|
+
delivery = {
|
|
306
|
+
street: tstr,
|
|
307
|
+
(city: city // po-box: uint)
|
|
308
|
+
}
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
AST representation:
|
|
312
|
+
|
|
313
|
+
```json
|
|
314
|
+
{
|
|
315
|
+
"Type": "group",
|
|
316
|
+
"Name": "delivery",
|
|
317
|
+
"IsChoiceAddition": false,
|
|
318
|
+
"Properties": [
|
|
319
|
+
{
|
|
320
|
+
"HasCut": true,
|
|
321
|
+
"Name": "street",
|
|
322
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
323
|
+
"Type": ["tstr"],
|
|
324
|
+
"Comments": []
|
|
325
|
+
},
|
|
326
|
+
[
|
|
327
|
+
{
|
|
328
|
+
"HasCut": false,
|
|
329
|
+
"Name": "",
|
|
330
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
331
|
+
"Type": {
|
|
332
|
+
"Type": "group",
|
|
333
|
+
"Value": "city",
|
|
334
|
+
"Unwrapped": false
|
|
335
|
+
},
|
|
336
|
+
"Comments": []
|
|
337
|
+
},
|
|
338
|
+
{
|
|
339
|
+
"HasCut": true,
|
|
340
|
+
"Name": "po-box",
|
|
341
|
+
"Occurrence": { "n": 1, "m": 1 },
|
|
342
|
+
"Type": ["uint"],
|
|
343
|
+
"Comments": []
|
|
344
|
+
}
|
|
345
|
+
]
|
|
346
|
+
],
|
|
347
|
+
"Comments": []
|
|
348
|
+
}
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
By understanding these different group representations in the AST, you can properly interpret and process CDDL group definitions for further transformation or analysis.
|