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..46b6723 100644 --- a/doc/datatypes/numeric.md +++ b/doc/datatypes/numeric.md @@ -36,7 +36,7 @@ Example: ``` Example of value: `65535` (size = 2) / `16777215` (size = 3) -### **varint** ( ) +### **varint** () 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. 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..b7a950c 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: Boolean } ]) 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. -* shift : Specify if flags is an object and holds bit positions as values opposed to a bitmask. +* 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, false by default. 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,15 +90,33 @@ Example: ``` or -```yaml +```json +[ + "bitflags", + { + "type": "lu32", + "big": true, + "flags": { + "onGround": 1, + "inAir": 2 + } + } +] +``` + +(where `1` and `2` respectively are the JSON-compatible, decimal representations of the bitmasks `0b01` and `0b10`) + +or +```json [ "bitflags", { "type": "lu32", "big": true, + "shift": true, "flags": { - "onGround": 0b1, - "inAir": 0b10 + "onGround": 0, + "inAir": 1 } } ] @@ -109,15 +125,16 @@ or 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/utils.json b/schemas/utils.json index c9d48b5..ec8a5b5 100644 --- a/schemas/utils.json +++ b/schemas/utils.json @@ -111,6 +111,32 @@ }, { "type": "object", + "properties": { + "type": "string", + "flags": { + "oneOf": [ + { + "type": "object" + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "big": { + "type": "boolean" + }, + "shift": { + "type": "boolean" + } + }, + "required": [ + "type", + "flags" + ], "additionalItems": false } ],