feat: implement a way to specify offsets in a struct

Author: MrIndeciso

libdestruct/__init__.py

@@ -12,15 +12,17 @@
     pass
 
 from libdestruct.c import c_int, c_long, c_str, c_uint, c_ulong
-from libdestruct.common import ptr
 from libdestruct.common.array import array, array_of
+from libdestruct.common.attributes import offset
 from libdestruct.common.enum import enum, enum_of
+from libdestruct.common.ptr import ptr
 from libdestruct.common.struct import ptr_to, ptr_to_self, struct
 from libdestruct.libdestruct import inflater
 
 __all__ = [
     "array",
     "array_of",
+    "offset",
     "c_int",
     "c_long",
     "c_str",

libdestruct/common/__init__.py

@@ -3,7 +3,3 @@
 # Copyright (c) 2024 Roberto Alessandro Bertolini. All rights reserved.
 # Licensed under the MIT license. See LICENSE file in the project root for details.
 #
-
-from libdestruct.common.ptr import ptr
-
-__all__ = ["ptr"]

libdestruct/common/attribute.py

@@ -0,0 +1,11 @@
+#
+# This file is part of libdestruct (https://github.com/mrindeciso/libdestruct).
+# Copyright (c) 2024 Roberto Alessandro Bertolini. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for details.
+#
+
+from abc import ABC
+
+
+class Attribute(ABC):
+    """Base class for all attributes, which are used to describe fields in a struct."""

libdestruct/common/attributes/__init__.py

@@ -0,0 +1,9 @@
+#
+# This file is part of libdestruct (https://github.com/mrindeciso/libdestruct).
+# Copyright (c) 2024 Roberto Alessandro Bertolini. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for details.
+#
+
+from libdestruct.common.attributes.offset import offset
+
+__all__ = ["offset"]

libdestruct/common/attributes/offset.py

@@ -0,0 +1,14 @@
+#
+# This file is part of libdestruct (https://github.com/mrindeciso/libdestruct).
+# Copyright (c) 2024 Roberto Alessandro Bertolini. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for details.
+#
+
+from __future__ import annotations
+
+from libdestruct.common.attributes.offset_attribute import OffsetAttribute
+
+
+def offset(offset: int) -> OffsetAttribute:
+    """Create an offset field."""
+    return OffsetAttribute(offset)

libdestruct/common/attributes/offset_attribute.py

@@ -0,0 +1,19 @@
+#
+# This file is part of libdestruct (https://github.com/mrindeciso/libdestruct).
+# Copyright (c) 2024 Roberto Alessandro Bertolini. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for details.
+#
+
+from __future__ import annotations
+
+from libdestruct.common.attribute import Attribute
+
+
+class OffsetAttribute(Attribute):
+    """A field that represents an offset in a struct."""
+
+    offset: int
+
+    def __init__(self: OffsetAttribute, offset: int) -> None:
+        """Initialize the offset field."""
+        self.offset = offset

libdestruct/common/struct/struct_impl.py

@@ -8,12 +8,13 @@
 
 from typing import TYPE_CHECKING
 
+from libdestruct.common.attributes.offset_attribute import OffsetAttribute
 from libdestruct.common.field import Field
 from libdestruct.common.obj import obj
 from libdestruct.common.struct import struct
 from libdestruct.common.type_registry import TypeRegistry
 
-if TYPE_CHECKING: # pragma: no cover
+if TYPE_CHECKING:  # pragma: no cover
     from libdestruct.backing.resolver import Resolver
 
 
@@ -54,8 +55,35 @@ def _inflate_struct_attributes(
         for name, annotation in reference_type.__annotations__.items():
             if name in reference_type.__dict__:
                 # Field associated with the annotation
-                field = getattr(reference_type, name)
-                resolved_type = inflater.inflater_for((field, annotation), owner=(self, reference_type._type_impl))
+                attrs = getattr(reference_type, name)
+
+                # If attrs is not a tuple, we need to convert it to a tuple
+                if not isinstance(attrs, tuple):
+                    attrs = (attrs,)
+
+                # Assert that in all attributes, there is only one Field
+                if sum(isinstance(attr, Field) for attr in attrs) > 1:
+                    raise ValueError("Only one Field is allowed per attribute.")
+
+                resolved_type = None
+
+                for attr in attrs:
+                    if isinstance(attr, Field):
+                        resolved_type = inflater.inflater_for(
+                            (attr, annotation),
+                            owner=(self, reference_type._type_impl),
+                        )
+                    elif isinstance(attr, OffsetAttribute):
+                        offset = attr.offset
+                        if offset < current_offset:
+                            raise ValueError("Offset must be greater than the current size.")
+                        current_offset = offset
+                    else:
+                        raise TypeError("Only Field and OffsetAttribute are allowed in attributes.")
+
+                # If we don't have a Field, we need to inflate the type as if we have no attributes
+                if not resolved_type:
+                    resolved_type = inflater.inflater_for(annotation, owner=(self, reference_type._type_impl))
             else:
                 resolved_type = inflater.inflater_for(annotation, owner=(self, reference_type._type_impl))
 
@@ -72,8 +100,32 @@ def compute_own_size(cls: type[struct_impl], reference_type: type) -> None:
         for name, annotation in reference_type.__annotations__.items():
             if name in reference_type.__dict__:
                 # Field associated with the annotation
-                field = getattr(reference_type, name)
-                attribute = cls._inflater.inflater_for((field, annotation))(None)
+                attrs = getattr(reference_type, name)
+
+                # If attrs is not a tuple, we need to convert it to a tuple
+                if not isinstance(attrs, tuple):
+                    attrs = (attrs,)
+
+                # Assert that in all attributes, there is only one Field
+                if sum(isinstance(attr, Field) for attr in attrs) > 1:
+                    raise ValueError("Only one Field is allowed per attribute.")
+
+                attribute = None
+
+                for attr in attrs:
+                    if isinstance(attr, Field):
+                        attribute = cls._inflater.inflater_for((attr, annotation))(None)
+                    elif isinstance(attr, OffsetAttribute):
+                        offset = attr.offset
+                        if offset < size:
+                            raise ValueError("Offset must be greater than the current size.")
+                        size = offset
+                    else:
+                        raise TypeError("Only Field and OffsetAttribute are allowed in attributes.")
+
+                # If we don't have a Field, we need to inflate the attribute as if we have no attributes
+                if not attribute:
+                    attribute = cls._inflater.inflater_for(annotation)
             elif isinstance(annotation, Field):
                 attribute = cls._inflater.inflater_for((annotation, annotation.base_type))(None)
             else:
@@ -106,10 +158,7 @@ def freeze(self: struct_impl) -> None:
     def to_str(self: struct_impl, indent: int = 0) -> str:
         """Return a string representation of the struct."""
         members = ",\n".join(
-            [
-                f"{' ' * (indent + 4)}{name}: {member.to_str(indent + 4)}"
-                for name, member in self._members.items()
-            ],
+            [f"{' ' * (indent + 4)}{name}: {member.to_str(indent + 4)}" for name, member in self._members.items()],
         )
         return f"""{self.name} {{
 {members}

libdestruct/common/utils.py

@@ -16,18 +16,19 @@
     from libdestruct.common.obj import obj
 
 
+def is_field_bound_method(item: obj) -> bool:
+    """Check if the provided item is the bound method of a Field object."""
+    return isinstance(item, MethodType) and isinstance(item.__self__, Field)
+
+
 def size_of(item_or_inflater: obj | callable[[Resolver], obj]) -> int:
     """Return the size of an object, from an obj or it's inflater."""
     if hasattr(item_or_inflater, "size"):
         return item_or_inflater.size
 
     # Check if item is the bound method of a Field
-    if not isinstance(item_or_inflater, MethodType):
-        raise TypeError("Provided inflater is not the bound method of a Field object")
-
-    field_object = item_or_inflater.__self__
-
-    if not isinstance(field_object, Field):
-        raise TypeError("Provided inflater is not the bound method of a Field object")
+    if is_field_bound_method(item_or_inflater):
+        field_object = item_or_inflater.__self__
+        return field_object.get_size()
 
-    return field_object.get_size()
+    raise ValueError(f"Cannot determine the size of {item_or_inflater}")