design: Initial PDL design

design/pdl.md

@@ -0,0 +1,83 @@
+# PDL Language Definition
+
+PDL allows defining a protocol using HOPP and TAPE.
+
+## Data Types
+
+| Syntax   | TN      | CN | Description
+| -------- | ------- | -: | -----------
+| I5       | SI      |    |   
+| I8       | LI      |  0 | 
+| I16      | LI      |  1 | 
+| I32      | LI      |  3 | 
+| I64      | LI      |  7 | 
+| I128[^2] | LI      | 15 | 
+| I256[^2] | LI      | 31 | 
+| U5       | SI      |    | 
+| U8       | LI      |  0 | 
+| U16      | LI      |  1 | 
+| U32      | LI      |  3 | 
+| U64      | LI      |  7 | 
+| U128[^2] | LI      | 15 | 
+| U256[^2] | LI      | 31 | 
+| F16      | FP      |  1 | 
+| F32      | FP      |  3 | 
+| F64      | FP      |  7 | 
+| F128[^2] | FP      | 15 | 
+| F256[^2] | FP      | 31 | 
+| String   | SBA/LBA |  * | UTF-8 string
+| Buffer   | SBA/LBA |  * | Byte array
+| []<TYPE> | OTA     |  * | Array of any type[^1]
+| Table    | KTV     |  * | 
+
+[^1]: Excluding SI and SBA. I5 and U5 cannot be used in an array, but String and
+Buffer are simply forced to use their "long" variant.
+
+[^2]: Some systems may lack support for this.
+
+## Tokens
+
+| Name     | Syntax                |
+| -------- | --------------------- |
+| Method   | `M[0-9A-Fa-f]{4}`     |
+| Key      | `[0-9A-Fa-f]{4}`      |
+| Ident    | `[A-Za-z][A-Za-z0-9]` |
+| Comma    | `,`                   |
+| LBrace   | `{`                   |
+| RBrace   | `}`                   |
+| LBracket | `[`                   |
+| RBracket | `]`                   |
+
+## Syntax
+
+Types are expressed with an Ident. A table can be used by either writing the
+name of the type (Table), or by defining a schema with curly braces. Arrays must
+be expressed using two matching square brackets before their element type.
+
+A table schema contains comma-separated fields in-between its braces. Each field
+has three parts: the key number (Key), the field name (Ident), and the field
+type. Tables, Arrays, etc. can be nested.
+
+Files directly contain messages and types, which start with a Method token and
+an Ident token respectively. A message consists of the method code (Method), the
+message name (Ident), and the message's root type. This is usually a table, but
+can be anything.
+
+Here is an example of all that:
+
+```
+M0000 Connect {
+	0000 Name String,
+	0001 Password String,
+}
+
+M0001 UserList {
+	0000 Users []User,
+}
+
+User {
+	0000 Name      String,
+	0001 Bio       String,
+	0002 Followers U32,
+}
+```