| Assets | ||
| example.jcd | ||
| LICENSE.md | ||
| Machine.MD | ||
| NoArrayTest.jcd | ||
| README.MD | ||
| schema.jcd | ||
| tinyexample.jcd | ||
| tinyexample.jcm | ||
JCData
Unified instruction sets for humans and machines alike.
◼ Documentation (WIP) ◼ Contact ◼ License ◼ Plans & Milestones ◼
JCData is a complex protocol infrastructure for sharing data and instructions according to a schema or set rules focusing on being easy to parse and translate for both perspective parties.
It consists of two different forms: Human and Machine. Each of these forms has its own data and schema formatting.
JCubeCode natively supports and uses this type to both communicate process to process and to allow users to modify settings in a readable and clean way.
Conversion between both these forms is 1:1 and the data is directly usable in the C library as JCData uses the Dynamic types.
It's unique appraoch in data conversion is that since this protocol talks over multiple different fields, the sides both first argue on which "commands" the data represents first.
If the header is data generic, the "commands" are sent first and then the data itself.
JCubeData is perfect for deterministic and quick responses which don't need to be parsed, such as APIs, process to process communication, rendering, sound and real time communication.
Principles
Ideology
=> HUMAN => MACHINE <=> MACHINE => HUMAN <=
Machines should only communicate with machines. Humans should only communicate with humans.
Human: This file must be easy to read at a first glance, easy to write new data in and easy to edit. Every part of this format should be explainable with one sentence.
Machine: This format must be easy to parse, very easy to use and should have minimal overhead upon converting it into usable data for JCubeCode.
Types
JCData operates under these specified types:
| Type | Description |
|---|---|
| Null | Empty and does nothing, either no = or small n |
| Boolean | Only true (T) or false (F) |
| Integer | Number without a decimal point |
| Float | Number with a decimal point |
| String | Human readable string composed of printable characters |
| Bytes | Raw bytes |
| List | Multiple ordered types accessed via position |
| Dictionary | Multiple unordered types accessed by "keys" (names) |
WIP: Schema
Implicitly, any variable can be any type because a machine doesn't really care about what data you send, which is why the burden of verifying falls on you.
Introducing a very powerful inbuilt schema system. This allows you to handle common problems such as matching types, allowed values and structured complex types.
In the schema, you can explicitly state each type or use one of the rules to enforce typing.
To use schema rules, you declare commands in the form of
@[COMMAND][NEWLINE]
The '@' part is a pun because it sounds like 'add' :) This schema can either be used in-line or from a range, surrounded by start and end tags.
Rules start at @ are ended by the newline.
[PREFIX] [TYPE] [IDENTIFIER] [DEFAULT VALUE] [;]
# f.e.
@start
Integer testNumber 5;
@end
# or
@String HelloWorld "Hi :D";
# No default value = this entry must exist
@Float Debt;
Commands
| Name | Description |
|---|---|
| start | Start schema mode parsing |
| end | Ends schema mode and resumes normal parsing |
| enum | Constrict value to be one of specified values |
| struct | Create a named template for data |
Implementation
| Type | Size | Description |
|---|---|---|
| Null | 0 | Empty and does nothing |
| Boolean | 0 | Only true or false |
| Integer | 1-4 | Number that can be both negative and positive |
| WholeInteger | 1-4 | Number that can be only positive, but larger |
| Float | 1-4 | Number with a decimal point that can have a sign |
| Date | 4 | Represents a date in the format of YY YY MM DD |
| Time | 4 | Represents a time with the format HH MM SS MS |
| Enum | any | Allows the variable to be one of the entries |
| Set | any | Same as Enum, but with multiple choices |
| Structure | any | Defines the size and shape of the special structure |
| Bytes | any | Raw bytes |
| String | any | Human readable string composed of printable chars |
| List | any | Series of multiple ordered types |
| Dictionary | any | Series of multiple unordered types accessed by keys |
| Reserved | - | This position is reserved for a future data type |
| Reserved | - | This position is reserved for a future data type |
Commands
Entries or commands are what defines the data itself.
[0-255]
[255] [0]
JCT[Version] JCS[Version] JCD[Version]
JCT [VERSION] [HEADER] [DATA] 00 [COMMAND] [DATA] [COMMAND] [DATA] 00
Client
JCT [VERSION] [HEADER] [DATA] 00 [COMMAND] [DATA] 00
Server (Sending schema)
JCT [VERSION] [RESPONSE CODE] [ENTRY] [METADATA] [ENTRY] [METADATA] 00 [DATA]
Server
JCT [VERSION] [RESPONSE CODE] 00 [DATA]
Metadata
The metadata will be the one byte big (8 bits). The specifics are defined in the Metadata.h file. This metadata must either preceed data or be defined in a schema.