[DEV] (2.5.0 rc) Bitfield revamp

[MatrixEditor]

New Concept

Each Bitfield instance maintains a sequence of bitfield groups, where each group contains a collection of sized fields. A bitfield group may consist of either multiple entries (i.e., any types that can be converted to an integral type) or a single _StructLike object. For example, consider the following bitfield definition:

  @bitfield
  class Format:
      a1 : 1
      a2 : 2
      _  : 0
      b1 : char
      c1 : uint32

This Bitfield definition will generate three distinct bitfield groups (labeled here as groups a, b, and c). By default, bitfields use 8-bit alignment, leading to the following layout:

      Group      Pos       Bits
      a          0x00      8
      b          0x01      8
      c          0x02      32

Internally, only the first group requires special bit-level parsing. The remaining groups (b and c) are treated as standard structures since they span full bytes or words without sub-byte alignment. This dynamic grouping mechanism allows leveraging full struct-like class definitions within bitfields.

Example Code:

@bitfield
class Format:
    # bitwise fields can be defined as before
    a1: 1
    a2: 2
    # the underlying integer size will be adjusted
    # automatically. Default alignment is 8bits.
    a3: 12

    # same as before, adds padding until the end based
    # on the current alignment (8bits -> aligned to 16bits,
    # since 12+2+1 is already bigger than 8)
    _: 0 

    # The new concept allows us to specify arbitrary structs
    # or fields.
    b1: Bytes(10)
    c1: CString(...)

    # The updated concept introduces a new extended syntax 
    # based on tuples
    d1: 10
    # ends the current group (implied) and sets the alignment
    # to 24bits for all following groups.
    _: (0, EndGroup, SetAlignment(24))

    # 5bits of 32, because the current alignment will be replaced
    # with the size of the current struct (here: uint32)
    e1: 5 - uint32 | B_OVERWRITE_ALIGNMENT

    # Actions are supported too

Additional changes introduced:

caterpillar.abc

• _ActionLike was removed and split into two separate protocols: _SupportsActionUnpack and _SupportsActionPack
• Int and UInt field structs now implement a reasonable __repr__ format