Skip to content

[DEV] New feature: inline syntax#59

Merged
MatrixEditor merged 14 commits into
masterfrom
feat/inline-syntax
Feb 8, 2026
Merged

[DEV] New feature: inline syntax#59
MatrixEditor merged 14 commits into
masterfrom
feat/inline-syntax

Conversation

@MatrixEditor
Copy link
Copy Markdown
Owner

@MatrixEditor MatrixEditor commented Feb 6, 2026

this pull request tracks changes related to the v2.8.1 release

Changes made here introduce a new inline syntax that can be used to unpack structs (not annotated struct classes) from bytes or a stream:

stream = BytesIO(b"\xff\xff@\xe2\x01\x00")

# To affect the endianess, either use 
O_DEFAULT_ENDIAN.value = LittleEndian
# or creating a constant field that represents the typed struct
uint32le = LittleEndian + uint32

# to read/unpack values from a stream/buffer, just use the left shift operator
value1: int = uint32le << stream 
value2: int = uint16 << stream 
value3: str = String(10) << stream 

Added

  • New inline syntax using the << operator to automatically unpack structs from data
  • All default struct types now implement from_bytes, from_file and to_bytes for direct packing or unpacking
  • Add PackMixin and UnpackMixin to automatically implement the methods mentioned above for struct types

Changes

  • pack, unpack and sizeof were moved into their own module (no changed visibe when importing from caterpillar.models)

Removed

  • Drop support for 'x' format character in PyStructFormattedField

Fixes

  • Pre-computed conditions in the Field class incorrectly evaluated to true or false unconditionally (in case of a context-lambda). This issue has now been fixed in all places.
  • Fix some missing or wrong typing annotations
  • Fix unpacking with dynamic offsets #57: allow dynamic offsets to be used again

tsheinen and others added 4 commits February 4, 2026 20:39
`_ContextLambda` is `ExprMixin` which overwrites `__eq__`. The
`__contains__` function for tuples delegates to `__eq__` and this
interaction means that `_has_offset` and `_keep_pos` will be
unconditionally false and true when using a dynamic offset.
---

Move all parsing and building related functions (pack*, unpack*, sizeof) into a separate file for easy import handling.

Refs: #57
Merge pull request #57 from tsheinen/fix-dynamic-offset-unpack
- Merge pull request #58 from MatrixEditor/fix/dynamic-offsets
- Move all parsing and building related functions (pack*, unpack*, sizeof) into a separate file for easy import handling.
- amount, offset and condition now apply comparison in the correct order
- Add correct typing to Chain struct
- Add pack and unpack wrappers to all available common structs
- Add inline syntax support to Field class
- update test_py_offset tests
Removes support for the padding 'x' format character within the PyStructFormattedField class.

- Remove '_is_padding' from  PyStructFormattedField
- Add inline syntax to tutorial
- Add inline syntax example
- Update documentation for PackMixin and UnpackMixin
@MatrixEditor MatrixEditor merged commit 5dd9e5f into master Feb 8, 2026
@MatrixEditor MatrixEditor deleted the feat/inline-syntax branch February 8, 2026 07:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants