hopp/design/pdl-language.md

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
I1281	LI	15
I2561	LI	31
U5	SI
U8	LI	0
U16	LI	1
U32	LI	3
U64	LI	7
U1281	LI	15
U2561	LI	31
F16	FP	1
F32	FP	3
F64	FP	7
F1281	FP	15
F2561	FP	31
String	SBA/LBA	*	UTF-8 string
Buffer	SBA/LBA	*	Byte array
[]<TYPE>	OTA	*	Array of any type2
Table	KTV	*	Table with undefined schema
{...}	KTV	*	Table with defined schema

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>

---

1. Some systems may lack support for this. ↩︎

2. 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. ↩︎