diff --git a/doc/datatypes/conditional.md b/doc/datatypes/conditional.md index 4526c45..79249f7 100644 --- a/doc/datatypes/conditional.md +++ b/doc/datatypes/conditional.md @@ -15,7 +15,6 @@ For `compareTo` variables, to go up one level when referencing a field, use "../ Switch statement field names starting with "/" will reference a root variable. Root variables are primitives that can be used for comparisons and changed dynamically. Example: - A switch which can encode a byte, a varint, a float or a string depending on "someField". If the value of someField is different, then the value encoded is of type void. ```json @@ -43,7 +42,8 @@ Represents a simple optional type. It's encoded as a boolean indicating whether the value is there or not. It's similar to the `Optional` type in java or `Maybe` in haskell. -Example: An option of value string +Example: +An option of value string ```json [ "option", diff --git a/doc/datatypes/numeric.md b/doc/datatypes/numeric.md index 9183861..dc02205 100644 --- a/doc/datatypes/numeric.md +++ b/doc/datatypes/numeric.md @@ -21,9 +21,11 @@ They default to big-endian encoding. To use little-endian, prefix its name with | zigzag32 | 1-4 | -100 | signed int var | | zigzag64 | 1-8 | -680n | signed long | -### **int** ({ size: Integer }) +### **int** ({ size: Integer, ?minimum: Integer, ?maximum: Integer }) Arguments: * size : fixed size in bytes +* minimum : optional, the minimum integer value +* maximum : optional, the maximum integer value Represents a unsigned integer using `size` bytes. @@ -31,34 +33,78 @@ Example: ```json [ "int", - { "size": "3" } + { "size": "3", "minimum": 14, "maximum": 15 } ] ``` Example of value: `65535` (size = 2) / `16777215` (size = 3) -### **varint** ( ) +Example: +```json +[ + "int", + { "size": "1", "minimum": 1, "maximum": 100 } +] +``` +Example of value: `1`, `100` (does not match `0` or `101`) + +### **varint** ({ ?minimum: Integer, ?maximum: Integer }) Arguments: None [Protobuf](https://developers.google.com/protocol-buffers/docs/encoding#varints)-compatible representation for variable-length integers using one or more bytes. Intended for 32-bit unsigned integers, or signed 32-bit integers that have been directly cast to an integer (where the MSB is the sign bit) before encoding. +Example: +```json +"varint" +``` + +or +```json +[ + "varint" +] +``` + +or +```json +[ + "varint", + {} +] +``` + +or +```json +[ + "varint", + { "minimum": 1, "maximum": 100 } +] +``` Example of value: `300` (size is 2 bytes) -### **varint64** () -Arguments: None +### **varint64** ({ ?minimum: Integer, ?maximum: Integer }) +Arguments: +* minimum : optional, the minimum integer value +* maximum : optional, the maximum integer value Same as **varint**, but for 64-bit unsigned integers, or signed 64-bit integers that have been directly cast to an integer (where the MSB is the sign bit) before encoding. -### **varint128** () -Arguments: None +### **varint128** ({ ?minimum: Integer, ?maximum: Integer }) +Arguments: +* minimum : optional, the minimum integer value +* maximum : optional, the maximum integer value Same as **varint**, but for 128-bit unsigned integers, or signed 128-bit integers that have been directly cast to an integer (where the MSB is the sign bit) before encoding. -### **zigzag32** () -Arguments: None +### **zigzag32** ({ ?minimum: Integer, ?maximum: Integer }) +Arguments: +* minimum : optional, the minimum integer value +* maximum : optional, the maximum integer value Similar to **varint**, except using [ZigZag encoding](https://protobuf.dev/programming-guides/encoding/#signed-ints) for signed integers. Intended for 32-bit signed numbers. -### **zigzag64** () -Arguments: None +### **zigzag64** ({ ?minimum: Integer, ?maximum: Integer }) +Arguments: +* minimum : optional, the minimum integer value +* maximum : optional, the maximum integer value Same as **zigzag32**, but for 64-bit signed integers in ZigZag encoding. diff --git a/doc/datatypes/primitives.md b/doc/datatypes/primitives.md index ddea505..790c9eb 100644 --- a/doc/datatypes/primitives.md +++ b/doc/datatypes/primitives.md @@ -1,20 +1,20 @@ ## Primitives -### **bool** ( ) +### **bool** () Arguments: None Represents a boolean, encoded in one byte. Example of value: `true` / `false` -### **cstring** ( ) -Arguments: encoding +### **cstring** ({ ?encoding: String }) +Arguments: +* encoding : the encoding of the string, UTF-8 by default -Represents a null terminated string. Similar to strings in C. -Assumes UTF-8 encoding by default +Represents a null-terminated string. Similar to strings in C. Example: -Example: A string length prefixed by a varint. +A UTF-16 string of unknown size that is expected to end with the zero character (null-terminal). ```json [ "cstring", { "encoding": "utf-16" } @@ -23,7 +23,7 @@ Example: A string length prefixed by a varint. Example of value: `"my string"` -### **void** ( ) +### **void** () Arguments: None Represents an empty value. diff --git a/doc/datatypes/structures.md b/doc/datatypes/structures.md index 6beaefd..a55a713 100644 --- a/doc/datatypes/structures.md +++ b/doc/datatypes/structures.md @@ -8,7 +8,8 @@ Arguments: Represents a list of values with same type. -Example: An array of int prefixed by a short length. +Example: +An array of int prefixed by a short length. ```json [ "array", @@ -20,7 +21,7 @@ Example: An array of int prefixed by a short length. ``` Example of value: `[1, 2, 3, 4]` (type = [i8](./numeric.md)) / `["ac", "dc"]` (type = [cstring](./utils.md)) -### **container** ([ { name: String, type: Type, ?anon: Bool }, ... ]) +### **container** ([ { name: String, type: Type, ?anon: Boolean }, ... ]) Arguments: * [array] : a field * * name : the name of field @@ -29,7 +30,8 @@ Arguments: Represents a list of named values. -Example: A container with fields of type int, int, ushort and ushort. +Example: +A container with fields of type int, int, ushort and ushort. ```json [ "container", @@ -57,7 +59,8 @@ Arguments: Represents a count field for an array or a buffer. -Example: A count for a field name records, of type short. +Example: +A count for a field name records, of type short. ```json [ "count", diff --git a/doc/datatypes/utils.md b/doc/datatypes/utils.md index c64a3aa..3a8a400 100644 --- a/doc/datatypes/utils.md +++ b/doc/datatypes/utils.md @@ -8,7 +8,8 @@ Arguments: Represents a raw bytes with count prefix/field or without it. -Example: An buffer prefixed by a varint length. +Example: +An buffer prefixed by a varint length. ```json [ "buffer", @@ -29,7 +30,6 @@ Represents a list of value with sizes that are not a multiple of 8bits. The sum of the sizes must be a multiple of 8. Example: - 3 values, x, y and z with sizes in bits : 26, 12, 26. Notice that 26+12+26=64. ```json [ @@ -52,7 +52,6 @@ Arguments: Maps string to a values. Example: - Maps a byte to a string, 1 to "byte", 2 to "short", 3 to "int", 4 to "long". ```json [ @@ -70,17 +69,16 @@ Maps a byte to a string, 1 to "byte", 2 to "short", 3 to "int", 4 to "long". ``` Example of value: `"int"` -### **bitflags** ([ { type: string, flags: object | array, big?: boolean, shift?: number } ]) +### **bitflags** ([ { type: String, flags: Object | Array, ?big: Boolean, ?shift: Number } ]) Arguments: * type : The underlying integer type (eg varint, lu32). * flags : Either an array of flag values from LSB to MSB, or an object containing a mappng of valueName => bitMask. -* big : 64+ bits. In langauges like javascript (where all numbers are 64-bit floating points), special data types may have to be used for integers greater than 32 bits, so this must be set to true if the `type` is using the special data type. +* big : If the type is 64+ bits. In languages like javascript (where all numbers are 64-bit floating points), special data types may have to be used for integers greater than 32 bits, so this must be set to true if the `type` is using the special data type. * shift : Specify if flags is an object and holds bit positions as values opposed to a bitmask. Represents boolean flags packed into an integer. Similar to bitfields, but only intended for enumerated boolean flags (each flag occupies 1 bit), and supports arbitrary underlying integer types. Example: - ```json [ "bitflags", @@ -92,32 +90,35 @@ Example: ``` or -```yaml +```json [ "bitflags", { "type": "lu32", "big": true, "flags": { - "onGround": 0b1, - "inAir": 0b10 + "onGround": 1, + "inAir": 2 } } ] ``` +where `1` and `2` respectively are the JSON-compatible, decimal representations of the bitmasks `0b01` and `0b10`. + Example of value to pass when writing: `{"flags": { "onGround": true, "inAir": false } }`. Likewise when reading you will get a similar object back, with a extra `_value` field holding the raw integer. -### **pstring** ({ countType: Type, ?count: Countable }) +### **pstring** ({ countType: Type, ?count: Countable, ?encoding: String }) Arguments: * countType : the type of the length prefix * count : optional (either count or countType), a reference to the field counting the elements, or a fixed size (an integer) -* encoding: the encoding of the string, UTF-8 by default +* encoding : the encoding of the string, UTF-8 by default Represents a string. -Example: A string length prefixed by a varint. +Example: +A string length prefixed by a varint. ```json [ "pstring", { "countType": "varint", "encoding": "utf-8" } diff --git a/schemas/numeric.json b/schemas/numeric.json index 9f9b264..a33f114 100644 --- a/schemas/numeric.json +++ b/schemas/numeric.json @@ -1,78 +1,753 @@ { "i8": { - "enum": ["i8"] + "title": "i8", + "oneOf": [ + { + "enum": ["i8"] + }, + { + "type": "array", + "items": [ + { + "enum": ["i8"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "u8": { - "enum": ["u8"] + "title": "u8", + "oneOf": [ + { + "enum": ["u8"] + }, + { + "type": "array", + "items": [ + { + "enum": ["u8"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "i16": { - "enum": ["i16"] + "title": "i16", + "oneOf": [ + { + "enum": ["i16"] + }, + { + "type": "array", + "items": [ + { + "enum": ["i16"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "u16": { - "enum": ["u16"] + "title": "u16", + "oneOf": [ + { + "enum": ["u16"] + }, + { + "type": "array", + "items": [ + { + "enum": ["u16"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "i32": { - "enum": ["i32"] + "title": "i32", + "oneOf": [ + { + "enum": ["i32"] + }, + { + "type": "array", + "items": [ + { + "enum": ["i32"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "u32": { - "enum": ["u32"] + "title": "u32", + "oneOf": [ + { + "enum": ["u32"] + }, + { + "type": "array", + "items": [ + { + "enum": ["u32"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "f32": { - "enum": ["f32"] + "title": "f32", + "oneOf": [ + { + "enum": ["f32"] + }, + { + "type": "array", + "items": [ + { + "enum": ["f32"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "f64": { - "enum": ["f64"] + "title": "f64", + "oneOf": [ + { + "enum": ["f64"] + }, + { + "type": "array", + "items": [ + { + "enum": ["f64"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "li8": { - "enum": ["li8"] + "title": "li8", + "oneOf": [ + { + "enum": ["li8"] + }, + { + "type": "array", + "items": [ + { + "enum": ["li8"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "lu8": { - "enum": ["lu8"] + "title": "lu8", + "oneOf": [ + { + "enum": ["lu8"] + }, + { + "type": "array", + "items": [ + { + "enum": ["lu8"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "li16": { - "enum": ["li16"] + "title": "li16", + "oneOf": [ + { + "enum": ["li16"] + }, + { + "type": "array", + "items": [ + { + "enum": ["li16"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "lu16": { - "enum": ["lu16"] + "title": "lu16", + "oneOf": [ + { + "enum": ["lu16"] + }, + { + "type": "array", + "items": [ + { + "enum": ["lu16"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "li32": { - "enum": ["li32"] + "title": "li32", + "oneOf": [ + { + "enum": ["li32"] + }, + { + "type": "array", + "items": [ + { + "enum": ["li32"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "lu32": { - "enum": ["lu32"] + "title": "lu32", + "oneOf": [ + { + "enum": ["lu32"] + }, + { + "type": "array", + "items": [ + { + "enum": ["lu32"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "lf32": { - "enum": ["lf32"] + "title": "lf32", + "oneOf": [ + { + "enum": ["lf32"] + }, + { + "type": "array", + "items": [ + { + "enum": ["lf32"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "lf64": { - "enum": ["lf64"] + "title": "lf64", + "oneOf": [ + { + "enum": ["lf64"] + }, + { + "type": "array", + "items": [ + { + "enum": ["lf64"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "i64": { - "enum": ["i64"] + "title": "i64", + "oneOf": [ + { + "enum": ["i64"] + }, + { + "type": "array", + "items": [ + { + "enum": ["i64"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "li64": { - "enum": ["li64"] + "title": "li64", + "oneOf": [ + { + "enum": ["li64"] + }, + { + "type": "array", + "items": [ + { + "enum": ["li64"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "u64": { - "enum": ["u64"] + "title": "u64", + "oneOf": [ + { + "enum": ["u64"] + }, + { + "type": "array", + "items": [ + { + "enum": ["u64"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "lu64": { - "enum": ["lu64"] + "title": "lu64", + "oneOf": [ + { + "enum": ["lu64"] + }, + { + "type": "array", + "items": [ + { + "enum": ["lu64"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "varint": { - "enum": ["varint"] + "title": "varint", + "oneOf": [ + { + "enum": ["varint"] + }, + { + "type": "array", + "items": [ + { + "enum": ["varint"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "varint64": { - "enum": ["varint64"] + "title": "varint64", + "oneOf": [ + { + "enum": ["varint64"] + }, + { + "type": "array", + "items": [ + { + "enum": ["varint64"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "varint128": { - "enum": ["varint128"] + "title": "varint128", + "oneOf": [ + { + "enum": ["varint128"] + }, + { + "type": "array", + "items": [ + { + "enum": ["varint128"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "zigzag32": { - "enum": ["zigzag32"] + "title": "zigzag32", + "oneOf": [ + { + "enum": ["zigzag32"] + }, + { + "type": "array", + "items": [ + { + "enum": ["zigzag32"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "zigzag64": { - "enum": ["zigzag64"] + "title": "zigzag64", + "oneOf": [ + { + "enum": ["zigzag64"] + }, + { + "type": "array", + "items": [ + { + "enum": ["zigzag64"] + }, + { + "type": "object", + "properties": { + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } + }, + "required": [], + "additionalProperties": false + } + ], + "additionalItems": false + } + ] }, "int": { "title": "int", @@ -82,18 +757,20 @@ "enum": ["int"] }, { - "type": "array", - "items": { - "type": "object", - "properties": { - "size": { - "type": "number" - } + "type": "object", + "properties": { + "size": { + "type": "number" }, - "required": ["size"], - "additionalProperties": false + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } }, - "additionalItems": false + "required": ["size"], + "additionalProperties": false } ], "additionalItems": false @@ -106,18 +783,20 @@ "enum": ["lint"] }, { - "type": "array", - "items": { - "type": "object", - "properties": { - "size": { - "type": "number" - } + "type": "object", + "properties": { + "size": { + "type": "number" }, - "required": ["size"], - "additionalProperties": false + "minimum": { + "type": "number" + }, + "maximum": { + "type": "number" + } }, - "additionalItems": false + "required": ["size"], + "additionalProperties": false } ], "additionalItems": false diff --git a/schemas/primitives.json b/schemas/primitives.json index c5359ea..b5af6ab 100644 --- a/schemas/primitives.json +++ b/schemas/primitives.json @@ -1,5 +1,6 @@ { "bool": { + "title": "bool", "enum": ["bool"] }, "cstring": { @@ -23,6 +24,7 @@ "additionalItems": false }, "void": { + "title": "void", "enum": ["void"] } }