# 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     |  * | Table with undefined schema
| {...}      | KTV     |  * | Table with defined schema

[^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

PDL files are divided into tokens, which assemble together into larger language
structures. They are separated by whitespace.

| Name     | Syntax             | Description
| -------- | ------------------ | -----------
| Magic    | `PDL/0`            | Must appear at the very start of the file.
| Method   | `M[0-9A-Fa-f]{4}`  | A 16-bit hexadecimal method code.
| Key      | `[0-9A-Fa-f]{4}`   | A 16-bit hexadecimal table key.
| Ident    | `[A-Z][A-Za-z0-9]` | An identifier.
| Comma    | `,`                | A comma separator.
| LBrace   | `{`                | A left curly brace.
| RBrace   | `}`                | A right curly brace.
| LBracket | `[`                | A left square bracket.
| RBracket | `]`                | A right square bracket.

## Syntax

All files must begin with a Magic token.

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:

```
PDL/0

M0000 Connect {
	0000 Name String,
	0001 Password String,
}

M0001 UserList {
	0000 Users []User,
}

User {
	0000 Name      String,
	0001 Bio       String,
	0002 Followers U32,
}
```

## EBNF Description

Below is an EBNF description of the language.

```
<file>    -> <magic> (<message> | <typedef)*
<magic>   -> "PDL/0"
<method>  -> /M[0-9A-Fa-f]{4}/
<key>     -> /[0-9A-Fa-f]{4}/
<ident>   -> /[A-Z][A-Za-z0-9]/
<field>   -> <key> <ident> <type>
<type> -> <ident>
        | "[" "]" <type>
        | "{" (<field> ",")* [<field>] "}"
<message> -> <method> <ident> <type>
<typedef> -> <ident> <type>
```