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	LSI	0
I16	LSI	1
I32	LSI	3
I64	LSI	7
I1281	LSI	15
I2561	LSI	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
Bool	SI
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
Any	*	*	Value of an undefined type

Tables with a defined schema can specify some fields as optional using a question mark before the type. This will wrap the field the go-util ucontainer.Option type. When encoding, void fields will not be included in the output, and when decoding, unspecified fields are left void.

Tokens

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

Name	Syntax	Description
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.
Option	?	A question mark.
Comma	,	A comma separator.
LBrace	{	A left curly brace.
RBrace	}	A right curly brace.
LBracket	[	A left square bracket.
RBracket	]	A right square bracket.
Comment	\/\/.*$	A doc comment starting with a double-slash.

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.

Messages, types, and table fields can all have doc comments preceding them, which are used to generate documentation for the protocol. The syntax is the same as Go's (for now). Comments aren't allowed anywhere else.

Here is an example of all that:

// Connect is sent from the client to the server as the first message of an
// authenticated transaction.
M0000 Connect {
	0000 Name String,
	0001 Password String,
}

// UserList is sent from the server to the client in response to a Connect
// message.
M0001 UserList {
	0000 Users []User,
}

// User holds profile information about a single user.
User {
	0000 Name      String,
	0001 Bio       String,
	0002 Followers U32,
}

EBNF Description

Below is an EBNF description of the language.

<file>    -> (<message> | <typedef)*
<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>
        | "{" (<comment>* <field> ",")* [<comment>* <field>] "}"
<message> -> <comment>* <method> <ident> <type>
<typedef> -> <comment>* <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. ↩︎