diff --git a/design/pdl.md b/design/pdl.md new file mode 100644 index 0000000..06075e6 --- /dev/null +++ b/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 +| [] | 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, +} +```