Codec layout tree

The layout tree: one line of text for any layout, a declaration's or the client's, which the facts check compares node by node. How it's used is on Codec and Codec facts check.

The notation

Nodes

A tree is a sequence of nodes in wire order, separated by one space. The codec reads and writes the text with WireTree.Parse and WireTree.Format, as WireNodes, and the generator writes each declaration's as WireLayout.TreeText.

Text	Node	Empty path
32	A field of 32 bits, 1 to 64. Selectors and counts are fields too	32
w	A wide string: a 1-bit form flag, a 7 or 15-bit length, then UTF-16 units	1 7
n	A narrow string: the same header, then bytes	1 7
t	A terminated wide string: a 16-bit count including the terminator, then the units	16 16 written, 16 read
b32, b32a	A blob with a 32-bit length; a when it starts on a byte boundary	The alignment bits, then 32
[3:...]	An array whose count is the field at index 3 of the same sequence; the element's sequence follows the colon	Nothing
{3:0=(...),2=(...)}	A union whose selector is the field at index 3, with one arm per selector value, ascending, in decimal	Arm 0's empty path
?	A layout that contains itself, not expanded	Stops

An index counts nodes, not bits, in the sequence the array or union sits in, and the node it names must be a field that comes earlier. An empty message's tree is the empty string.

What dissolves

Only arrays and unions nest, because only they hold a sequence of their own. Everything else dissolves into the sequence that holds it:

• a nested struct's or a base type's nodes sit inline;
• a fixed array repeats its element inline;
• a vector is one field per component;
• a pad is fields of at most 64 bits.

Examples

Layout	Tree
0x009A, four fixed fields	32 16 32 1
Three strings, one of each kind	w n t
A test layout with a union inside each array element	14 64 w 5 [3:4 16 16 {0:0=(1),2=(18)}] 16
A byte-aligned envelope	5 b32a
A NetworkGuid, dissolved into its holder	32 16 16 8 8 8 8 8 8 8 8

Naming a place in a tree

A disagreement is named by its opcode and side, then a path to its node:

Step	Means
[4]	Node 4 of the current sequence
.element	Into an array's element
.arm 0x02	Into a union's arm for selector 2

So in the test layout above, [4].element[3].arm 0x02[0] is the first node of arm 2 of the union inside the fifth node's element.

Known edges

• A layout that contains itself is written as ? and never expanded, so a comparison stops there.

Where the code lives

Piece	Path
The tree, its nodes and its text form	Source/NexusTomorrow.Network.Codec/WireTree.cs, Source/NexusTomorrow.Network.Codec/WireNode.cs
A declaration's layout	Source/NexusTomorrow.Network.Codec/WireLayout.cs
The generator that writes each tree	Source/NexusTomorrow.Network.Codec.Generator/