Ref System

Ref

class pystructs.ref.Ref(path: str)

Bases: object

Reference to another field’s value.

Ref allows fields to reference other fields’ current values. This is used for variable-length fields and conditional logic.

Path formats:

• ‘field_name’: Same level field

• ‘nested.field’: Nested struct field (dot notation)

• ‘../field_name’: Parent struct field

• ‘/header/size’: Absolute path from root

Examples:

>>> payload = Bytes(size=Ref('payload_size'))
>>> data = Bytes(size=Ref('header.data_size'))
>>> item_data = Bytes(size=Ref('../item_size'))

resolve(instance: Struct) → Any

Resolve the reference to get the actual value.

Args:

instance: The struct instance to resolve from

Returns:

The value of the referenced field

RefComparison

class pystructs.ref.RefComparison(ref: Ref, op: str, value: Any)

Bases: object

Result of comparing a Ref with a value.

Used in Conditional fields to determine if a field should exist.

Examples:

>>> extra = Conditional(UInt32(), when=Ref('version') >= 2)

evaluate(instance: Struct) → bool

Evaluate the comparison.

Args:

instance: The struct instance to evaluate against

Returns:

True if the comparison is satisfied

RefLogical

class pystructs.ref.RefLogical(left: RefComparison | RefLogical, op: str, right: RefComparison | RefLogical)

Bases: object

Logical combination of RefComparison objects.

Examples:

>>> cond = (Ref('version') >= 2) & (Ref('flags') != 0)
>>> field = Conditional(UInt32(), when=cond)

evaluate(instance: Struct) → bool

Evaluate the logical expression.

Args:

instance: The struct instance to evaluate against

Returns:

True if the logical expression is satisfied