cddl 0.8.4 → 0.9.0

package/docs/basic-types.md

@@ -0,0 +1,243 @@
+# Basic Types
+
+The CDDL AST parser defines several basic types that form the building blocks of the Abstract Syntax Tree. This document describes these core types.
+
+## Primitive Types
+
+The parser supports the following primitive types as defined in the CDDL specification:
+
+```typescript
+export enum Type {
+    /**
+     * any types
+     */
+    ANY = 'any',
+
+    /**
+     * boolean types
+     */
+    // Boolean value (major type 7, additional information 20 or 21).
+    BOOL = 'bool',
+
+    /**
+     * numeric types
+     */
+    // An unsigned integer or a negative integer.
+    INT = 'int',
+    // An unsigned integer (major type 0).
+    UINT = 'uint',
+    // A negative integer (major type 1).
+    NINT = 'nint',
+    // One of float16, float32, or float64.
+    FLOAT = 'float',
+    // A number representable as an IEEE 754 half-precision float
+    FLOAT16 = 'float16',
+    // A number representable as an IEEE 754 single-precision
+    FLOAT32 = 'float32',
+    // A number representable as an IEEE 754 double-precision
+    FLOAT64 = 'float64',
+
+    /**
+     * string types
+     */
+    // A byte string (major type 2).
+    BSTR = 'bstr',
+    // A byte string (major type 2).
+    BYTES = 'bytes',
+    // Text string (major type 3)
+    TSTR = 'tstr',
+    // Text string (major type 3)
+    TEXT = 'text',
+
+    /**
+     * null types
+     */
+    NIL = 'nil',
+    NULL = 'null'
+}
+```
+
+These types correspond to the CBOR (Concise Binary Object Representation) types as specified in [RFC 7049](https://datatracker.ietf.org/doc/rfc7049/).
+
+## Type References
+
+In the AST, a type reference can be represented in several ways:
+
+1. As a string directly corresponding to one of the primitive types:
+   ```typescript
+   "Type": "tstr"
+   ```
+
+2. As a property reference to another named type:
+   ```typescript
+   "Type": {
+     "Type": "group",
+     "Value": "person",
+     "Unwrapped": false
+   }
+   ```
+
+3. As a literal value:
+   ```typescript
+   "Type": {
+     "Type": "literal",
+     "Value": "some string",
+     "Unwrapped": false
+   }
+   ```
+
+4. As a range:
+   ```typescript
+   "Type": {
+     "Type": "range",
+     "Value": {
+       "Min": 0,
+       "Max": 255,
+       "Inclusive": true
+     },
+     "Unwrapped": false
+   }
+   ```
+
+5. As a type with an operator:
+   ```typescript
+   {
+     "Type": "uint",
+     "Operator": {
+       "Type": "ge",
+       "Value": {
+         "Type": "literal",
+         "Value": 0,
+         "Unwrapped": false
+       }
+     }
+   }
+   ```
+
+## Type Combinations
+
+Types can be combined in various ways:
+
+1. As an array of alternative types (choices):
+   ```typescript
+   "Type": [
+     "tstr",
+     "uint",
+     {
+       "Type": "literal",
+       "Value": "default value",
+       "Unwrapped": false
+     }
+   ]
+   ```
+
+2. As complex structures (groups and arrays):
+   ```typescript
+   "Type": {
+     "Type": "group",
+     "Name": "address",
+     "IsChoiceAddition": false,
+     "Properties": [
+       // properties...
+     ],
+     "Comments": []
+   }
+   ```
+
+## Usage in the AST
+
+These basic types are used throughout the AST to define:
+
+1. The type of a property in a group
+2. The possible values of a variable assignment
+3. The elements in an array
+4. The parameters for operators
+
+Understanding these basic types is essential for working with the AST and properly interpreting its structure.
+
+## Example
+
+Here's an example showing how different types are represented in a CDDL file and its corresponding AST:
+
+```cddl
+person = {
+  name: tstr,
+  age: uint,
+  is-active: bool,
+  tags: [* tstr],
+  status: "active" / "inactive" / "suspended"
+}
+```
+
+The AST representation for this would include the various types we've discussed:
+
+```json
+{
+  "Type": "group",
+  "Name": "person",
+  "IsChoiceAddition": false,
+  "Properties": [
+    {
+      "HasCut": true,
+      "Occurrence": { "n": 1, "m": 1 },
+      "Name": "name",
+      "Type": ["tstr"],
+      "Comments": []
+    },
+    {
+      "HasCut": true,
+      "Occurrence": { "n": 1, "m": 1 },
+      "Name": "age",
+      "Type": ["uint"],
+      "Comments": []
+    },
+    {
+      "HasCut": true,
+      "Occurrence": { "n": 1, "m": 1 },
+      "Name": "is-active",
+      "Type": ["bool"],
+      "Comments": []
+    },
+    {
+      "HasCut": true,
+      "Occurrence": { "n": 1, "m": 1 },
+      "Name": "tags",
+      "Type": [{
+        "Type": "array",
+        "Values": [{
+          "HasCut": false,
+          "Occurrence": { "n": 0, "m": Infinity },
+          "Name": "",
+          "Type": ["tstr"],
+          "Comments": []
+        }]
+      }],
+      "Comments": []
+    },
+    {
+      "HasCut": true,
+      "Occurrence": { "n": 1, "m": 1 },
+      "Name": "status",
+      "Type": [
+        {
+          "Type": "literal",
+          "Value": "active",
+          "Unwrapped": false
+        },
+        {
+          "Type": "literal",
+          "Value": "inactive",
+          "Unwrapped": false
+        },
+        {
+          "Type": "literal",
+          "Value": "suspended",
+          "Unwrapped": false
+        }
+      ],
+      "Comments": []
+    }
+  ],
+  "Comments": []
+}
+```

package/docs/comments.md

@@ -0,0 +1,307 @@
+# Comments
+
+Comments are an important part of CDDL files that provide additional context and information about the definitions. This document explains how comments are represented in the AST.
+
+## Comment Definition
+
+In the AST, a comment is represented by the following structure:
+
+```typescript
+export type Comment = {
+    Type: 'comment'
+    Content: string
+    Leading: boolean
+}
+```
+
+Where:
+- `Type`: Always set to 'comment' to identify this node as a comment
+- `Content`: The text content of the comment (without the comment marker)
+- `Leading`: A boolean indicating if this is a leading comment (appears before the definition) or a trailing comment (appears after the definition)
+
+## Comment Syntax
+
+In CDDL, comments are denoted by a semicolon `;` and continue until the end of the line:
+
+```cddl
+; This is a comment
+person = {
+    name: tstr,  ; This is another comment
+    age: uint
+}
+```
+
+## Comment Location in the AST
+
+Comments can be associated with various elements in the AST:
+
+1. Groups
+2. Arrays
+3. Variables
+4. Properties
+
+Each of these elements has a `Comments` field that contains an array of comment objects associated with that element.
+
+## Examples
+
+### Comments on Group Definitions
+
+```cddl
+; This is a comment
+; foobar
+; This is another
+; very nice comment
+person = {
+    ; a good employer
+    employer: tstr
+}
+```
+
+AST representation:
+
+```json
+{
+  "Type": "group",
+  "Name": "person",
+  "IsChoiceAddition": false,
+  "Properties": [
+    {
+      "HasCut": true,
+      "Occurrence": { "n": 1, "m": 1 },
+      "Name": "employer",
+      "Type": ["tstr"],
+      "Comments": [
+        {
+          "Type": "comment",
+          "Content": "a good employer",
+          "Leading": false
+        }
+      ]
+    }
+  ],
+  "Comments": [
+    {
+      "Type": "comment",
+      "Content": "This is a comment",
+      "Leading": false
+    },
+    {
+      "Type": "comment",
+      "Content": "foobar",
+      "Leading": false
+    },
+    {
+      "Type": "comment",
+      "Content": "This is another",
+      "Leading": false
+    },
+    {
+      "Type": "comment",
+      "Content": "very nice comment",
+      "Leading": false
+    }
+  ]
+}
+```
+
+### Comments on Array Elements
+
+```cddl
+Geography = [
+    ; a city
+    city: tstr,
+    ; some coordinates
+    gpsCoordinates: GpsCoordinates
+]
+```
+
+AST representation:
+
+```json
+{
+  "Type": "array",
+  "Name": "Geography",
+  "Values": [
+    {
+      "HasCut": true,
+      "Occurrence": { "n": 1, "m": 1 },
+      "Name": "city",
+      "Type": ["tstr"],
+      "Comments": [
+        {
+          "Type": "comment",
+          "Content": "a city",
+          "Leading": false
+        }
+      ]
+    },
+    {
+      "HasCut": true,
+      "Occurrence": { "n": 1, "m": 1 },
+      "Name": "gpsCoordinates",
+      "Type": [{
+        "Type": "group",
+        "Value": "GpsCoordinates",
+        "Unwrapped": false
+      }],
+      "Comments": [
+        {
+          "Type": "comment",
+          "Content": "some coordinates",
+          "Leading": false
+        }
+      ]
+    }
+  ],
+  "Comments": []
+}
+```
+
+### Comments on Variable Definitions
+
+```cddl
+; unit: m/s
+speed = number .ge 0
+```
+
+AST representation:
+
+```json
+{
+  "Type": "variable",
+  "Name": "speed",
+  "IsChoiceAddition": false,
+  "PropertyType": [
+    {
+      "Type": {
+        "Type": "group",
+        "Value": "number",
+        "Unwrapped": false
+      },
+      "Operator": {
+        "Type": "ge",
+        "Value": {
+          "Type": "literal",
+          "Value": 0,
+          "Unwrapped": false
+        }
+      }
+    }
+  ],
+  "Comments": [
+    {
+      "Type": "comment",
+      "Content": "unit: m/s",
+      "Leading": false
+    }
+  ]
+}
+```
+
+### Comments on Properties in Groups
+
+```cddl
+GpsCoordinates = {
+    ; degrees, scaled by 10^7
+    longitude: uint,
+    ; degreed, scaled by 10^7
+    latitude: uint
+}
+```
+
+AST representation:
+
+```json
+{
+  "Type": "group",
+  "Name": "GpsCoordinates",
+  "IsChoiceAddition": false,
+  "Properties": [
+    {
+      "HasCut": true,
+      "Occurrence": { "n": 1, "m": 1 },
+      "Name": "longitude",
+      "Type": ["uint"],
+      "Comments": [
+        {
+          "Type": "comment",
+          "Content": "degrees, scaled by 10^7",
+          "Leading": false
+        }
+      ]
+    },
+    {
+      "HasCut": true,
+      "Occurrence": { "n": 1, "m": 1 },
+      "Name": "latitude",
+      "Type": ["uint"],
+      "Comments": [
+        {
+          "Type": "comment",
+          "Content": "degreed, scaled by 10^7",
+          "Leading": false
+        }
+      ]
+    }
+  ],
+  "Comments": []
+}
+```
+
+### Multiple Comments on an Element
+
+Comments can be stacked together in the CDDL file:
+
+```cddl
+; some comment
+; another comment
+foo = {
+    bar
+}
+```
+
+AST representation:
+
+```json
+{
+  "Type": "group",
+  "Name": "foo",
+  "IsChoiceAddition": false,
+  "Properties": [
+    {
+      "HasCut": false,
+      "Occurrence": { "n": 1, "m": 1 },
+      "Name": "",
+      "Type": [{
+        "Type": "group",
+        "Value": "bar",
+        "Unwrapped": false
+      }],
+      "Comments": []
+    }
+  ],
+  "Comments": [
+    {
+      "Type": "comment",
+      "Content": "some comment",
+      "Leading": false
+    },
+    {
+      "Type": "comment",
+      "Content": "another comment",
+      "Leading": false
+    }
+  ]
+}
+```
+
+## Working with Comments
+
+When processing the AST, you can use the comments to:
+
+1. Generate documentation from the CDDL file
+2. Add explanatory comments to generated code
+3. Provide additional context or constraints not directly expressible in CDDL
+4. Preserve the original author's intentions and notes
+
+Comments provide valuable metadata about the CDDL definitions and should be preserved when transforming the AST to other formats.