cddl 0.16.0 → 0.17.0

package/docs/basic-types.md

@@ -1,243 +0,0 @@
-# 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/cddl-cheatsheet.md

@@ -1,231 +0,0 @@
-# CDDL Core Concepts: Choices and Maps
-
-This guide explains three fundamental concepts in CDDL that are often confused: **Type Choices**, **Group Choices**, and **Maps**.
-
-## 1. Type Choice (`/`)
-
-A **Type Choice** allows a value to be one of several distinct types. It is represented by the single forward slash `/`.
-
-Think of it as an "OR" operator for *values*.
-
-### Syntax
-```cddl
-type1 / type2 / type3
-```
-
-### Examples
-
-**Simple Value Choice:**
-```cddl
-; MyValue can be an integer OR a text string
-MyValue = int / tstr
-```
-
-**Inside an Array:**
-```cddl
-; An array where the first element is either an int OR a float
-MyArray = [ int / float, tstr ]
-```
-
-**Inside a Map Property:**
-```cddl
-; The "score" property can be an integer OR null
-MyMap = {
-    "score" => int / null
-}
-```
-
----
-
-## 2. Group Choice (`//`)
-
-A **Group Choice** allows a structure (like a map or array) to match one of several *groups* of properties. It is represented by the double forward slash `//`.
-
-Think of it as an "OR" operator for *sets of fields/entries*.
-
-### Syntax
-```cddl
-(group1) // (group2) // (group3)
-```
-
-### Examples
-
-**Choice between sets of fields:**
-```cddl
-; A defined group that is either a "street address" OR a "po box"
-Address = (
-    street: tstr,
-    city: tstr
-) // (
-    po-box: int,
-    city: tstr
-)
-```
-
-**Usage in Maps:**
-When used inside a map, it means the map must contain *either* the keys from the first group *OR* the keys from the second group.
-
-```cddl
-; A user profile must have either a "username" OR an "email" (but not necessarily both, depending on other rules)
-UserProfile = {
-    id: int,
-    (
-        username: tstr
-    ) // (
-        email: tstr
-    )
-}
-```
-
-**Key Difference from Type Choice:**
-- `key: int / tstr` -> The key exists, and its value is either int or string.
-- `(key1: int) // (key2: int)` -> Either the key `key1` exists OR the key `key2` exists.
-
----
-
-## 3. Maps
-
-In CDDL, a **Map** is defined using curly braces `{}`. It corresponds to a JSON Object or a dictionary/hash map.
-
-Inside a Map, you define **Groups** of properties/pairs using `key => value` or `key: value` syntax.
-
-### Syntax
-```cddl
-MyMap = {
-    key1 => value1,
-    key2: value2,
-    optional-key3?: value3
-}
-```
-
-### Deep Dive: Maps vs. Groups
-
-- A **Group** is just a sequence of fields (key-value pairs) inside a structure.
-- A **Map** `{ ... }` acts as a container for a Group.
-
-**Defining a reusable Group:**
-```cddl
-; "PersonFields" is just a list of fields, NOT a map yet.
-PersonFields = (
-    name: tstr,
-    age: int
-)
-```
-
-**Using the Group in a Map:**
-```cddl
-; "Student" is a Map that contains the PersonFields
-Student = {
-    PersonFields,
-    school: tstr
-}
-
-; "Teacher" is also a Map that contains the PersonFields
-Teacher = {
-    PersonFields,
-    subject: tstr
-}
-```
-
-### Mixing Choices in Maps
-
-You can combine Maps and Choices to create complex validation logic:
-
-```cddl
-Response = {
-    "status" => "ok",
-    "data" => tstr
-} / {
-    "status" => "error",
-    "code" => int,
-    "message" => tstr
-}
-```
-*This definition means a Response object must look like EITHER the first block (status="ok", data=...) OR the second block (status="error", code=...).*
-
----
-
-## 4. Arrays
-
-Arrays in CDDL are defined using square brackets `[]`. They correspond to JSON Arrays.
-
-### Syntax
-```cddl
-MyArray = [ type1, type2, ... ]
-```
-
-### Examples
-
-**Simple Array:**
-```cddl
-; An array of an integer, a string, and a float
-Point3D = [ x: float, y: float, z: float ]
-```
-
-**Array with Group Choice:**
-You can use group choices inside arrays to allow different structures.
-
-```cddl
-; An item is either an integer OR a string
-Item = [ (int // tstr) ]
-```
-
----
-
-## 5. Literals
-
-CDDL supports various literal values which are useful for exact matching.
-
-### Examples
-
-```cddl
-LiteralTest = {
-  ; Exact string match
-  type: "widget",
-
-  ; Exact integer match
-  version: 1,
-
-  ; Big Integers
-  big_id: 9007199254740995,
-
-  ; Null and Booleans
-  is_active: true,
-  deleted_at: null
-}
-
----
-
-## 6. Groups as Maps
-
-Wrap a **Group** in curly braces `{}` to treat it as a **Map**.
-
-```cddl
-; A reusable Group of fields
-DateFields = ( year: int, month: int, day: int )
-
-; 1. Mix it into a Map
-Appointment = {
-  description: tstr,
-  DateFields
-}
-
-; 2. Standalone Map
-DateObject = { DateFields }
-```
-
-### Choices with Groups and Maps
-
-You can mix explicit Maps and Groups-as-Maps in type choices:
-
-```cddl
-ArrayMap = { type: "array", values: [...] }
-DateGroup = ( type: "date", value: tstr )
-
-; Matches either map structure
-MixedValue = (
-  ArrayMap /      ; Map defined elsewhere
-  { DateGroup }   ; Group wrapped in Map
-)
-```
-```