[plum] Tutorial: Arbitrary Nesting

All plum types conform to a plug and play interface. This facilitates using any plum type in places where plum types embed other plum types such as (but not limited to) the Array and Structure types. The plug and play architecture facilitates practically unlimited nesting levels and combinations. The following example demonstrates four levels of nesting. Notice in the Access column of the dump that the indentation increases for every level to help visualize the nesting.

>>> from plum import unpack_and_dump
>>> from plum.array import Array
>>> from plum.int.little import UInt8
>>> from plum.structure import Member, Structure
>>>
>>> class InnerArray(Array, dims=(3,), item_cls=UInt8):
...     pass
...
>>> class MyStruct(Structure):
...     count: int = Member(cls=UInt8)
...     array: list = Member(cls=InnerArray)
...
>>> class OuterArray(Array, dims=(2,), item_cls=MyStruct):
...     pass
>>>
>>> x, dump = unpack_and_dump(OuterArray, bytes(range(8)))
>>> print(dump)
+--------+----------------+-------+-------+------------+
| Offset | Access         | Value | Bytes | Type       |
+--------+----------------+-------+-------+------------+
|        |                |       |       | OuterArray |
|        | [0]            |       |       | MyStruct   |
| 0      |   [0] (.count) | 0     | 00    | UInt8      |
|        |   [1] (.array) |       |       | InnerArray |
| 1      |     [0]        | 1     | 01    | UInt8      |
| 2      |     [1]        | 2     | 02    | UInt8      |
| 3      |     [2]        | 3     | 03    | UInt8      |
|        | [1]            |       |       | MyStruct   |
| 4      |   [0] (.count) | 4     | 04    | UInt8      |
|        |   [1] (.array) |       |       | InnerArray |
| 5      |     [0]        | 5     | 05    | UInt8      |
| 6      |     [1]        | 6     | 06    | UInt8      |
| 7      |     [2]        | 7     | 07    | UInt8      |
+--------+----------------+-------+-------+------------+
>>>
>>> x[1].array[1]
6